@astryxdesign/core 0.7.7 → 0.7.8-canary.30b1896

package/src/ComplexSelector/ComplexSelector.tsx

@@ -35,6 +35,7 @@ import {
 } from '../Field/fieldParts';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {mergeRefs} from '../utils/mergeRefs';
+import {isFocusLost} from '../utils/focusReturn';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {Field, inputWrapperStyles} from '../Field';
@@ -347,7 +348,10 @@ export interface ComplexSelectorRenderState {
 export interface ComplexSelectorHandle {
   /** Open the selector surface. No-op when disabled or already open. */
   open(): void;
-  /** Close the selector surface. Restores focus to the trigger. */
+  /**
+   * Close the selector surface. Focus returns to the trigger only when it
+   * would otherwise be lost; a caller-rendered trigger always gets it back.
+   */
   close(): void;
   /** Toggle the selector surface open or closed. */
   toggle(): void;
@@ -630,12 +634,22 @@ export function ComplexSelector<Value>({
     onOpenChange?.(true);
   }, [onOpenChange]);
 
+  // The popup's content element, read when it closes.
+  const popupContentRef = useRef<HTMLElement | null>(null);
+  const hasCallerTrigger = renderTrigger != null;
   const handlePopoverHide = useCallback(() => {
-    // Focus is restored first so a consumer that moves focus elsewhere from
-    // the callback wins, instead of being overwritten a line later.
-    triggerRef.current?.focus();
+    const trigger = triggerRef.current;
+    // A press that moved focus to another control keeps it there. A caller's
+    // control always gets focus back. Focus moves before the callback, so a
+    // consumer that moves it from the callback wins.
+    if (
+      hasCallerTrigger ||
+      isFocusLost(popupContentRef.current, trigger?.ownerDocument)
+    ) {
+      trigger?.focus();
+    }
     onOpenChange?.(false);
-  }, [onOpenChange]);
+  }, [hasCallerTrigger, onOpenChange]);
 
   const popover = usePopover({
     dialogLabel: label,
@@ -645,6 +659,7 @@ export function ComplexSelector<Value>({
     onShow: handlePopoverShow,
     onHide: handlePopoverHide,
   });
+  popupContentRef.current = popover.contentRef.current;
 
   const isOpen = popover.isOpen;
 

package/src/ContextMenu/ContextMenu.tsx

@@ -712,14 +712,14 @@ export function ContextMenu({
   );
   const handleTriggerTouchEnd = useCallback(
     (event: React.TouchEvent<HTMLElement>) => {
-      handleLongPressTouchEnd();
+      handleLongPressTouchEnd(event);
       onTouchEndProp?.(event);
     },
     [handleLongPressTouchEnd, onTouchEndProp],
   );
   const handleTriggerTouchCancel = useCallback(
     (event: React.TouchEvent<HTMLElement>) => {
-      handleLongPressTouchCancel();
+      handleLongPressTouchCancel(event);
       onTouchCancelProp?.(event);
     },
     [handleLongPressTouchCancel, onTouchCancelProp],

package/src/DateInput/MonthScroller.tsx

@@ -51,7 +51,10 @@ import {
   borderVars,
 } from '../theme/tokens.stylex';
 import {focusOutlineStyles} from '../utils';
-import {plainDateFormatStandaloneMonthYear} from '../utils/plainDate';
+import {
+  plainDateFormatDayNumber,
+  plainDateFormatStandaloneMonthYear,
+} from '../utils/plainDate';
 import {
   type DayOfWeek,
   type ISODateString,
@@ -591,6 +594,7 @@ export function MonthScroller({
    * it cannot oscillate.
    */
   const settleFrameRef = useRef<number | undefined>(undefined);
+  // Releases the settle frame on unmount.
   useEffect(
     () => () => {
       if (settleFrameRef.current != null) {
@@ -663,6 +667,8 @@ export function MonthScroller({
   // rAF-throttled: a touch scroll fires far more scroll events than frames,
   // and all this does is move a label and widen a window.
   const frameRef = useRef<number | undefined>(undefined);
+  // Syncs scroll, touch and wheel listeners on the scroller with its measured
+  // height.
   useEffect(() => {
     const scroller = scrollerRef.current;
     // Not before the height is known. A listener attached while it was zero
@@ -1012,7 +1018,7 @@ function MonthPane({
                       isToday && styles.puckToday,
                       isSelected && styles.puckSelected,
                     )}>
-                    {day.dayNumber}
+                    {plainDateFormatDayNumber(day.dayNumber, locale)}
                   </span>
                 </button>
               </div>

package/src/DateInput/TouchDateField.tsx

@@ -676,6 +676,7 @@ export function TouchDateField({
   const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
   // Pending focus handoff from the clear button; see handleClear.
   const clearFocusTimerRef = useRef<number | null>(null);
+  // Releases the focus timer on unmount.
   useEffect(
     () => () => {
       if (clearFocusTimerRef.current != null) {

package/src/DateInput/Wheel.tsx

@@ -462,6 +462,8 @@ export function Wheel({
   // useScrollSettle. The settle handler re-checks the position afterwards, so
   // a correction that is genuinely needed still happens, just at rest.
   const parkedRef = useRef(false);
+  // Syncs the wheel's scroll position with the selected index while the wheel
+  // is active.
   useEffect(() => {
     if (!isActive) {
       parkedRef.current = false;
@@ -492,6 +494,8 @@ export function Wheel({
   // Highlight follows the finger. rAF-throttled: a scroll can fire far more
   // often than the display refreshes, and this only feeds a repaint.
   const frameRef = useRef<number | undefined>(undefined);
+  // Syncs a scroll listener with the active wheel. It updates the highlighted
+  // row.
   useEffect(() => {
     const scroller = scrollerRef.current;
     if (scroller == null || !isActive) {

package/src/DateInput/useOwnScrollGesture.ts

@@ -137,6 +137,8 @@ export function useOwnScrollGesture(
   const onSwipeRef = useRef(onSwipe);
   onSwipeRef.current = onSwipe;
 
+  // Syncs touch listeners on the element with `isEnabled`. They decide which
+  // gesture owns a horizontal scroll.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {

package/src/DateInput/usePointerDragScroll.ts

@@ -87,6 +87,7 @@ export function usePointerDragScroll(
 ): PointerDragScrollState {
   const isDraggingRef = useRef(false);
 
+  // Syncs pointer listeners with `isEnabled`. A mouse drag scrolls the element.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {

package/src/DateInput/useScrollSettle.ts

@@ -98,6 +98,8 @@ export function useScrollSettle(
 
   const isAtRestRef = useRef(true);
 
+  // Syncs scroll, touch and pointer listeners with `isEnabled`. They find when
+  // scrolling stops.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {

package/src/Dialog/Dialog.tsx

@@ -81,7 +81,10 @@ import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
-import {focusForLastInput, isFocusLost} from '../utils/focusReturn';
+import {
+  focusForLastInput,
+  prepareFocusReturnOnRemoval,
+} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -603,7 +606,8 @@ export function Dialog({
   const allowEscape = purpose !== 'required';
   const allowBackdropClick = purpose === 'info';
 
-  // Handle open/close state — skip for inline rendering
+  // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
+  // An inline dialog is not in the top layer, so it skips this.
   useEffect(() => {
     if (isInline) {
       return;
@@ -653,39 +657,15 @@ export function Dialog({
   }, [isOpen, isInline]);
 
   // A dialog that unmounts while open (rendered only while open, or removed
-  // with the rest of a view) never runs the close branch above, and removing a
-  // <dialog> does not run the browser's own focus return. Focus left inside
-  // it, or dropped to the body by the removal, goes back to the opener.
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener.
   useEffect(() => {
-    if (isInline) {
+    const dialog = dialogRef.current;
+    if (isInline || dialog == null) {
       return;
     }
-    const dialog = dialogRef.current;
-    // Read now: a removed iframe's document has no window, so its frame
-    // element can no longer be found once the dialog is gone.
-    const host = dialog?.ownerDocument.defaultView?.frameElement ?? null;
-    return () => {
-      const trigger = triggerElementRef.current;
-      if (dialog == null || trigger == null) {
-        return;
-      }
-      // Checked once the commit has finished: StrictMode's simulated unmount
-      // leaves the dialog in the document, and only a real removal returns
-      // focus.
-      queueMicrotask(() => {
-        if (dialog.isConnected || !trigger.isConnected) {
-          return;
-        }
-        // isFocusLost reads the dialog's own document. For a dialog in an
-        // iframe, the document that hosts the frame must also have lost focus
-        // or keep it on that frame, wherever the opener is: a control the
-        // user pressed outside the frame to remove the dialog, or the frame
-        // itself, keeps its focus.
-        if (isFocusLost(dialog) && (host == null || isFocusLost(host))) {
-          focusForLastInput(trigger);
-        }
-      });
-    };
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => returnFocusOnRemoval(triggerElementRef.current);
   }, [isInline]);
 
   // Host app-global surfaces (toasts) inside this modal while it is open, so

package/src/Drawer/useDrawerDialogPresence.ts

@@ -131,6 +131,8 @@ export function useDrawerDialogPresence({
   // Element focused when the drawer opened — restored on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
 
+  // Syncs the drawer's native host with `isOpen`. It shows or hides the
+  // top-layer host, keeps the opener, waits for the exit, and returns focus.
   useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) {

package/src/DropdownMenu/useMenuOverflow.ts

@@ -63,6 +63,8 @@ export function useMenuOverflow(
     );
   }, [menuRef]);
 
+  // Syncs the overflow measurement with the open menu. It measures, then
+  // observes resize, DOM changes and window resize.
   useIsomorphicLayoutEffect(() => {
     if (!isOpen) {
       return;
@@ -98,6 +100,7 @@ export function useMenuOverflow(
     };
   }, [isOpen, measureOverflow, menuRef]);
 
+  // Measures overflow again after the content changes while the menu is open.
   useIsomorphicLayoutEffect(() => {
     if (isOpen) {
       measureOverflow();

package/src/Field/Field.tsx

@@ -25,11 +25,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 import type {FieldStatusPlacement} from './fieldStatusPlacement';
 

package/src/FieldStatus/useFieldStatusAnnouncement.ts

@@ -36,6 +36,7 @@ export function useFieldStatusAnnouncement(
   type: InputStatusType | undefined,
 ): void {
   const announce = useAnnounce();
+  // Syncs the live region with the status message.
   useEffect(() => {
     if (message) {
       announce(message, type === 'error' ? 'assertive' : 'polite');

package/src/FormLayout/FormLayout.doc.mjs

@@ -7,7 +7,16 @@ export const docs = {
   displayName: 'Form Layout',
   group: 'Layout',
   category: 'Layout',
-  keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],
+  keywords: [
+    'formlayout',
+    'form',
+    'fieldset',
+    'formgroup',
+    'formcontainer',
+    'fields',
+    'vertical',
+    'horizontal',
+  ],
   props: [
     {
       name: 'direction',
@@ -20,7 +29,7 @@ export const docs = {
       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.',
+        '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. CheckboxInput, Switch and CheckboxList are the exception: an unchecked box, an off switch or an empty group is an answer, so they take no required state from the default. A CheckboxInput or Switch is required only through its own isRequired. Leave unset for today\'s per-field behavior.',
     },
     {
       name: 'children',
@@ -36,25 +45,65 @@ export const docs = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-form-layout', visualProps: ['direction']},
-    ],
+    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
   },
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
 };
@@ -75,7 +124,7 @@ export const docsZh = {
       name: 'defaultOptionality',
       type: "'optional' | 'required'",
       description:
-        '表单视为默认的状态，因此仅例外字段显示可选/必填指示器。设为 "optional" 时，仅标记 isRequired 的字段显示指示器；设为 "required" 时，仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时，未标记的字段仍会暴露 aria-required，使屏幕阅读器与视觉默认一致——仅作用于 aria-required，不改变原生 required 属性。不设置则保持当前逐字段行为。',
+        '表单视为默认的状态，因此仅例外字段显示可选/必填指示器。设为 "optional" 时，仅标记 isRequired 的字段显示指示器；设为 "required" 时，仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时，未标记的字段仍会暴露 aria-required，使屏幕阅读器与视觉默认一致——仅作用于 aria-required，不改变原生 required 属性。CheckboxInput、Switch 和 CheckboxList 例外：未勾选的复选框、关闭的开关或空的复选框组本身就是一个回答，因此默认值不会赋予它们必填状态。CheckboxInput 或 Switch 只有通过自身的 isRequired 才会成为必填。不设置则保持当前逐字段行为。',
     },
     {
       name: 'children',
@@ -91,25 +140,65 @@ export const docsZh = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-form-layout', visualProps: ['direction']},
-    ],
+    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
   },
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
 };
@@ -119,26 +208,72 @@ export const docsDense = {
   description:
     'Layout container for form fields w/ consistent spacing + direction.',
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
   propDescriptions: {
-    direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=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.',
+    direction:
+      'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=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), except CheckboxInput, Switch and CheckboxList, which take no required state from it (CheckboxInput and Switch are required only through their own isRequired). 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.tsx

@@ -103,7 +103,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    *   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.
+   *   expose `aria-required` even though they show no indicator. Checkboxes,
+   *   switches and checkbox groups are the exception: an unchecked box, an off
+   *   switch or an empty group is an answer, so they take no required state
+   *   from the default. A checkbox or switch is required only through its own
+   *   `isRequired`.
    * - unset — today's behavior: `isRequired` and `isOptional` each show their
    *   own indicator independently.
    *