@charcuterie/ui 3.21.0 → 3.23.0

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

package/src/NavBar/NavBar.tsx

@@ -0,0 +1,271 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { Placement } from "@floating-ui/react"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { usePanelItemSize } from "../Overlay/usePanelItemSize.ts"
+import { Popover } from "../Popover/Popover.tsx"
+import { useToolbarOverflow } from "../Toolbar/useToolbarOverflow.ts"
+import { toClassName } from "../toClassName.ts"
+import { NavBarLink } from "./NavBarLink.tsx"
+import { getIsCurrentHref } from "./navBarCurrent.ts"
+
+export type NavBarItem = {
+  /**
+   * Where it goes. Routed through the injected `RouterLink` when it
+   * is this app's own path, and left to the platform when it is not.
+   */
+  href: string
+  /** Decoration beside the label. Never the accessible name. */
+  icon?: ReactNode
+  /** Defaults to `href`, which is already unique in a nav. */
+  key?: string
+  /** The visible text, and the accessible name. */
+  label: string
+}
+
+export type NavBarProps = {
+  className?: string
+  /**
+   * Where the reader is — `useLocation().pathname` in a
+   * react-router app. `aria-current="page"` is derived from it by
+   * `getIsCurrentHref`, which matches a parent path for its
+   * children and treats `/` as exact.
+   *
+   * Omitted means nothing is current, which is the honest answer on
+   * a route no destination owns.
+   */
+  currentHref?: string
+  /**
+   * **Initial** only, and the bar owns it from then on — the same
+   * uncontrolled contract every other component here has. It exists
+   * so a story (and a screenshot) can show the menu open; an app
+   * almost never passes it.
+   */
+  isMenuVisible?: boolean
+  items: readonly NavBarItem[]
+  /**
+   * Required, and it becomes the `<nav>`'s `aria-label`. Two unnamed
+   * navigation landmarks in one page is axe's `landmark-unique`, and
+   * more to the point it is a screen reader announcing "navigation"
+   * twice with no way to tell which is the main one.
+   */
+  label: string
+  /**
+   * Where the trigger sits in the bar's track once the row has
+   * folded. `"end"` when the header puts its own actions at the
+   * far edge, so the fold control joins them instead of hugging
+   * the wordmark with the whole track empty after it.
+   *
+   * It reaches **only** the folded row, which holds exactly one
+   * item — so it cannot disturb where the links sit when the bar
+   * is whole, and there is deliberately no prop that can.
+   */
+  menuAlign?: "end" | "start"
+  /**
+   * The collapsed trigger's glyph. **No default** — the library
+   * ships no icons, and `☰` renders as nothing where the font lacks
+   * it. With no icon the trigger is a text button reading
+   * `menuLabel`, which works everywhere.
+   */
+  menuIcon?: ReactNode
+  /**
+   * Names the trigger and, through it, the panel it opens. A
+   * `role="dialog"` takes no accessible name from its content.
+   */
+  menuLabel?: string
+  menuPlacement?: Placement
+  size?: ControlSize
+}
+
+/**
+ * The app's destinations as real links, in one line — folding into a
+ * single menu button, whole, when that line does not fit.
+ *
+ * ## Why this is not `Toolbar`
+ *
+ * `Toolbar` already solves collapse-into-an-overflow, and this
+ * component **reuses its measurement** (`useToolbarOverflow`) rather
+ * than growing a second one. What it cannot reuse is the rendering:
+ * a `ToolbarAction` is `{ label, onSelect }` and a collapsed one
+ * becomes a `MenuItem`, so a nav folded into a `Toolbar` is a row of
+ * `<button>`s. Navigation is an `<a href>` — see `NavBarLink`.
+ *
+ * The overflow is a `Popover` (`role="dialog"`) rather than a `Menu`
+ * for the same reason: `role="menu"` permits only the `menuitem`
+ * family, and a `menuitem` is something you *do*, not somewhere you
+ * *go*.
+ *
+ * ## It folds WHOLE, and that is the decision
+ *
+ * `Toolbar` collapses **progressively** — items drop off the end one
+ * at a time — because its items are ranked: the two things you do to
+ * a running job matter more than the two you do to the deck. A nav
+ * is not ranked. Its order is the shape of the product (Docket's
+ * reads as the pipeline: Triage → Backlog → Phases → Board →
+ * Archives), and a half-collapsed one splits that shape across two
+ * places with no rule the reader can learn — "some of the app is up
+ * here and the rest is behind a button" is worse than either whole
+ * answer. So the bar shows **every** destination or **none**, and
+ * the menu, when it opens, is the complete list in the product's own
+ * order.
+ *
+ * ## Measured, not breakpointed
+ *
+ * There is no `collapseAt` prop and no media query. The bar reads
+ * the width its links actually have and folds when their sum stops
+ * fitting, so a longer label, a tenth destination, a
+ * `data-density="kiosk"` or a reader at 175% browser zoom each move
+ * the fold on their own. A hardcoded pixel number is wrong the first
+ * time any of those changes — mux-magic collapses at `480px` and
+ * plex-channels at `760px`, and neither number has a reason.
+ *
+ * ⚠️ **The bar must not be sized by its own contents.** It measures
+ * its own box to decide what to draw in it, so a container that
+ * shrink-wraps makes the answer its own input: put it in a
+ * `minmax(0, 1fr)` grid track or a `flex-1 min-w-0` row. The root
+ * carries `min-w-0 flex-1` for the flex case; a grid track is the
+ * caller's to declare. Same trap `useAdaptiveColumns` documents from
+ * the other end.
+ *
+ * ## Mounted exactly once
+ *
+ * A destination is in the bar or in the panel, never both. The
+ * fleet's habit is to render the whole nav twice and hide one copy
+ * with `hidden md:flex` — mux-magic's `PageHeader` across two
+ * ~55-line blocks, mail-sifter's `TriageQueue` again — which puts
+ * every link in the DOM at every width, so an agent driving the page
+ * finds two of each and cannot tell which one a human can see.
+ */
+export const NavBar = ({
+  className,
+  currentHref,
+  isMenuVisible = false,
+  items,
+  label,
+  menuAlign = "start",
+  menuIcon,
+  menuLabel = "Menu",
+  menuPlacement = "bottom-start",
+  size = "sm",
+}: NavBarProps): ReactNode => {
+  const itemKeys = items.map(
+    (item) => item.key ?? item.href,
+  )
+
+  const { containerRef, trackItem, visibleCount } =
+    useToolbarOverflow({ itemKeys })
+
+  /**
+   * All or nothing. `visibleCount` is the progressive answer and
+   * this is the only thing read off it: the moment one link stops
+   * fitting, every link goes into the menu together.
+   *
+   * The hook's `trackTrigger` is deliberately not wired up, and the
+   * missing measurement costs nothing here. It exists so a
+   * progressive bar can ask "how many fit **beside a trigger**",
+   * which is a question this bar never asks: either every link fits
+   * with no trigger at all, or the row is one trigger and nothing
+   * else. `chooseVisibleCount` tests the whole-row case first and
+   * with the trigger costed at zero, so that branch is exact.
+   */
+  const isCollapsed = visibleCount < items.length
+
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isMenuVisible,
+  })
+
+  const panelItemSize = usePanelItemSize("lg")
+
+  const renderLink = (
+    item: NavBarItem,
+    placement: "bar" | "panel",
+  ) => (
+    <NavBarLink
+      isCurrent={getIsCurrentHref({
+        currentHref,
+        href: item.href,
+      })}
+      item={item}
+      key={item.key ?? item.href}
+      onNavigate={placement === "panel" ? hide : undefined}
+      placement={placement}
+      size={placement === "bar" ? size : panelItemSize}
+      trackElement={
+        placement === "bar" ? trackItem : undefined
+      }
+    />
+  )
+
+  const trigger =
+    menuIcon === undefined ? (
+      <Button
+        appearance="ghost"
+        intent="neutral"
+        onClick={toggle}
+        size={size}
+      >
+        {menuLabel}
+      </Button>
+    ) : (
+      <IconButton
+        appearance="ghost"
+        intent="neutral"
+        label={menuLabel}
+        onClick={toggle}
+        size={size}
+      >
+        {menuIcon}
+      </IconButton>
+    )
+
+  return (
+    <nav
+      aria-label={label}
+      className={toClassName(
+        "flex min-w-0 flex-1 items-center gap-1",
+        // Two written-out entries rather than one interpolated
+        // string: Tailwind's scanner cannot see a class that
+        // exists only at runtime.
+        isCollapsed && menuAlign === "end"
+          ? "justify-end"
+          : "justify-start",
+        className,
+      )}
+      ref={containerRef}
+    >
+      {isCollapsed ? (
+        <Popover
+          // The default panel is `max-w-xs p-3` — sized for a
+          // paragraph of prose. This one holds full-bleed rows that
+          // bring their own inset, so the padding shrinks to the
+          // gutter around them and the width is left to the list.
+          className="max-w-none p-1"
+          heading={menuLabel}
+          isVisible={isVisible}
+          onDismiss={hide}
+          placement={menuPlacement}
+          trigger={trigger}
+        >
+          {/*
+            A list, so a screen reader says how many destinations
+            there are before the reader starts down them — the one
+            thing the bar's own row communicates by simply being
+            visible all at once.
+          */}
+          <ul className="flex min-w-48 list-none flex-col gap-0.5">
+            {items.map((item) => (
+              <li key={item.key ?? item.href}>
+                {renderLink(item, "panel")}
+              </li>
+            ))}
+          </ul>
+        </Popover>
+      ) : (
+        items.map((item) => renderLink(item, "bar"))
+      )}
+    </nav>
+  )
+}