@charcuterie/ui 3.30.0 → 3.31.0

package/src/Tabs/Tabs.mdx

@@ -19,6 +19,76 @@ It did not come out ugly. The composition is two hooks and one decision.
 
 <Controls />
 
+## Two bars, and the question is not "how does it look"
+
+**Does this section have an address?**
+
+| | Panel tab | Routed tab |
+| --- | --- | --- |
+| The item carries | `content` | `href` |
+| Each trigger is | `<button role="tab">` | `<a href>` |
+| The bar is | `role="tablist"` | `<nav aria-label>` |
+| The section is drawn by | this component | the router, through your `<Outlet />` |
+| Which one is on | `Tabs` owns it | the address does, via `activeHref` |
+| Reload, Back, new tab | start over | land on the same section |
+
+```tsx
+// A disclosure inside one screen. Nothing outside knows about it.
+<Tabs label="Bay 3" tabs={[{ key: "log", label: "Log", content: <Log /> }]} />
+
+// A section that has an address.
+<Tabs
+  activeHref={pathname}
+  label="Bay 3 sections"
+  tabs={[{ href: "/projects/1/tasks", label: "Tasks" }]}
+/>
+<Outlet />
+```
+
+`activeHref` is the discriminant, and it is required in the routed mode. `tabs` alone
+could not carry the split: TypeScript does not narrow a union by the shape of an array's
+elements, so a bar mixing the two would type-check and then render half a navigation.
+
+<Canvas of={TabsStories.Routed} />
+
+### The paint is shared, and that is the point
+
+Docket had one of each on adjacent screens wearing **different paint** — a filled pill on
+the project bar, this underline on Settings — because a routed section switcher had to be
+built out of `Nav`, and `Nav`'s current item is a pill. `toTabTriggerClass` is now the one
+definition both triggers read, and `Tabs.test.tsx` compares the two computed styles
+property by property, because a screenshot cannot tell them apart on purpose.
+[Decision](../../../docs/decisions/2026-08-31-a-routed-tab-is-a-tab-with-an-href.md).
+
+<Canvas of={TabsStories.RoutedAllVariants} />
+
+### The routed bar is not a `tablist`
+
+`role="tab"` on an anchor **overrides** the link role. A screen reader announces a
+disclosure, the reader waits for a panel to appear beside it, and instead the address
+changes and the page under them is replaced. `aria-controls` has nothing to point at
+either — the section's content comes from the router, somewhere this component cannot see.
+
+So the routed bar is what it actually is: a named `<nav>` of real links with
+`aria-current="page"` on the one you are on. Which one that is comes from `Nav`'s
+`resolveActiveKey`, imported rather than restated — whole-segment matching, deepest match
+wins, the root is exact, an external item is never current, and the query string is not
+part of the answer.
+
+<Canvas of={TabsStories.RoutedAllStates} />
+
+A **disabled** routed tab is not a link at all. `<a>` has no `disabled` attribute, so the
+tempting version — a real `href` plus `aria-disabled` — greys out and still navigates on
+Enter and on a middle click; it renders as a `<span aria-disabled>` instead.
+
+### This is sub-navigation. `Nav` is still the app's destinations
+
+The header row, the side rail and the Narrow View's menu are `Nav` + `useNavLayout`, and
+that has not moved.
+[Decision](../../../docs/decisions/2026-08-27-nav-is-the-one-navigation-component-and-navbar-is-deprecated.md).
+A routed `Tabs` divides **one screen** into sections, so it renders no rail, no fold and
+no menu — a bar inside a screen has nowhere to fold to.
+
 ## The composition
 
 ```ts

package/src/Tabs/Tabs.stories.tsx

@@ -8,8 +8,8 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { ProgressBar } from "../ProgressBar/ProgressBar.tsx"
-import type { TabItem } from "./Tabs.tsx"
 import { Tabs } from "./Tabs.tsx"
+import type { TabItem, TabLinkItem } from "./tabItems.ts"
 
 const BAY_TABS: TabItem[] = [
   {
@@ -185,3 +185,135 @@ export const Manual: Story = {
     tabs: BAY_TABS,
   },
 }
+
+const BAY_ROUTE_TABS: TabLinkItem[] = [
+  {
+    href: "/bays/3",
+    label: "Overview",
+  },
+  {
+    href: "/bays/3/titles",
+    label: "Titles",
+  },
+  {
+    href: "/bays/3/tracks",
+    label: "Tracks",
+  },
+  {
+    href: "/bays/3/log",
+    label: "Log",
+  },
+]
+
+/**
+ * A tab that is a **place**. Every trigger is a real `<a href>`, so
+ * middle-click, ctrl-click, "open in a new tab" and "copy link
+ * address" all work — and reloading the page comes back to the same
+ * section, which is the whole reason to route one.
+ *
+ * The bar is a named `<nav>`, not a `tablist`: `role="tab"` on an
+ * anchor overrides the link role, so a screen reader would announce
+ * a disclosure and then the address would change instead. The
+ * *paint* is shared with the panel bar above through
+ * `toTabTriggerClass`, which is what this mode was added to fix.
+ *
+ * The sections themselves are rendered by the router — an
+ * `<Outlet />` under the bar — so this component draws no panels
+ * here at all.
+ */
+export const Routed: Story = {
+  args: { label: "Bay 3", tabs: BAY_TABS },
+  render: () => (
+    <Tabs
+      activeHref="/bays/3/log"
+      label="Bay 3 sections"
+      tabs={BAY_ROUTE_TABS}
+    />
+  ),
+}
+
+/**
+ * Routed and panel bars side by side — the comparison this mode
+ * exists for. They are one shape doing one job, and before `href`
+ * existed the routed one had to be built out of `Nav`, whose current
+ * item is a filled pill.
+ *
+ * The third cell is the matching rule, which is `Nav`'s
+ * `resolveActiveKey` rather than a second implementation: the
+ * deepest matching path wins, so `/tasks` stands down while the
+ * reader is on `/tasks` *and* nothing lights up twice.
+ */
+export const RoutedAllVariants: Story = {
+  args: { label: "Bay 3", tabs: BAY_TABS },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="routed · horizontal">
+        <Tabs
+          activeHref="/bays/3/titles"
+          label="Routed horizontal"
+          tabs={BAY_ROUTE_TABS}
+        />
+      </StoryCell>
+
+      <StoryCell label="panel · horizontal">
+        <Tabs label="Panel horizontal" tabs={BAY_TABS} />
+      </StoryCell>
+
+      <StoryCell label="routed · vertical">
+        <Tabs
+          activeHref="/bays/3/tracks"
+          label="Routed vertical"
+          orientation="vertical"
+          tabs={BAY_ROUTE_TABS}
+        />
+      </StoryCell>
+
+      <StoryCell label="routed · a child route is still the section">
+        <Tabs
+          activeHref="/bays/3/titles/4"
+          label="Routed on a child route"
+          tabs={BAY_ROUTE_TABS}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+const ROUTED_STATE_TABS: TabLinkItem[] = [
+  ...BAY_ROUTE_TABS,
+  {
+    href: "/bays/3/reports",
+    isDisabled: true,
+    label: "Reports",
+  },
+  {
+    href: "https://mkdocs.octen.dev/workspace/docket/",
+    isExternal: true,
+    label: "Handbook",
+  },
+]
+
+/**
+ * A disabled routed tab is **not a link at all** — a `<span>` with
+ * `aria-disabled`, because an anchor has no `disabled` attribute and
+ * `aria-disabled` alone still navigates on Enter. That is the
+ * version of this that looks right and is not.
+ *
+ * An external tab is a plain anchor with `target="_blank"` and
+ * `rel="noopener noreferrer"`, and it is **never current** — no
+ * address inside this app can be a place outside it.
+ *
+ * `activeHref` here is a screen the bar does not contain, which is
+ * the third state: **nothing** is current. A bar that guessed the
+ * closest tab instead would be lying on every modal route.
+ */
+export const RoutedAllStates: Story = {
+  args: { label: "Bay 3", tabs: BAY_TABS },
+  render: () => (
+    <Tabs
+      activeHref="/settings"
+      label="Bay 3 states"
+      tabs={ROUTED_STATE_TABS}
+    />
+  ),
+}

package/src/Tabs/Tabs.test.tsx

@@ -13,6 +13,9 @@ const {
   Default,
   Manual,
   Responsive,
+  Routed,
+  RoutedAllStates,
+  RoutedAllVariants,
 } = composeStories(stories)
 
 test("selecting a tab wires the panel back to it", async () => {
@@ -281,3 +284,169 @@ test("automatic activation selects as focus moves, and wraps", async () => {
     expect(tabs[0]).toHaveAttribute("aria-selected", "true")
   })
 })
+
+/**
+ * The routed bar is a **navigation**, not a tablist, and this is the
+ * assertion that says so. `role="tab"` on an anchor overrides the
+ * link role: a screen reader announces a disclosure, the reader
+ * waits for a panel, and the address changes under them instead.
+ *
+ * A screenshot cannot tell the two apart — the paint is deliberately
+ * identical — so nothing but this catches a regression to it.
+ */
+test("a routed tab is a link in a nav, never a tab in a tablist", async () => {
+  const { canvas, canvasElement } = await mountStory(Routed)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Bay 3 sections",
+    role: "navigation",
+  })
+
+  await expect(
+    canvas.queryByRole("tablist"),
+  ).not.toBeInTheDocument()
+
+  await expect(
+    canvas.queryByRole("tab"),
+  ).not.toBeInTheDocument()
+
+  // No panels either: the sections are the router's, rendered
+  // through an `<Outlet />` this component cannot see.
+  await expect(
+    canvas.queryByRole("tabpanel"),
+  ).not.toBeInTheDocument()
+
+  const links = Array.from(
+    nav.querySelectorAll<HTMLAnchorElement>("a[href]"),
+  )
+
+  await expect(links).toHaveLength(4)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("exactly one routed tab is current, and it is the deepest match", async () => {
+  const { canvas } = await mountStory(RoutedAllVariants)
+
+  // `/tasks` and the project root both match `/…/tasks`, and only
+  // the deeper one may light up — a bar with two current items has
+  // stopped saying anything. The rule is `resolveActiveKey`, shared
+  // with `Nav` rather than reimplemented here.
+  const nav = expectAgentDrivable(canvas, {
+    name: "Routed horizontal",
+    role: "navigation",
+  })
+
+  const current = nav.querySelectorAll(
+    '[aria-current="page"]',
+  )
+
+  await expect(current).toHaveLength(1)
+
+  await expect(current[0]).toHaveTextContent("Titles")
+
+  // A child route is still inside the section it belongs to.
+  const child = expectAgentDrivable(canvas, {
+    name: "Routed on a child route",
+    role: "navigation",
+  })
+
+  const childCurrent = child.querySelectorAll(
+    '[aria-current="page"]',
+  )
+
+  await expect(childCurrent).toHaveLength(1)
+
+  await expect(childCurrent[0]).toHaveTextContent("Titles")
+})
+
+/**
+ * A disabled anchor is the defect this guards. `<a>` has no
+ * `disabled` attribute, so the tempting version — a real `href` plus
+ * `aria-disabled` — greys out and still navigates on Enter and on a
+ * middle click.
+ */
+test("a disabled routed tab has no href, and an external one is never current", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(RoutedAllStates)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Bay 3 states",
+    role: "navigation",
+  })
+
+  const reports = canvas.getByText("Reports")
+
+  await expect(reports).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+
+  await expect(reports.closest("a")).toBeNull()
+
+  const handbook = expectAgentDrivable(canvas, {
+    name: /Handbook/u,
+    role: "link",
+  })
+
+  await expect(handbook).toHaveAttribute("target", "_blank")
+
+  await expect(handbook).toHaveAttribute(
+    "rel",
+    "noopener noreferrer",
+  )
+
+  // Never current: no address inside this app can be a place
+  // outside it, and a plain string compare would match one.
+  await expect(handbook).not.toHaveAttribute("aria-current")
+
+  // `activeHref` points at `/overview`, which no tab owns — so the
+  // bar honestly marks nothing rather than guessing the closest.
+  await expect(
+    nav.querySelectorAll('[aria-current="page"]'),
+  ).toHaveLength(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The reason both modes live in one component: a routed tab and a
+ * panel tab are one shape doing one job, and Docket shipped them on
+ * adjacent screens wearing different paint because the routed one
+ * had to be built out of `Nav`.
+ */
+test("a routed tab and a panel tab are painted identically", async () => {
+  const { canvas } = await mountStory(RoutedAllVariants)
+
+  const routedCurrent = expectAgentDrivable(canvas, {
+    name: "Routed horizontal",
+    role: "navigation",
+  }).querySelector('[aria-current="page"]')
+
+  const panelSelected = expectAgentDrivable(canvas, {
+    name: "Panel horizontal",
+    role: "tablist",
+  }).querySelector('[aria-selected="true"]')
+
+  const routedStyle = globalThis.getComputedStyle(
+    routedCurrent as HTMLElement,
+  )
+
+  const panelStyle = globalThis.getComputedStyle(
+    panelSelected as HTMLElement,
+  )
+
+  for (const property of [
+    "borderBottomColor",
+    "borderBottomWidth",
+    "color",
+    "fontSize",
+    "fontWeight",
+    "paddingInlineStart",
+    "paddingBlockStart",
+  ] as const) {
+    await expect(routedStyle[property]).toBe(
+      panelStyle[property],
+    )
+  }
+})