@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/Field/FieldLabel.spec.md

@@ -15,6 +15,7 @@ verified_by:
     packages/core/src/Field/FieldLabel.test.tsx,
     packages/core/src/FormLayout/FormLayout.test.tsx,
     packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts,
+    packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts,
     packages/core/src/theme/themingTargets.test.ts,
     packages/core/src/docPropReferences.test.ts,
     packages/core/src/docPropLiterals.test.ts,
@@ -37,15 +38,15 @@ system_specs: [spec:AST-020/FR1]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref.                  |
-| Behavior                | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control.          |
-| End-user impact         | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. The current tooltip remains unavailable to keyboard and screen-reader users.    |
-| Builder impact          | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface.                                                              |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
-| Review checks           | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop.    |
-| Governing rules         | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`.                          |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref.                                                                                             |
+| Behavior                | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control.                                                                                     |
+| End-user impact         | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area; a tap on the tooltip's info icon opens or closes the tooltip instead (DEC-1). The current tooltip remains unavailable to keyboard and screen-reader users. |
+| Builder impact          | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface.                                                                                                                                         |
+| Compatibility/readiness | Records shipped behavior and DEC-1; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact.                                                                  |
+| Review checks           | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop.                                                                               |
+| Governing rules         | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`.                                                                                                     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -56,9 +57,9 @@ This table is a review projection; the body below is authoritative.
 ## Compatibility and migration
 
 - Released default preserved: yes.
-- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change.
+- Compatibility class: records shipped behavior and DEC-1; no public prop, default, export, or DOM change.
 - Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none; the ref typing is OQ1.
+- Migration decision: DEC-1 needs no caller change; the ref typing is OQ1.
 
 ## Ownership boundary
 
@@ -79,15 +80,15 @@ This table is a review projection; the body below is authoritative.
 
 ## Public concepts
 
-| Concept                | Closed values or states                         | Meaning                                                                                   | Availability by variant/orientation/state | Default        | Owner                  | Stability | Invalid-value behavior                                                                                                               |
-| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| label mode             | single control; group                           | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`.    | All uses.                                 | single control | `component:FieldLabel` | released  | Boolean-constrained; see OQ1 for root/ref typing.                                                                                    |
-| label visibility       | visible; visually hidden                        | Keeps label and description accessible while removing their layout space when hidden.     | Both label modes.                         | visible        | `component:FieldLabel` | released  | Boolean-constrained.                                                                                                                 |
-| optionality marker     | none; optional; required                        | Shows the localized exception to FormLayout's form-level optionality default.             | Visible and hidden labels.                | none           | `component:FieldLabel` | released  | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
-| leading icon           | absent; icon type; rendered node                | Adds visual content before the label text.                                                | Both label modes.                         | absent         | `component:FieldLabel` | released  | Rendered through the shared icon slot.                                                                                               |
-| explanatory tooltip    | absent; localized string                        | Adds the shared info-icon anchor and tooltip surface after the label.                     | Both label modes.                         | absent         | `component:FieldLabel` | released  | The anchor is pointer-only (FR8 gap).                                                                                                |
-| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes.                         | absent         | `component:FieldLabel` | released  | Missing ID leaves association to the caller.                                                                                         |
-| description activation | forwarding; non-forwarding                      | For one control, noninteractive description clicks mirror native-label activation.        | Single mode only.                         | forwarding     | `component:FieldLabel` | released  | Group mode and interactive descendants do not forward.                                                                               |
+| Concept                | Closed values or states                         | Meaning                                                                                                                                                   | Availability by variant/orientation/state | Default        | Owner                  | Stability | Invalid-value behavior                                                                                                               |
+| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| label mode             | single control; group                           | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`.                                                                    | All uses.                                 | single control | `component:FieldLabel` | released  | Boolean-constrained; see OQ1 for root/ref typing.                                                                                    |
+| label visibility       | visible; visually hidden                        | Keeps label and description accessible while removing their layout space when hidden.                                                                     | Both label modes.                         | visible        | `component:FieldLabel` | released  | Boolean-constrained.                                                                                                                 |
+| optionality marker     | none; optional; required                        | Shows the localized exception to FormLayout's form-level optionality default.                                                                             | Visible and hidden labels.                | none           | `component:FieldLabel` | released  | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| leading icon           | absent; icon type; rendered node                | Adds visual content before the label text.                                                                                                                | Both label modes.                         | absent         | `component:FieldLabel` | released  | Rendered through the shared icon slot.                                                                                               |
+| explanatory tooltip    | absent; localized string                        | Adds the shared info-icon anchor and tooltip surface after the label; a tap on the icon opens or closes the tooltip without activating the control (FR9). | Both label modes.                         | absent         | `component:FieldLabel` | released  | The anchor is pointer-only (FR8 gap).                                                                                                |
+| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description.                                                                 | Both label modes.                         | absent         | `component:FieldLabel` | released  | Missing ID leaves association to the caller.                                                                                         |
+| description activation | forwarding; non-forwarding                      | For one control, noninteractive description clicks mirror native-label activation.                                                                        | Single mode only.                         | forwarding     | `component:FieldLabel` | released  | Group mode and interactive descendants do not forward.                                                                               |
 
 ## Behavioral and layout contract
 
