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

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.2
+> 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';
@@ -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

@@ -1,6 +1,6 @@
 # Wizard
 
-> Navigation · @motifx-community/ui 0.1.0-beta.2
+> 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.
 
@@ -44,7 +44,7 @@ export default function Basic() {
 }
 ```
 
-## From code
+## 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.
 
@@ -52,15 +52,15 @@ export default function Basic() {
 import { Component, reactive } from '@motifx/core';
 import { Button, Stack, Wizard, WizardStep } from '@motifx-community/ui';
 
-// A page made from code: any MotifJS component.
+// 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 from code: its steps as props with content factories, moved with its methods, a step added later. */
-export default function FromCode() {
+/** 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',
@@ -73,7 +73,7 @@ export default function FromCode() {
         onFinished: () => (s.told = 'Finished.')
     });
     const addStep = () => {
-        wizard.insert(2, new WizardStep({ title: 'Extra', optional: true, content: () => new Note({ text: 'Added from code.' }) }));
+        wizard.insert(2, new WizardStep({ title: 'Extra', optional: true, content: () => new Note({ text: 'Added programmatically.' }) }));
     };
     return (
         <Stack gap="md" style="inline-size: 100%">
@@ -195,7 +195,7 @@ export default function Custom() {
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `steps` | `readonly WizardStepProps[]` | `[]` | Steps made from code, each as the props of a `WizardStep`; the JSX `WizardStep` children come first. |
+| `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. |
@@ -222,7 +222,7 @@ export default function Custom() {
 | `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 from code, when the page is built. |
+| `content` | `() => ComponentBase \| ComponentBase[]` | — | Makes the page programmatically, when the page is built. |
 
 ### Events, properties and methods
 
@@ -234,7 +234,7 @@ export default function Custom() {
 | `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 from code; a step of another wizard moves here. |
+| `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. |