@motifx-community/ui 0.1.0-beta.1 → 0.1.0-beta.3

package/docs/toolbar.md

@@ -1,6 +1,6 @@
 # Toolbar
 
-> Buttons · @motifx-community/ui 0.1.0-beta.1
+> Buttons · @motifx-community/ui 0.1.0-beta.3
 
 A bar of commands: buttons, toggle buttons, menus and fields in groups between separators. It is one Tab stop and the arrow keys move inside it; items that do not fit move into a “more” menu at the end. Items come as data, as JSX children, or both.
 
@@ -10,9 +10,9 @@ A bar of commands: buttons, toggle buttons, menus and fields in groups between s
 import { Toolbar, ToolbarSeparator, type ToolbarItem } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-`items` describes the commands as data, each field a value or a function; JSX children (any control) come after them. From code, a toolbar is filled like any control: `toolbar.controls.add(button)`. Every prop is also a property.
+`items` describes the commands as data, each field a value or a function; JSX children (any control) come after them. Programmatically, a toolbar is filled like any control: `toolbar.controls.add(button)`. Every prop is also a property.
 
 ```tsx
 /** A small outline icon drawn from one path. */
@@ -41,21 +41,21 @@ import { reactive, type Component } from '@motifx/core';
 import { Button, Toolbar } from '@motifx-community/ui';
 
 /** A toolbar made with `new` and filled with `controls.add`. */
-export default function FromCode() {
+export default function Programmatic() {
   const s = reactive({ log: '' });
   let added = 0;
 
   const bar = new Toolbar({ label: 'Actions', size: 'sm' });
   bar.controls.add(new Button({ text: 'First', onclick: () => (s.log = 'First pressed') }));
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const n = ++added;
     bar.controls.add(new Button({ text: `Button ${n}`, onclick: () => (s.log = `Button ${n} pressed`) }));
   };
 
   return (
     <>
-      <Button text="Add a button from code" variant="outline" onclick={addFromCode} />
+      <Button text="Add a button programmatically" variant="outline" onclick={addProgrammatic} />
       <div style="inline-size: 100%" ref={(c: Component<HTMLDivElement>) => c.controls.add(bar)} />
       <output>{() => s.log}</output>
     </>
@@ -167,7 +167,7 @@ The only text a toolbar writes itself is the name of its “more” button, from
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, uiLocale } from '@motifx-community/ui';
 import { kitTexts } from '../../../shared/kit-texts';
 
 /** Switches the texts of the kit; the “more” buttons take the new name at once. */
@@ -175,7 +175,7 @@ export default function Localization() {
   const s = reactive({ lang: 'en' });
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
   return (
     <>

package/docs/tooltip.md

@@ -1,8 +1,8 @@
 # Tooltip
 
-> Feedback · @motifx-community/ui 0.1.0-beta.1
+> Feedback · @motifx-community/ui 0.1.0-beta.3
 
-A short description shown next to an element: after the pointer rests on it, when it gets keyboard focus, or from code. It can be hovered, Escape hides it, and one is open at a time on the page.
+A short description shown next to an element: after the pointer rests on it, when it gets keyboard focus, or programmatically. It can be hovered, Escape hides it, and one is open at a time on the page.
 
 ## Import
 
@@ -10,27 +10,27 @@ A short description shown next to an element: after the pointer rests on it, whe
 import { Tooltip, addTooltip, type TooltipShowOn } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-In JSX a tooltip is placed anywhere and pointed at its `target`; where it sits does not matter. From code, `new Tooltip({ target, text })` needs nothing else: it puts itself into the page when it first shows, and goes when its target component does.
+In JSX a tooltip is placed anywhere and pointed at its `target`; where it sits does not matter. Programmatically, `new Tooltip({ target, text })` needs nothing else: it puts itself into the page when it first shows, and goes when its target component does.
 
 ```tsx
 import { Button, Tooltip } from '@motifx-community/ui';
 
