Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/docs/specs/components/FieldStatus/FieldStatus.spec.md b/docs/specs/components/FieldStatus/FieldStatus.spec.md
index 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 polite
region, including on first mount and when message or type changes, without
moving 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 the
message is spoken or presented in braille are recommended real-AT follow-up
under `spec:AST-009`, not a merge or release requirement; DOM and
diff --git a/packages/core/src/FieldStatus/FieldStatus.doc.mjs b/packages/core/src/FieldStatus/FieldStatus.doc.mjs
index 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,
},