@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/sidebar.d.ts

@@ -0,0 +1,257 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** The props the Sidebar accepts. */
+export interface SidebarProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * The controlled collapsed state.
+     *
+     * Pass it with `onCollapsedChange` when the rail's state has to survive a
+     * reload, which is the common case: a product that forgets the rail on every
+     * page load teaches a reader that collapsing it was a mistake.
+     */
+    collapsed?: boolean;
+    /** Whether the rail starts collapsed, for a rail nobody controls. @defaultValue false */
+    defaultCollapsed?: boolean;
+    /** Called with the state the rail is moving to, for a rail nobody controls. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * The rail's id, for a consumer that has to name it.
+     *
+     * A prop and not a generated one where it matters, for the reason
+     * `Collapsible`'s is: a rail a consumer cannot name from their own stylesheet
+     * or their own test is a rail they have to reach into the DOM to find. Omit it
+     * and one is generated, which is what the toggle points `aria-controls` at.
+     */
+    id?: string;
+    /** The rail's header, its navigation, its footer, and any control of its own. */
+    children?: ReactNode;
+}
+/** The props the SidebarHeader accepts. */
+export interface SidebarHeaderProps extends ComponentProps<'div'> {
+}
+/** The props the SidebarNav accepts. */
+export interface SidebarNavProps extends Omit<ComponentProps<'nav'>, 'children'> {
+    /**
+     * The accessible name of the navigation landmark.
+     *
+     * Required rather than defaulted, and it sits on the navigation rather than on
+     * the rail because a rail can hold more than one set of links: a product rail
+     * with a workspace switcher above the navigation and an account menu below it
+     * has two things a reader would otherwise hear as one list. The name is the
+     * caller's word, because a shared library cannot know whether the answer is
+     * "Sections", "Main" or "Navigation".
+     */
+    label: string;
+    /** The items, in the order a reader should meet them. */
+    children?: ReactNode;
+}
+/**
+ * The props the SidebarItem accepts.
+ *
+ * Deliberately not a pass-through of an element's props. An item is a link when
+ * it has an `href` and a button when it does not, and one interface that claimed
+ * to be both would let a consumer pass `target` to an element that is not a link
+ * and type-check it. The item takes the props below and nothing else; a consumer
+ * who needs a `data-*` attribute or a click handler on the element itself has an
+ * element of their own and does not need this one.
+ */
+export interface SidebarItemProps {
+    /**
+     * The name of the item: the words beside the icon, and the item's accessible
+     * name in every state.
+     *
+     * Required, and it is the whole answer to the collapsed rail. A rail collapses
+     * to icons, and an icon is not a name: a screen reader announces "link" once
+     * for each of them, and a sighted reader who cannot tell the marks apart has
+     * nothing to go on. So the words are always in the document, shown beside the
+     * icon while the rail is open and moved to `sr-only` while it is closed, and
+     * the name a reader hears is the same string in both states.
+     */
+    label: string;
+    /**
+     * Where the item goes.
+     *
+     * Omit it for an item that acts rather than navigates, and the item renders a
+     * button. A navigation rail in a real product holds both kinds: a "Billing"
+     * link and a "New project" that opens something. A Component that only drew
+     * anchors would leave the second kind to be hand-built, which is the gap this
+     * rail exists to close.
+     */
+    href?: string;
+    /**
+     * What the item does when it is activated.
+     *
+     * Required for an item with no `href`, because an item that acts rather than
+     * navigates renders a real button and a button that does nothing is a control
+     * a reader can find and press with no result, which is the same defect as a
+     * list that renders an empty item. On an item that has an `href` it runs
+     * alongside the navigation.
+     */
+    onClick?: () => void;
+    /**
+     * The mark at the leading edge. It is never the name.
+     *
+     * Pass a `ProductMark`, a `lucide-react` icon, or a node of your own. Whatever
+     * is passed is drawn in the item's own ink, so it takes the item's state
+     * rather than keeping a colour of its own.
+     */
+    icon?: ReactNode;
+    /**
+     * Whether this is the page the reader is on. @defaultValue false
+     *
+     * Marking the current item is the one thing a rail cannot leave to inference,
+     * and it is not a colour. The item is given `aria-current="page"`, which is
+     * what a reader is told and what a browser's find-in-page uses to find the
+     * current page, and it is given a rail down its leading edge, which is a shape
+     * a reader who cannot separate two surfaces can still see. Colour is the third
+     * signal and never the only one.
+     */
+    current?: boolean;
+    /**
+     * A trailing slot: a count, a status, a badge.
+     *
+     * It is `aria-hidden` and it is not drawn while the rail is collapsed. Both
+     * decisions are the same one: the item's accessible name is its `label` and
+     * nothing else, which is what makes the name in a collapsed rail the same name
+     * as the name in an open one. A 4rem rail has room for one mark and a badge
+     * beside it is a badge at four pixels, and a count a reader has to have is the
+     * count on the page the item leads to. A caller whose count is part of the
+     * item's meaning puts it in the `label`.
+     */
+    children?: ReactNode;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Prism does not decide what counts as
+     * external: a cross-origin destination is not by itself a reason for a new tab.
+     */
+    newTab?: boolean;
+    /** Layout only. */
+    className?: string;
+}
+/** The props the SidebarToggle accepts. */
+export interface SidebarToggleProps extends Omit<ComponentProps<'button'>, 'children'> {
+    /**
+     * The words for the control while the rail is open.
+     *
+     * Required, and it names the action rather than the control: a button a reader
+     * is told is called "Collapse sidebar" is a button that collapses the sidebar.
+     * The state is on `aria-expanded` as well, so a reader who meets the control
+     * without its words still learns whether the rail is open.
+     */
+    collapseLabel: string;
+    /** The words for the same control while the rail is collapsed. */
+    expandLabel: string;
+}
+/** The props the SidebarFooter accepts. */
+export interface SidebarFooterProps extends ComponentProps<'div'> {
+}
+/**
+ * A navigation rail with its own ink, its own focus ring, and a collapsed state.
+ *
+ * **It exists because the sidebar tokens were the one family in the contract
+ * with no consumer.** `sidebar` through `sidebar-ring` were published, gated in
+ * both modes and in every pack, and nothing in the package used them: the one
+ * rail the package had drew its surface from `border` and left its focus ring to
+ * `ring`, which is a different token on a different step. Those two are not
+ * interchangeable and the contract says why. `ring` is pinned to a step that
+ * clears 3:1 against the page ground, and the sidebar ground is one step off the
+ * page ground in either mode, so on Mint in light mode the page ring measures
+ * 2.86:1 against the rail while `sidebar-ring` measures 4.11:1. A rail that
+ * inherited the page ring was a focus indicator a reader could not see in one
+ * pack out of six, and it looked correct in the other five.
+ *
+ * **The collapsed state is the same rail at a smaller width, not a second
+ * Component.** An icon-only rail that dropped the hover surface, the focus ring
+ * or the current marking would be a worse version of the thing rather than a
+ * smaller one, and the reader who paid for the density paid for a rail that is
+ * harder to use. So the hover surface, the ring, the current rail and the
+ * accessible name are all present in both states, and only the words and the
+ * padding change. The name in particular: the words move to `sr-only` rather than
+ * leaving the document, so a collapsed rail is still six links a reader can hear
+ * and still six links a browser's find-in-page can find.
+ *
+ * **The ring is `sidebar-ring`, and this Component does not suppress the
+ * browser's own outline.** Every other focusable Component here suppresses it and
+ * draws `ring-ring` in its place. This one does not, for two reasons that point
+ * the same way. The ring it draws is a different role, and
+ * `check-focus-indicators.mjs` recognises exactly one ring role in the pattern it
+ * reads a full-strength ring from, so a Component that claimed to replace the
+ * outline here would be claiming a replacement the repository cannot currently
+ * verify. A wide navigation item is also the one place in this package where a
+ * second indicator costs nothing, and WCAG 2.4.11 asks that the focused control
+ * be identifiable rather than that exactly one thing identify it.
+ *
+ * **It is a client Component**, because the collapsed state is a state, and a
+ * state with no owner in this Component means every consumer writes the same
+ * `useState` and the same context around it. The toggle is a part rather than a
+ * built-in control, so a product puts it in the rail's header or its footer
+ * without the Component deciding where a rail's controls belong.
+ *
+ * **The rail animates `width` and not a transform, and this is the one place in
+ * this package that could not be moved.** `Progress` and `RangeField` both express
+ * their value as a `scaleX` about the inline start, because a bar and a band are
+ * shapes: scaling one squashes its own corner radius and nothing else, and both
+ * Components say so and accept the trade. A rail is not a shape. It carries a
+ * brand mark, a list of items with a 16px icon, the item's own label, and a
+ * trailing count, and a `scaleX` scales every one of them: the icons become ovals,
+ * the labels become condensed, and the counts are unreadable at exactly the moment
+ * the rail is moving. A transform cannot reflow text, which is the whole reason a
+ * rail is animated at all: at `scaleX(0.25)` the labels are still laid out for a
+ * 16rem column, so the rail's contents would never reflow into the 4rem column they
+ * are supposed to occupy. The property has to be the one that reflows them.
+ *
+ * So the rail keeps `transition-[width]` and is the named exception rather than an
+ * unexplained gap, and the cost is stated rather than argued away: it is a layout
+ * animation on the main thread, over a column that is one element with a small
+ * subtree, once per reader's click. That is a different order of cost from a bar
+ * that advances on every frame of a running job, which is why the two were not the
+ * same decision.
+ */
+declare function Sidebar({ collapsed: controlled, defaultCollapsed, onCollapsedChange, id, children, className, ...props }: SidebarProps): import("react").JSX.Element;
+/**
+ * The space at the top of the rail, for a brand or a workspace switcher.
+ *
+ * A slot and nothing more, because what sits in it is the product's: a mark, a
+ * switcher, a search field. The padding follows the rail's state, so a collapsed
+ * rail's mark is centred rather than hanging off the left edge of a 4rem column.
+ */
+declare function SidebarHeader({ className, ...props }: SidebarHeaderProps): import("react").JSX.Element;
+/** The navigation, as a named landmark, and the part of the rail that scrolls. */
+declare function SidebarNav({ label, className, children, ...props }: SidebarNavProps): import("react").JSX.Element;
+/**
+ * The space at the foot of the rail, for an account menu or a version.
+ *
+ * A slot above a rail's own border, and the border is the sidebar's, so the
+ * divider reads as part of the rail rather than as a rule drawn on the page.
+ */
+declare function SidebarFooter({ className, ...props }: SidebarFooterProps): import("react").JSX.Element;
+/**
+ * One item: an icon, its name, and the marking of the page the reader is on.
+ *
+ * An item is a link when it has an `href` and a button when it does not, because
+ * a rail holds both and a reader meets them the same way either way. The two
+ * renderings take the same class string, so an item that is a link on one route
+ * and a button on another does not change its hover surface, its ring or its
+ * current marking.
+ */
+declare function SidebarItem({ label, href, onClick, icon, current, children, newTab, className, }: SidebarItemProps): import("react").JSX.Element;
+/**
+ * The control that collapses and expands the rail.
+ *
+ * A part rather than something the rail draws, because where a rail's controls
+ * belong is the product's decision: a rail whose toggle is in its header fights
+ * a workspace switcher for the same row. It points at the rail by id, so the
+ * region it controls is the element the rail actually rendered rather than a name
+ * that has drifted from it.
+ *
+ * **`pointer-coarse:size-11` is the coarse-pointer floor, as a step.** A band was
+ * rejected on condition 1 for the same reason `dialog.tsx` rejects one: this control
+ * is the one thing in the rail's header row, so there is no neighbouring control for
+ * a band to reach, and there is no inset to overhang either. `SidebarHeader` is
+ * `p-3` open and `p-2` collapsed with no fixed height, so growing the toggle by
+ * twelve pixels grows the header by twelve and moves nothing. The collapsed rail is
+ * `w-16`, so a 44px control centred in it by `mx-auto` still has ten pixels of air on
+ * each side. See DESIGN.md, The coarse-pointer floor.
+ */
+declare function SidebarToggle({ collapseLabel, expandLabel, className, ...props }: SidebarToggleProps): import("react").JSX.Element;
+export { Sidebar, SidebarHeader, SidebarNav, SidebarItem, SidebarFooter, SidebarToggle };
+//# sourceMappingURL=sidebar.d.ts.map

