shelving 1.236.2 → 1.237.0

package/ui/docs/DocumentationCard.md

@@ -0,0 +1,35 @@
+# DocumentationCard
+
+A compact link tile summarising a documented symbol — the default card renderer for `tree-documentation` elements in [`TreeCards`](/ui/TreeCards) directory listings. Each card links straight to the symbol's own page.
+
+**Things to know:**
+
+- It leads with the symbol's signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (the same calm code blocks as [`DocumentationPage`](/ui/DocumentationPage)). The signature already carries the name (and `readonly` for properties), so there is no separate title or kind tag — the card's *colour* carries the kind. Symbols with no signature (classes, interfaces, modules) fall back to a plain-name heading.
+- Below the heading it renders the symbol's [`DocumentationButtons`](/ui/DocumentationButtons) relations, then a prose lead-in. The `member of` relation is dropped — a member card almost always sits on its own class's page already.
+- The card links to the element's stamped `path` (the canonical URL set by `flattenTree()` — see [`TreeProvider`](/ui/TreeProvider)).
+
+## Usage
+
+Used automatically via [`TreeCards`](/ui/TreeCards) (which [`DocumentationPage`](/ui/DocumentationPage) uses for its child sections). To render a single card manually, spread the element's flattened props.
+
+```tsx
+import { DocumentationCard } from "shelving/ui";
+
+// `element` is a `tree-documentation` element from DirectoryExtractor (see /extract).
+<DocumentationCard {...element.props} />
+```
+
+To replace this renderer across the whole site, wrap the app in [`TreeCardMapping`](/ui/TreeCards).
+
+## Styling
+
+`DocumentationCard` has no own CSS hooks — it composes [`Card`](/ui/Card), [`Subheading`](/ui/Subheading), and [`Paragraph`](/ui/Paragraph). The card is tinted by `kind` via [`DocumentationKind`](/ui/DocumentationKind)'s colour map; retheme through `Card`'s `--card-*` hooks.
+
+## See also
+
+- [`DocumentationPage`](/ui/DocumentationPage) — the full detail page these cards link to.
+- [`DocumentationButtons`](/ui/DocumentationButtons) — the relations nav rendered inside the card.
+- [`DocumentationKind`](/ui/DocumentationKind) — supplies the colour that tints the card by kind.
+- [`TreeCards`](/ui/TreeCards) — the listing that dispatches cards, and the `*Mapping` override mechanism.
+- [`Card`](/ui/Card) — the surface this card is painted on.
+- [extract](/extract) — produces the `TreeElement` tree whose props this renderer consumes.

package/ui/docs/DocumentationCard.tsx

@@ -13,6 +13,7 @@ import { DocumentationSignatures } from "./DocumentationSignatures.js";
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
  *
+ * @kind component
  * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
  * @returns A `<Card>` linking to the symbol's own page.
  * @example <DocumentationCard {...element.props} />

package/ui/docs/DocumentationKind.d.ts

