@charcuterie/ui 3.23.0 → 3.25.0

package/src/Nav/Nav.mdx

@@ -0,0 +1,169 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as NavStories from "./Nav.stories";
+
+<Meta of={NavStories} />
+
+# Nav
+
+The app's destinations. A header row, a side rail, a collapsed rail, a strip along the foot
+of a phone, or a panel behind one control — the same list, drawn where it fits.
+
+> **This replaces [`NavBar`](?path=/docs/components-layout-navbar--docs)**, which shipped the
+> header row on its own and is deprecated as of this release. `bar` is `Nav`'s default
+> layout and behaves identically, down to the measured whole-row fold — see *`bar` folds
+> whole* below.
+
+<Canvas of={NavStories.Default} />
+
+## Props
+
+<Controls />
+
+## What was actually missing
+
+`Shell` / `Header` / `Rail` / `Main` shipped the page frame on 2026-08-10 and left **the
+rail empty**. Twelve UI repos, and exactly two have a `<nav>` at all: Docket hand-rolled a
+row of `NavLink`s with the collapse rule in its own stylesheet, Folio hand-rolled another,
+and the other ten have no destinations anywhere.
+
+The two that exist already disagree. Docket *wraps* below its breakpoint, so its header
+stands three lines tall on a phone — which is not a decision anybody made, it is what
+`flex-wrap` does when nobody writes the other rule.
+
+## Every item is a real link
+
+<Canvas of={NavStories.AllVariants} />
+
+`<a href>`, through the injected `RouterLinkProvider` — the same seam `TextLink` and
+`ButtonLink` take, so an app injects its router once and every destination in the library
+routes.
+
+Not a `<button onClick={navigate}>`. That is what mux-magic and QueuePilot do today, it is
+**identical in a screenshot**, and it loses middle-click, ctrl-click, "open in a new tab",
+the status bar preview, and "copy link address". See
+[buttons are actions, links are navigation](?path=/docs/guides-routing--docs).
+
+An `isExternal` item is the exception the seam already knows: a plain anchor,
+`target="_blank"`, `rel="noopener noreferrer"`. Pushing `https://…` onto a router's history
+navigates the SPA to a route that does not exist.
+
+## `icon`, and `NavRailItem`
+
+`NavItem` keeps `icon` optional, because a `bar` never takes the label away — Docket's nine
+destinations are words, and inventing nine glyphs to satisfy a type would be worse than the
+problem.
+
+A rail is the other case. `railIcons` is one `--control-height-lg` square and shows nothing
+else, so an item with no glyph is a blank square that still navigates, and there is no visual
+defect to notice because the row reads as padding. **Annotate a rail's array as
+`NavRailItem[]`** — the same shape with `icon` made required — and the type checker catches
+it before somebody drags a window narrow.
+
+`items` is deliberately **not** discriminated on `layout`. The main call site passes
+`layout={navLayout.layout}` straight from `useNavLayout`, which is a variable and not a
+literal, so a union that split the item type by layout would force a `switch` at the one
+place this component exists to make short.
+
+The library still ships no icons — lucide (ISC) is the fleet recommendation, and a glyph in
+a default renders as nothing where the font lacks it.
+
+## `bar` folds whole, and it is measured
+
+There is no `collapseAt` and no media query on this axis. 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.
+mux-magic collapses at a hardcoded `480px` and plex-channels at `760px`, and neither number
+has a reason.
+
+It folds **whole** rather than progressively, unlike `Toolbar`. `Toolbar`'s items are ranked;
+a nav's order is the shape of the product — Docket's reads as the pipeline, Triage → Backlog
+→ Phases → Board → Archives — and half of that behind a button is a rule no reader can learn.
+
+⚠️ **A `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 current destination is announced
+
+<Canvas of={NavStories.AllStates} />
+
+`aria-current="page"`, and a background. One without the other is WCAG 1.4.1, and a
+`font-weight` swap alone is exactly that failure.
+
+Matching is two rules:
+
+1. An exact path wins — `/board` on `/board`.
+2. Otherwise the **longest path-segment prefix** wins. `/board` matches `/board/inProgress`
+   and does **not** match `/boardgames`, because `games` is not a new segment. Longest, so
+   an app with `/settings` and `/settings/labels` marks the deeper one.
+
+The root is exempt from rule 2: `/` prefixes every path in the app, so a permissive root
+would mark Home current on every screen and the state would carry no information.
+
+Query and fragment are stripped first. A destination and a filtered view of it are the same
+place — `/board?lane=todo` is still Board, which is the case that breaks first in a real app.
+
+**And exactly one item is current.** `getIsCurrentHref` answers for a single link, so a nav
+holding both `/settings` and `/settings/labels` gets `true` twice while the reader is on the
+deeper one — which is what `NavBar` shipped. `resolveActiveKey` is the whole-list answer and
+takes the **deepest** match, by path rather than by array position, so the product's own
+order never decides which destination lights up.
+
+Both are exported, so an app can assert its own table without mounting anything.
+
+## Three widths, one rule — `useNavLayout`
+
+<Canvas of={NavStories.Responsive} />
+
+```tsx
+const nav = useNavLayout({ storageKey: "queuepilot-nav" })
+
+// nav.layout: "rail" | "railIcons" | "menu"
+// nav.isCollapsed, nav.mode, nav.setMode, nav.toggle
+```
+
+| Width | `layout` | What the app renders |
+| --- | --- | --- |
+| `>= 64rem` | `rail` | a `Rail` holding a `Nav` |
+| `>= 48rem` | `railIcons` | the same `Rail`, narrower |
+| below | `menu` | a trigger in the `Header` |
+
+`toggle()` overrides the width and the choice is remembered under `storageKey`. The
+override does **not** reach the narrow state — `expanded` on a 390px screen is a 212px rail
+beside 178px of content — and the remembered value is kept rather than cleared, so rotating
+a tablet back to landscape restores the rail the reader asked for.
+
+**Why the app still places it.** The placement genuinely differs and the rule does not. The
+`menu` state puts a control in the header, which is a different corner of `Shell`'s grid
+from a side rail, and no amount of restyling moves an element across a grid. So the library
+owns *which* state is right, at what width, with what override, remembered where; the app
+owns two `if`s.
+
+## The narrow panel is a `Popover`, not a `Menu`
+
+<Canvas of={NavStories.Interactive} />
+
+`Menu`'s items are `onSelect` callbacks on `<button>`s. That is right for what a menu
+usually holds — undo, redo, a scheme cycle — and wrong for a destination, for every reason
+in *Every item is a real link* above.
+
+So `layout="menu"` is a `Popover`: anchored, dismissable, portalled to the body, and
+`modal={false}` so the caret is not trapped. It is a disclosure, not a dialog somebody has
+to answer. Escape and an outside press both close it.
+
+Give the trigger a real name. A bare hamburger is a glyph, and a glyph is not a name — the
+reason `IconButton` requires `label`.
+
+## When to use which layout
+
+| Layout | For |
+| --- | --- |
+| `bar` | three to six destinations, and a grid that wants every pixel — ai-usage, folio, mux-magic, portly-controllers. Folds itself; needs no `useNavLayout`. |
+| `rail` / `railIcons` | seven or more, or a pipeline you read down — Docket, mail-sifter, QueuePilot |
+| `bottom` | three or four you switch between constantly, in the Narrow View only |
+| `menu` | the Narrow View of a `rail` app |
+
+`bottom` is deliberately not the default narrow answer. It costs a permanent strip of the
+screen, and it earns that only when the destinations are few and the switching is constant.
+An app you settle into for an evening wants the panel.

package/src/Nav/Nav.stories.tsx

@@ -0,0 +1,402 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  BulletedListIcon,
+  ExternalIcon,
+  InboxIcon,
+  MenuIcon,
+  MoonIcon,
+  PlayIcon,
+  SettingsIcon,
+} from "../icons.storyHelpers.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import { Nav } from "./Nav.tsx"
+import type { NavRailItem } from "./navItems.ts"
+
+/**
+ * A stand-in for react-router's `<Link>`, and it does the one thing
+ * a plain anchor must not do here: `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 away.
+ *
+ * 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 a
+      // folded panel see a click that has not been cancelled yet.
+      onClick?.(event)
+
+      event.preventDefault()
+    }}
+  />
+)
+
+/**
+ * A fixed-width box, because `bar` is a measurement. A story that
+ * sizes itself to its contents never folds 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>
+)
+
+/**
+ * **Invented, all of it.** The app this was built alongside is a
+ * household's media tool and a published library must not carry its
+ * shelves, so these are a fictional radio station's screens. The
+ * shape is what matters and the shape is the same: five or six
+ * destinations, two of them configuration, one of them leaving the
+ * app for a source it does not own.
+ */
+const STATION_ITEMS: NavRailItem[] = [
+  {
+    href: "/",
+    icon: <PlayIcon />,
+    key: "now",
+    label: "On air",
+  },
+  {
+    href: "/tonight",
+    icon: <MoonIcon />,
+    key: "tonight",
+    label: "Tonight",
+  },
+  {
+    href: "/library",
+    icon: <BulletedListIcon />,
+    key: "library",
+    label: "Library",
+  },
+  {
+    href: "/incoming",
+    icon: <InboxIcon />,
+    key: "incoming",
+    label: "Incoming",
+  },
+  {
+    href: "/settings",
+    icon: <SettingsIcon />,
+    key: "settings",
+    label: "Settings",
+  },
+]
+
+/**
+ * The same list with a destination that leaves the app, and one long
+ * enough to prove the truncation rule. A rail that only looks right
+ * with short labels has not been tested.
+ */
+const STATION_ITEMS_WITH_EXTERNAL: NavRailItem[] = [
+  ...STATION_ITEMS,
+  {
+    href: "https://example.com/catalogue",
+    icon: <ExternalIcon />,
+    isExternal: true,
+    key: "catalogue",
+    label: "Publisher catalogue — every pressing",
+  },
+]
+
+const meta = {
+  component: Nav,
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  parameters: { layout: "padded" },
+  title: "Components/Layout/Nav",
+} satisfies Meta<typeof Nav>
+
+export default meta
+
+// `typeof Nav`, not `typeof meta`: `NavProps` is a union, and
+// Storybook resolves a `satisfies Meta<>` object with decorators
+// down to `never` args when the component's props do not intersect.
+type Story = StoryObj<typeof Nav>
+
+/**
+ * A header row, which is what an app with a handful of destinations
+ * wants: ai-usage, folio, mux-magic, portly-controllers.
+ */
+export const Default: Story = {
+  args: {
+    activeHref: "/library",
+    items: STATION_ITEMS,
+    layout: "bar",
+    menuIcon: <MenuIcon />,
+    menuLabel: "Main menu",
+  },
+  render: (navProps) => (
+    // Wide enough for all five, so there is **no menu button at
+    // all** — a trigger that shows at every width is not a fold, it
+    // is a nav somebody has permanently hidden.
+    <Frame inlineSize="52rem">
+      <Nav {...navProps} />
+    </Frame>
+  ),
+}
+
+/**
+ * The four placed layouts side by side. `menu` is not here — it is a
+ * panel that needs a trigger, and it has `Interactive` to itself.
+ */
+export const AllVariants: Story = {
+  args: { items: STATION_ITEMS },
+  render: (args) => (
+    <div className="flex flex-col gap-8">
+      <StorySection title="bar — a header row, with room">
+        <Frame inlineSize="52rem">
+          <Nav
+            {...args}
+            activeHref="/library"
+            layout="bar"
+          />
+        </Frame>
+      </StorySection>
+
+      {/*
+        The same bar and the same five destinations, in a box that
+        cannot hold them. It folds WHOLE: `Toolbar` would leave two
+        in the row and put three behind the button, which splits the
+        product's own order across two places with no rule the
+        reader can learn.
+      */}
+      <StorySection title="bar — the same five, folded">
+        <Frame inlineSize="14rem">
+          <Nav
+            {...args}
+            activeHref="/library"
+            label="Main, folded"
+            layout="bar"
+            menuIcon={<MenuIcon />}
+            menuLabel="Main menu"
+          />
+        </Frame>
+      </StorySection>
+
+      {/*
+        The rail layouts take `NavRailItem[]`, so they are given the
+        fixture directly rather than through `args` — spreading the
+        story's args would widen `icon` back to optional and the
+        three cells below would stop type-checking, which is the
+        rule working rather than failing.
+      */}
+      <StoryGrid columns={3}>
+        <StoryCell align="stretch" label="rail">
+          <Nav
+            activeHref="/library"
+            items={STATION_ITEMS}
+            label="Rail with labels"
+            layout="rail"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="railIcons">
+          <Nav
+            activeHref="/library"
+            items={STATION_ITEMS}
+            label="Rail without labels"
+            layout="railIcons"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="bottom">
+          <Nav
+            activeHref="/library"
+            items={STATION_ITEMS}
+            label="Bottom bar"
+            layout="bottom"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </div>
+  ),
+}
+
+/**
+ * Every state one item can be in, and the two that are easy to get
+ * wrong are the last two.
+ *
+ * A **long label** must truncate rather than widen the column: a
+ * flex item's automatic minimum is its content's min-content width,
+ * so an untruncated destination name is the rail's floor.
+ *
+ * An **external** destination is never current, even while the app
+ * sits at a path that looks like it. It is somebody else's origin.
+ */
+export const AllStates: Story = {
+  args: { items: STATION_ITEMS },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="nothing current">
+        <Nav
+          items={STATION_ITEMS}
+          label="Nothing current"
+          layout="rail"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="current, exact">
+        <Nav
+          activeHref="/library"
+          items={STATION_ITEMS}
+          label="Current exact"
+          layout="rail"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="current, one segment deeper"
+      >
+        <Nav
+          activeHref="/library/a-flock-of-seagulls?sort=year"
+          items={STATION_ITEMS}
+          label="Current deeper"
+          layout="rail"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="a long label, and one that leaves"
+      >
+        <Nav
+          activeHref="/library"
+          items={STATION_ITEMS_WITH_EXTERNAL}
+          label="Long and external"
+          layout="rail"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The three widths a rail-shaped nav takes, drawn at the sizes that
+ * produce them rather than by resizing the window.
+ *
+ * `useNavLayout` is what picks between them in an app. Here they are
+ * placed by hand, because the point of the board is to show all
+ * three at once — which a hook keyed to the viewport cannot do.
+ */
+export const Responsive: Story = {
+  args: { items: STATION_ITEMS },
+  render: () => (
+    <div className="flex flex-wrap items-start gap-6">
+      {[
+        {
+          inlineSize: "13rem",
+          label: "≥ 64rem — rail",
+          layout: "rail" as const,
+        },
+        {
+          inlineSize: "4rem",
+          label: "≥ 48rem — railIcons",
+          layout: "railIcons" as const,
+        },
+        {
+          inlineSize: "22rem",
+          label: "< 48rem — bottom (or menu)",
+          layout: "bottom" as const,
+        },
+      ].map((panel) => (
+        <div
+          className="flex flex-col gap-2"
+          key={panel.label}
+          style={{ inlineSize: panel.inlineSize }}
+        >
+          <span className="font-mono text-content-muted text-xs">
+            {panel.label}
+          </span>
+
+          <div className="rounded-md border border-border-subtle bg-surface-raised p-2">
+            <Nav
+              activeHref="/library"
+              items={STATION_ITEMS}
+              label={panel.label}
+              layout={panel.layout}
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * The Narrow View, and the whole keyboard path: Tab to the trigger,
+ * Enter to open, Tab through real links, Escape to close.
+ *
+ * The trigger says **"Menu"** rather than carrying a bare hamburger,
+ * for the reason `IconButton` exists — a glyph is not a name.
+ */
+export const Interactive: Story = {
+  args: { items: STATION_ITEMS },
+  render: () => {
+    const NavMenuStory = () => {
+      const [isVisible, setIsVisible] = useState(false)
+
+      return (
+        <Nav
+          activeHref="/library"
+          isVisible={isVisible}
+          items={STATION_ITEMS_WITH_EXTERNAL}
+          label="Main"
+          layout="menu"
+          onDismiss={() => {
+            setIsVisible(false)
+          }}
+          trigger={
+            <Button
+              appearance="outline"
+              intent="neutral"
+              onClick={() => {
+                setIsVisible((isOpen) => !isOpen)
+              }}
+            >
+              Menu
+            </Button>
+          }
+        />
+      )
+    }
+
+    return <NavMenuStory />
+  },
+}