Skip to content

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

TypeScript

feat(FormLayout): add defaultOptionality — mark only the exception (#4791)

freddymeta22e61b523042
diff --git a/.changeset/formlayout-default-optionality.md b/.changeset/formlayout-default-optionality.md
new file mode 100644
index 0000000000..b7fce37393
--- /dev/null
+++ b/.changeset/formlayout-default-optionality.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] FormLayout: add `defaultOptionality` — set a form-wide default (`'optional'` or `'required'`) so only the exception carries a visible indicator. Under `'optional'` only `isRequired` fields show one; under `'required'` only `isOptional` fields do; a field that restates the default shows nothing. Under `'required'` the unmarked fields also expose `aria-required` so screen readers match what sighted users see — resolved on `aria-required` only, never the native `required` attribute. Unset keeps today's per-field behavior.
+
+@freddymeta
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsx
index 4bc9ea517a..ac418927d3 100644
--- a/apps/storybook/stories/FormLayout.stories.tsx
+++ b/apps/storybook/stories/FormLayout.stories.tsx
@@ -22,6 +22,12 @@ const meta: Meta<typeof FormLayout> = {
options: ['vertical', 'horizontal', 'horizontal-labels'],
description: 'Direction of field arrangement',
},
+ defaultOptionality: {
+ control: 'select',
+ options: [undefined, 'optional', 'required'],
+ description:
+ 'Form-wide default so only the exception shows an optional/required indicator',
+ },
},
};
@@ -265,3 +271,49 @@ export const InDialog: Story = {
);
},
};
+
+// ─── Default optionality: mark only the exception ─────────────────────────
+
+export const DefaultOptionalityOptional: Story = {
+ name: 'Default Optionality — Optional',
+ render: () => {
+ const [bio, setBio] = useState('');
+ const [nickname, setNickname] = useState('');
+ const [email, setEmail] = useState('');
+ // Everything reads as optional; only the required field is marked.
+ return (
+ <FormLayout defaultOptionality="optional">
+ <TextInput label="Bio" value={bio} onChange={setBio} />
+ <TextInput
+ label="Nickname"
+ value={nickname}
+ onChange={setNickname}
+ isOptional
+ />
+ <TextInput label="Email" value={email} onChange={setEmail} isRequired />
+ </FormLayout>
+ );
+ },
+};
+
+export const DefaultOptionalityRequired: Story = {
+ name: 'Default Optionality — Required',
+ render: () => {
+ const [name, setName] = useState('');
+ const [email, setEmail] = useState('');
+ const [nickname, setNickname] = useState('');
+ // Everything reads as required; only the optional field is marked.
+ return (
+ <FormLayout defaultOptionality="required">
+ <TextInput label="Name" value={name} onChange={setName} />
+ <TextInput label="Email" value={email} onChange={setEmail} isRequired />
+ <TextInput
+ label="Nickname"
+ value={nickname}
+ onChange={setNickname}
+ isOptional
+ />
+ </FormLayout>
+ );
+ },
+};
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index 8217c057a0..a00efedbdd 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx
@@ -47,6 +47,7 @@ import {useTooltip} from '../Tooltip';
import {mergeProps, mergeRefs} from '../utils';
import {indicatorScope} from '../Indicator/indicator.markers.stylex';
import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useIndicator} from '../Indicator';
import {themeProps} from '../utils/themeProps';
import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
@@ -301,6 +302,10 @@ export function CheckboxInput({
const id = useId();
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);
@@ -421,6 +426,7 @@ export function CheckboxInput({
form={isFocusableDisabled ? '' : undefined}
readOnly={isReadOnly}
required={isRequired}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
onChange={e => {
if (isDisabled || isBusy || isReadOnly) {
return;
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsx
index b1fb6e74ec..c7dda82f14 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.tsx
+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx
@@ -35,6 +35,7 @@ import {useTranslator} from '../i18n';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {usePopover} from '../Popover/usePopover';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {
colorVars,
durationVars,
@@ -344,6 +345,7 @@ export function ComplexSelector<Value>({
...props
}: ComplexSelectorProps<Value>) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
const effectiveStatusVariant =
variant === 'ghost' && statusVariant === 'attached'
@@ -497,7 +499,7 @@ export function ComplexSelector<Value>({
aria-controls={contentId}
aria-describedby={ariaDescribedBy}
aria-labelledby={labelId}
- aria-required={isRequired ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
disabled={isDisabled}
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index 2ec5fc9eeb..5adf3e6ddb 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -58,6 +58,7 @@ import {
} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {getInputARIA, isImeKeyEvent, parseDateInput} from '../utils';
@@ -399,6 +400,7 @@ export function DateInput({
...rest
}: DateInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.dateInput.placeholder');
const size = useSize(sizeProp, 'md');
@@ -737,7 +739,7 @@ export function DateInput({
readOnly={showsDisabledMessage || undefined}
aria-labelledby={ariaLabelledBy}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsx
index 090d509666..2498835b78 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx
@@ -60,6 +60,7 @@ import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {stableClassName} from '../naming';
@@ -413,6 +414,7 @@ export function DateRangeInput({
...rest
}: DateRangeInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.dateRangeInput.placeholder');
const size = useSize(sizeProp, 'md');
@@ -609,7 +611,7 @@ export function DateRangeInput({
aria-disabled={showsDisabledMessage ? 'true' : undefined}
aria-label={triggerAriaLabel}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
aria-expanded={popover.isOpen}
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index d899ca5ece..3b196313db 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -84,6 +84,7 @@ import {
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -448,6 +449,7 @@ export function DateTimeInput({
...rest
}: DateTimeInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
// Speaks arrow-key stepping results through the persistent live regions:
// stepping programmatically rewrites a plain textbox's value, which screen
// readers do not announce on their own (WCAG 4.1.2).
@@ -1009,7 +1011,7 @@ export function DateTimeInput({
aria-disabled={showsDisabledMessage ? 'true' : undefined}
readOnly={showsDisabledMessage || undefined}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isDateInputValid ? 'true' : undefined
}
@@ -1098,7 +1100,7 @@ export function DateTimeInput({
timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label})
}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isTimeInputValid ? 'true' : undefined
}
diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsx
index 13cad23e81..45ffeb5923 100644
--- a/packages/core/src/Field/FieldLabel.tsx
+++ b/packages/core/src/Field/FieldLabel.tsx
@@ -4,18 +4,19 @@
/**
* @file FieldLabel.tsx
- * @input Uses React, Icon, IconType, useTranslator
+ * @input Uses React, Icon, IconType, useTranslator, FormLayoutContext
* @output Exports FieldLabel component, FieldLabelProps
* @position Core label implementation; used by Field, CheckboxInput, Switch
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Field/index.ts (exports if types change)
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (defaultOptionality drives the indicator)
* - /packages/cli/assets/templates/blocks/components/Field/ (showcase blocks)
* - /packages/core/locales/en.json (@astryx.field.required / @astryx.field.optional)
*/
-import {useMemo, useRef, type ReactNode, type RefObject} from 'react';
+import {use, useMemo, useRef, type ReactNode, type RefObject} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {mergeProps} from '../utils';
@@ -32,6 +33,7 @@ import {Tooltip} from '../Tooltip';
import {useTranslator} from '../i18n';
import {themeProps} from '../utils/themeProps';
import {useInputContainer} from '../hooks';
+import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
const styles = stylex.create({
label: {
@@ -188,9 +190,23 @@ export function FieldLabel({
...rest
}: FieldLabelProps) {
const t = useTranslator();
- const statusText = isOptional
+ const {defaultOptionality} = use(FormLayoutContext);
+
+ // A form-level `defaultOptionality` means "only the exception is marked": a
+ // field that merely restates the form's default shows no indicator, and only
+ // a deviation from it does. This is the *visible indicator* only; the
+ // matching `aria-required` is resolved on each control (see
+ // useResolvedRequired) so the unmarked majority is still announced.
+ //
+ // defaultOptionality isRequired isOptional
+ // 'optional' → required indicator → (matches default, hidden)
+ // 'required' → (matches, hidden) → optional indicator
+ // unset → required indicator → optional indicator
+ const showRequired = isRequired && defaultOptionality !== 'required';
+ const showOptional = isOptional && defaultOptionality !== 'optional';
+ const statusText = showOptional
? t('@astryx.field.optional')
- : isRequired
+ : showRequired
? t('@astryx.field.required')
: null;
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index b7d38b5286..6a03a10d29 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -16,6 +16,12 @@ export const docs = {
'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
default: "'vertical'",
},
+ {
+ 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.',
+ },
{
name: 'children',
type: 'ReactNode',
@@ -64,6 +70,12 @@ export const docsZh = {
'控制字段排列方式。vertical 从上到下堆叠,horizontal 从左到右排列且等比弹性增长,horizontal-labels 使用 CSS Grid 将标签放在输入框左侧(在窄视口 <=480px 时折叠为垂直布局)。',
default: "'vertical'",
},
+ {
+ name: 'defaultOptionality',
+ type: "'optional' | 'required'",
+ description:
+ '表单视为默认的状态,因此仅例外字段显示可选/必填指示器。设为 "optional" 时,仅标记 isRequired 的字段显示指示器;设为 "required" 时,仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时,未标记的字段仍会暴露 aria-required,使屏幕阅读器与视觉默认一致——仅作用于 aria-required,不改变原生 required 属性。不设置则保持当前逐字段行为。',
+ },
{
name: 'children',
type: 'ReactNode',
@@ -122,6 +134,7 @@ export const docsDense = {
},
propDescriptions: {
direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=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.',
},
diff --git a/packages/core/src/FormLayout/FormLayout.test.tsx b/packages/core/src/FormLayout/FormLayout.test.tsx
index c6e779f7b9..805ad93dd4 100644
--- a/packages/core/src/FormLayout/FormLayout.test.tsx
+++ b/packages/core/src/FormLayout/FormLayout.test.tsx
@@ -16,6 +16,8 @@ import {FormLayout} from './FormLayout';
import {FormLayoutContext} from './FormLayoutContext';
import type {FormLayoutDirection} from './FormLayoutContext';
import {Field} from '../Field';
+import {TextInput} from '../TextInput';
+import {CheckboxInput} from '../CheckboxInput';
// Helper component to read context
function DirectionReader() {
@@ -23,6 +25,12 @@ function DirectionReader() {
return <span data-testid="direction">{direction}</span>;
}
+// Helper component to read the defaultOptionality context value
+function OptionalityReader() {
+ const {defaultOptionality} = use(FormLayoutContext);
+ return <span data-testid="optionality">{defaultOptionality ?? 'unset'}</span>;
+}
+
describe('FormLayout', () => {
// ─── Basic rendering ────────────────────────────────────────────────────
@@ -154,6 +162,178 @@ describe('FormLayout', () => {
expect(screen.getByTestId('inner-child-2')).toBeInTheDocument();
});
+ // ─── defaultOptionality context propagation ─────────────────────────────
+
+ it('leaves defaultOptionality unset by default', () => {
+ render(
+ <FormLayout>
+ <OptionalityReader />
+ </FormLayout>,
+ );
+ expect(screen.getByTestId('optionality')).toHaveTextContent('unset');
+ });
+
+ it('provides defaultOptionality="optional" to children', () => {
+ render(
+ <FormLayout defaultOptionality="optional">
+ <OptionalityReader />
+ </FormLayout>,
+ );
+ expect(screen.getByTestId('optionality')).toHaveTextContent('optional');
+ });
+
+ it('provides defaultOptionality="required" to children', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <OptionalityReader />
+ </FormLayout>,
+ );
+ expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+ });
+
+ it('an inner layout shadows the outer defaultOptionality', () => {
+ render(
+ <FormLayout defaultOptionality="optional">
+ <FormLayout defaultOptionality="required">
+ <OptionalityReader />
+ </FormLayout>
+ </FormLayout>,
+ );
+ expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+ });
+
+ // ─── defaultOptionality indicator behavior (through Field) ───────────────
+ //
+ // The rule: only the *exception* is marked. A field that restates the form
+ // default shows nothing; a deviation shows its indicator.
+
+ it('optional default: only isRequired fields show an indicator', () => {
+ render(
+ <FormLayout defaultOptionality="optional">
+ <Field label="Bio" inputID="bio">
+ <input id="bio" />
+ </Field>
+ <Field label="Nickname" inputID="nick" isOptional>
+ <input id="nick" />
+ </Field>
+ <Field label="Email" inputID="email" isRequired>
+ <input id="email" />
+ </Field>
+ </FormLayout>,
+ );
+ // Plain + isOptional match the default → nothing shown.
+ expect(screen.queryByText(/Optional/)).not.toBeInTheDocument();
+ // isRequired deviates → the required indicator shows.
+ expect(screen.getByText(/Required/)).toBeInTheDocument();
+ });
+
+ it('required default: only isOptional fields show an indicator', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <Field label="Name" inputID="name">
+ <input id="name" />
+ </Field>
+ <Field label="Email" inputID="email" isRequired>
+ <input id="email" />
+ </Field>
+ <Field label="Nickname" inputID="nick" isOptional>
+ <input id="nick" />
+ </Field>
+ </FormLayout>,
+ );
+ // Plain + isRequired match the default → nothing shown.
+ expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
+ // isOptional deviates → the optional indicator shows.
+ expect(screen.getByText(/Optional/)).toBeInTheDocument();
+ });
+
+ it('unset default preserves per-field indicators (backwards compatible)', () => {
+ render(
+ <FormLayout>
+ <Field label="Email" inputID="email" isRequired>
+ <input id="email" />
+ </Field>
+ <Field label="Nickname" inputID="nick" isOptional>
+ <input id="nick" />
+ </Field>
+ </FormLayout>,
+ );
+ expect(screen.getByText(/Required/)).toBeInTheDocument();
+ expect(screen.getByText(/Optional/)).toBeInTheDocument();
+ });
+
+ // ─── defaultOptionality aria-required resolution ─────────────────────────
+ //
+ // The indicator is suppressed for the unmarked majority, so the matching
+ // `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.
+
+ it('required default: an unmarked input still exposes aria-required', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <TextInput label="Name" value="" onChange={() => {}} />
+ </FormLayout>,
+ );
+ expect(screen.getByLabelText('Name')).toHaveAttribute(
+ 'aria-required',
+ 'true',
+ );
+ });
+
+ it('required default: an isOptional input is not aria-required', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <TextInput label="Nickname" value="" onChange={() => {}} isOptional />
+ </FormLayout>,
+ );
+ expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-required');
+ });
+
+ it('optional default: an unmarked input is not aria-required', () => {
+ render(
+ <FormLayout defaultOptionality="optional">
+ <TextInput label="Bio" value="" onChange={() => {}} />
+ </FormLayout>,
+ );
+ expect(screen.getByLabelText('Bio')).not.toHaveAttribute('aria-required');
+ });
+
+ it('no layout: an unmarked input is not aria-required (backwards compatible)', () => {
+ render(<TextInput label="Solo" value="" onChange={() => {}} />);
+ expect(screen.getByLabelText('Solo')).not.toHaveAttribute('aria-required');
+ });
+
+ it('required default resolves aria-required without native required', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <CheckboxInput label="Terms" value={false} onChange={() => {}} />
+ </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');
+ });
+
+ it('explicit isRequired still drives native required under a layout', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <CheckboxInput
+ label="Consent"
+ value={false}
+ onChange={() => {}}
+ isRequired
+ />
+ </FormLayout>,
+ );
+ const checkbox = screen.getByRole('checkbox', {name: 'Consent'});
+ expect(checkbox).toHaveAttribute('aria-required', 'true');
+ expect(checkbox).toHaveAttribute('required');
+ });
+
// ─── Snapshot tests ─────────────────────────────────────────────────────
it('matches snapshot for vertical direction', () => {
@@ -223,10 +403,7 @@ describe('FormLayout', () => {
it('horizontal-labels with Field: label and input wrapper are siblings under display:contents', () => {
render(
<FormLayout direction="horizontal-labels" data-testid="layout">
- <Field
- label="Username"
- inputID="username"
- data-testid="username-field">
+ <Field label="Username" inputID="username" data-testid="username-field">
<input id="username" data-testid="username-input" />
</Field>
</FormLayout>,
diff --git a/packages/core/src/FormLayout/FormLayout.tsx b/packages/core/src/FormLayout/FormLayout.tsx
index a5a4173c97..04c26e5cca 100644
--- a/packages/core/src/FormLayout/FormLayout.tsx
+++ b/packages/core/src/FormLayout/FormLayout.tsx
@@ -10,7 +10,10 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (context value shape)
+ * - /packages/core/src/FormLayout/FormLayout.doc.mjs (props table)
* - /packages/core/src/FormLayout/index.ts (exports if types change)
+ * - /packages/core/src/Field/FieldLabel.tsx (defaultOptionality indicator resolution)
* - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
*/
@@ -19,7 +22,11 @@ import {useMemo, type ReactNode} from 'react';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
-import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
+import {
+ FormLayoutContext,
+ type FormLayoutDirection,
+ type FormOptionality,
+} from './FormLayoutContext';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
@@ -82,6 +89,26 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
* @default 'vertical'
*/
direction?: FormLayoutDirection;
+
+ /**
+ * Which state the form treats as its default, so only the *exception*
+ * carries a visible optional/required indicator. It also resolves each
+ * field's `aria-required` so the unmarked majority is still announced
+ * correctly — but only `aria-required`, never the native `required`
+ * attribute, so a layout default can't switch on browser validation.
+ *
+ * - `'optional'` — fields read as optional; only a field with `isRequired`
+ * 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.
+ * - unset — today's behavior: `isRequired` and `isOptional` each show their
+ * own indicator independently.
+ *
+ * A field that merely restates the default (e.g. `isOptional` under
+ * `'optional'`) shows nothing. An inner `FormLayout` shadows an outer one.
+ */
+ defaultOptionality?: FormOptionality;
}
// =============================================================================
@@ -109,13 +136,17 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
export function FormLayout({
children,
direction = 'vertical',
+ defaultOptionality,
xstyle,
className,
style,
ref,
...props
}: FormLayoutProps) {
- const contextValue = useMemo(() => ({direction}), [direction]);
+ const contextValue = useMemo(
+ () => ({direction, defaultOptionality}),
+ [direction, defaultOptionality],
+ );
return (
<FormLayoutContext value={contextValue}>
diff --git a/packages/core/src/FormLayout/FormLayoutContext.ts b/packages/core/src/FormLayout/FormLayoutContext.ts
index eec57b00fc..6827fdb381 100644
--- a/packages/core/src/FormLayout/FormLayoutContext.ts
+++ b/packages/core/src/FormLayout/FormLayoutContext.ts
@@ -5,10 +5,13 @@
/**
* @file FormLayoutContext.ts
* @input Uses React createContext
- * @output Exports FormLayoutContext and FormLayoutDirection type
- * @position Context for form layout direction detection
+ * @output Exports FormLayoutContext, FormLayoutDirection, and FormOptionality types
+ * @position Context for form layout direction + default-optionality detection
*
* SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop + context value)
+ * - /packages/core/src/Field/FieldLabel.tsx (indicator resolution)
+ * - /packages/core/src/FormLayout/index.ts (exports if types change)
*/
import {createContext} from 'react';
@@ -22,15 +25,27 @@ import {createContext} from 'react';
* of their inputs (settings/admin panel pattern).
*/
export type FormLayoutDirection =
- | 'vertical'
- | 'horizontal'
- | 'horizontal-labels';
+ 'vertical' | 'horizontal' | 'horizontal-labels';
/**
- * Context for detecting which form layout direction a component is rendered in.
- * Children can use this to adapt their rendering based on the parent layout.
+ * Which state a form treats as its default, so only the *exception* carries a
+ * visible optional/required indicator.
+ *
+ * - `'optional'` — fields are optional unless a field opts into `isRequired`;
+ * only required fields show an indicator.
+ * - `'required'` — fields are required unless a field opts into `isOptional`;
+ * only optional fields show an indicator.
+ */
+export type FormOptionality = 'optional' | 'required';
+
+/**
+ * Context for detecting which form layout a component is rendered in. Children
+ * can use this to adapt their rendering based on the parent layout — direction
+ * for spatial arrangement, and `defaultOptionality` so a field can suppress the
+ * indicator that merely restates the form-wide default.
*/
export const FormLayoutContext = createContext<{
direction: FormLayoutDirection;
+ defaultOptionality?: FormOptionality;
}>({direction: 'vertical'});
FormLayoutContext.displayName = 'FormLayoutContext';
diff --git a/packages/core/src/FormLayout/index.ts b/packages/core/src/FormLayout/index.ts
index 51eff1d43e..1e11bfa38d 100644
--- a/packages/core/src/FormLayout/index.ts
+++ b/packages/core/src/FormLayout/index.ts
@@ -13,5 +13,5 @@
export {FormLayout} from './FormLayout';
export type {FormLayoutProps} from './FormLayout';
-export type {FormLayoutDirection} from './FormLayoutContext';
+export type {FormLayoutDirection, FormOptionality} from './FormLayoutContext';
export {FormLayoutContext} from './FormLayoutContext';
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index 08cad69334..214f3daa7a 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -73,6 +73,7 @@ import {
import {useMultiCombobox} from './hooks';
import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
@@ -706,6 +707,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
style,
}: MultiSelectorProps<T>) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.multiSelector.selectPlaceholder');
const selectAllLabel =
@@ -1526,7 +1528,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
}
aria-describedby={ariaDescribedBy}
aria-labelledby={ariaLabelledBy}
- aria-required={isRequired ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
// With a disabledMessage the trigger keeps focusability via
diff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsx
index 5027af0b6b..ec48f31b02 100644
--- a/packages/core/src/NumberInput/NumberInput.tsx
+++ b/packages/core/src/NumberInput/NumberInput.tsx
@@ -53,6 +53,7 @@ import {getInputARIA} from '../utils';
import {useSize} from '../SizeContext/SizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputGroup} from '../InputGroup/InputGroupContext';
const styles = stylex.create({
@@ -559,6 +560,7 @@ export function NumberInput({
...rest
}: NumberInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const size = useSize(sizeProp, 'md');
const id = useId();
const inputLabelID = useId();
@@ -927,7 +929,7 @@ export function NumberInput({
value == null || !formatValue ? undefined : formattedValue
}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
index a56d41691a..e147d658b8 100644
--- a/packages/core/src/RadioList/RadioList.tsx
+++ b/packages/core/src/RadioList/RadioList.tsx
@@ -29,6 +29,7 @@ import {spacingVars} from '../theme/tokens.stylex';
import {Field} from '../Field/Field';
import type {InputStatus} from '../Field/types';
import {useTooltip} from '../Tooltip';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
@@ -218,6 +219,13 @@ export function RadioList({
const groupRef = useRef<HTMLDivElement>(null);
+ // The radiogroup exposes the *effective* required state so a form-wide
+ // `defaultOptionality="required"` is announced even when the group carries no
+ // visible indicator. Individual radios keep their native `required` bound to
+ // the explicit `isRequired` (via context), so a layout default never switches
+ // on browser validation for the group.
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+
// Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
// controls swallow pointer events, so the tooltip listeners attach to the
// radiogroup container and the radios stay perceivable via aria-disabled
@@ -387,7 +395,7 @@ export function RadioList({
.join(' ') || undefined
}
aria-invalid={status?.type === 'error' ? true : undefined}
- aria-required={isRequired || undefined}
+ aria-required={isEffectivelyRequired || undefined}
{...mergeProps(
themeProps('radio-list', {orientation, size}),
stylex.props(
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index 41e5387fe9..378ce85bda 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -71,6 +71,7 @@ import {
} from './utils';
import {useCombobox, useSelectedItemOffset} from './hooks';
import {useTypeahead} from '../hooks/useTypeahead';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {SelectorOption} from './SelectorOption';
import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
import {useSize} from '../SizeContext/SizeContext';
@@ -699,6 +700,7 @@ export function Selector<T extends SelectorOptionType>(
hasClear: hasClearProp,
...rest
} = props as SelectorPropsClearable<T>;
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
const searchPlaceholder =
searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
@@ -1345,7 +1347,7 @@ export function Selector<T extends SelectorOptionType>(
}
aria-describedby={ariaDescribedBy}
aria-labelledby={ariaLabelledBy}
- aria-required={isRequired ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
// With a disabledMessage the trigger keeps focusability via
diff --git a/packages/core/src/Switch/Switch.tsx b/packages/core/src/Switch/Switch.tsx
index 0a3ed2ef7a..176dcff8b3 100644
--- a/packages/core/src/Switch/Switch.tsx
+++ b/packages/core/src/Switch/Switch.tsx
@@ -47,6 +47,7 @@ import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {VisuallyHidden} from '../VisuallyHidden';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
const wrapperSizeStyles = stylex.create({
sm: {
@@ -503,6 +504,10 @@ export function Switch({
const id = useId();
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);
@@ -559,6 +564,7 @@ export function Switch({
aria-disabled={showsDisabledMessage ? 'true' : undefined}
form={showsDisabledMessage ? '' : undefined}
required={isRequired}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
onChange={e => {
if (isDisabled || isBusy) {
return;
diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsx
index 5846bdf0eb..c96dddd018 100644
--- a/packages/core/src/TextArea/TextArea.tsx
+++ b/packages/core/src/TextArea/TextArea.tsx
@@ -52,6 +52,7 @@ import type {SizeValue} from '../utils/types';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {characterCount} from '../utils/characters';
@@ -394,6 +395,7 @@ export function TextArea({
}: TextAreaProps) {
const size = useSize(sizeProp, 'md');
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const announce = useAnnounce();
const id = useId();
const descriptionID = useId();
@@ -598,7 +600,7 @@ export function TextArea({
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired && !isOptional ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' ||
(maxLength != null && valueLength > maxLength)
diff --git a/packages/core/src/TextInput/TextInput.tsx b/packages/core/src/TextInput/TextInput.tsx
index 414e450781..b05b754a7e 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -101,6 +101,7 @@ import {mergeProps, mergeRefs} from '../utils';
import {useSize} from '../SizeContext/SizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
@@ -301,6 +302,7 @@ export function TextInput({
...rest
}: TextInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const size = useSize(sizeProp, 'md');
const id = useId();
@@ -445,7 +447,7 @@ export function TextInput({
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
aria-labelledby={ariaLabelledBy}
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 107af1f280..efb3475a56 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -67,6 +67,7 @@ import {useSize} from '../SizeContext/SizeContext';
import {useAnnounce} from '../hooks/useAnnounce';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {groupStyles} from '../InputGroup/groupStyles';
import {useTooltip} from '../Tooltip';
@@ -347,6 +348,7 @@ export function TimeInput({
ref,
}: TimeInputProps) {
const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.timeInput.placeholder');
const size = useSize(sizeProp, 'md');
@@ -664,7 +666,7 @@ export function TimeInput({
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
diff --git a/packages/core/src/hooks/useResolvedRequired.ts b/packages/core/src/hooks/useResolvedRequired.ts
new file mode 100644
index 0000000000..0b0c5482d8
--- /dev/null
+++ b/packages/core/src/hooks/useResolvedRequired.ts
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useResolvedRequired.ts
+ * @input Uses React, FormLayoutContext
+ * @output Exports useResolvedRequired
+ * @position Resolves a field's effective aria-required against the form default
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (defaultOptionality source)
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop doc: aria-required behavior)
+ */
+
+import {use} from 'react';
+import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
+
+/**
+ * Resolve a field's effective *required* state for `aria-required`, honoring a
+ * surrounding `FormLayout`'s `defaultOptionality`.
+ *
+ * Under `defaultOptionality="required"` a field is required unless it opts out
+ * with `isOptional`. The visible indicator is suppressed for the unmarked
+ * majority, so those fields must still expose `aria-required` — otherwise a
+ * sighted user reads them as required (form-wide default, no indicator) while a
+ * screen reader hears "not required". This closes that mismatch.
+ *
+ * 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`.
+ */
+export function useResolvedRequired({
+ isRequired = false,
+ isOptional = false,
+}: {
+ isRequired?: boolean;
+ isOptional?: boolean;
+}): boolean {
+ const {defaultOptionality} = use(FormLayoutContext);
+ return !isOptional && (isRequired || defaultOptionality === 'required');
+}