@charcuterie/ui 3.22.0 → 3.24.0

package/dist/Nav/Nav.js

@@ -0,0 +1,165 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useVisibility } from "@charcuterie/logic";
+import { Button } from "../Button/Button.js";
+import { IconButton } from "../IconButton/IconButton.js";
+import { usePanelItemSize } from "../Overlay/usePanelItemSize.js";
+import { Popover } from "../Popover/Popover.js";
+import { useToolbarOverflow } from "../Toolbar/useToolbarOverflow.js";
+import { toClassName } from "../toClassName.js";
+import { NavLink } from "./NavLink.js";
+import { getNavItemKey, resolveActiveKey, } from "./navItems.js";
+const LIST_CLASS = {
+    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 = {
+    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) => {
+    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, listLayout) => (_jsx("ul", { className: toClassName("list-none p-0", LIST_CLASS[listLayout]), children: items.map((item) => {
+            const key = getNavItemKey(item);
+            return (_jsx("li", { className: "min-w-0", children: _jsx(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 }) }, key));
+        }) }));
+    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 (_jsx(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.
+        , { 
+            // 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, children: _jsx("nav", { "aria-label": label, children: renderList("panel", "menu") }) }));
+    }
+    if (layout !== "bar") {
+        return (_jsx("nav", { "aria-label": label, className: toClassName(NAV_CLASS[layout], className), children: renderList(layout === "rail"
+                ? "rail"
+                : layout === "railIcons"
+                    ? "railIcons"
+                    : "bottom", layout) }));
+    }
+    const menuLabel = placedProps?.menuLabel ?? "Menu";
+    const menuIcon = placedProps?.menuIcon;
+    const trigger = menuIcon === undefined ? (_jsx(Button, { appearance: "ghost", intent: "neutral", onClick: toggle, size: size, children: menuLabel })) : (_jsx(IconButton, { appearance: "ghost", intent: "neutral", label: menuLabel, onClick: toggle, size: size, children: menuIcon }));
+    return (_jsx("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, children: isFolded ? (_jsx(Popover, { className: "max-w-none p-1", heading: menuLabel, isVisible: isVisible, onDismiss: hide, placement: placedProps?.menuPlacement ?? "bottom-start", trigger: trigger, children: renderList("panel", "menu") })) : (renderList("bar", "bar")) }));
+};
+//# sourceMappingURL=Nav.js.map

package/dist/Nav/Nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Nav.js","sourceRoot":"","sources":["../../src/Nav/Nav.tsx"],"names":[],"mappings":"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"}

package/dist/Nav/NavLink.d.ts

@@ -0,0 +1,43 @@
+import type { ControlSize } from "@charcuterie/tokens";
+import type { ReactNode } from "react";
+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;
+};
+/**
+ * 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 declare const NavLink: ({ isCurrent, item, onNavigate, placement, size, trackElement, }: NavLinkProps) => ReactNode;
+//# sourceMappingURL=NavLink.d.ts.map

package/dist/Nav/NavLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavLink.d.ts","sourceRoot":"","sources":["../../src/Nav/NavLink.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,OAAO,CAAA;AAWlD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GACxB,KAAK,GACL,QAAQ,GACR,OAAO,GACP,MAAM,GACN,WAAW,CAAA;AAEf,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,OAAO,CAAA;IACb;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,IAAI,EAAE,WAAW,CAAA;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;CACrD,CAAA;AAiDD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,GAAI,iEAOrB,YAAY,KAAG,SA0GjB,CAAA"}

package/dist/Nav/NavLink.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CONTROL_SIZE_CLASS, PANEL_ITEM_SIZE_CLASS, } from "../controlStyles.js";
+import { FOCUS_RING_CLASS } from "../intentStyles.js";
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.js";
+import { getIsRoutedHref } from "../RouterLink/routerLink.js";
+import { toClassName } from "../toClassName.js";
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.js";
+const PLACEMENT_CLASS = {
+    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 = {
+    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 = {
+    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, }) => {
+    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 (_jsxs(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) => {
+            if (event.defaultPrevented ||
+                event.button !== 0 ||
+                event.altKey ||
+                event.ctrlKey ||
+                event.metaKey ||
+                event.shiftKey) {
+                return;
+            }
+            onNavigate?.();
+        }, ref: (element) => {
+            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, children: [item.icon === undefined ? null : (_jsx("span", { "aria-hidden": "true", className: "flex shrink-0 text-content-secondary", children: item.icon })), isIconOnly ? (_jsx(VisuallyHidden, { children: item.label })) : (_jsx("span", { className: placement === "bar" ? undefined : "truncate", children: item.label })), isExternal ? (_jsx(VisuallyHidden, { children: "(opens in a new tab)" })) : null] }));
+};
+//# sourceMappingURL=NavLink.js.map

package/dist/Nav/NavLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavLink.js","sourceRoot":"","sources":["../../src/Nav/NavLink.tsx"],"names":[],"mappings":"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"}

package/dist/Nav/navItems.d.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+export type NavItem = {
+    /**
+     * 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;
+    /**
+     * A destination outside this app. It renders a plain anchor with
+     * `target="_blank"` and `rel="noopener noreferrer"`, and it is
+     * never current — pushing `https://…` onto a router's history
+     * navigates the app to a route it does not have.
+     */
+    isExternal?: boolean;
+    /** Defaults to `href`, which is already unique in a nav. */
+    key?: string;
+    /** The visible text, and the accessible name. */
+    label: string;
+};
+/**
+ * What the rail layouts take. `icon` stops being optional, because
+ * `railIcons` takes the **label** away: 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.
+ *
+ * Optional would move that failure out of the type checker and into
+ * the first time somebody drags a window narrow. The library still
+ * ships no icons — a glyph in a default renders as nothing where the
+ * font lacks it, so the app brings its own.
+ */
+export type NavRailItem = NavItem & {
+    icon: ReactNode;
+};
+export declare const getNavItemKey: (item: NavItem) => string;
+export declare const getIsCurrentHref: ({ currentHref, href, }: {
+    /** Where the reader is. `undefined` means "nothing is current". */
+    currentHref: string | undefined;
+    /** Where this destination goes. */
+    href: string;
+}) => boolean;
+/**
+ * The current destination's key, or `null` — the whole-list answer,
+ * and the one `Nav` marks with `aria-current="page"`.
+ *
+ * ## Exactly one, because the deepest match wins
+ *
+ * `getIsCurrentHref` is asked per item, so a nav holding both
+ * `/settings` and `/settings/labels` gets `true` twice while the
+ * reader is on the deeper one. Two current items is a nav that has
+ * stopped saying anything — the same thing react-router's `<NavLink
+ * to="/">` footgun produces — so the longest matching path wins and
+ * the shallower section stands down.
+ *
+ * Longest by **path**, not by array position: an app must be able to
+ * list its destinations in the order the product reads (Docket's is
+ * the pipeline) without that order deciding which one lights up.
+ *
+ * ## An external item is never current
+ *
+ * It is not a place inside this app, so no address the app is at can
+ * be it. Without this, an item pointing at `https://example.com/board`
+ * matches the app's own `/board` on a plain string compare.
+ */
+export declare const resolveActiveKey: (items: readonly NavItem[], activeHref?: string) => string | null;
+//# sourceMappingURL=navItems.d.ts.map

package/dist/Nav/navItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navItems.d.ts","sourceRoot":"","sources":["../../src/Nav/navItems.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,MAAM,OAAO,GAAG;IACpB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG;IAClC,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,OAAO,KAAG,MACvB,CAAA;AA8CvB,eAAO,MAAM,gBAAgB,GAAI,wBAG9B;IACD,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;CACb,KAAG,OAgBH,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,SAAS,OAAO,EAAE,EACzB,aAAa,MAAM,KAClB,MAAM,GAAG,IAqCX,CAAA"}

package/dist/Nav/navItems.js

@@ -0,0 +1,104 @@
+export const getNavItemKey = (item) => item.key ?? item.href;
+/**
+ * Which destination the reader is on — the rule behind
+ * `aria-current="page"`, kept pure so it can be checked in Node.
+ *
+ * The library is router-agnostic (see `RouterLinkProvider`), so it
+ * cannot ask a router which link is active. The app hands it one
+ * string — `useLocation().pathname`, `window.location.pathname`,
+ * whatever it has — and this decides the rest.
+ *
+ * ## A parent path is current for its children
+ *
+ * `/tasks` is current while the reader is 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: `/task` is *not* current for `/tasks`, which a bare
+ * `startsWith` would get wrong.
+ *
+ * ## `/` is exact, and that is deliberately not react-router
+ *
+ * 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 in the fleet. The root
+ * matches only itself here, and there is no prop to change it: a nav
+ * with two current items is a nav that has stopped saying anything.
+ *
+ * ## The query string and the fragment are not part of the answer
+ *
+ * `/backlog?focus=search` is still the Backlog. Sorting a list does
+ * not move the reader to a different destination.
+ *
+ * ⚠️ **This answers for ONE item, so it cannot keep the promise in
+ * the paragraph above by itself.** Given `/settings` and
+ * `/settings/labels`, it says `true` for both on the deeper path.
+ * `resolveActiveKey` is the whole-list answer, and it is what `Nav`
+ * uses; reach for this one only when there is a single link to test.
+ */
+const toComparablePath = (href) => {
+    const path = href.split(/[#?]/u)[0] ?? "";
+    // A trailing slash is the same place, so it must not change the
+    // answer — but `/` itself has to survive being trimmed.
+    return path.length > 1 ? path.replace(/\/+$/u, "") : path;
+};
+export const getIsCurrentHref = ({ currentHref, href, }) => {
+    if (currentHref === undefined) {
+        return false;
+    }
+    const current = toComparablePath(currentHref);
+    const target = toComparablePath(href);
+    if (target === "" || target === "/") {
+        return current === target;
+    }
+    return (current === target || current.startsWith(`${target}/`));
+};
+/**
+ * The current destination's key, or `null` — the whole-list answer,
+ * and the one `Nav` marks with `aria-current="page"`.
+ *
+ * ## Exactly one, because the deepest match wins
+ *
+ * `getIsCurrentHref` is asked per item, so a nav holding both
+ * `/settings` and `/settings/labels` gets `true` twice while the
+ * reader is on the deeper one. Two current items is a nav that has
+ * stopped saying anything — the same thing react-router's `<NavLink
+ * to="/">` footgun produces — so the longest matching path wins and
+ * the shallower section stands down.
+ *
+ * Longest by **path**, not by array position: an app must be able to
+ * list its destinations in the order the product reads (Docket's is
+ * the pipeline) without that order deciding which one lights up.
+ *
+ * ## An external item is never current
+ *
+ * It is not a place inside this app, so no address the app is at can
+ * be it. Without this, an item pointing at `https://example.com/board`
+ * matches the app's own `/board` on a plain string compare.
+ */
+export const resolveActiveKey = (items, activeHref) => {
+    if (activeHref === undefined) {
+        return null;
+    }
+    let matchedItem = null;
+    let matchedLength = -1;
+    for (const item of items) {
+        if (item.isExternal === true) {
+            continue;
+        }
+        if (!getIsCurrentHref({
+            currentHref: activeHref,
+            href: item.href,
+        })) {
+            continue;
+        }
+        const candidateLength = toComparablePath(item.href).length;
+        if (candidateLength > matchedLength) {
+            matchedItem = item;
+            matchedLength = candidateLength;
+        }
+    }
+    return matchedItem === null
+        ? null
+        : getNavItemKey(matchedItem);
+};
+//# sourceMappingURL=navItems.js.map

package/dist/Nav/navItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navItems.js","sourceRoot":"","sources":["../../src/Nav/navItems.ts"],"names":[],"mappings":"AAsCA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAa,EAAU,EAAE,CACrD,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAU,EAAE;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAEzC,gEAAgE;IAChE,wDAAwD;IACxD,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC3D,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAC/B,WAAW,EACX,IAAI,GAML,EAAW,EAAE;IACZ,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAA;IAE7C,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;IAErC,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACpC,OAAO,OAAO,KAAK,MAAM,CAAA;IAC3B,CAAC;IAED,OAAO,CACL,OAAO,KAAK,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CACvD,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,KAAyB,EACzB,UAAmB,EACJ,EAAE;IACjB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,WAAW,GAAmB,IAAI,CAAA;IAEtC,IAAI,aAAa,GAAG,CAAC,CAAC,CAAA;IAEtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC7B,SAAQ;QACV,CAAC;QAED,IACE,CAAC,gBAAgB,CAAC;YAChB,WAAW,EAAE,UAAU;YACvB,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,EACF,CAAC;YACD,SAAQ;QACV,CAAC;QAED,MAAM,eAAe,GAAG,gBAAgB,CACtC,IAAI,CAAC,IAAI,CACV,CAAC,MAAM,CAAA;QAER,IAAI,eAAe,GAAG,aAAa,EAAE,CAAC;YACpC,WAAW,GAAG,IAAI,CAAA;YAElB,aAAa,GAAG,eAAe,CAAA;QACjC,CAAC;IACH,CAAC;IAED,OAAO,WAAW,KAAK,IAAI;QACzB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAA;AAChC,CAAC,CAAA"}

package/dist/Nav/useNavLayout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What the reader asked for, which is not the same as what they get.
+ *
+ * `auto` lets the width decide. The other two are a deliberate
+ * override and outrank the width — but only where a rail fits at
+ * all; see `useNavLayout`.
+ */
+export type NavLayoutMode = "auto" | "collapsed" | "expanded";
+/** The three forms a rail-shaped nav actually takes on screen. */
+export type ResolvedNavLayout = "menu" | "rail" | "railIcons";
+export type UseNavLayoutOptions = {
+    /**
+     * Below this width the rail drops its labels. Default `64rem`,
+     * which is `screen.lg`.
+     */
+    iconsBelow?: string;
+    /**
+     * Below this width there is no rail at all. Default `48rem`, which
+     * is `screen.md` — and the same step `Rail` itself collapses at,
+     * so the two cannot disagree.
+     */
+    menuBelow?: string;
+    /**
+     * Where the manual choice is remembered. Omit and the override
+     * lasts until the tab is closed.
+     *
+     * Name it for the app (`"queuepilot-nav"`), not for this library:
+     * two apps on the same origin share `localStorage`, and this
+     * fleet's dev servers all sit on `localhost`.
+     */
+    storageKey?: string;
+};
+export type NavLayoutState = {
+    /** `true` in `railIcons`. The rail's own collapse control reads it. */
+    isCollapsed: boolean;
+    /** What to pass to `Nav`'s `layout`. */
+    layout: ResolvedNavLayout;
+    mode: NavLayoutMode;
+    setMode: (mode: NavLayoutMode) => void;
+    /**
+     * Expanded ⇄ collapsed. From `auto` it goes to whichever of the two
+     * is **not** on screen now, so the first press always visibly does
+     * something — which "toggle" has to mean or the control reads as
+     * broken.
+     */
+    toggle: () => void;
+};
+/**
+ * The width rule for a rail-shaped navigation, written once.
+ *
+ * Three states, and the app chooses none of them:
+ *
+ * | Width | Layout | What the app renders |
+ * | --- | --- | --- |
+ * | `>= iconsBelow` | `rail` | a `Rail` holding a `Nav` |
+ * | `>= menuBelow` | `railIcons` | the same `Rail`, narrower |
+ * | below that | `menu` | a trigger in the `Header` |
+ *
+ * ### Why the app still places it
+ *
+ * Because the placement genuinely differs and the rule does not. The
+ * `menu` state puts a control in the header — a different corner of
+ * the page from a side rail — and no amount of restyling moves an
+ * element across `Shell`'s grid. So the library owns *which* state
+ * is right, at what width, with what override and where the override
+ * is remembered; the app owns two `if`s. That is the half that was
+ * being rewritten per app, and rewritten differently: Docket's nav
+ * wraps to three lines on a phone, mail-sifter collapses at `40rem`,
+ * and QueuePilot at `760px`, all of them arrived at alone.
+ *
+ * ### The override does not reach the narrow state
+ *
+ * `expanded` on a 390px screen would be a 212px rail beside 178px of
+ * content. The width wins there, and the remembered choice is *kept*
+ * rather than cleared — rotating a tablet back to landscape restores
+ * the rail the reader asked for, instead of silently forgetting it.
+ *
+ * ### It is a hook, not CSS
+ *
+ * The same reason `usePanelItemSize` is: a media query can restyle a
+ * rail, but it cannot move a control into the header, and it cannot
+ * tell the trigger whether to render at all. A resize re-renders;
+ * a scheme or density change still does not.
+ */
+export declare const useNavLayout: ({ iconsBelow, menuBelow, storageKey, }?: UseNavLayoutOptions) => NavLayoutState;
+//# sourceMappingURL=useNavLayout.d.ts.map

package/dist/Nav/useNavLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavLayout.d.ts","sourceRoot":"","sources":["../../src/Nav/useNavLayout.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,WAAW,GACX,UAAU,CAAA;AAEd,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,WAAW,CAAA;AAEf,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAA;IACpB,wCAAwC;IACxC,MAAM,EAAE,iBAAiB,CAAA;IACzB,IAAI,EAAE,aAAa,CAAA;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAA;IACtC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB,CAAA;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,YAAY,GAAI,yCAI1B,mBAAwB,KAAG,cAgD7B,CAAA"}