@fairgarden/design 0.1.0-alpha.1 → 0.1.0-alpha.2

package/navigation/sidebar-nav/SidebarNav.js

@@ -0,0 +1,169 @@
+'use client';
+import * as React from 'react';
+import { Collapsible as BaseCollapsible } from '@base-ui/react/collapsible';
+import { cva } from 'class-variance-authority';
+import { DisclosureGlyph, disclosureGlyphHost } from '../../disclosure/collapsible';
+import { Link } from '../../actions/link';
+import { cx } from '../../utils/className';
+import { isCurrentPath } from '../../utils/navigation';
+import { primaryScaleVariants, secondaryScaleVariants } from '../../utils/scales';
+import { useScopeAttributes } from '../../utils/scope';
+import styles from './sidebar-nav.module.css';
+/*
+ * Sidebar Navigation (§9.15) [D202]: the docs layout's page tree, one
+ * component in the desktop column and inside the mobile drawer.
+ *
+ * Implementation (CSS Modules + CVA)
+ * - Module: sidebar-nav.module.css; CVA function `sidebarNav`.
+ * - Axes: `primary`, `secondary` → scales module classes.
+ * - Compound variants: none. Defaults: none; color axes none.
+ * - Color fallback: inherits the scope.
+ * - States: group headings are Link `kind="nav"` (bare text): `:hover` →
+ *   the --role-accent underline at --border-size-2 [D181];
+ *   `aria-current="page"` → the --border-size-2-25 underline and weight
+ *   700. Page links are Link `kind="nav"` with `list`: `:hover` →
+ *   --role-link-hover only (plus the underline where it is --primary12)
+ *   [D181]; `aria-current="page"` → the --border-size-2-25 start-edge bar
+ *   over the guide and weight 700, whose width every label reserves, so
+ *   the current page never rewraps a line. Collapsible Trigger
+ *   `data-panel-open` → the D109 glyph turns inward in --primary12; Panel
+ *   `data-starting-style` / `data-ending-style` → the clip reveal, instant
+ *   under --motionNotOK. `:focus-visible` → the ring, inset inside rows.
+ * - Parts: base (the nav), groups, group, headingRow, heading, toggle,
+ *   glyph, panel, list, item, link, label, labelText.
+ * - Scope: none. Container: none; its host (the docs layout's column or
+ *   the drawer's Scroll Area) sets its width.
+ * - Data: `items` is plain data ({ title, href, items }), so it can come
+ *   from the docs engine's sitemap (utils/docs `toSidebarItems`) or a CMS.
+ */
+export const sidebarNav = cva(styles.base, {
+    variants: {
+        // Color axes: never defaulted, so an omitted prop inherits the scope [D133].
+        primary: primaryScaleVariants,
+        secondary: secondaryScaleVariants,
+    },
+});
+const SidebarNavContext = React.createContext({
+    collapsible: false,
+    toggleLabel: (title) => `${title} pages`,
+});
+function isCurrent(item, currentPath) {
+    return item.current ?? isCurrentPath(item.href, currentPath);
+}
+/** Whether the item or any of its descendants is the current page. */
+function holdsCurrent(item, currentPath) {
+    if (isCurrent(item, currentPath))
+        return true;
+    return item.items?.some((child) => holdsCurrent(child, currentPath)) ?? false;
+}
+/** The nearest ancestor that scrolls its block axis (never the page itself). */
+function scrollParent(element) {
+    const root = element.ownerDocument.scrollingElement;
+    let node = element.parentElement;
+    while (node != null && node !== root && node !== element.ownerDocument.body) {
+        const { overflowY } = getComputedStyle(node);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && node.scrollHeight > node.clientHeight) {
+            return node;
+        }
+        node = node.parentElement;
+    }
+    return null;
+}
+/**
+ * The docs page tree [D202]: a `nav` of groups, each a caps heading
+ * (`type-label`, a link to the group's index page when it has one) over its
+ * pages on a --role-hairline guide, groups split by hairline rules. The
+ * current page takes `aria-current="page"`, the --border-size-2-25
+ * start-edge bar and weight 700. The same component, from the same data,
+ * fills the docs layout's column from --fgd-nav-inline-n-above and the
+ * drawer below it. On mount, and when the current page changes, the
+ * current link is scrolled into view inside the nearest scrolling
+ * ancestor (the column or the drawer's Scroll Area), never the page, so
+ * nothing moves around it. Hidden in print.
+ */
+export function SidebarNav(props) {
+    const { items, currentPath, label = 'Documentation', collapsible = false, toggleLabel = (title) => `${title} pages`, renderLink, primary, secondary, className, ref, ...rest } = props;
+    const scope = useScopeAttributes();
+    const navRef = React.useRef(null);
+    const setRef = React.useCallback((node) => {
+        navRef.current = node;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref]);
+    // Bring the current page into view inside the scroller that holds the
+    // nav, never the page. A scroll offset moves nothing in layout, so it is
+    // no layout shift; in the docs layout's column, browsers with
+    // `scroll-initial-target` (its CSS) have done it before first paint.
+    React.useLayoutEffect(() => {
+        const nav = navRef.current;
+        const link = nav?.querySelector('[aria-current="page"]');
+        if (nav == null || link == null)
+            return;
+        const scroller = scrollParent(link);
+        if (scroller == null)
+            return;
+        const box = scroller.getBoundingClientRect();
+        const target = link.getBoundingClientRect();
+        if (target.top >= box.top && target.bottom <= box.bottom)
+            return;
+        scroller.scrollTop += target.top - box.top - (box.height - target.height) / 2;
+    }, [currentPath]);
+    // Rebuilt on every render: the functions are usually inline, and the tree re-renders with it anyway.
+    const context = { currentPath, collapsible, toggleLabel, renderLink };
+    return (React.createElement(SidebarNavContext.Provider, { value: context },
+        React.createElement("nav", { ...rest, ...scope, ref: setRef, "aria-label": label, className: sidebarNav({ primary, secondary, className }) },
+            React.createElement("ul", { className: styles.groups }, items.map((item) => (React.createElement("li", { key: item.href ?? item.title, className: styles.group }, item.items != null && item.items.length > 0 ? (React.createElement(SidebarNavGroup, { item: item })) : (React.createElement(SidebarNavHeading, { item: item })))))))));
+}
+/** A group heading: a caps link to the group's index page, or plain caps text. */
+function SidebarNavHeading({ item, id }) {
+    const { currentPath, renderLink } = React.useContext(SidebarNavContext);
+    if (item.href == null) {
+        return (React.createElement("span", { id: id, className: styles.heading }, item.title));
+    }
+    const current = isCurrent(item, currentPath);
+    return (React.createElement(Link, { id: id, kind: "nav", href: item.href, render: renderLink?.(item.href), "aria-current": current ? 'page' : undefined, className: styles.heading },
+        React.createElement(Label, { text: item.title })));
+}
+/** A group: its heading over its pages, open (default) or a Collapsible. */
+function SidebarNavGroup({ item }) {
+    const { currentPath, collapsible, toggleLabel } = React.useContext(SidebarNavContext);
+    const headingId = React.useId();
+    const list = React.createElement(SidebarNavList, { items: item.items ?? [], labelledBy: headingId });
+    if (!collapsible) {
+        return (React.createElement(React.Fragment, null,
+            React.createElement(SidebarNavHeading, { item: item, id: headingId }),
+            list));
+    }
+    const containsCurrent = holdsCurrent(item, currentPath);
+    return (React.createElement(BaseCollapsible.Root, { defaultOpen: item.defaultOpen ?? containsCurrent, className: styles.collapsible },
+        item.href != null ? (React.createElement("div", { className: styles.headingRow },
+            React.createElement(SidebarNavHeading, { item: item, id: headingId }),
+            React.createElement(BaseCollapsible.Trigger, { "aria-label": toggleLabel(item.title), className: cx(styles.toggle, disclosureGlyphHost) },
+                React.createElement(DisclosureGlyph, { size: "chrome", className: styles.glyph })))) : (React.createElement(BaseCollapsible.Trigger, { id: headingId, className: cx(styles.headingRow, styles.headingTrigger) },
+            React.createElement("span", { className: styles.heading }, item.title),
+            React.createElement(DisclosureGlyph, { size: "chrome", className: styles.glyph }))),
+        React.createElement(BaseCollapsible.Panel, { className: styles.panel }, list)));
+}
+/** A list of pages on the hairline guide; a page's subpages nest one level in. */
+function SidebarNavList({ items, labelledBy, }) {
+    const { currentPath, renderLink } = React.useContext(SidebarNavContext);
+    return (React.createElement("ul", { className: styles.list, "aria-labelledby": labelledBy }, items.map((item) => {
+        const current = isCurrent(item, currentPath);
+        return (React.createElement("li", { key: item.href ?? item.title, className: styles.item },
+            item.href != null ? (React.createElement(Link, { kind: "nav", list: true, href: item.href, render: renderLink?.(item.href), "aria-current": current ? 'page' : undefined, className: styles.link },
+                React.createElement(Label, { text: item.title }))) : (React.createElement("span", { className: cx(styles.link, styles.plain) },
+                React.createElement(Label, { text: item.title }))),
+            item.items != null && item.items.length > 0 ? React.createElement(SidebarNavList, { items: item.items }) : null));
+    })));
+}
+/**
+ * A label that reserves its weight-700 box: a hidden copy at weight 700
+ * shares its grid cell, so becoming current never widens or rewraps it.
+ */
+function Label({ text }) {
+    return (React.createElement("span", { className: styles.label, "data-label": text },
+        React.createElement("span", { className: styles.labelText }, text)));
+}
+//# sourceMappingURL=SidebarNav.js.map

