@nanisoft/prism-ui 0.6.0 → 0.7.0

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,aAAa,yCAA0C,CAAA;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,eAAO,MAAM,oBAAoB,sHAQvB,CAAA;AACV,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAA;CAChC;AAED,eAAO,MAAM,OAAO,EAAE,SAAS,WAAW,EA0pBzC,CAAA;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,GAAE,SAAS,WAAW,EAAY,GAAG,WAAW,EAAE,CAEnF;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAE1D,CAAA"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,aAAa,yCAA0C,CAAA;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,eAAO,MAAM,oBAAoB,sHAQvB,CAAA;AACV,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAA;CAChC;AAED,eAAO,MAAM,OAAO,EAAE,SAAS,WAAW,EAqqBzC,CAAA;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,GAAE,SAAS,WAAW,EAAY,GAAG,WAAW,EAAE,CAEnF;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAE1D,CAAA"}

package/dist/catalog.js

@@ -664,6 +664,16 @@ export const catalog = [
         exports: ['BlogPostPage'],
         status: 'stable',
     },
+    {
+        name: 'DocsShell',
+        slug: 'docs-shell',
+        kind: 'page',
+        category: null,
+        description: 'A documentation screen: a navigation rail whose shape arrives as data, the document at the measure, a contents rail, and a pager derived from the navigation rather than passed.',
+        source: 'src/pages/docs-shell/index.tsx',
+        exports: ['DocsShell'],
+        status: 'stable',
+    },
 ];
 /** Returns the catalogue ordered for display and keyed for lookup. */
 export function buildCatalog(items = catalog) {

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"}

package/dist/pages/docs-shell/docs-shell.js

@@ -0,0 +1,197 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Prose } from '../../components/ui/prose';
+import { Heading, Text } from '../../components/ui/typography';
+import { cn } from '../../lib/utils';
+/**
+ * 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 function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }) {
+    const rail = nav && nav.length > 0 ? nav : undefined;
+    const contents = toc && toc.length > 0 ? toc : undefined;
+    const neighbours = currentHref === undefined ? undefined : deriveNeighbours(nav ?? [], currentHref);
+    return (_jsxs("div", { "data-slot": "docs-shell", className: cn('mx-auto w-full max-w-6xl px-6 py-10 lg:px-8', className), children: [header, _jsxs("div", { "data-slot": "docs-shell-frame", className: cn('flex flex-col gap-8 lg:flex-row lg:gap-10', 
+                // One column for the document, and a third for whichever rails are
+                // present. The frame is sized by what the consumer passed rather than
+                // by a fixed three-column grid, so a tree with no contents rail leaves
+                // the document the width the two remaining columns divide between
+                // them.
+                contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)] xl:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "hidden lg:col-start-1 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": navLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4", children: _jsx(NavList, { entries: rail, currentHref: currentHref, depth: 0 }) }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", size: "3xl", children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "hidden lg:col-start-3 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": tocLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto", children: _jsx(NavList, { entries: contents, currentHref: currentHref, depth: 0 }) }) })) : null] }), footer] }));
+}
+/* ------------------------------------------------------------------ *
+ * The rail
+ * ------------------------------------------------------------------ */
+/**
+ * One level of the tree as a list, at whatever depth it sits.
+ *
+ * The nesting is a rule rather than a special case: the tree is the shape the
+ * navigation has, and one level of that is the whole renderer. A tree one deep
+ * and a tree seven deep are the same code with different data, which is what
+ * lets one Page carry a site that files nine pages under a heading and a site
+ * that files six sections separated by rules.
+ */
+function NavList({ entries, currentHref, depth, }) {
+    return (_jsx("ul", { "data-slot": "docs-nav-list", "data-depth": depth, 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: entries.map((entry, index) => (_jsx(NavNode, { entry: entry, currentHref: currentHref, depth: depth }, `${entry.type}:${index}`))) }));
+}
+/**
+ * One entry, in whichever of the three shapes it arrives.
+ *
+ * The switch is on `type` rather than on the presence of fields, so an entry
+ * that arrives malformed falls to the last arm and renders nothing rather than
+ * rendering a destination it has no address for.
+ */
+function NavNode({ entry, currentHref, depth, }) {
+    if (entry.type === 'divider') {
+        // A rule between entries. 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": "docs-nav-divider", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: entry.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: entry.title })) : null }));
+    }
+    if (entry.type === 'group') {
+        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [entry.href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(entry.href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+    }
+    return (_jsx("li", { "data-slot": "docs-nav-page", children: _jsx("a", { "data-slot": "docs-nav-link", href: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === entry.href
+                ? 'text-foreground border-primary font-medium'
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title }) }));
+}
+/**
+ * Every page the tree holds, in the order a reader meets them.
+ *
+ * A group's own index page comes before the pages under it, because that is the
+ * order the tree states and the Page does not reorder it. A group with no index
+ * contributes its children and nothing else, which is the second thing that
+ * makes an absent `href` a label rather than a route: there is no page there for
+ * the pager to reach either. A divider contributes nothing at all.
+ */
+function flatten(entries, into = []) {
+    for (const entry of entries) {
+        if (entry.type === 'page') {
+            into.push({ title: entry.title, href: entry.href });
+            continue;
+        }
+        if (entry.type === 'group') {
+            if (entry.href !== undefined)
+                into.push({ title: entry.title, href: entry.href });
+            flatten(entry.items, into);
+        }
+    }
+    return into;
+}
+/**
+ * The pages either side of `currentHref`, or nothing when it is not in the tree.
+ *
+ * It returns `undefined` rather than a pair of blanks when the address is not in
+ * the navigation, because a pager with two empty halves is a rule above nothing
+ * and a reader cannot tell it from a page that has no neighbours.
+ */
+function deriveNeighbours(entries, currentHref) {
+    const flat = flatten(entries);
+    const at = flat.findIndex((entry) => entry.href === currentHref);
+    if (at === -1)
+        return undefined;
+    return { previous: flat[at - 1], next: flat[at + 1] };
+}
+/**
+ * The two pages either side of this one, rendered as native links.
+ *
+ * Each half renders only when there is a page for it. A "previous" link on the
+ * first page is a link to the page the reader has already read, and a "next"
+ * link on the last is a promise the site cannot keep.
+ */
+function Pager({ previous, next, label, labels, }) {
+    if (!previous && !next)
+        return null;
+    return (_jsxs("nav", { "aria-label": label, "data-slot": "docs-pager", className: "border-border mt-4 flex flex-wrap items-start justify-between gap-4 border-t pt-6", children: [previous ? (_jsxs("a", { href: previous.href, className: "hover:text-foreground flex flex-col rounded-sm transition-colors duration-fast ease-out", children: [_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: labels.previous }), _jsx("span", { className: "text-sm font-semibold", children: previous.title })] })) : (_jsx("span", {})), next ? (_jsxs("a", { href: next.href, className: "hover:text-foreground ms-auto flex flex-col rounded-sm text-right transition-colors duration-fast ease-out", children: [_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: labels.next }), _jsx("span", { className: "text-sm font-semibold", children: next.title })] })) : null] }));
+}
+/* ------------------------------------------------------------------ *
+ * The current address
+ * ------------------------------------------------------------------ */
+/** Under a route, or at it, and never under a route that merely starts the same. */
+function under(href, currentHref) {
+    return (href !== undefined &&
+        currentHref !== undefined &&
+        (currentHref === href || currentHref.startsWith(`${href}/`)));
+}
+/**
+ * Whether the current page is inside this group.
+ *
+ * A group with a route answers for that route and everything under it. A group
+ * without one has no route to answer with, so it asks its children, which is the
+ * only way a label can still show a reader that they are inside it.
+ */
+function containsHref(group, currentHref) {
+    if (under(group.href, currentHref))
+        return true;
+    return group.items.some((entry) => {
+        if (entry.type === 'page')
+            return under(entry.href, currentHref);
+        if (entry.type === 'group')
+            return containsHref(entry, currentHref);
+        return false;
+    });
+}
+export default DocsShell;

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

