@nanisoft/prism-llms 0.4.0 → 0.5.0

package/dist/md/pages/blog-post-page.md

@@ -0,0 +1,136 @@
+# BlogPostPage
+
+A complete blog post screen: title, standfirst, byline with both the display and the machine date, the body at the measure and the trail to the neighbouring posts.
+
+```tsx
+import { BlogPostPage } from '@nanisoft/prism-ui/pages/blog-post-page'
+```
+
+## Overview
+
+BlogPostPage is a complete blog post screen: the title, the standfirst, the
+byline, the body at the reading 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.
+
+**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.
+
+## Guidelines
+
+### When to use
+
+Use BlogPostPage as the body of the route that renders one post, handed the
+frontmatter your content pipeline produced.
+
+Use it for every post. A blog whose posts each have their own wrapper is a blog
+whose posts drift apart within a year.
+
+### When not to use
+
+Do not use it for a documentation page. Documentation is a set of short pages
+about one thing; a post is a dated argument about one thing, and a trail to the
+post before it is not a trail through a manual.
+
+Do not use it for a landing page. `MarketingPage` is that composition.
+
+### Best practices
+
+- Pass `dateTime` in `YYYY-MM-DD`. It is the value a feed reader and a search
+  engine order by, and it is the one that is wrong silently.
+- The body is `children`, held by `Prose`. Your pipeline owns the document; this
+  owns the measure and the rhythm. Do not parse it into an array of paragraphs to
+  hand over - that is a second representation of something your pipeline already
+  has.
+- Render only the halves of the trail you have. 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.
+- `trailLabel` and `trailLabels` are required alongside a neighbour. They are words
+  a reader reads and hears, and a Page that ships no copy ships no reader-facing
+  copy either: a site that files posts newest-last says the opposite pair.
+- Use `footer` for what comes after the trail: related posts, a newsletter form, a
+  closing call to action. It is a slot 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.
+- Pass `indexLink` with the words and the route your archive lives at. The page
+  ships neither.
+
+### Content guidelines
+
+- Write the standfirst as one or two sentences a reader can stop at. It is what an
+  index, a feed and a search result show.
+- Keep tags to nouns. A tag is a category a reader browses, not a sentence.
+- Keep the title to one line at the largest viewport unless the post is the only
+  thing on the page.
+
+**A post: the title, the standfirst, both dates, tags, the body and the trail.**
+
+```tsx
+import { BlogPostPage } from '@nanisoft/prism-ui/pages/blog-post-page'
+
+/** A post: the title, the standfirst, both dates, tags, the body and the trail. */
+export default function BlogPostPageDemo() {
+  return (
+    <BlogPostPage
+      title="Every minute, the whole chain"
+      description="What live full-chain capture at index scale actually takes: the spike, then production, then Kubernetes."
+      date="21 September 2026"
+      dateTime="2026-09-21"
+      author="NaniSoft"
+      readingTime="6 min read"
+      tags={[{ label: 'market-data' }, { label: 'collector' }]}
+      trailLabels={{ previous: 'Previous', next: 'Next' }}
+      trailLabel="More posts"
+      previous={{ title: 'One feed to research them all', href: '#one-feed' }}
+      next={{ title: 'Multi-agent research, mapped', href: '#multi-agent' }}
+      indexLink={{ title: 'All posts', href: '#all' }}
+    >
+      <p>
+        The claim sounds like a feature. It is a measurement with a timestamp on
+        it, and it started as a suspicion that it was impossible.
+      </p>
+      <h2>The assumption that was backwards</h2>
+      <p>
+        Going in, full-chain-per-minute looked like a streaming problem. It was a
+        counting problem, and the count had to fit in a minute.
+      </p>
+      <ul>
+        <li>Every strike, call and put.</li>
+        <li>Open interest, implied volatility and the Greeks.</li>
+        <li>Index futures, index spot and the volatility index.</li>
+      </ul>
+    </BlogPostPage>
+  )
+}
+```
+
+## Props
+
+**`title`** `string` · required · default: — — The post's title. It is the page's `h1`, so the page has exactly one and it is the post's name.
+**`description`** `string` · optional · default: — — 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.
+**`date`** `string` · required · default: — — 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.
+**`dateTime`** `string` · required · default: — — 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.
+**`author`** `ReactNode` · optional · default: — — Who wrote the post. A name, or a link to an author page.
+**`tags`** `readonly BlogPostTag[]` · optional · default: — — 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.
+**`readingTime`** `string` · optional · default: — — How long the post takes to read, in the consumer's own words.
+**`children`** `ReactNode` · required · default: — — 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.
+**`previous`** `BlogPostNeighbour` · optional · default: — — 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.
+**`next`** `BlogPostNeighbour` · optional · default: —
+**`trailLabels`** `BlogPostTrailLabels` · required · default: — — 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.
+**`trailLabel`** `string` · required · default: — — 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.
+**`indexLink`** `BlogPostNeighbour` · optional · default: — — 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.
+**`footer`** `ReactNode` · optional · default: — — 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.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `BlogPostPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/blog-post-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `Badge, CtaLink, Prose, Section` — the public Prism exports this item composes

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/marketing-page.md

@@ -0,0 +1,199 @@
+# MarketingPage
+
+A complete marketing page composing a hero, a feature grid, a KPI row, a plan comparison and a closing call to action.
+
+```tsx
+import { MarketingPage } from '@nanisoft/prism-ui/pages/marketing-page'
+```
+
+## Overview
+
+MarketingPage is a complete marketing screen. It composes five blocks in reading
+order and passes each one its own content, so the page adds the sequence and
+nothing else: an opening hero, a capability grid, a row of key figures, a plan
+comparison and a closing call to action.
+
+The page composes these blocks:
+
+| Section | Block | Role |
+| --- | --- | --- |
+| Opening | Hero01 | the headline, the supporting line and one or two actions |
+| Capabilities | FeatureGrid01 | a grid of short feature blurbs, with or without icons |
+| Figures | Stats01 | two to four key numbers, each with an optional delta |
+| Plans | Pricing01 | a plan comparison with one highlighted tier |
+| Closing | Cta01 | the final call to action on a filled surface |
+
+Every string, number, icon, price and action is a prop. The page ships no sample
+copy and fetches nothing. It is a product-agnostic screen model, so a consumer
+installs it, passes their own content and owns the links. It is not this site's
+own landing route: that page is site-owned and composes the same blocks at the
+call site.
+
+## Guidelines
+
+### When to use
+
+Use MarketingPage for a public landing route whose job is to introduce a product
+and move a reader to one next step. It works when the five sections form one
+argument from the headline to the closing action.
+
+### When not to use
+
+Do not use it inside an authenticated screen. A hero and a plan comparison carry
+marketing weight that competes with the task an application screen exists to
+support; compose the blocks you need directly instead.
+
+Do not use it as a documentation page. Guides and item pages have their own
+shell, and a marketing hero would sit above content that is already scoped.
+
+Do not use it when the sequence is not the five sections. The page is a fixed
+composition; a different order or a missing section is a page the consumer
+builds from the blocks.
+
+### Best practices
+
+- Pass every block its own props. The page does not merge or default them, so
+  omitting a section's content renders an empty section rather than a fallback.
+- Keep the hero as the only `h1`. The page defaults `headingLevel` to `h1`; when
+  it is embedded under a heading the consumer already owns, pass one level
+  deeper and the rest of the outline follows.
+- Put the primary action on the hero and the secondary action on the closing
+  band, not both in each. One decision per band keeps the page from reading as
+  two pitches.
+- Keep the figures real. Stats01 renders exactly the numbers it is given, so the
+  page makes no claim the consumer did not make.
+
+### Content guidelines
+
+- The hero headline states an outcome, not a feature name.
+- The feature titles are the four or five things the product does; the bodies
+  are one sentence each.
+- The closing line is a verb phrase and the action names what the reader gets.
+
+**The marketing page, composed with placeholder sections.**
+
+```tsx
+import { Blocks, Palette, ShieldCheck, Zap } from 'lucide-react'
+
+import { MarketingPage } from '@nanisoft/prism-ui/pages/marketing-page'
+
+/**
+ * The marketing page, composed with placeholder sections.
+ *
+ * The page owns the sequence; the demo owns the strings, the numbers and the
+ * feature icons. It renders at `h3` because the documentation page already owns
+ * an `h1`, which is the same reason a block demo nests its heading.
+ */
+export default function MarketingPageDemo() {
+  return (
+    <MarketingPage
+      headingLevel="h3"
+      hero={{
+        eyebrow: 'Preview',
+        title: 'A headline that fits on two lines',
+        description:
+          'One or two sentences of supporting copy, so the measure and the spacing around it can be judged.',
+        actions: [
+          { label: 'Primary action' },
+          { label: 'Secondary', variant: 'outline' },
+        ],
+      }}
+      features={{
+        eyebrow: 'Preview',
+        title: 'Section heading',
+        description: 'An optional line that explains what the set below it has in common.',
+        features: [
+          {
+            icon: Palette,
+            title: 'First item',
+            body: 'A short sentence describing the first thing in the set.',
+          },
+          {
+            icon: Blocks,
+            title: 'Second item',
+            body: 'A short sentence describing the second thing in the set.',
+          },
+          {
+            icon: Zap,
+            title: 'Third item',
+            body: 'A short sentence describing the third thing in the set.',
+          },
+          {
+            icon: ShieldCheck,
+            title: 'Fourth item',
+            body: 'A short sentence describing the fourth thing in the set.',
+          },
+        ],
+      }}
+      stats={{
+        eyebrow: 'Preview',
+        title: 'Section heading',
+        stats: [
+          { label: 'First metric', value: '1,284', delta: 12, hint: 'vs last month' },
+          { label: 'Second metric', value: '47.2%', delta: -3, hint: 'vs last month' },
+          { label: 'Third metric', value: '2.4d', delta: 0, hint: 'vs last quarter' },
+          { label: 'Fourth metric', value: '138' },
+        ],
+      }}
+      pricing={{
+        title: 'Section heading',
+        plans: [
+          {
+            name: 'First plan',
+            price: '$0',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['First included line', 'Second included line', 'Third included line'],
+            cta: 'Choose',
+          },
+          {
+            name: 'Second plan',
+            price: '$24',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['Everything in the first plan', 'One extra line', 'Another extra line'],
+            cta: 'Choose',
+            featured: true,
+          },
+          {
+            name: 'Third plan',
+            price: '$68',
+            period: ' / month',
+            body: 'One line on who it is for.',
+            features: ['Everything in the second plan', 'One extra line', 'Another extra line'],
+            cta: 'Choose',
+          },
+        ],
+      }}
+      cta={{
+        title: 'A closing line, two lines at most',
+        description: 'A sentence that says what happens next, then one action.',
+        action: { label: 'Do the thing', href: '/components/button' },
+      }}
+    />
+  )
+}
+```
+
+## Props
+
+**`hero`** `ComponentProps<typeof Hero01>` · required · default: — — The opening band: an optional eyebrow, the headline and one or two actions.
+**`features`** `ComponentProps<typeof FeatureGrid01>` · required · default: — — The capability grid below the hero.
+**`stats`** `ComponentProps<typeof Stats01>` · required · default: — — The key-figure row.
+**`pricing`** `ComponentProps<typeof Pricing01>` · required · default: — — The plan comparison.
+**`cta`** `ComponentProps<typeof Cta01>` · required · default: — — The closing call to action.
+**`headingLevel`** `HeadingLevel` · optional · default: — — The heading level for the hero. Defaults to `h1`, because a page owns the top of the document outline. A consumer that embeds the page under a heading it already owns passes one level deeper.
+
+## Composition
+
+**`exports`** `MarketingPage` — the public runtime names this Page promises
+**`source`** `packages/ui/src/pages/marketing-page/index.tsx` — the file this Page is defined in
+**`dependencies`** `Cta01, FeatureGrid01, Hero01, Pricing01, Stats01` — the public Prism exports this item composes
+
+## Blocks
+
+- [Cta01](https://prism.nanisoft.com/blocks/cta-01.md)
+- [FeatureGrid01](https://prism.nanisoft.com/blocks/feature-grid-01.md)
+- [Hero01](https://prism.nanisoft.com/blocks/hero-01.md)
+- [Pricing01](https://prism.nanisoft.com/blocks/pricing-01.md)
+- [Stats01](https://prism.nanisoft.com/blocks/stats-01.md)