An open source design system that's fully customizable and agent ready
TypeScript
docs(FieldStatus): a repeated failed submit is the form's occasion to announce (#10122)
Cindy Zhang2d316a45fc03
diff --git a/.changeset/field-status-repeated-submit.md b/.changeset/field-status-repeated-submit.mdnew file mode 100644index 0000000000..36e1624639--- /dev/null+++ b/.changeset/field-status-repeated-submit.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] FieldStatus: the guidance now says that a field's status is announced when its message or type changes, not again when a repeated submit fails with the same errors, and shows how the form announces such a repeated submit, with unchanged errors, once with `useAnnounce` (the error count and the first error) and moves focus to the first invalid field.++@cixzhangdiff --git a/docs/specs/components/FieldStatus/FieldStatus.spec.md b/docs/specs/components/FieldStatus/FieldStatus.spec.mdindex afba3e860f..862283b0ee 100644--- a/docs/specs/components/FieldStatus/FieldStatus.spec.md+++ b/docs/specs/components/FieldStatus/FieldStatus.spec.md@@ -129,6 +129,12 @@ intentional decision.assertive region; warnings and successes MUST update the persistent politeregion, including on first mount and when message or type changes, withoutmoving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.+- **AR6 — A repeated submit is the form's occasion.** A field's status+ announces when its message or type changes, and not again for the same value+ (`spec:AST-086` FR6). A submit is the form's occasion (`spec:AST-086` FR1),+ so when a repeated submit fails with unchanged errors, the form announces it+ once through `useAnnounce`, for example the error count and the first error,+ and FieldStatus does not announce again.- **AR5 — Assistive-technology output.** Claims about whether, when, or how themessage is spoken or presented in braille are recommended real-AT follow-upunder `spec:AST-009`, not a merge or release requirement; DOM anddiff --git a/packages/core/src/FieldStatus/FieldStatus.doc.mjs b/packages/core/src/FieldStatus/FieldStatus.doc.mjsindex 865741314c..a7897cf401 100644--- a/packages/core/src/FieldStatus/FieldStatus.doc.mjs+++ b/packages/core/src/FieldStatus/FieldStatus.doc.mjs@@ -79,6 +79,11 @@ export const docs = {description:'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',},+ {+ guidance: true,+ description:+ "A field's status is announced when it first appears and when its message or type changes, not again when a repeated submit fails with the same errors. On such a repeated submit, with the errors unchanged, announce it once from the form with useAnnounce, for example announce(`${errors.length} errors. ${errors[0]}`, 'assertive'), and move focus to the first invalid field. On a first failed submit the fields announce their own errors, so the form adds no announcement.",+ },],anatomy,},@@ -105,6 +110,11 @@ export const docsDense = {description:'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',},+ {+ guidance: true,+ description:+ 'Status announces when it appears and on message/type change only. On a repeated submit with unchanged errors, the form announces once via useAnnounce (error count + first error) and focuses the first invalid field.',+ },],anatomy,},