package/dist/components/ui/sidebar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/sidebar.tsx"],"names":[],"mappings":"AAGA,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAmCd,qCAAqC;AACrC,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC3E;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAmB,SAAQ,cAAc,CAAC,KAAK,CAAC;CAAG;AAEpE,wCAAwC;AACxC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC9E;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACpF;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAmB,SAAQ,cAAc,CAAC,KAAK,CAAC;CAAG;AAkBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,iBAAS,OAAO,CAAC,EACf,SAAS,EAAE,UAAU,EACrB,gBAAwB,EACxB,iBAAiB,EACjB,EAAE,EACF,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,+BAmDd;AAED;;;;;;GAMG;AACH,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,+BASjE;AAED,kFAAkF;AAClF,iBAAS,UAAU,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,+BAgB5E;AAED;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,+BASjE;AAED;;;;;;;;GAQG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,OAAe,EACf,QAAQ,EACR,MAAM,EACN,SAAS,GACV,EAAE,gBAAgB,+BAgGlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,aAAa,CAAC,EACrB,aAAa,EACb,WAAW,EACX,SAAS,EACT,GAAG,KAAK,EACT,EAAE,kBAAkB,+BA2BpB;AAED,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,CAAA"}

package/dist/components/ui/sidebar.js

@@ -0,0 +1,205 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import { createContext, useContext, useId, useMemo, useState, } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * The default, for a part rendered outside a rail.
+ *
+ * Expanded, because a part outside a rail has no rail to be collapsed against,
+ * and a rail that starts collapsed because nobody said otherwise is a rail whose
+ * content a reader cannot see. The empty id means a toggle outside a rail points
+ * at nothing, which is honest: there is nothing there to point at.
+ */
+const SIDEBAR_STATE = {
+    collapsed: false,
+    id: '',
+    toggle: () => undefined,
+};
+const SidebarStateContext = createContext(SIDEBAR_STATE);
+/** The rail's state, from the rail above it. */
+function useSidebarState() {
+    return useContext(SidebarStateContext);
+}
+/**
+ * The fill and the ink an item takes, from the state it is in.
+ *
+ * Both halves are here because a fill and an inheritance are the same control on
+ * the page ground and a different one here. A `bg-sidebar-primary` with the rail's
+ * inherited ink would be `sidebar-primary` behind `sidebar-foreground`, which is
+ * neutral 900 behind neutral 900 in light mode. The token gate measures the pair
+ * it was given and cannot see which ink a class string failed to state.
+ */
+const ITEM_FILL = {
+    current: 'bg-sidebar-primary text-sidebar-primary-foreground',
+    // No fill at all rather than a transparent one: the rail's own surface is the
+    // surface here, and a `bg-transparent` would be a second statement of it.
+    rest: '',
+};
+/**
+ * A navigation rail with its own ink, its own focus ring, and a collapsed state.
+ *
+ * **It exists because the sidebar tokens were the one family in the contract
+ * with no consumer.** `sidebar` through `sidebar-ring` were published, gated in
+ * both modes and in every pack, and nothing in the package used them: the one
+ * rail the package had drew its surface from `border` and left its focus ring to
+ * `ring`, which is a different token on a different step. Those two are not
+ * interchangeable and the contract says why. `ring` is pinned to a step that
+ * clears 3:1 against the page ground, and the sidebar ground is one step off the
+ * page ground in either mode, so on Mint in light mode the page ring measures
+ * 2.86:1 against the rail while `sidebar-ring` measures 4.11:1. A rail that
+ * inherited the page ring was a focus indicator a reader could not see in one
+ * pack out of six, and it looked correct in the other five.
+ *
+ * **The collapsed state is the same rail at a smaller width, not a second
+ * Component.** An icon-only rail that dropped the hover surface, the focus ring
+ * or the current marking would be a worse version of the thing rather than a
+ * smaller one, and the reader who paid for the density paid for a rail that is
+ * harder to use. So the hover surface, the ring, the current rail and the
+ * accessible name are all present in both states, and only the words and the
+ * padding change. The name in particular: the words move to `sr-only` rather than
+ * leaving the document, so a collapsed rail is still six links a reader can hear
+ * and still six links a browser's find-in-page can find.
+ *
+ * **The ring is `sidebar-ring`, and this Component does not suppress the
+ * browser's own outline.** Every other focusable Component here suppresses it and
+ * draws `ring-ring` in its place. This one does not, for two reasons that point
+ * the same way. The ring it draws is a different role, and
+ * `check-focus-indicators.mjs` recognises exactly one ring role in the pattern it
+ * reads a full-strength ring from, so a Component that claimed to replace the
+ * outline here would be claiming a replacement the repository cannot currently
+ * verify. A wide navigation item is also the one place in this package where a
+ * second indicator costs nothing, and WCAG 2.4.11 asks that the focused control
+ * be identifiable rather than that exactly one thing identify it.
+ *
+ * **It is a client Component**, because the collapsed state is a state, and a
+ * state with no owner in this Component means every consumer writes the same
+ * `useState` and the same context around it. The toggle is a part rather than a
+ * built-in control, so a product puts it in the rail's header or its footer
+ * without the Component deciding where a rail's controls belong.
+ *
+ * **The rail animates `width` and not a transform, and this is the one place in
+ * this package that could not be moved.** `Progress` and `RangeField` both express
+ * their value as a `scaleX` about the inline start, because a bar and a band are
+ * shapes: scaling one squashes its own corner radius and nothing else, and both
+ * Components say so and accept the trade. A rail is not a shape. It carries a
+ * brand mark, a list of items with a 16px icon, the item's own label, and a
+ * trailing count, and a `scaleX` scales every one of them: the icons become ovals,
+ * the labels become condensed, and the counts are unreadable at exactly the moment
+ * the rail is moving. A transform cannot reflow text, which is the whole reason a
+ * rail is animated at all: at `scaleX(0.25)` the labels are still laid out for a
+ * 16rem column, so the rail's contents would never reflow into the 4rem column they
+ * are supposed to occupy. The property has to be the one that reflows them.
+ *
+ * So the rail keeps `transition-[width]` and is the named exception rather than an
+ * unexplained gap, and the cost is stated rather than argued away: it is a layout
+ * animation on the main thread, over a column that is one element with a small
+ * subtree, once per reader's click. That is a different order of cost from a bar
+ * that advances on every frame of a running job, which is why the two were not the
+ * same decision.
+ */
+function Sidebar({ collapsed: controlled, defaultCollapsed = false, onCollapsedChange, id, children, className, ...props }) {
+    const [internal, setInternal] = useState(defaultCollapsed);
+    const generated = useId();
+    // The controlled prop is the whole truth when there is one. A rail that wrote
+    // only its own state would show a state its parent had already overridden, and
+    // a rail whose parent later stops controlling it would jump to a state nobody
+    // chose.
+    const collapsed = controlled ?? internal;
+    const railId = id ?? generated;
+    const state = useMemo(() => ({
+        collapsed,
+        id: railId,
+        toggle: () => {
+            const following = !collapsed;
+            setInternal(following);
+            onCollapsedChange?.(following);
+        },
+    }), [collapsed, railId, onCollapsedChange]);
+    return (_jsx(SidebarStateContext.Provider, { value: state, children: _jsx("div", { "data-slot": "sidebar", id: railId, "data-collapsed": collapsed, className: cn('bg-sidebar text-sidebar-foreground border-sidebar-border flex shrink-0 flex-col self-stretch border-r', 
+            // The width is the state feedback, and it is the only motion on the
+            // rail: a rail that collapsed and looked identical teaches a reader
+            // that the control did nothing.
+            //
+            // `duration-slow` because this is a layout animation, which is the case
+            // `DESIGN.md`'s motion scale assigns `slow` to. The items in the rail
+            // stay on `duration-fast` for colour, because colour is the other case.
+            'transition-[width] duration-slow ease-out', collapsed ? 'w-16' : 'w-64', className), ...props, children: children }) }));
+}
+/**
+ * The space at the top of the rail, for a brand or a workspace switcher.
+ *
+ * A slot and nothing more, because what sits in it is the product's: a mark, a
+ * switcher, a search field. The padding follows the rail's state, so a collapsed
+ * rail's mark is centred rather than hanging off the left edge of a 4rem column.
+ */
+function SidebarHeader({ className, ...props }) {
+    const { collapsed } = useSidebarState();
+    return (_jsx("div", { "data-slot": "sidebar-header", className: cn(collapsed ? 'p-2' : 'p-3', className), ...props }));
+}
+/** The navigation, as a named landmark, and the part of the rail that scrolls. */
+function SidebarNav({ label, className, children, ...props }) {
+    const { collapsed } = useSidebarState();
+    return (_jsx("nav", { "data-slot": "sidebar-nav", "aria-label": label, className: cn('flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto', collapsed ? 'px-2' : 'px-3', className), ...props, children: children }));
+}
+/**
+ * The space at the foot of the rail, for an account menu or a version.
+ *
+ * A slot above a rail's own border, and the border is the sidebar's, so the
+ * divider reads as part of the rail rather than as a rule drawn on the page.
+ */
+function SidebarFooter({ className, ...props }) {
+    const { collapsed } = useSidebarState();
+    return (_jsx("div", { "data-slot": "sidebar-footer", className: cn('border-sidebar-border border-t', collapsed ? 'p-2' : 'p-3', className), ...props }));
+}
+/**
+ * One item: an icon, its name, and the marking of the page the reader is on.
+ *
+ * An item is a link when it has an `href` and a button when it does not, because
+ * a rail holds both and a reader meets them the same way either way. The two
+ * renderings take the same class string, so an item that is a link on one route
+ * and a button on another does not change its hover surface, its ring or its
+ * current marking.
+ */
+function SidebarItem({ label, href, onClick, icon, current = false, children, newTab, className, }) {
+    const { collapsed } = useSidebarState();
+    const classes = cn('text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground relative flex h-9 items-center rounded-md text-sm', 'transition-colors duration-fast ease-out', 
+    // The sidebar's own ring, on the sidebar's own ground. See the rail's own
+    // note: this is the one focusable surface in the package where the page ring
+    // measures below 3:1 in a real pack.
+    'focus-visible:ring-sidebar-ring focus-visible:ring-[3px]', collapsed ? 'justify-center px-0' : 'gap-2 px-3', ITEM_FILL[current ? 'current' : 'rest'], 
+    // Weight as the second channel for "current", so the marking survives a
+    // reader who cannot see the rail down the item's leading edge.
+    current && 'font-medium', className);
+    const content = (_jsxs(_Fragment, { children: [current ? (_jsx("span", { "data-slot": "sidebar-item-mark", "aria-hidden": "true", className: "bg-sidebar-primary absolute inset-y-1.5 left-0 w-0.5 rounded-full" })) : null, icon === undefined ? null : (_jsx("span", { "data-slot": "sidebar-item-icon", className: "flex size-4 shrink-0 items-center justify-center [&_svg]:size-4", children: icon })), _jsx("span", { "data-slot": "sidebar-item-label", className: cn(collapsed ? 'sr-only' : 'min-w-0 truncate'), children: label }), children === undefined || collapsed ? null : (_jsx("span", { "data-slot": "sidebar-item-trailing", "aria-hidden": "true", className: "ml-auto shrink-0 text-xs tabular-nums", children: children }))] }));
+    // An anchor with no `href` is not a link: it has no role and it is not
+    // focusable, so an item that acts rather than navigates has to be a real
+    // button or it is an element a keyboard cannot reach.
+    if (href === undefined) {
+        return (_jsx("button", { type: "button", "data-slot": "sidebar-item", "data-current": current ? 'true' : undefined, "aria-current": current ? 'page' : undefined, onClick: onClick, className: classes, children: content }));
+    }
+    return (_jsx("a", { "data-slot": "sidebar-item", "data-current": current ? 'true' : undefined, "aria-current": current ? 'page' : undefined, href: href, target: newTab ? '_blank' : undefined, rel: newTab ? 'noopener noreferrer' : undefined, onClick: onClick, className: classes, children: content }));
+}
+/**
+ * The control that collapses and expands the rail.
+ *
+ * A part rather than something the rail draws, because where a rail's controls
+ * belong is the product's decision: a rail whose toggle is in its header fights
+ * a workspace switcher for the same row. It points at the rail by id, so the
+ * region it controls is the element the rail actually rendered rather than a name
+ * that has drifted from it.
+ *
+ * **`pointer-coarse:size-11` is the coarse-pointer floor, as a step.** A band was
+ * rejected on condition 1 for the same reason `dialog.tsx` rejects one: this control
+ * is the one thing in the rail's header row, so there is no neighbouring control for
+ * a band to reach, and there is no inset to overhang either. `SidebarHeader` is
+ * `p-3` open and `p-2` collapsed with no fixed height, so growing the toggle by
+ * twelve pixels grows the header by twelve and moves nothing. The collapsed rail is
+ * `w-16`, so a 44px control centred in it by `mx-auto` still has ten pixels of air on
+ * each side. See DESIGN.md, The coarse-pointer floor.
+ */
+function SidebarToggle({ collapseLabel, expandLabel, className, ...props }) {
+    const { collapsed, id, toggle } = useSidebarState();
+    return (_jsx("button", { type: "button", "data-slot": "sidebar-toggle", "data-collapsed": collapsed, "aria-expanded": !collapsed, "aria-controls": id, "aria-label": collapsed ? expandLabel : collapseLabel, onClick: toggle, className: cn('text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-sidebar-ring focus-visible:ring-[3px] flex size-8 shrink-0 items-center justify-center rounded-md', 'transition-colors duration-fast ease-out', 'pointer-coarse:size-11', collapsed && 'mx-auto', className), ...props, children: collapsed ? (_jsx(PanelLeftOpen, { className: "size-4", "aria-hidden": "true" })) : (_jsx(PanelLeftClose, { className: "size-4", "aria-hidden": "true" })) }));
+}
+export { Sidebar, SidebarHeader, SidebarNav, SidebarItem, SidebarFooter, SidebarToggle };

