@nanisoft/prism-llms 0.4.0 → 0.5.1

package/dist/md/pages/dashboard-page.md

@@ -0,0 +1,241 @@
+# DashboardPage
+
+A full dashboard screen composing the app shell, a page header, a KPI row and a data table.
+
+```tsx
+import { DashboardPage } from '@nanisoft/prism-ui/pages/dashboard-page'
+```
+
+## Overview
+
+DashboardPage is a complete application screen. It composes the shell, a page
+header, a row of key figures and a data table, and it owns the sequence and the
+spacing only. The frame comes from the shell, the screen's name from the header,
+the summary from the stats and the working set from the table.
+
+The page composes these blocks:
+
+| Region | Block | Role |
+| --- | --- | --- |
+| Frame | AppShell01 | the navigation rail, the top bar and the mobile navigation sheet |
+| Header | PageHeader01 | the trail, the page title and the page actions |
+| Summary | Stats01 | the key figures above the table |
+| Working set | DataTable01 | the toolbar, filters, selection and pagination |
+
+Navigation, rows, columns, labels and every callback are props. The page fetches
+nothing and imports no router, so the consumer owns the links and the data. The
+table's search, page, filters and selection are controlled by the consumer, so
+the same page can be driven by a server render or a client cache.
+
+## Guidelines
+
+### When to use
+
+Use DashboardPage for the landing screen of an application, where a reader checks
+the state of a workspace and acts on a collection. It works when the navigation
+is stable across screens and the table is the reason the reader came.
+
+### When not to use
+
+Do not use it for a single-purpose screen with no collection. A dashboard with an
+empty table is a header and a stat row around nothing; compose the header and the
+stats directly instead.
+
+Do not use it for a read-only report. The table's toolbar promises search,
+filters and selection; a screen that does not offer them should not render the
+toolbar.
+
+### Best practices
+
+- Pass the same navigation node to both the rail and the sheet. AppShell01 renders
+  it twice, so keep ids in the navigation unique or avoid ids there.
+- Keep the page's own controls in the header, not the table toolbar. The header
+  action belongs to the screen; the toolbar belongs to the rows.
+- Own the table state at the call site. Pass `page`, `searchValue`, `filterValues`
+  and `selectedIds`, and reset the page to one when the search or a filter
+  changes, so the view and the data never disagree.
+- Give every row a stable `getRowId`. An index-based id loses the selection when
+  the page changes.
+- Pass every string the table needs in `labels`. The page supplies none of them.
+
+### Content guidelines
+
+- The title names the screen: "Overview", not "View overview".
+- A stat label is a noun phrase in sentence case, and the figure keeps one unit.
+- A table column header is a short noun and a row action is a verb phrase.
+
+**The dashboard page, with the shell, a header, a KPI row and a driven table.**
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+import { DashboardPage } from '@nanisoft/prism-ui/pages/dashboard-page'
+
+const LINKS = [
+  { href: '#dashboard', label: 'Dashboard', current: true },
+  { href: '#projects', label: 'Projects', current: false },
+  { href: '#team', label: 'Team', current: false },
+]
+
+const ACCOUNTS = [
+  { id: 'northwind', name: 'Northwind', plan: 'Team', status: 'Active', seats: '24' },
+  { id: 'contoso', name: 'Contoso', plan: 'Business', status: 'Active', seats: '86' },
+  { id: 'fabrikam', name: 'Fabrikam', plan: 'Team', status: 'Paused', seats: '12' },
+  { id: 'adventure', name: 'Adventure Works', plan: 'Starter', status: 'Active', seats: '4' },
+  { id: 'litware', name: 'Litware', plan: 'Business', status: 'Active', seats: '140' },
+  { id: 'proseware', name: 'Proseware', plan: 'Starter', status: 'Paused', seats: '7' },
+]
+
+const PAGE_SIZE = 3
+
+/** The dashboard page, with the shell, a header, a KPI row and a driven table. */
+export default function DashboardPageDemo() {
+  const [query, setQuery] = useState('')
+  const [filters, setFilters] = useState<Record<string, string | undefined>>({})
+  const [selected, setSelected] = useState<string[]>([])
+  const [page, setPage] = useState(1)
+
+  const filtered = ACCOUNTS.filter((row) => {
+    const matchesQuery = row.name.toLowerCase().includes(query.toLowerCase())
+    const matchesStatus = !filters.status || row.status === filters.status
+    return matchesQuery && matchesStatus
+  })
+  const pageCount = Math.max(1, Math.ceil(filtered.length / PAGE_SIZE))
+  const pageRows = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)
+
+  return (
+    <DashboardPage
+      shell={{
+        navigationLabel: 'Primary',
+        brand: <span className="text-sm font-semibold">Northwind</span>,
+        breadcrumbs: [{ label: 'Dashboard', href: '#dashboard' }, { label: 'Overview' }],
+        actions: (
+          <span className="bg-muted text-muted-foreground rounded-full px-3 py-1 text-xs font-medium">
+            AR
+          </span>
+        ),
+        navigation: (
+          <ul className="flex flex-col gap-1 text-sm">
+            {LINKS.map((link) => (
+              <li key={link.href}>
+                <a
+                  href={link.href}
+                  className={
+                    link.current
+                      ? 'bg-accent text-accent-foreground block rounded-md px-3 py-2 font-medium'
+                      : 'text-muted-foreground hover:text-foreground block rounded-md px-3 py-2'
+                  }
+                >
+                  {link.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ),
+      }}
+      header={{
+        breadcrumbs: [{ label: 'Dashboard', href: '#dashboard' }, { label: 'Overview' }],
+        title: 'Overview',
+        description: 'Accounts, usage and the people on this workspace.',
+        actions: [{ label: 'New account' }],
+      }}
+      stats={{
+        eyebrow: 'This month',
+        title: 'Delivery',
+        headingLevel: 'h2',
+        stats: [
+          { label: 'Active accounts', value: '1,284', delta: 12, hint: 'vs last month' },
+          { label: 'On track', value: '47.2%', delta: -3, hint: 'vs last month' },
+          { label: 'Open issues', value: '138' },
+        ],
+      }}
+      table={{
+        title: 'Accounts',
+        description: 'Every workspace you can manage.',
+        columns: [
+          { id: 'name', header: 'Account', label: 'Account', cell: (row) => String(row.name) },
+          { id: 'plan', header: 'Plan', label: 'Plan', cell: (row) => String(row.plan) },
+          { id: 'status', header: 'Status', label: 'Status', cell: (row) => String(row.status) },
+          {
+            id: 'seats',
+            header: 'Seats',
+            label: 'Seats',
+            className: 'text-right',
+            cell: (row) => String(row.seats),
+          },
+        ],
+        rows: pageRows,
+        getRowId: (row) => String(row.id),
+        selectable: true,
+        selectedIds: selected,
+        onSelectedIdsChange: setSelected,
+        searchValue: query,
+        onSearchChange: (value) => {
+          setQuery(value)
+          setPage(1)
+        },
+        filters: [
+          {
+            id: 'status',
+            label: 'Status',
+            options: [
+              { label: 'Active', value: 'Active' },
+              { label: 'Paused', value: 'Paused' },
+            ],
+          },
+        ],
+        filterValues: filters,
+        onFilterChange: (id, value) => {
+          setFilters((previous) => ({ ...previous, [id]: value }))
+          setPage(1)
+        },
+        page,
+        pageCount,
+        onPageChange: setPage,
+        rowActions: () => [
+          { label: 'View details' },
+          { label: 'Rename' },
+          { label: 'Delete', variant: 'destructive' },
+        ],
+        labels: {
+          search: 'Search accounts',
+          filters: 'Filters',
+          reset: 'Reset filters',
+          columns: 'Columns',
+          viewColumns: 'View',
+          selectAll: 'Select every account on this page',
+          selectRow: 'Select this account',
+          rowActions: 'Account actions',
+          previous: 'Previous',
+          next: 'Next',
+          page: (value) => `Go to page ${value}`,
+          selectedCount: (count) => `${count} selected`,
+          empty: 'No accounts match the current search and filters.',
+        },
+      }}
+    />
+  )
+}
+```
+
+## Props
+
+**`shell`** `Omit<ComponentProps<typeof AppShell01>, 'children'>` · required · default: — — The frame: the navigation rail, the top bar and the mobile navigation sheet. Navigation, actions and the rail slots are passed as nodes, so the page never imports a router.
+**`header`** `ComponentProps<typeof PageHeader01>` · required · default: — — The page title band.
+**`stats`** `ComponentProps<typeof Stats01>` · required · default: — — The key-figure row above the table.
+**`table`** `ComponentProps<typeof DataTable01>` · required · default: — — The main table, with its rows, columns, labels and callbacks.
+
+## Composition
+
+**`exports`** `DashboardPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/dashboard-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `AppShell01, DataTable01, PageHeader01, Stats01` — the public Prism exports this item composes
+
+## Blocks
+
+- [AppShell01](https://prism.nanisoft.com/blocks/app-shell-01.md)
+- [DataTable01](https://prism.nanisoft.com/blocks/data-table-01.md)
+- [PageHeader01](https://prism.nanisoft.com/blocks/page-header-01.md)
+- [Stats01](https://prism.nanisoft.com/blocks/stats-01.md)

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

@@ -1,23 +1,218 @@
 # DocsShell
 
-Prism page — full documentation pending.
+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.
 
-```ts
-import { DocsShell } from '@nanisoft/prism-ui/pages';
+```tsx
+import { DocsShell } from '@nanisoft/prism-ui/pages/docs-shell'
 ```
 
-`DocsShell` is a Prism page. Full documentation is pending — the prism MCP answers API questions in the meantime (`get_item_props`, `get_item_source`).
+## 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
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `children` | ReactNode | — | The article body (the app renders fumadocs MDX content into it). |
-| `title` (optional) | string | — | Page title; omitted for index-style pages that own their heading. |
-| `description` (optional) | string | — | — |
-| `nav` (optional) | DocsNavEntry[] | — | Sidebar navigation tree. |
-| `toc` (optional) | DocsNavEntry[] | — | Table-of-contents entries for the current page. |
-| `neighbours` (optional) | { previous?: { title: string; url: string; }; next?: { title: string; url: string; }; } | — | Prev/next neighbours at the boundary. |
-| `header` (optional) | ReactNode | — | Slot overrides for chrome — the app's header/footer. |
-| `footer` (optional) | ReactNode | — | — |
-| `className` (optional) | string | — | — |
+**`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