@nanisoft/prism-llms 0.4.0 → 0.5.0

package/dist/md/components/checkbox.md

@@ -1,14 +1,108 @@
 # Checkbox
 
-antd Checkbox, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The control for an independent yes-or-no choice, with an optional mixed state.
 
-```ts
-import { Checkbox } from '@nanisoft/prism-ui/components';
+```tsx
+import { Checkbox } from '@nanisoft/prism-ui/components/checkbox'
 ```
 
-`Checkbox` is antd's [Checkbox](https://ant.design/components/checkbox), re-exported unchanged.
+## Overview
 
-- Extends: antd **Checkbox** — for inherited props and demos, use the antd MCP (`antd_info Checkbox`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Checkbox is an independent choice that is either ticked, unticked, or mixed.
+It renders as a styled control with a hidden native checkbox beside it, so it
+submits with a form and validates like the element it stands in for. Space
+toggles the focused control, and a mixed state is announced as "mixed" rather
+than as checked or unchecked.
 
-_No additional props beyond the antd base component._
+Use the `indeterminate` prop for a parent choice that summarizes children, such
+as a select-all control. The mixed state is a summary, not a third answer: a
+click should move it to ticked or unticked.
+
+## Guidelines
+
+### When to use
+
+Use a Checkbox when each choice stands on its own and several may be ticked, or
+when one choice confirms something, such as accepting terms or selecting a row
+in a table.
+
+### When not to use
+
+Do not use a Checkbox for a setting that takes effect the moment it changes.
+That is a Switch, which reads as immediate rather than as pending a save.
+
+Do not use one when exactly one of several options must be chosen. A RadioGroup
+announces the single answer; a set of checkboxes implies that all, some or none
+may be ticked.
+
+Do not use a Checkbox as a button that performs an action. It holds a state, it
+does not do a thing.
+
+### Best practices
+
+- Give every Checkbox a label through `FieldLabel` and `htmlFor`, or an
+  `aria-label` when the design has no room for visible text. A bare box is
+  unlabelled to a screen reader.
+- Make the label the click target where you can, so the reader does not have to
+  hit the small control.
+- Use `indeterminate` only to summarize child checkboxes, and update it from the
+  children rather than setting it by hand in unrelated places.
+- Keep the state in the consumer. Pass `checked` with `onCheckedChange` for a
+  controlled box, or `defaultChecked` when the form owns it.
+- Show a required checkbox's consequence in the label, not as a separate error
+  after submission.
+
+### Content guidelines
+
+- Write the label as a positive statement of what is true when ticked:
+  "Email me release notes", not "Do not email me release notes".
+- Use sentence case and no trailing period on a short label.
+- Put an explanation in an adjacent helper line, not inside the label.
+
+**Checkbox at rest, ticked, mixed and disabled.**
+
+```tsx
+'use client'
+
+import { Checkbox } from '@nanisoft/prism-ui/components/checkbox'
+import { FieldLabel } from '@nanisoft/prism-ui/components/field'
+
+/** Checkbox at rest, ticked, mixed and disabled. */
+export default function CheckboxDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-4">
+      <div className="flex items-center gap-3">
+        <Checkbox id="checkbox-news" defaultChecked />
+        <FieldLabel htmlFor="checkbox-news">Email me release notes</FieldLabel>
+      </div>
+      <div className="flex items-center gap-3">
+        <Checkbox id="checkbox-all" indeterminate />
+        <FieldLabel htmlFor="checkbox-all">Select all invoices</FieldLabel>
+      </div>
+      <div className="flex items-center gap-3">
+        <Checkbox id="checkbox-quiet" />
+        <FieldLabel htmlFor="checkbox-quiet">Send a weekly digest</FieldLabel>
+      </div>
+      <div className="flex items-center gap-3">
+        <Checkbox id="checkbox-sso" disabled />
+        <FieldLabel htmlFor="checkbox-sso" className="text-muted-foreground">
+          Single sign-on (paid plan)
+        </FieldLabel>
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`checked`** `boolean` · optional · default: — — The controlled ticked state.
+**`defaultChecked`** `boolean` · optional · default: — — The initially ticked state, for an uncontrolled checkbox.
+**`indeterminate`** `boolean` · optional · default: — — Whether the checkbox shows a mixed state: neither ticked nor unticked.
+**`disabled`** `boolean` · optional · default: — — Whether the control ignores user interaction.
+**`readOnly`** `boolean` · optional · default: — — Whether the value must be ticked before the form submits.
+**`required`** `boolean` · optional · default: — — Whether the value must be ticked before the form submits.
+**`name`** `string` · optional · default: — — The form field name submitted with the form.
+**`value`** `string` · optional · default: — — The value submitted when the checkbox is ticked.
+**`form`** `string` · optional · default: — — Identifies the form that owns the hidden input.
+**`onCheckedChange`** `(checked: boolean) => void` · optional · default: — — Called when the ticked state changes.

