@charcuterie/ui 3.22.0 → 3.24.0

package/src/Nav/Nav.tsx

@@ -0,0 +1,406 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { Placement } from "@floating-ui/react"
+import type { ReactElement, 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 { NavLink } from "./NavLink.tsx"
+import type { NavItem } from "./navItems.ts"
+import {
+  getNavItemKey,
+  resolveActiveKey,
+} from "./navItems.ts"
+
+/**
+ * Where the destinations are drawn. Not *whether* — see
+ * `useNavLayout`, which answers that from the width.
+ */
+export type NavLayout =
+  | "bar"
+  | "bottom"
+  | "menu"
+  | "rail"
+  | "railIcons"
+
+type NavCommonProps = {
+  /**
+   * The destinations, in the order the product reads.
+   *
+   * Annotate the array as `NavRailItem[]` when the app uses a rail:
+   * it is the same shape with `icon` made **required**, because
+   * `railIcons` takes the label away and an item with no glyph is a
+   * blank square that still navigates. `NavItem` keeps `icon`
+   * optional so that a `bar`, where the label never goes anywhere,
+   * does not have to invent one.
+   */
+  items: readonly NavItem[]
+  /**
+   * The address the app is at — usually `location.pathname`. The
+   * item that matches wears `aria-current="page"`.
+   *
+   * Omitted means nothing is current, which is honest on a screen
+   * the nav does not contain (a modal route, an error page) and is
+   * better than marking the closest thing.
+   */
+  activeHref?: string
+  className?: string
+  /**
+   * The `<nav>`'s accessible name. Default `"Main"`.
+   *
+   * Required in spirit and defaulted in practice: two unnamed
+   * navigations on one page are two landmarks a screen reader
+   * announces identically, which is axe's `landmark-unique`. An app
+   * with a second nav — a queue's sub-navigation, a footer — names
+   * that one and leaves this one alone.
+   */
+  label?: string
+}
+
+type NavPlacedProps = NavCommonProps & {
+  /**
+   * **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. `bar` only.
+   */
+  isMenuVisible?: boolean
+  layout?: "bar" | "bottom" | "rail" | "railIcons"
+  /**
+   * 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 folded trigger's glyph. **No default** — the library ships
+   * no icons, and a hamburger 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
+}
+
+type NavMenuProps = NavCommonProps & {
+  isVisible: boolean
+  layout: "menu"
+  onDismiss: () => void
+  placement?: Placement
+  /** The control the panel hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+/**
+ * The union splits on `menu` and **only** on `menu`, because that is
+ * the one layout an app cannot reach with a variable: its trigger
+ * goes in the `Header`, so the app is already writing the branch.
+ *
+ * Everything else takes `layout={navLayout.layout}` straight from
+ * `useNavLayout` — which is a *variable*, not a literal, so a union
+ * that also split `items` by layout would force a `switch` at the
+ * one call site this component exists to make short.
+ */
+export type NavProps = NavMenuProps | NavPlacedProps
+
+const LIST_CLASS: Record<NavLayout, string> = {
+  bar: "flex min-w-0 flex-row items-center gap-1",
+  // `auto-cols-fr` with `grid-flow-col`: equal columns whose count
+  // comes from the item list, so four destinations divide the width
+  // and five still do, with no per-app count to keep in step.
+  bottom: "grid auto-cols-fr grid-flow-col gap-0",
+  menu: "flex min-w-48 flex-col gap-0.5",
+  rail: "flex min-w-0 flex-col gap-1",
+  railIcons: "flex flex-col items-center gap-1",
+}
+
+const NAV_CLASS: Record<NavLayout, string> = {
+  bar: "flex min-w-0 flex-1 items-center gap-1",
+  bottom: "border-border-subtle border-t bg-surface-raised",
+  menu: "min-w-0",
+  rail: "min-w-0",
+  railIcons: "min-w-0",
+}
+
+/**
+ * The app's destinations — a header row, a side rail, a collapsed
+ * rail, a strip along the foot of the Narrow View, or a panel behind
+ * one control. The same list, drawn where it fits.
+ *
+ * ## What was actually missing
+ *
+ * `Shell` / `Header` / `Rail` / `Main` shipped the page frame on
+ * 2026-08-10 and left the **contents of the nav rail empty**. Twelve
+ * UI repos, and exactly two of them had a `<nav>` at all: Docket
+ * hand-rolled a row of `NavLink`s with the collapse rule in the
+ * app's own stylesheet, Folio hand-rolled another, and the other ten
+ * had no destinations anywhere. The two that existed already
+ * disagreed — Docket *wraps* below its breakpoint and 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
+ *
+ * `<a href>`, through the injected `RouterLinkProvider` — see
+ * `NavLink`, which is where that argument is written down.
+ *
+ * ## `aria-current="page"`, and exactly one of them
+ *
+ * `resolveActiveKey` takes the **deepest** matching path, so an app
+ * holding both `/settings` and `/settings/labels` marks the page the
+ * reader is actually on rather than both.
+ *
+ * ## `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, and a nav's order is the shape of
+ * the product (Docket's reads as the pipeline: Triage → Backlog →
+ * Phases → Board → Archives). 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 root
+ * carries `min-w-0 flex-1` for the flex case; a grid track is the
+ * caller's to declare.
+ *
+ * ## `menu` is the rail's narrow state, and the app owns it
+ *
+ * `bar` builds its own trigger because it knows when it folded.
+ * `menu` takes one, because the rail's narrow state puts that
+ * control in the `Header` — a different corner of `Shell`'s grid
+ * from a side rail, and no media query moves an element across a
+ * grid. `useNavLayout` is what tells the app which of the two it is
+ * rendering.
+ *
+ * ## 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 Nav = (props: NavProps): ReactNode => {
+  const {
+    activeHref,
+    className,
+    items,
+    label = "Main",
+  } = props
+
+  const layout = props.layout ?? "bar"
+
+  const activeKey = resolveActiveKey(items, activeHref)
+
+  const itemKeys = items.map(getNavItemKey)
+
+  const { containerRef, trackItem, visibleCount } =
+    useToolbarOverflow({ itemKeys })
+
+  // The bar-only knobs. `menu` is the one variant that does not
+  // carry them, and it is the one variant the app branches on
+  // anyway.
+  const placedProps = props.layout === "menu" ? null : props
+
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: placedProps?.isMenuVisible ?? false,
+  })
+
+  const panelItemSize = usePanelItemSize("lg")
+
+  /**
+   * 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.
+   */
+  const isFolded =
+    layout === "bar" && visibleCount < items.length
+
+  const size = placedProps?.size ?? "sm"
+
+  const renderList = (
+    placement:
+      | "bar"
+      | "bottom"
+      | "panel"
+      | "rail"
+      | "railIcons",
+    listLayout: NavLayout,
+  ) => (
+    <ul
+      className={toClassName(
+        "list-none p-0",
+        LIST_CLASS[listLayout],
+      )}
+    >
+      {items.map((item) => {
+        const key = getNavItemKey(item)
+
+        return (
+          <li className="min-w-0" key={key}>
+            <NavLink
+              isCurrent={key === activeKey}
+              item={item}
+              onNavigate={
+                placement === "panel" ? hide : undefined
+              }
+              placement={placement}
+              size={
+                placement === "panel" ? panelItemSize : size
+              }
+              trackElement={
+                placement === "bar"
+                  ? (element) => {
+                      trackItem(key, element)
+                    }
+                  : undefined
+              }
+            />
+          </li>
+        )
+      })}
+    </ul>
+  )
+
+  if (props.layout === "menu") {
+    /**
+     * A `Popover` rather than a `Menu`. `Menu`'s items are
+     * `onSelect` callbacks on `<button>`s, which is right for the
+     * things a menu usually holds — undo, redo, a scheme cycle — and
+     * wrong for a destination, for every reason `NavLink` gives.
+     *
+     * `modal={false}` inside it, so the caret is not trapped: the
+     * panel is a disclosure, not a dialog somebody has to answer.
+     */
+    return (
+      <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={label}
+        isVisible={props.isVisible}
+        onDismiss={props.onDismiss}
+        placement={props.placement ?? "bottom-start"}
+        trigger={props.trigger}
+      >
+        {/*
+          A list, so a screen reader says how many destinations
+          there are before the reader starts down them — the one
+          thing a visible row communicates by simply being visible
+          all at once.
+        */}
+        <nav aria-label={label}>
+          {renderList("panel", "menu")}
+        </nav>
+      </Popover>
+    )
+  }
+
+  if (layout !== "bar") {
+    return (
+      <nav
+        aria-label={label}
+        className={toClassName(
+          NAV_CLASS[layout],
+          className,
+        )}
+      >
+        {renderList(
+          layout === "rail"
+            ? "rail"
+            : layout === "railIcons"
+              ? "railIcons"
+              : "bottom",
+          layout,
+        )}
+      </nav>
+    )
+  }
+
+  const menuLabel = placedProps?.menuLabel ?? "Menu"
+
+  const menuIcon = placedProps?.menuIcon
+
+  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(
+        NAV_CLASS.bar,
+        // Two written-out entries rather than one interpolated
+        // string: Tailwind's scanner cannot see a class that exists
+        // only at runtime.
+        isFolded && placedProps?.menuAlign === "end"
+          ? "justify-end"
+          : "justify-start",
+        className,
+      )}
+      ref={containerRef}
+    >
+      {isFolded ? (
+        <Popover
+          className="max-w-none p-1"
+          heading={menuLabel}
+          isVisible={isVisible}
+          onDismiss={hide}
+          placement={
+            placedProps?.menuPlacement ?? "bottom-start"
+          }
+          trigger={trigger}
+        >
+          {renderList("panel", "menu")}
+        </Popover>
+      ) : (
+        renderList("bar", "bar")
+      )}
+    </nav>
+  )
+}

