@designtools/docs 0.0.0-stage → 0.1.0

package/dist/search.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Autocomplete } from "@base-ui/react/autocomplete";
+import { Dialog } from "@base-ui/react/dialog";
+import { Search } from "lucide-react";
+import { useRouter } from "next/navigation";
+import { useEffect, useId, useMemo, useState } from "react";
+import { cx, target } from "./lib/cx.js";
+import { search } from "./lib/search.js";
+const PLURAL = { Component: "Components", Rule: "Rules", Pattern: "Patterns", Page: "Pages" };
+/**
+ * Find a component, a part, a rule, a pattern or a page by name, fuzzily, and go
+ * there. A wrong name finds the right thing ("Dropdown" finds Select, and says
+ * so). Opens with ⌘K or Ctrl+K anywhere, or / when you are not typing. Build the
+ * items with `searchIndex` from `lib/search`; the shell does, when you pass it the
+ * taxonomy. Navigation only: it does not search page text.
+ */
+export function DocsSearch({ items, shortcuts = true, variant = "field", className, }) {
+    const router = useRouter();
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    const [shortcut, setShortcut] = useState("Ctrl K");
+    const hintId = useId();
+    const groups = useMemo(() => search(items, query), [items, query]);
+    useEffect(() => {
+        if (/Mac|iPhone|iPad/.test(navigator.platform))
+            setShortcut("⌘K");
+        if (!shortcuts)
+            return;
+        const onKey = (e) => {
+            const typing = e.target instanceof HTMLElement && (e.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName));
+            if ((e.key === "k" && (e.metaKey || e.ctrlKey)) || (e.key === "/" && !typing && !e.metaKey && !e.ctrlKey && !e.altKey)) {
+                e.preventDefault();
+                setOpen(true);
+            }
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [shortcuts]);
+    const go = (item) => {
+        setOpen(false);
+        setQuery("");
+        router.push(item.href);
+    };
+    return (_jsxs(Dialog.Root, { open: open, onOpenChange: (next) => (setOpen(next), next || setQuery("")), children: [variant === "icon" ? (_jsx(Dialog.Trigger, { "data-slot": "docs-search-trigger", "aria-label": "Search the design system", className: cx("inline-flex size-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring", className), children: _jsx(Search, { "aria-hidden": true, className: "size-(--dt-size-sm)" }) })) : (_jsxs(Dialog.Trigger, { "data-slot": "docs-search-trigger", className: cx(target, "flex w-full items-center gap-2.5 rounded-md border border-border bg-canvas px-3 text-sm text-muted-foreground transition-colors duration-(--dt-duration-fast) hover:border-input hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring", className), children: [_jsx(Search, { "aria-hidden": true, className: "size-(--dt-size-xs) shrink-0" }), _jsx("span", { className: "flex-1 text-left", children: "Search" }), _jsx("kbd", { className: "rounded-sm border border-border bg-surface px-1.5 py-0.5 font-mono text-xs pointer-coarse:hidden", children: shortcut })] })), _jsxs(Dialog.Portal, { children: [_jsx(Dialog.Backdrop, { "data-designtools": "", className: "fixed inset-0 z-40 bg-canvas-foreground/30 backdrop-blur-xs transition-opacity duration-(--dt-duration-base) data-ending-style:opacity-0 data-starting-style:opacity-0" }), _jsx(Dialog.Viewport, { "data-designtools": "", className: "fixed inset-0 z-50 flex items-start justify-center px-4 pt-[12dvh]", children: _jsx(Dialog.Popup, { "data-slot": "docs-search", "aria-label": "Search the design system", className: "flex max-h-[min(36rem,80dvh)] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-border bg-overlay text-overlay-foreground shadow-xl transition-[opacity,scale] duration-(--dt-duration-base) ease-(--dt-ease-out) data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0", children: _jsxs(Autocomplete.Root, { open: true, inline: true, items: groups, filter: null, value: query, onValueChange: (next) => setQuery(next), itemToStringValue: (item) => item.label, autoHighlight: "always", keepHighlight: true, children: [_jsxs("div", { className: "flex items-center gap-3 border-b border-border px-4", children: [_jsx(Search, { "aria-hidden": true, className: "size-(--dt-size-sm) shrink-0 text-muted-foreground" }), _jsx(Autocomplete.Input, { "aria-label": "Search components, rules, patterns and pages", "aria-describedby": hintId, placeholder: "Search components, rules, patterns\u2026", className: "h-(--dt-size-3xl) w-full bg-transparent text-lg outline-none placeholder:text-muted-foreground" })] }), _jsx(Dialog.Close, { className: "sr-only", children: "Close search" }), _jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto overscroll-contain p-2", children: [_jsx(Autocomplete.Empty, { children: _jsx("p", { className: "px-4 py-6 text-sm text-muted-foreground", children: query.trim() ? `Nothing called “${query.trim()}”.` : "Type a name, or a name you half remember." }) }), _jsx(Autocomplete.List, { children: (group) => (_jsxs(Autocomplete.Group, { items: group.items, className: "not-last:mb-2", children: [_jsx(Autocomplete.GroupLabel, { className: "px-3 pt-2 pb-1 text-xs font-medium tracking-wide text-muted-foreground uppercase", children: PLURAL[group.kind] }), _jsx(Autocomplete.Collection, { children: (item) => (_jsxs(Autocomplete.Item, { value: item, onClick: () => go(item), className: cx(target, "flex cursor-pointer items-center justify-between gap-3 rounded-md px-3 py-2 text-sm outline-none select-none data-highlighted:bg-muted"), children: [_jsx("span", { className: "min-w-0 truncate font-medium", children: item.label }), _jsx("span", { className: "shrink-0 text-xs text-muted-foreground", children: item.matched ? `for “${item.matched}”` : item.detail })] }, item.href)) })] }, group.kind)) })] }), _jsx("p", { id: hintId, className: "border-t border-border px-4 py-2 text-xs text-muted-foreground", children: "Arrow keys to move, Enter to go, Escape to close." })] }) }) })] })] }));
+}

package/dist/shell.d.ts

@@ -0,0 +1,89 @@
+import { type ReactNode } from "react";
+import type { ComponentsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./lib/manifest-types.js";
+export interface DocsLink {
+    label: string;
+    href: string;
+    /** Shown beneath it while you are on it or one of them: a component's parts. */
+    children?: DocsLink[];
+}
+/**
+ * The docs frame, in the site's order: overview, brand, foundations, rules,
+ * patterns, components by `@category`, standards. Editorial pages are the links
+ * you pass; rules, patterns and components come from the manifest.
+ *
+ * On a laptop the navigation is an inset panel down the left, each section
+ * folding open where the current page is, with search at the top and the colour
+ * mode at the foot; wide screens add an "On this page" rail. On a phone it is a
+ * bar with search and a drawer. Every page ends with the previous and next page,
+ * and `DocsHeader` names the section it sits in. Put it in the docs layout.
+ */
+export declare function DocsShell({ manifest, rules, patterns, terms, search, themeSwitch, title, logo, basePath, brand, foundations, standards, hero, children, }: {
+    manifest: ComponentsManifest;
+    /** Listed under Rules, each linking to its anchor on `${basePath}/rules`. */
+    rules?: RulesManifest;
+    /** Listed under Patterns, each at `${basePath}/patterns/${id}`. */
+    patterns?: PatternsManifest;
+    /** The taxonomy, so search finds a component by a wrong name ("Dropdown" finds Select). */
+    terms?: TaxonomyManifest;
+    /** Search over components, parts, rules, patterns and pages, on ⌘K, Ctrl+K or /. On by default. */
+    search?: boolean;
+    /** System, light and dark, at the foot of the navigation. Off for a project with its own switch. */
+    themeSwitch?: boolean;
+    title?: string;
+    /** The client's logo, shown beside the title: the site is theirs. */
+    logo?: ReactNode;
+    /** Component pages live at `${basePath}/components/${slug}`. */
+    basePath?: string;
+    /** Brand pages: principles, design language, voice, logo, imagery. */
+    brand?: DocsLink[];
+    /** Foundations pages: colour, type, scale. */
+    foundations?: DocsLink[];
+    /** Standards pages: budgets, accessibility, adherence. */
+    standards?: DocsLink[];
+    /**
+     * A full-bleed introduction across the top of the overview, edge to edge of the
+     * content area: the brand's splash. The overview's own header can then be left out.
+     */
+    hero?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A page's heading: the section it sits in (from the navigation), the title, the
+ * lead, and the page's actions as children. Where the page comes from goes at the
+ * foot, in `DocsFooter`.
+ */
+export declare function DocsHeader({ title, lead, eyebrow, children, }: {
+    title: string;
+    lead?: string;
+    /** Above the title. Defaults to the section the page sits in. */
+    eyebrow?: string;
+    /** The page's actions, beside the title: `PageActions`. */
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Where a page comes from, at its foot: a generated page names the version and
+ * commit it was built from; an editorial page names its author, who reviewed it,
+ * when, and whether it is settled. Never both, and never a review date on a
+ * generated page, which would be invented. `source` names the file it documents.
+ */
+export declare function DocsFooter({ provenance, editorial, source, }: {
+    /** For a generated page: `Generated from acme-web@1.4.0 at 3f2a9c1`, from `designtools-manifest provenance`. */
+    provenance?: string;
+    /** For an editorial page. `reviewer` when the person who signs it off is not the author. */
+    editorial?: {
+        author: string;
+        reviewer?: string;
+        reviewed: string;
+        status: "draft" | "published";
+    };
+    source?: string;
+}): import("react").JSX.Element | null;
+/**
+ * A titled section of a docs page, numbered in a gutter beside it (01, 02, …,
+ * counted by CSS in page order) and listed in "On this page".
+ */
+export declare function DocsSection({ title, lead, children }: {
+    title: string;
+    lead?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/shell.js

@@ -0,0 +1,199 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Collapsible } from "@base-ui/react/collapsible";
+import { Dialog } from "@base-ui/react/dialog";
+import { ArrowLeft, ArrowRight, BookOpen, ChevronRight, Component, Gauge, House, LayoutTemplate, Menu, Palette, Scale, X } from "lucide-react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { accent, cx, display, target } from "./lib/cx.js";
+import { groupFamilies, slugOf } from "./lib/manifest.js";
+import { searchIndex } from "./lib/search.js";
+import { Prose } from "./lib/text.js";
+import { DocsSearch } from "./search.js";
+import { ThemeSwitch, useThemeScript } from "./theme-switch.js";
+/** What the page knows from the navigation: the section it sits in, and its neighbours. */
+const DocsPage = createContext({});
+/**
+ * The docs frame, in the site's order: overview, brand, foundations, rules,
+ * patterns, components by `@category`, standards. Editorial pages are the links
+ * you pass; rules, patterns and components come from the manifest.
+ *
+ * On a laptop the navigation is an inset panel down the left, each section
+ * folding open where the current page is, with search at the top and the colour
+ * mode at the foot; wide screens add an "On this page" rail. On a phone it is a
+ * bar with search and a drawer. Every page ends with the previous and next page,
+ * and `DocsHeader` names the section it sits in. Put it in the docs layout.
+ */
+export function DocsShell({ manifest, rules, patterns, terms, search = true, themeSwitch = true, title = "Design system", logo, basePath = "/design/system", brand = [], foundations = [], standards = [], hero, children, }) {
+    const current = usePathname();
+    const searchItems = useMemo(() => searchIndex({
+        manifest,
+        rules: rules?.rules,
+        patterns: patterns?.patterns,
+        terms: terms?.terms,
+        pages: [...brand, ...foundations, ...(rules?.rules.length ? [{ label: "Rules", href: `${basePath}/rules` }] : []), ...standards],
+        basePath,
+    }), [manifest, rules, patterns, terms, brand, foundations, standards, basePath]);
+    const sections = useMemo(() => {
+        const families = groupFamilies(manifest);
+        const all = [
+            { id: "overview", label: "Overview", icon: House, href: basePath, groups: [] },
+            { id: "brand", label: "Brand", icon: BookOpen, groups: [{ links: brand }] },
+            { id: "foundations", label: "Foundations", icon: Palette, groups: [{ links: foundations }] },
+            ...(rules?.rules.length ? [{ id: "rules", label: "Rules", icon: Scale, href: `${basePath}/rules`, groups: [] }] : []),
+            {
+                id: "patterns",
+                label: "Patterns",
+                icon: LayoutTemplate,
+                groups: [{ links: (patterns?.patterns ?? []).map((p) => ({ label: p.name, href: `${basePath}/patterns/${p.id}` })) }],
+            },
+            {
+                id: "components",
+                label: "Components",
+                icon: Component,
+                groups: families.map((g) => ({
+                    heading: families.length > 1 ? g.category : undefined,
+                    links: g.families.map(({ head, parts }) => ({
+                        label: head.name,
+                        href: `${basePath}/components/${slugOf(head)}`,
+                        children: parts.map((p) => ({ label: p.name, href: `${basePath}/components/${slugOf(p)}` })),
+                    })),
+                })),
+            },
+            { id: "standards", label: "Standards", icon: Gauge, groups: [{ links: standards }] },
+        ];
+        return all.filter((s) => s.href || s.groups.some((g) => g.links.length));
+    }, [manifest, rules, patterns, brand, foundations, standards, basePath]);
+    // every page in navigation order, for the section a page sits in and its neighbours
+    const page = useMemo(() => {
+        // a section of one page has no section above it: the page is the section
+        const order = [];
+        for (const s of sections) {
+            if (s.href)
+                order.push({ link: { label: s.label, href: s.href } });
+            for (const g of s.groups)
+                for (const l of g.links)
+                    order.push({ link: l, section: s.label });
+        }
+        const at = order.findIndex(({ link }) => link.href === current || link.children?.some((c) => c.href === current));
+        if (at < 0)
+            return {};
+        return { section: order[at].section, prev: order[at - 1]?.link, next: order[at + 1]?.link };
+    }, [sections, current]);
+    // a hook, so it runs whether or not the switch is shown; the script only reads a saved choice
+    useThemeScript();
+    const [menu, setMenu] = useState(false);
+    useEffect(() => setMenu(false), [current]);
+    const brandLink = (_jsxs(Link, { href: basePath, "data-slot": "docs-title", className: cx(target, "flex min-w-0 items-center gap-3 rounded-md focus-visible:outline-2 focus-visible:outline-ring"), children: [logo && (_jsx("span", { "data-slot": "docs-logo", className: "shrink-0", children: logo })), _jsx("span", { className: cx(logo ? "sr-only" : "truncate text-base font-semibold tracking-tight"), children: title })] }));
+    return (_jsx(DocsPage.Provider, { value: page, children: _jsxs("div", { "data-designtools": "", "data-slot": "docs-shell", className: "min-h-dvh bg-canvas text-canvas-foreground lg:grid lg:grid-cols-[19rem_minmax(0,1fr)]", children: [_jsx("aside", { "data-slot": "docs-sidebar", className: "sticky top-0 hidden h-dvh p-3 lg:block", children: _jsxs("div", { className: "flex h-full flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs", children: [_jsxs("div", { className: "flex flex-col gap-3 p-4 pb-3", children: [brandLink, search && _jsx(DocsSearch, { items: searchItems })] }), _jsx(Nav, { sections: sections, current: current, title: title }), themeSwitch && (_jsxs("div", { "data-slot": "docs-sidebar-foot", className: "flex items-center justify-between gap-3 border-t border-border px-4 py-3", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: "Appearance" }), _jsx(ThemeSwitch, {})] }))] }) }), _jsxs("div", { className: "min-w-0", children: [_jsxs("header", { "data-slot": "docs-topbar", className: "sticky top-0 z-20 flex h-16 items-center gap-2 border-b border-border bg-canvas/85 px-3 backdrop-blur-md lg:hidden", children: [_jsxs(Dialog.Root, { open: menu, onOpenChange: setMenu, children: [_jsx(Dialog.Trigger, { "aria-label": "Open the navigation", className: iconButton, children: _jsx(Menu, { "aria-hidden": true, className: "size-(--dt-size-sm)" }) }), _jsxs(Dialog.Portal, { children: [_jsx(Dialog.Backdrop, { "data-designtools": "", className: "fixed inset-0 z-40 bg-canvas-foreground/30 transition-opacity duration-(--dt-duration-base) data-ending-style:opacity-0 data-starting-style:opacity-0" }), _jsxs(Dialog.Popup, { "data-designtools": "", "data-slot": "docs-drawer", "aria-label": title, className: "fixed inset-y-0 left-0 z-50 flex w-[min(21rem,88vw)] flex-col bg-surface text-surface-foreground shadow-xl transition-transform duration-(--dt-duration-slow) ease-(--dt-ease-out) data-ending-style:-translate-x-full data-starting-style:-translate-x-full", children: [_jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-border p-3 pl-4", children: [brandLink, _jsx(Dialog.Close, { "aria-label": "Close the navigation", className: iconButton, children: _jsx(X, { "aria-hidden": true, className: "size-(--dt-size-sm)" }) })] }), _jsx(Nav, { sections: sections, current: current, title: title }), themeSwitch && (_jsxs("div", { className: "flex items-center justify-between gap-3 border-t border-border px-4 py-3", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: "Appearance" }), _jsx(ThemeSwitch, {})] }))] })] })] }), _jsx("div", { className: "min-w-0 flex-1", children: brandLink }), search && _jsx(DocsSearch, { items: searchItems, shortcuts: false, variant: "icon" })] }), hero && current === basePath && (_jsx("div", { "data-slot": "docs-hero", className: "w-full", children: hero })), _jsxs("div", { className: "mx-auto flex w-full max-w-[90rem] gap-16 px-5 pt-12 pb-20 sm:px-8 lg:px-12 lg:pt-20 xl:px-20", children: [_jsxs("main", { "data-slot": "docs-main", className: "flex min-w-0 flex-1 flex-col gap-16 [counter-reset:docs-section] lg:gap-24", children: [children, _jsx(Pager, { prev: page.prev, next: page.next })] }), _jsx(OnThisPage, { current: current })] })] })] }) }));
+}
+const iconButton = "inline-flex size-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring";
+/** The sections, each a link or a fold that opens where the current page is. */
+function Nav({ sections, current, title }) {
+    const holds = (s) => s.groups.some((g) => g.links.some((l) => l.href === current || l.children?.some((c) => c.href === current)));
+    const [open, setOpen] = useState(() => Object.fromEntries(sections.map((s) => [s.id, holds(s)])));
+    // moving to a page opens its section; nothing closes on its own
+    useEffect(() => {
+        const here = sections.find(holds);
+        if (here)
+            setOpen((o) => (o[here.id] ? o : { ...o, [here.id]: true }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [current, sections]);
+    return (_jsx("nav", { "aria-label": title, "data-slot": "docs-nav", className: "min-h-0 flex-1 overflow-y-auto px-3 pb-4 text-sm", children: _jsx("ul", { className: "flex flex-col gap-0.5", children: sections.map((s) => {
+                const Icon = s.icon;
+                const row = cx(target, "group flex w-full items-center gap-3 rounded-md px-2.5 font-medium text-canvas-foreground hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring");
+                const icon = _jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs) shrink-0 text-muted-foreground group-hover:text-canvas-foreground" });
+                if (s.href) {
+                    const active = current === s.href;
+                    return (_jsx("li", { children: _jsxs(Link, { href: s.href, "aria-current": active ? "page" : undefined, "data-slot": "docs-nav-section", className: cx(row, active && "bg-muted"), children: [icon, s.label] }) }, s.id));
+                }
+                return (_jsx("li", { children: _jsxs(Collapsible.Root, { open: open[s.id] ?? false, onOpenChange: (next) => setOpen((o) => ({ ...o, [s.id]: next })), children: [_jsxs(Collapsible.Trigger, { "data-slot": "docs-nav-section", className: row, children: [icon, _jsx("span", { className: "flex-1 text-left", children: s.label }), _jsx(ChevronRight, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground transition-transform duration-(--dt-duration-fast) group-data-panel-open:rotate-90" })] }), _jsx(Collapsible.Panel, { "data-slot": "docs-nav-panel", className: "h-(--collapsible-panel-height) overflow-hidden transition-[height] duration-(--dt-duration-base) ease-(--dt-ease-out) data-ending-style:h-0 data-starting-style:h-0", children: _jsx("div", { className: "ml-[1.1875rem] flex flex-col gap-3 border-l border-border py-1 pl-3", children: s.groups.map((g, i) => (_jsxs("div", { className: "flex flex-col", children: [g.heading && (_jsx("p", { "data-slot": "docs-nav-heading", className: "px-2.5 pt-1 pb-1 text-xs font-medium tracking-wide text-muted-foreground uppercase", children: g.heading })), _jsx("ul", { className: "flex flex-col", children: g.links.map((link) => {
+                                                    const here = current === link.href || link.children?.some((c) => c.href === current);
+                                                    return (_jsxs("li", { children: [_jsx(NavLink, { link: link, current: current }), here && link.children?.length ? (_jsx("ul", { "data-slot": "docs-nav-parts", "aria-label": `${link.label} parts`, className: "ml-3 flex flex-col border-l border-border pl-2", children: link.children.map((child) => (_jsx("li", { children: _jsx(NavLink, { link: child, current: current }) }, child.href))) })) : null] }, link.href));
+                                                }) })] }, g.heading ?? i))) }) })] }) }, s.id));
+            }) }) }));
+}
+function NavLink({ link, current }) {
+    const active = current === link.href;
+    return (_jsxs(Link, { href: link.href, "aria-current": active ? "page" : undefined, "data-slot": "docs-nav-link", className: cx(target, "relative flex items-center rounded-md px-2.5 text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring", active && "bg-muted font-medium text-canvas-foreground"), children: [active && _jsx("span", { "aria-hidden": true, "data-slot": "docs-nav-marker", className: cx(accent, "absolute inset-y-2.5 -left-[0.8125rem] w-0.5 rounded-full") }), link.label] }));
+}
+/** The page's sections, beside it on a wide screen, marking the one being read. */
+function OnThisPage({ current }) {
+    const [items, setItems] = useState([]);
+    const [active, setActive] = useState();
+    useEffect(() => {
+        const headings = [...document.querySelectorAll('[data-slot="docs-main"] [data-slot="docs-section-title"][id]')];
+        setItems(headings.map((h) => ({ id: h.id, label: h.textContent ?? "" })));
+        setActive(headings[0]?.id);
+        if (!headings.length)
+            return;
+        // the section being read is the last whose heading has passed the top quarter of the window
+        let frame = 0;
+        const update = () => {
+            frame = 0;
+            const line = window.innerHeight * 0.25;
+            let at = headings[0];
+            for (const h of headings)
+                if (h.getBoundingClientRect().top <= line)
+                    at = h;
+            // at the foot of the page the last section is the one in view, however short
+            if (window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 4)
+                at = headings[headings.length - 1];
+            setActive(at.id);
+        };
+        const onScroll = () => {
+            if (!frame)
+                frame = requestAnimationFrame(update);
+        };
+        update();
+        window.addEventListener("scroll", onScroll, { passive: true });
+        window.addEventListener("resize", onScroll);
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener("scroll", onScroll);
+            window.removeEventListener("resize", onScroll);
+        };
+    }, [current]);
+    if (items.length < 2)
+        return null;
+    return (_jsxs("nav", { "aria-label": "On this page", "data-slot": "docs-toc", className: "sticky top-16 hidden h-fit w-48 shrink-0 2xl:block", children: [_jsx("p", { className: "mb-3 text-xs font-medium tracking-wide text-muted-foreground uppercase", children: "On this page" }), _jsx("ul", { className: "flex flex-col border-l border-border text-sm", children: items.map((item) => (_jsx("li", { children: _jsxs("a", { href: `#${item.id}`, "aria-current": active === item.id ? "location" : undefined, className: cx("relative -ml-px block border-l border-transparent py-1.5 pl-4 text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring", active === item.id && "font-medium text-canvas-foreground"), children: [active === item.id && _jsx("span", { "aria-hidden": true, className: cx(accent, "absolute inset-y-1.5 -left-px w-0.5 rounded-full") }), item.label] }) }, item.id))) })] }));
+}
+/** The previous and next page in the navigation's order. */
+function Pager({ prev, next }) {
+    if (!prev && !next)
+        return null;
+    const card = cx(target, "group flex flex-col gap-1 rounded-lg border border-border p-5 transition-colors duration-(--dt-duration-fast) hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring");
+    return (_jsxs("nav", { "aria-label": "Previous and next", "data-slot": "docs-pager", className: "grid gap-3 border-t border-border pt-10 sm:grid-cols-2", children: [prev ? (_jsxs(Link, { href: prev.href, className: card, children: [_jsxs("span", { className: "flex items-center gap-1.5 text-xs text-muted-foreground", children: [_jsx(ArrowLeft, { "aria-hidden": true, className: "size-(--dt-size-xs) transition-transform group-hover:-translate-x-0.5" }), " Previous"] }), _jsx("span", { className: "text-base font-medium", children: prev.label })] })) : (_jsx("span", {})), next && (_jsxs(Link, { href: next.href, className: cx(card, "sm:items-end sm:text-right"), children: [_jsxs("span", { className: "flex items-center gap-1.5 text-xs text-muted-foreground", children: ["Next ", _jsx(ArrowRight, { "aria-hidden": true, className: "size-(--dt-size-xs) transition-transform group-hover:translate-x-0.5" })] }), _jsx("span", { className: "text-base font-medium", children: next.label })] }))] }));
+}
+/**
+ * A page's heading: the section it sits in (from the navigation), the title, the
+ * lead, and the page's actions as children. Where the page comes from goes at the
+ * foot, in `DocsFooter`.
+ */
+export function DocsHeader({ title, lead, eyebrow, children, }) {
+    const { section } = useContext(DocsPage);
+    const over = eyebrow ?? (section && section !== title ? section : undefined);
+    return (_jsxs("header", { "data-slot": "docs-header", className: "flex flex-col gap-6 border-b border-border pb-12 lg:pb-16", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-4", children: [over ? (_jsx("p", { "data-slot": "docs-eyebrow", className: "text-xs font-medium tracking-[var(--tracking-widest,0.16em)] text-muted-foreground uppercase", children: over })) : (_jsx("span", {})), children && (_jsx("div", { "data-slot": "docs-header-actions", className: "flex flex-wrap items-center gap-2", children: children }))] }), _jsx("h1", { className: cx(display, "text-5xl leading-[1.05] tracking-tight md:text-7xl"), children: title }), lead && (_jsx("div", { "data-slot": "docs-lead", className: "flex max-w-3xl flex-col gap-3 text-xl leading-snug font-light text-muted-foreground md:text-2xl md:leading-snug [&_code]:bg-transparent [&_code]:p-0", children: _jsx(Prose, { text: lead }) }))] }));
+}
+/**
+ * Where a page comes from, at its foot: a generated page names the version and
+ * commit it was built from; an editorial page names its author, who reviewed it,
+ * when, and whether it is settled. Never both, and never a review date on a
+ * generated page, which would be invented. `source` names the file it documents.
+ */
+export function DocsFooter({ provenance, editorial, source, }) {
+    if (!provenance && !editorial && !source)
+        return null;
+    return (_jsxs("footer", { "data-slot": "docs-footer", className: "flex flex-wrap items-center gap-x-6 gap-y-2 text-xs text-muted-foreground", children: [(provenance || editorial) && (_jsxs("p", { "data-slot": "docs-provenance", className: "flex items-center gap-2", children: [_jsx("span", { "aria-hidden": true, className: cx("size-1.5 shrink-0 rounded-full", editorial ? (editorial.status === "published" ? "bg-success" : "bg-warning") : "bg-primary") }), editorial
+                        ? `Written by ${editorial.author} · ${editorial.reviewer ? `reviewed by ${editorial.reviewer}, ` : "last reviewed "}${editorial.reviewed} · ${editorial.status}`
+                        : `${provenance} · generated from the code`] })), source && (_jsx("p", { "data-slot": "docs-source", className: "font-mono", children: source }))] }));
+}
+/**
+ * A titled section of a docs page, numbered in a gutter beside it (01, 02, …,
+ * counted by CSS in page order) and listed in "On this page".
+ */
+export function DocsSection({ title, lead, children }) {
+    const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    return (_jsxs("section", { "data-slot": "docs-section", "aria-labelledby": id, className: "grid gap-x-10 gap-y-8 [counter-increment:docs-section] xl:grid-cols-[5rem_minmax(0,1fr)]", children: [_jsx("span", { "aria-hidden": true, className: "pt-2 font-mono text-xs tracking-[var(--tracking-widest,0.16em)] text-muted-foreground before:content-[counter(docs-section,decimal-leading-zero)]" }), _jsxs("div", { className: "flex min-w-0 flex-col gap-10", children: [_jsxs("div", { className: "flex flex-col gap-4", children: [_jsx("h2", { id: id, "data-slot": "docs-section-title", className: cx(display, "scroll-mt-24 text-4xl leading-[1.1] tracking-tight md:text-5xl"), children: title }), lead && _jsx("p", { className: "max-w-2xl text-lg leading-relaxed text-muted-foreground", children: lead })] }), children] })] }));
+}

package/dist/standards.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+/**
+ * The project's performance budgets, accessibility target and support baseline,
+ * rendered from the thresholds it already records (`.mxa/stack.json`
+ * `baselines`), so the docs and the checks cannot disagree. A value nobody has
+ * set is left out rather than shown as `null`; a note is shown as a sentence.
+ * Thresholds a client agrees beyond the schema (`textSize`, `touchTargets`) are
+ * titled from their keys.
+ */
+export declare function Standards({ baselines, children }: {
+    baselines: Record<string, unknown>;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/standards.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Gauge, Info, Monitor, PersonStanding, Ruler } from "lucide-react";
+import { standardsSections } from "./lib/standards.js";
+const ICON = { a11y: PersonStanding, performance: Gauge, support: Monitor };
+/**
+ * The project's performance budgets, accessibility target and support baseline,
+ * rendered from the thresholds it already records (`.mxa/stack.json`
+ * `baselines`), so the docs and the checks cannot disagree. A value nobody has
+ * set is left out rather than shown as `null`; a note is shown as a sentence.
+ * Thresholds a client agrees beyond the schema (`textSize`, `touchTargets`) are
+ * titled from their keys.
+ */
+export function Standards({ baselines, children }) {
+    return (_jsxs("div", { "data-slot": "standards", className: "flex flex-col gap-6", children: [_jsx("div", { className: "grid gap-x-12 gap-y-10 md:grid-cols-2 xl:grid-cols-3", children: standardsSections(baselines).map((section) => {
+                    const Icon = ICON[section.key] ?? Ruler;
+                    const single = section.rows.length === 1 && !section.rows[0].label;
+                    return (_jsxs("section", { "data-slot": "standard", className: "flex flex-col gap-4 border-t border-border pt-5", children: [_jsxs("h3", { className: "flex items-center gap-2 text-sm font-medium text-muted-foreground", children: [_jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), section.title] }), single ? (_jsx("p", { className: "text-5xl font-light tracking-tight", children: section.rows[0].value })) : section.rows.length ? (_jsx("dl", { className: "flex flex-col gap-3", children: section.rows.map((row) => (_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: row.label }), _jsx("dd", { className: "text-2xl font-light tracking-tight tabular-nums", children: row.value })] }, row.label))) })) : null, section.notes.map((note) => (_jsx("p", { className: "text-sm text-muted-foreground", children: note }, note)))] }, section.key));
+                }) }), typeof baselines.$note === "string" && (_jsxs("p", { className: "flex items-start gap-2 text-sm text-muted-foreground", children: [_jsx(Info, { "aria-hidden": true, className: "mt-0.5 size-(--dt-size-xs) shrink-0" }), baselines.$note] })), children] }));
+}