@charcuterie/ui 3.21.0 → 3.22.0

package/src/NavBar/NavBar.stories.tsx

@@ -0,0 +1,350 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import {
+  controlSizeArgType,
+  placementArgType,
+} from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Header } from "../Header/Header.tsx"
+import { MenuIcon } from "../icons.storyHelpers.tsx"
+import { Main } from "../Main/Main.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import { Shell } from "../Shell/Shell.tsx"
+import { PageContent } from "../shell.storyHelpers.tsx"
+import type { NavBarItem } from "./NavBar.tsx"
+import { NavBar } from "./NavBar.tsx"
+
+/**
+ * A stand-in for react-router's `<Link>`, and it does the one thing
+ * the plain `SoftRouterLink` in the other link boards does not:
+ * `preventDefault()`.
+ *
+ * That is not a test convenience, it is what a router does — it
+ * intercepts the plain left click and pushes history instead of
+ * letting the browser leave the page. Without it these boards
+ * genuinely navigate: the first run of `NavBar.test.tsx` clicked
+ * "Phases" and took the whole vitest iframe to `/phases`, which is
+ * the most direct proof available that these rows are real anchors
+ * and not `<button>`s.
+ *
+ * The `href` is untouched, so middle-click and ctrl-click still go
+ * to the platform — exactly as they do in an app.
+ */
+const SoftRouterLink = ({
+  href,
+  onClick,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a
+    {...linkProps}
+    data-router="soft"
+    href={href}
+    onClick={(event) => {
+      // The caller's handler first, then the interception — which
+      // is react-router's own order in `Link`, and it is what lets
+      // `NavBar` see a click that has not been cancelled yet.
+      onClick?.(event)
+
+      event.preventDefault()
+    }}
+  />
+)
+
+/**
+ * Docket's nine, in the product's own order — the nav that outgrew
+ * a single line and is the reason this component exists. The order
+ * is the pipeline work moves along, which is exactly why it may not
+ * be split across a bar and a menu.
+ */
+const DESTINATIONS: NavBarItem[] = [
+  { href: "/triage", label: "Triage" },
+  { href: "/backlog", label: "Backlog" },
+  { href: "/phases", label: "Phases" },
+  { href: "/lanes", label: "Lanes" },
+  { href: "/board", label: "Board" },
+  { href: "/archives", label: "Archives" },
+  { href: "/tonight", label: "Tonight" },
+  { href: "/chats", label: "Chats" },
+  { href: "/settings", label: "Settings" },
+]
+
+const FEW_DESTINATIONS = DESTINATIONS.slice(0, 3)
+
+/**
+ * A fixed-width box, because the whole component is a measurement.
+ * A `layout: "centered"` story would size itself to its contents
+ * and never fold at all.
+ */
+const Frame = ({
+  children,
+  inlineSize,
+}: {
+  children: ReactNode
+  inlineSize: string
+}): ReactNode => (
+  <div
+    className="flex rounded-md border border-border-subtle bg-surface-raised p-2"
+    style={{ inlineSize }}
+  >
+    {children}
+  </div>
+)
+
+const meta = {
+  title: "Components/Layout/NavBar",
+  component: NavBar,
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  parameters: { layout: "padded" },
+  argTypes: {
+    menuPlacement: placementArgType,
+    size: controlSizeArgType,
+  },
+  args: {
+    currentHref: "/board",
+    items: DESTINATIONS,
+    label: "Main",
+    menuIcon: <MenuIcon />,
+    menuLabel: "Main menu",
+    size: "sm",
+  },
+} satisfies Meta<typeof NavBar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Wide enough for all nine, so there is **no menu button at all** —
+ * a trigger that shows at every width is not a fold, it is a nav
+ * you have permanently hidden.
+ */
+export const Default: Story = {
+  render: (navBarProps) => (
+    <Frame inlineSize="52rem">
+      <NavBar {...navBarProps} />
+    </Frame>
+  ),
+}
+
+/**
+ * The two states, and there is deliberately no third.
+ *
+ * `Toolbar` drops items one at a time from the end because its items
+ * are **ranked**. A nav's order is the product's shape, not a
+ * priority list, so half of it in the bar and half behind a button
+ * is a rule no reader can learn.
+ */
+export const AllVariants: Story = {
+  render: ({ currentHref, size }) => (
+    <StoryGrid columns={1}>
+      <StoryCell label="It fits — every destination is a link">
+        <Frame inlineSize="52rem">
+          <NavBar
+            currentHref={currentHref}
+            items={DESTINATIONS}
+            label="Main, wide"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell label="It does not fit — all nine fold together">
+        <Frame inlineSize="18rem">
+          <NavBar
+            currentHref={currentHref}
+            items={DESTINATIONS}
+            label="Main, narrow"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell
+        label={
+          'Folded, menuAlign="end" — the trigger joins the header\'s own actions'
+        }
+      >
+        <Frame inlineSize="18rem">
+          <NavBar
+            currentHref={currentHref}
+            items={DESTINATIONS}
+            label="Main, trigger at the end"
+            menuAlign="end"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell label="No icon — the trigger is its own label">
+        <Frame inlineSize="18rem">
+          <NavBar
+            currentHref={currentHref}
+            items={DESTINATIONS}
+            label="Main, worded trigger"
+            menuLabel="Menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Folded and open is the state nobody screenshots, and it is the
+ * one that matters: the panel is the **complete** list, in the
+ * product's order, with the current destination marked in it.
+ */
+export const AllStates: Story = {
+  render: ({ size }) => (
+    <StoryGrid columns={1}>
+      <StoryCell label="Current destination, in the bar">
+        <Frame inlineSize="52rem">
+          <NavBar
+            currentHref="/board"
+            items={DESTINATIONS}
+            label="Main, current in bar"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell label="On a route no destination owns — nothing is current">
+        <Frame inlineSize="52rem">
+          <NavBar
+            currentHref="/tasks/41"
+            items={FEW_DESTINATIONS}
+            label="Main, nothing current"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+
+      <StoryCell label="Folded, menu open — the complete list">
+        <Frame inlineSize="18rem">
+          <NavBar
+            currentHref="/board"
+            isMenuVisible
+            items={DESTINATIONS}
+            label="Main, folded and open"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Measured rather than breakpointed. The same nine destinations at
+ * three container widths, with no pixel number anywhere in the
+ * component — so a longer label, a tenth destination or a denser
+ * theme moves the fold on its own.
+ */
+export const Responsive: Story = {
+  render: ({ currentHref, size }) => (
+    <ContainerBoard>
+      {(width) => (
+        <Frame inlineSize="100%">
+          <NavBar
+            currentHref={currentHref}
+            items={DESTINATIONS}
+            label={`Main at ${width}`}
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+            size={size}
+          />
+        </Frame>
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * Tab to the trigger, Enter to open, and focus moves into the
+ * panel; Escape closes it and hands focus back. Every row is a real
+ * `<a href>`, so ctrl-click and middle-click still open a tab —
+ * which is the entire reason this is not a `Menu`.
+ */
+export const Interactive: Story = {
+  render: ({ currentHref, size }) => (
+    <Frame inlineSize="18rem">
+      <NavBar
+        currentHref={currentHref}
+        items={DESTINATIONS}
+        label="Main, keyboard"
+        menuIcon={<MenuIcon />}
+        menuLabel="Main menu"
+        size={size}
+      />
+    </Frame>
+  ),
+}
+
+/**
+ * Where it actually goes: `Shell` → `Header`, with the wordmark
+ * before it and the page's own action after it.
+ *
+ * The header row is a flex line, so the bar's `flex-1 min-w-0` is
+ * what gives it a box sized by the row rather than by its own
+ * links — the one arrangement rule the component cannot enforce
+ * from the inside.
+ */
+const AppShellHarness = (): ReactNode => (
+  <Shell>
+    <Header
+      actions={
+        <Button intent="accent" size="sm">
+          Add Task
+        </Button>
+      }
+      heading="Docket"
+    >
+      <NavBar
+        currentHref="/board"
+        items={DESTINATIONS}
+        label="Main"
+        // The header's own action is at the far edge, so the fold
+        // control joins it rather than hugging the wordmark with
+        // the whole track empty after it.
+        menuAlign="end"
+        menuIcon={<MenuIcon />}
+        menuLabel="Main menu"
+      />
+    </Header>
+
+    <Main>
+      <PageContent />
+    </Main>
+  </Shell>
+)
+
+export const InAppShell: Story = {
+  parameters: { layout: "fullscreen" },
+  render: () => <AppShellHarness />,
+}

package/src/NavBar/NavBar.test.tsx

@@ -0,0 +1,344 @@
+import { composeStories } from "@storybook/react"
+import {
+  expect,
+  userEvent,
+  waitFor,
+  within,
+} from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./NavBar.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  Default,
+  InAppShell,
+  Interactive,
+} = composeStories(stories)
+
+test("the nav is named, and its destinations are links", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main",
+    role: "navigation",
+  })
+
+  const board = expectAgentDrivable(within(nav), {
+    name: "Board",
+    role: "link",
+  })
+
+  // A `<button onClick={navigate}>` looks identical in a screenshot
+  // and satisfies "the nav works". It has no `href`, so middle-click,
+  // ctrl-click and "copy link address" all do nothing.
+  await expect(board).toHaveAttribute("href", "/board")
+
+  await expectNoAxeViolations(nav)
+})
+
+/**
+ * The trigger exists **only when the row did not fit**. mux-magic
+ * shows its overflow glyph at every width, which is why its collapse
+ * is not a collapse at all — almost everything lives behind the
+ * button permanently.
+ */
+test("a bar with room shows no menu trigger", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main",
+    role: "navigation",
+  })
+
+  await waitFor(() => {
+    expect(
+      within(nav).queryByRole("button", {
+        name: "Main menu",
+      }),
+    ).toBeNull()
+  })
+
+  await expect(
+    within(nav).getAllByRole("link"),
+  ).toHaveLength(9)
+})
+
+/**
+ * All or nothing — the decision this component exists to hold.
+ *
+ * `Toolbar` would leave four of the nine in the bar at this width
+ * and put five behind the button, which splits the product's own
+ * order across two places with no rule the reader can learn.
+ */
+test("a bar that does not fit folds every destination together", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main, narrow",
+    role: "navigation",
+  })
+
+  expectAgentDrivable(within(nav), {
+    name: "Main menu",
+    role: "button",
+  })
+
+  // Not "fewer links" — no links.
+  await waitFor(() => {
+    expect(within(nav).queryAllByRole("link")).toHaveLength(
+      0,
+    )
+  })
+})
+
+/**
+ * The defect this component refuses to introduce, and the reason it
+ * is not a folded `Toolbar`: `MenuItem` is `{ label, onSelect }`, so
+ * every row in the panel would be a `<button>` — no new tab, no
+ * status bar, nothing to copy.
+ */
+test("a folded destination is still a real link", async () => {
+  const { body } = await mountStory(AllStates)
+
+  const panel = expectAgentDrivable(body, {
+    name: "Main menu",
+    role: "dialog",
+  })
+
+  const archives = expectAgentDrivable(within(panel), {
+    name: "Archives",
+    role: "link",
+  })
+
+  await expect(archives).toHaveAttribute(
+    "href",
+    "/archives",
+  )
+
+  // The complete list, in the product's order — a folded nav is not
+  // an abridged one.
+  await expect(
+    within(panel)
+      .getAllByRole("link")
+      .map((link) => link.textContent),
+  ).toEqual([
+    "Triage",
+    "Backlog",
+    "Phases",
+    "Lanes",
+    "Board",
+    "Archives",
+    "Tonight",
+    "Chats",
+    "Settings",
+  ])
+})
+
+/**
+ * The fleet's habit is to render the nav twice and hide one copy
+ * with `hidden md:flex` — so every link is in the DOM at every
+ * width, and an agent driving the page finds two of each with no way
+ * to tell which one a human can see.
+ */
+test("a destination is mounted exactly once", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main, folded and open",
+    role: "navigation",
+  })
+
+  await expect(
+    within(nav).queryAllByRole("link"),
+  ).toHaveLength(0)
+
+  await waitFor(() => {
+    expect(
+      within(
+        body.getByRole("dialog", { name: "Main menu" }),
+      ).getAllByRole("link", { name: "Chats" }),
+    ).toHaveLength(1)
+  })
+})
+
+/**
+ * A highlight is invisible to a screen reader and to anyone who
+ * cannot separate the two surfaces, so the current destination says
+ * so in the platform's own words — and exactly one does.
+ */
+test("the current destination is marked, and only it", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main, current in bar",
+    role: "navigation",
+  })
+
+  await expect(
+    within(nav)
+      .getAllByRole("link")
+      .filter(
+        (link) =>
+          link.getAttribute("aria-current") === "page",
+      )
+      .map((link) => link.textContent),
+  ).toEqual(["Board"])
+})
+
+/**
+ * `/tasks/41` belongs to no destination, and the honest answer is
+ * that none is current. react-router's `<NavLink to="/">` would mark
+ * the root here unless the caller remembered `end`.
+ */
+test("a route no destination owns marks nothing", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Main, nothing current",
+    role: "navigation",
+  })
+
+  await expect(
+    within(nav)
+      .getAllByRole("link")
+      .filter((link) => link.hasAttribute("aria-current")),
+  ).toHaveLength(0)
+})
+
+/**
+ * A fold control belongs at an edge. `menuAlign="end"` puts it
+ * beside the header's own actions instead of hugging the wordmark
+ * with the whole track empty after it — and it reaches only the
+ * folded row, so the links' own position is not a prop.
+ */
+test("the folded trigger can sit at the end of the track", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const aligned = expectAgentDrivable(canvas, {
+    name: "Main, trigger at the end",
+    role: "navigation",
+  })
+
+  const start = expectAgentDrivable(canvas, {
+    name: "Main, narrow",
+    role: "navigation",
+  })
+
+  await waitFor(() => {
+    expect(
+      within(aligned)
+        .getByRole("button", { name: "Main menu" })
+        .getBoundingClientRect().left,
+    ).toBeGreaterThan(
+      within(start)
+        .getByRole("button", { name: "Main menu" })
+        .getBoundingClientRect().left,
+    )
+  })
+})
+
+/**
+ * The trigger advertises what it opens, and gets focus back when it
+ * closes — both from `useRole` and `FloatingFocusManager` inside
+ * `Popover`, so neither can be forgotten here.
+ */
+test("the trigger advertises the panel it opens", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Main menu",
+    role: "button",
+  })
+
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  await expect(trigger).toHaveAttribute(
+    "aria-haspopup",
+    "dialog",
+  )
+
+  await userEvent.click(trigger)
+
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "true",
+  )
+
+  const panel = expectAgentDrivable(body, {
+    name: "Main menu",
+    role: "dialog",
+  })
+
+  await waitFor(() => {
+    expect(panel).toContainElement(
+      document.activeElement as HTMLElement,
+    )
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(trigger).toHaveFocus()
+  })
+})
+
+/**
+ * Choosing a destination closes the menu behind you — the one
+ * interaction people read as "it didn't work" when it is missing.
+ */
+test("following a link in the panel closes it", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Main menu",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  const panel = expectAgentDrivable(body, {
+    name: "Main menu",
+    role: "dialog",
+  })
+
+  await userEvent.click(
+    within(panel).getByRole("link", { name: "Phases" }),
+  )
+
+  await waitFor(() => {
+    expect(
+      body.queryByRole("dialog", { name: "Main menu" }),
+    ).toBeNull()
+  })
+})
+
+test("the folded nav audits clean while open", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  await expectNoAxeViolations(canvasElement)
+
+  // The panel is portalled out of the canvas, so the resting audit
+  // above cannot see it — an overflow audited only while shut is an
+  // overflow nobody audited.
+  await expectNoAxeViolations(document.body)
+})
+
+/**
+ * Where it actually goes. `Header`'s row is what sizes the bar; the
+ * bar measures that box to decide what to draw in it.
+ */
+test("the shell mounts exactly one nav", async () => {
+  const { canvas } = await mountStory(InAppShell)
+
+  await expect(
+    canvas.getAllByRole("navigation", { name: "Main" }),
+  ).toHaveLength(1)
+})