package/src/Nav/NavLink.tsx

@@ -0,0 +1,220 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { MouseEvent, ReactNode } from "react"
+
+import {
+  CONTROL_SIZE_CLASS,
+  PANEL_ITEM_SIZE_CLASS,
+} from "../controlStyles.ts"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import type { NavItem } from "./navItems.ts"
+
+/** Where the row is drawn. Each paints differently; all are links. */
+export type NavLinkPlacement =
+  | "bar"
+  | "bottom"
+  | "panel"
+  | "rail"
+  | "railIcons"
+
+export type NavLinkProps = {
+  isCurrent: boolean
+  item: NavItem
+  /**
+   * Fires when the reader activates this link **in a way that keeps
+   * them on the page** — a plain left click, Enter, Space. It is
+   * what closes the panel behind them.
+   *
+   * A modified click (ctrl, meta, shift, alt) opens a new tab and
+   * leaves this document exactly where it was, so it deliberately
+   * does not fire: shutting the menu the reader is still working
+   * through is the behaviour that makes people stop ctrl-clicking.
+   */
+  onNavigate?: () => void
+  placement: NavLinkPlacement
+  size: ControlSize
+  /** Hands the bar row's box to the measuring hook. Bar only. */
+  trackElement?: (element: HTMLElement | null) => void
+}
+
+const PLACEMENT_CLASS: Record<NavLinkPlacement, string> = {
+  bar: "inline-flex shrink-0 items-center rounded-md border border-transparent whitespace-nowrap",
+  // A foot-of-the-screen target is a thumb target, so it takes the
+  // 44px WCAG 2.5.5 floor rather than a control height. It is a
+  // genuinely standalone tap target and shares a row with nothing,
+  // which is the case
+  // `2026-08-05-controls-share-one-height-no-per-component-touch-floor`
+  // reserves `MIN_TOUCH_TARGET_CLASS` for.
+  bottom:
+    "flex min-h-(--control-min-touch-target) flex-col items-center justify-center gap-1 rounded-none px-1 py-2 text-xs",
+  panel: "flex w-full items-center rounded-sm text-start",
+  rail: "flex w-full items-center rounded-md",
+  // Square, and sized on both axes from the height token — the same
+  // rule `ICON_CONTROL_SIZE_CLASS` states, so a collapsed rail item
+  // and an `IconButton` beside it measure the same.
+  railIcons:
+    "flex size-(--control-height-lg) items-center justify-center rounded-md",
+}
+
+/**
+ * `-hover` in the panel, not the plain surface: the panel is drawn
+ * on `surface-overlay`, which every dark scheme paints *lighter*
+ * than the base tint, so the plain one reads as no change at all.
+ * Same correction `MenuAction` carries.
+ */
+const CURRENT_CLASS: Record<NavLinkPlacement, string> = {
+  bar: "bg-intent-neutral-surface font-medium text-content-primary",
+  bottom:
+    "bg-intent-neutral-surface font-medium text-content-primary",
+  panel:
+    "bg-intent-neutral-surface-hover font-medium text-content-primary",
+  rail: "bg-intent-neutral-surface font-medium text-content-primary",
+  railIcons:
+    "bg-intent-neutral-surface font-medium text-content-primary",
+}
+
+const RESTING_CLASS: Record<NavLinkPlacement, string> = {
+  bar: "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+  bottom:
+    "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+  panel:
+    "text-content-primary hover:bg-intent-neutral-surface-hover",
+  rail: "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+  railIcons:
+    "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+}
+
+/**
+ * One destination — and it is a real `<a href>` in every placement.
+ *
+ * That is the whole reason this exists rather than the `Menu` a
+ * collapsed `Toolbar` opens: `MenuItem` is `{ label, onSelect }`, so
+ * a nav folded into one becomes a row of `<button>`s. It looks
+ * identical in a screenshot and it loses middle-click, ctrl-click,
+ * "open in a new tab", "copy link address", the status bar, and the
+ * browser's own visited styling. `BuildingAnApp.mdx` names
+ * `<button onClick={navigate}>` as the fleet's most common
+ * navigation defect; a collapse mechanism that introduced it at
+ * narrow widths would be that defect on a timer.
+ *
+ * The router seam is `ButtonLink`'s, unchanged: an external
+ * destination or a fragment falls back to a plain anchor rather than
+ * being pushed onto a history stack that has no route for it.
+ */
+export const NavLink = ({
+  isCurrent,
+  item,
+  onNavigate,
+  placement,
+  size,
+  trackElement,
+}: NavLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  const isExternal = item.isExternal === true
+
+  const LinkElement =
+    isExternal || !getIsRoutedHref(item.href)
+      ? "a"
+      : RouterLink
+
+  const isIconOnly = placement === "railIcons"
+
+  const sizeClass =
+    placement === "panel"
+      ? PANEL_ITEM_SIZE_CLASS[size]
+      : placement === "bar"
+        ? CONTROL_SIZE_CLASS[size]
+        : placement === "rail"
+          ? "min-h-(--control-height-md) gap-(--control-gap-md) px-(--control-padding-inline-md) py-1.5 text-md"
+          : ""
+
+  return (
+    <LinkElement
+      // The platform's own "you are here", and the reason the paint
+      // is never the only signal: a highlight is invisible to a
+      // screen reader and to anyone who cannot tell the two surfaces
+      // apart. A `font-weight` swap alone is the same WCAG 1.4.1
+      // failure.
+      aria-current={isCurrent ? "page" : undefined}
+      className={toClassName(
+        "no-underline transition-colors duration-(--duration-fast) ease-standard",
+        PLACEMENT_CLASS[placement],
+        sizeClass,
+        // Two written-out entries rather than one interpolated
+        // string, the same rule `SegmentedOption` follows:
+        // Tailwind's scanner cannot see a class that exists only at
+        // runtime, and `tailwindCandidates.test.ts` rejects a
+        // template literal in a className outright.
+        isCurrent
+          ? CURRENT_CLASS[placement]
+          : RESTING_CLASS[placement],
+        FOCUS_RING_CLASS,
+      )}
+      href={item.href}
+      onClick={(event: MouseEvent<HTMLAnchorElement>) => {
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.metaKey ||
+          event.shiftKey
+        ) {
+          return
+        }
+
+        onNavigate?.()
+      }}
+      ref={(element: HTMLAnchorElement | null) => {
+        trackElement?.(element)
+      }}
+      // `noreferrer` beside `noopener` on purpose: one closes the
+      // `window.opener` hole, the other stops this app's address
+      // leaking as the referrer to a product it does not own.
+      rel={isExternal ? "noopener noreferrer" : undefined}
+      target={isExternal ? "_blank" : undefined}
+      // A pointer can recover the name a collapsed rail has hidden.
+      // It is not the accessible name — see the `VisuallyHidden`
+      // below — because `title` alone is not reliably announced.
+      title={isIconOnly ? item.label : undefined}
+    >
+      {item.icon === undefined ? null : (
+        // Decoration beside the item's own text. An icon that
+        // announces itself turns "Settings" into "gear Settings".
+        <span
+          aria-hidden="true"
+          className="flex shrink-0 text-content-secondary"
+        >
+          {item.icon}
+        </span>
+      )}
+
+      {isIconOnly ? (
+        <VisuallyHidden>{item.label}</VisuallyHidden>
+      ) : (
+        // `truncate`, not `min-w-0` alone: a flex item's automatic
+        // minimum is its content's min-content width, so one long
+        // unbroken destination name becomes the rail's floor and
+        // widens the column. The full text stays reachable in the
+        // `title` a truncated element gets from the platform.
+        <span
+          className={
+            placement === "bar" ? undefined : "truncate"
+          }
+        >
+          {item.label}
+        </span>
+      )}
+
+      {isExternal ? (
+        <VisuallyHidden>
+          (opens in a new tab)
+        </VisuallyHidden>
+      ) : null}
+    </LinkElement>
+  )
+}