package/dist/md/components/cta-link.md

@@ -0,0 +1,98 @@
+# CtaLink
+
+The call to action that goes somewhere: a native link carrying the weight of a button.
+
+```tsx
+import { CtaLink } from '@nanisoft/prism-ui/components/cta-link'
+```
+
+## Overview
+
+The CtaLink is the call to action that goes somewhere. It renders a native
+`<a>` and carries the visual weight of a Button, so a marketing page can have a
+primary action that is genuinely a link: right-clickable, openable in a new tab,
+and announced as a link rather than as a button.
+
+`href` is required. There is no form of this component without a destination,
+because an action with no handler navigates nothing, and a control that
+announces itself as a button and does not move the reader anywhere is worse than
+a control that is plainly a button.
+
+The rendered control is a second component rather than a `Button` that changes
+element by prop. The design system had already answered this twice, in
+`Breadcrumb` and in `Pagination`, where the link is a second export beside the
+item rather than an `as` on the item. Following the existing answer costs no
+client JavaScript: the CtaLink is a server component.
+
+## Guidelines
+
+### When to use
+
+Use a CtaLink wherever the reader's intent is to go somewhere: the primary
+action on a landing section, the closing action on a page, a cross-reference
+between two pages.
+
+Set `newTab` when opening a new browsing context is what the reader wants, such
+as an external playground or a reference. The link relationship then defaults to
+`noopener noreferrer`, so the opened page cannot reach back through `window.opener`.
+
+### When not to use
+
+Do not use a CtaLink for an action that changes the page's state rather than its
+address: submitting a form, saving a change, deleting a record. That is a Button,
+and the Button's own guidance says so.
+
+Do not reach for `newTab` because a URL looks external. Prism does not parse the
+destination and makes no guess about what counts as external, because a
+cross-origin URL is not by itself a reason to take the reader out of the page
+they are reading. Decide per link.
+
+### Best practices
+
+- One CtaLink per section carries `default` weight. Two primaries make neither
+  of them primary.
+- Keep the label in the imperative and state the outcome, the same as a Button.
+- Prefer a same-tab link unless the destination is genuinely somewhere else.
+- If the destination is the current route, use a different control: a link to
+  where the reader already is is a dead link.
+
+### Content guidelines
+
+- Start with a verb: "Read the guides", "Compare variants", "Open the playground".
+- Sentence case, no period, three words where possible.
+- Never "Click here". The label should state the outcome, not the mechanism.
+
+**The call to action at each variant, same tab and new tab.**
+
+```tsx
+import { CtaLink } from '@nanisoft/prism-ui/components/cta-link'
+
+/**
+ * The call to action at each variant, same tab and new tab.
+ *
+ * Self-contained: the only import is from the package, and it has a default
+ * export. The file is the source for the live preview, the copy control and the
+ * corpus.
+ */
+export default function CtaLinkDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <CtaLink href="/components/button">Read the guide</CtaLink>
+      <CtaLink href="/components/button" variant="secondary">
+        Compare variants
+      </CtaLink>
+      <CtaLink href="/components/button" variant="outline">
+        See the API
+      </CtaLink>
+      <CtaLink href="https://example.com" newTab>
+        Open the playground
+      </CtaLink>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`href`** `string` · required · default: — — The destination. Required, because an anchor without one is not a link: a screen reader announces no destination, the middle-click and open-in-new-tab affordances go quiet, and the control is a button that cannot act.
+**`newTab`** `boolean` · optional · default: — — Opens the destination in a new browsing context. This is the only way to ask for one: `target` is not accepted, so the safe relationship below cannot be opted out of by accident. Prism does not decide what counts as external. A destination on another origin is not automatically a new tab, and a destination on this origin is not automatically the same tab, so the caller declares it.

package/dist/md/components/diagram.md

@@ -0,0 +1,124 @@
+# Diagram
+
+Named things and the labelled relations between them, drawn as inline vector markup whose every stroke and fill is a token.
+
+```tsx
+import { Diagram } from '@nanisoft/prism-ui/components/diagram'
+```
+
+## Overview
+
+A Diagram draws named things and the labelled relations between them, as inline
+vector markup. It takes its geometry as data and returns an `<svg>`, so a
+consumer needs no hook, no mode, no provider and no client code to render one.
+
+Every stroke and fill it draws is a semantic utility on the emitted token
+contract, and never a resolved value. That is the whole reason it exists: a
+drawing that reads a colour out of computed style at runtime takes its value from
+one element, while a pack is an attribute on an ancestor, so a scoped boundary
+hands it the pack's light values on a dark page. Inline markup inherits the pack
+the way every other element does, and a subtree carrying a second pack restyles
+in place.
+
+`x` and `y` are in your coordinate space and are normalised into the canvas, so
+fractions, pixels or any other monotonic scale draw the same shape and keep their
+aspect ratio. A fixed canvas is deliberate: a viewBox derived from your numbers
+would make the label size a function of how large a number you happened to use,
+so the same drawing would come out with unreadable labels from `0..1` fractions
+and enormous ones from `0..4000` pixels.
+
+## Guidelines
+
+### When to use
+
+Use a Diagram when the thing you are showing is a set of named things and the
+relations between them: a pipeline, a data flow, a set of moving parts. It is the
+right replacement for a canvas that drew the same thing, because it inherits the
+pack, ships no client code, and is legible to a screen reader.
+
+Mark at most one node with `emphasis`. It is the node the drawing is about, and
+it takes the brand ink. Two emphasised nodes is a caller's mistake, not a second
+level.
+
+Use `indirect` on a relation that happens rather than causes, for example a
+review that follows a merge. It draws the line dashed, chosen over fading the
+line because a dashed line keeps its contrast and a faded one does not.
+
+### When not to use
+
+Do not use a Diagram for a series of values, a time axis or anything quantitative.
+A drawing of a shape with no name on it is not a diagram, and a fabricated series
+presented under a live label is a lie the surface is not able to make.
+
+Do not use a Diagram where the relationships are a linear sequence. A numbered
+list is a linear sequence, and it is more honest and more accessible than a
+drawing of one.
+
+Do not pass `decorative` to a drawing that carries meaning. `label` is required
+unless the drawing is decorative, and the union is what makes the compiler hold
+that: a single optional prop could only be required everywhere or optional
+everywhere, and both halves of that are wrong.
+
+### Best practices
+
+- Give the Diagram a `label` that says what the drawing is, not what it is called.
+  The name is read aloud; "How a finding is produced" beats "architecture".
+- Keep the node count readable. A drawing that needs a legend to be understood is
+  a table.
+- Two nodes at the same position collapse onto one another, so spread a column
+  rather than repeating a number.
+- Put the emphasised node near the middle. The eye goes there first and the
+  relations read outward from it.
+- Do not nest a pack boundary inside a drawing. A boundary moves the pack's
+  corner radius, and a drawing's marks are circles and paths with no radius
+  concept, so a boundary on one changes its colour and nothing else. That is the
+  property that makes a drawing safe under a boundary.
+
+### Content guidelines
+
+- Node names are labels: one or two words, sentence case, no period.
+- Relation labels are the verb or preposition that says what the line is: "feeds",
+  "confirms", "blocks on".
+- A relation label is placed beside its line rather than on it. A label drawn over
+  a line has to be knocked out with a halo, and the halo has to be filled with
+  the colour of the surface the drawing happens to sit on, which the component is
+  not told.
+
+**A three-node loop with one emphasised node and one indirect relation.**
+
+```tsx
+import { Diagram } from '@nanisoft/prism-ui/components/diagram'
+
+/**
+ * A three-node loop with one emphasised node and one indirect relation.
+ *
+ * Self-contained: the only import is from the package, and it has a default
+ * export. No hook, no mode, no provider, which is the point of the component.
+ * The coordinates are fractions, and they draw the same shape they would as
+ * pixels.
+ */
+export default function DiagramDemo() {
+  return (
+    <Diagram
+      label="How a finding is produced, checked and published"
+      nodes={[
+        { id: 'capture', name: 'Capture', x: 0.12, y: 0.3 },
+        { id: 'read', name: 'Read', x: 0.5, y: 0.62, emphasis: true },
+        { id: 'review', name: 'Review', x: 0.88, y: 0.3 },
+        { id: 'publish', name: 'Publish', x: 0.5, y: 0.12 },
+      ]}
+      relations={[
+        { from: 'capture', to: 'read', label: 'feeds' },
+        { from: 'read', to: 'review', label: 'raises' },
+        { from: 'review', to: 'publish', label: 'confirms', indirect: true },
+        { from: 'publish', to: 'capture', label: 'returns' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`decorative`** `true` · required · default: — — Hides the drawing from assistive technology and drops the name. Use it when the surrounding sentence already says what the diagram shows, and nothing inside the hidden tree is named either: there is no `<title>` here, so there is no name stranded inside an `aria-hidden` subtree.
+**`label`** `never` · optional · default: —

package/dist/md/components/dialog.md

@@ -0,0 +1,128 @@
+# Dialog
+
+The modal surface for a decision or a short task, with a side-anchored sheet variant.
+
+```tsx
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose } from '@nanisoft/prism-ui/components/dialog'
+```
+
+## Overview
+
+A Dialog is a modal surface for a decision or a short task. It ships as
+`Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`,
+`DialogTitle`, `DialogDescription` and `DialogClose`. It also covers the old
+drawer pattern through the `side` prop on `DialogContent`: `center` is the modal
+card, and `top`, `bottom`, `left` and `right` anchor the panel to an edge as a
+sheet.
+
+While it is open the dialog traps focus, locks page scroll, closes on Escape and
+on an outside press, and returns focus to its trigger when it closes. Always
+render a `DialogTitle`: it names the dialog and is announced on open.
+
+## Guidelines
+
+### When to use
+
+Use a Dialog when the reader must stop and make a decision before continuing, or
+when a short task needs focus without losing the page behind it: a confirmation,
+a rename, or a compact form.
+
+### When not to use
+
+Do not use a Dialog for content that is not a task. Reading material or settings
+belong on a page or in a Popover.
+
+Do not stack dialogs, and do not use a centered Dialog for a long list or a
+full-screen form. The side variant covers a sheet.
+
+### Best practices
+
+- Always include a `DialogTitle`. It is the dialog's accessible name, and
+  without it a screen reader announces an unnamed dialog.
+- Put the primary action last in `DialogFooter`, and keep one primary action per
+  dialog.
+- For a destructive action, state the consequence in the `DialogDescription`,
+  not only in the button label.
+- The component returns focus to the trigger on close, so the reader resumes
+  where they left off. Do not move focus yourself.
+- Prefer the side variant on narrow screens when the reader is deciding about
+  content the centered card would cover.
+
+### Content guidelines
+
+- Make the title a short statement of the task: "Rename workspace", not "Are you
+  sure?".
+- Put the consequence in the description, in one sentence, before the actions.
+- Name the action in the confirming button: "Delete project", not "Confirm".
+
+**A centered modal and a side-anchored sheet, the old drawer re-expressed.**
+
+```tsx
+'use client'
+
+import { Button } from '@nanisoft/prism-ui/components/button'
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@nanisoft/prism-ui/components/dialog'
+
+/** A centered modal and a side-anchored sheet, the old drawer re-expressed. */
+export default function DialogDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Dialog>
+        <DialogTrigger>Rename workspace</DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Rename workspace</DialogTitle>
+            <DialogDescription>
+              The new name appears in every menu, link and email.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <DialogClose className="bg-background hover:bg-accent hover:text-accent-foreground h-9 rounded-md border px-4 text-sm font-medium">
+              Cancel
+            </DialogClose>
+            <Button>Rename</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog>
+        <DialogTrigger>Open filters</DialogTrigger>
+        <DialogContent side="right">
+          <DialogHeader>
+            <DialogTitle>Filters</DialogTitle>
+            <DialogDescription>Narrow the table to the rows you need.</DialogDescription>
+          </DialogHeader>
+          <p className="text-muted-foreground text-sm">
+            Filters open from the edge on a narrow screen, where a centered
+            dialog would hide the table.
+          </p>
+          <DialogFooter>
+            <DialogClose className="bg-background hover:bg-accent hover:text-accent-foreground h-9 rounded-md border px-4 text-sm font-medium">
+              Done
+            </DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`open`** `boolean` · optional · default: — — The controlled open state.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state, for an uncontrolled dialog.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the open state changes.
+**`modal`** `boolean | 'trap-focus'` · optional · default: `true` — Whether the dialog is modal.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and content.
+**`side`** `'center' | 'top' | 'bottom' | 'left' | 'right'` · optional · default: `center` — Where the dialog is anchored. `center` is a modal card; `top`, `bottom`, `left` and `right` anchor the panel to an edge as a sheet, which is the old drawer re-expressed.
+**`showCloseButton`** `boolean` · optional · default: `true` — Whether the built-in close control is rendered.

package/dist/md/components/dropdown-menu.md

@@ -0,0 +1,125 @@
+# DropdownMenu
+
+The menu of actions and choices opened from one trigger.
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuGroup, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent } from '@nanisoft/prism-ui/components/dropdown-menu'
+```
+
+## Overview
+
+A DropdownMenu is a list of actions and choices opened from one trigger. It
+ships as `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
+`DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioItem`,
+`DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuGroup`,
+`DropdownMenuSub`, `DropdownMenuSubTrigger` and `DropdownMenuSubContent`.
+
+The menu supports arrow-key navigation, typeahead by item label, Home and End,
+and Escape to close. A submenu opens from its trigger with the right arrow, and
+focus returns to the trigger when the menu closes.
+
+## Guidelines
+
+### When to use
+
+Use a DropdownMenu for a short list of commands attached to one control: a row's
+actions, an account menu, or a toolbar overflow. It keeps secondary actions out
+of the way without losing them.
+
+### When not to use
+
+Do not hide a primary action in a menu. If it is the main thing a view is for,
+keep it visible as a Button.
+
+Do not use a DropdownMenu for navigation between pages, and do not nest menus
+more than one level deep. Both cases want a page or a sidebar.
+
+### Best practices
+
+- Put a `DropdownMenuLabel` inside a `DropdownMenuGroup`. The label is tied to
+  its group, so it must have one.
+- Use `DropdownMenuCheckboxItem` for toggles that do not close the menu, so the
+  reader can change several in a row.
+- Put a destructive action last, after a `DropdownMenuSeparator`, with
+  `variant="destructive"`.
+- Keep items to a verb or a short noun phrase, and name the object when the
+  action is ambiguous: "Duplicate project" beats "Duplicate".
+- One level of `DropdownMenuSub` is the ceiling. Beyond that, promote the
+  commands to a page.
+
+### Content guidelines
+
+- Write items as imperative commands: "Duplicate", "Archive", "Sign out".
+- Use sentence case and no trailing periods.
+- Group related commands and label the group in sentence case, such as
+  "Account" or "Danger zone".
+
+**A menu with items, a checkbox item and a nested submenu.**
+
+```tsx
+'use client'
+
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from '@nanisoft/prism-ui/components/dropdown-menu'
+
+/** A menu with items, a checkbox item and a nested submenu. */
+export default function DropdownMenuDemo() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56">
+        <DropdownMenuGroup>
+          <DropdownMenuLabel>Account</DropdownMenuLabel>
+          <DropdownMenuItem>Profile</DropdownMenuItem>
+          <DropdownMenuItem>Settings</DropdownMenuItem>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuCheckboxItem defaultChecked>
+          Show archived rows
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>Invite</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>Send by email</DropdownMenuItem>
+            <DropdownMenuItem>Copy invite link</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem variant="destructive">Sign out</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+## Props
+
+**`open`** `boolean` · optional · default: — — The controlled open state.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state, for an uncontrolled menu.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the open state changes.
+**`disabled`** `boolean` · optional · default: — — Whether the menu ignores user interaction.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and the menu content.
+**`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `bottom` — Which side of the trigger the menu is placed on.
+**`align`** `'start' | 'center' | 'end'` · optional · default: `start` — How the menu aligns against the trigger.
+**`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the menu.
+**`alignOffset`** `number` · optional · default: `0` — The offset in pixels along the alignment axis.
+**`inset`** `boolean` · optional · default: `false` — Whether the item aligns with the labels above it.
+**`variant`** `'default' | 'destructive'` · optional · default: `default` — Whether the item reads as a destructive action.
+**`closeOnClick`** `boolean` · optional · default: `true` — Whether the menu closes when the item is chosen.
+**`checked`** `boolean` · optional · default: — — The controlled ticked state.
+**`defaultChecked`** `boolean` · optional · default: — — The initially ticked state, for an uncontrolled item.
+**`onCheckedChange`** `(checked: boolean) => void` · optional · default: — — Called when the ticked state changes.
+**`value`** `string` · optional · default: — — The controlled value of the selected radio item.
+**`defaultValue`** `string` · optional · default: — — The initially selected value, for an uncontrolled group.
+**`onValueChange`** `(value: string) => void` · optional · default: — — Called when the selected value changes.

package/dist/md/components/fact-list.md

@@ -0,0 +1,85 @@
+# FactList
+
+A short list of named facts as a definition list, where a value may be a link and the term column stays aligned down its length.
+
+```tsx
+import { FactList } from '@nanisoft/prism-ui/components/fact-list'
+```
+
+## Overview
+
+A FactList is a short list of named facts: a term beside its value, in a column a
+reader can scan. It renders a real `<dl>`, so a screen reader announces the term
+before the value instead of reading a list of labels and then a list of answers.
+
+Every NaniSoft site states facts beside prose: what a plan costs, what a feed
+carries, which version a document describes, when a collector went live. Each one
+re-derived a `<dl>`, and each one got the alignment and the term-before-value
+wiring subtly wrong.
+
+## Guidelines
+
+### When to use
+
+Use a FactList for two to six facts that belong to one thing and are worth reading
+together: a release, a feed source, a plan, a deployment.
+
+Use it beside prose rather than inside it. A fact in the middle of a paragraph is
+a sentence, and a sentence is not a fact list.
+
+### When not to use
+
+Do not use a FactList for a table of records. That is `Table`, and a fact list of
+twenty rows is a table with its column headers removed.
+
+Do not use it for a set of links. That is a footer's column or a plain list, and a
+column of destinations is not a column of terms.
+
+Do not use it to compare products. A comparison has a row per product and a column
+per fact, and this is the other way round.
+
+### Best practices
+
+- Keep the label column short. The column is a fixed fraction so a list of facts
+  lines up down its whole length, and a label that wraps costs every other row its
+  alignment.
+- Give a fact an `href` only when the fact is kept somewhere else. A link to a fact
+  already on the page is a click that changes nothing.
+- Omit `label` when the list is already inside something that names it.
+- An empty list renders nothing, so a caller with nothing to state does not get a
+  bordered box with a title above it.
+
+### Content guidelines
+
+- Write a label as a name, not a question: "Last capture", not "When did it last
+  capture".
+- Keep a value to a word or a short phrase. A value that needs a sentence belongs
+  in a `NoteGrid01` row.
+- Write values as they would be read aloud, because that is how they are scanned.
+
+**Named facts, with one value that is a link and one that is a count.**
+
+```tsx
+import { FactList } from '@nanisoft/prism-ui/components/fact-list'
+
+/** Named facts, with one value that is a link and one that is a count. */
+export default function FactListDemo() {
+  return (
+    <FactList
+      label="Release"
+      facts={[
+        { label: 'Version', value: '0.5.1' },
+        { label: 'Package', value: '@nanisoft/prism-ui' },
+        { label: 'Axes', value: 'Two: pack and mode' },
+        { label: 'Changelog', value: 'Read it', href: '/changelogs/prism-ui' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`facts`** `readonly Fact[]` · required · default: — — The facts, in the order a reader should meet them. Order is the caller's because it is a claim about importance, and a list that sorted itself would be making that claim on the caller's behalf.
+**`label`** `ReactNode` · optional · default: — — A heading above the list, for a set of facts that needs to say what it is. Rendered as a `dt`-level caption rather than as a heading, so it does not compete with the document's own outline.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.