@nanisoft/prism-llms 0.5.0 → 0.5.1

package/dist/md/changelogs/prism-ui.md

@@ -1,5 +1,43 @@
 # @nanisoft/prism-ui
 
+## 0.7.0
+
+### Minor Changes
+
+- 5c43520: Add `DocsShell`, a documentation page that takes a site's navigation as data
+  
+  `DocsShell` is a documentation screen: a navigation rail, the document, a
+  contents rail, and a pager to the neighbouring pages. It replaces the unstyled
+  `docs-shell` the retired line published, and it is the Page the three NaniSoft
+  product sites already import by that name.
+  
+  The navigation is data. A tree of one page and a tree of twenty-seven render the
+  same way, at any depth, and the frame is sized by what the caller passed rather
+  than by a fixed arrangement, so three sites whose documentation sets differ in
+  shape share one Page with no per-site fork.
+  
+  - `nav` and `toc` are closed unions of `page`, `group` and `divider`. Both are
+    read in the order given: nothing is sorted or alphabetised, so a site that
+    files its rail as a pipeline and its contents as a reference has both in one
+    render.
+  - The pager is derived from `nav` and `currentHref`. There is no `neighbours`
+    prop, so a neighbour that is not in the tree cannot be expressed, and each
+    consumer loses one derivation of its own.
+  - A group with no `href` renders a `span` rather than an anchor with no
+    destination. The three sites spell that case today as an empty string, and two
+    of them carry a stylesheet rule that styles the result back into a label; those
+    rules are now deletable.
+  - A section carries no status, no badge, no count, no collapse and no sort. A
+    status written into a title stays in the title as words.
+  - Both rails are bounded against the viewport, because one site's tree is half
+    again as tall as another's.
+  
+  The corpus fix that shipped with it: the props extractor read each declaration
+  body twice with two depth counters that disagreed, so a Page whose `index.tsx`
+  re-exported a value and a type from one sibling published every prop twice and
+  swept the members of its navigation union into its own prop list. It now reads
+  each body once.
+
 ## 0.6.0
 
 ### Minor Changes

package/dist/md/components/product-mark.md