@@ -0,0 +1,3 @@
+export { DocsShell, default } from './docs-shell';
+export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACjD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/pages/docs-shell/index.js

@@ -0,0 +1 @@
+export { DocsShell, default } from './docs-shell';

package/dist/pages/index.d.ts

@@ -3,8 +3,13 @@
  *
  * A Page is a shipped, installable screen model composed of Blocks and
  * Components that receives application-owned navigation, content and data
- * (ticket 07). The v1 roster ships four Pages. Each is also importable on its
- * own subpath, `@nanisoft/prism-ui/pages/<slug>`.
+ * (ticket 07). Each is also importable on its own subpath,
+ * `@nanisoft/prism-ui/pages/<slug>`.
+ *
+ * `DocsShell` and `DocsNavEntry` keep the names the three consumer sites already
+ * import, so the name follows those import lines rather than this file's shape.
+ * A published name cannot be cheaply changed and there is no redirect lane for
+ * item routes.
  */
 export { MarketingPage } from './marketing-page';
 export type { MarketingPageProps } from './marketing-page';
@@ -18,4 +23,6 @@ export { NotFoundPage } from './not-found-page';
 export type { NotFoundPageProps, NotFoundLink } from './not-found-page';
 export { BlogPostPage } from './blog-post-page';
 export type { BlogPostPageProps, BlogPostTag, BlogPostNeighbour, BlogPostTrailLabels } from './blog-post-page';
+export { DocsShell } from './docs-shell';
+export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell';
 //# sourceMappingURL=index.d.ts.map

package/dist/pages/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC9G,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/pages/index.js

@@ -3,8 +3,13 @@
  *
  * A Page is a shipped, installable screen model composed of Blocks and
  * Components that receives application-owned navigation, content and data
- * (ticket 07). The v1 roster ships four Pages. Each is also importable on its
- * own subpath, `@nanisoft/prism-ui/pages/<slug>`.
+ * (ticket 07). Each is also importable on its own subpath,
+ * `@nanisoft/prism-ui/pages/<slug>`.
+ *
+ * `DocsShell` and `DocsNavEntry` keep the names the three consumer sites already
+ * import, so the name follows those import lines rather than this file's shape.
+ * A published name cannot be cheaply changed and there is no redirect lane for
+ * item routes.
  */
 export { MarketingPage } from './marketing-page';
 export { DashboardPage } from './dashboard-page';
@@ -12,3 +17,4 @@ export { SettingsPage } from './settings-page';
 export { AuthPage } from './auth-page';
 export { NotFoundPage } from './not-found-page';
 export { BlogPostPage } from './blog-post-page';
+export { DocsShell } from './docs-shell';