@nanisoft/prism-ui 0.6.0 → 0.8.0

package/dist/components/ui/product-switcher.js

@@ -36,10 +36,10 @@ import { cn } from '../../lib/utils';
  * wants a menu rather than a row of marks composes `DropdownMenu` with the marks
  * and does not use this.
  */
-function ProductSwitcher({ products, currentId, size = 'sm', label = 'Products', className, ...props }) {
+function ProductSwitcher({ products, currentId, size = 'sm', label, className, ...props }) {
     if (products.length === 0)
         return null;
-    return (_jsx("nav", { "data-slot": "product-switcher", "aria-label": label, className: cn('flex flex-wrap items-center gap-x-4 gap-y-2', className), ...props, children: products.map((product) => {
+    return (_jsx("nav", { "data-slot": "product-switcher", ...(label === undefined ? null : { 'aria-label': label }), className: cn('flex flex-wrap items-center gap-x-4 gap-y-2', className), ...props, children: products.map((product) => {
             const current = product.id === currentId;
             return (_jsx("a", { href: product.href, "aria-current": current ? 'page' : undefined, "data-current": current ? 'true' : undefined, className: "rounded-sm transition-opacity duration-fast ease-out hover:opacity-80", children: _jsx(ProductMark, { id: product.id, name: product.name, pack: product.pack, size: size }) }, product.id));
         }) }));

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

@@ -5,7 +5,7 @@ import type { ComponentProps } from 'react';
  * Declared here rather than re-exported from Base UI so no upstream type
  * crosses the package seam (ticket 07 section 6).
  */
-export interface SliderProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defaultValue'> {
+export interface SliderProps extends Omit<ComponentProps<'div'>, 'onChange'> {
     /** The current value, when the slider is controlled. */
     value?: number;
     /** The value the slider starts at, for an uncontrolled 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,GAAG,cAAc,CAAC;IAC3F,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;;;;;;;;GAQG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,YAAY,EAAE,SAAS,EACvB,GAAG,KAAK,EACT,EAAE,WAAW,+BAiCb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

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

@@ -0,0 +1,115 @@
+import { type ReactNode } from 'react';
+/**
+ * A node a reader can arrive at: a title and the address it is read at.
+ *
+ * `href` is required. A node in a tree that goes nowhere is an entry a reader can
+ * focus and not follow, and this Component renders every node with a destination
+ * as a native anchor so a reader can see where it goes before taking it.
+ */
+export type TreeNodePage = {
+    type: 'page';
+    /** The words the reader meets. */
+    title: string;
+    /** The address the node is read at. */
+    href: string;
+};
+/**
+ * A label over a list of nodes, at any depth.
+ *
+ * `href` is the group's own index and it is optional on purpose. A group with no
+ * index is a place in the tree and not a route, so this Component renders it as a
+ * label: no anchor, no `href`, nothing focusable. Inventing a route for it would
+ * publish an address that resolves to nothing.
+ *
+ * `items` is required, because a group that renders a label and holds nothing is
+ * an empty entry rather than a group. Pass a node with no children rather than a
+ * group with none.
+ */
+export type TreeNodeGroup = {
+    type: 'group';
+    /** The words on the label. A status inside them stays inside them. */
+    title: string;
+    /** The group's own index, where it has one. Omit it for a label over a list. */
+    href?: string;
+    /** The nodes under this group, in the order a reader should meet them. */
+    items: readonly TreeNode[];
+};
+/**
+ * A rule between nodes, carrying a name that is usually empty.
+ *
+ * It is a label and never a link. The alternative spelling, a page node with an
+ * empty `href`, is a control that cannot be operated, so a rule is its own type.
+ */
+export type TreeNodeDivider = {
+    type: 'divider';
+    /** The words on the rule, which may be the empty string. */
+    title: string;
+};
+/**
+ * One node in a tree, of any of the three kinds.
+ *
+ * The union is closed, and it is a union rather than one shape with optional
+ * fields because a reader meets three different things in a tree: a destination, a
+ * label over a list, and a rule. A single shape would make all three look alike,
+ * and "a place that is a heading, not a link" is the distinction the whole
+ * arrangement turns on.
+ */
+export type TreeNode = TreeNodePage | TreeNodeGroup | TreeNodeDivider;
+/** The props the Tree accepts. */
+export interface TreeProps {
+    /** The nodes, in the order a reader should meet them. */
+    nodes: readonly TreeNode[];
+    /**
+     * The address the reader is currently at, which is what marks the current node.
+     *
+     * The marking is the attribute and not a class, so it survives a theme change and
+     * does not depend on a colour a reader may not distinguish.
+     */
+    currentHref?: string;
+    /**
+     * The accessible name of the tree, read before its nodes.
+     *
+     * Required rather than defaulted, because a tree with no name is announced as
+     * "tree" and a page with two of them is a page where a reader cannot tell which
+     * is which. The name is the caller's word.
+     */
+    label: string;
+    /** Layout only. */
+    className?: string;
+    /**
+     * The words a reader is told when the tree is empty, and optionally what to do
+     * about it.
+     *
+     * A tree that renders nothing is a control with nothing in it, so the empty case
+     * is authored rather than left to a caller to notice.
+     */
+    empty?: {
+        message: string;
+        action?: ReactNode;
+    };
+}
+/**
+ * A tree of nodes, given as data.
+ *
+ * This is the third of the three primitives the expansion found missing, and the
+ * one with a different kind of work behind it: the implementation already existed
+ * as two private renderers inside the documentation Page, with its depth rule, its
+ * `aria-current` marking and its rule that a group with no index renders a label.
+ * What was missing was that it was unreachable, and that its data type was bound
+ * to documentation navigation rather than being a tree's own vocabulary. So this is
+ * a promotion rather than a second implementation, and the reasoning in the
+ * documentation Page is carried across rather than rewritten.
+ *
+ * **A flat list renders a flat tree.** An outline is a tree of depth one, so a
+ * caller passes leaves and gets leaves. A Component that required nesting to
+ * express a flat structure would make the common case the awkward one.
+ *
+ * **The Page keeps its own renderers and does not change.** Its two rules, that a
+ * section carries no status or count and that a group with no index is a label,
+ * are specific to a documentation rail and are reasoned at length in the design
+ * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
+ * Page composes this Component later is a decision this ticket does not make.
+ */
+declare function Tree({ nodes, currentHref, label, className, empty }: TreeProps): import("react").JSX.Element;
+export { Tree };
+//# sourceMappingURL=tree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tree.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;AAErE,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;CAChD;AAqKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,SAAS,+BAkEvE;AAED,OAAO,EAAE,IAAI,EAAE,CAAA"}

package/dist/components/ui/tree.js

@@ -0,0 +1,137 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { cn } from '../../lib/utils';
+/** Whether a group's subtree contains the current address, at any depth. */
+function containsHref(nodes, currentHref) {
+    if (currentHref === undefined)
+        return false;
+    for (const node of nodes) {
+        if (node.type === 'page' && node.href === currentHref)
+            return true;
+        if (node.type === 'group') {
+            if (node.href === currentHref)
+                return true;
+            if (containsHref(node.items, currentHref))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether an address is the current one or lies under it, for a heading's emphasis. */
+function under(href, currentHref) {
+    if (currentHref === undefined)
+        return false;
+    return currentHref === href || currentHref.startsWith(`${href}/`);
+}
+function TreeLevel({ nodes, currentHref, depth, }) {
+    return (_jsx("ul", { "data-slot": "tree-list", "data-depth": depth, 
+        // `group` on the list, not `treeitem`: the items are the things a reader
+        // navigates between, and a `ul` of them is a group. `role="none"` on each
+        // item below removes the listitem role so that only the anchors and labels
+        // are the navigable things, which is what lets a caller's own keyboard model
+        // move between them without a roving tabindex fighting the document's.
+        role: "group", className: cn('border-border flex flex-col gap-1 border-l', 
+        // One level of indent per nested group and none at the top, so the depth
+        // reads from the rule rather than from the words.
+        depth > 0 && 'ps-3'), children: nodes.map((node, index) => (_jsx(TreeItem, { node: node, currentHref: currentHref, depth: depth }, `${node.type}:${index}`))) }));
+}
+function TreeItem({ node, currentHref, depth, }) {
+    if (node.type === 'divider') {
+        // A rule between nodes. It is a label, so it is not focusable and a reader
+        // does not meet it as a destination, and the empty title renders no words
+        // above the hairline rather than a word a reader has to interpret.
+        return (_jsx("li", { "data-slot": "tree-divider", role: "none", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: node.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: node.title })) : null }));
+    }
+    if (node.type === 'group') {
+        return (_jsx("li", { "data-slot": "tree-group", role: "none", children: _jsxs("div", { className: "flex flex-col gap-1", children: [node.href === undefined ? (
+                    /*
+                     * A group with no index is a tree item that is not a destination, so it
+                     * carries `role="treeitem"` and its level and nothing else. It is not a
+                     * bare span: `aria-level` on an element with no role is prohibited
+                     * rather than ignored, which the accessibility gate caught the first
+                     * time this was rendered, and a reader needs the level to place a label
+                     * that has no anchor to place it by.
+                     */
+                    _jsx("span", { "data-slot": "tree-label", role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(node.items, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })) : (_jsx("a", { "data-slot": "tree-heading", href: node.href, role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(node.href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })), node.items.length > 0 ? (_jsx(TreeLevel, { nodes: node.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+    }
+    return (_jsx("li", { "data-slot": "tree-item", role: "none", children: _jsx("a", { "data-slot": "tree-link", href: node.href, 
+            // A destination in a tree is a `treeitem`, not a link with a level hung
+            // off it: the level belongs to the item, and a reader placing it in the
+            // tree is reading the item rather than the anchor inside it.
+            role: "treeitem", "aria-level": depth + 1, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === node.href
+                ? 'text-foreground border-primary font-medium'
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: node.title }) }));
+}
+/**
+ * A tree of nodes, given as data.
+ *
+ * This is the third of the three primitives the expansion found missing, and the
+ * one with a different kind of work behind it: the implementation already existed
+ * as two private renderers inside the documentation Page, with its depth rule, its
+ * `aria-current` marking and its rule that a group with no index renders a label.
+ * What was missing was that it was unreachable, and that its data type was bound
+ * to documentation navigation rather than being a tree's own vocabulary. So this is
+ * a promotion rather than a second implementation, and the reasoning in the
+ * documentation Page is carried across rather than rewritten.
+ *
+ * **A flat list renders a flat tree.** An outline is a tree of depth one, so a
+ * caller passes leaves and gets leaves. A Component that required nesting to
+ * express a flat structure would make the common case the awkward one.
+ *
+ * **The Page keeps its own renderers and does not change.** Its two rules, that a
+ * section carries no status or count and that a group with no index is a label,
+ * are specific to a documentation rail and are reasoned at length in the design
+ * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
+ * Page composes this Component later is a decision this ticket does not make.
+ */
+function Tree({ nodes, currentHref, label, className, empty }) {
+    const root = useRef(null);
+    /**
+     * The keyboard model, and the reason it lives here rather than in a caller's.
+     *
+     * A tree is one Tab stop, and the arrow keys move inside it. That is the ARIA
+     * pattern, and a consumer who composes the markup themselves gets the Tab order
+     * of the document instead, which is every node in the tree and none of the
+     * arrows. A roving tabindex is the mechanism: one node is tabbable at a time and
+     * the arrows move which one.
+     *
+     * The flat order is collected from the DOM rather than computed from the node
+     * data, because the DOM is what a reader actually moves through and computing a
+     * second order from the data is a second list to fall behind the first. Only
+     * focusable nodes take part, so a label that is not a destination is skipped
+     * rather than focused and doing nothing.
+     */
+    const onKeyDown = (event) => {
+        const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
+        if (!keys.includes(event.key))
+            return;
+        const root_ = root.current;
+        if (root_ === null)
+            return;
+        const items = [
+            ...root_.querySelectorAll('[data-slot="tree-link"], [data-slot="tree-heading"]'),
+        ];
+        if (items.length === 0)
+            return;
+        const at = items.indexOf(document.activeElement);
+        if (at === -1)
+            return;
+        event.preventDefault();
+        const next = event.key === 'ArrowDown'
+            ? Math.min(at + 1, items.length - 1)
+            : event.key === 'ArrowUp'
+                ? Math.max(at - 1, 0)
+                : event.key === 'Home'
+                    ? 0
+                    : items.length - 1;
+        items[next]?.focus();
+    };
+    if (nodes.length === 0) {
+        // A tree that renders nothing is a control with nothing in it, so the empty
+        // case is authored rather than left for a caller to notice.
+        return (_jsxs("div", { "data-slot": "tree-empty", className: cn('text-muted-foreground text-sm', className), children: [empty?.message ?? null, empty?.action] }));
+    }
+    return (_jsx("div", { "data-slot": "tree", ref: root, role: "tree", "aria-label": label, onKeyDown: onKeyDown, className: cn('flex flex-col', className), children: _jsx(TreeLevel, { nodes: nodes, currentHref: currentHref, depth: 0 }) }));
+}
+export { Tree };

package/dist/pages/docs-shell/docs-shell.d.ts

@@ -0,0 +1,250 @@
+import type { ReactNode } from 'react';
+/**
+ * One page in a documentation tree: a title and the address it is read at.
+ *
+ * `href` is required. A page in the navigation that goes nowhere is an entry a
+ * reader can focus and not follow, and the Page renders every page entry as a
+ * native anchor so a reader can see where a destination is before taking it.
+ */
+export type DocsNavPage = {
+    type: 'page';
+    /** The words the reader meets. */
+    title: string;
+    /** The address the page is read at. */
+    href: string;
+};
+/**
+ * One group in a documentation tree: a label and the pages under it, at any
+ * depth.
+ *
+ * `href` is the group's own index page, and it is optional on purpose. A group
+ * with no index is a place in the tree and not a route, so the Page renders it
+ * as a label: no anchor, no `href`, nothing focusable. Inventing a route for it
+ * would publish an address that resolves to nothing, and rendering an anchor
+ * with no `href` would publish a destination a reader can reach and cannot
+ * follow. AlphaLens already uses the absent case to mean exactly this, in every
+ * section whose folder holds no `index.mdx`, and Atlas and Nexus style those
+ * entries out of their own stylesheets with a rule that has now become dead.
+ *
+ * `items` is required, because a group that renders a label and holds nothing
+ * is an empty rail entry rather than a group. Pass a page with no children
+ * rather than a group with none.
+ */
+export type DocsNavGroup = {
+    type: 'group';
+    /** The words on the label. A status inside them stays inside them. */
+    title: string;
+    /**
+     * The group's own index page, where it has one. Omit it for a group that is
+     * only a heading over its pages.
+     */
+    href?: string;
+    /** The pages under this group, in the order a reader should meet them. */
+    items: readonly DocsNavEntry[];
+};
+/**
+ * A rule between entries, carrying a name that is usually empty.
+ *
+ * It is a label and never a link. The alternative spelling, a page entry with an
+ * empty `href`, was what two of the three consumer sites shipped and had to
+ * restyle in their own stylesheets, because an anchor with no destination is a
+ * control that cannot be operated.
+ */
+export type DocsNavDivider = {
+    type: 'divider';
+    /** The words on the rule, which may be the empty string. */
+    title: string;
+};
+/**
+ * One entry in a documentation tree, of any of the three kinds.
+ *
+ * The union is closed, and it is a union rather than one shape with optional
+ * fields because a reader meets three different things in a rail: a destination,
+ * a label over a list, and a rule. A single shape would make all three look
+ * alike, and "a place that is a heading, not a link" is the distinction the whole
+ * arrangement turns on.
+ */
+export type DocsNavEntry = DocsNavPage | DocsNavGroup | DocsNavDivider;
+/**
+ * The two words the pager renders above the neighbouring pages' titles.
+ *
+ * Both are required, and both are the caller's: "Previous" and "Next" are this
+ * Page's own phrasing, a site that files its pages in the other direction says
+ * the opposite pair, and a Page that ships no copy ships no reader-facing copy
+ * either.
+ */
+export type DocsPagerLabels = {
+    /** The word above the previous page's title. */
+    previous: string;
+    /** The word above the next page's title. */
+    next: string;
+};
+/**
+ * The props a DocsShell takes.
+ *
+ * The navigation is data and the frame is the consumer's. Three sites publish
+ * full documentation sets and each of them has a different shape: Nexus files
+ * six sections of five pages, Atlas files four of which one holds nine pages
+ * under a single heading, and AlphaLens files six sections separated by rules
+ * and named for subject matter rather than for a documentation genre. The shape
+ * arrives in `nav` and the Page renders it, so none of the three had to be told
+ * which of the others it looks like.
+ *
+ * The document's own body is `children`, because a document is authored wherever
+ * it is authored, a Markdown pipeline or a CMS, and Prism owns the measure and
+ * the rhythm around the words rather than the words.
+ */
+export type DocsShellProps = {
+    /**
+     * The page's title, and the document's `h1`.
+     *
+     * It is optional because the three consumer sites do not agree about whether a
+     * documentation page has one: two render the frontmatter title as the page
+     * heading, and one lets the document's own Markdown own it. When it is absent
+     * the Page renders no heading at all rather than an empty one, so the document
+     * keeps exactly the outline its own content declares.
+     */
+    title?: string;
+    /**
+     * One or two sentences under the title: what this part of the documentation
+     * covers. A `ReactNode` because a site that files a page for a pipeline states
+     * the pipeline's stage as markup rather than as a sentence.
+     */
+    description?: ReactNode;
+    /**
+     * The documentation tree, in the order a reader should meet it. The whole
+     * shape arrives here, so the Page holds no opinion about how many sections a
+     * site has, how deep they nest, or what a section is called.
+     */
+    nav?: readonly DocsNavEntry[];
+    /**
+     * The headings inside this page, in document order, for the contents rail.
+     *
+     * It is the consumer's document that knows its own outline, because Prism does
+     * not parse Markdown and a Page that guessed at it would guess wrong on every
+     * document rather than on some. Pass the whole outline or none: a partial one
+     * is a contents list that lies about the page.
+     */
+    toc?: readonly DocsNavEntry[];
+    /**
+     * The address of the page being rendered. The rail marks it with
+     * `aria-current="page"` and the pager derives its two neighbours from it, so
+     * the same navigation renders a different pager for every page without the
+     * caller deriving anything.
+     */
+    currentHref?: string;
+    /**
+     * The accessible name of the rail. Required whenever `nav` is passed, because
+     * it is a word a reader hears and a Page that ships no copy ships no
+     * reader-facing copy either.
+     */
+    navLabel: string;
+    /**
+     * The accessible name of the contents rail. Required whenever `toc` is passed,
+     * for the same reason `navLabel` is.
+     */
+    tocLabel: string;
+    /**
+     * The accessible name of the pager. Required whenever there is a neighbour to
+     * reach, for the same reason `navLabel` is.
+     */
+    pagerLabel: string;
+    /**
+     * The two words the pager renders above the neighbouring pages' titles.
+     * Required whenever either neighbour exists, for the same reason `navLabel`
+     * is.
+     */
+    pagerLabels: DocsPagerLabels;
+    /**
+     * The document's own body. Any flow content: paragraphs, headings, lists,
+     * code, images, tables. `Prose` holds it to the reading measure and to the
+     * block rhythm, and it is passed `fullWidth` so the document fills the column
+     * the frame gives it rather than sitting in a second measure inside one.
+     */
+    children: ReactNode;
+    /**
+     * A slot above the frame, inside the container: a breadcrumb trail, a version
+     * picker, a search field. A slot rather than a prop because each of those is a
+     * Block, and a Page that took one per prop would be a Page whose interface
+     * lists the whole catalogue.
+     */
+    header?: ReactNode;
+    /**
+     * A slot below the frame, inside the container: a feedback prompt, a link back
+     * to the section index, a support address.
+     */
+    footer?: ReactNode;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A documentation screen: a navigation rail, the document, a contents rail and
+ * the pager to the neighbouring pages.
+ *
+ * **This is the Page the other three NaniSoft sites import, and the name is
+ * theirs.** All three already read `import { DocsShell, type DocsNavEntry }
+ * from '@nanisoft/prism-ui/pages'` in their own document template, and all three
+ * map their page tree into that shape in their own `lib/to-prism-tree`. A
+ * published name cannot be cheaply changed and there is no redirect lane for item
+ * routes, so the name follows the three import lines rather than this file's
+ * shape. It was `docs-shell` in the retired line, where it was an empty
+ * `div` plus a class name that each site then had to style from scratch, and it
+ * is `docs-shell` here because that is what the three call sites already say.
+ *
+ * **A section is a label, not a control.** It carries no status, no badge, no
+ * count, no collapse and no sort, and that is the whole of its interface. The
+ * reason is specific: AlphaLens files its documentation as a pipeline, where
+ * "Unified data contract (approved)" is a stage of the work and not a topic a
+ * reader may visit in any order, and every structural affordance says the
+ * opposite. A status in the title is part of the title and stays there as words:
+ * the Page reads no parentheses, matches no vocabulary, and renders no pill
+ * beside a heading that has one. A tree is data, and a Page that parsed a
+ * consumer's data would be a Page that had opinions about it.
+ *
+ * **A group with no index is a label rather than a route.** `href` is optional
+ * on `DocsNavGroup` for exactly that, and the absence means the label. The three
+ * consumer sites all write `url: node.index?.url ?? ''` in their own adapter
+ * today, which is the same fact spelled as an empty string, and two of the three
+ * then carry a stylesheet rule that styles the resulting anchor-with-no-href
+ * back into a label. Naming the case in the type makes those two rules dead
+ * rather than load-bearing, and the type is the only place that had to change.
+ *
+ * **The pager is derived from the navigation rather than passed.** The rail
+ * already knows every page and the order a reader meets them in, and deriving the
+ * two neighbours from that plus `currentHref` removes one derivation from each
+ * of the three sites. It is derived rather than passed for a second reason: a
+ * caller who passes neighbours can pass a neighbour that is not in the tree, and
+ * this is the one arrangement where a reader would notice.
+ *
+ * **The consumer supplies two orders and the Page imposes neither.** `nav` is in
+ * the order the rail shows, and `toc` is in the order the contents rail shows.
+ * Both are read as given: nothing is sorted, deduplicated or alphabetised, and a
+ * tree whose sections are named for subject matter reads in the order its
+ * author filed it. A Page that sorted its rail would flatten the one thing the
+ * three sites disagree about and cannot both be right about.
+ *
+ * **The rail is bounded in height.** Atlas files nineteen pages and AlphaLens
+ * files twenty-seven, so the taller tree is half again as long, and an unbounded
+ * rail on a tall tree is a rail that pushes the document below the fold before
+ * the reader has read a line of it. The rail and the contents rail are each
+ * capped against the viewport and scroll inside it, so a nineteen-page tree and a
+ * twenty-seven-page tree are both a full screen and neither is a page-long
+ * sidebar.
+ *
+ * It is a Page rather than a Block because it is a whole screen and it is the
+ * screen a content pipeline targets: a route that reads one document and hands
+ * it the page tree, the outline and the current address. A Block would be the
+ * rail, and the rail's job is not separable from the screen's, because the
+ * arrangement of rail, document, contents and pager is what the three sites each
+ * wrote separately and are here written once.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, so a consumer renders it from whichever route their framework names
+ * and hands it the document their pipeline produced.
+ */
+export declare function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }: DocsShellProps): import("react").JSX.Element;
+export default DocsShell;
+//# sourceMappingURL=docs-shell.d.ts.map

package/dist/pages/docs-shell/docs-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-shell.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/docs-shell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAW,EACX,GAAG,EACH,GAAG,EACH,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,cAAc,+BAmFhB;AA4QD,eAAe,SAAS,CAAA"}