Merge component pages across frameworks with per-framework tabs

[nathanacurtis]

Subissue of #574. Wave 1.

Problem

Emitted stories are titled by emitter — React/Button, WebComponents/Button — so one component appears twice in the navigation and a reader has to know which tree they are in. The system has one Button. Storybook should show one Button, with the frameworks as views of it.

Resolved: the host side works

A spike on specs-testing/workspaces/de-library (Storybook 8.6, branch spike/storybook-framework-tabs, uncommitted) has the whole interaction working. Everything below is verified in a browser, and all of it is host configuration — two files, .storybook/manager.tsx and .storybook/preview.tsx, plus one staticDirs entry in main.ts.

Capability	Mechanism
Per-framework canvas tabs — React · Web Components · Specs	addons.add(id, { type: types.TAB, route, match, render }). route/match receive storyId, and useStorybookState() gives it live inside render, so a globally registered tab resolves the selected component
Web Components view	Derives the sibling story id by prefix swap and renders iframe.html?id=<sibling>. Under a docs entry it shows the whole Web Components docs page — its own Controls table, its own stories
Specs view	Fetches the workspace's specs/<dir>/<file>.yaml over a static dir, rendered with SyntaxHighlighter and TabsState from storybook/internal/components, with api / variants / examples as sub-tabs
Component is the sidebar link	docs: { docsMode: true }, with defaultName: 'Overview' naming the parent's own page where a component has subcomponents
One Components section	api.experimental_setFilter hides the Web Components tree from the sidebar while leaving it in the index for the tab
Section order	storySort.order: ['Overview', 'Foundations', 'Components', 'Analysis']
Per-story controls on the docs page	docs.canvas with withToolbar: false and an additionalActions entry that recovers the story id from the Canvas block's anchor and opens it full screen

Remaining work

One transform change, in react-from-specs: emit title: 'Components/<Name>' instead of title: 'React/<Name>', subcomponent segments included. Nothing else in either transform changes.

Everything else is host configuration, so it belongs to #607 (document it) and #610 (template it) rather than here. Close this issue when the title change ships and #607 carries the configuration above.

Findings that constrain the design

Four things the spike settled, each of which contradicts a reasonable first guess:

1. Identical titles across the two trees do not work. Matching titles produce matching story ids, and Storybook rejects duplicates. The Web Components tree keeps its own titles; the tab maps between the two id spaces by prefix swap. The invariant that actually matters is slug and story-name parity between trees, which already holds — Default, AlertWithActions and the rest exist in both. That parity is incidental today and needs a test if the tabs ship, or a divergence in one emitter silently drops the reader onto a missing story.
2. tags: ['!dev'] does not remove stories from the sidebar here. The tag lands in the index and the section renders anyway. experimental_setFilter is what works, which means hiding the Web Components tree costs the emitters nothing.
3. The canvas tab label cannot be a story parameter. Set as parameters.previewTabs, the manager only learns the rename once the preview reports that story's parameters, so the tab reads "Canvas" on every navigation and corrects itself a moment later. addons.setConfig({ previewTabs: … }) in the manager is known before any story loads. Since the sidebar only ever shows the React tree, the label is a scaffold decision keyed on which trees a workspace has — not something an emitter can know.
4. A component with subcomponents is a folder, not a link. Storybook has no node that is both leaf and parent, so DE Alert expands while DE Avatar opens. Accepted as-is: subcomponents stay in the navigation, and defaultName: 'Overview' names the parent's own page.

Compatibility risk

types.TAB is marked @unstable in Storybook 8's own types — "might be removed in the future". The host also imports from storybook/internal/manager-api, storybook/internal/components, and storybook/internal/theming. It is what the built-in Docs tab uses, so none of this is obscure, but a scaffold that writes this code couples customers to internal entrypoints of a tool we do not control. Recorded in #574's ADR A section as a compatibility question rather than left here.

Acceptance criteria

• react-from-specs emits Components/<Name> titles.
• One navigation entry per component, with the React view as the default.
• A Web Components view reachable without leaving the component.
• A Specs view showing api, variants, and examples formatted, not raw.
• Document the complete reference Storybook host #607's documented host includes every row of the capability table above.
• Story-name parity between the two emitted trees is covered by a test.

Case data

• Workspace: de-library
• Territory: cli
• Size: m

[nathanacurtis]

Spike result — the tab approach works

