@charcuterie/ui 3.21.0 → 3.23.0

package/src/NavBar/NavBar.mdx

@@ -0,0 +1,157 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as NavBarStories from "./NavBar.stories";
+
+<Meta of={NavBarStories} />
+
+# NavBar
+
+The app's destinations as real links, in one line — folding into a single menu button,
+**whole**, when that line does not fit.
+
+<Canvas of={NavBarStories.Default} />
+
+## Props
+
+<Controls />
+
+## 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
+work moves along — Triage → Backlog → Phases → Lanes → Board → Archives — and a
+half-collapsed bar splits that shape across two places with no rule a 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 is the complete list in
+the product's own order.
+
+<Canvas of={NavBarStories.AllVariants} />
+
+## Why this is not a folded `Toolbar`
+
+`Toolbar` already solves collapse-into-an-overflow, and this component **reuses its
+measurement** — `useToolbarOverflow`, the same tape measure — 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`, which is also `{ label, onSelect }`. A nav folded into
+one is a row of `<button>`s:
+
+| | `<button onClick={navigate}>` | `<a href>` |
+| --- | --- | --- |
+| Middle-click, ctrl-click | nothing | opens a tab |
+| "Open link in new tab" | absent from the menu | there |
+| "Copy link address" | absent | there |
+| Status bar on hover | blank | the destination |
+| Visited styling, the back button's idea of history | none | the platform's |
+
+`BuildingAnApp.mdx` names `<button onClick={navigate}>` as the fleet's most common
+navigation defect. A collapse mechanism that introduced it below a certain width would be
+that defect on a timer — and it screenshots identically, which is how it would survive
+review.
+
+The panel 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**.
+
+## 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, `data-density="kiosk"`, or a reader at 175% browser zoom each move the fold on
+their own.
+
+mux-magic collapses at a hardcoded `480px` and plex-channels at `760px`. Neither number has
+a reason, and both are wrong the first time anything about the content changes.
+
+<Canvas of={NavBarStories.Responsive} />
+
+## ⚠️ 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: fewer links → a narrower box → fewer links.
+
+The root carries `min-w-0 flex-1`, which is the whole fix inside a flex row. A grid track is
+the caller's to declare:
+
+```css
+grid-template-columns: auto minmax(0, 1fr) auto; /* brand, nav, actions */
+```
+
+`auto` on that middle track is the bug — it floors at the nav's min-content width, which is
+the sum of every link.
+
+## Which destination is current
+
+The library is router-agnostic (see `RouterLinkProvider`), so it cannot ask a router which
+link is active. The app hands it one string:
+
+```tsx
+<NavBar currentHref={useLocation().pathname} items={DESTINATIONS} label="Main" />
+```
+
+`getIsCurrentHref` decides the rest, and it is exported so an app can ask the same question
+elsewhere:
+
+- **A parent path is current for its children.** `/tasks` is current on `/tasks/41`,
+  because a nav item names a section and a section does not stop being the one you are in
+  when you open something inside it. The match is on whole segments, so `/task` is not
+  current for `/tasks`.
+- **`/` is exact.** react-router's `<NavLink to="/">` is active on *every* route unless the
+  caller remembers `end`, which is the footgun behind every "why is Home always
+  highlighted" bug. There is no prop to change it here: a nav with two current items has
+  stopped saying anything.
+- **The query string and the fragment are not part of the answer.**
+  `/backlog?focus=search` is still the Backlog.
+
+The current destination gets `aria-current="page"` as well as the fill, because a highlight
+is invisible to a screen reader and to anyone who cannot separate the two surfaces.
+
+## 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.
+Every link is then 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, the two copies drift, and every test has to
+be defensively scoped.
+
+<Canvas of={NavBarStories.AllStates} />
+
+## A fold control belongs at an edge
+
+`menuAlign="end"` puts the trigger beside the header's own actions rather than leaving it
+hugging the wordmark with the whole track empty after it. It reaches **only** the folded
+row, which holds exactly one item — so where the links sit when the bar is whole is not a
+prop, and cannot be made inconsistent with the rest of the header.
+
+## The trigger's glyph is the app's
+
+The library ships no icons, so `menuIcon` has no default — U+2630 renders as nothing where
+the font lacks it, which includes this sandbox's chromium and the kiosk image. With no icon
+the trigger is a text button reading `menuLabel`, which works everywhere.
+
+`menuLabel` names the trigger **and** the panel it opens: a `role="dialog"` takes no
+accessible name from its content.
+
+## Keyboard
+
+Every link in the bar is its own tab stop, which is what a `<nav>` is — this is not a
+`role="toolbar"`, and there is no roving focus to learn.
+
+Folded, it is one tab stop: Enter or Space opens the panel, focus moves into it, Escape
+closes it and hands focus back to the trigger. Choosing a destination closes it too —
+unless the click was modified, because a ctrl-click leaves the reader exactly where they
+were and shutting the menu they are still reading is how people stop ctrl-clicking.
+
+<Canvas of={NavBarStories.Interactive} />
+
+## In a shell
+
+<Canvas of={NavBarStories.InAppShell} />

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 />,
+}