@charcuterie/ui 3.21.0 → 3.22.0

package/README.md

@@ -48,6 +48,17 @@ Moving a card takes **no drag-and-drop dependency**: one handle per card, a `Men
 other lanes as the primary path, Pointer-Event dragging at 1.4 KB gzip beside it
 ([decision](../../docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md)).
 
+**`DropRail` is the move control for a page `Board`'s `Menu` cannot serve.** A menu of the
+other lanes is right at three lanes; it is wrong at thirty-four groups, where it becomes a
+scrolling list inside a popup and a drag becomes a scroll with the button held down. The
+rail pins every destination to the top for the length of a move — no travel, nothing off
+screen — as a `listbox` driven by pointer, tap **or** the arrow keys, all committing through
+one `onPick`. It reads `event.buttons` to tell a drag from a tap, so a host says only
+whether a move is in flight. It holds the same line on dependencies: `elementFromPoint` over
+its own chips is the only geometry a rail needs. Not to be confused with `Rail`, the app
+shell's side landmark — `FileDropZone` is the precedent for the prefix carrying the
+distinction.
+
 **`BadgeButton` is a `Badge` you can press**, and it came from a consumer rather than from a
 plan: QueuePilot has six pill-shaped controls — per-entry setting tags, an Edit chip, two
 start-point chips, a group chip, a pool's Exclude chip — that were hand-rolled

package/dist/DropRail/DropRail.d.ts

@@ -0,0 +1,109 @@
+import type { ReactNode } from "react";
+export type DropRailTarget = {
+    /**
+     * A number after the label — a lane's size, a project's open
+     * count. Optional, and absent is a real answer: a rail of
+     * destinations that have no size should not print a zero on every
+     * chip.
+     */
+    count?: number;
+    /**
+     * Where the thing being moved already is. It stays **visible and
+     * unofferable** rather than being filtered out, because a rail
+     * whose contents change depending on what you grabbed is a rail
+     * whose chips move under the pointer between one move and the
+     * next — and muscle memory is the only reason this control is
+     * faster than a menu.
+     */
+    isCurrent?: boolean;
+    isDisabled?: boolean;
+    key: string;
+    label: string;
+    /** A leading glyph the app owns — an emoji, a dot, an icon. */
+    mark?: ReactNode;
+};
+export type DropRailProps = {
+    className?: string;
+    /**
+     * Whether the rail is showing. The host owns this, because only
+     * the host knows a move started — and it is the same boolean
+     * whether the move began as a pointer drag or as a tap on a
+     * handle.
+     */
+    isOpen: boolean;
+    /** The rail's accessible name. Required — it is a listbox. */
+    label: string;
+    onDismiss?: () => void;
+    onPick: (targetKey: string) => void;
+    targets: readonly DropRailTarget[];
+};
+/**
+ * Every destination at once, brought to the pointer instead of the
+ * pointer being carried to it.
+ *
+ * ### The measurement this exists for
+ *
+ * `Board` moves a card with a `Menu` on the card, and that is the
+ * right control for a board: three or four lanes, all on screen, and
+ * the menu opens where your hand already is. It stops being the
+ * right control at the size the fleet's real lists reach. Docket's
+ * Backlog draws **34 project groups down one page**, of which about
+ * four fit on a display. Dragging a card from the first to the
+ * thirty-fourth means holding a pointer down while the page scrolls,
+ * and a menu of 34 items is a scrolling list inside a popup — the
+ * same problem in a smaller box.
+ *
+ * A rail answers both. It pins to the top for the length of the
+ * move, so nothing is ever off screen, and there is no travel: every
+ * destination is the same short distance away.
+ *
+ * ### One control, three drivers, and that is the whole design
+ *
+ * WCAG 2.5.7 requires a single-pointer alternative to any dragging
+ * movement, and `FileDropZone` next door says the same thing about
+ * its own gesture: build the accessible path first and let the drag
+ * be the enhancement. So the rail is **not** a drag affordance with
+ * a fallback bolted on. It is a listbox that three things drive:
+ *
+ *  1. **Pointer.** While a button is held, the chip under the
+ *     pointer is active and releasing over it commits.
+ *  2. **Tap.** Opened with no button held, it is a list you touch.
+ *     Identical markup, identical commit.
+ *  3. **Keyboard.** Arrow keys walk it, Enter commits, Escape
+ *     abandons. `useRovingFocus` owns which chip is tabbable, so
+ *     there is no second keyboard model in this file to drift out of
+ *     step with `Listbox`.
+ *
+ * The rail does not know which of the three opened it, and the host
+ * does not have to say. It reads `event.buttons` on the first
+ * pointer event it sees: a button already down means a drag is in
+ * flight, and nothing else needs threading through.
+ *
+ * ### It takes no drag-and-drop dependency, and it hit-tests chips
+ *
+ * The board's decision priced four libraries and took none of them,
+ * because a published library's dependency list is inherited by
+ * every consumer — including one with 60 KB gzipped to spend in
+ * total. Nothing here changes that arithmetic, and this needs far
+ * less than `Board` does: a chip is a box under the pointer, so
+ * `elementFromPoint` answers the only geometric question there is.
+ * No snapshot, no collision strategy, no sortable transform.
+ *
+ * ### It is not `Rail`, and the two must not be confused
+ *
+ * `Rail` is the app shell's side rail — a landmark, an `<aside>` or
+ * a `<nav>`, permanent furniture down one edge of a page. This is a
+ * horizontal strip of drop targets that exists only for the length
+ * of a move, and it is a `listbox`. They share four letters and
+ * nothing else. `FileDropZone` sets the precedent for the prefix
+ * carrying the distinction.
+ *
+ * ### What it deliberately does not do
+ *
+ * It does not render the thing being dragged, own the handle, or
+ * know what a move means. The host keeps all three, which is what
+ * lets the same rail sit above a board, a card grid, or a list of
+ * accordions without any of them being modelled here.
+ */
+export declare const DropRail: ({ className, isOpen, label, onDismiss, onPick, targets, }: DropRailProps) => ReactNode;
+//# sourceMappingURL=DropRail.d.ts.map

package/dist/DropRail/DropRail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropRail.d.ts","sourceRoot":"","sources":["../../src/DropRail/DropRail.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CACnC,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,eAAO,MAAM,QAAQ,GAAI,2DAOtB,aAAa,KAAG,SAuWlB,CAAA"}

package/dist/DropRail/DropRail.js

@@ -0,0 +1,277 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useLatestRef, useRovingFocus, useUniqueId, } from "@charcuterie/logic";
+import { useEffect, useRef, useState } from "react";
+import { toClassName } from "../toClassName.js";
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.js";
+/**
+ * The attribute the pointer hit test reads. A `data-` attribute
+ * rather than a class, for the same reason `Board` marks its cards
+ * with one: a class is a style and may be renamed by a consumer's
+ * tooling, and this is a contract with a hit test.
+ */
+const TARGET_ATTRIBUTE = "data-drop-rail-target";
+const TARGET_SELECTOR = "[data-drop-rail-target]";
+/**
+ * Every destination at once, brought to the pointer instead of the
+ * pointer being carried to it.
+ *
+ * ### The measurement this exists for
+ *
+ * `Board` moves a card with a `Menu` on the card, and that is the
+ * right control for a board: three or four lanes, all on screen, and
+ * the menu opens where your hand already is. It stops being the
+ * right control at the size the fleet's real lists reach. Docket's
+ * Backlog draws **34 project groups down one page**, of which about
+ * four fit on a display. Dragging a card from the first to the
+ * thirty-fourth means holding a pointer down while the page scrolls,
+ * and a menu of 34 items is a scrolling list inside a popup — the
+ * same problem in a smaller box.
+ *
+ * A rail answers both. It pins to the top for the length of the
+ * move, so nothing is ever off screen, and there is no travel: every
+ * destination is the same short distance away.
+ *
+ * ### One control, three drivers, and that is the whole design
+ *
+ * WCAG 2.5.7 requires a single-pointer alternative to any dragging
+ * movement, and `FileDropZone` next door says the same thing about
+ * its own gesture: build the accessible path first and let the drag
+ * be the enhancement. So the rail is **not** a drag affordance with
+ * a fallback bolted on. It is a listbox that three things drive:
+ *
+ *  1. **Pointer.** While a button is held, the chip under the
+ *     pointer is active and releasing over it commits.
+ *  2. **Tap.** Opened with no button held, it is a list you touch.
+ *     Identical markup, identical commit.
+ *  3. **Keyboard.** Arrow keys walk it, Enter commits, Escape
+ *     abandons. `useRovingFocus` owns which chip is tabbable, so
+ *     there is no second keyboard model in this file to drift out of
+ *     step with `Listbox`.
+ *
+ * The rail does not know which of the three opened it, and the host
+ * does not have to say. It reads `event.buttons` on the first
+ * pointer event it sees: a button already down means a drag is in
+ * flight, and nothing else needs threading through.
+ *
+ * ### It takes no drag-and-drop dependency, and it hit-tests chips
+ *
+ * The board's decision priced four libraries and took none of them,
+ * because a published library's dependency list is inherited by
+ * every consumer — including one with 60 KB gzipped to spend in
+ * total. Nothing here changes that arithmetic, and this needs far
+ * less than `Board` does: a chip is a box under the pointer, so
+ * `elementFromPoint` answers the only geometric question there is.
+ * No snapshot, no collision strategy, no sortable transform.
+ *
+ * ### It is not `Rail`, and the two must not be confused
+ *
+ * `Rail` is the app shell's side rail — a landmark, an `<aside>` or
+ * a `<nav>`, permanent furniture down one edge of a page. This is a
+ * horizontal strip of drop targets that exists only for the length
+ * of a move, and it is a `listbox`. They share four letters and
+ * nothing else. `FileDropZone` sets the precedent for the prefix
+ * carrying the distinction.
+ *
+ * ### What it deliberately does not do
+ *
+ * It does not render the thing being dragged, own the handle, or
+ * know what a move means. The host keeps all three, which is what
+ * lets the same rail sit above a board, a card grid, or a list of
+ * accordions without any of them being modelled here.
+ */
+export const DropRail = ({ className, isOpen, label, onDismiss, onPick, targets, }) => {
+    const baseId = useUniqueId();
+    const railRef = useRef(null);
+    /**
+     * A pointer button was already down when the rail opened, so this
+     * move is a drag and it commits on release. A tap-opened rail
+     * commits on click instead, and the two must not both fire — a
+     * released drag also produces a `click`.
+     */
+    const isPointerDriven = useRef(false);
+    /**
+     * Focus is moved into the rail once per open, not once per render.
+     * Without the latch the effect below re-runs whenever the host
+     * re-renders and drags focus back to the first chip, which
+     * undoes every arrow key the moment anything above updates.
+     */
+    const hasTakenFocus = useRef(false);
+    const [announcement, setAnnouncement] = useState("");
+    const offerableKeys = targets
+        .filter((target) => !target.isCurrent && !target.isDisabled)
+        .map((target) => target.key);
+    /**
+     * The offerable keys as one string, because the effects below
+     * depend on *which* destinations are offerable and none of them
+     * may depend on the array's identity.
+     *
+     * `targets` is almost always a literal in the host's render, so
+     * the array is new on every render. An effect keyed on it
+     * re-registers every chip each time, and re-registering loses the
+     * active one — which during a keyboard walk means the arrow keys
+     * stop moving for no reason a consumer could ever debug.
+     */
+    const offerableKeysText = offerableKeys.join(" ");
+    const firstOfferableKey = offerableKeys[0];
+    const { activeValue, next, previous, register, setActiveValue, } = useRovingFocus({ isWrapping: true });
+    /**
+     * Read by the global listeners, which are registered once per
+     * open rather than once per render. Without them the pointer
+     * handler closes over a stale `activeValue`, and Enter commits
+     * whichever chip was active when the rail opened.
+     */
+    const activeValueRef = useLatestRef(activeValue);
+    const offerableKeysRef = useLatestRef(offerableKeys);
+    const onDismissRef = useLatestRef(onDismiss);
+    const onPickRef = useLatestRef(onPick);
+    const targetsRef = useLatestRef(targets);
+    useEffect(() => {
+        const releases = offerableKeysText
+            .split(" ")
+            .filter((key) => key !== "")
+            .map((key) => register(key));
+        return () => {
+            for (const release of releases) {
+                release();
+            }
+        };
+    }, [offerableKeysText, register]);
+    /**
+     * Closing resets everything a reopen must not inherit. Without it
+     * a rail reopened for a different card starts on whatever the last
+     * move chose, and the first arrow key moves from a place the
+     * person never went.
+     */
+    useEffect(() => {
+        if (isOpen) {
+            return;
+        }
+        setActiveValue(null);
+        isPointerDriven.current = false;
+        hasTakenFocus.current = false;
+        setAnnouncement("");
+    }, [isOpen, setActiveValue]);
+    useEffect(() => {
+        if (!isOpen) {
+            return undefined;
+        }
+        const commit = (targetKey) => {
+            const target = targetsRef.current.find((one) => one.key === targetKey);
+            if (target) {
+                setAnnouncement(`Moved to ${target.label}.`);
+            }
+            onPickRef.current(targetKey);
+        };
+        const getKeyAt = (clientX, clientY) => {
+            const chip = globalThis.document
+                .elementFromPoint(clientX, clientY)
+                ?.closest(TARGET_SELECTOR);
+            return chip?.getAttribute(TARGET_ATTRIBUTE) ?? null;
+        };
+        const getIsOfferable = (key) => key !== null && offerableKeysRef.current.includes(key);
+        const onPointerMove = (pointerEvent) => {
+            if (pointerEvent.buttons === 0) {
+                return;
+            }
+            isPointerDriven.current = true;
+            const key = getKeyAt(pointerEvent.clientX, pointerEvent.clientY);
+            // `null` when the pointer is between chips or off the rail
+            // entirely, and that has to clear the highlight. A rail that
+            // keeps the last chip lit is telling you it will land
+            // somewhere it will not.
+            setActiveValue(getIsOfferable(key) ? key : null);
+        };
+        const onPointerUp = (pointerEvent) => {
+            if (!isPointerDriven.current) {
+                return;
+            }
+            const key = getKeyAt(pointerEvent.clientX, pointerEvent.clientY);
+            if (getIsOfferable(key) && key !== null) {
+                commit(key);
+                return;
+            }
+            onDismissRef.current?.();
+        };
+        const onKeyDown = (keyEvent) => {
+            if (keyEvent.key === "Escape") {
+                keyEvent.preventDefault();
+                onDismissRef.current?.();
+                return;
+            }
+            if (keyEvent.key === "ArrowRight" ||
+                keyEvent.key === "ArrowDown") {
+                keyEvent.preventDefault();
+                next();
+                return;
+            }
+            if (keyEvent.key === "ArrowLeft" ||
+                keyEvent.key === "ArrowUp") {
+                keyEvent.preventDefault();
+                previous();
+                return;
+            }
+            const isCommitKey = keyEvent.key === "Enter" || keyEvent.key === " ";
+            if (isCommitKey && activeValueRef.current !== null) {
+                keyEvent.preventDefault();
+                commit(activeValueRef.current);
+            }
+        };
+        globalThis.addEventListener("pointermove", onPointerMove);
+        globalThis.addEventListener("pointerup", onPointerUp);
+        globalThis.addEventListener("keydown", onKeyDown);
+        return () => {
+            globalThis.removeEventListener("pointermove", onPointerMove);
+            globalThis.removeEventListener("pointerup", onPointerUp);
+            globalThis.removeEventListener("keydown", onKeyDown);
+        };
+    }, [
+        activeValueRef,
+        isOpen,
+        next,
+        offerableKeysRef,
+        onDismissRef,
+        onPickRef,
+        previous,
+        setActiveValue,
+        targetsRef,
+    ]);
+    /**
+     * Focus enters the rail only when a pointer is NOT driving it.
+     * Stealing focus mid-drag scrolls the page to the rail on some
+     * browsers, which is the one thing this control exists to avoid.
+     */
+    useEffect(() => {
+        if (!isOpen ||
+            isPointerDriven.current ||
+            hasTakenFocus.current ||
+            firstOfferableKey === undefined) {
+            return;
+        }
+        hasTakenFocus.current = true;
+        setActiveValue(firstOfferableKey);
+        railRef.current
+            ?.querySelector("[data-drop-rail-target]:not([aria-disabled='true'])")
+            ?.focus();
+    }, [firstOfferableKey, isOpen, setActiveValue]);
+    if (!isOpen) {
+        return null;
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-label": label, className: toClassName("sticky top-0 z-20 flex flex-wrap items-center gap-2 rounded-md border border-border-default bg-surface-overlay p-2 shadow-(--elevation-medium)", className), id: baseId, ref: railRef, role: "listbox", children: targets.map((target) => {
+                    const isOfferable = !target.isCurrent && !target.isDisabled;
+                    const isActive = isOfferable && activeValue === target.key;
+                    return (_jsxs("button", { "aria-disabled": isOfferable ? undefined : true, "aria-selected": isActive, className: toClassName("flex max-w-80 items-center gap-1.5 rounded-full border px-3 py-1 text-sm transition-colors duration-(--duration-fast) ease-standard", isOfferable
+                            ? "cursor-pointer border-border-default bg-surface-raised text-content-primary hover:bg-surface-sunken"
+                            : "cursor-not-allowed border-border-subtle bg-surface-sunken text-content-disabled", isActive &&
+                            "border-intent-accent-border bg-intent-accent-surface text-intent-accent-content outline-solid outline-(length:--focus-ring-width) outline-focus-ring"), "data-drop-rail-target": target.key, onClick: () => {
+                            // A released drag also fires a click. The pointer path
+                            // has already committed by then, so this guard is what
+                            // stops a drag committing twice.
+                            if (isPointerDriven.current ||
+                                !isOfferable) {
+                                return;
+                            }
+                            onPick(target.key);
+                        }, role: "option", tabIndex: isActive ? 0 : -1, type: "button", children: [target.mark === undefined ? null : (_jsx("span", { "aria-hidden": true, children: target.mark })), _jsx("span", { className: "truncate", children: target.label }), target.count === undefined ? null : (_jsx("span", { className: "text-content-secondary text-xs", children: target.count })), target.isCurrent ? (_jsx(VisuallyHidden, { children: "\u2014 where it is now" })) : null] }, target.key));
+                }) }), _jsx("output", { "aria-live": "polite", className: "sr-only", children: announcement })] }));
+};
+//# sourceMappingURL=DropRail.js.map

package/dist/DropRail/DropRail.js.map

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

package/dist/NavBar/NavBar.d.ts

@@ -0,0 +1,130 @@
+import type { ControlSize } from "@charcuterie/tokens";
+import type { Placement } from "@floating-ui/react";
+import type { ReactNode } from "react";
+export type NavBarItem = {
+    /**
+     * 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;
+    /** Defaults to `href`, which is already unique in a nav. */
+    key?: string;
+    /** The visible text, and the accessible name. */
+    label: string;
+};
+export type NavBarProps = {
+    className?: string;
+    /**
+     * Where the reader is — `useLocation().pathname` in a
+     * react-router app. `aria-current="page"` is derived from it by
+     * `getIsCurrentHref`, which matches a parent path for its
+     * children and treats `/` as exact.
+     *
+     * Omitted means nothing is current, which is the honest answer on
+     * a route no destination owns.
+     */
+    currentHref?: string;
+    /**
+     * **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.
+     */
+    isMenuVisible?: boolean;
+    items: readonly NavBarItem[];
+    /**
+     * Required, and it becomes the `<nav>`'s `aria-label`. Two unnamed
+     * navigation landmarks in one page is axe's `landmark-unique`, and
+     * more to the point it is a screen reader announcing "navigation"
+     * twice with no way to tell which is the main one.
+     */
+    label: string;
+    /**
+     * 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 collapsed trigger's glyph. **No default** — the library
+     * ships no icons, and `☰` 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;
+};
+/**
+ * The app's destinations as real links, in one line — folding into a
+ * single menu button, whole, when that line does not fit.
+ *
+ * ## Why this is not `Toolbar`
+ *
+ * `Toolbar` already solves collapse-into-an-overflow, and this
+ * component **reuses its measurement** (`useToolbarOverflow`) rather
+ * than growing a second one. What it cannot reuse is the rendering:
+ * a `ToolbarAction` is `{ label, onSelect }` and a collapsed one
+ * becomes a `MenuItem`, so a nav folded into a `Toolbar` is a row of
+ * `<button>`s. Navigation is an `<a href>` — see `NavBarLink`.
+ *
+ * The overflow is a `Popover` (`role="dialog"`) rather than a `Menu`
+ * for the same reason: `role="menu"` permits only the `menuitem`
+ * family, and a `menuitem` is something you *do*, not somewhere you
+ * *go*.
+ *
+ * ## It folds WHOLE, and that is the decision
+ *
+ * `Toolbar` collapses **progressively** — items drop off the end one
+ * at a time — because its items are ranked: the two things you do to
+ * a running job matter more than the two you do to the deck. A nav
+ * is not ranked. Its order is the shape of the product (Docket's
+ * reads as the pipeline: Triage → Backlog → Phases → Board →
+ * Archives), and a half-collapsed one splits that shape across two
+ * places with no rule the reader can learn — "some of the app is up
+ * here and the rest is behind a button" is worse than either whole
+ * answer. So the bar shows **every** destination or **none**, and
+ * the menu, when it opens, is the complete list in the product's own
+ * order.
+ *
+ * ## Measured, not breakpointed
+ *
+ * There is no `collapseAt` prop and no media query. The bar reads
+ * the width its links actually have and folds when their sum stops
+ * fitting, so a longer label, a tenth destination, a
+ * `data-density="kiosk"` or a reader at 175% browser zoom each move
+ * the fold on their own. A hardcoded pixel number is wrong the first
+ * time any of those changes — mux-magic collapses at `480px` and
+ * plex-channels at `760px`, and neither number has a reason.
+ *
+ * ⚠️ **The bar must not be sized by its own contents.** It measures
+ * its own box to decide what to draw in it, so a container that
+ * shrink-wraps makes the answer its own input: 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. Same trap `useAdaptiveColumns` documents from
+ * the other end.
+ *
+ * ## 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 declare const NavBar: ({ className, currentHref, isMenuVisible, items, label, menuAlign, menuIcon, menuLabel, menuPlacement, size, }: NavBarProps) => ReactNode;
+//# sourceMappingURL=NavBar.d.ts.map

package/dist/NavBar/NavBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavBar.d.ts","sourceRoot":"","sources":["../../src/NavBar/NavBar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWtC,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IAC5B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,MAAM,GAAI,+GAWpB,WAAW,KAAG,SAsHhB,CAAA"}