@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/DateInput/MonthScroller.tsx

@@ -85,13 +85,8 @@ const DAY_SIZE = dateInputTouchSizes.daySize;
  */
 const OVERSCAN = 3;
 
-/** Input on the scroller that ends a steer: the user's from here. */
-const USER_INPUT_EVENTS = [
-  'touchstart',
-  'wheel',
-  'pointerdown',
-  'keydown',
-] as const;
+/** Every listener on the scroller is passive; one options object serves all. */
+const PASSIVE: AddEventListenerOptions = {passive: true};
 
 const styles = stylex.create({
   scroller: {
@@ -682,17 +677,20 @@ export function MonthScroller({
         onVisibleMonthChangeRef.current(minMonthIndex + row);
       });
     };
-    scroller.addEventListener('scroll', onScroll, {passive: true});
-    for (const type of USER_INPUT_EVENTS) {
-      scroller.addEventListener(type, endSteer, {passive: true});
-    }
-    scroller.addEventListener('touchstart', onTouchStart, {passive: true});
+    scroller.addEventListener('scroll', onScroll, PASSIVE);
+    // The user's input on the scroller ends a steer: from here, it's theirs.
+    scroller.addEventListener('touchstart', endSteer, PASSIVE);
+    scroller.addEventListener('wheel', endSteer, PASSIVE);
+    scroller.addEventListener('pointerdown', endSteer, PASSIVE);
+    scroller.addEventListener('keydown', endSteer, PASSIVE);
+    scroller.addEventListener('touchstart', onTouchStart, PASSIVE);
     return () => {
-      scroller.removeEventListener('scroll', onScroll);
-      for (const type of USER_INPUT_EVENTS) {
-        scroller.removeEventListener(type, endSteer);
-      }
-      scroller.removeEventListener('touchstart', onTouchStart);
+      scroller.removeEventListener('scroll', onScroll, PASSIVE);
+      scroller.removeEventListener('touchstart', endSteer, PASSIVE);
+      scroller.removeEventListener('wheel', endSteer, PASSIVE);
+      scroller.removeEventListener('pointerdown', endSteer, PASSIVE);
+      scroller.removeEventListener('keydown', endSteer, PASSIVE);
+      scroller.removeEventListener('touchstart', onTouchStart, PASSIVE);
       if (frameRef.current != null) {
         cancelAnimationFrame(frameRef.current);
         frameRef.current = undefined;

package/src/DateRangeInput/DateRangeInput.tsx

@@ -50,7 +50,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -82,6 +81,7 @@ import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {useLocale, useTranslator} from '../i18n';
 import type {Locale} from '../i18n/types';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 export type {DateRange} from '../Calendar';
 
@@ -443,7 +443,7 @@ export interface DateRangeInputProps extends Omit<
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -613,7 +613,7 @@ export function DateRangeInput({
 
   const fireChange = useCallback(
     (newValue: DateRange | null) => {
-      if (isBusy) {
+      if (isEffectivelyDisabled) {
         return;
       }
       onChange(newValue);
@@ -624,7 +624,13 @@ export function DateRangeInput({
         });
       }
     },
-    [isBusy, onChange, changeAction, startTransition, setOptimisticValue],
+    [
+      isEffectivelyDisabled,
+      onChange,
+      changeAction,
+      startTransition,
+      setOptimisticValue,
+    ],
   );
 
   const handleToggle = useCallback(() => {
@@ -639,10 +645,13 @@ export function DateRangeInput({
 
   const handleRangeSelect = useCallback(
     (range: DateRange) => {
+      if (isDisabled) {
+        return;
+      }
       fireChange(range);
       popover.hide();
     },
-    [fireChange, popover],
+    [isDisabled, fireChange, popover],
   );
 
   const triggerRef = useRef<HTMLButtonElement>(null);
@@ -813,6 +822,7 @@ export function DateRangeInput({
                 const presetRange = preset.getRange();
                 const isActive = isRangeEqual(value, presetRange);
                 const isPresetDisabled =
+                  isDisabled ||
                   !isRangeWithinSpan(presetRange, maxRangeSpan, minRangeSpan) ||
                   isDateDisabled(plainDateFromISO(presetRange.start)) ||
                   isDateDisabled(plainDateFromISO(presetRange.end));
@@ -828,6 +838,11 @@ export function DateRangeInput({
                     aria-current={isActive ? 'true' : undefined}
                     // Focusable while disabled (AR3, spec:AST-085 FR1).
                     aria-disabled={isPresetDisabled || undefined}
+                    aria-describedby={
+                      showsDisabledMessage
+                        ? disabledMessageTooltip.describedBy
+                        : undefined
+                    }
                     onClick={() => {
                       if (!isPresetDisabled) {
                         handleRangeSelect(presetRange);

package/src/Dialog/Dialog.tsx

@@ -76,11 +76,7 @@ import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
-import {
-  getInteractionModality,
-  trackInteractionModalityIn,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {focusForLastInput} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
@@ -533,25 +529,17 @@ export function Dialog({
     [titleId, hasConsumerName],
   );
 
-  const mergedDialogRef = useMergedRefs(ref, attachDialog);
-
-  // Capture the element that was focused when the dialog opened, for
-  // directional animation origin and focus restoration on close.
-  const triggerElementRef = useRef<HTMLElement | null>(null);
-
-  useInteractionModalityTracking();
-
   // Input in a second document (a same-origin iframe, a Document
   // Picture-in-Picture window) never reaches the page's listeners, so the
   // dialog's own document keeps its own last input for the focus return while
   // this Dialog is mounted, from before it opens until it unmounts.
-  useEffect(() => {
-    const ownerDocument = dialogRef.current?.ownerDocument;
-    if (ownerDocument == null || ownerDocument === document) {
-      return undefined;
-    }
-    return trackInteractionModalityIn(ownerDocument);
-  }, [isInline]);
+  const {ref: modalityRef} = useInteractionModalityTracking();
+
+  const mergedDialogRef = useMergedRefs(ref, attachDialog, modalityRef);
+
+  // Capture the element that was focused when the dialog opened, for
+  // directional animation origin and focus restoration on close.
+  const triggerElementRef = useRef<HTMLElement | null>(null);
 
   // This runs in a layout effect so the capture lands before any descendant's
   // passive mount effect: all layout effects run before any passive effect,
@@ -622,11 +610,7 @@ export function Dialog({
       // the last input in that element's own document calls for.
       const trigger = triggerElementRef.current;
       if (trigger) {
-        focusForLastInput(
-          trigger,
-          undefined,
-          getInteractionModality(trigger.ownerDocument),
-        );
+        focusForLastInput(trigger);
       }
       triggerElementRef.current = null;
     }

package/src/Drawer/Drawer.tsx

@@ -53,7 +53,7 @@
  * - /packages/core/src/Drawer/Drawer.doc.mjs (props table, features, usage)
  * - /packages/core/src/Drawer/Drawer.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Drawer/__tests__/DrawerNonModalPageScroll.a11y.chromium.spec.ts (the page beside a non-modal drawer scrolls)
- * - /packages/core/src/Drawer/Drawer.spec.md (component contract)
+ * - /docs/specs/components/Drawer/Drawer.spec.md (component contract)
  * - /packages/core/src/Drawer/index.ts (exports if types change)
  * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
  * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)

package/src/DropdownMenu/DropdownMenu.tsx

@@ -622,9 +622,13 @@ function DropdownMenuBottomSheet({
   const button = buttonFromProps ?? {label: t(DEFAULT_BUTTON_I18N_KEY)};
   const backLabel = t('@astryx.dropdownMenu.back');
   const buttonRef = useRef<HTMLElement>(null);
+  // The trigger, where focus returns after the sheet closes, carries the
+  // modality tracking for its document.
+  const modality = useInteractionModalityTracking();
   // The caller's `button.ref` rides along with the sheet's own trigger ref.
   const triggerRef = useMergedRefs<HTMLButtonElement>(
     buttonRef as React.Ref<HTMLButtonElement>,
+    modality.ref,
     button.ref,
   );
   const triggerId = useId();
@@ -636,7 +640,7 @@ function DropdownMenuBottomSheet({
     onFocusReturnTargetFocus,
     prepareFocusReturn,
     resetFocusReturn,
-  } = useFocusReturnVisibility();
+  } = useFocusReturnVisibility(modality);
   const viewHeadingRef = useRef<HTMLHeadingElement>(null);
   const previousSubmenuDepthRef = useRef(0);
   const [internalIsOpen, setInternalIsOpen] = useState(false);
@@ -793,9 +797,14 @@ function DropdownMenuBottomSheet({
     </Heading>
   );
   // A stable ref: an inline one re-runs on every render (null, then the element).
-  const sheetTriggerRef = useCallback((el: HTMLElement | null) => {
-    buttonRef.current = el;
-  }, []);
+  const sheetModalityRef = modality.ref;
+  const sheetTriggerRef = useCallback(
+    (el: HTMLElement | null) => {
+      buttonRef.current = el;
+      sheetModalityRef(el);
+    },
+    [sheetModalityRef],
+  );
   return (
     <>
       {renderTrigger != null ? (
@@ -950,14 +959,14 @@ function DropdownMenuPopover({
   const pendingControlledOpenRef = useRef(false);
   const suppressControlledRollbackHideRef = useRef(false);
 
-  useInteractionModalityTracking();
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const modality = useInteractionModalityTracking();
   const {
     isFocusRingSuppressed,
     onFocusReturnTargetFocus,
     prepareFocusReturn,
     resetFocusReturn,
-  } = useFocusReturnVisibility();
-  const contentRef = useRef<HTMLDivElement | null>(null);
+  } = useFocusReturnVisibility(modality);
   const headerRef = useRef<HTMLDivElement | null>(null);
   const footerRef = useRef<HTMLDivElement | null>(null);
   const hasRegions = useMemo(
@@ -1598,12 +1607,18 @@ function DropdownMenuPopover({
   // popover's anchor off the trigger and back: two inline-style writes on the
   // trigger per render of the menu.
   const popoverTriggerRef = popover.triggerRef;
+  // The trigger, where focus returns, also carries the modality tracking for
+  // its document.
+  const modalityRef = modality.ref;
   const triggerRef = useCallback(
     (el: HTMLElement | null) => {
       buttonRef.current = el;
       popoverTriggerRef(el);
+      // Called with each node and with `null`, so its cleanup isn't returned
+      // (a returned cleanup would stop React's `null` call to the others).
+      modalityRef(el);
     },
-    [popoverTriggerRef],
+    [popoverTriggerRef, modalityRef],
   );
   const consumerButtonRef = button.ref;
   const buttonTriggerRef = useCallback(
@@ -1715,7 +1730,7 @@ function DropdownMenuPopover({
               )?.(event);
               if (event.target === event.currentTarget) {
                 setIsMenuKeyboardFocused(
-                  getInteractionModality() === 'keyboard',
+                  getInteractionModality(event.currentTarget) === 'keyboard',
                 );
               }
             }}

package/src/DropdownMenu/DropdownMenuGroup.tsx

@@ -35,6 +35,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {isRenderable} from '../utils/isRenderable';
 
 const styles = stylex.create({
   heading: {
@@ -98,7 +99,7 @@ export function DropdownMenuGroup({
   ...rest
 }: DropdownMenuGroupProps) {
   const headingId = useId();
-  const hasTitle = title != null && title !== '' && title !== false;
+  const hasTitle = isRenderable(title);
 
   return (
     <div

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -1183,7 +1183,9 @@ export function DropdownMenuSubMenu(
   // on the menu element shows the ring the base style otherwise removes.
   const handleMenuFocus = (event: React.FocusEvent<HTMLDivElement>) => {
     if (hasRegions && event.target === event.currentTarget) {
-      setIsMenuKeyboardFocused(getInteractionModality() === 'keyboard');
+      setIsMenuKeyboardFocused(
+        getInteractionModality(event.currentTarget) === 'keyboard',
+      );
     }
   };
   const handleMenuBlur = (event: React.FocusEvent<HTMLDivElement>) => {

package/src/DropdownMenu/MenuBottomSheetActionList.tsx

@@ -17,9 +17,10 @@ import {Icon, renderIconSlot} from '../Icon/Icon';
 import {List} from '../List/List';
 import {ListItem} from '../List/ListItem';
 import {useMenuPress} from '../hooks/useMenuPress';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {rtlStyles} from '../utils/rtlStyles';
-import {getInteractionModality} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import type {DropdownMenuItemData, DropdownMenuOption} from './DropdownMenu';
 import {isModifiedClick} from './menuItemRoles';
 
@@ -68,6 +69,8 @@ export function MenuBottomSheetActionList({
   onOpenSubmenu: (item: DropdownMenuItemData) => void;
 }) {
   const listRef = useRef<HTMLUListElement>(null);
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
+  const listComposedRef = useMergedRefs(listRef, modalityRef);
   // The press model: the row under a finger's RELEASE acts, and the
   // highlight (focus) follows the finger across the rows. The sheet is modal,
   // so a release outside it is the scrim's, not a dismissal of ours.
@@ -90,7 +93,7 @@ export function MenuBottomSheetActionList({
         event.preventDefault();
         return;
       }
-      if (getInteractionModality() === 'pointer') {
+      if (readModality() === 'pointer') {
         (event.currentTarget as HTMLElement).blur();
       }
       if (isSubmenu) {
@@ -146,7 +149,7 @@ export function MenuBottomSheetActionList({
 
   return (
     <List
-      ref={listRef}
+      ref={listComposedRef}
       density="spacious"
       xstyle={styles.list}
       {...menuPress.menuProps}>

package/src/Field/Field.doc.mjs

@@ -120,7 +120,8 @@ export const docs = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text to display in an info icon at the end of the label.',
+      description:
+        'Tooltip text to display in an info icon at the end of the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field, while a mouse click on the icon focuses the field like the rest of the label.',
     },
     {
       name: 'status',

package/src/Field/Field.tsx

@@ -22,7 +22,6 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {FieldLabel} from './FieldLabel';
 import {FieldStatus} from '../FieldStatus/FieldStatus';
-import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
@@ -32,6 +31,7 @@ import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
+import type {FieldStatusPlacement} from './fieldStatusPlacement';
 
 const styles = stylex.create({
   container: {
@@ -187,7 +187,7 @@ export interface FieldProps extends Omit<
    * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so

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

@@ -31,6 +31,7 @@ import {
 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';
@@ -256,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() {
@@ -285,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/PanelSearchInput.tsx

@@ -45,10 +45,8 @@ import type {StyleXStyles} from '@stylexjs/stylex';
 import {Icon} from '../Icon/Icon';
 import {InputClearButton} from './InputClearButton';
 import {mergeProps} from '../utils/mergeProps';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+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

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