@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/form.json

@@ -0,0 +1,378 @@
+{
+  "family": "form",
+  "ui": "form",
+  "binding": "angular",
+  "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 {\n  provideFormDefaults,\n  provideFormErrorMessages,\n  SlForm,\n  SlFormActions,\n  SlFormSummary,\n} from '@slotted/angular/form';",
+        "selector": "form[slForm]",
+        "exportAs": "slForm"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "form",
+          "required": true,
+          "purpose": "The element itself, and the selector is form[slForm] rather than [slForm]: a submit event has nowhere else to come from, FormData reads a form, and requestSubmit() and reset() are the element’s own. It carries data-ui=\"form\", data-invalid, data-loading and data-disabled, writes novalidate, and is the query container the action row is measured against."
+        },
+        {
+          "part": "summary",
+          "element": "the element carrying slFormSummary",
+          "required": false,
+          "purpose": "The region a reader is sent to after a failed submit, with role=\"alert\" and tabindex=\"-1\". Rendered by the form under summary=\"auto\", or placed by the consumer 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": "the element carrying slFormActions",
+          "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": "slForm",
+          "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": "slForm",
+          "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": "slForm, provideFormDefaults",
+          "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": "slForm, provideFormDefaults",
+          "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": "slForm, provideFormDefaults",
+          "description": "Whether the family renders the summary as its first child. none leaves it to the consumer, who puts slFormSummary wherever the page needs it"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<FormMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slForm",
+          "description": "Words laid over the language in force, key by key: the summary’s heading (summaryTitle) and the built-in validators’ sentences (errors.required, errors.minlength, …)"
+        },
+        {
+          "name": "summaryDescription",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slForm, provideFormDefaults",
+          "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": "slForm, slFormActions, provideFormDefaults",
+          "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": "slForm, provideFormDefaults",
+          "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": "slForm",
+          "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": "slForm",
+          "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": "false",
+          "appliesTo": "slForm",
+          "description": "Writes data-disabled on the root. It does not disable the controls: a fieldset does that, and it does it natively"
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs",
+          "type": "'slForm'",
+          "defaultValue": "—",
+          "appliesTo": "the template",
+          "description": "Reaches the instance, and through it validateNow(), submit(), reset() and focusFirstError() — the four actions a consumer cannot express by passing a value"
+        },
+        {
+          "name": "ControlContainer",
+          "type": "formGroup, ngForm",
+          "defaultValue": "—",
+          "appliesTo": "the same element",
+          "description": "Reactive Forms is the second source of errors. Every control is marked touched at submit, and each failing one becomes a sentence: a built-in validator’s from the catalog’s errors.* messages, an application’s own through SL_FORM_ERROR_MESSAGES"
+        },
+        {
+          "name": "provideFormErrorMessages",
+          "type": "Record<string, (context) => string>",
+          "defaultValue": "{}",
+          "appliesTo": "an injector",
+          "description": "The sentence for a validator the application adds, by its key. Angular reports a key and a shape and never a message; the seven built-in keys are written by the catalog, and an entry for one of them replaces the catalog’s"
+        },
+        {
+          "name": "provideFormDefaults",
+          "type": "{ validate, errorFocus, summary, summaryDescription, align, nativeValidation }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The six decisions an application takes once. The summary’s heading comes from the language in force (provideSlotted)"
+        },
+        {
+          "name": "slFormSummary / slFormActions",
+          "type": "directives on the consumer’s own element",
+          "defaultValue": "—",
+          "appliesTo": "inside a form",
+          "description": "The summary placed by the page rather than by the family, and the action row with its own alignment when the form’s is not the one this row wants"
+        },
+        {
+          "name": "Signal Forms",
+          "type": "[field]",
+          "defaultValue": "—",
+          "appliesTo": "Angular 22",
+          "description": "Nothing is added here. Signal Forms binds a control through its ControlValueAccessor, which every Slotted control provides, so they work under [field] today"
+        }
+      ],
+      "events": [
+        {
+          "name": "errorsChange",
+          "payload": "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 validateNow() — the originating event, and cancel(). A request for the map the family already holds is not emitted."
+        },
+        {
+          "name": "formSubmit",
+          "payload": "{ values, event, errors(map), pending(promise) }",
+          "when": "When the form submits and nothing is wrong with it. The values are read from FormData in document order; errors() publishes what a server answered and moves focus; pending() holds the form in its busy state until the promise 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": "html",
+      "source": "<form slForm (formSubmit)=\"save($event.values)\">\n  <div slField>\n    <label slFieldLabel>Nome completo</label>\n    <div slTextField><input slTextFieldInput name=\"nome\" required /></div>\n  </div>\n  <div slFormActions>\n    <button slButton type=\"submit\">Salvar</button>\n  </div>\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": "html",
+      "source": "<form slForm validate=\"submit\">…</form>\n<form slForm validate=\"blur\">…</form>\n\n<!-- The browser still validates; only its bubble is off. -->\n<input slTextFieldInput name=\"email\" type=\"email\" required />\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 Reactive Forms. A server error is dropped as soon as the field it names is edited, and every error is dropped at the next submit.",
+      "language": "html",
+      "source": "<form slForm [errors]=\"serverErrors()\" [formGroup]=\"group\" (formSubmit)=\"save($event)\">\n  <div slField>\n    <label slFieldLabel>Nome</label>\n    <div slTextField><input slTextFieldInput name=\"nome\" formControlName=\"nome\" /></div>\n  </div>\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": "html",
+      "source": "<form slForm [messages]=\"{ summaryTitle: 'Corrija estes campos' }\">…</form>\n\n<!-- Somewhere else on the page, under a heading of your own. -->\n<form slForm summary=\"none\">\n  <h1>Pedido</h1>\n  <div slFormSummary></div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "submit",
+      "title": "Submission, and the second press that does nothing",
+      "note": "The submit event hands back a pending() for work that takes time and an errors() for what the server answered. A second submit while one is pending is refused — the defect a double-clicked button produces in a bare form.",
+      "language": "ts",
+      "source": "class CheckoutPage {\n  save(request: { values: Record<string, unknown>; pending: (work: Promise<unknown>) => void }) {\n    request.pending(\n      firstValueFrom(this.pedidos.criar(request.values)).then((answer) => answer.errors),\n    );\n  }\n}\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": "html",
+      "source": "<div slFormActions>\n  <button slButton type=\"button\" tone=\"secondary\" variant=\"ghost\">Cancelar</button>\n  <button slButton type=\"submit\">Salvar alterações</button>\n</div>\n\n<div slFormActions align=\"between\">…</div>\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": "html",
+      "source": "<form slForm [loading]=\"saving()\" #checkout=\"slForm\">\n  <div slFormActions>\n    <button slButton type=\"submit\" [loading]=\"saving()\">Salvar</button>\n  </div>\n</form>\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": "html",
+      "source": "<form slForm [errors]=\"{ cupom: 'O cupom informado expirou', email: 'Endereço inválido' }\">\n  <div slField>\n    <label slFieldLabel>E-mail</label>\n    <div slTextField><input slTextFieldInput name=\"email\" /></div>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, reaching past it, and guarding it",
+      "note": "Two injection tokens carry what an application decides once: how its forms behave, and the sentence of a validator the application adds. exportAs reaches the four actions a value cannot express, and guardUnsaved registers a beforeunload nothing surveyed ships.",
+      "language": "ts",
+      "source": "providers: [\n  provideFormDefaults({ validate: 'blur' }),\n  provideFormErrorMessages({\n    cnpj: () => 'CNPJ inválido.',\n  }),\n];\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": "html",
+      "source": "<form slForm [errors]=\"{ email: 'O endereço precisa conter um arroba' }\">\n  <div slField [invalid]=\"true\">\n    <label slFieldLabel>E-mail</label>\n    <div slTextField><input slTextFieldInput name=\"email\" /></div>\n    <p slFieldError>O endereço precisa conter um arroba</p>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/form.md

@@ -0,0 +1,235 @@
+<!-- index: ./index.md -->
+# form
+
+`data-ui="form"` · Form with validation, error summary and submit.
+
+## Import
+
+```ts
+import {
+  provideFormDefaults,
+  provideFormErrorMessages,
+  SlForm,
+  SlFormActions,
+  SlFormSummary,
+} from '@slotted/angular/form';
+```
+
+Selector: `form[slForm]` · exportAs: `slForm`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<form slForm (formSubmit)="save($event.values)">
+  <div slField>
+    <label slFieldLabel>Nome completo</label>
+    <div slTextField><input slTextFieldInput name="nome" required /></div>
+  </div>
+  <div slFormActions>
+    <button slButton type="submit">Salvar</button>
+  </div>
+</form>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | form | yes |
+| `summary` | the element carrying slFormSummary | no |
+| `summary-title` | h2 | no |
+| `summary-list` | ul | no |
+| `summary-item` | a[href], or span | no |
+| `actions` | the element carrying slFormActions | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `errors` | `Record<string, string \| string[]>` | — | slForm | 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[]>` | — | slForm | 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 | slForm, provideFormDefaults | 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 | slForm, provideFormDefaults | 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 | slForm, provideFormDefaults | Whether the family renders the summary as its first child. none leaves it to the consumer, who puts slFormSummary wherever the page needs it |
+| `messages` | `Partial<FormMessages>` | — | slForm | Words laid over the language in force, key by key: the summary’s heading (summaryTitle) and the built-in validators’ sentences (errors.required, errors.minlength, …) |
+| `summaryDescription` | `string` | — | slForm, provideFormDefaults | A sentence under the heading, for a form whose failure needs more than a list |
+| `align` | `'end' \| 'start' \| 'between' \| 'stretch'` | end | slForm, slFormActions, provideFormDefaults | 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 | slForm, provideFormDefaults | 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 | slForm | 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 | slForm | 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` | false | slForm | Writes data-disabled on the root. It does not disable the controls: a fieldset does that, and it does it natively |
+| `exportAs` | `'slForm'` | — | the template | Reaches the instance, and through it validateNow(), submit(), reset() and focusFirstError() — the four actions a consumer cannot express by passing a value |
+| `ControlContainer` | `formGroup, ngForm` | — | the same element | Reactive Forms is the second source of errors. Every control is marked touched at submit, and each failing one becomes a sentence: a built-in validator’s from the catalog’s errors.* messages, an application’s own through SL_FORM_ERROR_MESSAGES |
+| `provideFormErrorMessages` | `Record<string, (context) => string>` | {} | an injector | The sentence for a validator the application adds, by its key. Angular reports a key and a shape and never a message; the seven built-in keys are written by the catalog, and an entry for one of them replaces the catalog’s |
+| `provideFormDefaults` | `{ validate, errorFocus, summary, summaryDescription, align, nativeValidation }` | — | an injector | The six decisions an application takes once. The summary’s heading comes from the language in force (provideSlotted) |
+| `slFormSummary / slFormActions` | `directives on the consumer’s own element` | — | inside a form | The summary placed by the page rather than by the family, and the action row with its own alignment when the form’s is not the one this row wants |
+| `Signal Forms` | `[field]` | — | Angular 22 | Nothing is added here. Signal Forms binds a control through its ControlValueAccessor, which every Slotted control provides, so they work under [field] today |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `errorsChange` | `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 validateNow() — the originating event, and cancel(). A request for the map the family already holds is not emitted. |
+| `formSubmit` | `{ values, event, errors(map), pending(promise) }` | When the form submits and nothing is wrong with it. The values are read from FormData in document order; errors() publishes what a server answered and moves focus; pending() holds the form in its busy state until the promise 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
+
+```html
+<form slForm validate="submit">…</form>
+<form slForm validate="blur">…</form>
+
+<!-- The browser still validates; only its bubble is off. -->
+<input slTextFieldInput name="email" type="email" required />
+```
+
+### Where the errors come from
+
+Three sources merge into one map, latest last: a server’s answer, the platform’s own constraint validation, and Reactive Forms. 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
+
+```html
+<form slForm [errors]="serverErrors()" [formGroup]="group" (formSubmit)="save($event)">
+  <div slField>
+    <label slFieldLabel>Nome</label>
+    <div slTextField><input slTextFieldInput name="nome" formControlName="nome" /></div>
+  </div>
+</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
+
+```html
+<form slForm [messages]="{ summaryTitle: 'Corrija estes campos' }">…</form>
+
+<!-- Somewhere else on the page, under a heading of your own. -->
+<form slForm summary="none">
+  <h1>Pedido</h1>
+  <div slFormSummary></div>
+</form>
+```
+
+### Submission, and the second press that does nothing
+
+The submit event hands back a pending() for work that takes time and an errors() for what the server answered. A second submit while one is pending is refused — the defect a double-clicked button produces in a bare form.
+
+Excerpt — not a complete module
+
+```ts
+class CheckoutPage {
+  save(request: { values: Record<string, unknown>; pending: (work: Promise<unknown>) => void }) {
+    request.pending(
+      firstValueFrom(this.pedidos.criar(request.values)).then((answer) => answer.errors),
+    );
+  }
+}
+```
+
+### 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
+
+```html
+<div slFormActions>
+  <button slButton type="button" tone="secondary" variant="ghost">Cancelar</button>
+  <button slButton type="submit">Salvar alterações</button>
+</div>
+
+<div slFormActions align="between">…</div>
+```
+
+### 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
+
+```html
+<form slForm [loading]="saving()" #checkout="slForm">
+  <div slFormActions>
+    <button slButton type="submit" [loading]="saving()">Salvar</button>
+  </div>
+</form>
+```
+
+### 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
+
+```html
+<form slForm [errors]="{ cupom: 'O cupom informado expirou', email: 'Endereço inválido' }">
+  <div slField>
+    <label slFieldLabel>E-mail</label>
+    <div slTextField><input slTextFieldInput name="email" /></div>
+  </div>
+</form>
+```
+
+### Setting it once, reaching past it, and guarding it
+
+Two injection tokens carry what an application decides once: how its forms behave, and the sentence of a validator the application adds. exportAs reaches the four actions a value cannot express, and guardUnsaved registers a beforeunload nothing surveyed ships.
+
+Excerpt — not a complete module
+
+```ts
+providers: [
+  provideFormDefaults({ validate: 'blur' }),
+  provideFormErrorMessages({
+    cnpj: () => 'CNPJ inválido.',
+  }),
+];
+```
+
+### 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
+
+```html
+<form slForm [errors]="{ email: 'O endereço precisa conter um arroba' }">
+  <div slField [invalid]="true">
+    <label slFieldLabel>E-mail</label>
+    <div slTextField><input slTextFieldInput name="email" /></div>
+    <p slFieldError>O endereço precisa conter um arroba</p>
+  </div>
+</form>
+```