@astryxdesign/core 0.4.4 → 0.4.5-canary.0472ec1

package/src/Field/InputClearButton.test.tsx

@@ -2,7 +2,8 @@
 
 /**
  * @file InputClearButton.test.tsx
- * @input Uses vitest, @testing-library/react, InputClearButton, Icon, theme
+ * @input Uses node:fs, node:path, vitest, @testing-library/react, InputClearButton, Icon,
+ *   theme
  * @output Unit tests for the shared clear-button primitive
  * @position Testing; validates InputClearButton.tsx — the single home for the
  *   clearable input family's clear (✕) affordance and its theme target.
@@ -10,6 +11,8 @@
  * SYNC: When InputClearButton.tsx changes, update tests to match new behavior.
  */
 
+import {readFileSync} from 'node:fs';
+import path from 'node:path';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {InputClearButton} from './InputClearButton';
@@ -22,6 +25,39 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   return [prose, component].filter(Boolean).join('\n\n');
 }
 
+interface InjectedRule {
+  selector: string;
+  text: string;
+  media: string | null;
+}
+
+/**
+ * Every style rule StyleX has injected at runtime (`runtimeInjection` in the
+ * root vitest config), flattened out of any at-rule wrapper and tagged with
+ * that wrapper's condition — so a `@media (pointer: coarse)` rule stays
+ * distinguishable from the unconditional one.
+ */
+function injectedRules(): InjectedRule[] {
+  const walk = (rules: CSSRuleList, condition: string | null) =>
+    [...rules].flatMap((rule): InjectedRule[] => {
+      const {selectorText} = rule as CSSStyleRule;
+      if (typeof selectorText === 'string') {
+        return [{selector: selectorText, text: rule.cssText, media: condition}];
+      }
+      // A grouping rule (@media, @keyframes, ...): descend, carrying the
+      // innermost condition down. jsdom hangs an empty `cssRules` off plain
+      // style rules too, which is why the leaf check comes first.
+      const nested = (rule as CSSGroupingRule).cssRules;
+      if (nested == null) {
+        return [];
+      }
+      const own = (rule as CSSMediaRule).media?.mediaText;
+      return walk(nested, own != null && own !== '' ? own : condition);
+    });
+
+  return [...document.styleSheets].flatMap(sheet => walk(sheet.cssRules, null));
+}
+
 const getGlyph = (): HTMLElement => {
   const button = screen.getByRole('button', {name: 'Clear'});
   const icon = button.querySelector('.astryx-icon');
@@ -111,7 +147,103 @@ describe('InputClearButton', () => {
     const css = generateThemeTestCSS(theme);
     expect(css).toContain('.astryx-input-clear-icon {');
     expect(css).toContain('width: 12px');
-    expect(css).toContain('.astryx-input-clear-icon:hover {');
+    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('grows the hit area to 24px on a coarse pointer only (WCAG 2.5.8 AA)', () => {
+    // The visual glyph stays 20px; an ::after overlay expands only the
+    // tappable region, and only under a coarse pointer. Asserted against the
+    // CSS StyleX injects at runtime, because jsdom resolves neither media
+    // queries nor pseudo-element boxes.
+    render(<InputClearButton label="Clear" onClick={() => {}} />);
+    const button = screen.getByRole('button', {name: 'Clear'});
+    const classes = new Set(button.className.split(' ').filter(Boolean));
+
+    const css = injectedRules();
+    const rulesForButton = css.filter(({selector}) =>
+      [...classes].some(c => selector.includes(`.${c}`)),
+    );
+    // Guards every assertion below against silently passing if StyleX's
+    // runtime injection or the class plumbing ever changes shape.
+    expect(rulesForButton.length).toBeGreaterThan(0);
+
+    const decl = (pattern: RegExp, inMedia?: string) =>
+      rulesForButton.some(
+        ({text, media}) =>
+          pattern.test(text) &&
+          (inMedia == null ? media == null : (media ?? '').includes(inMedia)),
+      );
+
+    // Fine pointer: hit area == the 20px visual glyph, no expansion.
+    expect(decl(/--_input-clear-hit-inset\s*:\s*0px/)).toBe(true);
+    // Coarse pointer: 20px + 2px on each side = 24x24, the AA floor.
+    expect(decl(/--_input-clear-hit-inset\s*:\s*-2px/, 'pointer: coarse')).toBe(
+      true,
+    );
+    // ...and nothing wider than that, which would reach into the adornment
+    // gap and the input's caret area. Scoped to the coarse block, because
+    // that is the only place a wider value can appear.
+    expect(
+      decl(
+        /--_input-clear-hit-inset\s*:\s*-(?:[3-9]|\d{2,})px/,
+        'pointer: coarse',
+      ),
+    ).toBe(false);
+    // The overlay exists only on touch. On a fine pointer a generated
+    // ::after would cover the button and take hover away from the glyph
+    // target, so `content` is gated the same way the inset is.
+    expect(decl(/--_input-clear-hit-content\s*:\s*none/)).toBe(true);
+    expect(decl(/--_input-clear-hit-content\s*:\s*""/, 'pointer: coarse')).toBe(
+      true,
+    );
+    // The overlay itself is what carries the expansion, and what is gated.
+    expect(
+      decl(/::after\s*\{[^}]*inset\s*:\s*var\(--_input-clear-hit-inset\)/),
+    ).toBe(true);
+    expect(
+      decl(/::after\s*\{[^}]*content\s*:\s*var\(--_input-clear-hit-content\)/),
+    ).toBe(true);
+  });
+
+  it('declares its own containing block for the hit overlay', () => {
+    // The ::after overlay must resolve against this button. Button happens to
+    // set `position: relative` on itself, so at runtime the overlay is
+    // correctly placed either way — and StyleX compiles both declarations to
+    // the same atomic class, so the rendered CSS cannot tell the two apart.
+    // Assert on the source instead, so a future edit can't quietly leave the
+    // overlay depending on another component's internal.
+    const source = readFileSync(
+      path.resolve(__dirname, './InputClearButton.tsx'),
+      'utf-8',
+    );
+    const buttonStyle = source.match(/button:\s*\{[\s\S]*?\n {2}\},/)?.[0];
+    expect(buttonStyle).toBeDefined();
+    expect(buttonStyle).toMatch(/position:\s*'relative'/);
+  });
+
+  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';
@@ -24,6 +25,44 @@ const styles = stylex.create({
   button: {
     height: '20px',
     flexShrink: 0,
+    // Containing block for the ::after hit overlay below. Button sets its own
+    // `position: relative`, so the overlay would resolve correctly without
+    // this — but that is another component's internal, and if it ever changes
+    // the overlay silently reattaches to some ancestor and the hit area lands
+    // in the wrong place. Declaring it here keeps the containing block
+    // colocated with the thing that depends on it. No-op at runtime.
+    position: 'relative',
+    // Expand the tap target to 24px ONLY on touch (WCAG 2.5.8 AA is a touch
+    // requirement, and its floor is 24x24). On a fine pointer the 20px glyph
+    // is precise enough, and an unconditional overlay could overlap
+    // neighboring controls in dense layouts. The inset is 0 by default (hit
+    // area == visual glyph) and grows to -2px (=> 24x24) under a coarse
+    // pointer — no further, because at -4px the overlay reaches into the 8px
+    // adornment gap and, on the inline-start side, over the input's own caret
+    // area. Driven through a custom property because StyleX only allows plain
+    // values inside a pseudo-element; the conditional lives on this top-level
+    // property instead. Private (--_) because it is an internal implementation
+    // detail, not a themeable target.
+    '--_input-clear-hit-inset': {
+      default: '0px',
+      '@media (pointer: coarse)': '-2px',
+    },
+    // The overlay itself is gated too, not just its size. An ::after that is
+    // generated on a fine pointer sits exactly over the button at inset 0,
+    // where it adds no hit area but is the topmost hit-test box — so hover
+    // stops reaching the descendants and `.astryx-input-clear-icon:hover`, a
+    // public theme target, no longer matches. `content: none` means the
+    // pseudo-element is not generated at all, so on a fine pointer the
+    // overlay does not exist.
+    '--_input-clear-hit-content': {
+      default: 'none',
+      '@media (pointer: coarse)': '""',
+    },
+    '::after': {
+      content: 'var(--_input-clear-hit-content)',
+      position: 'absolute',
+      inset: 'var(--_input-clear-hit-inset)',
+    },
   },
 });
 
@@ -48,11 +87,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/Field/inputStyles.stylex.ts

@@ -56,9 +56,10 @@ export const inputWrapperStyles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': `inset 0px 0px 0px 2px color-mix(in srgb, ${colorVars['--color-border-emphasized']} 30%, transparent)`,
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': `inset 0px 0px 0px 2px color-mix(in srgb, ${colorVars['--color-border-emphasized']} 30%, transparent)`,
+        },
       ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
     },
     outline: 'none',
@@ -96,25 +97,28 @@ export const inputStatusHoverShadowStyles = stylex.create({
   warning: {
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': shadowVars['--shadow-inset-warning'],
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': shadowVars['--shadow-inset-warning'],
+        },
     },
   },
   error: {
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': shadowVars['--shadow-inset-error'],
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': shadowVars['--shadow-inset-error'],
+        },
     },
   },
   success: {
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': shadowVars['--shadow-inset-success'],
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': shadowVars['--shadow-inset-success'],
+        },
     },
   },
 });

package/src/FileInput/FileInput.tsx

@@ -158,7 +158,7 @@ const styles = stylex.create({
   dropzoneHover: {
     boxShadow: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `inset 0 0 0 2px color-mix(in srgb, ${colorVars['--color-accent']} 20%, transparent)`,
       },
     },
@@ -197,9 +197,10 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': `inset 0 0 0 2px color-mix(in srgb, ${colorVars['--color-accent']} 20%, transparent)`,
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': `inset 0 0 0 2px color-mix(in srgb, ${colorVars['--color-accent']} 20%, transparent)`,
+        },
     },
     cursor: 'pointer',
     height: sizeVars['--size-element-md'],

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

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

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