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.mdnew file mode 100644index 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.++@freddymetadiff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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 contextfunction 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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 viadiff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsxindex 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.tsxindex 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.tsxindex 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 viadiff --git a/packages/core/src/Switch/Switch.tsx b/packages/core/src/Switch/Switch.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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');+}