@nanisoft/prism-ui 0.6.0 → 0.8.0

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';

package/dist/styles.css

@@ -364,6 +364,9 @@
   .my-6 {
     margin-block: var(--spacing-6);
   }
+  .-ms-px {
+    margin-inline-start: -1px;
+  }
   .ms-auto {
     margin-inline-start: auto;
   }
@@ -632,6 +635,9 @@
     --tw-translate-y: var(--spacing-0\.5);
     translate: var(--tw-translate-x) var(--tw-translate-y);
   }
+  .transform {
+    transform: var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,);
+  }
   .cursor-default {
     cursor: default;
   }
@@ -822,6 +828,10 @@
     border-left-style: var(--tw-border-style);
     border-left-width: 1px;
   }
+  .border-l-2 {
+    border-left-style: var(--tw-border-style);
+    border-left-width: 2px;
+  }
   .border-border {
     border-color: var(--border);
   }
@@ -995,6 +1005,9 @@
   .p-6 {
     padding: var(--spacing-6);
   }
+  .px-0\.5 {
+    padding-inline: var(--spacing-0\.5);
+  }
   .px-1 {
     padding-inline: var(--spacing-1);
   }
@@ -1055,9 +1068,15 @@
   .py-20 {
     padding-block: var(--spacing-20);
   }
+  .ps-3 {
+    padding-inline-start: var(--spacing-3);
+  }
   .pt-0 {
     padding-top: var(--spacing-0);
   }
+  .pt-2 {
+    padding-top: var(--spacing-2);
+  }
   .pt-4 {
     padding-top: var(--spacing-4);
   }
@@ -1405,10 +1424,20 @@
   .placeholder\:text-muted-foreground::placeholder {
     color: var(--muted-foreground);
   }
+  .first\:mt-0:first-child {
+    margin-top: var(--spacing-0);
+  }
   .first\:border-t:first-child {
     border-top-style: var(--tw-border-style);
     border-top-width: 1px;
   }
