themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/features--rich-text-editor--tiptap.md

@@ -19,7 +19,7 @@ import { createTiptapEngine } from "themelia-ui/features/rich-text-editor/tiptap
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
@@ -27,7 +27,7 @@ npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
 
 ## Composition
 
-This family has no component-family dependencies.
+This module depends on no other module.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -54,5 +54,5 @@ Kind: interface.
 
 ## Preview recipes
 
-No dedicated recipe is currently attributed to this family. Use the public declarations
+No dedicated recipe is currently attributed to this module. Use the public declarations
 above and the composition guide; this absence is explicit and verification-visible.

package/docs/generated/components/features--rich-text-editor.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/rich-text-editor.css"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
@@ -28,7 +28,7 @@ npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
 
 ## Composition
 
-This family composes `base/text-inputs`, `base/toolbar`, `base/typography`, `features/rich-text-editor/tiptap`.
+This module composes `base/text-inputs`, `base/toolbar`, `base/typography`, `features/rich-text-editor/tiptap`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -55,8 +55,9 @@ RichTextEditorStrings
 
 Kind: callable.
 
-Character and word counts. Over the limit the count turns error-toned; input is never
-refused, so the form decides.
+The word and character counts under the editor. Over the limit the count turns error-toned;
+input is never refused, so the form decides. Separate because a limit is often shown beside a
+submit button rather than under the field it applies to.
 
 ```text
 ({ text, maxLength, strings, className }: EditorCountsProps) => import("react").JSX.Element
@@ -150,6 +151,9 @@ Kind: type.
 
 Kind: callable.
 
+An editing surface with a toolbar and an imperative handle. Content is controlled through
+`value` and `onValueChange`; the handle covers what a prop cannot.
+
 ```text
 ({ engine, value, onValueChange, placeholder, compact, minHeight, maxHeight, disabled, showCounts, maxLength, extraToolbarItems, toolbarTrailing, footerSlot, hideSourceToggle, autoFocus, className, onCaretChange, strings, ref, }: RichTextEditorProps & { ref?: Ref<RichTextEditorHandle>; }) => import("react").JSX.Element
 ```
@@ -158,6 +162,10 @@ Kind: callable.
 
 Kind: interface.
 
+The editor's imperative handle, for what a prop cannot do: caret context, and replacing text
+before the caret. A superset of MentionEditorHandle, so the two plug together with no
+adapter.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `focus` | yes | `void` |  |
@@ -167,7 +175,7 @@ Kind: interface.
 | `isEmpty` | yes | `boolean` |  |
 | `clear` | yes | `void` |  |
 | `getCaretContext` | yes | `RichTextCaretContext \| null` |  |
-| `replaceBeforeCaret` | yes | `void` | Deletes the `length` characters before the caret and inserts `html` in their place,<br>as one operation (one undo entry, no intermediate caret state). |
+| `replaceBeforeCaret` | yes | `void` | Deletes the `length` characters before the caret and inserts `html` in their place, as<br>one operation, not a delete then an insert: the caret never visits an in-between state,<br>and undo gets one entry for what the writer experienced as one act. |
 
 ### `RichTextEditorProps`
 
@@ -175,23 +183,23 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `engine` | no | `RichTextEngine` | What edits the document. Defaults to TipTap with StarterKit and inline mentions; the<br>chrome (toolbar, source view, counts, footer, strings) is engine-independent. Install<br>the family's documented TipTap peers when importing the editor. |
-| `value` | yes | `string` | The document, as HTML. Controlled. |
-| `onValueChange` | yes | `(html: string) => void` |  |
-| `placeholder` | no | `string` | Drawn over the empty document. |
-| `compact` | no | `boolean` | Tightens the toolbar and shortens the body, for a composer rather than a page. |
+| `engine` | no | `RichTextEngine` | What edits the document. Defaults to TipTap with StarterKit and inline, atomic mentions;<br>supply a RichTextEngine for a custom schema or implementation, and the caller owns its<br>destruction. The chrome (toolbar, source view, counts, footer, strings) is<br>engine-independent. Install the family's documented TipTap peers when importing the<br>editor. @default TipTap |
+| `value` | yes | `string` | The document, as HTML. Controlled: parent echoes preserve the selection, and actual<br>external changes update the document, including while it is focused. Output is normalized<br>to the active engine's schema. |
+| `onValueChange` | yes | `(html: string) => void` | Receives the document, as HTML, after every edit. |
+| `placeholder` | no | `string` | Drawn over the first line of the empty document, because a contenteditable has no<br>placeholder attribute. Sitting over it rather than replacing the document means the caret<br>is already in the right place. |
+| `compact` | no | `boolean` | Tightens the toolbar and shortens the body, for a composer rather than a page: a line and a<br>half instead of a page — enough to look like it takes more than a word, without claiming a<br>screen for a one-sentence reply. |
 | `minHeight` | no | `string` |  |
 | `maxHeight` | no | `string` | Where the body starts scrolling instead of growing. |
 | `disabled` | no | `boolean` |  |
-| `showCounts` | no | `boolean` |  |
-| `maxLength` | no | `number` | Shown as "n / max". Does not truncate: the count reports, the form decides. |
-| `extraToolbarItems` | no | `ReadonlyArray<RichTextEditorToolbarItem>` |  |
-| `toolbarTrailing` | no | `ReactNode` | Pinned to the end of the toolbar, usually the submit control. |
-| `footerSlot` | no | `ReactNode` | Below the body: attachment chips, a hint. |
+| `showCounts` | no | `boolean` | Shows the word and character counts under the body. |
+| `maxLength` | no | `number` | Shown as "n / max". Over the limit the count turns error-toned; input is NOT refused — a<br>composer that stops accepting characters mid-word loses what the writer was in the middle<br>of. The count reports, the form decides. |
+| `extraToolbarItems` | no | `ReadonlyArray<RichTextEditorToolbarItem>` | Appended after the built-ins, behind a rule. Each takes an icon, a label used for both the<br>accessible name and the tooltip, and an optional `isActive`. |
+| `toolbarTrailing` | no | `ReactNode` | Pinned to the end of the toolbar, usually the submit control. Inside the frame, like<br>`footerSlot`, so the composer reads as one control. |
+| `footerSlot` | no | `ReactNode` | Below the body: attachment chips, a hint. Inside the frame, like `toolbarTrailing`, so the<br>composer reads as one control. |
 | `hideSourceToggle` | no | `boolean` |  |
 | `autoFocus` | no | `boolean` |  |
 | `className` | no | `string` |  |
-| `onCaretChange` | no | `() => void` | Fires after every input and every selection change (the caret can move without the<br>document changing); read `getCaretContext()` from the handle in response. |
+| `onCaretChange` | no | `() => void` | Fires after every input AND every selection change; read `getCaretContext()` from the<br>handle in response. Two events, because a caret moves without the document changing — and<br>a trigger detector watching only input misses the writer moving back into a half-typed<br>mention. |
 | `strings` | no | `Partial<RichTextEditorStrings>` |  |
 
 ### `RichTextEditorStrings`
@@ -210,6 +218,9 @@ Kind: interface.
 
 Kind: callable.
 
+The formatting row, exported so an editor can be mounted with the toolbar somewhere else — a
+sticky bar above a long document, or a shared bar over two editors.
+
 ```text
 ({ buttons, extraToolbarItems, hideSourceToggle, sourceMode, toggleSourceMode, disabled, toolbarTrailing, strings, className, }: RichTextEditorToolbarProps) => import("react").JSX.Element
 ```
@@ -304,28 +315,98 @@ The shape the toolbar renders. Built-ins and consumer items resolve to this.
 
 Preview route: Rich text editor — `/rich-text-editor`
 
-### The editor
+### The editor and what comes out
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<RichTextEditor
-  value={body}
-  onValueChange={setBody}
-  showCounts
-  maxLength={280}
-  placeholder="Write something…"
-/>
+import { useState } from "react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { DisplayLabel, RichText, Text } from "themelia-ui/base/typography"
+import { RichTextEditor } from "themelia-ui/features/rich-text-editor"
+
+import styles from "./editor.module.css"
+
+const SEED = "<p>Select some text and press <strong>B</strong>. The toolbar reports what the caret is inside, so the buttons light up as you move through the document.</p><ul><li>Lists work.</li><li>So does <em>emphasis</em>.</li></ul>"
+
+export default function Editor() {
+	const [body, setBody] = useState(SEED)
+
+	return (
+		<>
+			<RichTextEditor
+				value={body}
+				onValueChange={setBody}
+				placeholder="Write something…"
+				showCounts
+				maxLength={280}
+			/>
+
+			<Stack gap="xs">
+				<DisplayLabel>Emitted HTML</DisplayLabel>
+				<Text size="xs" type="secondary" className={styles.source}>
+					{body || "(empty)"}
+				</Text>
+			</Stack>
+
+			<Stack gap="xs">
+				<DisplayLabel>Rendered through RichText</DisplayLabel>
+				<RichText html={body} />
+			</Stack>
+		</>
+	)
+}
 ```
 
 ### compact
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<RichTextEditor
-  compact
-  value={note}
-  onValueChange={setNote}
-  hideSourceToggle
-  footerSlot={<><AttachmentChips /><Button>Post</Button></>}
-/>
+import { AtSignIcon, PaperclipIcon } from "lucide-react"
+import { useRef, useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { RichTextEditor, type RichTextEditorHandle } from "themelia-ui/features/rich-text-editor"
+
+export default function EditorCompact() {
+	const [note, setNote] = useState("")
+	const composerRef = useRef<RichTextEditorHandle>(null)
+
+	return (
+		<RichTextEditor
+			ref={composerRef}
+			compact
+			value={note}
+			onValueChange={setNote}
+			placeholder="Add a note…"
+			hideSourceToggle
+			extraToolbarItems={[
+				{
+					id: "mention",
+					icon: AtSignIcon,
+					label: "Insert reference",
+					onClick: () => composerRef.current?.insertHTML("@"),
+				},
+				{
+					id: "attach",
+					icon: PaperclipIcon,
+					label: "Attach a file",
+					onClick: () => undefined,
+				},
+			]}
+			footerSlot={
+				<Stack direction="horizontal" align="center" justify="between" gap="md">
+					<Text size="xs" type="secondary">
+						Markdown is not parsed — use the toolbar.
+					</Text>
+					<Button disabled={!note} onClick={() => setNote("")}>
+						Post
+					</Button>
+				</Stack>
+			}
+		/>
+	)
+}
 ```
 
 ### Custom engines

package/docs/generated/components/features--schema-form.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/schema-form.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/structure`, `base/text-inputs`, `base/value-inputs`.
+This module composes `base/badge`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/forms-numeric`, `base/structure`, `base/text-inputs`, `base/value-inputs`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -92,6 +92,9 @@ Empty sections are dropped.
 
 Kind: callable.
 
+Renders and validates a form described as data. `validate()` runs on submit, and a message
+clears as soon as its field changes.
+
 ```text
 ({ schema, value, defaultValue, errors, disabled, layout, columns, id, name, title, description, headerSlot, footerSlot, actionsSlot, emptySlot, showActions, submitLabel, resetLabel, submitDisabled, resetDisabled, submitting, onValueChange, onFieldChange, onSubmit, onReset, onError, renderField, renderSection, strings, className, contentClassName, sectionClassName, fieldClassName, }: SchemaFormProps) => import("react").JSX.Element
 ```
@@ -100,6 +103,10 @@ Kind: callable.
 
 Kind: callable.
 
+The form's submit row, generated from the same schema; reset renders only when there is an
+`onReset` for it to reach. Exported so a screen can place it somewhere the generated layout
+does not — a drawer footer, a sticky bar.
+
 ```text
 ({ submitLabel, resetLabel, showReset, disabled, submitDisabled, resetDisabled, submitting, onReset, className, }: SchemaFormActionsProps) => import("react").JSX.Element
 ```
@@ -172,26 +179,28 @@ SchemaFormTextField | SchemaFormTextareaField | SchemaFormNumberField | SchemaFo
 
 Kind: interface.
 
+The keys every field shares, whatever its `type`.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `key` | yes | `string` |  |
-| `type` | no | `SchemaFormFieldType` |  |
+| `type` | no | `SchemaFormFieldType` | Picks the control. Omitted means `text`. |
 | `label` | yes | `string` |  |
 | `description` | no | `string` |  |
 | `hint` | no | `string` |  |
 | `helperText` | no | `string` |  |
 | `placeholder` | no | `string` |  |
 | `required` | no | `boolean` |  |
-| `disabled` | no | `boolean \| ((values: SchemaFormValues) => boolean)` | A function form, for a field only editable once a sibling says so. |
-| `hidden` | no | `boolean \| ((values: SchemaFormValues) => boolean)` | A hidden field is not rendered AND not validated. |
+| `disabled` | no | `boolean \| ((values: SchemaFormValues) => boolean)` | The predicate form reads the whole value set, for a field only editable once a sibling<br>says so. |
+| `hidden` | no | `boolean \| ((values: SchemaFormValues) => boolean)` | A hidden field is not rendered AND not validated — blocking a submit on a required field<br>the reader cannot see is a dead end. The predicate form reads the whole value set, for a<br>field that only matters once a sibling says so. |
 | `defaultValue` | no | `SchemaFormValue` |  |
 | `sectionId` | no | `string` | Puts the field in a section without listing it there. |
-| `width` | no | `SchemaFormFieldWidth` |  |
+| `width` | no | `SchemaFormFieldWidth` | Column span inside the section grid, which is keyed to a container. A form in a 320px<br>drawer collapses to one column whatever the section asked for. |
 | `className` | no | `string` |  |
 | `controlClassName` | no | `string` | Merged onto the control rather than the field wrapper. |
-| `validate` | no | `SchemaFormValidator \| SchemaFormValidator[]` |  |
-| `formatValue` | no | `(value: SchemaFormValue, values: SchemaFormValues) => string` | Turns the stored value into what the control displays. |
-| `parseValue` | no | `(value: string, values: SchemaFormValues) => SchemaFormValue` | Turns what the control produced back into the stored value. |
+| `validate` | no | `SchemaFormValidator \| SchemaFormValidator[]` | Return a string to fail. The first message wins: the rest are about a value already known<br>to be wrong. |
+| `formatValue` | no | `(value: SchemaFormValue, values: SchemaFormValues) => string` | Turns the stored value into what the control displays: with `parseValue`, the two halves<br>of a custom representation. |
+| `parseValue` | no | `(value: string, values: SchemaFormValues) => SchemaFormValue` | Turns what the control produced back into the stored value: with `formatValue`, the two<br>halves of a custom representation. |
 | `meta` | no | `Record<string, unknown>` | Free-form payload, carried through to `renderField`. |
 
 ### `SchemaFormFieldContext`
@@ -224,6 +233,10 @@ Kind: type.
 
 Kind: callable.
 
+One field, resolved from its schema entry to a control, with FormField owning the label, hint
+and message. Reach for it when a form is mostly generated but one field needs to be placed by
+hand.
+
 ```text
 ({ field, value, values, error, disabled, required, fieldId, onValueChange, onError, strings, className, }: SchemaFormFieldRendererProps) => import("react").JSX.Element
 ```
@@ -319,12 +332,12 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `schema` | yes | `SchemaFormSchema` |  |
-| `value` | no | `SchemaFormValues` |  |
-| `defaultValue` | no | `SchemaFormValues` |  |
-| `errors` | no | `SchemaFormErrors` | Server-side messages, keyed by field. Merged over the form's own. |
+| `schema` | yes | `SchemaFormSchema` | Sections and fields. A section names its fields explicitly or claims the ones carrying its<br>`sectionId`; whatever no section claimed lands in a leading default bucket. |
+| `value` | no | `SchemaFormValues` | Controlled values. Under a controlled value the schema's own defaults still apply, so a<br>consumer holding two fields does not blank the rest. |
+| `defaultValue` | no | `SchemaFormValues` | Uncontrolled starting values. An explicit default outranks the schema's own. |
+| `errors` | no | `SchemaFormErrors` | Server-side messages, keyed by field. Merged over the form's own and not cleared by<br>typing. |
 | `disabled` | no | `boolean` |  |
-| `layout` | no | `SchemaFormLayout` |  |
+| `layout` | no | `SchemaFormLayout` | One bordered surface with sections inside it, or one surface per section. The schema does<br>not change between them. |
 | `columns` | no | `SchemaFormColumns` |  |
 | `id` | no | `string` |  |
 | `name` | no | `string` |  |
@@ -342,11 +355,11 @@ Kind: interface.
 | `submitting` | no | `boolean` | Additional external busy state. An async onSubmit also sets busy automatically. |
 | `onValueChange` | no | `(values: SchemaFormValues) => void` |  |
 | `onFieldChange` | no | `(key: string, value: SchemaFormValue, values: SchemaFormValues) => void` |  |
-| `onSubmit` | no | `(values: SchemaFormValues, helpers: SchemaFormSubmitHelpers, event: FormEvent<HTMLFormElement>) => void \| Promise<void>` |  |
+| `onSubmit` | no | `(values: SchemaFormValues, helpers: SchemaFormSubmitHelpers, event: FormEvent<HTMLFormElement>) => void \| Promise<void>` | Runs only if validation passed. `helpers` carries `setFieldValue`, `setValues`, `reset`,<br>and `validate` — for a server response that has to write back into the form. |
 | `onReset` | no | `(values: SchemaFormValues, helpers: SchemaFormSubmitHelpers) => void` |  |
 | `onError` | no | `(error: unknown) => void` | Receives errors from submission and consumer predicates, validators, or parsers. |
-| `renderField` | no | `(context: SchemaFormRenderFieldContext) => ReactNode` |  |
-| `renderSection` | no | `(context: SchemaFormRenderSectionContext) => ReactNode` |  |
+| `renderField` | no | `(context: SchemaFormRenderFieldContext) => ReactNode` | Replaces how a field renders. It receives `defaultField`, so decorating is as easy as<br>replacing. |
+| `renderSection` | no | `(context: SchemaFormRenderSectionContext) => ReactNode` | Replaces how a section renders, with its fields already laid out. |
 | `strings` | no | `Partial<SchemaFormStrings>` |  |
 | `className` | no | `string` |  |
 | `contentClassName` | no | `string` |  |
@@ -539,6 +552,10 @@ Record<string, SchemaFormValue>
 
 Kind: callable.
 
+The values, the errors, and `validate()` without any of the rendering. Server `errors` win
+over local messages for the same key; local messages clear on the field's next change,
+server messages stay until the consumer replaces them.
+
 ```text
 ({ fields, value, defaultValue, errors: externalErrors, onValueChange, onFieldChange, requiredError, validationError, onError, }: UseSchemaFormOptions) => UseSchemaFormResult
 ```
@@ -579,22 +596,241 @@ Preview route: Schema form — `/schema-form`
 ### One surface
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<SchemaForm
-  schema={{
-    sections: [{ id: "identity", title: "Identity", columns: 2 }],
-    fields: [
-      { key: "name", label: "Venue name", sectionId: "identity", required: true },
-      { key: "cutoff", type: "integer", label: "Cut-off",
-        hidden: (values) => values.selfService !== true },
-    ],
-  }}
-  onSubmit={(values) => api.save(values)}
-  onReset={() => undefined}
-/>
+import { useState } from "react"
+import { BuildingIcon, CreditCardIcon, SettingsIcon } from "lucide-react"
+
+import { Checkbox } from "themelia-ui/base/choice-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { SchemaForm, type SchemaFormSchema, type SchemaFormValues } from "themelia-ui/features/schema-form"
+
+const VENUE_SCHEMA: SchemaFormSchema = {
+	title: "Venue details",
+	description: "What appears on the booking confirmation.",
+	sections: [
+		{ id: "identity", title: "Identity", icon: <BuildingIcon />, columns: 2 },
+		{
+			id: "commercial",
+			title: "Commercial",
+			description: "Only the deposit is shown to the customer.",
+			icon: <CreditCardIcon />,
+			columns: 2,
+		},
+		{ id: "advanced", title: "Advanced", icon: <SettingsIcon />, columns: 1 },
+	],
+	fields: [
+		{
+			key: "name",
+			label: "Venue name",
+			sectionId: "identity",
+			required: true,
+			placeholder: "Marlow Hall",
+			defaultValue: "Marlow Hall",
+		},
+		{
+			key: "email",
+			type: "email",
+			label: "Bookings email",
+			sectionId: "identity",
+			required: true,
+			placeholder: "bookings@example.com",
+			defaultValue: "bookings@marlowhall.example",
+			validate: (value) =>
+				typeof value === "string" && value.includes("@") ? true : "That is not an email address.",
+		},
+		{
+			key: "address",
+			type: "textarea",
+			label: "Address",
+			sectionId: "identity",
+			width: "full",
+			rows: 2,
+			defaultValue: "14 Bridge Street, Marlow",
+		},
+		{
+			key: "capacity",
+			type: "integer",
+			label: "Seated capacity",
+			sectionId: "commercial",
+			min: 0,
+			step: 10,
+			defaultValue: 180,
+		},
+		{
+			key: "deposit",
+			type: "decimal",
+			label: "Deposit",
+			sectionId: "commercial",
+			decimalPlaces: 2,
+			min: 0,
+			defaultValue: 300,
+			helperText: "Charged when the booking is confirmed.",
+		},
+		{
+			key: "tier",
+			type: "radio-cards",
+			label: "Rate card",
+			sectionId: "commercial",
+			width: "full",
+			columns: 3,
+			defaultValue: "standard",
+			options: [
+				{ value: "standard", label: "Standard", description: "The published rate." },
+				{ value: "partner", label: "Partner", description: "15% off, invoiced monthly." },
+				{ value: "internal", label: "Internal", description: "No charge." },
+			],
+		},
+		{
+			key: "amenities",
+			type: "checkbox-cards",
+			label: "Included",
+			sectionId: "commercial",
+			width: "full",
+			columns: 3,
+			defaultValue: ["bar"],
+			options: [
+				{ value: "bar", label: "Bar" },
+				{ value: "kitchen", label: "Kitchen" },
+				{ value: "parking", label: "Parking" },
+			],
+		},
+		{
+			key: "tags",
+			type: "tags",
+			label: "Tags",
+			sectionId: "advanced",
+			maxTags: 5,
+			recommendations: ["wedding", "conference", "accessible", "late licence"],
+			defaultValue: ["wedding"],
+		},
+		{
+			key: "selfService",
+			type: "switch",
+			switchStyle: "card",
+			label: "Self-service booking",
+			description: "Customers can book without an operator.",
+			sectionId: "advanced",
+			defaultValue: false,
+		},
+		{
+			key: "cutoffHours",
+			type: "integer",
+			label: "Cut-off (hours before)",
+			sectionId: "advanced",
+			min: 0,
+			defaultValue: 48,
+			// Only meaningful once self-service is on — the whole reason the predicate form exists.
+			hidden: (values) => values.selfService !== true,
+		},
+		{
+			key: "metadata",
+			type: "json",
+			label: "Integration metadata",
+			sectionId: "advanced",
+			rows: 4,
+			defaultValue: { externalId: "MRL-1", region: "south" },
+			helperText: "Sent verbatim to the booking provider.",
+		},
+	],
+}
+
+export default function FormLayout() {
+	const [submitted, setSubmitted] = useState<string | null>(null)
+	const [failSave, setFailSave] = useState(false)
+
+	const submit = async (values: SchemaFormValues) => {
+		await new Promise((resolve) => setTimeout(resolve, 600))
+		if (failSave) throw new Error("Save failed")
+		setSubmitted(JSON.stringify(values))
+	}
+
+	return (
+		<>
+			<Checkbox label="Make the save fail" checked={failSave} onChange={(event) => setFailSave(event.target.checked)} />
+			<SchemaForm
+				schema={VENUE_SCHEMA}
+				onSubmit={(values) => submit(values)}
+				onReset={() => setSubmitted(null)}
+			/>
+			{!!submitted && (
+				<Text size="xs" type="secondary" numeric>submitted: {submitted}</Text>
+			)}
+		</>
+	)
+}
 ```
 
 ### One surface per section
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<SchemaForm schema={schema} layout="cards" onSubmit={save} />
+import { useState } from "react"
+
+import { Text } from "themelia-ui/base/typography"
+import { SchemaForm, type SchemaFormSchema, type SchemaFormValues } from "themelia-ui/features/schema-form"
+
+const SETTINGS_SCHEMA: SchemaFormSchema = {
+	sections: [
+		{ id: "notify", title: "Notifications", columns: 1 },
+		{ id: "billing", title: "Billing", columns: 2 },
+	],
+	fields: [
+		{
+			key: "digest",
+			type: "switch",
+			label: "Daily digest",
+			description: "One email at 08:00 with yesterday's bookings.",
+			sectionId: "notify",
+			defaultValue: true,
+		},
+		{
+			key: "channel",
+			type: "select",
+			label: "Escalation channel",
+			sectionId: "notify",
+			allowClear: true,
+			placeholder: "None",
+			options: [
+				{ value: "email", label: "Email" },
+				{ value: "sms", label: "SMS" },
+				{ value: "webhook", label: "Webhook" },
+			],
+		},
+		{
+			key: "vat",
+			label: "VAT number",
+			sectionId: "billing",
+			placeholder: "GB123456789",
+		},
+		{
+			key: "terms",
+			type: "integer",
+			label: "Payment terms (days)",
+			sectionId: "billing",
+			defaultValue: 30,
+			min: 0,
+		},
+	],
+}
+
+export default function CardsLayout() {
+	const [submitted, setSubmitted] = useState<string | null>(null)
+
+	const submit = async (values: SchemaFormValues) => {
+		await new Promise((resolve) => setTimeout(resolve, 600))
+		setSubmitted(JSON.stringify(values))
+	}
+
+	return (
+		<>
+			<SchemaForm
+				schema={SETTINGS_SCHEMA}
+				layout="cards"
+				submitLabel="Save settings"
+				onSubmit={(values) => submit(values)}
+			/>
+			{!!submitted && (
+				<Text size="xs" type="secondary" numeric>submitted: {submitted}</Text>
+			)}
+		</>
+	)
+}
 ```