@charcuterie/ui 3.23.0 → 3.24.0

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":";AAGA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAsC,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAsC,CAAA;AA+BrE,MAAM,eAAe,GAAqC;IACxD,GAAG,EAAE,0FAA0F;IAC/F,iEAAiE;IACjE,8DAA8D;IAC9D,iEAAiE;IACjE,oBAAoB;IACpB,sEAAsE;IACtE,yCAAyC;IACzC,MAAM,EACJ,mHAAmH;IACrH,KAAK,EAAE,gDAAgD;IACvD,IAAI,EAAE,qCAAqC;IAC3C,kEAAkE;IAClE,kEAAkE;IAClE,kDAAkD;IAClD,SAAS,EACP,wEAAwE;CAC3E,CAAA;AAED;;;;;GAKG;AACH,MAAM,aAAa,GAAqC;IACtD,GAAG,EAAE,4DAA4D;IACjE,MAAM,EACJ,4DAA4D;IAC9D,KAAK,EACH,kEAAkE;IACpE,IAAI,EAAE,4DAA4D;IAClE,SAAS,EACP,4DAA4D;CAC/D,CAAA;AAED,MAAM,aAAa,GAAqC;IACtD,GAAG,EAAE,mFAAmF;IACxF,MAAM,EACJ,mFAAmF;IACrF,KAAK,EACH,4DAA4D;IAC9D,IAAI,EAAE,mFAAmF;IACzF,SAAS,EACP,mFAAmF;CACtF,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EACtB,SAAS,EACT,IAAI,EACJ,UAAU,EACV,SAAS,EACT,IAAI,EACJ,YAAY,GACC,EAAa,EAAE;IAC5B,MAAM,UAAU,GAAG,aAAa,EAAE,CAAA;IAElC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,KAAK,IAAI,CAAA;IAE3C,MAAM,WAAW,GACf,UAAU,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QACvC,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,UAAU,CAAA;IAEhB,MAAM,UAAU,GAAG,SAAS,KAAK,WAAW,CAAA;IAE5C,MAAM,SAAS,GACb,SAAS,KAAK,OAAO;QACnB,CAAC,CAAC,qBAAqB,CAAC,IAAI,CAAC;QAC7B,CAAC,CAAC,SAAS,KAAK,KAAK;YACnB,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC;YAC1B,CAAC,CAAC,SAAS,KAAK,MAAM;gBACpB,CAAC,CAAC,oGAAoG;gBACtG,CAAC,CAAC,EAAE,CAAA;IAEZ,OAAO,CACL,MAAC,WAAW;IACV,8DAA8D;IAC9D,0DAA0D;IAC1D,+DAA+D;IAC/D,2DAA2D;IAC3D,WAAW;wBACG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAC5C,SAAS,EAAE,WAAW,CACpB,yEAAyE,EACzE,eAAe,CAAC,SAAS,CAAC,EAC1B,SAAS;QACT,uDAAuD;QACvD,mDAAmD;QACnD,4DAA4D;QAC5D,sDAAsD;QACtD,4CAA4C;QAC5C,SAAS;YACP,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC;YAC1B,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,EAC5B,gBAAgB,CACjB,EACD,IAAI,EAAE,IAAI,CAAC,IAAI,EACf,OAAO,EAAE,CAAC,KAAoC,EAAE,EAAE;YAChD,IACE,KAAK,CAAC,gBAAgB;gBACtB,KAAK,CAAC,MAAM,KAAK,CAAC;gBAClB,KAAK,CAAC,MAAM;gBACZ,KAAK,CAAC,OAAO;gBACb,KAAK,CAAC,OAAO;gBACb,KAAK,CAAC,QAAQ,EACd,CAAC;gBACD,OAAM;YACR,CAAC;YAED,UAAU,EAAE,EAAE,CAAA;QAChB,CAAC,EACD,GAAG,EAAE,CAAC,OAAiC,EAAE,EAAE;YACzC,YAAY,EAAE,CAAC,OAAO,CAAC,CAAA;QACzB,CAAC;QACD,4DAA4D;QAC5D,2DAA2D;QAC3D,wDAAwD;QACxD,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS,EACnD,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QACzC,8DAA8D;QAC9D,2DAA2D;QAC3D,2DAA2D;QAC3D,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,aAEzC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAGhC,8BACc,MAAM,EAClB,SAAS,EAAC,sCAAsC,YAE/C,IAAI,CAAC,IAAI,GACL,CACR,EAEA,UAAU,CAAC,CAAC,CAAC,CACZ,KAAC,cAAc,cAAE,IAAI,CAAC,KAAK,GAAkB,CAC9C,CAAC,CAAC,CAAC,CAMF,eACE,SAAS,EACP,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,YAG7C,IAAI,CAAC,KAAK,GACN,CACR,EAEA,UAAU,CAAC,CAAC,CAAC,CACZ,KAAC,cAAc,uCAEE,CAClB,CAAC,CAAC,CAAC,IAAI,IACI,CACf,CAAA;AACH,CAAC,CAAA"}

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"}