-/** A tooltip from JSX pointed at its target, and one created with `new` and opened from code. */
-export default function FromCode() {
+/** A tooltip from JSX pointed at its target, and one created with `new` and opened programmatically. */
+export default function Programmatic() {
   let save: Button | null = null;
   let target: Button | null = null;
   let tip: Tooltip | null = null;
   let opened = 0;
 
-  const openFromCode = () => {
+  const openProgrammatic = () => {
     if (!target) return;
     if (!tip) {
       tip = new Tooltip({ target });
       tip.placement = 'end';
     }
-    tip.text = `Made from code, opened ${++opened} time(s)`;
+    tip.text = `Made programmatically, opened ${++opened} time(s)`;
     tip.open();
   };
 
@@ -39,7 +39,7 @@ export default function FromCode() {
       <Button ref={(b: Button) => (save = b)} text="Save" tone="accent" />
       <Tooltip target={() => save} text="Save the file (Ctrl+S)" />
       <Button ref={(b: Button) => (target = b)} text="Target" variant="outline" />
-      <Button text="Open a tooltip from code" variant="outline" onclick={openFromCode} />
+      <Button text="Open a tooltip programmatically" variant="outline" onclick={openProgrammatic} />
     </>
   );
 }
@@ -200,7 +200,7 @@ export default function RichContent() {
 import { reactive } from '@motifx/core';
 import { Button, Tooltip } from '@motifx-community/ui';
 
-/** A tooltip opened only from code, and one shown on keyboard focus while a toggle allows it. */
+/** A tooltip opened only programmatically, and one shown on keyboard focus while a toggle allows it. */
 export default function ShowOn() {
   const s = reactive({ on: true });
   let help: Button | null = null;
@@ -209,7 +209,7 @@ export default function ShowOn() {
   return (
     <>
       <Button ref={(b: Button) => (help = b)} text="Help" variant="outline" />
-      <Tooltip ref={(t: Tooltip) => (tip = t)} target={() => help} text="Shown from code" showOn="manual" placement="bottom" />
+      <Tooltip ref={(t: Tooltip) => (tip = t)} target={() => help} text="Shown programmatically" showOn="manual" placement="bottom" />
       <Button text={() => (tip?.opened ? 'Hide it' : 'Show it')} onclick={() => tip && (tip.opened = !tip.opened)} />
       <Button text={() => (s.on ? 'Tooltips on' : 'Tooltips off')} toggle x-model={() => s.on} variant="ghost" />
       <Button ref={(b: Button) => (keyboardOnly = b)} text="Keyboard only" variant="outline" />
@@ -233,7 +233,7 @@ const SEATS = ['1', '2', '3', '4', '5', '6'].flatMap((row) =>
   })),
 );
 
-/** A tooltip on each of 24 seats, made only when first needed, and one that is removed from code. */
+/** A tooltip on each of 24 seats, made only when first needed, and one that is removed programmatically. */
 export default function ManyElements() {
   let removeGuideTip = () => {};
   return (

package/docs/treeview.md

@@ -1,6 +1,6 @@
 # TreeView
 
-> Data · @motifx-community/ui 0.1.0-beta.1
+> Data · @motifx-community/ui 0.1.0-beta.3
 
 A tree view shows items in a hierarchy. Rows open and close, are selected one or many at a time, can carry check boxes that add up to their parents, can be searched, and can load their children when they are first opened. Long trees draw only the rows in view.
 
@@ -10,9 +10,9 @@ A tree view shows items in a hierarchy. Rows open and close, are selected one or
 import { TreeView } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-Items are objects with a `children` array (or a `parentId`, see below). `value` is the selected row's key and `x-model` binds it two-way. Created with `new`, the tree is filled and driven from code; items changed in place, plain or reactive, show after `refresh()` (`refreshItem(key)` for one row).
+Items are objects with a `children` array (or a `parentId`, see below). `value` is the selected row's key and `x-model` binds it two-way. Created with `new`, the tree is filled and driven programmatically; items changed in place, plain or reactive, show after `refresh()` (`refreshItem(key)` for one row).
 
 ```tsx
 /** A row of the trees on this page. */
@@ -84,7 +84,7 @@ export interface Entry {
 
 ## Search and filter
 
-`searchEnabled` adds a search box; matches show with their parents, opened, and clearing the search brings the rows back as they were. `searchValue` (or `filter(text)`) filters from code; `searchMode` is `contains` or `startswith`.
+`searchEnabled` adds a search box; matches show with their parents, opened, and clearing the search brings the rows back as they were. `searchValue` (or `filter(text)`) filters programmatically; `searchMode` is `contains` or `startswith`.
 
 ```tsx
 /** A row of the trees on this page. */
@@ -185,7 +185,7 @@ The tree writes four texts, all from `uiLocale.strings`: `noItems` (nothing to s
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, uiLocale } from '@motifx-community/ui';
 import { kitTexts } from '../../../shared/kit-texts';
 
 /** Switches the texts of the kit; the trees on the page follow at once. */
@@ -193,7 +193,7 @@ export default function Localization() {
   const s = reactive({ lang: 'en' });
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
   return (
     <>
@@ -269,8 +269,8 @@ export default function Localization() {
 | --- | --- | --- |
 | `expand(key), collapse(key)` | `boolean` | Opens / closes a row; children load first if they have to. The cancelable events run. |
 | `expandAll(), collapseAll()` | `void` | Every row whose children are known. No event per row. |
-| `select(key), unselect(key), selectAll(), clearSelection()` | `void` | From code; `select` adds to the selection with `multiple`. |
-| `check(key, checked?), uncheck(key), checkAll(), uncheckAll()` | `void` | From code. |
+| `select(key), unselect(key), selectAll(), clearSelection()` | `void` | Programmatically; `select` adds to the selection with `multiple`. |
+| `check(key, checked?), uncheck(key), checkAll(), uncheckAll()` | `void` | Programmatically. |
 | `filter(text)` | `void` | Sets `searchValue`. |
 | `scrollTo(key), focusNode(key)` | `boolean` | Opens the row's parents and scrolls it into view (and focuses it). |
 | `reload(key?)` | `void` | Loads a row's children again (all loaded children without a key). |
@@ -291,7 +291,7 @@ export default function Localization() {
 
 ## Example files
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -302,7 +302,7 @@ import { project } from './project';
 const BOX = 'inline-size: 100%; max-inline-size: 26rem; background: var(--mx-color-bg-card)';
 
 /** A tree bound with x-model, and a tree made with `new` whose items change in place and are read again on `refresh()`. */
-export default function FromCode() {
+export default function Programmatic() {
   const s = reactive({ file: 'tree' as unknown, clicked: '' });
   const menu = reactive<Entry[]>([
     { id: 'home', text: 'Home' },
@@ -327,7 +327,7 @@ export default function FromCode() {
       </Panel>
       <output class="tv-value">{() => `value: ${JSON.stringify(s.file)}`}</output>
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a product from code" variant="outline" onclick={addProduct} />
+        <Button text="Add a product programmatically" variant="outline" onclick={addProduct} />
         <Button text="Expand all" variant="ghost" onclick={() => tree.expandAll()} />
         <Button text="Collapse all" variant="ghost" onclick={() => tree.collapseAll()} />
         <output class="tv-clicked">{() => s.clicked}</output>

package/docs/validationsummary.md

@@ -0,0 +1,115 @@
+# ValidationSummary
+
+> Editors · @motifx-community/ui 0.1.0-beta.3
+
+The failed fields of a `ValidationGroup`, one line each with the field’s label and its message, under a header; a press on a line goes to the field. It draws itself again whenever a field of the group is checked or reset, and stays out of sight while nothing has failed.
+
+## Import
+
+```tsx
+import { ValidationSummary, ValidationGroup } from '@motifx-community/ui';
+```
+
+## Above a form
+
+Give it the `group` the fields join with `validationGroup`. After `group.validate()` the failed fields are listed; a field that passes again leaves the list, and `group.reset()` empties it. A press on a line focuses the field (`focusOnClick`).
+
+```tsx
+import { Button, NumberBox, Stack, TextBox, ValidationGroup, ValidationSummary } from '@motifx-community/ui';
+
+/** The failed fields of a form listed above it after Save; a press on a line goes to the field. */
+export default function Form() {
+    const group = new ValidationGroup();
+    return (
+        <Stack gap="md" style="inline-size: 100%; max-inline-size: 420px">
+            <ValidationSummary class="vs-form" group={group} />
+            <TextBox label="Name" required validationGroup={group} />
+            <TextBox label="E-mail" required rules={[{ type: 'email' }]} validationGroup={group} />
+            <NumberBox label="Guests" required rules={[{ type: 'range', min: 1, max: 8 }]} validationGroup={group} />
+            <Stack orientation="horizontal" gap="sm">
+                <Button class="vs-save" text="Save" tone="accent" onclick={() => void group.validate({ focus: false })} />
+                <Button class="vs-reset" text="Start again" variant="outline" onclick={() => group.reset()} />
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Programmatic use
+
+`header` gives the line above the list, `showHeader` hides it; `onItemClick` tells which line was pressed, `failed` and `count` say what is listed.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, TextBox, ValidationGroup, ValidationSummary } from '@motifx-community/ui';
+
+/** A header of its own, or none; the lines tell which field was pressed, and `failed` says how many there are. */
+export default function Programmatic() {
+    const group = new ValidationGroup();
+    const s = reactive({ header: true, told: '', count: 0 });
+    const summary = new ValidationSummary({
+        group,
+        header: 'Before you send it',
+        showHeader: () => s.header,
+        onItemClick: e => (s.told = `pressed: ${e.text}`)
+    });
+    return (
+        <Stack gap="md" style="inline-size: 100%; max-inline-size: 420px">
+            <span class="vs-coded" onConfig={c => c.controls.add(summary)} />
+            <TextBox label="Street" required validationGroup={group} />
+            <TextBox label="Town" required validationGroup={group} />
+            <Stack orientation="horizontal" wrap align="center">
+                <Button class="vs-coded-check" text="Check" tone="accent" onclick={async () => {
+                    await group.validate({ focus: false });
+                    s.count = summary.count;
+                }} />
+                <Button text="Header on and off" variant="outline" onclick={() => (s.header = !s.header)} />
+                <output class="vs-coded-told">{() => `${s.count} failed${s.told ? `, ${s.told}` : ''}`}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `The summary` | A live region (`polite`): the lines are read out when they appear; out of sight while nothing has failed. |
+| `A line` | A button with the field’s label and its message (“E-mail: Enter a valid e-mail address”); a press focuses the field. |
+| `Glyph` | The mark before the header is decorative. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-validation-summary` | The summary. `data-empty` while nothing has failed. |
+| `.mx-validation-summary__header, .mx-validation-summary__icon, .mx-validation-summary__header-text` | The header, its glyph, its text. |
+| `.mx-validation-summary__list, .mx-validation-summary__line, .mx-validation-summary__item` | The list, a line, the button in it. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `validation-summary.box, .icon, .header, .item` | Units: the box, the glyph before the header (`icon`), the header’s text, a line (`hover`, `focus`). |
+| `validation-summary.gap, .line-gap` | Between the header and the list; between the lines. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `group` | `Bind<ValidationGroup \| null>` | `null` | The group whose failed fields are listed. |
+| `header` | `Bind<string>` | the kit’s “Please correct the following” | The line above the list. |
+| `showHeader` | `Bind<boolean>` | `true` | The header is shown. |
+| `focusOnClick` | `Bind<boolean>` | `true` | A press on a line focuses its field. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onItemClick` | event | A line was pressed (`target`, `text`). |
+| `failed` | read-only | The failed targets listed now, in the group’s order. |
+| `count` | read-only | How many lines there are. |
+| `refresh()` | `void` | Draws the lines again from the fields as they are now. |

package/docs/window.md

@@ -1,6 +1,6 @@
 # Window and dialog
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
 A window or a dialog on a native `<dialog>`: one form, shown modeless or modal by whoever shows it. It has a title bar, moves, resizes, minimizes and maximizes; Enter and Escape press its buttons; forms open forms. `messageBox` and `confirm` cover the common questions.
 
@@ -10,9 +10,9 @@ A window or a dialog on a native `<dialog>`: one form, shown modeless or modal b
 import { MxForm, messageBox, confirm, type FormResult } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-In JSX, `x-model` shows the form while the value is true and writes `false` when the user closes it; it is hidden, not disposed, and lives with its parent. From code, a form (often a class with a `view()`) is shown with `show(host)` or `showDialog(host)`; it is added to the host and disposed when it closes.
+In JSX, `x-model` shows the form while the value is true and writes `false` when the user closes it; it is hidden, not disposed, and lives with its parent. Programmatically, a form (often a class with a `view()`) is shown with `show(host)` or `showDialog(host)`; it is added to the host and disposed when it closes.
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -206,7 +206,7 @@ export class RenameForm extends MxForm {
 
 ## Events
 
-`onClosing` can keep the form open, here while it has changes; `reason` tells the user (close button, Escape) from code and from the owner going away.
+`onClosing` can keep the form open, here while it has changes; `reason` tells the user (close button, Escape) programmatically and from the owner going away.
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -327,7 +327,7 @@ The title bar buttons and the `ok`, `cancel`, `yes`, `no` buttons of a message b
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, enStrings, messageBox, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, messageBox, uiLocale } from '@motifx-community/ui';
 
 /** Switches the names of the title bar buttons and of the message box buttons. */
 export default function Localization() {
@@ -335,7 +335,7 @@ export default function Localization() {
 
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
 
   const ask = () =>
@@ -451,7 +451,7 @@ import { reactive, type Component } from '@motifx/core';
 import { Button, MxForm, Stack, TextBox, type FormResult } from '@motifx-community/ui';
 import { RenameForm } from './RenameForm';
 
-/** A modeless form in JSX shown through x-model, and a form class shown modal from code. */
+/** A modeless form in JSX shown through x-model, and a form class shown modal programmatically. */
 export default function JsxAndCode() {
   const s = reactive({ find: false, query: '', found: '', renamed: '' });
   let host: Component<HTMLDivElement> | null = null;

package/docs/wizard.md

@@ -0,0 +1,240 @@
+# Wizard
+
+> Navigation · @motifx-community/ui 0.1.0-beta.3
+
+A task in steps: a [Stepper](stepper.md) above or beside one page per step, and the Back and Next buttons under them. Next validates the page first; on the last step it finishes.
+
+## Import
+
+```tsx
+import { Wizard, WizardStep } from '@motifx-community/ui';
+```
+
+## Pages from JSX
+
+Each `WizardStep` is a step and its page. Next validates the kit’s fields on the page, then the step’s own `validate`; a page that fails keeps the wizard, marks its step and focuses the first invalid field. On the last step Next reads Finish and raises `onFinished`.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { CheckBox, Stack, TextBox, Wizard, WizardStep } from '@motifx-community/ui';
+
+/** Three pages with the kit's fields: Next validates the page first; Finish tells the app. */
+export default function Basic() {
+    const s = reactive({ name: '', email: '', city: '', agreed: false, result: '' });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Wizard label="Sign up" onFinished={() => (s.result = `Welcome, ${s.name}.`)}>
+                <WizardStep title="Account" description="Who you are">
+                    <Stack orientation="horizontal" wrap align="center">
+                        <TextBox label="Name" x-model={() => s.name} required />
+                        <TextBox label="E-mail" x-model={() => s.email} required rules={[{ type: 'email' }]} />
+                    </Stack>
+                </WizardStep>
+                <WizardStep title="Address" description="Where you live">
+                    <TextBox label="City" x-model={() => s.city} required />
+                </WizardStep>
+                <WizardStep title="Review" validate={() => s.agreed}>
+                    <p>{() => `${s.name || '—'}, ${s.email || '—'}, ${s.city || '—'}`}</p>
+                    <CheckBox label="Everything is right" x-model={() => s.agreed} />
+                </WizardStep>
+            </Wizard>
+            <output class="wz-result">{() => s.result}</output>
+        </Stack>
+    );
+}
+```
+
+## Programmatic use
+
+`steps` makes the steps from props, each page from a `content` factory when it is first shown; `add`, `insert` and `remove` change them later. `next()`, `previous()`, `goTo()` and `finish()` move it.
+
+```tsx
+import { Component, reactive } from '@motifx/core';
+import { Button, Stack, Wizard, WizardStep } from '@motifx-community/ui';
+
+// A page made programmatically: any MotifJS component.
+class Note extends Component<HTMLDivElement, { text: string }> {
+    override view() {
+        return <p>{this.props.text}</p>;
+    }
+}
+
+/** A wizard made programmatically: its steps as props with content factories, moved with its methods, a step added later. */
+export default function Programmatic() {
+    const s = reactive({ told: '' });
+    const wizard = new Wizard({
+        label: 'Setup',
+        steps: [
+            { title: 'Welcome', content: () => new Note({ text: 'A page made by a factory, built when first shown.' }) },
+            { title: 'Options', description: 'Pick what you need', content: () => new Note({ text: 'The second page.' }) },
+            { title: 'Done', content: () => new Note({ text: 'The last page; Next reads Finish here.' }) }
+        ],
+        onStepChanged: e => (s.told = `Step ${e.index + 1}: ${(e.item as { text: string }).text}`),
+        onFinished: () => (s.told = 'Finished.')
+    });
+    const addStep = () => {
+        wizard.insert(2, new WizardStep({ title: 'Extra', optional: true, content: () => new Note({ text: 'Added programmatically.' }) }));
+    };
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <span onConfig={c => c.controls.add(wizard)} />
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Go to Done" variant="outline" onclick={() => void wizard.goTo(wizard.steps.length - 1)} />
+                <Button text="Add a step" variant="outline" onclick={addStep} />
+                <output class="wz-told">{() => s.told}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Standing
+
+```tsx
+import { reactive } from '@motifx/core';
+import { RadioGroup, Switch, TextArea, Wizard, WizardStep } from '@motifx-community/ui';
+
+/** The stepper beside the pages, the texts after the indicators. */
+export default function Vertical() {
+    const s = reactive({ plan: 'Team', notify: true, note: '' });
+    return (
+        <Wizard label="Subscription" orientation="vertical" style="min-block-size: 16rem; inline-size: 100%">
+            <WizardStep title="Plan" description="What you pay for">
+                <RadioGroup label="Plan" items={['Solo', 'Team', 'Business']} x-model={() => s.plan} />
+            </WizardStep>
+            <WizardStep title="Alerts" description="How we reach you">
+                <Switch label="Send me a monthly summary" x-model={() => s.notify} />
+            </WizardStep>
+            <WizardStep title="Notes" optional>
+                <TextArea label="Anything else?" x-model={() => s.note} rows={3} />
+            </WizardStep>
+        </Wizard>
+    );
+}
+```
+
+## Your own buttons, finishing that waits
+
+`showNavigation={false}` takes the bar away; your own buttons call the methods. `onFinishing` may set a `promise`: the wizard finishes when it resolves to `true`, and stays otherwise.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, TextBox, Wizard, WizardStep } from '@motifx-community/ui';
+
+/** No bar: buttons of your own drive it; finishing waits for a promise (a server) and may be refused. */
+export default function Custom() {
+    const s = reactive({ code: '', busy: false, note: '' });
+    let wizard!: Wizard;
+    const finish = () => {
+        s.note = '';
+        void wizard.finish().then(ok => (s.note = ok ? 'Saved.' : s.note || 'Not finished.'));
+    };
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Wizard
+                ref={(w: Wizard) => (wizard = w)}
+                label="Redeem"
+                showNavigation={false}
+                labelPosition="end"
+                onFinishing={e => {
+                    s.busy = true;
+                    e.promise = new Promise<boolean>(resolve => setTimeout(() => resolve(s.code.toUpperCase() === 'MOTIF'), 600)).then(ok => {
+                        s.busy = false;
+                        if (!ok) s.note = 'That code is not known.';
+                        return ok;
+                    });
+                }}
+            >
+                <WizardStep title="Code">
+                    <TextBox label="Gift code" x-model={() => s.code} required placeholder="MOTIF" />
+                </WizardStep>
+                <WizardStep title="Confirm">
+                    <p>{() => `Redeem “${s.code}”?`}</p>
+                </WizardStep>
+            </Wizard>
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Back" variant="outline" onclick={() => void wizard.previous()} />
+                <Button text="Next" variant="outline" onclick={() => void wizard.next()} />
+                <Button text="Redeem" busy={() => s.busy} onclick={finish} />
+                <output class="wz-note">{() => s.note}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Stepper` | A `nav` of steps as on the [Stepper](stepper.md) page: each a button with its position and status in its name, one Tab stop. |
+| `Page` | A `group` named after its step; the hidden pages are out of the tree. |
+| `Validation` | A page that fails keeps focus on its first invalid field, with its message; the step reads “Needs attention”. |
+| `Buttons` | The kit’s buttons, named in the kit language: “Back”, “Next”, “Finish”. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-wizard` | The wizard. `data-orientation`. |
+| `.mx-wizard__stepper` | The stepper (`.mx-stepper` too). |
+| `.mx-wizard__pages, .mx-wizard__page` | The pages and each page; a hidden page carries `hidden`. |
+| `.mx-wizard__bar, .mx-wizard__previous, .mx-wizard__next` | The bar and its buttons. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `wizard.frame, .page, .bar` | Units: the whole, a page, the bar (a rule over it, its padding). |
+| `wizard.previous, wizard.next` | Places: the buttons’ look in the bar (`variant`). |
+| `wizard.gap, .bar-gap, .rail-width` | Between the stepper, the pages and the bar; between the buttons; the stepper’s width when it stands beside the pages. |
+
+## API reference
+
+### Wizard props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` | `readonly WizardStepProps[]` | `[]` | Steps made programmatically, each as the props of a `WizardStep`; the JSX `WizardStep` children come first. |
+| `value` | `Bind<string \| number \| null>` | `0` | The current step: its `key`, else its index. `x-model` binds it two-way. |
+| `linear` | `Bind<boolean>` | `true` | A step is reached only after the ones before it; optional steps may be skipped. |
+| `orientation` | `Bind<StepperOrientation>` | `'horizontal'` | `horizontal`: the stepper above the pages; `vertical`: beside them. |
+| `labelPosition` | `Bind<StepperLabelPosition>` | `'bottom'` | Where the stepper’s texts sit, horizontal only. |
+| `size` | `Bind<ControlSize>` | `'md'` | The stepper’s size. |
+| `showStepper, showNavigation` | `Bind<boolean>` | `true` | The stepper, and the bar with the Back and Next buttons. |
+| `clickable` | `Bind<boolean>` | `true` | The steps of the stepper can be pressed. |
+| `lazy` | `Bind<boolean>` | `true` | A page is built when first shown, then kept (a step’s own `lazy` wins). |
+| `keepAlive` | `Bind<boolean>` | `true` | `false`: what a step’s `content` made is disposed while hidden and made again when it shows (a step’s own `keepAlive` wins). |
+| `previousText, nextText, finishText` | `Bind<string>` | the kit’s “Back”, “Next”, “Finish” | The buttons’ texts. |
+| `label` | `Bind<string>` | the kit’s “Steps” | What screen readers call the stepper. |
+
+### WizardStep props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `Bind<string>` | `''` | The step’s text in the stepper. The same property as `text`. |
+| `description` | `Bind<string>` | `''` | A second line under the title. |
+| `key` | `Bind<string>` | the index | Names the step in `value`; the JSX `key` works too. |
+| `icon` | `Bind<IconSource \| null>` | `null` | Drawn in the indicator in place of the number. |
+| `optional` | `Bind<boolean>` | `false` | May be skipped; says so under the title. |
+| `enabled` | `Bind<boolean>` | `true` | `false` keeps the step from being reached. |
+| `error` | `Bind<boolean>` | `false` | Draws the step with an error; the wizard sets it when the page does not validate, and clears it when it does. |
+| `validateFields` | `Bind<boolean>` | `true` | The kit’s fields on the page are validated before the wizard moves on from it; the first invalid one takes focus. |
+| `validate` | `() => boolean \| Promise<boolean>` | — | Asked after the fields; `false` keeps the page and marks the step. |
+| `lazy, keepAlive` | `Bind<boolean \| undefined>` | the wizard’s | See the wizard’s. |
+| `content` | `() => ComponentBase \| ComponentBase[]` | — | Makes the page programmatically, when the page is built. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onStepChanging, onStepChanged` | event | The stepper’s events: `onStepChanging` (`cancel`, `promise`) runs before the page is validated. |
+| `onFinishing` | event | The last page validated and the wizard is about to finish; `cancel = true` keeps it open, `promise` waits and finishes on `true`. |
+| `onFinished` | event | The wizard finished: every step is drawn done. |
+| `next(), previous(), goTo(step)` | `Promise<boolean>` | Next validates the page first and finishes on the last step; Back validates nothing; `goTo` validates when it goes forward. |
+| `finish()` | `Promise<boolean>` | Validates the page, asks `onFinishing`, then finishes. |
+| `leaveCheck()` | `Promise<boolean>` | Validates the current page the way Next does, without moving. |
+| `add(step), insert(index, step), remove(step)` | `WizardStep` / `boolean` | Steps programmatically; a step of another wizard moves here. |
+| `stepper, steps, currentStep, selectedIndex` | read-only | The `Stepper`, the `WizardStep`s in order, the current one and its index. |
+| `isLast, isFinished` | read-only | The current step is the last that can be gone to (Next finishes); the wizard finished. |
+| `previousButton, nextButton` | read-only | The kit’s buttons in the bar, for an icon or a look of your own. |