@@ -7,7 +7,7 @@ import type { UIColor } from "../style/Color.js";
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindProps
  */
 export interface DocumentationKindProps extends TagProps {
-    /** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
+    /** The documentation kind (e.g. `"component"`, `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
     readonly kind: string;
 }
 /**

package/ui/docs/DocumentationKind.js

@@ -1,14 +1,19 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tag } from "../misc/Tag.js";
-/** Mapping from a documented symbol's `kind` to its raw colour variant. */
+/**
+ * Mapping from a documented symbol's `kind` to its raw colour variant.
+ * - Related kinds share a hue: component/class (purple), function/method (blue), interface/type (aqua).
+ * - Leaves `orange`, `pink`, and the brand aliases free for future kinds.
+ */
 const KIND_COLOR = {
     module: "red",
-    function: "blue",
+    component: "purple",
     class: "purple",
+    function: "blue",
+    method: "blue",
     interface: "aqua",
-    type: "pink",
+    type: "aqua",
     constant: "green",
-    method: "orange",
     property: "yellow",
 };
 /**

package/ui/docs/DocumentationKind.tsx

@@ -8,19 +8,24 @@ import type { UIColor } from "../style/Color.js";
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindProps
  */
 export interface DocumentationKindProps extends TagProps {
-	/** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
+	/** The documentation kind (e.g. `"component"`, `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
 	readonly kind: string;
 }
 
-/** Mapping from a documented symbol's `kind` to its raw colour variant. */
+/**
+ * Mapping from a documented symbol's `kind` to its raw colour variant.
+ * - Related kinds share a hue: component/class (purple), function/method (blue), interface/type (aqua).
+ * - Leaves `orange`, `pink`, and the brand aliases free for future kinds.
+ */
 const KIND_COLOR: { readonly [K in string]?: UIColor } = {
 	module: "red",
-	function: "blue",
+	component: "purple",
 	class: "purple",
+	function: "blue",
+	method: "blue",
 	interface: "aqua",
-	type: "pink",
+	type: "aqua",
 	constant: "green",
-	method: "orange",
 	property: "yellow",
 };
 

package/ui/docs/DocumentationPage.d.ts

@@ -6,6 +6,7 @@ import type { DocumentationElementProps } from "../../util/tree.js";
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
+ * @kind component
  * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
  * @returns A `<Page>` containing the symbol's full documentation.
  * @example <DocumentationPage {...element.props} />

package/ui/docs/DocumentationPage.js

@@ -22,6 +22,7 @@ import { DocumentationSignatures } from "./DocumentationSignatures.js";
 const DEFAULT_TYPE = "unknown";
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
 const KIND_SECTIONS = {
+    component: "Components",
     function: "Functions",
     class: "Classes",
     interface: "Interfaces",
@@ -36,6 +37,7 @@ const KIND_SECTIONS = {
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
+ * @kind component
  * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
  * @returns A `<Page>` containing the symbol's full documentation.
  * @example <DocumentationPage {...element.props} />

package/ui/docs/DocumentationPage.md

@@ -0,0 +1,46 @@
+# DocumentationPage
+
+The full detail page for a documented symbol — the default renderer for `tree-documentation` elements dispatched by [`TreeApp`](/ui/TreeApp). It is the most detailed page renderer in the tree shell; render it directly only when you need a symbol page outside the tree, or replace it for one element type via [`TreePageMapping`](/ui/TreeRouter).
+
+**Things to know:**
+
+- Above the title it renders an ancestor trail via [`TreeBreadcrumbs`](/ui/TreeBreadcrumbs), so it needs a [`TreeProvider`](/ui/TreeProvider) above it to resolve the ancestors.
+- The title carries a [`DocumentationKind`](/ui/DocumentationKind) tag, and below it [`DocumentationButtons`](/ui/DocumentationButtons) lists the symbol's relations (`member of`, `extends`, `implements`) as links.
+- It renders the signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries.
+- Child symbols follow, grouped by `kind` into card sections (`Components`, `Functions`, `Classes`, `Interfaces`, `Types`, `Constants`, `Methods`, `Properties`) rendered as [`DocumentationCard`](/ui/DocumentationCard)s inside a [`TreeCards`](/ui/TreeCards) listing. A new documented kind needs an entry in `KIND_SECTIONS` here (and a colour in [`DocumentationKind`](/ui/DocumentationKind)).
+
+## Usage
+
+Used automatically by [`TreeApp`](/ui/TreeApp). To render a single page manually, spread the element's flattened props.
+
+```tsx
+import { DocumentationPage } from "shelving/ui";
+
+// `element` is a `tree-documentation` element from DirectoryExtractor (see /extract).
+<DocumentationPage {...element.props} />
+```
+
+To replace this renderer across the whole site, wrap the app in [`TreePageMapping`](/ui/TreeRouter).
+
+```tsx
+import { TreeApp, TreePageMapping } from "shelving/ui";
+
+<TreePageMapping mapping={{ "tree-documentation": MyDocumentationPage }}>
+  <TreeApp tree={tree} />
+</TreePageMapping>
+```
+
+## Styling
+
+`DocumentationPage` has no own CSS hooks — it composes [`Page`](/ui/Page), [`Panel`](/ui/Panel), [`Section`](/ui/Section), and the other block components, which carry their own themeable surfaces. Retheme through those.
+
+## See also
+
+- [`DocumentationCard`](/ui/DocumentationCard) — the compact card form of a symbol, used for the child sections here.
+- [`DocumentationButtons`](/ui/DocumentationButtons) — the relations nav rendered below the title.
+- [`DocumentationKind`](/ui/DocumentationKind) — the colour-coded kind tag carried by the title.
+- [`DocumentationSignatures`](/ui/DocumentationSignatures) — renders the symbol's signature blocks.
+- [`TreeApp`](/ui/TreeApp) — wires this renderer into a complete site via the page mappers.
+- [`TreeBreadcrumbs`](/ui/TreeBreadcrumbs) — the ancestor trail rendered above the title.
+- [extract](/extract) — produces the `TreeElement` tree whose props this renderer consumes.
+- [markup](/markup) — renders the Markdown `content` field carried by each element.

package/ui/docs/DocumentationPage.tsx

@@ -25,6 +25,7 @@ const DEFAULT_TYPE = "unknown";
 
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
 const KIND_SECTIONS = {
+	component: "Components",
 	function: "Functions",
 	class: "Classes",
 	interface: "Interfaces",
@@ -40,6 +41,7 @@ const KIND_SECTIONS = {
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
+ * @kind component
  * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
  * @returns A `<Page>` containing the symbol's full documentation.
  * @example <DocumentationPage {...element.props} />

package/ui/form/Button.d.ts

@@ -37,6 +37,7 @@ interface ButtonProps extends ButtonVariants, ClickableProps {
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
+ * @kind component
  * @example <Button onClick={save} color="primary">Save</Button>
  * @example <Button href="/about">About</Button>
  * @see https://dhoulb.github.io/shelving/ui/form/Button/Button

package/ui/form/Button.js

@@ -22,6 +22,7 @@ export function getButtonClass(variants) {
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
+ * @kind component
  * @example <Button onClick={save} color="primary">Save</Button>
  * @example <Button href="/about">About</Button>
  * @see https://dhoulb.github.io/shelving/ui/form/Button/Button

package/ui/form/Button.md

@@ -0,0 +1,88 @@
+# Button
+
+A clickable styled as a solid button. Renders an `<a href="">` when given `href`, or a `<button>` when given `onClick` — the shared `Clickable` primitive picks the element, so a button is always the right semantics for what it does.
+
+**Things to know:**
+
+- Content-width by default: it sizes to its label and never grows. Pass `full` to fill the available width (it then shrinks to share a row, down to the content floor).
+- `strong` marks the default action in a form — a filled background instead of an outline. `plain` and `outline` drop the background until hover/focus.
+- `color=` / `status=` move the tint anchor, so the background, border and label re-derive from the same ladder; `small` tightens the padding.
+- `getButtonClass(variants)` returns the same `className` the component composes — use it to style a non-`<button>` element as a button when `Button` itself doesn't fit.
+
+## Usage
+
+### Actions and links
+
+```tsx
+import { Button } from "shelving/ui";
+
+<Button onClick={save} color="primary" strong>Save</Button>
+<Button href="/about">About</Button>
+<Button onClick={remove} status="error">Delete</Button>
+```
+
+### A row of buttons
+
+```tsx
+import { Button } from "shelving/ui";
+import { Row } from "shelving/ui";
+
+<Row gap="small" right>
+  <Button plain onClick={cancel}>Cancel</Button>
+  <Button strong onClick={submit}>Continue</Button>
+</Row>
+```
+
+### Reusing the button class
+
+```tsx
+import { getButtonClass } from "shelving/ui";
+
+// Style an arbitrary element as a button.
+<label className={getButtonClass({ color: "primary", small: true })}>
+  Upload<input type="file" hidden />
+</label>
+```
+
+## Styling
+
+`Button` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` or any ancestor scope; move `--button-tint` to recolour the whole button, or use a per-property hook for one change.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--button-tint` | Tint anchor for the button scope | `inherit` (flows from `color=` / `status=` / parent) |
+| `--button-background` | Surface fill | `var(--tint-90)` |
+| `--button-hover-background` | Surface fill on hover / focus | `var(--tint-95)` |
+| `--button-text` | Label colour | `var(--tint-50)` |
+| `--button-border` | Border shorthand | `var(--button-stroke) solid var(--tint-80)` |
+| `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
+| `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
+| `--button-padding` | Inner padding | `var(--space-small)` (12px) |
+| `--button-small-padding` | Inner padding when `small` | `var(--space-xxsmall)` (4px) |
+| `--button-space` | Outer block margin | `var(--space-small)` (12px) |
+| `--button-font` | Font family | `var(--font-body)` |
+| `--button-weight` | Font weight | `var(--weight-strong)` (700) |
+| `--button-size` | Font size | `var(--size-normal)` |
+| `--button-leading` | Line height | `var(--leading)` |
+| `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
+| `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
+| `--button-disabled-opacity` | Opacity when disabled | `0.5` |
+| `--button-strong-background` | Fill when `strong` | `var(--tint-50)` |
+| `--button-strong-text` | Label colour when `strong` | `var(--tint-100)` |
+| `--button-strong-border` | Border when `strong` | `var(--button-stroke) solid transparent` |
+| `--button-strong-hover-background` | Hover fill when `strong` | `var(--tint-55)` |
+
+**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90` / `--tint-95` / `--tint-100` / `--tint-55`, plus `--space-small`, `--space-xxsmall`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--font-body`, `--weight-strong`, `--size-normal`, `--leading`, and `--duration-fast`.
+
+```css
+/* Theme: pill-shaped buttons. */
+:root {
+  --button-radius: 999px;
+}
+```
+
+## See also
+
+- [`Clickable`](/ui/Clickable) — the unstyled click/press primitive `Button` delegates to.
+- [`Link`](/ui/Link) — an inline text link (vs. a button-styled `<a>`).
+- [`ui`](/ui) — the styling system: tint ladder, cascade layers, and theming.

package/ui/form/Button.tsx

@@ -50,6 +50,7 @@ interface ButtonProps extends ButtonVariants, ClickableProps {}
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
+ * @kind component
  * @example <Button onClick={save} color="primary">Save</Button>
  * @example <Button href="/about">About</Button>
  * @see https://dhoulb.github.io/shelving/ui/form/Button/Button

package/ui/form/Field.d.ts

@@ -13,5 +13,10 @@ export interface FieldProps extends ChildProps {
     /** Render at half width (50%) so two fields sit side-by-side; defaults to full width (one per row). */
     half?: boolean | undefined;
 }
-/** A `<Field>` wraps around a form control/input, to shows a small `<label>` above it. */
+/**
+ * A `<Field>` wraps around a form control/input, to shows a small `<label>` above it.
+ *
+ * @kind component
+ * @see https://dhoulb.github.io/shelving/ui/form/Field/Field
+ */
 export declare function Field({ title, description, message, half, children }: FieldProps): ReactElement;

package/ui/form/Field.js

@@ -2,7 +2,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Message } from "../notice/Message.js";
 import { getClass } from "../util/css.js";
 import styles from "./Field.module.css";
-/** A `<Field>` wraps around a form control/input, to shows a small `<label>` above it. */
+/**
+ * A `<Field>` wraps around a form control/input, to shows a small `<label>` above it.
+ *
+ * @kind component
+ * @see https://dhoulb.github.io/shelving/ui/form/Field/Field
+ */
 export function Field({ title, description, message, half, children }) {
     return (_jsxs("label", { className: getClass(styles.field, half && styles.half), children: [(title || description) && (_jsxs("div", { children: [title ? _jsx("div", { className: styles.title, children: title }) : null, description && _jsx("div", { className: styles.description, children: description })] })), children, message && (_jsx(Message, { status: "error", right: true, children: message }))] }));
 }

package/ui/form/Field.md

@@ -0,0 +1,59 @@
+# Field
+
+The visual wrapper for a single form control. `Field` renders a `<label>` with an optional title and description above the input, and an inline error message below it. Use it when composing inputs by hand rather than relying on the automatic fields rendered by [`Form`](/ui/Form).
+
+**Things to know:**
+
+- Full width by default (one field per row). Pass `half` to render at 50% so two fields sit side-by-side.
+- The `message` prop renders below the input as an error `Message` — wire it to the field's error string.
+- `FormInput name="…"` combines a field's value, error, and schema lookup from the surrounding `FormContext`; reach for `Field` directly when you want explicit control over the label and layout.
+
+## Usage
+
+### Standalone field
+
+```tsx
+import { Field, TextInput } from "shelving/ui";
+
+<Field title="Email address" message={emailError}>
+  <TextInput name="email" value={email} onValue={setEmail} required />
+</Field>
+```
+
+### Two-up layout
+
+```tsx
+import { Field, TextInput } from "shelving/ui";
+
+<Field title="First name" half>
+  <TextInput name="first" value={first} onValue={setFirst} />
+</Field>
+<Field title="Last name" half>
+  <TextInput name="last" value={last} onValue={setLast} />
+</Field>
+```
+
+## Styling
+
+`Field` paints its label, description, and message text. Override these hooks at `:root` or any ancestor scope.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--field-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+| `--field-gap` | Gap between label, control, and message | `var(--space-xsmall)` |
+| `--field-title-size` | Title font size | `var(--size-normal)` |
+| `--field-title-weight` | Title font weight | `var(--weight-strong)` |
+| `--field-color-title` | Title colour | `var(--tint-00)` |
+| `--field-description-size` | Description font size | `var(--size-normal)` |
+| `--field-description-weight` | Description font weight | `var(--weight-normal)` |
+| `--field-color-description` | Description colour | `var(--shade-dark)` |
+| `--field-message-weight` | Message font weight | `var(--weight-strong)` |
+| `--field-color-message` | Message colour | `var(--color-red)` |
+
+**Global tokens it reads:** the tint ladder `--tint-00`, plus `--space-paragraph`, `--space-xsmall`, `--size-normal`, `--weight-strong`, `--weight-normal`, `--shade-dark`, and `--color-red`.
+
+## See also
+
+- [`Form`](/ui/Form) — renders fields automatically from a schema.
+- [`SchemaInput`](/ui/SchemaInput) — the control `SchemaField` drops inside a `Field`.
+- [ui](/ui) — top-level UI module index.

package/ui/form/Field.tsx

@@ -18,7 +18,12 @@ export interface FieldProps extends ChildProps {
 	half?: boolean | undefined;
 }
 
-/** A `<Field>` wraps around a form control/input, to shows a small `<label>` above it. */
+/**
+ * A `<Field>` wraps around a form control/input, to shows a small `<label>` above it.
+ *
+ * @kind component
+ * @see https://dhoulb.github.io/shelving/ui/form/Field/Field
+ */
 export function Field({ title, description, message, half, children }: FieldProps): ReactElement {
 	return (
 		// biome-ignore lint/a11y/noLabelWithoutControl: Generally `children` will contain a field.

package/ui/form/Form.d.ts

@@ -38,6 +38,7 @@ export interface FormProps<T extends Data> extends OptionalChildProps {
  *
  * @param props Props including `schema`, initial `data`, `onSubmit`, `submit` content, and initial `messages`.
  * @returns A `<form>` element wrapping the fields in a `FormContext` provider.
+ * @kind component
  * @example <Form schema={USER_SCHEMA} onSubmit={save} />
  * @see https://dhoulb.github.io/shelving/ui/form/Form/Form
  */

package/ui/form/Form.md

@@ -0,0 +1,118 @@
+# Form
+
+The entry point for shelving forms. `Form` creates a [`FormStore`](/ui/FormStore) from a `schema` prop, wraps everything in an HTML `<form>`, disables the whole fieldset while busy, and calls `onSubmit` on a valid submit. Build validated, schema-driven forms from a handful of composable pieces, or drop in a single `<Form>` for a fully automatic experience.
+
+**Things to know:**
+
+- If you provide no `children`, `Form` renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message), so a usable form is one prop away.
+- Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
+- The whole `<fieldset>` is disabled while a submit is in flight, so inputs and buttons lock automatically.
+- A successful submit inside a `<dialog>` closes the dialog automatically.
+- Notices are surfaced from the `onSubmit` return/throw — see [Notices and error surfacing](#notices-and-error-surfacing) below.
+
+## Usage
+
+### Automatic form
+
+With no `children`, `Form` renders one input per schema property plus a footer.
+
+```tsx
+import { Form } from "shelving/ui";
+import { DATA, StringSchema, NumberSchema } from "shelving/schema";
+
+const PRODUCT_SCHEMA = DATA({
+  name: new StringSchema({ title: "Name", min: 1, max: 100 }),
+  price: new NumberSchema({ title: "Price", min: 0 }),
+});
+
+export function NewProductForm() {
+  return (
+    <Form
+      schema={PRODUCT_SCHEMA}
+      submit="Create product"
+      onSubmit={async data => {
+        await createProduct(data);
+        return "Product created"; // dispatched as a success notice
+      }}
+    />
+  );
+}
+```
+
+### Edit form with seeded data
+
+```tsx
+import { Form } from "shelving/ui";
+import { DATA, StringSchema, NumberSchema, BOOLEAN } from "shelving/schema";
+
+const LISTING_SCHEMA = DATA({
+  title: new StringSchema({ title: "Title", min: 1, max: 80 }),
+  price: new NumberSchema({ title: "Price", min: 0 }),
+  published: BOOLEAN,
+});
+
+export function ListingForm({ listing }: { listing?: typeof LISTING_SCHEMA.type }) {
+  return (
+    <Form
+      schema={LISTING_SCHEMA}
+      data={listing}
+      submit={listing ? "Save changes" : "Publish listing"}
+      onSubmit={async data => {
+        await saveListing(data);
+        return listing ? "Listing updated" : "Listing published";
+      }}
+    />
+  );
+}
+```
+
+### Custom layout
+
+Provide explicit `children` when you need control over field order, groupings, or extra buttons. `<FormInput name="…">` uses `useField()` to pull the current value, error, and schema from context, then delegates to [`SchemaInput`](/ui/SchemaInput) so each field renders the correct control type.
+
+```tsx
+import { Form, Field, FormInput, SubmitButton, Button, FormMessage } from "shelving/ui";
+
+<Form schema={LISTING_SCHEMA} data={listing} onSubmit={handleSubmit}>
+  <Field title="Title" required>
+    <FormInput name="title" />
+  </Field>
+  <Field title="Price">
+    <FormInput name="price" />
+  </Field>
+  <FormInput name="published" />
+  <footer>
+    <SubmitButton>Save changes</SubmitButton>
+    <Button plain onClick={onCancel}>Cancel</Button>
+    <FormMessage />
+  </footer>
+</Form>
+```
+
+## Notices and error surfacing
+
+When an `onSubmit` callback returns a non-empty `ReactNode`, `Form` dispatches it as a success notice. When it throws a **string**, the string is parsed into field messages — any line matching `"fieldName: message"` maps to that field's error display; an unmatched remainder appears as the form-wide message shown by `<FormMessage>`. Non-string throws become global error notices. The string-splitting rule comes from [schema](/schema).
+
+- `<FormMessage>` renders the top-level `""` message inline as a `<Message>`.
+- `<FormNotice>` renders it as a larger `<Notice>` block.
+- `<FormNotify>` (no JSX output) forwards the message to the global notice system via a side effect instead.
+
+## Styling
+
+`Form` only lays out its block flow — it exposes a single spacing hook and otherwise inherits styling from the components inside it.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--form-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+
+**Global tokens it reads:** `--space-paragraph`.
+
+## See also
+
+- [`FormStore`](/ui/FormStore) — the reactive state class underlying every form.
+- [`Field`](/ui/Field) — the label + input + error wrapper for a single control.
+- [`SchemaInput`](/ui/SchemaInput) — the schema-to-input dispatch component.
+- [`SubmitButton`](/ui/SubmitButton) — submit button that reads the surrounding form's busy state.
+- [schema](/schema) — `DataSchema`, `StringSchema`, `NumberSchema`, and the other schema types that drive automatic input selection.
+- [react](/react) — `useStore`, `useInstance`, and other hooks used internally.
+- [ui](/ui) — top-level UI module index.

package/ui/form/Form.tsx

@@ -51,6 +51,7 @@ export interface FormProps<T extends Data> extends OptionalChildProps {
  *
  * @param props Props including `schema`, initial `data`, `onSubmit`, `submit` content, and initial `messages`.
  * @returns A `<form>` element wrapping the fields in a `FormContext` provider.
+ * @kind component
  * @example <Form schema={USER_SCHEMA} onSubmit={save} />
  * @see https://dhoulb.github.io/shelving/ui/form/Form/Form
  */

package/ui/form/FormStore.md

@@ -0,0 +1,47 @@
+# FormStore
+
+The reactive brain behind every form. `FormStore` extends `DataStore` from [store](/store) and owns the current (partial) field values, a `messages` dictionary of per-field errors, and the validate/submit helpers that drive a [`Form`](/ui/Form).
+
+**Things to know:**
+
+- It holds the current (possibly partial and invalid) field values plus a `messages` dictionary — error strings keyed by field name, with a top-level `""` key for form-wide messages.
+- `validated` is a getter that runs the schema and returns fully-typed data or throws a string on failure.
+- `publish(name, value)` validates a single field, writes the result, and stores any per-field error (it persists the raw value even when invalid, so nothing is lost on the way to submit).
+- `submit(callback)` validates the whole form and, if valid, runs the callback.
+- Assigning a string to `reason` splits it into per-field messages (using the `"fieldName: message"` line format from [schema](/schema)) instead of recording a global failure; any non-string reason is surfaced as-is.
+- You rarely construct `FormStore` directly — [`Form`](/ui/Form) does it for you — but you can grab it from context with `requireForm()` when you need it.
+
+## Usage
+
+### Direct construction
+
+```tsx
+import { FormStore } from "shelving/ui";
+import { DATA, StringSchema } from "shelving/schema";
+
+const USER_SCHEMA = DATA({ name: new StringSchema({ title: "Name", min: 1 }) });
+
+const store = new FormStore(USER_SCHEMA, { name: "Dave" });
+
+store.publish("name", "Dave Houlbrooke"); // Validate + write a single field.
+const data = store.validated; // Fully-typed data, or throws a string message.
+```
+
+### Reading the store from context
+
+```tsx
+import { requireForm } from "shelving/ui";
+
+function ResetButton() {
+  const store = requireForm();
+  return <Button plain onClick={() => store.set("name", "")}>Clear name</Button>;
+}
+```
+
+## See also
+
+- [`Form`](/ui/Form) — the component that creates and provides a `FormStore`.
+- [`Field`](/ui/Field) — renders a single field's value and message from the store.
+- [store](/store) — `DataStore` and the reactive store family `FormStore` builds on.
+- [schema](/schema) — schema validation and the `"fieldName: message"` split format.
+- [react](/react) — `useStore`, `useInstance`, and other hooks used to subscribe to the store.

package/ui/form/SchemaInput.d.ts

@@ -37,6 +37,7 @@ export interface SchemaInputProps<T extends Schema, I = never> extends ValueInpu
  * @param props Props including the `schema` plus value input props.
  * @returns The matching input element for the schema.
  * @throws `UnexpectedError` if no input matches the schema type.
+ * @kind component
  * @example <SchemaInput name="email" schema={EMAIL} /> // Outputs a `<TextInput>` for the "email" property.
  * @example <SchemaInput name="age" schema={AGE} /> // Outputs a `<NumberInput>` for the "age" property.
  * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInput