@astryxdesign/core 0.4.4 → 0.4.5-canary.1dc3e5d

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -98,6 +98,18 @@ export const docs = {
       type: 'Array<(date: Date) => boolean>',
       description: 'Custom constraint functions to disable specific dates.',
     },
+    {
+      name: 'maxRangeSpan',
+      type: 'number',
+      description:
+        'Maximum days a selected range may span, counting both endpoints (`7` = a 7-day window, start + 6). Once a start is picked, days beyond this distance are disabled so the range cannot stretch past the cap. Rolling window relative to the start — for fixed calendar bounds use `min`/`max`. Constrains selection only; it never rewrites a `value` already wider than the cap (flag that with `status`).',
+    },
+    {
+      name: 'minRangeSpan',
+      type: 'number',
+      description:
+        'Minimum days a selected range must span, counting both endpoints (`2` forbids a single-day range). Once a start is picked, days closer than this are disabled. Defaults to 1 (same-day start and end allowed).',
+    },
     {
       name: 'presets',
       type: 'Array<DateRangePreset>',
@@ -313,6 +325,10 @@ export const docsDense = {
     min: 'min selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     max: 'max selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     dateConstraints: 'custom constraint fns to disable dates',
+    maxRangeSpan:
+      'max days a range may span, both endpoints counted (7 = a 7-day window); caps the window from the picked start. Selection-only; does not rewrite an over-wide value',
+    minRangeSpan:
+      'min days a range must span, both endpoints counted (2 forbids a single-day range); default 1',
     presets: 'preset ranges as quick-select options',
     hasClear: 'clear button when range is set (default true)',
     placeholder: 'placeholder when empty',

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When DateRangeInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
@@ -712,3 +712,83 @@ describe('DateRangeInput disabled theme state', () => {
     expect(root).not.toHaveAttribute('data-disabled');
   });
 });
+
+describe('DateRangeInput range-span forwarding', () => {
+  // Pin "today" so the popover opens on a known month and the day buttons we
+  // query are guaranteed to render.
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-05T12:00:00Z'));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // The calendar renders in the top layer; jsdom keeps day buttons in the DOM
+  // but role queries skip them, so reach them by their machine-readable
+  // data-date (ISO) attribute — the same approach Calendar's own tests use.
+  const dayButton = (iso: string): HTMLButtonElement | null =>
+    document.querySelector<HTMLButtonElement>(`button[data-date="${iso}"]`);
+
+  it('forwards maxRangeSpan so the window caps after a start is picked', () => {
+    render(
+      <DateRangeInput
+        label="Reporting period"
+        value={null}
+        onChange={() => {}}
+        maxRangeSpan={7}
+      />,
+    );
+
+    fireEvent.click(getButton('Open calendar'));
+
+    // Before a start is picked, a far-off day is selectable.
+    expect(dayButton('2026-01-20')).not.toBeDisabled();
+
+    fireEvent.click(dayButton('2026-01-10') as HTMLButtonElement);
+
+    // A 7-day window spans start ± 6 days: Jan 16 is the edge, Jan 17 is out.
+    expect(dayButton('2026-01-16')).not.toBeDisabled();
+    expect(dayButton('2026-01-17')).toBeDisabled();
+  });
+
+  it('disables a preset whose range violates the span cap', () => {
+    const presets = [
+      {
+        label: 'Last 3 days',
+        getRange: (): DateRange => ({
+          start: '2026-01-08',
+          end: '2026-01-10',
+        }),
+      },
+      {
+        label: 'Last 30 days',
+        getRange: (): DateRange => ({
+          start: '2025-12-12',
+          end: '2026-01-10',
+        }),
+      },
+    ];
+    const handleChange = vi.fn();
+    render(
+      <DateRangeInput
+        label="Reporting period"
+        value={null}
+        onChange={handleChange}
+        maxRangeSpan={7}
+        presets={presets}
+      />,
+    );
+
+    fireEvent.click(getButton('Open calendar'));
+
+    // The 3-day preset fits the 7-day cap; the 30-day preset can't be committed.
+    const withinCap = getButton('Last 3 days');
+    const overCap = getButton('Last 30 days');
+    expect(withinCap).not.toBeDisabled();
+    expect(overCap).toBeDisabled();
+
+    fireEvent.click(overCap);
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+});

package/src/DateRangeInput/DateRangeInput.tsx

@@ -22,6 +22,7 @@ import {
   plainDateFromISO,
   plainDateToday,
   plainDateFormat,
+  plainDateDiffDays,
   DATE_FORMAT_SHORT,
   DATE_FORMAT_SHORT_WITH_YEAR,
 } from '../utils/plainDate';
@@ -60,6 +61,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';
@@ -161,6 +163,11 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-accent-muted'],
     color: colorVars['--color-accent'],
   },
+  presetButtonDisabled: {
+    color: colorVars['--color-text-disabled'],
+    cursor: 'not-allowed',
+    backgroundColor: 'transparent',
+  },
 });
 
 const sizeStyles = stylex.create({
@@ -201,6 +208,34 @@ function isRangeEqual(a: DateRange | null, b: DateRange | null): boolean {
   return a.start === b.start && a.end === b.end;
 }
 
+// A preset that would land outside the span bounds is disabled rather than
+// allowed to override them: the cap is authoritative, so an out-of-window
+// preset stays visible (discoverable) but non-committable, mirroring how the
+// calendar disables out-of-window days. Spans count both endpoints.
+function isRangeWithinSpan(
+  range: DateRange,
+  maxRangeSpan: number | undefined,
+  minRangeSpan: number | undefined,
+): boolean {
+  if (maxRangeSpan == null && minRangeSpan == null) {
+    return true;
+  }
+  const span =
+    Math.abs(
+      plainDateDiffDays(
+        plainDateFromISO(range.start),
+        plainDateFromISO(range.end),
+      ),
+    ) + 1;
+  if (maxRangeSpan != null && span > maxRangeSpan) {
+    return false;
+  }
+  if (minRangeSpan != null && span < minRangeSpan) {
+    return false;
+  }
+  return true;
+}
+
 export interface DateRangeInputProps extends Omit<
   BaseProps,
   'onChange' | 'defaultValue'
@@ -303,6 +338,30 @@ export interface DateRangeInputProps extends Omit<
    */
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
 
+  /**
+   * Maximum number of days the selected range may span, counting both
+   * endpoints — `maxRangeSpan={7}` allows a 7-day window (start + 6 days).
+   * Once a start date is picked, days beyond this distance from it are
+   * disabled, so the user can't stretch the range past the cap. Use for
+   * rolling windows like "at most a week from the chosen day"; for fixed
+   * calendar bounds use `min`/`max`.
+   *
+   * This constrains selection only — it never rewrites a `value` that is
+   * already wider than the cap. Surface such a value with `status` if you
+   * need to flag it. A `preset` whose range violates the cap is disabled
+   * (shown but not committable) rather than allowed to override it.
+   */
+  maxRangeSpan?: number;
+
+  /**
+   * Minimum number of days the selected range must span, counting both
+   * endpoints — `minRangeSpan={2}` forbids a single-day range. Once a start
+   * date is picked, days closer than this to it are disabled — except the
+   * start itself, which stays selectable as the active anchor. Defaults to 1
+   * (a same-day start and end is allowed).
+   */
+  minRangeSpan?: number;
+
   /**
    * Preset date ranges shown as quick-select options beside the calendar.
    */
@@ -396,6 +455,8 @@ export function DateRangeInput({
   min,
   max,
   dateConstraints,
+  maxRangeSpan,
+  minRangeSpan,
   presets,
   hasClear = true,
   placeholder: placeholderFromProps,
@@ -413,6 +474,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 +671,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}
@@ -642,6 +704,11 @@ export function DateRangeInput({
               {presets.map(preset => {
                 const presetRange = preset.getRange();
                 const isActive = isRangeEqual(value, presetRange);
+                const isPresetDisabled = !isRangeWithinSpan(
+                  presetRange,
+                  maxRangeSpan,
+                  minRangeSpan,
+                );
                 return (
                   <button
                     key={preset.label}
@@ -652,11 +719,13 @@ export function DateRangeInput({
                     // marked with aria-current (not aria-selected, a listbox
                     // concept that contradicted the Tab interaction) (forms-5).
                     aria-current={isActive ? 'true' : undefined}
+                    disabled={isPresetDisabled}
                     onClick={() => handlePresetClick(preset)}
                     {...stylex.props(
                       focusOutlineStyles.focusVisible,
                       styles.presetButton,
                       isActive && styles.presetButtonActive,
+                      isPresetDisabled && styles.presetButtonDisabled,
                     )}>
                     {preset.label}
                   </button>
@@ -671,6 +740,8 @@ export function DateRangeInput({
             min={min}
             max={max}
             dateConstraints={dateConstraints}
+            maxRangeSpan={maxRangeSpan}
+            minRangeSpan={minRangeSpan}
             numberOfMonths={numberOfMonths}
             weekStartsOn={weekStartsOn}
           />

package/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
             }

package/src/Field/Field.doc.mjs

@@ -34,6 +34,7 @@ export const docs = {
         className: 'astryx-input-status-icon',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-input-clear-button'},
       {className: 'astryx-input-clear-icon'},
     ],
     vars: [

package/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;
 

package/src/Field/InputClearButton.test.tsx

@@ -114,4 +114,29 @@ describe('InputClearButton', () => {
     expect(css).toContain('.astryx-input-clear-icon:hover {');
     expect(css).toContain('color: var(--color-icon-primary)');
   });
+
+  it('renders the astryx-input-clear-button target on the button wrapper', () => {
+    render(<InputClearButton label="Clear" onClick={() => {}} />);
+    const button = screen.getByRole('button', {name: 'Clear'});
+    expect(button).toHaveClass('astryx-input-clear-button');
+  });
+
+  it('exposes input-clear-button so a theme controls the button size and hover', () => {
+    const theme = defineTheme({
+      name: 'input-clear-button-test',
+      components: {
+        'input-clear-button': {
+          base: {
+            height: '28px',
+            ':hover': {backgroundImage: 'none'},
+          },
+        },
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-input-clear-button {');
+    expect(css).toContain('height: 28px');
+    expect(css).toContain('.astryx-input-clear-button:hover {');
+    expect(css).toContain('background-image: none');
+  });
 });

package/src/Field/InputClearButton.tsx

@@ -11,7 +11,8 @@
  *   TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
  *   DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
  *   routes it through here, so the glyph is themed in one place via the
- *   `astryx-input-clear-icon` target.
+ *   `astryx-input-clear-icon` target and the button wrapper is themed via the
+ *   `astryx-input-clear-button` target.
  */
 
 import type {ReactNode} from 'react';
@@ -48,11 +49,13 @@ export function InputClearButton({
   iconClassName,
 }: InputClearButtonProps): ReactNode {
   const {className: iconTargetClassName} = themeProps('input-clear-icon');
+  const {className: buttonTargetClassName} = themeProps('input-clear-button');
   return (
     <Button
       variant="ghost"
       size="sm"
       label={label}
+      className={buttonTargetClassName}
       icon={
         <Icon
           icon="close"

package/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.',
   },

package/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>,