@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/DateTimeInput/DateTimeInput.tsx

@@ -17,6 +17,7 @@
  */
 
 import {
+  use,
   useId,
   useState,
   useCallback,
@@ -84,10 +85,11 @@ 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';
-import {useTranslator} from '../i18n';
+import {useTranslator, InternationalizationContext} from '../i18n';
 
 export type ISODateTimeString = string & {
   readonly __brand: 'ISODateTimeString';
@@ -448,6 +450,8 @@ export function DateTimeInput({
   ...rest
 }: DateTimeInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+  const {locale} = use(InternationalizationContext);
   // 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).
@@ -558,13 +562,17 @@ export function DateTimeInput({
     datePendingInput !== null
       ? datePendingInput
       : valueParts.date && /^\d{4}-\d{2}-\d{2}$/.test(valueParts.date)
-        ? plainDateFormat(plainDateFromISO(valueParts.date), DATE_FORMAT_LONG)
+        ? plainDateFormat(
+            plainDateFromISO(valueParts.date),
+            DATE_FORMAT_LONG,
+            locale,
+          )
         : '';
 
   const isDateInputValid =
     datePendingInput === null || !datePendingInput.trim()
       ? true
-      : parseDateInput(datePendingInput) !== null;
+      : parseDateInput(datePendingInput, locale) !== null;
 
   // --- Time input state ---
   const [timePendingInput, setTimePendingInput] = useState<string | null>(null);
@@ -692,7 +700,7 @@ export function DateTimeInput({
       const text = e.target.value;
       setDatePendingInput(text);
 
-      const parsed = parseDateInput(text);
+      const parsed = parseDateInput(text, locale);
       if (
         parsed &&
         plainDateToISO(parsed) !== valueParts.date &&
@@ -704,7 +712,13 @@ export function DateTimeInput({
         calendarRef.current?.navigateTo(parsedISO);
       }
     },
-    [valueParts.date, isDateDisabled, handleDateChange, isEffectivelyDisabled],
+    [
+      valueParts.date,
+      isDateDisabled,
+      handleDateChange,
+      isEffectivelyDisabled,
+      locale,
+    ],
   );
 
   const commitDatePendingInput = useCallback(() => {
@@ -720,7 +734,7 @@ export function DateTimeInput({
       return;
     }
 
-    const parsed = parseDateInput(datePendingInput);
+    const parsed = parseDateInput(datePendingInput, locale);
     if (parsed && !isDateDisabled(parsed)) {
       const parsedISO = plainDateToISO(parsed);
       if (parsedISO !== valueParts.date) {
@@ -735,6 +749,7 @@ export function DateTimeInput({
     fireChange,
     isDateDisabled,
     handleDateChange,
+    locale,
   ]);
 
   const handleDateBlur = useCallback(() => {
@@ -1009,7 +1024,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 +1113,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/Dialog/Dialog.test.tsx

@@ -461,4 +461,28 @@ describe('Dialog', () => {
       before.remove();
     });
   });
+
+  describe('container padding isolation', () => {
+    it('resets container padding custom properties on the root dialog element', () => {
+      render(
+        <Dialog isOpen={true} onOpenChange={() => {}}>
+          Content
+        </Dialog>,
+      );
+      const dialog = screen.getByRole('dialog');
+      const computed = window.getComputedStyle(dialog);
+      expect(
+        computed.getPropertyValue('--container-padding-inline-start'),
+      ).toBe('0px');
+      expect(computed.getPropertyValue('--container-padding-inline-end')).toBe(
+        '0px',
+      );
+      expect(computed.getPropertyValue('--container-padding-block-start')).toBe(
+        '0px',
+      );
+      expect(computed.getPropertyValue('--container-padding-block-end')).toBe(
+        '0px',
+      );
+    });
+  });
 });

package/src/Dialog/Dialog.tsx

@@ -44,6 +44,7 @@ import {
   containerPaddingBlockStartVarStyles,
   containerPaddingBlockEndVarStyles,
   spacingStepToToken,
+  overlayPaddingReset,
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
@@ -610,6 +611,7 @@ export function Dialog({
           themeProps('dialog', {variant}),
           stylex.props(
             styles.inlineWrapper,
+            overlayPaddingReset.reset,
             !isFullscreen && dynamicStyles.sizing(width, maxHeight),
             isFullscreen && styles.fullscreen,
             xstyle,
@@ -636,6 +638,7 @@ export function Dialog({
         themeProps('dialog', {variant}),
         focusOutlineProps.focusVisible(
           styles.dialog,
+          overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
           !isFullscreen && dynamicStyles.sizing(width, maxHeight),

package/src/Field/Field.doc.mjs

@@ -34,10 +34,13 @@ export const docs = {
         className: 'astryx-input-status-icon',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-input-clear-button'},
       {className: 'astryx-input-clear-icon'},
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},
+      {name: '--_input-clear-hit-inset', description: 'Outset of the clear (\u2715) button\u2019s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
+      {name: '--_input-clear-hit-content', description: 'Whether the clear (\u2715) button\u2019s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the glyph; `""` on a coarse one, where the overlay provides the 24px touch target.', default: 'none', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_field-radius']},

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

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