@nanisoft/prism-ui 0.5.1 → 0.7.0

package/dist/pages/blog-post-page/index.d.ts

@@ -0,0 +1,174 @@
+import type { ReactNode } from 'react';
+/**
+ * One tag on a post, or one step in the trail to the next one.
+ *
+ * `href` is optional and a tag without one renders as text. A tag that goes
+ * somewhere is a link, a tag that does not is a word, and a post's tags are
+ * usually the words.
+ */
+export type BlogPostTag = {
+    /** The word on the tag. */
+    label: string;
+    /** Where the tag goes, for a tag that filters an archive. */
+    href?: string;
+};
+/**
+ * One neighbour of this post: the title and where it is.
+ *
+ * `title` and `href` are both required. A next post with no title is an arrow
+ * with a destination and no promise about what is at the other end, which is the
+ * one thing a reader deciding whether to click cannot afford.
+ */
+export type BlogPostNeighbour = {
+    /** The post's title. */
+    title: string;
+    /** Where the post is. */
+    href: string;
+};
+/**
+ * The two words the trail renders above the neighbouring posts' titles.
+ *
+ * Both are required, and both are the caller's: "Previous" and "Next" are this
+ * Page's own phrasing, a site that files posts newest-last says the opposite pair,
+ * and a Page that ships no copy ships no reader-facing copy either.
+ */
+export type BlogPostTrailLabels = {
+    /** The word above the previous post's title. */
+    previous: string;
+    /** The word above the next post's title. */
+    next: string;
+};
+/**
+ * The props a BlogPostPage takes.
+ *
+ * The post's own text is `children`, because a post's body is authored wherever it
+ * is authored - a Markdown file, a CMS, a headless store - and Prism owns the
+ * measure and the rhythm around it, not the words. Everything that is a *fact*
+ * about the post rather than its text is a prop: the title, the standfirst, the
+ * date, the tags and the neighbours.
+ */
+export type BlogPostPageProps = {
+    /**
+     * The post's title. It is the page's `h1`, so the page has exactly one and it
+     * is the post's name.
+     */
+    title: string;
+    /**
+     * The standfirst: one or two sentences under the title that say what the post
+     * is about. It is a prop rather than the first paragraph of the body because a
+     * reader deciding whether to read needs it before the body starts, and because
+     * it is what an index, a feed and a search result show.
+     */
+    description?: string;
+    /**
+     * The publication date, already formatted for display, and the machine value
+     * for the `time` element's `dateTime`. Both are props, and the machine one is
+     * required: `dateTime` is what a reader's browser, a feed reader and a search
+     * engine use to order posts, and a formatted string is none of those.
+     */
+    date: string;
+    /**
+     * The date in a machine-readable form, `YYYY-MM-DD`, carried on the `time`
+     * element. Required, and deliberately not derived from `date`: parsing a
+     * formatted date back into an ISO one is a guess about a locale, and a guess
+     * in a `datetime` attribute is a wrong date in a feed.
+     */
+    dateTime: string;
+    /** Who wrote the post. A name, or a link to an author page. */
+    author?: ReactNode;
+    /**
+     * The tags on the post, in the order a reader should meet them. Omit them for a
+     * post with none: an empty row of badges is a row of nothing.
+     */
+    tags?: readonly BlogPostTag[];
+    /** How long the post takes to read, in the consumer's own words. */
+    readingTime?: string;
+    /**
+     * The post's body. Any flow content: paragraphs, headings, lists, code, images,
+     * tables. `Prose` holds it to the reading measure and to the block rhythm.
+     */
+    children: ReactNode;
+    /**
+     * The post before this one and the post after it, for the trail at the foot of
+     * the page. Omit the half there is no neighbour for; a "previous" link with no
+     * previous post is a link to nothing.
+     */
+    previous?: BlogPostNeighbour;
+    next?: BlogPostNeighbour;
+    /**
+     * The two words the trail renders above the neighbouring posts' titles. Required
+     * whenever either neighbour is passed, because they are words a reader reads and
+     * a Page that ships no copy ships no reader-facing copy either.
+     */
+    trailLabels: BlogPostTrailLabels;
+    /**
+     * The accessible name of the trail between the neighbouring posts. It is
+     * required whenever either neighbour is passed, because it is a word a reader
+     * hears and a Page that ships no copy ships no reader-facing copy either. "More
+     * posts" is the Page's own phrasing and a site that files posts by release calls
+     * the same landmark something else.
+     */
+    trailLabel: string;
+    /**
+     * The way back to the archive the post is filed in, rendered as one call to
+     * action under the trail. A prop rather than a hardcoded "back to the index",
+     * because the words and the route belong to the site that publishes the post
+     * and a Page that held either would be a Page making a claim about a consumer's
+     * own site.
+     */
+    indexLink?: BlogPostNeighbour;
+    /**
+     * A slot for what comes after the trail: a related-posts grid, a newsletter
+     * form, a call to action. A slot rather than a prop because every one of those
+     * is a Block, and a Page that took a Block per prop would be a Page whose
+     * interface lists the whole catalogue.
+     */
+    footer?: ReactNode;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A complete blog post screen: the title, the standfirst, the byline, the body at
+ * the measure, and the trail to the neighbouring posts.
+ *
+ * All four NaniSoft sites publish a blog, each with four posts and the same
+ * frontmatter: a title, a description, a date and a list of tags. Each one then
+ * rendered that frontmatter in its own component, with its own wrapper, its own
+ * measure and its own treatment of the date, and each of them wrote the trail to
+ * the neighbouring posts separately or not at all.
+ *
+ * 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
+ * its frontmatter to this Page. The Page is what makes the frontmatter a
+ * contract, because a field that is not a prop is a field nothing checks.
+ *
+ * **The date is two props.** `date` is the words a reader sees and `dateTime` is
+ * the machine value on the `time` element, and they are kept apart because
+ * parsing a formatted date back into an ISO one is a guess about a locale. A
+ * wrong date in a `datetime` attribute is a wrong date in a feed reader and in a
+ * search result, and neither reader can see the string that was wrong. This is
+ * the arrangement every one of the four sites needs and none of them has, because
+ * each of them formats its date in one place and has nowhere else to put the ISO
+ * value.
+ *
+ * The body is `children` and it is held by `Prose`, not by a set of per-element
+ * props. A post's body is authored somewhere else - a Markdown pipeline, a CMS -
+ * and a Page that took `paragraphs` and `headings` as arrays would be a Page that
+ * had to be handed a parsed document, which is a second representation of
+ * something the consumer's own pipeline already owns.
+ *
+ * The trail is one `nav` with two links, and it renders only the halves it is
+ * given. A previous link on the oldest post is a link to the first post a reader
+ * has already read, and a next link on the newest is a promise the site cannot
+ * keep.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, so a consumer renders it from a server route and hands it the
+ * document their pipeline produced.
+ */
+export declare function BlogPostPage({ title, description, date, dateTime, author, tags, readingTime, children, previous, next, trailLabels, trailLabel, indexLink, footer, className, }: BlogPostPageProps): import("react").JSX.Element;
+export default BlogPostPage;
+//# sourceMappingURL=index.d.ts.map

package/dist/pages/blog-post-page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/blog-post-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAQtC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IAC7B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACxB;;;;OAIG;IACH,WAAW,EAAE,mBAAmB,CAAA;IAChC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,GACV,EAAE,iBAAiB,+BAgFnB;AAED,eAAe,YAAY,CAAA"}

package/dist/pages/blog-post-page/index.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from '../../components/ui/badge';
+import { CtaLink } from '../../components/ui/cta-link';
+import { Heading, Text } from '../../components/ui/typography';
+import { Prose } from '../../components/ui/prose';
+import { Section } from '../../components/ui/section';
+/**
+ * A complete blog post screen: the title, the standfirst, the byline, the body at
+ * the measure, and the trail to the neighbouring posts.
+ *
+ * All four NaniSoft sites publish a blog, each with four posts and the same
+ * frontmatter: a title, a description, a date and a list of tags. Each one then
+ * rendered that frontmatter in its own component, with its own wrapper, its own
+ * measure and its own treatment of the date, and each of them wrote the trail to
+ * the neighbouring posts separately or not at all.
+ *
+ * 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
+ * its frontmatter to this Page. The Page is what makes the frontmatter a
+ * contract, because a field that is not a prop is a field nothing checks.
+ *
+ * **The date is two props.** `date` is the words a reader sees and `dateTime` is
+ * the machine value on the `time` element, and they are kept apart because
+ * parsing a formatted date back into an ISO one is a guess about a locale. A
+ * wrong date in a `datetime` attribute is a wrong date in a feed reader and in a
+ * search result, and neither reader can see the string that was wrong. This is
+ * the arrangement every one of the four sites needs and none of them has, because
+ * each of them formats its date in one place and has nowhere else to put the ISO
+ * value.
+ *
+ * The body is `children` and it is held by `Prose`, not by a set of per-element
+ * props. A post's body is authored somewhere else - a Markdown pipeline, a CMS -
+ * and a Page that took `paragraphs` and `headings` as arrays would be a Page that
+ * had to be handed a parsed document, which is a second representation of
+ * something the consumer's own pipeline already owns.
+ *
+ * The trail is one `nav` with two links, and it renders only the halves it is
+ * given. A previous link on the oldest post is a link to the first post a reader
+ * has already read, and a next link on the newest is a promise the site cannot
+ * keep.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, so a consumer renders it from a server route and hands it the
+ * document their pipeline produced.
+ */
+export function BlogPostPage({ title, description, date, dateTime, author, tags, readingTime, children, previous, next, trailLabels, trailLabel, indexLink, footer, className, }) {
+    return (_jsxs(Section, { className: className, children: [_jsxs("article", { "data-slot": "blog-post", className: "flex flex-col gap-8", children: [_jsxs("header", { className: "flex flex-col gap-4", children: [_jsx(Heading, { as: "h1", size: "3xl", children: title }), description ? (_jsx(Text, { size: "lg", className: "text-muted-foreground max-w-measure", children: description })) : null, _jsxs("div", { className: "text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-2 text-sm", children: [author ? _jsx("span", { className: "text-foreground font-medium", children: author }) : null, _jsx("time", { dateTime: dateTime, children: date }), readingTime ? _jsx("span", { children: readingTime }) : null] }), tags && tags.length > 0 ? (_jsx("ul", { className: "flex flex-wrap items-center gap-2", children: tags.map((tag) => (_jsx("li", { children: tag.href ? (_jsx("a", { href: tag.href, className: "rounded-sm", "aria-label": `Posts tagged ${tag.label}`, children: _jsx(Badge, { variant: "secondary", children: tag.label }) })) : (_jsx(Badge, { variant: "secondary", children: tag.label })) }, tag.label))) })) : null] }), _jsx(Prose, { children: children }), previous || next ? (_jsxs("nav", { "aria-label": trailLabel, className: "border-border grid gap-4 border-t pt-6 sm:grid-cols-2", children: [previous ? (_jsxs("a", { href: previous.href, className: "flex flex-col gap-1 rounded-sm", children: [_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: trailLabels.previous }), _jsx("span", { className: "text-sm font-semibold", children: previous.title })] })) : null, next ? (_jsxs("a", { href: next.href, className: "flex flex-col gap-1 rounded-sm sm:items-end sm:text-right", children: [_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: trailLabels.next }), _jsx("span", { className: "text-sm font-semibold", children: next.title })] })) : null] })) : null, footer ? _jsx("div", { className: "border-border border-t pt-8", children: footer }) : null] }), indexLink ? (_jsx("div", { className: "mt-10 flex justify-center", children: _jsx(CtaLink, { href: indexLink.href, variant: "outline", children: indexLink.title }) })) : null] }));
+}
+export default BlogPostPage;

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