package/navigation/sidebar-nav/SidebarNav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarNav.js","sourceRoot":"","sources":["../../src/navigation/sidebar-nav/SidebarNav.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC3E,OAAO,EAAE,GAAG,EAAqB,MAAM,0BAA0B,CAAA;AAEjE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AACnF,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;IACzC,QAAQ,EAAE;QACR,6EAA6E;QAC7E,OAAO,EAAE,oBAAoB;QAC7B,SAAS,EAAE,sBAAsB;KAClC;CACF,CAAC,CAAA;AA8DF,MAAM,iBAAiB,GAAG,KAAK,CAAC,aAAa,CAAyB;IACpE,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,QAAQ;CACzC,CAAC,CAAA;AAEF,SAAS,SAAS,CAAC,IAAoB,EAAE,WAA+B;IACtE,OAAO,IAAI,CAAC,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;AAC9D,CAAC;AAED,sEAAsE;AACtE,SAAS,YAAY,CAAC,IAAoB,EAAE,WAA+B;IACzE,IAAI,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7C,OAAO,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,IAAI,KAAK,CAAA;AAC/E,CAAC;AAED,gFAAgF;AAChF,SAAS,YAAY,CAAC,OAAoB;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAA;IACnD,IAAI,IAAI,GAAG,OAAO,CAAC,aAAa,CAAA;IAChC,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QAC5E,MAAM,EAAE,SAAS,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC5C,IAAI,CAAC,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAC9F,OAAO,IAAI,CAAA;QACb,CAAC;QACD,IAAI,GAAG,IAAI,CAAC,aAAa,CAAA;IAC3B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,EACJ,KAAK,EACL,WAAW,EACX,KAAK,GAAG,eAAe,EACvB,WAAW,GAAG,KAAK,EACnB,WAAW,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,KAAK,QAAQ,EACjD,UAAU,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,GAAG,EACH,GAAG,IAAI,EACR,GAAG,KAAK,CAAA;IAET,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAqB,IAAI,CAAC,CAAA;IAErD,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAC9B,CAAC,IAAwB,EAAE,EAAE;QAC3B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;QACrB,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,GAAG,CAAC,IAAI,CAAC,CAAA;aACnC,IAAI,GAAG;YAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;IAClC,CAAC,EACD,CAAC,GAAG,CAAC,CACN,CAAA;IAED,sEAAsE;IACtE,yEAAyE;IACzE,8DAA8D;IAC9D,qEAAqE;IACrE,KAAK,CAAC,eAAe,CAAC,GAAG,EAAE;QACzB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAA;QAC1B,MAAM,IAAI,GAAG,GAAG,EAAE,aAAa,CAAc,uBAAuB,CAAC,CAAA;QACrE,IAAI,GAAG,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;YAAE,OAAM;QACvC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,QAAQ,IAAI,IAAI;YAAE,OAAM;QAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,qBAAqB,EAAE,CAAA;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAA;QAC3C,IAAI,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM;YAAE,OAAM;QAChE,QAAQ,CAAC,SAAS,IAAI,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC/E,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAA;IAEjB,qGAAqG;IACrG,MAAM,OAAO,GAA2B,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA;IAE7F,OAAO,CACL,oBAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO;QACxC,gCACM,IAAI,KACJ,KAAK,EACT,GAAG,EAAE,MAAM,gBACC,KAAK,EACjB,SAAS,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;YAExD,4BAAI,SAAS,EAAE,MAAM,CAAC,MAAM,IACzB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACnB,4BAAI,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,IACtD,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAC7C,oBAAC,eAAe,IAAC,IAAI,EAAE,IAAI,GAAI,CAChC,CAAC,CAAC,CAAC,CACF,oBAAC,iBAAiB,IAAC,IAAI,EAAE,IAAI,GAAI,CAClC,CACE,CACN,CAAC,CACC,CACD,CACqB,CAC9B,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE,EAAyC;IAC5E,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAA;IACvE,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;QACtB,OAAO,CACL,8BAAM,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,IACpC,IAAI,CAAC,KAAK,CACN,CACR,CAAA;IACH,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IAC5C,OAAO,CACL,oBAAC,IAAI,IACH,EAAE,EAAE,EAAE,EACN,IAAI,EAAC,KAAK,EACV,IAAI,EAAE,IAAI,CAAC,IAAI,EACf,MAAM,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,kBACjB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAC1C,SAAS,EAAE,MAAM,CAAC,OAAO;QAEzB,oBAAC,KAAK,IAAC,IAAI,EAAE,IAAI,CAAC,KAAK,GAAI,CACtB,CACR,CAAA;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,eAAe,CAAC,EAAE,IAAI,EAA4B;IACzD,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAA;IACrF,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,EAAE,CAAA;IAC/B,MAAM,IAAI,GAAG,oBAAC,cAAc,IAAC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,UAAU,EAAE,SAAS,GAAI,CAAA;IAE/E,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,CACL;YACE,oBAAC,iBAAiB,IAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,GAAI;YAC/C,IAAI,CACJ,CACJ,CAAA;IACH,CAAC;IAED,MAAM,eAAe,GAAG,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IACvD,OAAO,CACL,oBAAC,eAAe,CAAC,IAAI,IAAC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,eAAe,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW;QAClG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CACnB,6BAAK,SAAS,EAAE,MAAM,CAAC,UAAU;YAC/B,oBAAC,iBAAiB,IAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,GAAI;YAChD,oBAAC,eAAe,CAAC,OAAO,kBACV,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EACnC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC;gBAEjD,oBAAC,eAAe,IAAC,IAAI,EAAC,QAAQ,EAAC,SAAS,EAAE,MAAM,CAAC,KAAK,GAAI,CAClC,CACtB,CACP,CAAC,CAAC,CAAC,CACF,oBAAC,eAAe,CAAC,OAAO,IAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,cAAc,CAAC;YAC7F,8BAAM,SAAS,EAAE,MAAM,CAAC,OAAO,IAAG,IAAI,CAAC,KAAK,CAAQ;YACpD,oBAAC,eAAe,IAAC,IAAI,EAAC,QAAQ,EAAC,SAAS,EAAE,MAAM,CAAC,KAAK,GAAI,CAClC,CAC3B;QACD,oBAAC,eAAe,CAAC,KAAK,IAAC,SAAS,EAAE,MAAM,CAAC,KAAK,IAAG,IAAI,CAAyB,CACzD,CACxB,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,cAAc,CAAC,EACtB,KAAK,EACL,UAAU,GAIX;IACC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAA;IACvE,OAAO,CACL,4BAAI,SAAS,EAAE,MAAM,CAAC,IAAI,qBAAmB,UAAU,IACpD,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAClB,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;QAC5C,OAAO,CACL,4BAAI,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI;YACrD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CACnB,oBAAC,IAAI,IACH,IAAI,EAAC,KAAK,EACV,IAAI,QACJ,IAAI,EAAE,IAAI,CAAC,IAAI,EACf,MAAM,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,kBACjB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAC1C,SAAS,EAAE,MAAM,CAAC,IAAI;gBAEtB,oBAAC,KAAK,IAAC,IAAI,EAAE,IAAI,CAAC,KAAK,GAAI,CACtB,CACR,CAAC,CAAC,CAAC,CACF,8BAAM,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC;gBAC5C,oBAAC,KAAK,IAAC,IAAI,EAAE,IAAI,CAAC,KAAK,GAAI,CACtB,CACR;YACA,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAC,cAAc,IAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAI,CAAC,CAAC,CAAC,IAAI,CACxF,CACN,CAAA;IACH,CAAC,CAAC,CACC,CACN,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,KAAK,CAAC,EAAE,IAAI,EAAoB;IACvC,OAAO,CACL,8BAAM,SAAS,EAAE,MAAM,CAAC,KAAK,gBAAc,IAAI;QAC7C,8BAAM,SAAS,EAAE,MAAM,CAAC,SAAS,IAAG,IAAI,CAAQ,CAC3C,CACR,CAAA;AACH,CAAC"}

