@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/form.json

@@ -0,0 +1,383 @@
+{
+  "family": "form",
+  "ui": "form",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Form with validation, error summary and submit."
+  },
+  "axes": {
+    "validate": [
+      "submit",
+      "blur",
+      "change",
+      "none"
+    ],
+    "errorFocus": [
+      "summary",
+      "control",
+      "none"
+    ],
+    "summary": [
+      "auto",
+      "none"
+    ],
+    "align": [
+      "end",
+      "start",
+      "between",
+      "stretch"
+    ]
+  },
+  "members": {
+    "form": {
+      "nativeElement": "form",
+      "defaults": {
+        "validate": "submit",
+        "errorFocus": "summary",
+        "summary": "auto",
+        "align": "end",
+        "nativeValidation": false,
+        "guardUnsaved": false,
+        "loading": false
+      },
+      "capabilities": [
+        "validity",
+        "appearance",
+        "loading",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "invalid",
+        "loading",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "summary",
+        "summary-title",
+        "summary-list",
+        "summary-item",
+        "actions"
+      ]
+    }
+  },
+  "docs": {
+    "form": {
+      "imports": {
+        "source": "import { Form, FormActions, FormDefaultsProvider, FormSummary, useFormState } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "form",
+          "required": true,
+          "purpose": "The element itself. Carries data-ui=\"form\", data-invalid, data-loading and data-disabled, writes novalidate, and is the query container the action row is measured against. It stays a form: a submit event has nowhere else to come from, FormData reads a form, and requestSubmit() and reset() are the element’s own."
+        },
+        {
+          "part": "summary",
+          "element": "div[role=alert][tabindex=-1]",
+          "required": false,
+          "purpose": "The region a reader is sent to after a failed submit. Rendered by the form under summary=\"auto\", or placed by the consumer as <FormSummary /> under summary=\"none\". It exists only while something is wrong. It carries data-ui=\"form\" beside its data-part, so the family’s rules reach it wherever it stands and never a nested family’s summary — a table’s totals row."
+        },
+        {
+          "part": "summary-title",
+          "element": "h2",
+          "required": false,
+          "purpose": "The heading the sourced pattern requires, the summaryTitle message of the language in force (“There is a problem”). It labels the region, so a reader who is moved there is told what they arrived at."
+        },
+        {
+          "part": "summary-list",
+          "element": "ul",
+          "required": false,
+          "purpose": "One item per message, in document order. It scrolls past twelve lines rather than truncating, because a hundred errors is a real answer from a real server and none of them may leave the DOM."
+        },
+        {
+          "part": "summary-item",
+          "element": "a[href], or span",
+          "required": false,
+          "purpose": "A link to the control the message is about, which moves focus there without following the fragment. An error naming a control the form does not hold is a span instead: a message a reader cannot reach is still a message they have to be given."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "The row a form’s actions stand in, aligned to the reading end. Below 360 container pixels it becomes a column of full-width actions with the primary one first — a reader’s thumb is at the bottom of a phone and their eye at the end of a row. It carries data-ui=\"form\" beside its data-part, so a nested family’s actions — a section’s — keep their own row."
+        }
+      ],
+      "api": [
+        {
+          "name": "errors",
+          "type": "Record<string, string | string[]>",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "Present means the consumer owns the error map, for the life of the component. Keyed by the name attribute of the control each error is about, which is the key the platform already uses and the key a server already sends"
+        },
+        {
+          "name": "defaultErrors",
+          "type": "Record<string, string | string[]>",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "The errors an uncontrolled form starts from, read once — a page rendered on the server with a failed submission already in it"
+        },
+        {
+          "name": "validate",
+          "type": "'submit' | 'blur' | 'change' | 'none'",
+          "defaultValue": "submit",
+          "appliesTo": "Form, FormDefaultsProvider",
+          "description": "When the form checks its controls. submit re-checks on change afterwards, because telling a reader an answer is wrong before they have finished writing it is noise and telling them nothing after they have fixed it is worse"
+        },
+        {
+          "name": "errorFocus",
+          "type": "'summary' | 'control' | 'none'",
+          "defaultValue": "summary",
+          "appliesTo": "Form, FormDefaultsProvider",
+          "description": "Where focus goes after a failed submit. summary is the sourced pattern’s answer; control is for a form of one field, where a summary is ceremony"
+        },
+        {
+          "name": "summary",
+          "type": "'auto' | 'none'",
+          "defaultValue": "auto",
+          "appliesTo": "Form, FormDefaultsProvider",
+          "description": "Whether the family renders the summary as its first child. none leaves it to the consumer, who places <FormSummary /> wherever the page needs it"
+        },
+        {
+          "name": "summaryTitle",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "The summary’s heading as content of the page’s own, replacing the summaryTitle message"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<FormMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "Words laid over the language in force: the summary’s heading (summaryTitle)"
+        },
+        {
+          "name": "summaryDescription",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Form, FormDefaultsProvider",
+          "description": "A sentence under the heading, for a form whose failure needs more than a list"
+        },
+        {
+          "name": "align",
+          "type": "'end' | 'start' | 'between' | 'stretch'",
+          "defaultValue": "end",
+          "appliesTo": "Form, FormActions, FormDefaultsProvider",
+          "description": "How the action row is arranged above the reflow. Every alignment becomes one column of full-width actions below 360 container pixels"
+        },
+        {
+          "name": "nativeValidation",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Form, FormDefaultsProvider",
+          "description": "Lets the browser draw its own validation bubble. Off by default, because the field around each control already draws the message — and constraint validation still runs either way"
+        },
+        {
+          "name": "guardUnsaved",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Form",
+          "description": "Registers a beforeunload while anything in the form has been edited. Off by default: a page that refuses to close after one character is a trap"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Form",
+          "description": "Marks the form busy for work the family did not start. It is merged with the family’s own submission, so either one writes data-loading and aria-busy"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "Writes data-disabled on the root. It does not disable the controls: a fieldset does that, and it does it natively"
+        }
+      ],
+      "composition": [
+        {
+          "name": "ref",
+          "type": "Ref<HTMLFormElement>",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "Reaches the element. requestSubmit(), reset(), checkValidity() and FormData are the element’s own, so nothing is invented for what the platform already ships"
+        },
+        {
+          "name": "handle",
+          "type": "Ref<FormHandle>",
+          "defaultValue": "—",
+          "appliesTo": "Form",
+          "description": "validate(), submit(), reset() and focusFirstError() — the four actions a consumer cannot express by passing a value"
+        },
+        {
+          "name": "FormSummary",
+          "type": "HTMLAttributes<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "inside a Form",
+          "description": "The summary, placed by the consumer under summary=\"none\". It renders nothing while nothing is wrong"
+        },
+        {
+          "name": "FormActions",
+          "type": "{ align } & HTMLAttributes<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "inside a Form",
+          "description": "The action row, with its own alignment when the form’s is not the one this row wants"
+        },
+        {
+          "name": "useFormState()",
+          "type": "() => FormContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Form",
+          "description": "The errors, their document order, whether a submit is in flight and whether the form has been submitted. It is what a submit button reads to disable itself"
+        },
+        {
+          "name": "FormDefaultsProvider",
+          "type": "{ validate, errorFocus, summary, summaryDescription, align, nativeValidation }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The six decisions an application takes once. The summary’s heading comes from the language in force (SlottedProvider)"
+        }
+      ],
+      "events": [
+        {
+          "name": "onErrorsChange",
+          "payload": "(errors: FormErrors, request: ChangeRequest<FormErrors>)",
+          "when": "Before the error map moves. The request carries the new map, the map it replaces, the reason — \"submit\" for validation running, \"keyboard\" for a field changing and dropping its own error, \"clear\" for a reset, \"programmatic\" for validate() — the originating event, and cancel(). A request for the map the family already holds is not emitted."
+        },
+        {
+          "name": "onSubmit",
+          "payload": "(values, request) => void | FormErrorInput | Promise<void | FormErrorInput>",
+          "when": "When the form submits and nothing is wrong with it. The values are read from FormData in document order. Returning an error map publishes those errors and moves focus; returning a promise holds the form in its busy state until it settles."
+        }
+      ],
+      "accessibility": [
+        "There is no APG pattern for a form. The sourced guidance is WCAG 2.2 SC 3.3.1 Error Identification, the GOV.UK error summary component, and the HTML form element itself; each decides something the family does, and the contract names all three.",
+        "The summary answers the four things GOV.UK states a summary must do: keyboard focus moves to it, it carries the heading “There is a problem”, it links to each of the answers that have validation errors, and its messages are worded the same as the ones beside the inputs. The last one is free here — one map feeds the summary and the field, so the two cannot drift.",
+        "The region is role=\"alert\" with tabindex=\"-1\" and is labelled by its own heading, so it announces when it appears and can be reached afterwards. A link inside it moves focus to the control rather than following the fragment: a page that never navigated should not gain a history entry or write a control’s identifier into the address bar.",
+        "novalidate is written by default. The browser would otherwise draw its own bubble beside a control whose error the field is already showing, and the two would say the same thing twice in two places. Constraint validation still runs: checkValidity() is called explicitly, and validationMessage is the platform’s own string, localized by the operating system in a way no library can better.",
+        "An error naming a control the form does not hold keeps its place in the list and loses its link. A server may answer about a field the page no longer renders, and a message a reader cannot reach is still a message they have to be given.",
+        "A submit while one is pending is refused, and aria-busy says so. The form does not dim or disable itself while it saves: what a reader is waiting on is the values, and a form that hid them would take away the only thing they can check."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-width-thick",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-md",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-heading",
+    "--slotted-font-family-sans",
+    "--slotted-font-weight-semibold",
+    "--slotted-form-color",
+    "--slotted-form-summary-background",
+    "--slotted-form-summary-border-color",
+    "--slotted-form-summary-color",
+    "--slotted-form-summary-radius",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-radius-md",
+    "--slotted-radius-xs",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-8",
+    "--slotted-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A form of two fields with the family’s whole lifecycle on it. Submit it empty: the platform’s own messages appear in the summary, focus moves there, and each link jumps to the field it names.",
+      "language": "tsx",
+      "source": "<Form onSubmit={(values) => save(values)}>\n  <Field>\n    <FieldLabel>Nome completo</FieldLabel>\n    <TextField name=\"nome\" required />\n  </Field>\n  <FormActions>\n    <Button type=\"submit\">Salvar</Button>\n  </FormActions>\n</Form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "validation",
+      "title": "When the form checks its controls",
+      "note": "submit is the default and re-checks on change afterwards; blur checks only the control that lost focus; change checks after the first submit; none leaves validation entirely to the consumer. novalidate is written either way, so the browser’s bubble never lands beside a message the field is already drawing.",
+      "language": "tsx",
+      "source": "<Form validate=\"submit\">…</Form>;\n<Form validate=\"blur\">…</Form>;\n\n// The browser still validates; only its bubble is off.\n<TextField name=\"email\" required type=\"email\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "errors",
+      "title": "Where the errors come from",
+      "note": "Three sources merge into one map, latest last: a server’s answer, the platform’s own constraint validation, and whatever the submit handler returned. A server error is dropped as soon as the field it names is edited, and every error is dropped at the next submit.",
+      "language": "tsx",
+      "source": "const [errors, setErrors] = useState({});\n\n<Form\n  errors={errors}\n  onErrorsChange={setErrors}\n  onSubmit={async (values) => (await save(values)).errors}\n>\n  …\n</Form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "summary",
+      "title": "The region a reader is sent to",
+      "note": "The four things the sourced error summary states a summary must do: focus moves to it, it carries a heading, it links to each answer in error, and its messages are the same strings the fields show. errorFocus=\"control\" skips it and goes to the first field instead.",
+      "language": "tsx",
+      "source": "<Form summaryTitle=\"Corrija estes campos\">…</Form>;\n\n// Somewhere else on the page, under a heading of your own.\n<Form summary=\"none\">\n  <PageHeader />\n  <FormSummary />…\n</Form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "submit",
+      "title": "Submission, and the second press that does nothing",
+      "note": "A handler that returns a promise puts the form in its busy state until it settles, and a second submit while one is pending is refused — the defect a double-clicked button produces in a bare form. Returning an error map from the handler re-enters the same path a failed validation takes.",
+      "language": "tsx",
+      "source": "<Form\n  onSubmit={async (values) => {\n    const answer = await fetch('/pedidos', {\n      body: new URLSearchParams(values as never),\n      method: 'POST',\n    });\n    if (!answer.ok) return await answer.json();\n  }}\n>\n  …\n</Form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "The row the actions stand in",
+      "note": "end is the default, between pushes a destructive action away from the one beside it, and stretch shares the row. Narrow the column below 360 pixels and every alignment becomes the same column of full-width actions, primary first.",
+      "language": "tsx",
+      "source": "<FormActions>\n  <Button tone=\"secondary\" type=\"button\" variant=\"ghost\">\n    Cancelar\n  </Button>\n  <Button type=\"submit\">Salvar alterações</Button>\n</FormActions>;\n\n<FormActions align=\"between\">…</FormActions>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the family carries",
+      "note": "data-invalid while anything is wrong, data-loading and aria-busy while a submit is in flight, data-disabled when the consumer says so. The form does not dim itself while it saves: a form that hid its own values would hide what the reader is waiting on.",
+      "language": "tsx",
+      "source": "// The family's own submission, and a mutation the consumer started.\n<Form loading={mutation.isPending}>…</Form>;\n\nconst form = useFormState();\n<Button disabled={form?.submitting} type=\"submit\">\n  Salvar\n</Button>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Eleven errors, and one for a field that is not there",
+      "note": "The list scrolls past twelve lines rather than truncating, and an error naming a control the form does not hold keeps its place without a link. Both are cases a real server produces and none of the surveyed implementations answers.",
+      "language": "tsx",
+      "source": "<Form errors={{ cupom: 'O cupom informado expirou', email: 'Endereço inválido' }}>\n  <Field>\n    <FieldLabel>E-mail</FieldLabel>\n    <TextField name=\"email\" />\n  </Field>\n</Form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, reaching past it, and guarding it",
+      "note": "The provider carries the six decisions an application takes once; the handle reaches the four actions a value cannot express; guardUnsaved registers a beforeunload while anything has been edited, which nothing surveyed ships.",
+      "language": "tsx",
+      "source": "<FormDefaultsProvider validate=\"blur\">\n  <Form guardUnsaved handle={handle}>\n    …\n  </Form>\n</FormDefaultsProvider>;\n\n<Button onClick={() => handle.current?.validate()}>Conferir</Button>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears, and where focus goes",
+      "note": "Tab into the form, submit it empty, and follow what happens: the region announces itself, takes focus, and each link moves focus to the control it names without changing the address bar. Every message in the summary is the same string the field shows.",
+      "language": "tsx",
+      "source": "<Form errors={{ email: 'O endereço precisa conter um arroba' }}>\n  <Field invalid>\n    <FieldLabel>E-mail</FieldLabel>\n    <TextField name=\"email\" />\n    <FieldError>O endereço precisa conter um arroba</FieldError>\n  </Field>\n</Form>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/form.md

@@ -0,0 +1,240 @@
+<!-- index: ./index.md -->
+# form
+
+`data-ui="form"` · Form with validation, error summary and submit.
+
+## Import
+
+```tsx
+import { Form, FormActions, FormDefaultsProvider, FormSummary, useFormState } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Form onSubmit={(values) => save(values)}>
+  <Field>
+    <FieldLabel>Nome completo</FieldLabel>
+    <TextField name="nome" required />
+  </Field>
+  <FormActions>
+    <Button type="submit">Salvar</Button>
+  </FormActions>
+</Form>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | form | yes |
+| `summary` | div[role=alert][tabindex=-1] | no |
+| `summary-title` | h2 | no |
+| `summary-list` | ul | no |
+| `summary-item` | a[href], or span | no |
+| `actions` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `errors` | `Record<string, string \| string[]>` | — | Form | Present means the consumer owns the error map, for the life of the component. Keyed by the name attribute of the control each error is about, which is the key the platform already uses and the key a server already sends |
+| `defaultErrors` | `Record<string, string \| string[]>` | — | Form | The errors an uncontrolled form starts from, read once — a page rendered on the server with a failed submission already in it |
+| `validate` | `'submit' \| 'blur' \| 'change' \| 'none'` | submit | Form, FormDefaultsProvider | When the form checks its controls. submit re-checks on change afterwards, because telling a reader an answer is wrong before they have finished writing it is noise and telling them nothing after they have fixed it is worse |
+| `errorFocus` | `'summary' \| 'control' \| 'none'` | summary | Form, FormDefaultsProvider | Where focus goes after a failed submit. summary is the sourced pattern’s answer; control is for a form of one field, where a summary is ceremony |
+| `summary` | `'auto' \| 'none'` | auto | Form, FormDefaultsProvider | Whether the family renders the summary as its first child. none leaves it to the consumer, who places <FormSummary /> wherever the page needs it |
+| `summaryTitle` | `ReactNode` | — | Form | The summary’s heading as content of the page’s own, replacing the summaryTitle message |
+| `messages` | `Partial<FormMessages>` | — | Form | Words laid over the language in force: the summary’s heading (summaryTitle) |
+| `summaryDescription` | `ReactNode` | — | Form, FormDefaultsProvider | A sentence under the heading, for a form whose failure needs more than a list |
+| `align` | `'end' \| 'start' \| 'between' \| 'stretch'` | end | Form, FormActions, FormDefaultsProvider | How the action row is arranged above the reflow. Every alignment becomes one column of full-width actions below 360 container pixels |
+| `nativeValidation` | `boolean` | false | Form, FormDefaultsProvider | Lets the browser draw its own validation bubble. Off by default, because the field around each control already draws the message — and constraint validation still runs either way |
+| `guardUnsaved` | `boolean` | false | Form | Registers a beforeunload while anything in the form has been edited. Off by default: a page that refuses to close after one character is a trap |
+| `loading` | `boolean` | false | Form | Marks the form busy for work the family did not start. It is merged with the family’s own submission, so either one writes data-loading and aria-busy |
+| `disabled` | `boolean` | — | Form | Writes data-disabled on the root. It does not disable the controls: a fieldset does that, and it does it natively |
+| `ref` | `Ref<HTMLFormElement>` | — | Form | Reaches the element. requestSubmit(), reset(), checkValidity() and FormData are the element’s own, so nothing is invented for what the platform already ships |
+| `handle` | `Ref<FormHandle>` | — | Form | validate(), submit(), reset() and focusFirstError() — the four actions a consumer cannot express by passing a value |
+| `FormSummary` | `HTMLAttributes<HTMLElement>` | — | inside a Form | The summary, placed by the consumer under summary="none". It renders nothing while nothing is wrong |
+| `FormActions` | `{ align } & HTMLAttributes<HTMLElement>` | — | inside a Form | The action row, with its own alignment when the form’s is not the one this row wants |
+| `useFormState()` | `() => FormContextValue \| undefined` | — | inside a Form | The errors, their document order, whether a submit is in flight and whether the form has been submitted. It is what a submit button reads to disable itself |
+| `FormDefaultsProvider` | `{ validate, errorFocus, summary, summaryDescription, align, nativeValidation }` | — | a subtree | The six decisions an application takes once. The summary’s heading comes from the language in force (SlottedProvider) |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onErrorsChange` | `(errors: FormErrors, request: ChangeRequest<FormErrors>)` | Before the error map moves. The request carries the new map, the map it replaces, the reason — "submit" for validation running, "keyboard" for a field changing and dropping its own error, "clear" for a reset, "programmatic" for validate() — the originating event, and cancel(). A request for the map the family already holds is not emitted. |
+| `onSubmit` | `(values, request) => void \| FormErrorInput \| Promise<void \| FormErrorInput>` | When the form submits and nothing is wrong with it. The values are read from FormData in document order. Returning an error map publishes those errors and moves focus; returning a promise holds the form in its busy state until it settles. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `validate` | `submit`, `blur`, `change`, `none` | `submit` |
+| `errorFocus` | `summary`, `control`, `none` | `summary` |
+| `summary` | `auto`, `none` | `auto` |
+| `align` | `end`, `start`, `between`, `stretch` | `end` |
+
+## Rules
+
+- There is no APG pattern for a form. The sourced guidance is WCAG 2.2 SC 3.3.1 Error Identification, the GOV.UK error summary component, and the HTML form element itself; each decides something the family does, and the contract names all three.
+- The summary answers the four things GOV.UK states a summary must do: keyboard focus moves to it, it carries the heading “There is a problem”, it links to each of the answers that have validation errors, and its messages are worded the same as the ones beside the inputs. The last one is free here — one map feeds the summary and the field, so the two cannot drift.
+- The region is role="alert" with tabindex="-1" and is labelled by its own heading, so it announces when it appears and can be reached afterwards. A link inside it moves focus to the control rather than following the fragment: a page that never navigated should not gain a history entry or write a control’s identifier into the address bar.
+- novalidate is written by default. The browser would otherwise draw its own bubble beside a control whose error the field is already showing, and the two would say the same thing twice in two places. Constraint validation still runs: checkValidity() is called explicitly, and validationMessage is the platform’s own string, localized by the operating system in a way no library can better.
+- An error naming a control the form does not hold keeps its place in the list and loses its link. A server may answer about a field the page no longer renders, and a message a reader cannot reach is still a message they have to be given.
+- A submit while one is pending is refused, and aria-busy says so. The form does not dim or disable itself while it saves: what a reader is waiting on is the values, and a form that hid them would take away the only thing they can check.
+
+## Tokens
+
+`--slotted-border-width-thick`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-form-color`, `--slotted-form-summary-background`, `--slotted-form-summary-border-color`, `--slotted-form-summary-color`, `--slotted-form-summary-radius`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-radius-md`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`
+
+## Examples
+
+### When the form checks its controls
+
+submit is the default and re-checks on change afterwards; blur checks only the control that lost focus; change checks after the first submit; none leaves validation entirely to the consumer. novalidate is written either way, so the browser’s bubble never lands beside a message the field is already drawing.
+
+Excerpt — not a complete module
+
+```tsx
+<Form validate="submit">…</Form>;
+<Form validate="blur">…</Form>;
+
+// The browser still validates; only its bubble is off.
+<TextField name="email" required type="email" />;
+```
+
+### Where the errors come from
+
+Three sources merge into one map, latest last: a server’s answer, the platform’s own constraint validation, and whatever the submit handler returned. A server error is dropped as soon as the field it names is edited, and every error is dropped at the next submit.
+
+Excerpt — not a complete module
+
+```tsx
+const [errors, setErrors] = useState({});
+
+<Form
+  errors={errors}
+  onErrorsChange={setErrors}
+  onSubmit={async (values) => (await save(values)).errors}
+>
+  …
+</Form>;
+```
+
+### The region a reader is sent to
+
+The four things the sourced error summary states a summary must do: focus moves to it, it carries a heading, it links to each answer in error, and its messages are the same strings the fields show. errorFocus="control" skips it and goes to the first field instead.
+
+Excerpt — not a complete module
+
+```tsx
+<Form summaryTitle="Corrija estes campos">…</Form>;
+
+// Somewhere else on the page, under a heading of your own.
+<Form summary="none">
+  <PageHeader />
+  <FormSummary />…
+</Form>;
+```
+
+### Submission, and the second press that does nothing
+
+A handler that returns a promise puts the form in its busy state until it settles, and a second submit while one is pending is refused — the defect a double-clicked button produces in a bare form. Returning an error map from the handler re-enters the same path a failed validation takes.
+
+Excerpt — not a complete module
+
+```tsx
+<Form
+  onSubmit={async (values) => {
+    const answer = await fetch('/pedidos', {
+      body: new URLSearchParams(values as never),
+      method: 'POST',
+    });
+    if (!answer.ok) return await answer.json();
+  }}
+>
+  …
+</Form>;
+```
+
+### The row the actions stand in
+
+end is the default, between pushes a destructive action away from the one beside it, and stretch shares the row. Narrow the column below 360 pixels and every alignment becomes the same column of full-width actions, primary first.
+
+Excerpt — not a complete module
+
+```tsx
+<FormActions>
+  <Button tone="secondary" type="button" variant="ghost">
+    Cancelar
+  </Button>
+  <Button type="submit">Salvar alterações</Button>
+</FormActions>;
+
+<FormActions align="between">…</FormActions>;
+```
+
+### Every state the family carries
+
+data-invalid while anything is wrong, data-loading and aria-busy while a submit is in flight, data-disabled when the consumer says so. The form does not dim itself while it saves: a form that hid its own values would hide what the reader is waiting on.
+
+Excerpt — not a complete module
+
+```tsx
+// The family's own submission, and a mutation the consumer started.
+<Form loading={mutation.isPending}>…</Form>;
+
+const form = useFormState();
+<Button disabled={form?.submitting} type="submit">
+  Salvar
+</Button>;
+```
+
+### Eleven errors, and one for a field that is not there
+
+The list scrolls past twelve lines rather than truncating, and an error naming a control the form does not hold keeps its place without a link. Both are cases a real server produces and none of the surveyed implementations answers.
+
+Excerpt — not a complete module
+
+```tsx
+<Form errors={{ cupom: 'O cupom informado expirou', email: 'Endereço inválido' }}>
+  <Field>
+    <FieldLabel>E-mail</FieldLabel>
+    <TextField name="email" />
+  </Field>
+</Form>;
+```
+
+### Setting it once, reaching past it, and guarding it
+
+The provider carries the six decisions an application takes once; the handle reaches the four actions a value cannot express; guardUnsaved registers a beforeunload while anything has been edited, which nothing surveyed ships.
+
+Excerpt — not a complete module
+
+```tsx
+<FormDefaultsProvider validate="blur">
+  <Form guardUnsaved handle={handle}>
+    …
+  </Form>
+</FormDefaultsProvider>;
+
+<Button onClick={() => handle.current?.validate()}>Conferir</Button>;
+```
+
+### What a reader hears, and where focus goes
+
+Tab into the form, submit it empty, and follow what happens: the region announces itself, takes focus, and each link moves focus to the control it names without changing the address bar. Every message in the summary is the same string the field shows.
+
+Excerpt — not a complete module
+
+```tsx
+<Form errors={{ email: 'O endereço precisa conter um arroba' }}>
+  <Field invalid>
+    <FieldLabel>E-mail</FieldLabel>
+    <TextField name="email" />
+    <FieldError>O endereço precisa conter um arroba</FieldError>
+  </Field>
+</Form>;
+```