@astryxdesign/core 0.7.5 → 0.7.6-canary.00146a7

package/src/Field/FieldLabel.doc.mjs

@@ -72,7 +72,8 @@ export const docs = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text for the info icon after the label.',
+      description:
+        'Tooltip text for the info icon after the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field or toggling the control, while a mouse click on the icon activates the control like the rest of the label.',
     },
     {
       name: 'description',
@@ -176,7 +177,8 @@ export const docsZh = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: '标签后信息图标的工具提示文本。',
+      description:
+        '标签后信息图标的工具提示文本。悬停即可显示；在触摸屏上点按图标即可打开，不会聚焦字段或切换控件；用鼠标点击图标则与点击标签其他部分一样激活控件。',
     },
     {
       name: 'description',

package/src/Field/FieldLabel.tsx

@@ -19,7 +19,7 @@
 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';
+import {mergeProps} from '../utils/mergeProps';
 
 import {
   colorVars,
@@ -28,9 +28,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 {useTapStop} 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 +257,12 @@ 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 {onPointerDown: handleIconPointerDown, onClick: handleIconClick} =
+    useTapStop('click');
   const controlRef = useMemo<RefObject<HTMLElement | null>>(
     () => ({
       get current() {
@@ -284,8 +292,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,13 +42,11 @@
 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 {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {mergeProps} from '../utils/mergeProps';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {
   colorVars,
   durationVars,
@@ -220,14 +218,15 @@ export function PanelSearchInput({
   // stays `:focus-visible`, this only narrows it.
   const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);
 
-  useInteractionModalityTracking();
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
+  const mergedInputRef = useMergedRefs(ref, modalityRef);
 
   const handleFocus = useCallback(
     (e: React.FocusEvent<HTMLInputElement>) => {
-      setIsKeyboardFocus(getInteractionModality() === 'keyboard');
+      setIsKeyboardFocus(readModality() === 'keyboard');
       onFocus?.(e);
     },
-    [onFocus],
+    [onFocus, readModality],
   );
 
   const handleBlur = useCallback(
@@ -272,7 +271,7 @@ export function PanelSearchInput({
         )}>
         <Icon icon="search" size="sm" color="secondary" xstyle={styles.icon} />
         <input
-          ref={ref}
+          ref={mergedInputRef}
           type="text"
           aria-label={label}
           placeholder={placeholder}

package/src/Field/fieldStatusPlacement.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fieldStatusPlacement.ts
+ * @input The FieldStatus variant map
+ * @output FieldStatusPlacement, where a field control shows its status
+ * @position Field family type behind every field control's `statusVariant`
+ *
+ * A field control places its status message as a FieldStatus variant, or under
+ * `'tooltip'`, which the Field family consumes before rendering FieldStatus and
+ * shows through the control's on-field status icon (`component:FieldStatus`
+ * FR7, DEC-2). `'tooltip'` belongs here, not to FieldStatus itself, whose map
+ * keeps it only as a deprecated entry until the next minor.
+ */
+
+import type {FieldStatusVariantMap} from '../FieldStatus';
+
+export type FieldStatusPlacement = keyof FieldStatusVariantMap | 'tooltip';

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.
@@ -136,6 +143,28 @@ export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
   variant?: FieldStatusVariant;
 }
 
+// A direct `tooltip` resolves to the deprecated signature first; every other
+// call, a `FieldStatusVariant`-typed value included, resolves to the second,
+// which `ComponentProps<typeof FieldStatus>` reads.
+/**
+ * @deprecated FieldStatus has no `tooltip` presentation
+ * (`component:FieldStatus` FR7): it draws a plain message box with no tooltip.
+ * Set `statusVariant="tooltip"` on the field control instead, which shows the
+ * message from its on-field status icon. Removed in the next minor release.
+ */
+export function FieldStatus(
+  props: FieldStatusProps & {variant: 'tooltip'},
+): React.JSX.Element;
+/**
+ * A status message component for form fields: an `attached` message under a
+ * field, or a `detached` one with its own status icon.
+ *
+ * @example
+ * ```
+ * <FieldStatus type="error" message="This field is required" />
+ * ```
+ */
+export function FieldStatus(props: FieldStatusProps): React.JSX.Element;
 /**
  * A status message component for form fields.
  *
@@ -144,9 +173,10 @@ export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
  * decorative for assistive tech (`aria-hidden`): the message text already names
  * the status in words and is announced through the live region. The `attached`
  * variant keeps its status affordance on the bordered input, so it renders no
- * icon here to avoid a duplicate. The `tooltip` variant renders no message box
- * at all — the input surfaces the status through a tooltip on its on-field
- * icon — so callers skip rendering FieldStatus for it.
+ * icon here to avoid a duplicate. FieldStatus has no `tooltip` presentation:
+ * a field control given `statusVariant="tooltip"` surfaces the status through
+ * a tooltip on its on-field icon and renders no FieldStatus for it
+ * (`component:FieldStatus` FR7).
  *
  * Screen-reader announcements go through the persistent `useAnnounce` live
  * regions (assertive for errors, polite otherwise) rather than `role`/

package/src/FieldStatus/index.ts

@@ -25,6 +25,13 @@
 export interface FieldStatusVariantMap {
   attached: true;
   detached: true;
+  /**
+   * @deprecated FieldStatus has no `tooltip` presentation
+   * (`component:FieldStatus` FR7): given it directly, it draws a plain message
+   * box with no tooltip. Set `statusVariant="tooltip"` on the field control
+   * (TextInput, Selector, and the rest), which shows the message from its
+   * on-field status icon. Removed in the next minor release.
+   */
   tooltip: true;
 }
 

package/src/FileInput/FileInput.doc.mjs

@@ -123,7 +123,7 @@ export const docs = {
       name: 'statusVariant',
       type: "'attached' | 'detached' | 'tooltip'",
       description:
-        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon. Dropzone mode does not support attached: use detached or tooltip. From the next minor release, a dropzone resolves attached to detached and defaults to it.',
       default: "'attached'",
     },
     {
@@ -296,7 +296,7 @@ export const docsZh = {
       name: 'statusVariant',
       type: "'attached' | 'detached' | 'tooltip'",
       description:
-        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。dropzone 模式不支持 attached：请使用 detached 或 tooltip。从下一个次版本起，dropzone 会将 attached 解析为 detached，并以其为默认值。',
       default: "'attached'",
     },
     {
@@ -408,7 +408,7 @@ export const docsDense = {
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
     status: 'Validation status; colored border. Message floats below.',
-    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon. Dropzone: attached unsupported; use detached or tooltip (detached default from next minor).',
     labelTooltip: 'Tooltip in info icon at label end.',
   },
 };

package/src/FileInput/FileInput.tsx

@@ -37,12 +37,7 @@ import {
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
-import {
-  Field,
-  InputClearButton,
-  type InputStatus,
-  type FieldStatusVariant,
-} from '../Field';
+import {Field, InputClearButton, type InputStatus} from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -68,6 +63,9 @@ import {useTranslator} from '../i18n';
 import type {TranslatorFn} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useListFormatter} from '../i18n/useListFormatter';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 function formatFileSize(bytes: number, t: TranslatorFn): string {
   if (bytes < 1024) {
     return t('@astryx.fileInput.fileSize.bytes', {size: bytes});
@@ -236,6 +234,10 @@ const styles = stylex.create({
       ':focus-within': colorVars['--color-accent'],
     },
   },
+  busy: {
+    cursor: 'default',
+    boxShadow: 'none',
+  },
   hiddenInput: {
     position: 'absolute',
     width: 1,
@@ -311,6 +313,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.
@@ -399,9 +404,13 @@ export interface FileInputProps extends Omit<
    * - 'attached': message overlaps directly below the input (bordered treatment)
    * - 'detached': message floats below as a separate element with spacing
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   *
+   * Dropzone mode does not support 'attached': its tall surface cannot carry an
+   * overlapping message. Use 'detached' or 'tooltip' there. From the next minor
+   * release, a dropzone resolves 'attached' to 'detached' and defaults to it.
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * Description text displayed below the label.
    */
@@ -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 =
     [
@@ -559,6 +575,31 @@ export function FileInput({
       .filter(Boolean)
       .join(' ') || undefined;
 
+  // The native input keeps taking the caller's base props (the shared FR10
+  // contract), but it is `aria-hidden` and never focused, so a caller's
+  // `aria-*` props are also set on the trigger, the field's focusable control,
+  // where assistive tech reads them. The ones the trigger composes itself are
+  // not copied, and a caller's description is joined to its own, first.
+  const {
+    'aria-describedby': callerDescribedBy,
+    'aria-label': _callerLabel,
+    'aria-labelledby': _callerLabelledBy,
+    'aria-hidden': _callerHidden,
+    'aria-disabled': _callerDisabled,
+    'aria-busy': _callerBusy,
+    'aria-invalid': _callerInvalid,
+    ...otherRest
+  } = rest as typeof rest & Record<string, unknown>;
+  const triggerAriaProps: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(otherRest)) {
+    // Booleans and numbers are valid ARIA values too: React serializes them.
+    if (key.startsWith('aria-') && value != null) {
+      triggerAriaProps[key] = value;
+    }
+  }
+  const triggerDescribedBy =
+    [callerDescribedBy, ariaDescribedBy].filter(Boolean).join(' ') || undefined;
+
   const defaultPlaceholder = isMultiple
     ? t('@astryx.fileInput.placeholderMultiple')
     : t('@astryx.fileInput.placeholder');
@@ -566,7 +607,7 @@ export function FileInput({
 
   const handleFiles = useCallback(
     (fileList: File[]) => {
-      if (isDisabled) {
+      if (isSelectionDisabled) {
         return;
       }
 
@@ -580,7 +621,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 +658,7 @@ export function FileInput({
     },
     [
       accept,
-      isDisabled,
+      isSelectionDisabled,
       isMultiple,
       maxFiles,
       maxSize,
@@ -625,6 +668,7 @@ export function FileInput({
       setOptimisticValue,
       announce,
       t,
+      formatList,
     ],
   );
 
@@ -670,22 +714,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 +741,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 +786,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 +794,7 @@ export function FileInput({
         handleFiles(fileList);
       }
     },
-    [isDisabled, mode, handleFiles],
+    [isSelectionDisabled, mode, handleFiles],
   );
 
   const hasFiles =
@@ -760,15 +806,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 +843,7 @@ export function FileInput({
         <span {...stylex.props(styles.placeholderText)}>
           {isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
         </span>
+        {tooltipStatus}
       </>
     );
   };
@@ -794,6 +856,7 @@ export function FileInput({
             {fileNames ?? displayPlaceholder}
           </span>
           <Spinner size="sm" aria-hidden="true" />
+          {tooltipStatus}
         </>
       );
     }
@@ -861,17 +924,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 +958,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
@@ -904,8 +971,9 @@ export function FileInput({
                 : label
             }
             aria-busy={isBusy || undefined}
-            aria-describedby={ariaDescribedBy}
             aria-invalid={status?.type === 'error' ? 'true' : undefined}
+            {...triggerAriaProps}
+            aria-describedby={triggerDescribedBy}
           />
         </VisuallyHidden>
         <input
@@ -919,8 +987,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/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';

package/src/HoverCard/HoverCard.doc.mjs

@@ -104,7 +104,7 @@ export const docs = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens. none never opens on touch. A tap-opened card is dismissed by a tap outside it.',
+            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens. none never opens on touch. A tap-opened card is dismissed by a tap outside it.',
           default: "'auto'",
         },
         {
@@ -289,7 +289,7 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开。none：触摸永不打开。轻点打开的卡片可通过点击卡片外部关闭。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开。none：触摸永不打开。轻点打开的卡片可通过点击卡片外部关闭。',
           default: "'auto'",
         },
         {
@@ -439,7 +439,7 @@ export const docsDense = {
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger hover card.',
         touchTrigger:
-          'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',
+          'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',
         isEnabled: 'Enable/disable hover + focus triggers.',
         label:
           'Accessible name for the popup. With label: named role="dialog"; without: role="group".',