package/navigation/sidebar-nav/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SidebarNav';
+//# sourceMappingURL=index.d.ts.map

package/navigation/sidebar-nav/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/sidebar-nav/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/navigation/sidebar-nav/index.js

@@ -0,0 +1,2 @@
+export * from './SidebarNav';
+//# sourceMappingURL=index.js.map

package/navigation/sidebar-nav/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/sidebar-nav/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/navigation/sidebar-nav/sidebar-nav.module.css

@@ -0,0 +1,270 @@
+/*
+ * Sidebar Navigation (§9.15). CVA function `sidebarNav` in SidebarNav.tsx.
+ *
+ * Parts: base (the nav), groups, group, collapsible, headingRow,
+ * headingTrigger, heading, toggle, glyph (the Collapsible module's D109
+ * glyph), panel, list, item, link, plain, label, labelText.
+ *
+ * Line-based [D202]: groups split by --role-hairline rules; pages hang on a
+ * --border-size-1 --role-hairline guide at the list's start edge; the
+ * current page draws the --border-size-2-25 --primary12 bar over the guide.
+ * No fills, no shadows. Colors are role variables only; there are no local
+ * custom properties.
+ */
+
+/* Composition sits in top-level rules, outside the layers: Lightning CSS
+ * (Next.js with Turbopack) rejects `composes` inside @layer or any nesting.
+ * The composed classes keep their own layers. */
+.heading {
+  composes: typeLabel from '../../utils/type.module.css';
+}
+
+.link {
+  composes: typeBodyUi from '../../utils/type.module.css';
+}
+
+@layer base {
+  .base {
+    display: block;
+    min-inline-size: 0;
+  }
+
+  .groups,
+  .list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .group,
+  .item,
+  .collapsible {
+    display: block;
+  }
+
+  /* Groups split by a hairline rule, --size-px-3 on either side [§4.4]. */
+  .group + .group {
+    margin-block-start: var(--size-px-3);
+    padding-block-start: var(--size-px-3);
+    border-block-start: var(--border-size-1) solid var(--role-hairline);
+  }
+
+  /* The caps heading (type-label, caps wayfinding [D165]): a 44 px row. */
+  .heading {
+    display: flex;
+    align-items: center;
+    box-sizing: border-box;
+    min-block-size: var(--fgd-size-hit);
+    margin: 0;
+    color: var(--primary12);
+  }
+
+  /* A collapsible group's row: the heading, then its toggle at the end. */
+  .headingRow {
+    display: flex;
+    align-items: center;
+    gap: var(--size-px-2);
+  }
+
+  .headingRow > .heading {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+
+  /* A group without a page: the whole row is the toggle. */
+  .headingTrigger {
+    box-sizing: border-box;
+    inline-size: 100%;
+    min-block-size: var(--fgd-size-hit);
+    margin: 0;
+    padding: 0;
+    border: 0;
+    border-radius: var(--radius-1);
+    background: none;
+    color: var(--primary12);
+    text-align: start;
+    cursor: pointer;
+    appearance: none;
+  }
+
+  .headingTrigger > .heading {
+    flex: 1 1 auto;
+    text-decoration-color: var(--role-accent);
+    text-decoration-thickness: var(--border-size-2);
+    text-underline-offset: var(--size-px-1);
+  }
+
+  /* The glyph-only toggle: a 44 px square, the glyph at the chrome tier. */
+  .toggle {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    inline-size: var(--fgd-size-hit);
+    block-size: var(--fgd-size-hit);
+    margin: 0;
+    margin-inline-end: calc(-1 * var(--size-px-3));
+    padding: 0;
+    border: 0;
+    border-radius: var(--radius-1);
+    background: none;
+    color: var(--primary12);
+    cursor: pointer;
+    appearance: none;
+  }
+
+  .glyph {
+    flex: none;
+  }
+
+  /* The clip reveal (§1.5.15) [D91]: the panel wipes open; never faded. */
+  .panel {
+    block-size: var(--collapsible-panel-height);
+    overflow: hidden;
+    overflow: clip;
+  }
+
+  /* Pages hang on a --border-size-1 hairline guide at the list's start edge. */
+  .list {
+    border-inline-start: var(--border-size-1) solid var(--role-hairline);
+  }
+
+  /* Subpages: one level in, on their own guide. */
+  .list .list {
+    margin-inline-start: var(--size-px-3);
+  }
+
+  /* A page: type-body-ui at weight 400, a 44 px row, --size-px-3 off the guide. */
+  .link {
+    position: relative;
+    display: flex;
+    align-items: center;
+    box-sizing: border-box;
+    min-block-size: var(--fgd-size-hit);
+    padding-block: var(--size-px-2);
+    padding-inline: var(--size-px-3) 0;
+    color: var(--primary12);
+    text-decoration-line: none;
+  }
+
+  .plain {
+    color: var(--role-muted);
+  }
+
+  /* The current bar, over the guide: a border, so it survives forced colors. */
+  .link::before {
+    content: '';
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: calc(-1 * var(--border-size-1));
+    border-inline-start: 0 solid var(--primary12);
+    pointer-events: none;
+  }
+
+  /*
+   * The label reserves its weight-700 box: a hidden copy of its words at
+   * --font-weight-7 (`data-label`) shares the one grid cell, so the cell is
+   * always the bold setting's size and the current page never widens or
+   * rewraps a line (no layout shift on navigation or scrollspy).
+   */
+  .label {
+    display: grid;
+    min-inline-size: 0;
+  }
+
+  .label::after {
+    content: attr(data-label);
+    grid-area: 1 / 1;
+    font-weight: var(--font-weight-7);
+    visibility: hidden;
+    pointer-events: none;
+    user-select: none;
+  }
+
+  .labelText {
+    grid-area: 1 / 1;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .panel {
+      transition-property: block-size;
+      transition-duration: var(--fgd-duration-disclosure);
+      transition-timing-function: var(--ease-out-3);
+    }
+  }
+}
+
+@layer compounds {
+  /* Page links fill their row: a block flex box, over Link's inline `nav` row. */
+  .link {
+    display: flex;
+  }
+
+  /* Headings: a flex row over Link's inline `nav` row, the text's own 44 px. */
+  .heading {
+    display: flex;
+  }
+}
+
+@layer states {
+  /* The whole-row toggle: the bare-text underline on its words [D181]. */
+  .headingTrigger:hover > .heading {
+    text-decoration-line: underline;
+  }
+
+  .toggle:active,
+  .headingTrigger:active {
+    background-color: var(--primary12);
+    color: var(--role-inverse);
+  }
+
+  .toggle:active .glyph {
+    color: var(--role-inverse);
+  }
+
+  .toggle:focus-visible,
+  .headingTrigger:focus-visible {
+    outline: var(--border-size-2) solid var(--primary12);
+    outline-offset: calc(-1 * var(--border-size-2));
+  }
+
+  /* Rows: the ring inset inside the row (the list parent raises it over Link's ring). */
+  .list .link:focus-visible,
+  .group > .heading:focus-visible,
+  .headingRow > .heading:focus-visible {
+    outline: var(--border-size-2) solid var(--primary12);
+    outline-offset: calc(-1 * var(--border-size-2));
+  }
+
+  /* Current page: the --border-size-2-25 start-edge bar and weight 700 [D15]. */
+  .list .link[aria-current='page']::before {
+    border-inline-start-width: var(--border-size-2-25);
+  }
+
+  /* The bar replaces Link's current underline on a page (the list parent raises this over Link's rule). */
+  .list .link[aria-current='page'] {
+    font-weight: var(--font-weight-7);
+    text-decoration-line: none;
+  }
+
+  .panel[data-starting-style],
+  .panel[data-ending-style] {
+    block-size: 0;
+  }
+
+  @media (forced-colors: active) {
+    .headingTrigger:hover > .heading {
+      text-decoration-line: underline;
+    }
+  }
+}
+
+@layer print {
+  @media print {
+    /* Screen wayfinding: the page prints alone (§7.7). */
+    .base {
+      display: none;
+    }
+  }
+}

package/navigation/table-of-contents/TableOfContents.d.ts

@@ -0,0 +1,92 @@
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+export declare const tableOfContents: (props?: ({
+    kind?: "bar" | "list" | null | undefined;
+    primary?: "ruby" | "brown" | "crimson" | "gold" | "gray" | "indigo" | "olive" | "pink" | "plum" | "purple" | "red" | "tomato" | "violet" | "bronze" | "iris" | "mauve" | "sage" | "sand" | "slate" | null | undefined;
+    secondary?: "ruby" | "blue" | "brown" | "crimson" | "cyan" | "gold" | "gray" | "green" | "indigo" | "lime" | "olive" | "orange" | "pink" | "plum" | "purple" | "red" | "teal" | "tomato" | "violet" | "yellow" | "amber" | "bronze" | "grass" | "iris" | "jade" | "mauve" | "mint" | "sage" | "sand" | "sky" | "slate" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type TableOfContentsVariants = VariantProps<typeof tableOfContents>;
+/** How the contents draw: the full list, or the compact bar that opens it. */
+export type TableOfContentsKind = NonNullable<TableOfContentsVariants['kind']>;
+/** Heading levels the list shows: H2 at its top level, H3 and H4 nested under it. */
+export type TableOfContentsLevel = 2 | 3 | 4;
+/** One heading on the page. */
+export interface TableOfContentsItem {
+    /** The heading's `id`: the entry links to `#id`. */
+    id: string;
+    /** The heading's text. */
+    title: string;
+    /** The heading level: 2, 3 or 4. */
+    level: TableOfContentsLevel;
+}
+/**
+ * What a host tells the contents inside it. The docs layout sets
+ * `kind: 'bar'` where it pins the compact bar (below --xl-n-above), so
+ * the one `toc` it is given draws as the column there and as the bar here.
+ */
+export interface TableOfContentsContextValue {
+    /** The kind to draw when the component names none. */
+    kind?: TableOfContentsKind;
+    /** Hides the list's visible heading; it stays the landmark's name. */
+    labelHidden?: boolean;
+}
+/** Provided by a host of the contents, such as the docs layout. */
+export declare const TableOfContentsContext: React.Context<TableOfContentsContextValue>;
+/** Props for TableOfContents: `nav` props, the headings, the section in view, the kind and the color axes. */
+export type TableOfContentsProps = Omit<React.ComponentPropsWithRef<'nav'>, 'children'> & {
+    /** The page's headings in order, levels 2–4 (a level-3 nests under the level-2 before it). */
+    items: readonly TableOfContentsItem[];
+    /**
+     * The id of the section in view: its entry takes `aria-current="location"`,
+     * and the bar names it. Pass `useActiveHeading(ids)` for scrollspy.
+     * Omitted, no entry is marked and the bar names the first section.
+     */
+    activeId?: string;
+    /** The visible heading (the bar's label) and the landmark's name. Default "On this page". */
+    label?: string;
+    /**
+     * `list` (default): the full list. `bar`: one line naming the section in
+     * view, which opens the list in an anchored panel. Omitted, a host's
+     * `TableOfContentsContext` may set it (the docs layout does).
+     */
+    kind?: TableOfContentsVariants['kind'];
+    /**
+     * With `kind="bar"`: the outline morph, the bar's ring or edge growing
+     * into the panel's frame on open and back on close [D204]. Default
+     * `true`; it never runs under reduced motion, in forced colors or in
+     * print.
+     */
+    morph?: boolean;
+    /** Builds each anchor. Default: a plain `<a href="#id">`, which scrolls and writes the hash. */
+    renderLink?: (href: string) => React.ReactElement;
+    /** Override the scope's primary. Never defaulted [D133]. */
+    primary?: TableOfContentsVariants['primary'];
+    /** Override the scope's secondary. Never defaulted. */
+    secondary?: TableOfContentsVariants['secondary'];
+};
+/**
+ * The page's contents [D202, D203].
+ *
+ * `kind="list"` (default): a `nav` named by its caps heading (`type-label`)
+ * over an `ol` of in-page links in `type-caption`, H2s at the top level and
+ * H3 and H4 nested on the --role-hairline guide. The section in view
+ * (`activeId`) takes `aria-current="location"`, the --border-size-2-25
+ * start-edge bar and weight 700; every entry reserves that weight's box, so
+ * marking a section never moves the list.
+ *
+ * `kind="bar"`: one field-box line, "On this page" and the section in view
+ * (the first before scrollspy runs), truncated, with a chevron. It opens
+ * the same list in an anchored panel about a third of the viewport tall,
+ * scrolled inside so the section in view sits centered and marked, with
+ * focus on it; following an entry goes to its heading and closes the
+ * panel; Escape and an outside press close it and focus returns to the
+ * bar. The bar's ring or edge morphs into the panel's frame [D204].
+ *
+ * Presentational: pair it with `useActiveHeading` for scrollspy. The docs
+ * layout shows the list in a sticky column from --xl-n-above and the bar,
+ * pinned under the header, below. With no items it renders nothing. Hidden
+ * in print.
+ */
+export declare function TableOfContents(props: TableOfContentsProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=TableOfContents.d.ts.map

package/navigation/table-of-contents/TableOfContents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableOfContents.d.ts","sourceRoot":"","sources":["../../src/navigation/table-of-contents/TableOfContents.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAuDjE,eAAO,MAAM,eAAe;;;;8EAa1B,CAAA;AAEF,KAAK,uBAAuB,GAAG,YAAY,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAA;AAE9E,qFAAqF;AACrF,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAE5C,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAA;IACV,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,KAAK,EAAE,oBAAoB,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sDAAsD;IACtD,IAAI,CAAC,EAAE,mBAAmB,CAAA;IAC1B,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,4CAAuD,CAAA;AAG1F,8GAA8G;AAC9G,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACtF,8FAA8F;IAC9F,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAA;IACtC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,gGAAgG;IAChG,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,YAAY,CAAA;IACjD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAA;IAC5C,uDAAuD;IACvD,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAA;CACjD,CAAA;AA6FH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,4BAgD1D"}