--- name: form-error-summary-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit FormErrorSummary for a focusable error summary that links to invalid fields, without depending on a specific form library. metadata: component_version: "1.3.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/molecules/form-error-summary.tsx libs/ui/src/tokens/components/molecules/_form-error-summary.css libs/ui/stories/molecules/form-error-summary.stories.tsx" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit FormErrorSummary Usage Use FormErrorSummary to list validation errors with links that move focus to the invalid fields. It is presentational and form-library-agnostic. ## Shared focus contract The summary is programmatically focusable (`tabIndex=-1`) without adding a tab stop. After a failed submit, focus its ref once the errors have rendered. Its heading supplies the accessible name. Each link focuses and scrolls its real `targetId`, then calls `onFieldFocus`; keep target IDs unique within the document. This display-only alert has no value, read-only or canonical control-size axis. Pair its actionable error list with inline, icon-bearing field feedback; do not wrap it in another live region. An empty errors list renders nothing. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `FormErrorSummary`. **Use it when** - After a failed submit with two or more errors, above the form (or at the top of a long page). - Server-side validation results that map to several fields. **Use something else when** | Need | Use instead | | --- | --- | | A single field error | the field's inline error only; focus that field | | A non-field failure (network, permission) | StatusText above the actions or an error Toast with `Try again` | | Live validation while typing | inline field errors | **Do** - Move focus to the summary after submit; each item links to and focuses its field. - Word items the same as the inline messages, prefixed by the field label where needed. - Keep inline errors too — the summary is an index, not a replacement. - Remove the summary when the errors are fixed or on the next successful submit. **Don't** - Show the summary before the user tries to submit. - Put it in a toast or in a second alert dialog. For a form inside a Dialog, render it inside the dialog body above the fields, scroll the body to the top and focus the summary after a failed submit (it sits inside the focus trap). **Copy and states** - Title: `There are 3 problems with this form` (pluralised); items: `Enter an SKU with at least 4 characters`. **Behaviour (from the UX spec)** - Show it only after a submit attempt, and remove it when the errors are fixed or the next submit succeeds; stale items never linger. - Order items as the fields appear; an error for a field that isn't on screen goes to StatusText above the actions, not a dead link. - If `revealField` rejects, focus stays on the link and the app reports why. **Figma → code** | Figma | Code | | --- | --- | | no Figma component | code is the only source | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/FormErrorSummary → UX guidelines*. ## Setup ```tsx import { FormErrorSummary } from "@techsio/ui-kit/molecules/form-error-summary" ``` Supported props: ```text title?: string errors: { id: string; label: string; targetId: string }[] revealField?: (targetId: string) => void | Promise onFieldFocus?: (targetId: string) => void className ``` ## Core Patterns ### Link by field id `targetId` must match the `id` prop of the corresponding `Form*` component. The summary renders a real fragment link, reveals closed native `details` ancestors and focuses/scrolls the target without changing the page URL. For a custom accordion, tab or conditionally mounted field, provide `revealField(targetId): void | Promise`; resolve only after the target mounts. The summary resolves the element after this hook and calls `onFieldFocus` only after successful focus. ### Keep it form-library-agnostic Do not couple FormErrorSummary to a validation library. Consumers build the `errors` array and can use `onFieldFocus` for custom scroll/announce behavior. ### Hidden when empty Pass an empty `errors` array to render nothing. ## Common Mistakes ### HIGH Manual error list Wrong: ```tsx
    {errors.map((e) =>
  • {e.message}
  • )}
``` Correct: ```tsx ``` ### HIGH Wrong targetId Wrong: ```tsx errors={[{ id: "email", label: "Enter email", targetId: "email" }]} ``` Correct: ```tsx errors={[{ id: "email", label: "Enter email", targetId: "email-field" }]} ``` Source: libs/ui/src/molecules/form-error-summary.tsx ## Regression coverage Native checkbox/numeric targets, the focusable summary, and empty rendering are covered by `tests/form-error-summary.ids.test.ts`, included in the regular `pnpm test` Vitest run (no separate Bun invocation is needed). ## Validation Commands ```sh rg -P -n "]*>[[:space:]]*\{.*errors|]*errors=)" apps rg -n "targetId=\"" apps ```