@nanisoft/prism-ui 0.5.1 → 0.6.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/index.d.ts

@@ -14,4 +14,8 @@ export { SettingsPage } from './settings-page';
 export type { SettingsPageProps, SettingsPageTab } from './settings-page';
 export { AuthPage } from './auth-page';
 export type { AuthPageProps, AuthPageAside } from './auth-page';
+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';
 //# 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"}
+{"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"}

package/dist/pages/index.js

@@ -10,3 +10,5 @@ export { MarketingPage } from './marketing-page';
 export { DashboardPage } from './dashboard-page';
 export { SettingsPage } from './settings-page';
 export { AuthPage } from './auth-page';
+export { NotFoundPage } from './not-found-page';
+export { BlogPostPage } from './blog-post-page';

package/dist/pages/not-found-page/index.d.ts

@@ -0,0 +1,112 @@
+import type { ReactNode } from 'react';
+/**
+ * One way out of a page that was not found.
+ *
+ * A destination, and the words for it. Both are required, because a not-found
+ * page with no way out is a dead end with a message on it, and a link with no
+ * words is a shape a reader has to guess at.
+ */
+export type NotFoundLink = {
+    /** The words of the link. */
+    label: string;
+    /** Where it goes. */
+    href: string;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Almost never right here: a reader who
+     * followed a broken link and is sent to a new tab has to find their way back.
+     */
+    newTab?: boolean;
+};
+/**
+ * The props a NotFoundPage takes.
+ *
+ * Every string is a prop and the Page ships none. There is no "404", no "this
+ * page does not exist", no product name and no default set of links: a not-found
+ * page that hardcoded any of them would be a page that made a claim about a
+ * product it knows nothing about, and the one page on a site that every reader
+ * and no crawler will see is the worst place to hardcode a sentence.
+ */
+export type NotFoundPageProps = {
+    /**
+     * The status code, shown as the page's own `h1`. Required, and a string rather
+     * than a number because it is displayed, not computed: a Page never decides
+     * what code it is answering.
+     */
+    code: string;
+    /**
+     * The headline under the code: the sentence that says what happened. It is the
+     * part a reader actually reads, and it is the caller's because every product
+     * says it differently - "No node here", "This page does not exist (yet)".
+     */
+    title: string;
+    /**
+     * One or two sentences under the headline, for anything a reader should know
+     * before they follow one of the links: that the URL may be mistyped, that the
+     * page is planned, that a search would find it.
+     */
+    description?: string;
+    /**
+     * The ways out, in the order a reader should see them. Put the destination
+     * most likely to help first; a not-found page that offers a homepage link
+     * before the documentation sends a reader further from what they wanted.
+     */
+    links: readonly NotFoundLink[];
+    /**
+     * The accessible name of the row of ways out. It is required, because it is a
+     * word a reader hears and a Page that ships no copy ships no reader-facing copy
+     * either. "Ways out" is the Page's own phrasing; a site that files its
+     * destinations differently names the same landmark differently.
+     */
+    linksLabel: string;
+    /**
+     * A slot for whatever else the site wants to say here: a search box, a list of
+     * recent posts, a contact address.
+     */
+    children?: ReactNode;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A complete not-found screen: the code, what happened, and the ways out.
+ *
+ * All four NaniSoft sites compose one, each in its own `not-found` route, and
+ * three of them are the same six lines with a different product name on it: a
+ * display title carrying the code, one muted sentence, and two or three links.
+ * The fourth wrote the same thing in its own markup. Four hand-written screens
+ * for one shape.
+ *
+ * It is a Page rather than a Block because it is a whole screen: it owns the
+ * document's `h1`, it is what a router renders when a route does not resolve, and
+ * it composes `Section`, `Heading`, `Text`, `Prose` and `CtaLink` into the one
+ * arrangement of them that answers "this is not here". A Block would be a band
+ * of that arrangement, and the band's job is not separable from the screen's:
+ * there is one correct page here and it is short.
+ *
+ * **The code is the `h1` and the sentence is not.** A not-found page whose
+ * `h1` is "Page not found" gives a search engine and a screen reader nothing
+ * distinct to index, and the code is the one string on the page that is the same
+ * for every broken URL. The code takes the display step and the sentence takes
+ * the muted one, which is the reverse of what a reader sees first and the right
+ * way round for anything that reads the outline.
+ *
+ * The links are `CtaLink`, so each one is a native anchor with a destination a
+ * browser can show, copy and open in a new tab. A not-found page is the one place
+ * on a site where a reader most wants to see where a link goes before following
+ * it, because they have just followed one that went nowhere.
+ *
+ * The page carries no `noindex` and no `robots` directive, because this is a
+ * component and not a route: what a not-found response is indexed as is the
+ * consumer's server's decision, and a Page that declared it would be a Page
+ * making a claim about a deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, which is what lets a consumer render it from whichever not-found
+ * route their framework names.
+ */
+export declare function NotFoundPage({ code, title, description, links, linksLabel, children, className, }: NotFoundPageProps): import("react").JSX.Element;
+export default NotFoundPage;
+//# sourceMappingURL=index.d.ts.map

package/dist/pages/not-found-page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/not-found-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,UAAU,EACV,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BA+BnB;AAED,eAAe,YAAY,CAAA"}

package/dist/pages/not-found-page/index.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 not-found screen: the code, what happened, and the ways out.
+ *
+ * All four NaniSoft sites compose one, each in its own `not-found` route, and
+ * three of them are the same six lines with a different product name on it: a
+ * display title carrying the code, one muted sentence, and two or three links.
+ * The fourth wrote the same thing in its own markup. Four hand-written screens
+ * for one shape.
+ *
+ * It is a Page rather than a Block because it is a whole screen: it owns the
+ * document's `h1`, it is what a router renders when a route does not resolve, and
+ * it composes `Section`, `Heading`, `Text`, `Prose` and `CtaLink` into the one
+ * arrangement of them that answers "this is not here". A Block would be a band
+ * of that arrangement, and the band's job is not separable from the screen's:
+ * there is one correct page here and it is short.
+ *
+ * **The code is the `h1` and the sentence is not.** A not-found page whose
+ * `h1` is "Page not found" gives a search engine and a screen reader nothing
+ * distinct to index, and the code is the one string on the page that is the same
+ * for every broken URL. The code takes the display step and the sentence takes
+ * the muted one, which is the reverse of what a reader sees first and the right
+ * way round for anything that reads the outline.
+ *
+ * The links are `CtaLink`, so each one is a native anchor with a destination a
+ * browser can show, copy and open in a new tab. A not-found page is the one place
+ * on a site where a reader most wants to see where a link goes before following
+ * it, because they have just followed one that went nowhere.
+ *
+ * The page carries no `noindex` and no `robots` directive, because this is a
+ * component and not a route: what a not-found response is indexed as is the
+ * consumer's server's decision, and a Page that declared it would be a Page
+ * making a claim about a deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, which is what lets a consumer render it from whichever not-found
+ * route their framework names.
+ */
+export function NotFoundPage({ code, title, description, links, linksLabel, children, className, }) {
+    return (_jsx(Section, { className: className, children: _jsxs("div", { className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: "h1", size: "4xl", className: "text-muted-foreground font-mono", children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h2", size: "2xl", children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
+}
+export default NotFoundPage;

package/dist/provider/provider.d.ts

@@ -7,6 +7,11 @@
  * the same two markup attributes the declarative form uses. There is no
  * override, merge, token, className or style prop: the provider's only outputs
  * are the document-element attributes and context (ticket 07).
+ *
+ * It resolves through `resolveTheme`, the one rule the boot script also
+ * implements, and it never writes `THEME_ORIGIN_ATTRIBUTE`: the script is that
+ * attribute's only writer, and two writers would turn a record of the origin
+ * into a race.
  */
 import { type ReactNode } from 'react';
 import { type Mode, type PackId } from '../theming';

package/dist/provider/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider/provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAEd,OAAO,EAML,KAAK,IAAI,EACT,KAAK,MAAM,EACZ,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;IACV,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B,UAAU,EAAE,MAAM,IAAI,CAAA;CACvB,CAAA;AAID,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAwBD,wBAAgB,aAAa,CAAC,EAC5B,WAAuB,EACvB,WAAqB,EACrB,UAAgC,EAChC,QAAQ,GACT,EAAE,kBAAkB,+BA8CpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAM1C"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider/provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAEd,OAAO,EAML,KAAK,IAAI,EACT,KAAK,MAAM,EAEZ,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;IACV,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B,UAAU,EAAE,MAAM,IAAI,CAAA;CACvB,CAAA;AAID,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAyCD,wBAAgB,aAAa,CAAC,EAC5B,WAAuB,EACvB,WAAqB,EACrB,UAAgC,EAChC,QAAQ,GACT,EAAE,kBAAkB,+BAuHpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAM1C"}

package/dist/provider/provider.js

@@ -9,67 +9,158 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * the same two markup attributes the declarative form uses. There is no
  * override, merge, token, className or style prop: the provider's only outputs
  * are the document-element attributes and context (ticket 07).
+ *
+ * It resolves through `resolveTheme`, the one rule the boot script also
+ * implements, and it never writes `THEME_ORIGIN_ATTRIBUTE`: the script is that
+ * attribute's only writer, and two writers would turn a record of the origin
+ * into a race.
  */
-import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
-import { DEFAULT_STORAGE_KEY, MODES, PACKS, parseStoredTheme, themeAttributes, } from '../theming';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { DEFAULT_STORAGE_KEY, PACK_ATTRIBUTE, readLegacyMode, resolveTheme, themeAttributes, } from '../theming';
 const PrismThemeContext = createContext(null);
 function applyDocumentAttributes(pack, mode) {
     const root = document.documentElement;
     const { 'data-pack': packAttribute, className } = themeAttributes({ pack, mode });
     if (packAttribute)
-        root.setAttribute('data-pack', packAttribute);
+        root.setAttribute(PACK_ATTRIBUTE, packAttribute);
     else
-        root.removeAttribute('data-pack');
+        root.removeAttribute(PACK_ATTRIBUTE);
     if (className)
         root.classList.add('dark');
     else
         root.classList.remove('dark');
 }
-function packFromDocument(fallback) {
-    const attribute = document.documentElement.getAttribute('data-pack');
-    return attribute && PACKS.includes(attribute)
-        ? attribute
-        : fallback;
+/** One guarded read. A blocked or full store must not break the page. */
+function read(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/** One guarded write. The attributes are already applied when this fails. */
+function persist(key, pack, mode) {
+    try {
+        localStorage.setItem(key, JSON.stringify({ pack, mode }));
+    }
+    catch {
+        // A blocked or full localStorage must not break theme switching. The
+        // attributes are already applied, so the visible behaviour is unchanged.
+    }
 }
-function modeFromDocument(fallback) {
-    return document.documentElement.classList.contains('dark') ? 'dark' : fallback;
+function retire(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch {
+        // Nothing to do: a key that cannot be removed is read again next load,
+        // recovers the same decision, and writes the same pair.
+    }
 }
 export function PrismProvider({ defaultPack = 'default', defaultMode = 'light', storageKey = DEFAULT_STORAGE_KEY, children, }) {
-    const [pack, setPackState] = useState(defaultPack);
-    const [mode, setModeState] = useState(defaultMode);
-    const [resolved, setResolved] = useState(false);
     /*
-     * Resolution order on mount: stored value, then the server-rendered attribute,
-     * then the default. A server-rendered pack therefore survives hydration
-     * instead of flashing to the default.
+     * The resolution, and whether a decision has been made. Two pieces of state
+     * for two different questions, which is why the old `resolved` flag was not
+     * enough on its own:
+     *
+     *   - `theme` is null until the store has been read. It gates APPLY, because
+     *     applying the default over a server-rendered pack before resolution is
+     *     the flash the resolution order exists to prevent. It carries the
+     *     origin, so the recovery below can read it without a second lookup.
+     *   - `decided` is a ref, not state, because it must be readable by the write
+     *     effect without causing a render, and settable synchronously by a caller
+     *     whose state update has not been committed yet. It gates WRITE.
+     *
+     * A ref also cannot be re-rendered into an extra effect pass, which is what
+     * would have made the write fire once for the flag and once for the value.
+     */
+    const [theme, setTheme] = useState(null);
+    const decided = useRef(false);
+    /*
+     * Resolution on mount, through the one shared rule: the stored value, then a
+     * key this line no longer writes, then what the server rendered, then the
+     * defaults. A server-rendered pack therefore survives hydration.
      */
     useEffect(() => {
-        const stored = parseStoredTheme(localStorage.getItem(storageKey));
-        const next = stored ?? { pack: packFromDocument(defaultPack), mode: modeFromDocument(defaultMode) };
-        setPackState(next.pack);
-        setModeState(next.mode);
-        setResolved(true);
+        const recovered = readLegacyMode(read);
+        const next = resolveTheme({
+            stored: read(storageKey),
+            legacy: recovered?.mode ?? null,
+            documentPack: document.documentElement.getAttribute(PACK_ATTRIBUTE),
+            documentDark: document.documentElement.classList.contains('dark'),
+            defaultPack,
+            defaultMode,
+        });
+        if (next.origin === 'legacy' && recovered) {
+            /*
+             * The recovery write. A decision taken from a key this line no longer
+             * writes is put in the key it does write, and the old key is retired in
+             * the same breath, which is what makes the clause self-disabling: the
+             * next load finds nothing to recover, so a reader is migrated once and
+             * the population the clause can still reach only ever shrinks.
+             */
+            persist(storageKey, next.pack, next.mode);
+            retire(recovered.key);
+        }
+        // A caller that decided in a layout effect before this ran keeps its value.
+        if (!decided.current)
+            setTheme(next);
     }, [storageKey, defaultPack, defaultMode]);
     /*
-     * Persist and apply only after resolution, so the first client commit never
-     * writes the defaults over a stored or server-rendered choice.
+     * Apply always, once there is a resolution; persist only on a decision.
+     *
+     * The first resolution from the document or the defaults writes nothing, so a
+     * visitor who never touched the toggle ends the load with an empty store and
+     * a site that changes its default reaches everyone who has not chosen.
      */
     useEffect(() => {
-        if (!resolved)
+        if (!theme)
             return;
-        applyDocumentAttributes(pack, mode);
-        try {
-            localStorage.setItem(storageKey, JSON.stringify({ pack, mode }));
-        }
-        catch {
-            // A blocked or full localStorage must not break theme switching. The
-            // attributes are already applied, so the visible behaviour is unchanged.
-        }
-    }, [resolved, pack, mode, storageKey]);
-    const setPack = useCallback((next) => setPackState(next), []);
-    const setMode = useCallback((next) => setModeState(next), []);
-    const toggleMode = useCallback(() => setModeState((current) => (current === 'dark' ? MODES[0] : MODES[1])), []);
-    const value = useMemo(() => ({ pack, mode, setPack, setMode, toggleMode }), [pack, mode, setPack, setMode, toggleMode]);
+        applyDocumentAttributes(theme.pack, theme.mode);
+        if (decided.current)
+            persist(storageKey, theme.pack, theme.mode);
+    }, [theme, storageKey]);
+    const setPack = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: next,
+            mode: current?.mode ?? defaultMode,
+            origin: 'stored',
+        }));
+    }, [defaultMode]);
+    const setMode = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: next,
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    /*
+     * The pair is a closed union of two members, so the other one is the other
+     * member. Spelling it out costs nothing and does not hide the coupling behind
+     * an index into a list this file does not otherwise need.
+     *
+     * The three setters all fall back to the consumer's own default rather than
+     * to the neutral one, so a decision taken before the store has been read
+     * pairs the chosen axis with the site's default and not with a guess.
+     */
+    const toggleMode = useCallback(() => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: current?.mode === 'dark' ? 'light' : 'dark',
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    const value = useMemo(() => ({
+        pack: theme?.pack ?? defaultPack,
+        mode: theme?.mode ?? defaultMode,
+        setPack,
+        setMode,
+        toggleMode,
+    }), [theme, defaultPack, defaultMode, setPack, setMode, toggleMode]);
     return _jsx(PrismThemeContext.Provider, { value: value, children: children });
 }
 /**