package/dist/components/ui/signal-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/signal-field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAU,EACV,UAAU,EACV,KAAK,EACL,UAAiB,EACjB,KAAa,EACb,SAAS,GACV,EAAE,gBAAgB,+BA0ClB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"signal-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/signal-field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAU,EACV,UAAU,EACV,KAAK,EACL,UAAiB,EACjB,KAAa,EACb,SAAS,GACV,EAAE,gBAAgB,+BA2ClB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/signal-field.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The canvas the field draws into, in its own user units.
  *
@@ -72,6 +72,6 @@ function SignalField({ count = 28, emphasisAt, label, decorative = true, drift =
                     '--ambient-drift-x': `${(index % 2 === 0 ? 1 : -1) * (0.4 + (index % 5) * 0.15)}rem`,
                     '--ambient-drift-y': `${(index % 3 === 0 ? 1 : -1) * 0.35}rem`,
                 }
-                : undefined }))) }));
+                : undefined }, index))) }));
 }
 export { SignalField };

package/dist/components/ui/skeleton.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A placeholder surface that mirrors the shape of content while it loads.
  *

package/dist/components/ui/slider.d.ts

@@ -37,6 +37,13 @@ export interface SliderProps extends Omit<ComponentProps<'div'>, 'onChange'> {
  * ends. Give it an `aria-label` or a visible label. Use a Slider for a value
  * that is approximate and continuous; when the exact number matters, use an
  * Input of type number.
+ *
+ * The thumb is 16px for a mouse and a trackpad and takes the 44px coarse-pointer
+ * floor on touch input as a transparent band around itself, so the dot you see and
+ * the dot you grab are the same size on every pointer. A press inside the band
+ * drags the thumb from where it was rather than jumping the value to where you
+ * pressed, which is the trade the floor costs on a six pixel rail; the arrow keys
+ * and the range input behind the track still reach every value.
  */
 declare function Slider({ className, 'aria-label': ariaLabel, ...props }: SliderProps): import("react").JSX.Element;
 export { Slider };

package/dist/components/ui/slider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../../../src/components/ui/slider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC1E,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED;;;;;;;;GAQG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,GAAG,KAAK,EACT,EAAE,WAAW,+BAiCb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../../../src/components/ui/slider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC1E,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,GAAG,KAAK,EACT,EAAE,WAAW,+BAyDb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/slider.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Slider as SliderPrimitive } from '@base-ui/react/slider';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A control for choosing a number along a range.
  *