@@ -101,6 +102,7 @@ This table is a review projection; the body below is authoritative.
 | FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element.                               | `architecture:public-component-api/INV5–INV7`                        |
 | FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`.                  | `architecture:public-component-api/INV8,INV9`; current runtime/types |
 | FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2). Implementation gap: it anchors to an anonymous, nonfocusable info icon, so the content is pointer-only.                           | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1`                      |
+| FR9 | A tap on the tooltip's info icon, by finger or pen, opens or closes the tooltip as `component:Tooltip` FR5 states under `touchTrigger="tap"`, and does not activate the associated control. A mouse click on the icon activates the control like the rest of the label, and hover shows the tooltip.      | DEC-1                                                                |
 
 ### Allowed variation
 
@@ -157,6 +159,7 @@ No current repository design record governs component-local visual tuning. The i
 | FR6, ORD2         | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts`                                                                                         | Ref; composed target; with a description wrapper          | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper. | `audit:FieldLabel/api`           |
 | FR7               | Evidence gap: no type test pins the public ref and props against the rendered group span                                                                                         | —                                                         | —                                                                                                                                                                                                                                                        | `audit:FieldLabel/api`           |
 | FR8, AR5          | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count                                                                                                                     | Tooltip present                                           | The audit records the one anonymous, nonfocusable anchor; it changes when the FR8 gap closes.                                                                                                                                                            | `audit:FieldLabel/accessibility` |
+| FR9               | `FieldLabel.test.tsx` finger-tap, pen-tap, and mouse-click checkbox cases; `FieldLabelTap.a11y.chromium.spec.ts` touch-tap and mouse-click text-field cases                      | Checkbox; text field                                      | A tap that toggles or focuses the control, or a mouse click that does not activate it, fails.                                                                                                                                                            | `audit:FieldLabel/accessibility` |
 | PR1               | Evidence gap: no test asserts the absence of retained resources                                                                                                                  | —                                                         | —                                                                                                                                                                                                                                                        | `audit:FieldLabel/code-health`   |
 | Documentation     | `docPropLiterals.test.ts`; `docPropReferences.test.ts`                                                                                                                           | Documented props and defaults                             | A documented literal or prop reference that drifts from the source type fails.                                                                                                                                                                           | `audit:FieldLabel/docs`          |
 | RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel`                                                                                              | Checked-in FieldLabel stories                             | A story that gains directional placement or behavior makes the not-applicable entry stale.                                                                                                                                                               | `audit:FieldLabel/i18n-rtl`      |
@@ -171,7 +174,13 @@ No current repository design record governs component-local visual tuning. The i
 
 ## Decision log
 
-No component-local decision. The label-element and ref typing is OQ1.
+- **DEC-1 — A tap on the info icon is for its help.** A tap on the
+  tooltip's info icon, by finger or pen, opens or closes the tooltip and does not
+  activate the label's control, so asking for help never toggles a switch or
+  focuses a field. A mouse click on the icon keeps native label activation,
+  and hover shows the help. Rejected: leaving the tap to the label.
+
+The label-element and ref typing is OQ1.
 
 ## Open questions
 

package/src/Field/FieldLabel.tsx

@@ -16,10 +16,18 @@
  * - /packages/core/locales/en.json (@astryx.field.required / @astryx.field.optional)
  */
 