Run against specs-testing/workspaces/de-library on branch spike/storybook-framework-tabs, Storybook 8.6.18, react-vite. Working, verified in a browser: Canvas | Web Components | Specs tabs on a single component, with the Web Components tab rendering the real Lit element and the Specs tab showing formatted YAML with api / variants / examples sub-tabs.

Two files changed, both host configuration, no generator change:

• .storybook/manager.tsx (new) — registers two types.TAB addons.
• .storybook/main.ts — one staticDirs entry serving the workspace specs/ directory at /specs.

Answers to the two questions this issue asked

Can a tab resolve which component is selected? Yes. route and match both receive RenderData, which carries storyId, viewMode, and refId; inside render, useStorybookState() from storybook/internal/manager-api gives the live storyId. Tabs are still registered globally — they exist for every story — but they can resolve and filter on the selection, which is what the framework switch needed. No fallback to a toolbar global is required.

Exact signature on Storybook 8. Confirmed against the installed @storybook/core types:

addons.add(id, {
  type: types.TAB,
  title: 'Web Components',
  route: ({ storyId, refId }) => refId ? `/webcomponents/${refId}_${storyId}` : `/webcomponents/${storyId}`,
  match: ({ viewMode, storyId }) => viewMode === 'webcomponents' && isComponentStory(storyId),
  render: ({ active }) => (active ? <WebComponentsTab /> : null),
})

The first path segment returned by route becomes viewMode, which is what match tests. Selecting a tab produces ?path=/story/react-de-alert--alert-with-actions&tab=<addon-id>, so a tab selection is linkable.

How each tab is implemented

• Web Components — derives the sibling story id from the current one and renders iframe.html?id=<sibling>&viewMode=story. Both trees are already in the same index, so no second server and no duplicate build. Verified that de-alert renders inside with its full light-DOM children.
• Specs — fetches /specs/<dir>/<file>.yaml and renders it; the three files are buttons inside the one tab's own render, since sub-tabs are not a Storybook concept. Confirmed live for api and variants.

The finding that matters most

Story export names are identical across the two emitted trees. Default, AlertWithActions, and the rest appear in both react/src/.../stories.tsx and webcomponents/src/.../stories.ts, so the sibling id is a pure prefix swap — react-de-alert--alert-with-actions → web-components-de-alert--alert-with-actions — and switching frameworks keeps the reader on the same story, not just the same component.

That is a contract the transforms currently satisfy incidentally. If tabs ship, it becomes a real invariant and needs a test, or a divergence in one emitter silently drops the reader onto a missing story.

What is still open, and is not a tab problem

Three things the spike does not solve, all of them work rather than risk:

1. The sidebar still has React and Web Components roots. Merging to one Components/<Name> entry is a change to the emitted title in both transforms, not a host change. Hiding the Web Components tree from the sidebar while keeping its stories in the index needs a decision — a tags exclusion in the sidebar filter is the likely mechanism.
2. types.TAB is marked @unstable in Storybook 8's own types, with a comment saying it "might be removed in the future". It is what the built-in Docs tab uses, so it is not obscure, but it is an explicit compatibility risk and belongs in ADR A's tool-version compatibility section rather than being discovered later.
3. The addons panel is not visible while a custom tab is active — Controls and Actions are Canvas-tab features. That is correct behaviour, not a defect, but it means the Web Components tab shows a rendered component with no controls unless we mount our own.

Reproducing

Branch spike/storybook-framework-tabs in specs-testing, left uncommitted per the repo's commit convention. bash scripts/storybook-up.sh de-library, then open a React story and click through the tabs.

[nathanacurtis]

The canvas tab label must be per-story, not global

Follow-up to the spike. The built-in canvas tab is renameable with the previewTabs parameter:

parameters: { previewTabs: { canvas: { title: 'React' } } }

Set in preview.tsx this is global, and it labels whatever the canvas happens to be. A workspace that runs only specs webcomponents would show a Lit story under a tab reading "React". The label would be asserting something no one checked.

So the shipped form is per-story: each transform emits previewTabs into its own story meta — 'React' from react-from-specs, 'Web Components' from webcomponents-from-specs. The label then comes from the tree that produced the story, and a single-framework workspace is correct with no knowledge of what else was or was not generated.

This also settles a smaller question the spike left open: the Web Components tab should only register when web-components stories are present in the index, for the same reason.

Applied globally on the spike branch for now, with a comment marking it as the wrong shape.