@@ -10,6 +10,13 @@ import { cn } from '../../lib/utils';
  * ends. Give it an `aria-label` or a visible label. Use a Slider for a value
  * that is approximate and continuous; when the exact number matters, use an
  * Input of type number.
+ *
+ * The thumb is 16px for a mouse and a trackpad and takes the 44px coarse-pointer
+ * floor on touch input as a transparent band around itself, so the dot you see and
+ * the dot you grab are the same size on every pointer. A press inside the band
+ * drags the thumb from where it was rather than jumping the value to where you
+ * pressed, which is the trade the floor costs on a six pixel rail; the arrow keys
+ * and the range input behind the track still reach every value.
  */
 function Slider({ className, 'aria-label': ariaLabel, ...props }) {
     return (_jsx(SliderPrimitive.Root, { "data-slot": "slider", className: cn('relative flex w-full touch-none items-center select-none', 'data-[orientation=vertical]:h-full data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col', 'data-[disabled]:opacity-50', className), ...props, children: _jsxs(SliderPrimitive.Control, { className: "flex w-full items-center data-[orientation=vertical]:h-full data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col", children: [_jsx(SliderPrimitive.Track, { className: "bg-muted relative grow overflow-hidden rounded-full data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5", children: _jsx(SliderPrimitive.Indicator, { className: "bg-primary absolute rounded-full data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full" }) }), _jsx(SliderPrimitive.Thumb, { "aria-label": ariaLabel, className: cn(
@@ -18,6 +25,30 @@ function Slider({ className, 'aria-label': ariaLabel, ...props }) {
                     // compliant ring and never sees that half strength fails 3:1. This thumb is
                     // the element the JSDoc above says stays focusable, so it is the one
                     // indicator a keyboard user has. See the comment on the Button's base class.
-                    'border-primary bg-background shadow-xs ring-ring block size-4 shrink-0 rounded-full border outline-none', 'transition-[color,box-shadow] duration-fast ease-out', 'hover:ring-4 focus-visible:ring-4', 'data-[disabled]:pointer-events-none') })] }) }));
+                    'border-primary bg-background shadow-xs ring-ring block size-4 shrink-0 rounded-full border outline-none', 
+                    // The 44px coarse-pointer floor, and here it is a band rather than a step.
+                    //
+                    // The two obvious steps are both wrong for a thumb. Growing the dot to 44px
+                    // puts a ball the size of a switch on a 6px track, and Base UI positions the
+                    // thumb with `left: <percent>%` plus a `translate`, so the value would not
+                    // move, but the drawing would: a slider whose handle is seven times the
+                    // thickness of its own rail reads as a different control. A band reaches the
+                    // same 44px with the 16px dot untouched.
+                    //
+                    // The band is safe here because nothing sits within fourteen pixels of a
+                    // thumb to be swallowed by it. It does overlap the track, and that is the
+                    // trade rather than an oversight: a press inside the band grabs the thumb and
+                    // drags it from where it was, where a press on the bare track 10px away would
+                    // have jumped the value to that point. On a coarse pointer the drag is the
+                    // model, a 6px rail cannot be tapped to a chosen value by anyone, and the
+                    // keyboard still reaches every value through the range input behind it.
+                    //
+                    // Nothing about the value maths moves, and that is a claim about Base UI
+                    // rather than about this class string. It reads the press offset from
+                    // `getMidpoint(thumb)`, and it computes the value from the control's own
+                    // `getBoundingClientRect()`, so a pseudo-element, which contributes to neither
+                    // box, cannot shift either. `slider.test.tsx` asserts that the value still
+                    // tracks a pointer press at a given coordinate.
+                    'transition-[color,box-shadow] duration-fast ease-out', 'hover:ring-4 focus-visible:ring-4', 'data-[disabled]:pointer-events-none', 'pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-[""]') })] }) }));
 }
 export { Slider };