-import {use, useMemo, useRef, type ReactNode, type RefObject} from 'react';
+import {
+  use,
+  useMemo,
+  useRef,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+  type RefObject,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 
 import {
   colorVars,
@@ -28,9 +36,11 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
-import {Tooltip} from '../Tooltip';
-import {useTranslator} from '../i18n';
+import {Icon, renderIconSlot} from '../Icon/Icon';
+import type {IconType} from '../Icon';
+import {Tooltip} from '../Tooltip/Tooltip';
+import {TOUCH_POINTER_TYPES} from '../Layer/useTouchTrigger';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
@@ -255,6 +265,22 @@ export function FieldLabel({
   // a ref-shaped object, since FieldLabel points at the control by id rather
   // than holding a ref to it.
   const descriptionRef = useRef<HTMLSpanElement>(null);
+  // A tap on the info icon asks for the help, so it stops there: it does not
+  // go on to activate the label's control, as a press anywhere else on the
+  // label would (focus the field, toggle a switch). A mouse click on the icon
+  // keeps that native activation, and hover shows the help.
+  const iconPressIsTapRef = useRef(false);
+  const handleIconPointerDown = (event: PointerEvent<Element>) => {
+    // A finger or a pen: the pointers whose tap the shared touch trigger
+    // answers, so the ones whose tap opens or closes the help.
+    iconPressIsTapRef.current = TOUCH_POINTER_TYPES.has(event.pointerType);
+  };
+  const handleIconClick = (event: MouseEvent<Element>) => {
+    if (iconPressIsTapRef.current) {
+      event.preventDefault();
+    }
+    iconPressIsTapRef.current = false;
+  };
   const controlRef = useMemo<RefObject<HTMLElement | null>>(
     () => ({
       get current() {
@@ -284,8 +310,17 @@ export function FieldLabel({
         </span>
       )}
       {labelTooltip && (
-        <Tooltip content={labelTooltip} placement="above">
-          <Icon icon="info" size="sm" color="inherit" />
+        // The icon's one job is to reveal the help, so a tap on it opens or
+        // closes the help (`touchTrigger="tap"`), although it sits inside a
+        // `<label>`.
+        <Tooltip content={labelTooltip} placement="above" touchTrigger="tap">
+          <Icon
+            icon="info"
+            size="sm"
+            color="inherit"
+            onPointerDown={handleIconPointerDown}
+            onClick={handleIconClick}
+          />
         </Tooltip>
       )}
     </>

package/src/Field/InputClearButton.tsx

@@ -18,9 +18,9 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Button} from '../Button';
-import {Icon} from '../Icon';
-import {useTranslator} from '../i18n';
+import {Button} from '../Button/Button';
+import {Icon} from '../Icon/Icon';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({

package/src/Field/PanelSearchInput.tsx

@@ -42,9 +42,9 @@
 import {useCallback, useState, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {Icon} from '../Icon';
+import {Icon} from '../Icon/Icon';
 import {InputClearButton} from './InputClearButton';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {
   getInteractionModality,
   useInteractionModalityTracking,

package/src/FieldStatus/FieldStatus.tsx

@@ -20,7 +20,7 @@
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {
   colorVars,
   radiusVars,
@@ -31,7 +31,7 @@ import {
 import type {InputStatusType} from '../Field/types';
 import {useEntryAnimation} from '../hooks/useEntryAnimation';
 import {themeProps} from '../utils/themeProps';
-import {Icon} from '../Icon';
+import {Icon} from '../Icon/Icon';
 import type {IconName} from '../Icon';
 import type {FieldStatusVariantMap} from './index';
 import {useFieldStatusAnnouncement} from './useFieldStatusAnnouncement';
@@ -63,6 +63,10 @@ const styles = stylex.create({
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
+    // A validation message often echoes the value that failed (an address, a
+    // URL). Let such an unbroken token wrap inside the field instead of
+    // painting past its edges (WCAG 2.2 SC 1.4.10 Reflow).
+    overflowWrap: 'anywhere',
   },
   attached: {
     marginTop: `calc(-1 * ${ATTACHED_OVERLAP})`,
@@ -118,6 +122,9 @@ const colorStyles = stylex.create({
 export type FieldStatusVariant = keyof FieldStatusVariantMap;
 
 export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
+  /**
+   * Ref to the rendered message box.
+   */
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The type of status to display.

package/src/FileInput/FileInput.tsx

@@ -68,6 +68,8 @@ import {useTranslator} from '../i18n';
 import type {TranslatorFn} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useListFormatter} from '../i18n/useListFormatter';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 function formatFileSize(bytes: number, t: TranslatorFn): string {
   if (bytes < 1024) {
     return t('@astryx.fileInput.fileSize.bytes', {size: bytes});
@@ -236,6 +238,10 @@ const styles = stylex.create({
       ':focus-within': colorVars['--color-accent'],
     },
   },
+  busy: {
+    cursor: 'default',
+    boxShadow: 'none',
+  },
   hiddenInput: {
     position: 'absolute',
     width: 1,
@@ -311,6 +317,9 @@ export interface FileInputProps extends Omit<
   FieldInputBaseProps,
   'onChange' | 'defaultValue' | 'value'
 > {
+  /**
+   * Ref to the native file input.
+   */
   ref?: React.Ref<HTMLInputElement>;
   /**
    * Accessible label for the file input.
@@ -491,9 +500,14 @@ export function FileInput({
   const containerRef = useRef<HTMLDivElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | null>(null);
+  const formatList = useListFormatter();
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
+  const isSelectionDisabled = isDisabled || isBusy;
+  if (isDragOver && isSelectionDisabled) {
+    setIsDragOver(false);
+  }
   // A pick is one user action, already announced as "file selected"; a busy
   // period it starts (changeAction, or a caller setting isLoading from
   // onChange) adds no second message (spec:AST-086 FR6). The mark lasts until
@@ -544,7 +558,9 @@ export function FileInput({
   // at a visually hidden "Required" span — mirroring the Field label's visible
   // indicator (where isOptional takes precedence) and the pattern Slider uses
   // for its thumbs.
-  const conveysRequired = isRequired && !isOptional;
+  // A surrounding FormLayout's defaultOptionality="required" makes an unmarked
+  // field required too (FormLayout FR5).
+  const conveysRequired = useResolvedRequired({isRequired, isOptional});
 
   const ariaDescribedBy =
     [
@@ -566,7 +582,7 @@ export function FileInput({
 
   const handleFiles = useCallback(
     (fileList: File[]) => {
-      if (isDisabled) {
+      if (isSelectionDisabled) {
         return;
       }
 
@@ -580,7 +596,9 @@ export function FileInput({
       );
 
       if (errors.length > 0) {
-        setValidationError(errors[0]);
+        // Every rejected file is identified, in one status message
+        // (WCAG 3.3.1), joined as a list in the active locale.
+        setValidationError(formatList(errors));
       } else {
         setValidationError(null);
       }
@@ -615,7 +633,7 @@ export function FileInput({
     },
     [
       accept,
-      isDisabled,
+      isSelectionDisabled,
       isMultiple,
       maxFiles,
       maxSize,
@@ -625,6 +643,7 @@ export function FileInput({
       setOptimisticValue,
       announce,
       t,
+      formatList,
     ],
   );
 
@@ -670,22 +689,24 @@ export function FileInput({
   );
 
   const handleClick = useCallback(() => {
-    if (!isDisabled) {
+    if (!isSelectionDisabled) {
       inputRef.current?.click();
     }
-  }, [isDisabled]);
+  }, [isSelectionDisabled]);
 
   // Explicit keyboard activation so Enter/Space open the picker even where a
-  // synthetic keydown does not raise a native click. The isDisabled guard
-  // blocks activation while focusable-disabled.
+  // synthetic keydown does not raise a native click. Disabled and busy triggers
+  // also cancel the default activation while remaining focusable.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
-      if ((e.key === 'Enter' || e.key === ' ') && !isDisabled) {
+      if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
-        inputRef.current?.click();
+        if (!isSelectionDisabled) {
+          inputRef.current?.click();
+        }
       }
     },
-    [isDisabled],
+    [isSelectionDisabled],
   );
 
   // Make the surface clickable without giving it an interactive role. Clicks on
@@ -695,29 +716,29 @@ export function FileInput({
     useClickableContainer({
       containerRef,
       onClick: handleClick,
-      disabled: isDisabled,
+      disabled: isSelectionDisabled,
     });
 
   const handleDragEnter = useCallback(
     (e: DragEvent) => {
       e.preventDefault();
       e.stopPropagation();
-      if (!isDisabled && mode === 'dropzone') {
+      if (!isSelectionDisabled && mode === 'dropzone') {
         setIsDragOver(true);
       }
     },
-    [isDisabled, mode],
+    [isSelectionDisabled, mode],
   );
 
   const handleDragOver = useCallback(
     (e: DragEvent) => {
       e.preventDefault();
       e.stopPropagation();
-      if (!isDisabled && mode === 'dropzone') {
+      if (!isSelectionDisabled && mode === 'dropzone') {
         setIsDragOver(true);
       }
     },
-    [isDisabled, mode],
+    [isSelectionDisabled, mode],
   );
 
   const handleDragLeave = useCallback((e: DragEvent) => {
@@ -740,7 +761,7 @@ export function FileInput({
       e.preventDefault();
       e.stopPropagation();
       setIsDragOver(false);
-      if (isDisabled || mode !== 'dropzone') {
+      if (isSelectionDisabled || mode !== 'dropzone') {
         return;
       }
       const fileList = Array.from(e.dataTransfer.files);
@@ -748,7 +769,7 @@ export function FileInput({
         handleFiles(fileList);
       }
     },
-    [isDisabled, mode, handleFiles],
+    [isSelectionDisabled, mode, handleFiles],
   );
 
   const hasFiles =
@@ -760,15 +781,30 @@ export function FileInput({
       : (optimisticValue?.name ?? '')
     : null;
 
+  // The tooltip placement renders no message box: its focusable status button
+  // is the only place the message lives, and the trigger's aria-describedby
+  // points at that button's tooltip. Every content branch that can show a
+  // status keeps it, so the message stays reachable in dropzone mode and while
+  // busy (family:input-fields FR8).
+  const tooltipStatus = statusTooltipDescribedBy != null ? statusIcon : null;
+
   const renderDropzoneContent = () => {
     if (isBusy) {
-      return <Spinner size="md" aria-hidden="true" />;
+      return (
+        <>
+          <Spinner size="md" aria-hidden="true" />
+          {tooltipStatus}
+        </>
+      );
     }
     if (hasFiles) {
       return (
-        <div {...stylex.props(styles.fileNameText, styles.fileNameDropzone)}>
-          {fileNames}
-        </div>
+        <>
+          <div {...stylex.props(styles.fileNameText, styles.fileNameDropzone)}>
+            {fileNames}
+          </div>
+          {tooltipStatus}
+        </>
       );
     }
     return (
@@ -782,6 +818,7 @@ export function FileInput({
         <span {...stylex.props(styles.placeholderText)}>
           {isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
         </span>
+        {tooltipStatus}
       </>
     );
   };
@@ -794,6 +831,7 @@ export function FileInput({
             {fileNames ?? displayPlaceholder}
           </span>
           <Spinner size="sm" aria-hidden="true" />
+          {tooltipStatus}
         </>
       );
     }
@@ -861,17 +899,21 @@ export function FileInput({
           // keyboard focus. Handlers are gated internally by isEnabled.
           disabledMessageTooltip.ref(el);
         }}
-        onClick={!isDisabled ? onContainerClick : undefined}
-        onMouseUp={!isDisabled ? onContainerMouseUp : undefined}
+        onClick={!isSelectionDisabled ? onContainerClick : undefined}
+        onMouseUp={!isSelectionDisabled ? onContainerMouseUp : undefined}
         {...dragDropProps}
         {...mergeProps(
           themeProps('file-input', {mode, status: status?.type ?? null}),
           stylex.props(
             isDropzone ? styles.dropzone : styles.compact,
-            isDropzone && !isDisabled && styles.dropzoneHover,
-            isDropzone && isDragOver && styles.dropzoneActive,
+            isDropzone && !isSelectionDisabled && styles.dropzoneHover,
+            isDropzone &&
+              !isSelectionDisabled &&
+              isDragOver &&
+              styles.dropzoneActive,
             isDropzone && isDisabled && styles.dropzoneDisabled,
             !isDropzone && isDisabled && styles.compactDisabled,
+            isBusy && styles.busy,
             status && statusBorderStyles[status.type],
             controlXstyle,
           ),
@@ -891,7 +933,7 @@ export function FileInput({
             type="button"
             // A disabled trigger keeps its Tab stop (spec:AST-085 FR1).
             tabIndex={0}
-            aria-disabled={isDisabled ? 'true' : undefined}
+            aria-disabled={isSelectionDisabled ? 'true' : undefined}
             onClick={handleClick}
             onKeyDown={handleKeyDown}
             // aria-label suppresses child content from the accessible name, so
@@ -919,8 +961,10 @@ export function FileInput({
           // submitted and `required` does not block submission (FR3).
           form={isDisabled ? '' : undefined}
           // A label or description click activates this input directly; cancel
-          // it so a disabled input never opens the picker (FR2).
-          onClick={isDisabled ? event => event.preventDefault() : rest.onClick}
+          // it so a disabled or busy input never opens the picker (FR2).
+          onClick={
+            isSelectionDisabled ? event => event.preventDefault() : rest.onClick
+          }
           onChange={handleInputChange}
           // The visually-hidden native input is never focused (tabIndex={-1});
           // its describedby/required/invalid live on the trigger button.

package/src/FormLayout/FormLayout.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-038]
 | Behavior                | Vertical stacks children; horizontal creates one fractional grid track per child in logical inline order; horizontal-labels pairs Field labels and controls, then collapses below a 481px viewport.                                |
 | End-user impact         | People encounter predictable field spacing and order, and assistive technology receives required-state information even when the form-wide visual convention leaves the common case unmarked.                                      |
 | Builder impact          | Builders supply the fields and any semantic `<form>`, title, or footer; nested layouts replace the outer direction and optionality context for their descendants.                                                                  |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or runtime changes. One implementation gap is listed under Current-state impact.                                                                                           |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or runtime changes.                                                                                                                                                        |
 | Review checks           | Reject lost root props, physical inline ordering, changed collapse boundaries, caller-overridable direction reflection, lost nested-context shadowing, or a visible optionality convention that disagrees with ARIA.               |
 | Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                     |
 
@@ -61,15 +61,6 @@ This table is a review projection; the body below is authoritative.
 - Controlled/uncontrolled behavior: not applicable; FormLayout owns no form value or submission state.
 - Migration decision: none.
 
-## Current-state impact
-
-- **Required state lost for four controls (FR5, AR2).** Under
-  `defaultOptionality="required"` the visible "Required" marker is hidden,
-  but Typeahead and Tokenizer set no `aria-required`, and FileInput and
-  Slider build their required description from `isRequired` alone. Screen
-  reader users hear those fields as not required, while sighted users see
-  the form-wide convention.
-
 ## Ownership boundary
 
 **Owns**
@@ -95,14 +86,14 @@ This table is a review projection; the body below is authoritative.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                           |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Released source, tests, and stories                             |
-| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                                                                                                                                                                                          | Released source, tests, and stories                             |
-| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap.                                                                                                                                                                          | Released source, Field composition, and tests                   |
-| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                                                                                                                                                                                                    | Context source and tests                                        |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. Implementation gap: under `defaultOptionality="required"`, Typeahead and Tokenizer set no `aria-required`, and FileInput and Slider describe required state from `isRequired` alone, so those fields are announced as not required while the marker is hidden (Current-state impact). | Tests; `family:input-fields` ownership                          |
-| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                                                                                                                                                                                           | `architecture:public-component-api/INV5–INV8`; source and tests |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap.                                                                                                                                                                                                                                                                                                | Released source, tests, and stories                             |
+| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                 | Released source, tests, and stories                             |
+| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap. | Released source, Field composition, and tests                   |
+| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                           | Context source and tests                                        |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators.                                                                                                              | Tests; `family:input-fields` ownership                          |
+| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                  | `architecture:public-component-api/INV5–INV8`; source and tests |
 
 ### Allowed variation
 
@@ -135,7 +126,7 @@ This table is a review projection; the body below is authoritative.
 ## Accessibility contract
 
 - **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
-- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology. Implementation gap: Typeahead, Tokenizer, FileInput, and Slider do not (FR5).
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
 - **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
 
 ## Design relationships
@@ -191,7 +182,7 @@ The root target reflects the closed `direction` axis. It owns the outer arrangem
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
 | FR1–FR3        | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow                  | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior`      |
 | FR4, ORD1      | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx`                                                | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary.                                                                                                                                                                                                          | `audit:FormLayout/behavior`      |
-| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. Gap: no test covers Typeahead, Tokenizer, FileInput, or Slider under a `required` default, which do not expose it.                                                                                                                                                                                                                                                                                       | `audit:FormLayout/accessibility` |
+| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput, Slider, Typeahead, and Tokenizer tests cover a `required` default.                                                                                                                                                                                                                                                                                                                            | `audit:FormLayout/accessibility` |
 | FR6, ORD2      | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts`                                          | Ref, attributes, colliding `data-direction`                              | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order.                                                                                                                                                                                                                                                                                                                                                | `audit:FormLayout/api`           |
 | AR1, AR3       | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks                                               | Plain root; caller `role`                                                | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own.                                                                                                                                                                                                                                                                                 | `audit:FormLayout/accessibility` |
 | PR1            | Source review                                                                                                                       | Every direction                                                          | Gap: no automated check covers context identity or added resources.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `audit:FormLayout/behavior`      |

package/src/Heading/Heading.tsx

@@ -45,7 +45,7 @@ import {
 import {useTruncation} from '../Text/useTruncation';
 import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';