@@ -112,12 +112,3 @@ export default function ProductMarkDemo() {
 **`pack`** `PackId | null` · optional · default: — — The product's pack, which is the mark's hue. Omit it, or pass `null`, for the one entry in a set that has no pack of its own: that entry is drawn as the full spectrum rather than as a colourless mark. See `SPECTRUM` above. `default` is a real answer and not the same as the empty one. The base pack is a pack a product can wear, and it is the absence of a `data-pack` attribute, so a product whose pack is `default` carries no attribute and its core resolves the base pack's `primary` from the page.
 **`size`** `ProductMarkSize` · optional · default: `'md'` — Which of the three drawn sizes to use.
 **`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited, and this Component spreads no other prop, so there is no second route to its ink.
-**`stored`** `string | null` · required · default: — — Raw contents of the key this line writes, or `null` when it is absent.
-**`legacy`** `string | null` · required · default: — — Raw contents of one key this line no longer writes, or `null`.
-**`documentPack`** `string | null` · required · default: — — `data-pack` on the root element as rendered, valid or not.
-**`documentDark`** `boolean` · required · default: — — Whether the root element carries `.dark` as rendered.
-**`defaultPack`** `PackId` · required · default: —
-**`defaultMode`** `Mode` · required · default: —
-**`mode`** `Mode` · required · default: —
-**`origin`** `ThemeOrigin` · required · default: — — Which source named the pair, for `THEME_ORIGIN_ATTRIBUTE`.
-**`key`** `string` · required · default: —

package/dist/md/components/select.md

@@ -142,9 +142,9 @@ export default function SelectDemo() {
 **`items`** `Record<string, React.ReactNode> | ReadonlyArray<{ label: React.ReactNode; value: string; }>` · optional · default: — — The options, keyed by value, so the trigger can render a label before any item has mounted. Without it, `SelectValue` shows the raw value.
 **`itemToStringLabel`** `(value: string) => string` · optional · default: — — Converts an item value to the label shown in the trigger.
 **`children`** `React.ReactNode` · optional · default: — — The trigger and the popup content.
-**`label`** `React.ReactNode` · required · default: —
 **`size`** `'sm' | 'default'` · optional · default: `default` — The trigger's height.
 **`placeholder`** `React.ReactNode` · optional · default: — — Shown when no value is selected.
 **`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `bottom` — Which side of the trigger the list is placed on.
 **`align`** `'start' | 'center' | 'end'` · optional · default: `center` — How the list aligns against the trigger.
 **`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the list.
+**`label`** `string` · optional · default: — — A text label used for keyboard typeahead when the option text differs.

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

@@ -0,0 +1,218 @@
+# DocsShell
+
+A documentation screen: a navigation rail whose shape arrives as data, the document at the measure, a contents rail, and a pager derived from the navigation rather than passed.
+
+```tsx
+import { DocsShell } from '@nanisoft/prism-ui/pages/docs-shell'
+```
+
+## Overview
+
+DocsShell is a documentation screen: a navigation rail, the document, a contents
+rail, and the pager to the neighbouring pages.
+
+**It 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 those three import lines rather than this file's shape. It was
+`docs-shell` in the retired line too, where it was an empty `div` and a class
+name each site then had to style from scratch.
+
+**The shape arrives as data.** The three sites publish full documentation sets
+and none of them agrees on the shape:
+
+- Nexus files six sections of five pages, each named for a documentation genre,
+  each with an index.
+- Atlas files four sections, one of which holds nine pages under a single
+  heading, and not one of them has an index.
+- AlphaLens files six sections separated by rules, named for subject matter
+  rather than for a genre, with a status inside three of the titles.
+
+The tree is a prop and the Page renders it, so none of the three had to be told
+which of the others it looks like.
+
+## Guidelines
+
+### When to use
+
+Use DocsShell as the body of the route that renders one documentation page,
+handed the page tree, the document's own outline, and the address being rendered.
+
+Use it for every page of a documentation set. A documentation site whose pages
+each carry their own rail is a site whose rail drifts.
+
+### When not to use
+
+Do not use it for a single-page site. It is a whole screen around a tree, and a
+site with one page has no tree.
+
+Do not use it for a blog. A post is a dated argument about one thing, and
+`BlogPostPage` is that screen.
+
+Do not hand it a `nav` you built by parsing a folder tree at render time. Map
+the tree once, in your own adapter, and pass the result: a Page that walked a
+filesystem would be a Page that fetches, and a Page imports no router and no data
+client.
+
+### Best practices
+
+- **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. 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.
+- **Omit `href` on a group that has no index.** That absence is what makes the
+  heading a label rather than a route, and it is the same thing all three sites
+  already spell as `url: node.index?.url ?? ''`, which two of them then restyle
+  back into a label in their own stylesheets. Naming the case in the type makes
+  those rules dead rather than load-bearing, and the type is the only thing that
+  had to change.
+- **Do not pass a previous and a next.** The pager is derived from `nav` and
+  `currentHref`, which removes one derivation from every consumer. 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.
+- **Give the rail and the contents their own orders, and let both stand.** `nav`
+  is in the order the rail shows and `toc` is in the order the contents rail
+  shows. Nothing is sorted, deduplicated or alphabetised. A site that files its
+  rail as a pipeline and its contents as a reference has both in one render.
+- Pass `toc` whole or not at all. A partial outline is a contents list that lies
+  about the page.
+- Omit `title` when your document owns its own heading. The Page renders no empty
+  `h1` to fill the gap, so a document with no title keeps exactly the outline its
+  own content declares.
+- Name the three regions. `navLabel`, `tocLabel` and `pagerLabel` are required
+  because they are words a reader hears, and a Page that ships no copy ships no
+  reader-facing copy either. A site that files its pages as a pipeline and its
+  contents as a reference names the three regions three different ways.
+
+### Content guidelines
+
+- Put a section's stage in its title, as AlphaLens does, and let it stay a
+  sentence. The Page will not pull it out into a badge for you, and a badge is a
+  state the reader can act on, which a stage of a pipeline is not.
+- Keep a rule's title short or leave it empty. A rule with words is a label a
+  reader reads twice: once in the rule and once on the section beneath it.
+- Keep a section index page's title the same as its section's title, so a reader
+  who arrives at the index and a reader who is already inside the section are
+  reading the same words.
+
+**A documentation screen: the rail, the document, the contents and the pager.**
+
+```tsx
+import { DocsShell, type DocsNavEntry } from '@nanisoft/prism-ui/pages/docs-shell'
+
+/**
+ * The shape the three consumer sites actually publish, taken from AlphaLens
+ * because it is the one that exercises every part of the interface at once: a
+ * status inside a section title, a rule between sections, and a section whose
+ * own index is a page a reader lands on.
+ */
+const NAV: DocsNavEntry[] = [
+  { type: 'page', title: 'AlphaLens', href: '#alphalens' },
+  { type: 'divider', title: 'Data platform (live)' },
+  {
+    type: 'group',
+    title: 'Data platform (live)',
+    href: '#data-platform',
+    items: [
+      { type: 'page', title: 'Capture', href: '#capture' },
+      { type: 'page', title: 'Storage', href: '#storage' },
+      { type: 'page', title: 'Operations', href: '#platform-operations' },
+    ],
+  },
+  { type: 'divider', title: 'Unified data contract (approved)' },
+  {
+    type: 'group',
+    title: 'Unified data contract (approved)',
+    href: '#data-contract',
+    items: [
+      { type: 'page', title: 'Data feed view', href: '#feed-view' },
+      { type: 'page', title: 'Timestamps and symbols', href: '#timestamps' },
+    ],
+  },
+  { type: 'divider', title: 'Research pipeline (designed)' },
+  {
+    // No `href`: this group is a label, because its folder holds no index page.
+    type: 'group',
+    title: 'Research pipeline (designed)',
+    items: [
+      { type: 'page', title: 'Anatomy', href: '#anatomy' },
+      { type: 'page', title: 'NSE portability', href: '#nse-portability' },
+    ],
+  },
+]
+
+/** The headings inside this page. Your own pipeline knows them; Prism does not. */
+const TOC: DocsNavEntry[] = [
+  { type: 'page', title: 'The capture path', href: '#the-capture-path' },
+  { type: 'page', title: 'What the store holds', href: '#what-the-store-holds' },
+  { type: 'page', title: 'Where this is heading', href: '#where-this-is-heading' },
+]
+
+/** A documentation screen: the rail, the document, the contents and the pager. */
+export default function DocsShellDemo() {
+  return (
+    <DocsShell
+      title="Storage"
+      description="Where a full chain of bars lands, and how it is partitioned."
+      nav={NAV}
+      toc={TOC}
+      currentHref="#storage"
+      navLabel="AlphaLens documentation"
+      tocLabel="On this page"
+      pagerLabel="AlphaLens pages"
+      pagerLabels={{ previous: 'Previous', next: 'Next' }}
+    >
+      <p>
+        The chain is written in columnar blocks, one per session per symbol, and
+        nothing is rewritten to correct it. What lands is what the exchange sent.
+      </p>
+      <h2 id="the-capture-path">The capture path</h2>
+      <p>
+        A capture is a session and a symbol, never a whole day. A day is a
+        partition over sessions, which is what makes a backtest cheap to repeat
+        and expensive to store twice.
+      </p>
+      <h2 id="what-the-store-holds">What the store holds</h2>
+      <ul>
+        <li>Every strike, call and put, at the exchange clock.</li>
+        <li>Open interest and the implied volatility of each strike.</li>
+        <li>The index future and the spot it settled against.</li>
+      </ul>
+      <h2 id="where-this-is-heading">Where this is heading</h2>
+      <p>
+        The same path, ported to .NET, is designed rather than built. The stage it
+        is at is in its title, because a stage of a pipeline is not a topic a
+        reader may visit in any order.
+      </p>
+    </DocsShell>
+  )
+}
+```
+
+## Props
+
+**`title`** `string` · optional · default: — — 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.
+**`description`** `ReactNode` · optional · default: — — 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.
+**`nav`** `readonly DocsNavEntry[]` · optional · default: — — 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.
+**`toc`** `readonly DocsNavEntry[]` · optional · default: — — 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.
+**`currentHref`** `string` · optional · default: — — 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.
+**`navLabel`** `string` · required · default: — — 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.
+**`tocLabel`** `string` · required · default: — — The accessible name of the contents rail. Required whenever `toc` is passed, for the same reason `navLabel` is.
+**`pagerLabel`** `string` · required · default: — — The accessible name of the pager. Required whenever there is a neighbour to reach, for the same reason `navLabel` is.
+**`pagerLabels`** `DocsPagerLabels` · required · default: — — The two words the pager renders above the neighbouring pages' titles. Required whenever either neighbour exists, for the same reason `navLabel` is.
+**`children`** `ReactNode` · required · default: — — 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.
+**`header`** `ReactNode` · optional · default: — — 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.
+**`footer`** `ReactNode` · optional · default: — — A slot below the frame, inside the container: a feedback prompt, a link back to the section index, a support address.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `DocsShell` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/docs-shell/index.tsx` — the file this Page is defined in
+**`dependencies`** `Prose` — the public Prism exports this item composes

package/dist/prism-skill.md

@@ -44,7 +44,7 @@ The read-only MCP endpoint is `https://prism.nanisoft.com/mcp`. It exposes nine
 ## This corpus
 
 Generated from the catalogue and the authored pages: 34
-Components, 19 Blocks and 6 Pages, plus the Overview,
+Components, 19 Blocks and 7 Pages, plus the Overview,
 Foundation, Content and Changelogs pages. The Changelogs pages are each
 published package's own changelog, byte for byte; `get_changelog` returns one
 package's, optionally one version of it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanisoft/prism-llms",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Prism's agent-facing corpus: llms.txt, the Markdown mirror, prism-skill.md and the PrismDocsStore projection. One build-fresh dist/ serves npm, the site and the MCP server.",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4",
-    "@nanisoft/prism-ui": "0.6.0",
-    "@nanisoft/prism-tokens": "0.6.0"
+    "@nanisoft/prism-tokens": "0.6.0",
+    "@nanisoft/prism-ui": "0.7.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",