+  .first\:border-t-0:first-child {
+    border-top-style: var(--tw-border-style);
+    border-top-width: 0px;
+  }
+  .first\:pt-0:first-child {
+    padding-top: var(--spacing-0);
+  }
   .last\:border-b-0:last-child {
     border-bottom-style: var(--tw-border-style);
     border-bottom-width: 0px;
@@ -1778,12 +1807,36 @@
     }
   }
   @media (width >= 64rem) {
+    .lg\:sticky {
+      position: sticky;
+    }
+    .lg\:top-20 {
+      top: var(--spacing-20);
+    }
+    .lg\:col-start-1 {
+      grid-column-start: 1;
+    }
+    .lg\:col-start-3 {
+      grid-column-start: 3;
+    }
+    .lg\:row-start-1 {
+      grid-row-start: 1;
+    }
+    .lg\:block {
+      display: block;
+    }
     .lg\:flex {
       display: flex;
     }
+    .lg\:grid {
+      display: grid;
+    }
     .lg\:hidden {
       display: none;
     }
+    .lg\:max-h-\[calc\(100svh-7rem\)\] {
+      max-height: calc(100svh - 7rem);
+    }
     .lg\:grid-cols-2 {
       grid-template-columns: repeat(2, minmax(0, 1fr));
     }
@@ -1793,12 +1846,27 @@
     .lg\:grid-cols-4 {
       grid-template-columns: repeat(4, minmax(0, 1fr));
     }
+    .lg\:grid-cols-\[15rem_minmax\(0\,1fr\)\] {
+      grid-template-columns: 15rem minmax(0,1fr);
+    }
+    .lg\:flex-row {
+      flex-direction: row;
+    }
+    .lg\:gap-10 {
+      gap: var(--spacing-10);
+    }
+    .lg\:overflow-y-auto {
+      overflow-y: auto;
+    }
     .lg\:p-6 {
       padding: var(--spacing-6);
     }
     .lg\:px-8 {
       padding-inline: var(--spacing-8);
     }
+    .lg\:pe-4 {
+      padding-inline-end: var(--spacing-4);
+    }
   }
   @media (pointer: coarse) {
     .pointer-coarse\:size-11 {
@@ -2562,6 +2630,26 @@
   inherits: false;
   initial-value: 0;
 }
+@property --tw-rotate-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-z {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-y {
+  syntax: "*";
+  inherits: false;
+}
 @property --tw-border-style {
   syntax: "*";
   inherits: false;
@@ -2829,6 +2917,11 @@
       --tw-translate-x: 0;
       --tw-translate-y: 0;
       --tw-translate-z: 0;
+      --tw-rotate-x: initial;
+      --tw-rotate-y: initial;
+      --tw-rotate-z: initial;
+      --tw-skew-x: initial;
+      --tw-skew-y: initial;
       --tw-border-style: solid;
       --tw-gradient-position: initial;
       --tw-gradient-from: #0000;

package/gates/README.md

@@ -0,0 +1,98 @@
+# `@nanisoft/prism-ui/gates`
+
+The cross-repository laws, as programs, in the package a consumer already pins
+exactly.
+
+For four years the five NaniSoft repositories coordinated through a prose
+contract mirrored in four files. It drifted into three implementations of one rule
+and one of the three rules was false, and it could not be enforced because prose
+cannot fail. This subpath is the replacement: every law is the failure message of
+a gate, and the gate is here, so a change to a law lands once and reaches every
+consumer in one release.
+
+## What a consumer holds, and what the package holds
+
+A consumer's repository holds **data**:
+
+| the consumer declares | because |
+| --- | --- |
+| its stylesheets | which sheets are its own is a fact about its own pages |
+| its pack map | the regions it allows, and why each one exists |
+| its region resolver | naming a region means knowing its own DOM |
+| its coverage floors | how many rules or routes count as having read something |
+| its destinations known to be broken | one site's content defect, with a reason |
+| its custom properties the build supplies | one site's build, one site's font |
+
+The package holds **every law**: what the judgements are, what each failure says,
+and why each one exists. A consumer that restates any of it has two rules that will
+disagree, and the disagreement is invisible until a reader sees the difference.
+
+## Running it
+
+```bash
+pnpm exec prism-gates                 # every gate prism-gates.json names
+pnpm exec prism-gates --gate=links    # one gate
+pnpm exec prism-gates --json          # machine-readable, for a test
+```
+
+In a consumer's `package.json`:
+
+```json
+{
+  "scripts": {
+    "check:gates": "prism-gates"
+  }
+}
+```
+
+And in `prism-gates.json`, at the repository root:
+
+```json
+{
+  "gateKit": 1,
+  "gates": ["pin", "retired-line", "stylesheet-ownership", "links", "hidden-state"],
+  "stylesheet-ownership": { "sheets": ["app/globals.css"], "minDeclarations": 20 },
+  "links": { "outDir": "out", "minRoutes": 30, "minAnchors": 200 },
+  "hidden-state": { "sheets": ["app/globals.css"], "minRules": 25 }
+}
+```
+
+`gateKit` is the generation of the contract the consumer is holding itself to. A
+consumer that does not state one gets the package's current generation, and a law
+rewritten in a later release is then a version the consumer has not moved to rather
+than a silent change of wording underneath it.
+
+## The laws
+
+| id | the law |
+| --- | --- |
+| `pin` | the design system is an exact version, and the token package is the component package's dependency rather than the consumer's |
+| `retired-line` | no trace of the retired component library survives |
+| `stylesheet-ownership` | a site stylesheet does not own a surface the design system owns |
+| `token-read` | a custom property that nothing declares is not a wrong colour, it is no declaration at all |
+| `links` | every internal destination resolves and every fragment names an element that exists |
+| `pack-boundary` | a pack boundary lands on a mark, and a declared region set is the whole of what may carry a second pack |
+| `hidden-state` | a CSS-authored hidden state is escapable, and its exit is not a clock |
+
+The full text of each, and the failure each one prevents, is in `laws.mjs` and is
+printed by the gate that holds it. It is not restated here on purpose: this file is
+the one place a reader looks when a build is red, and a second copy of a law in a
+second file is a second rule.
+
+## What a gate here cannot do
+
+Stated here rather than left for a reader to discover:
+
+- **It reads text, not a cascade.** The ownership gate sees a selector and a
+  declaration. It does not resolve which rule wins.
+- **It reads the emitted export, not a browser.** The links and pack-boundary gates
+  read `out/`. Run the build first; a gate that read nothing fails rather than
+  reporting a clean page.
+- **It does not see a runtime.** A `data-pack` attribute set after paint, or a
+  token read in client code, is outside every gate in this kit.
+- **A stylesheet half is not a rendered half.** A consumer that ships a hidden
+  state also needs a test that renders with scripting switched off.
+
+These limits are printed on every run as well, because a gate that appeared to
+resolve cascades and did not would be worse than no gate: it would retire the
+question.

package/gates/cli.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * The consumer's gate chain. One program, one configuration file, one exit code.
+ *
+ * A consumer's repository holds data: its roots, its sheet, its pack map, its
+ * coverage floors, its destinations it knows are broken. It does not hold the
+ * wording of a rule, because a wording held in four places is four rules that will
+ * disagree, and the version they disagree at is the version nobody chose.
+ *
+ *     pnpm prism-gates                       # every gate the configuration names
+ *     pnpm prism-gates --gate=links          # one gate
+ *     pnpm prism-gates --gate=links --json   # machine-readable, for a test
+ *
+ * `--json` exists because the assertion that matters about a gate is not that it
+ * passed: it is that it went red on a defect it can see. A test cannot watch a
+ * human-readable exit code and be sure it saw the failure it planted, so the
+ * machine form carries the findings and the coverage the run achieved.
+ *
+ * **The exit code is the contract.** 0 means every named gate ran and found
+ * nothing. 1 means a gate found something. 2 means a gate could not read what it
+ * was pointed at, which is a different answer from "clean" and is never reported
+ * as 0. A gate that read nothing and exited 0 is the failure this program exists
+ * to make impossible, and it is why the coverage floors live in the gates rather
+ * than in the consumer's expectations.
+ */
+import process from 'node:process'
+import path from 'node:path'
+
+import { GATE_IDS, GATE_KIT_VERSION, gate, laws } from './index.mjs'
+import { CoverageError, readJson } from './run.mjs'
+
+const CONFIG_NAME = 'prism-gates.json'
+
+const flag = (name) => process.argv.find((argument) => argument.startsWith(`--${name}=`))?.slice(name.length + 3)
+const has = (name) => process.argv.includes(`--${name}`)
+
+async function main() {
+  const root = path.resolve(process.cwd())
+  const configPath = flag('config') ?? CONFIG_NAME
+  const json = has('json')
+  const only = flag('gate')
+
+  let config
+  try {
+    config = readJson(root, configPath)
+  } catch (cause) {
+    return fail(`error prism-gates: ${cause.message}`)
+  }
+  if (!config) {
+    return fail(
+      `error prism-gates: ${path.join(root, configPath)} does not resolve.\n` +
+        '  A gate chain with no configuration is a chain that runs nothing, and nothing looks like a pass.\n' +
+        '  The configuration holds this repository\'s own data only: its roots, its sheet, its pack map, its\n' +
+        '  coverage floors. The laws are not in it, because they are in the package.',
+    )
+  }
+
+  const named = only ? [only] : (config.gates ?? [])
+  if (named.length === 0) {
+    return fail(
+      `error prism-gates: ${configPath} names no gates, so this run enforced nothing.\n` +
+        `  A chain that runs nothing exits the same as a chain that found nothing, which is the answer this\n` +
+        `  program exists to stop giving. The kit ships: ${GATE_IDS.join(', ')}.`,
+    )
+  }
+
+  const results = []
+  let findings = 0
+  let unreadable = 0
+
+  for (const id of named) {
+    const settings = config[id] ?? {}
+    try {
+      const { run } = await gate(id)
+      const result = await run({ root, config: settings })
+      findings += result.findings.length
+      results.push({ gate: id, law: result.law.id, ok: result.findings.length === 0, findings: result.findings, notes: result.notes, also: (result.also ?? []).map((l) => l.id) })
+    } catch (cause) {
+      unreadable += 1
+      const message =
+        cause instanceof CoverageError
+          ? `error prism-gates: ${id}: ${cause.message}`
+          : `error prism-gates: ${id} could not run: ${cause.stack ?? cause.message}`
+      if (json) {
+        results.push({ gate: id, ok: false, unreadable: true, findings: [], notes: [message] })
+      } else {
+        console.error(message)
+      }
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { gateKit: GATE_KIT_VERSION, laws: laws().map((l) => l.id), results },
+        null,
+        2,
+      ),
+    )
+    return findings > 0 || unreadable > 0 ? 1 : 0
+  }
+
+  for (const result of results) {
+    if (result.unreadable) continue
+    for (const line of result.notes) console.log(line)
+    for (const line of result.findings) console.error(line)
+    if (result.findings.length > 0) {
+      const law = laws().find((l) => l.id === result.law)
+      console.error(`\n${law.title}`)
+      console.error(law.message)
+      console.error(`  It is here because: ${law.why}`)
+    }
+  }
+
+  console.log(
+    `\nprism-gates: gate kit ${GATE_KIT_VERSION}, ${named.length} gate(s) run, ${findings} finding(s), ` +
+      `${unreadable} unreadable`,
+  )
+  console.log(`prism-gates: the laws this run enforced: ${laws().map((l) => l.id).join(', ')}`)
+  console.log(
+    'prism-gates: the wording of every law above is in the package you pinned, not in this repository. A change\n' +
+      '  to it reaches this repository in one release and cannot be declined here.',
+  )
+
+  return findings > 0 || unreadable > 0 ? 1 : 0
+}
+
+function fail(message) {
+  console.error(message)
+  return 2
+}
+
+process.exitCode = await main()