Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(CheckboxInput, Switch): a form's required default no longer marks an unchecked box or off switch required (#9664)

Cindy Zhang4b7546d3baef
diff --git a/.changeset/checkbox-switch-no-required-from-form-default.md b/.changeset/checkbox-switch-no-required-from-form-default.md
new file mode 100644
index 0000000000..2a751e289a
--- /dev/null
+++ b/.changeset/checkbox-switch-no-required-from-form-default.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `CheckboxInput`, `Switch` and `CheckboxList`: in a `FormLayout` with `defaultOptionality="required"`, an unchecked box, an off switch or an empty checkbox group no longer carries `aria-required`. A screen reader used to say "required", which on a checkbox means "must be ticked", while the form still submitted. Unchecked or off is an answer, so these controls take no required state from the form default. A `CheckboxInput` or `Switch` is required only through its own `isRequired`, which still sets `aria-required` and native `required`. The "Optional" and "Required" labels follow the same rules as on every other field. No code change is needed (WCAG 4.1.2).
+
+@cixzhang
diff --git a/.github/a11y-contract-durations.json b/.github/a11y-contract-durations.json
index abdc686ad6..6772af5006 100644
--- a/.github/a11y-contract-durations.json
+++ b/.github/a11y-contract-durations.json
@@ -1093,7 +1093,7 @@
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-disabled] — a disabled checkbox that keeps its tab stop": 14.4,
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-handlerless-read-only] — a handlerless controlled checkbox that is inert but does not declare read-only semantics": 14.6,
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-hidden-label] — a checkbox named by a visually hidden associated label": 19.3,
- "packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-inherited-required-valid] — an unchecked checkbox inheriting required semantics without native validation": 17.6,
+ "packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-under-required-default] — an unchecked checkbox under a required form default, which gives it no required state": 17.6,
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-invalid] — a checkbox whose current value is in error": 21.1,
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-loading] — a busy checkbox that stays focusable but refuses another change": 14.2,
"packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts › CheckboxInput [input-mixed] — a tri-state select-all checkbox in its partially checked state": 19.6,
diff --git a/apps/storybook/stories/CheckboxA11y.stories.tsx b/apps/storybook/stories/CheckboxA11y.stories.tsx
index 60416b8214..fee2c9210c 100644
--- a/apps/storybook/stories/CheckboxA11y.stories.tsx
+++ b/apps/storybook/stories/CheckboxA11y.stories.tsx
@@ -48,8 +48,8 @@ export const InputLoading = storyFor('input-loading');
export const InputReadOnly = storyFor('input-read-only');
export const InputHandlerlessReadOnly = storyFor('input-handlerless-read-only');
export const InputRequired = storyFor('input-required');
-export const InputInheritedRequiredValid = storyFor(
- 'input-inherited-required-valid',
+export const InputUnderRequiredDefault = storyFor(
+ 'input-under-required-default',
);
export const InputInvalid = storyFor('input-invalid');
export const InputWarning = storyFor('input-warning');
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsx
index 4253ef6de6..df8734d2c1 100644
--- a/apps/storybook/stories/FormLayout.stories.tsx
+++ b/apps/storybook/stories/FormLayout.stories.tsx
@@ -8,6 +8,9 @@ import {TextInput} from '@astryxdesign/core/TextInput';
import {Selector} from '@astryxdesign/core/Selector';
import {Field} from '@astryxdesign/core/Field';
import {Text} from '@astryxdesign/core/Text';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
+import {Switch} from '@astryxdesign/core/Switch';
import * as stylex from '@stylexjs/stylex';
const meta: Meta<typeof FormLayout> = {
@@ -344,6 +347,43 @@ export const DefaultOptionalityRequired: Story = {
},
};
+/**
+ * Choice controls in a form whose fields are required by default. An unchecked
+ * box, an off switch and an empty group are answers, so only a control's own
+ * `isRequired` makes it required; the text field still takes the default.
+ */
+export const DefaultOptionalityRequiredChoices: Story = {
+ name: 'Default Optionality — Required, choice controls',
+ render: () => {
+ const [name, setName] = useState('');
+ const [subscribe, setSubscribe] = useState(false);
+ const [darkMode, setDarkMode] = useState(false);
+ const [topics, setTopics] = useState<string[]>([]);
+ const [terms, setTerms] = useState(false);
+ return (
+ <FormLayout defaultOptionality="required">
+ <TextInput label="Name" value={name} onChange={setName} />
+ <CheckboxInput
+ label="Subscribe to the newsletter"
+ value={subscribe}
+ onChange={setSubscribe}
+ />
+ <Switch label="Dark mode" value={darkMode} onChange={setDarkMode} />
+ <CheckboxList label="Topics" value={topics} onChange={setTopics}>
+ <CheckboxListItem label="Design" value="design" />
+ <CheckboxListItem label="Code" value="code" />
+ </CheckboxList>
+ <CheckboxInput
+ label="Accept the terms"
+ value={terms}
+ onChange={setTerms}
+ isRequired
+ />
+ </FormLayout>
+ );
+ },
+};
+
// ─── Audit matrix ─────────────────────────────────────────────────────────────
/**
diff --git a/docs/specs/components/CheckboxInput/CheckboxInput.spec.md b/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
index 8f22d17de1..f9e21441ea 100644
--- a/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
+++ b/docs/specs/components/CheckboxInput/CheckboxInput.spec.md
@@ -111,7 +111,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR4 | `isDisabled` MUST keep the input focusable with `aria-disabled="true"` and no native `disabled`, block every change and the caller `onClick`, withhold `name`, and detach the input from its form so it neither submits nor blocks submission. With `disabledMessage`, a tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: other caller DOM handlers, such as `onKeyDown`, still run while disabled. | `spec:AST-085` FR1–FR3; shipped source and component tests; WCAG 2.1.1 and 4.1.2 |
| FR5 | Explicit `isReadOnly` MUST preserve the controlled value and ordinary focusability, expose read-only state, remain full-opacity, and refuse mutation. | shipped source and shared checkbox binding; WCAG 4.1.2 |
| FR6 | Description, status, disabled reason, and caller-provided `aria-describedby` ids MUST compose without dropping any source; error status MUST expose invalid state. | shipped source and tests; WCAG 1.3.1, 3.3.1, 4.1.2 |
-| FR7 | Explicit required state MUST retain native form validation; inherited required presentation MUST expose `aria-required` without silently enabling native validation. | shipped source and shared checkbox binding |
+| FR7 | Explicit `isRequired` MUST retain native form validation and expose `aria-required`. An unchecked box is an answer, so a form default (`component:FormLayout` FR5) gives the checkbox no required state: without its own `isRequired` it carries neither `aria-required` nor native `required`. Its Required and Optional markers follow `component:FieldLabel` FR4. | shipped source and shared checkbox binding |
| FR8 | Caller DOM props MUST reach the input, while component-owned type, checked, disabled, read-only, required, busy, invalid, description, ref, and styling values retain precedence. | `architecture:public-component-api/INV5–INV8`; component tests |
| FR9 | The outer field MUST retain `checkbox-input`, the label MUST retain `checkbox-label`, and the built-in CheckboxIndicator path MUST retain its canonical targets. Replacement indicators are not required to accept target classes. | source/docs target inventory; replacement component tests; `architecture:component-theming-surface/INV4–INV8,INV12` |
| FR10 | Keyboard/programmatic focus on the hidden native input MUST paint the shared focus-visible outline on the resolved indicator element, including a replacement indicator that forwards no props. | `architecture:interaction-modality/INV1–INV3`; component tests |
@@ -179,17 +179,18 @@ The consumer record includes composed targets owned by CheckboxIndicator, FieldL
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1, FR4–FR7, FR13, AR1–AR4 | `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` over the shared state list | Value states; hidden and described label; disabled; disabled reason; loading; read-only; handlerless; required; invalid | A role, name, state, focusability, or description expectation fails, or a removed known failure becomes stale. | `audit:CheckboxInput/a11y` |
-| FR2, FR3 | `CheckboxInput.test.tsx` change, changeAction-only, and loading cases; `BusyOwnerAnnouncement.test.tsx` CheckboxInput case | Click, label click, description click; `isLoading` | A wrong `onChange` value, a missing `aria-busy`, or a busy start announced more than once, or by the Spinner, fails. Evidence gap: no test asserts `changeAction` after `onChange` with `preventDefault`, or the optimistic value. | `audit:CheckboxInput/behavior` |
-| FR4, FR6, FR7 | `CheckboxInput.test.tsx` disabled, disabledMessage, description, status, and form suites | Disabled with and without reason; required; error | A toggling disabled box, a submitted disabled value, or a dropped description fails. Evidence gap: no test asserts that caller `onKeyDown` still runs while disabled (the FR4 gap). | `audit:CheckboxInput/behavior` |
-| FR8 | `CheckboxInput.test.tsx` passthrough, id, ref, and rest-precedence cases | Caller `id`, `data-*`, ref | A caller prop overriding `checked`, `disabled`, or `type` fails. | `audit:CheckboxInput/api` |
-| FR9 | `CheckboxInput.test.tsx` label-target case; `themingTargets.test.ts` | Label; built-in indicator | A missing label target, or a rendered class absent from the documented targets, fails. Evidence gap: no test asserts the root `checkbox-input` target. | `audit:CheckboxInput/theming` |
-| FR10, AR3 | `CheckboxInput.test.tsx` focus-ring ownership suite | Built-in and prop-dropping replacement indicators; blur | A ring on the wrong element, or none, fails. | `audit:CheckboxInput/a11y` |
-| FR11 | `CheckboxInput.test.tsx` pressed-state suite and its suite for an indicator that paints its own press | Enabled press; disabled; touch fade | A missing overlay, or one on a disabled box, fails. | `audit:CheckboxInput/visual` |
-| FR12, AR5 | `CheckboxInput.test.tsx` coarse-pointer, RTL, and forced-colors suites | `sm`, `md`; RTL; forced colors | A misplaced hit target or a mark lost in forced colors fails. Evidence gap: no test asserts field `width`. | `audit:CheckboxInput/layout` |
-| ORD1–ORD4, PR1 | ORD4 is covered by the FR8 rest-precedence case and ORD3 by the shared accessibility suite's disabled, disabled-reason, and read-only states. Evidence gap: no test asserts the optimistic value between `value` and the indicator (ORD1), the `preventDefault` check before `changeAction` (ORD2), or the absence of global listeners | — | — | `audit:CheckboxInput/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1, FR4–FR7, FR13, AR1–AR4 | `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` over the shared state list | Value states; hidden and described label; disabled; disabled reason; loading; read-only; handlerless; required; invalid | A role, name, state, focusability, or description expectation fails, or a removed known failure becomes stale. | `audit:CheckboxInput/a11y` |
+| FR2, FR3 | `CheckboxInput.test.tsx` change, changeAction-only, and loading cases; `BusyOwnerAnnouncement.test.tsx` CheckboxInput case | Click, label click, description click; `isLoading` | A wrong `onChange` value, a missing `aria-busy`, or a busy start announced more than once, or by the Spinner, fails. Evidence gap: no test asserts `changeAction` after `onChange` with `preventDefault`, or the optimistic value. | `audit:CheckboxInput/behavior` |
+| FR4, FR6, FR7 | `CheckboxInput.test.tsx` disabled, disabledMessage, description, status, and form suites | Disabled with and without reason; required; error | A toggling disabled box, a submitted disabled value, or a dropped description fails. Evidence gap: no test asserts that caller `onKeyDown` still runs while disabled (the FR4 gap). | `audit:CheckboxInput/behavior` |
+| FR8 | `CheckboxInput.test.tsx` passthrough, id, ref, and rest-precedence cases | Caller `id`, `data-*`, ref | A caller prop overriding `checked`, `disabled`, or `type` fails. | `audit:CheckboxInput/api` |
+| FR7 | `FormLayout.test.tsx` required-default and explicit `isRequired` cases; the shared state list's `input-under-required-default` and `input-required` states | Unmarked under a required default: no `aria-required`, no `required`, and the form submits; `isRequired`: `aria-required` plus native `required`, and an unchecked submission is blocked | An unmarked checkbox under a required default carrying `aria-required` or `required`, or an `isRequired` checkbox without both, fails. | `audit:CheckboxInput/api` |
+| FR9 | `CheckboxInput.test.tsx` label-target case; `themingTargets.test.ts` | Label; built-in indicator | A missing label target, or a rendered class absent from the documented targets, fails. Evidence gap: no test asserts the root `checkbox-input` target. | `audit:CheckboxInput/theming` |
+| FR10, AR3 | `CheckboxInput.test.tsx` focus-ring ownership suite | Built-in and prop-dropping replacement indicators; blur | A ring on the wrong element, or none, fails. | `audit:CheckboxInput/a11y` |
+| FR11 | `CheckboxInput.test.tsx` pressed-state suite and its suite for an indicator that paints its own press | Enabled press; disabled; touch fade | A missing overlay, or one on a disabled box, fails. | `audit:CheckboxInput/visual` |
+| FR12, AR5 | `CheckboxInput.test.tsx` coarse-pointer, RTL, and forced-colors suites | `sm`, `md`; RTL; forced colors | A misplaced hit target or a mark lost in forced colors fails. Evidence gap: no test asserts field `width`. | `audit:CheckboxInput/layout` |
+| ORD1–ORD4, PR1 | ORD4 is covered by the FR8 rest-precedence case and ORD3 by the shared accessibility suite's disabled, disabled-reason, and read-only states. Evidence gap: no test asserts the optimistic value between `value` and the indicator (ORD1), the `preventDefault` check before `changeAction` (ORD2), or the absence of global listeners | — | — | `audit:CheckboxInput/behavior` |
## Current-state impact
diff --git a/docs/specs/components/FormLayout/FormLayout.spec.md b/docs/specs/components/FormLayout/FormLayout.spec.md
index 53a486374a..a9b0b50462 100644
--- a/docs/specs/components/FormLayout/FormLayout.spec.md
+++ b/docs/specs/components/FormLayout/FormLayout.spec.md
@@ -86,14 +86,14 @@ This table is a review projection; the body below is authoritative.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap. | Released source, tests, and stories |
-| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule. | Released source, tests, and stories |
-| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap. | Released source, Field composition, and tests |
-| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8). | Context source and tests |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. | Tests; `family:input-fields` ownership |
-| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target. | `architecture:public-component-api/INV5–INV8`; source and tests |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap. | Released source, tests, and stories |
+| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule. | Released source, tests, and stories |
+| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap. | Released source, Field composition, and tests |
+| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8). | Context source and tests |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. Exception: CheckboxList, CheckboxInput, and Switch treat an empty selection, an unchecked box, or an off switch as an answer, so `defaultOptionality` gives them no required state: they take neither `aria-required` nor native `required` from it. CheckboxInput and Switch are required only through their own `isRequired`, and a CheckboxList and its rows take no required state from the form default; the marker rule above applies to them unchanged. | Tests; `family:input-fields` ownership |
+| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target. | `architecture:public-component-api/INV5–INV8`; source and tests |
### Allowed variation
@@ -117,7 +117,7 @@ This table is a review projection; the body below is authoritative.
- **ORD1 — Context.** Explicit props resolve against `vertical` and unset defaults, then the nearest provider exposes the resolved values to descendants.
- **ORD2 — Root props.** FormLayout-owned target and direction reflection compose with StyleX and caller styling; caller DOM props reach the same root without replacing owned reflection.
-- **ORD3 — Optionality.** The layout default establishes the unmarked majority; a field-level `isRequired` or `isOptional` marks the exception and controls native validation only when explicitly requested.
+- **ORD3 — Optionality.** The layout default establishes the unmarked majority; a field-level `isRequired` or `isOptional` marks the exception and controls native validation only when explicitly requested. CheckboxList, CheckboxInput, and Switch are the FR5 exception: the default sets no required state for them, so only their own `isRequired` makes them required.
### Performance and resources
@@ -126,7 +126,7 @@ This table is a review projection; the body below is authoritative.
## Accessibility contract
- **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
-- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology. This does not apply to the FR5 exception (CheckboxList, CheckboxInput, Switch), whose unmarked state is an answer, not a missing required value; a control marked `isRequired` still exposes its required state.
- **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
## Design relationships
@@ -178,14 +178,15 @@ The root target reflects the closed `direction` axis. It owns the outer arrangem
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
-| FR1–FR3 | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior` |
-| FR4, ORD1 | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx` | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary. | `audit:FormLayout/behavior` |
-| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests | Required, optional, unset defaults; explicit exceptions | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput, Slider, Typeahead, and Tokenizer tests cover a `required` default. | `audit:FormLayout/accessibility` |
-| FR6, ORD2 | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts` | Ref, attributes, colliding `data-direction` | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order. | `audit:FormLayout/api` |
-| AR1, AR3 | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks | Plain root; caller `role` | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own. | `audit:FormLayout/accessibility` |
-| PR1 | Source review | Every direction | Gap: no automated check covers context identity or added resources. | `audit:FormLayout/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
+| FR1–FR3 | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior` |
+| FR4, ORD1 | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx` | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary. | `audit:FormLayout/behavior` |
+| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests | Required, optional, unset defaults; explicit exceptions | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput, Slider, Typeahead, and Tokenizer tests cover a `required` default. | `audit:FormLayout/accessibility` |
+| FR5 | `FormLayout.test.tsx` "required default gives an unmarked checkbox, switch and checkbox group no required state" | Under `defaultOptionality="required"`, an unmarked CheckboxInput, Switch and CheckboxList (each box) carry no `aria-required` and no `required`, while a TextInput beside them still carries `aria-required`; the markers follow FieldLabel FR4 | An unmarked checkbox, switch or checkbox group carrying `aria-required` fails. | `audit:FormLayout/accessibility` |
+| FR6, ORD2 | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts` | Ref, attributes, colliding `data-direction` | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order. | `audit:FormLayout/api` |
+| AR1, AR3 | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks | Plain root; caller `role` | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own. | `audit:FormLayout/accessibility` |
+| PR1 | Source review | Every direction | Gap: no automated check covers context identity or added resources. | `audit:FormLayout/behavior` |
## Decision log
diff --git a/docs/specs/components/Switch/Switch.spec.md b/docs/specs/components/Switch/Switch.spec.md
index e1bca13301..37b3cb86f5 100644
--- a/docs/specs/components/Switch/Switch.spec.md
+++ b/docs/specs/components/Switch/Switch.spec.md
@@ -155,7 +155,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR5 | A change calls `onChange(checked, event)`; unless that call prevents default, `changeAction(checked, event)` runs in a transition and the switch shows the proposed state while the Action is pending, and `value` once it settles. | Current tests |
| FR6 | While `isLoading`, or while the shown state differs from `value`, the input sets `aria-busy`, ignores pointer input, refuses changes, keeps focus, and the switch announces its busy start once per busy period through the shared channel. | `spec:AST-086` FR8; current tests |
| FR7 | Disabled: `aria-disabled="true"` on a focusable input, no `name`, detached from its form (so it neither submits nor blocks submission when required), no change, no caller `onClick` on the field, no hover or press paint, and a half-opacity track. With `disabledMessage`, a reason tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: caller DOM handlers other than `onClick`, such as `onKeyDown`, still run on the field root while disabled (`spec:AST-085` FR2). | `spec:AST-085` FR1–FR3, FR5; current tests |
-| FR8 | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, while `aria-required` follows the effective required state; `aria-invalid` follows `status` (`false` on a required switch without an error), so the browser's own invalid state never shows before an error. | Current tests |
+| FR8 | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, and `aria-required` follows its own `isRequired` only; an off switch is an answer, so a form default (`component:FormLayout` FR5) gives it no required state; `aria-invalid` follows `status` (`false` on a required switch without an error), so the browser's own invalid state never shows before an error. | Current tests |
| FR9 | Keyboard focus paints the shared focus outline on the track. Hovering the enabled row tints the track; pressing paints the pressed overlay on both, applying `design:user-states` DR1 and DR2; a touch press fades out from the row. Track color transitions are instant under reduced motion; under a finger the colour fades with the thumb's cross-fade (FR15). | `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2 for the pressed overlay; `design:reduced-motion`; current tests |
| FR10 | The thumb travels toward the inline end when on, mirrored under RTL, and moves without a transition under reduced motion (`design:reduced-motion` DR1); under a finger it cross-fades to its rest instead (FR15). Where the primary pointer is coarse, the switch's hit area grows around the track toward 44 by 44 CSS pixels, each side stopping at half the gap to a neighbouring target so a tap goes to the nearer one (`spec:AST-094` FR42, `utils/hitArea.ts`), with nothing visible added. | WCAG 2.5.8; current tests; `design:reduced-motion` DR1; `spec:AST-094` FR42 |
| FR11 | Under forced colors, on and off stay distinguishable (Highlight track when on), and the hover tint does not hide the thumb. | WCAG 1.4.11; current tests |
@@ -305,7 +305,8 @@ making the absence intentional.
| FR1, FR4 | `Switch.test.tsx` structure, label, description, and interaction suites | On/off, size, label position, hidden label | Removing stable parts, or folding the description into the name, fails; the caller description first is asserted. Evidence gap: no test asserts the label order (the position cases count children only) or the disabled reason last. | `audit:Switch/anatomy` |
| FR2 | `Switch.test.tsx` label-target, labelSpacing, and pressed-state cases; `themingTargets.test.ts` | Current local targets | A missing label, field, track, or thumb target, or a missing `data-label-spacing`, fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts `data-label-position`, or the track and thumb `data-size`, `data-checked`, and `data-disabled`. | `audit:Switch/theming` |
| FR3, FR5, FR6 | `Switch.test.tsx` loading, announcement, and status suites | Busy, pending Action, StrictMode, re-busy, detached status | Removing composed feedback, or announcing more than once per busy period, fails. Evidence gap: no test asserts the Spinner inside the thumb, `changeAction` after `onChange` with `preventDefault`, the optimistic state, or that pointer input is ignored while busy. | `audit:Switch/anatomy` |
-| FR7, FR8 | `Switch.test.tsx` disabled, disabledMessage, and form cases; `PressedState.a11y.chromium.spec.ts` disabled press case | Disabled with and without reason; required; on and off | A change while disabled, a submitted disabled value, a blocked submit, or press paint on a disabled switch fails. Evidence gap: no test asserts the absent hover tint, the half-opacity track, or that caller `onKeyDown` still runs while disabled (the FR7 gap). No test asserts `aria-required` following a form-level required default. | `audit:Switch/behavior` |
+| FR7, FR8 | `Switch.test.tsx` disabled, disabledMessage, and form cases; `PressedState.a11y.chromium.spec.ts` disabled press case | Disabled with and without reason; required; on and off | A change while disabled, a submitted disabled value, a blocked submit, or press paint on a disabled switch fails. Evidence gap: no test asserts the absent hover tint, the half-opacity track, or that caller `onKeyDown` still runs while disabled (the FR7 gap). | `audit:Switch/behavior` |
+| FR8 | `FormLayout.test.tsx` required-default and switch `isRequired` cases; `Switch.test.tsx` required case | Unmarked under a required default: no `aria-required`, no `required`, and the form submits; `isRequired`: `aria-required` plus native `required`, and an off submission is blocked | An unmarked switch under a required default carrying `aria-required` or `required`, or an `isRequired` switch without both, fails. | `audit:Switch/behavior` |
| FR9–FR11 | `Switch.test.tsx` pressed-state, RTL, coarse-pointer, and forced-colors cases; `Switch.focusRing.source-build.test.mjs` | Mouse and touch press; RTL; coarse pointer; forced colors | Missing press paint, unmirrored travel, or lost forced-colors state fails. Evidence gap: no test asserts the hover tint, instant transitions under reduced motion with a mouse, or the track focus outline; the source-build check covers only how the outline finds the input. | `audit:Switch/visual` |
| FR12 | `Switch.test.tsx` rest-forwarding and ref cases | Root attributes; caller labelledby and describedby | A dropped ref, or a caller `aria-labelledby` or `aria-describedby` on the root, fails; the rest-forwarding case asserts `aria-label` on the root, which is the FR12 gap, so fixing the gap changes that test. Evidence gap: no test distinguishes `onFocus` and `onBlur` on the input from the root, or asserts a caller `onClick`, other handlers, `className`, `style`, `xstyle`, or `width` on the root. | `audit:Switch/api` |
| FR10 (coarse hit area), FR13–FR15 | `__tests__/Switch.interaction.browser.spec.ts` (Chromium and WebKit, real touch input), `__tests__/SwitchPointer.interaction.browser.spec.ts` (Chromium and WebKit, a real mouse; Chromium, a real pen), `Switch.test.tsx` hit-area cases and listener counts, and `switchTouch.test.ts` | The circle at each state's size; the 44 × 44 px hit area, and its stop halfway to a link beside it; a tap, a hold, a short drag, a flipping drag and a press slid off and lifted outside; right to left; Reduce Motion; a mouse or a pen drag past the flip, past it and back, and slid off; a click and a right click; a fine pointer's listeners at rest | A reshaped thumb, a hit area under 44 × 44 px with nothing near, a hit area past the midpoint to a neighbour, a thumb painted outside the track, a slid-off press that leaves the switch alone under a finger, a flip at any other distance, a mouse or pen drag that does not flip at the flip distance, a mouse or pen slid off that toggles, a lift or animation under a fine pointer, or more than one listener at rest under a fine pointer fails. | `audit:Switch/behavior` |
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index 86f58346c5..0a53411352 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx
@@ -51,7 +51,6 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {usePressFeedback} from '../hooks/usePressFeedback';
-import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useIndicator} from '../Indicator/useIndicator';
import {themeProps} from '../utils/themeProps';
@@ -378,10 +377,6 @@ export function CheckboxInput({
const id = idProp || generatedId;
const descriptionID = useId();
const statusMessageID = useId();
- // Announce the effective required state (form default included) while the
- // native `required` stays bound to the explicit `isRequired` so a layout
- // default never switches on browser validation.
- const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -511,7 +506,8 @@ export function CheckboxInput({
onClick={isDisabled ? undefined : rest.onClick}
readOnly={isReadOnly}
required={isRequired}
- aria-required={isEffectivelyRequired ? 'true' : undefined}
+ // A form's required default sets nothing here: an unchecked box is an answer.
+ aria-required={isRequired ? 'true' : undefined}
onChange={e => {
if (isDisabled || isBusy || isReadOnly) {
// Activation clears the native mixed state; React restores
diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.renders.tsx b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.renders.tsx
index fdd3c3f8cd..5ea95816a9 100644
--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.renders.tsx
+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.renders.tsx
@@ -52,7 +52,7 @@ function ControlledInput({
);
}
-function InheritedRequiredInput() {
+function UnderRequiredDefaultInput() {
return (
<FormLayout defaultOptionality="required">
<ControlledInput initial={false} label="Marketing consent" />
@@ -244,7 +244,7 @@ export const CHECKBOX_STATE_RENDERS: Record<
'input-required': () => (
<ControlledInput initial={false} label="Accept terms" isRequired />
),
- 'input-inherited-required-valid': () => <InheritedRequiredInput />,
+ 'input-under-required-default': () => <UnderRequiredDefaultInput />,
'input-invalid': () => (
<ControlledInput
initial={false}
diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts
index b83ea5aed7..28e1ebaaca 100644
--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts
+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts
@@ -184,13 +184,13 @@ export const CHECKBOX_BINDING_STATES = [
storyId: 'a11y-checkbox-pattern--input-required',
},
{
- id: 'input-inherited-required-valid',
+ id: 'input-under-required-default',
binding: 'CheckboxInput',
summary:
- 'an unchecked checkbox inheriting required semantics without native validation',
- facts: facts({required: true}),
+ 'an unchecked checkbox under a required form default, which gives it no required state',
+ facts: facts(),
visibleLabel: 'Marketing consent',
- storyId: 'a11y-checkbox-pattern--input-inherited-required-valid',
+ storyId: 'a11y-checkbox-pattern--input-under-required-default',
},
{
id: 'input-invalid',
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index 9b040193ef..ada68aadc8 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -7,7 +7,16 @@ export const docs = {
displayName: 'Form Layout',
group: 'Layout',
category: 'Layout',
- keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],
+ keywords: [
+ 'formlayout',
+ 'form',
+ 'fieldset',
+ 'formgroup',
+ 'formcontainer',
+ 'fields',
+ 'vertical',
+ 'horizontal',
+ ],
props: [
{
name: 'direction',
@@ -20,7 +29,7 @@ export const docs = {
name: 'defaultOptionality',
type: "'optional' | 'required'",
description:
- 'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. Leave unset for today\'s per-field behavior.',
+ 'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. CheckboxInput, Switch and CheckboxList are the exception: an unchecked box, an off switch or an empty group is an answer, so they take no required state from the default. A CheckboxInput or Switch is required only through its own isRequired. Leave unset for today\'s per-field behavior.',
},
{
name: 'children',
@@ -36,25 +45,65 @@ export const docs = {
},
],
theming: {
- targets: [
- {className: 'astryx-form-layout', visualProps: ['direction']},
- ],
+ targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
},
usage: {
- description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+ description:
+ 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
- { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
- { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
- { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
- { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
- { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+ {
+ guidance: true,
+ description:
+ "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+ },
],
anatomy: [
- {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
- {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
- {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
- {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+ {
+ name: 'Layout container',
+ required: true,
+ description:
+ 'Owns field arrangement, spacing, direction, and form-level optionality.',
+ },
+ {
+ name: 'Form title',
+ required: false,
+ description: 'Heading that describes the purpose of the form.',
+ },
+ {
+ name: 'Fields',
+ required: true,
+ description: 'Input components with labels for collecting user data.',
+ },
+ {
+ name: 'Footer',
+ required: false,
+ description: 'Contains confirmation buttons such as Submit or Cancel.',
+ },
],
},
};
@@ -75,7 +124,7 @@ export const docsZh = {
name: 'defaultOptionality',
type: "'optional' | 'required'",
description:
- '表单视为默认的状态,因此仅例外字段显示可选/必填指示器。设为 "optional" 时,仅标记 isRequired 的字段显示指示器;设为 "required" 时,仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时,未标记的字段仍会暴露 aria-required,使屏幕阅读器与视觉默认一致——仅作用于 aria-required,不改变原生 required 属性。不设置则保持当前逐字段行为。',
+ '表单视为默认的状态,因此仅例外字段显示可选/必填指示器。设为 "optional" 时,仅标记 isRequired 的字段显示指示器;设为 "required" 时,仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时,未标记的字段仍会暴露 aria-required,使屏幕阅读器与视觉默认一致——仅作用于 aria-required,不改变原生 required 属性。CheckboxInput、Switch 和 CheckboxList 例外:未勾选的复选框、关闭的开关或空的复选框组本身就是一个回答,因此默认值不会赋予它们必填状态。CheckboxInput 或 Switch 只有通过自身的 isRequired 才会成为必填。不设置则保持当前逐字段行为。',
},
{
name: 'children',
@@ -91,25 +140,65 @@ export const docsZh = {
},
],
theming: {
- targets: [
- {className: 'astryx-form-layout', visualProps: ['direction']},
- ],
+ targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
},
usage: {
- description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+ description:
+ 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
- { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
- { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
- { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
- { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
- { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+ {
+ guidance: true,
+ description:
+ "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+ },
],
anatomy: [
- {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
- {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
- {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
- {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+ {
+ name: 'Layout container',
+ required: true,
+ description:
+ 'Owns field arrangement, spacing, direction, and form-level optionality.',
+ },
+ {
+ name: 'Form title',
+ required: false,
+ description: 'Heading that describes the purpose of the form.',
+ },
+ {
+ name: 'Fields',
+ required: true,
+ description: 'Input components with labels for collecting user data.',
+ },
+ {
+ name: 'Footer',
+ required: false,
+ description: 'Contains confirmation buttons such as Submit or Cancel.',
+ },
],
},
};
@@ -119,26 +208,72 @@ export const docsDense = {
description:
'Layout container for form fields w/ consistent spacing + direction.',
usage: {
- description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+ description:
+ 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
- { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
- { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
- { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
- { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
- { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+ {
+ guidance: true,
+ description:
+ "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+ },
],
anatomy: [
- {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
- {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
- {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
- {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+ {
+ name: 'Layout container',
+ required: true,
+ description:
+ 'Owns field arrangement, spacing, direction, and form-level optionality.',
+ },
+ {
+ name: 'Form title',
+ required: false,
+ description: 'Heading that describes the purpose of the form.',
+ },
+ {
+ name: 'Fields',
+ required: true,
+ description: 'Input components with labels for collecting user data.',
+ },
+ {
+ name: 'Footer',
+ required: false,
+ description: 'Contains confirmation buttons such as Submit or Cancel.',
+ },
],
},
propDescriptions: {
- direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
- defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
- children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+ direction:
+ 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
+ defaultOptionality:
+ 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required), except CheckboxInput, Switch and CheckboxList, which take no required state from it (CheckboxInput and Switch are required only through their own isRequired). Unset = per-field behavior.',
+ children:
+ 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
+ xstyle:
+ 'StyleX styles for layout customization. Must be stylex.create() value.',
},
};
diff --git a/packages/core/src/FormLayout/FormLayout.test.tsx b/packages/core/src/FormLayout/FormLayout.test.tsx
index 5391560002..cfdca4b6a7 100644
--- a/packages/core/src/FormLayout/FormLayout.test.tsx
+++ b/packages/core/src/FormLayout/FormLayout.test.tsx
@@ -18,6 +18,8 @@ import type {FormLayoutDirection} from './FormLayoutContext';
import {Field} from '../Field';
import {TextInput} from '../TextInput';
import {CheckboxInput} from '../CheckboxInput';
+import {CheckboxList, CheckboxListItem} from '../CheckboxList';
+import {Switch} from '../Switch';
// Helper component to read context
function DirectionReader() {
@@ -283,7 +285,8 @@ describe('FormLayout', () => {
// `aria-required` must still be exposed — otherwise a sighted user reads a
// field as required (form default, no indicator) while a screen reader hears
// "not required". Native `required` stays bound to the explicit prop so a
- // layout default never switches on browser validation.
+ // layout default never switches on browser validation. Checkboxes, switches
+ // and checkbox groups are the exception: empty or off is an answer.
it('required default: an unmarked input still exposes aria-required', () => {
render(
@@ -320,17 +323,49 @@ describe('FormLayout', () => {
expect(screen.getByLabelText('Solo')).not.toHaveAttribute('aria-required');
});
- it('required default resolves aria-required without native required', () => {
+ // FR5 exception: an unchecked box, an off switch or an empty checkbox group
+ // is an answer, so the form default gives them no required state. A text
+ // field beside them still takes it.
+ it('required default gives an unmarked checkbox, switch and checkbox group no required state', () => {
render(
<FormLayout defaultOptionality="required">
- <CheckboxInput label="Terms" value={false} onChange={() => {}} />
+ <TextInput label="Name" value="" onChange={() => {}} />
+ <CheckboxInput label="Subscribe" value={false} onChange={() => {}} />
+ <Switch label="Dark mode" value={false} onChange={() => {}} />
+ <CheckboxList label="Topics" value={[]} onChange={() => {}}>
+ <CheckboxListItem label="Design" value="design" />
+ <CheckboxListItem label="Code" value="code" />
+ </CheckboxList>
</FormLayout>,
);
- const checkbox = screen.getByRole('checkbox', {name: 'Terms'});
- // Announced as required (form default)…
- expect(checkbox).toHaveAttribute('aria-required', 'true');
- // …but the native `required` attribute is not switched on by the layout.
- expect(checkbox).not.toHaveAttribute('required');
+ expect(screen.getByLabelText('Name')).toHaveAttribute(
+ 'aria-required',
+ 'true',
+ );
+ const unmarked = [
+ screen.getByRole('checkbox', {name: 'Subscribe'}),
+ screen.getByRole('switch', {name: 'Dark mode'}),
+ screen.getByRole('checkbox', {name: 'Design'}),
+ screen.getByRole('checkbox', {name: 'Code'}),
+ ];
+ for (const control of unmarked) {
+ expect(control).not.toHaveAttribute('aria-required');
+ expect(control).not.toHaveAttribute('required');
+ }
+ // The form default still hides the "Required" marker on these labels
+ // (FieldLabel FR4), as on every field.
+ expect(screen.queryByText('Required')).toBeNull();
+ });
+
+ it('explicit isRequired on a switch drives aria-required and native required under a layout', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <Switch label="Accept" value={false} onChange={() => {}} isRequired />
+ </FormLayout>,
+ );
+ const control = screen.getByRole('switch', {name: 'Accept'});
+ expect(control).toHaveAttribute('aria-required', 'true');
+ expect(control).toBeRequired();
});
it('explicit isRequired still drives native required under a layout', () => {
diff --git a/packages/core/src/FormLayout/FormLayout.tsx b/packages/core/src/FormLayout/FormLayout.tsx
index f0bdbb991a..bd5f398af8 100644
--- a/packages/core/src/FormLayout/FormLayout.tsx
+++ b/packages/core/src/FormLayout/FormLayout.tsx
@@ -103,7 +103,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
* shows an indicator (the "required" one).
* - `'required'` — fields read as required; only a field with `isOptional`
* shows an indicator (the "optional" one). Fields without `isOptional`
- * expose `aria-required` even though they show no indicator.
+ * expose `aria-required` even though they show no indicator. Checkboxes,
+ * switches and checkbox groups are the exception: an unchecked box, an off
+ * switch or an empty group is an answer, so they take no required state
+ * from the default. A checkbox or switch is required only through its own
+ * `isRequired`.
* - unset — today's behavior: `isRequired` and `isOptional` each show their
* own indicator independently.
*
diff --git a/packages/core/src/Switch/Switch.test.tsx b/packages/core/src/Switch/Switch.test.tsx
index 5ce565eaf3..705ff15188 100644
--- a/packages/core/src/Switch/Switch.test.tsx
+++ b/packages/core/src/Switch/Switch.test.tsx
@@ -665,9 +665,9 @@ describe('Switch', () => {
// Retained after review. The shared contract's switch.required.declared
// accepts either the native attribute or aria-required, because a non-native
- // switch can only offer the latter — and Switch sets aria-required from a
- // form-level default too. Only this test pins `isRequired` to the NATIVE
- // attribute, which is what makes the browser block submission.
+ // switch can only offer the latter. Switch sets aria-required from its own
+ // `isRequired` only. This test pins `isRequired` to the NATIVE attribute,
+ // which is what makes the browser block submission.
it('sets required attribute when isRequired is true', () => {
render(
<Switch
diff --git a/packages/core/src/Switch/Switch.tsx b/packages/core/src/Switch/Switch.tsx
index 35e99cf95b..c1f52a5882 100644
--- a/packages/core/src/Switch/Switch.tsx
+++ b/packages/core/src/Switch/Switch.tsx
@@ -52,7 +52,6 @@ import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {useAnnounce} from '../hooks/useAnnounce';
-import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {usePressFeedback} from '../hooks/usePressFeedback';
@@ -867,10 +866,6 @@ export function Switch({
const pressable = usePressFeedback();
const descriptionID = useId();
const statusMessageID = useId();
- // Announce the effective required state (form default included) while the
- // native `required` stays bound to the explicit `isRequired` so a layout
- // default never switches on browser validation.
- const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -1003,7 +998,8 @@ export function Switch({
aria-disabled={isDisabled ? 'true' : undefined}
form={isDisabled ? '' : undefined}
required={isRequired}
- aria-required={isEffectivelyRequired ? 'true' : undefined}
+ // A form's required default sets nothing here: an off switch is an answer.
+ aria-required={isRequired ? 'true' : undefined}
onChange={e => {
if (isDisabled || isBusy) {
return;
diff --git a/packages/core/src/hooks/useResolvedRequired.ts b/packages/core/src/hooks/useResolvedRequired.ts
index 0b0c5482d8..71584215e7 100644
--- a/packages/core/src/hooks/useResolvedRequired.ts
+++ b/packages/core/src/hooks/useResolvedRequired.ts
@@ -29,6 +29,9 @@ import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
* Semantics only: this drives `aria-required`, never the native `required`
* attribute, so a layout-level default can't silently switch on browser
* validation bubbles. `isOptional` takes precedence, matching `FieldLabel`.
+ *
+ * CheckboxInput and Switch do not use this hook: an unchecked box or an off
+ * switch is an answer, so a form default gives them no required state.
*/
export function useResolvedRequired({
isRequired = false,