package/dist/Nav/useNavLayout.js

@@ -0,0 +1,114 @@
+import { useMediaQuery } from "@charcuterie/logic";
+import { matchMediaMatcher } from "@charcuterie/logic/browser";
+import { useState } from "react";
+const DEFAULT_ICONS_BELOW = "64rem";
+const DEFAULT_MENU_BELOW = "48rem";
+const isNavLayoutMode = (value) => value === "auto" ||
+    value === "collapsed" ||
+    value === "expanded";
+/**
+ * `localStorage`, wrapped both ways.
+ *
+ * It throws in a sandboxed iframe and in some privacy modes, and it
+ * does not exist at all while a page renders on a server — a rail
+ * that cannot remember its width should still have one.
+ *
+ * `@charcuterie/logic/browser`'s `localStoragePersistence` is the
+ * same shape and is deliberately **not** reused: it validates what
+ * it reads with `isColorSchemeMode`, so it answers `null` for every
+ * value this hook stores.
+ */
+const readStoredMode = (key) => {
+    try {
+        const stored = window.localStorage.getItem(key);
+        return isNavLayoutMode(stored) ? stored : null;
+    }
+    catch {
+        return null;
+    }
+};
+const writeStoredMode = (key, mode) => {
+    try {
+        window.localStorage.setItem(key, mode);
+    }
+    catch {
+        // A page that cannot persist still switches for this session.
+    }
+};
+/**
+ * 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 const useNavLayout = ({ iconsBelow = DEFAULT_ICONS_BELOW, menuBelow = DEFAULT_MENU_BELOW, storageKey, } = {}) => {
+    // Read once, lazily — a `useState` initialiser, so the stored
+    // choice is in place for the first paint and the rail does not
+    // open wide and then snap shut.
+    const [mode, setStoredMode] = useState(() => (storageKey === undefined
+        ? null
+        : readStoredMode(storageKey)) ?? "auto");
+    const { isMatching: isBelowMenu } = useMediaQuery({
+        matcher: matchMediaMatcher(`(width < ${menuBelow})`),
+    });
+    const { isMatching: isBelowIcons } = useMediaQuery({
+        matcher: matchMediaMatcher(`(width < ${iconsBelow})`),
+    });
+    const setMode = (nextMode) => {
+        setStoredMode(nextMode);
+        if (storageKey !== undefined) {
+            writeStoredMode(storageKey, nextMode);
+        }
+    };
+    const autoLayout = isBelowIcons
+        ? "railIcons"
+        : "rail";
+    const layout = isBelowMenu
+        ? "menu"
+        : mode === "auto"
+            ? autoLayout
+            : mode === "collapsed"
+                ? "railIcons"
+                : "rail";
+    return {
+        isCollapsed: layout === "railIcons",
+        layout,
+        mode,
+        setMode,
+        toggle: () => {
+            setMode(layout === "rail" ? "collapsed" : "expanded");
+        },
+    };
+};
+//# sourceMappingURL=useNavLayout.js.map

package/dist/Nav/useNavLayout.js.map

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