@charcuterie/ui 3.30.0 → 3.32.0

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],
+    )
+  }
+})