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

package/src/DropdownMenu/DropdownMenu.tsx

@@ -67,6 +67,7 @@ import {
   type DropdownMenuSurfaceValue,
 } from './DropdownMenuContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useListFocus} from '../hooks/useListFocus';
 import {useMenuPress} from '../hooks/useMenuPress';
 import type {MenuPressPointerType} from '../hooks/menuPressGesture';
@@ -350,7 +351,7 @@ export type DropdownMenuButtonProps = Omit<ButtonProps, 'onClick'>;
 export type DropdownMenuPresentation = AdaptivePresentation;
 
 /**
- * The props a custom `trigger` spreads onto the control that opens the menu.
+ * The props `renderTrigger` spreads onto the control that opens the menu.
  * They carry the press model — a mouse opens on press-down, a held finger
  * opens with the finger down — the keyboard opens (Enter, Space, ArrowDown,
  * ArrowUp), the toggle click, and the ARIA wiring that names the menu after
@@ -621,6 +622,15 @@ 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();
   const sheetId = useId();
   const actionListRef = useRef<HTMLDivElement>(null);
@@ -630,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);
@@ -645,9 +655,10 @@ function DropdownMenuBottomSheet({
     }
   }
   // The closed sheet renders nothing, so load its rows at rest: the first
-  // open shows the actions at once.
+  // open shows the actions at once. The preload's result says whether they
+  // loaded; after a failure the first open loads them.
   useEffect(() => {
-    preloadMenuBottomSheetActionList();
+    void preloadMenuBottomSheetActionList();
   }, []);
   const currentSubmenu = submenuPath.at(-1);
   const currentItems = currentSubmenu?.items ?? items;
@@ -785,13 +796,20 @@ function DropdownMenuBottomSheet({
       {currentTitle}
     </Heading>
   );
+  // A stable ref: an inline one re-runs on every render (null, then the element).
+  const sheetModalityRef = modality.ref;
+  const sheetTriggerRef = useCallback(
+    (el: HTMLElement | null) => {
+      buttonRef.current = el;
+      sheetModalityRef(el);
+    },
+    [sheetModalityRef],
+  );
   return (
     <>
       {renderTrigger != null ? (
         renderTrigger({
-          ref: el => {
-            buttonRef.current = el;
-          },
+          ref: sheetTriggerRef,
           id: triggerId,
           onClick: handleSheetTriggerClick,
           onClickCapture: () => {},
@@ -806,7 +824,7 @@ function DropdownMenuBottomSheet({
       ) : (
         <Button
           {...button}
-          ref={buttonRef as React.Ref<HTMLButtonElement>}
+          ref={triggerRef}
           xstyle={[
             isOpen && styles.triggerOpen,
             button.xstyle,
@@ -941,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(
@@ -1584,11 +1602,41 @@ function DropdownMenuPopover({
       </>
     );
 
-  const triggerProps: DropdownMenuTriggerProps = {
-    ref: el => {
+  // Stable trigger refs. An inline ref is a new function every render, so React
+  // re-runs it on every commit (null, then the element), and each run moved the
+  // 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;
-      popover.triggerRef(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, modalityRef],
+  );
+  const consumerButtonRef = button.ref;
+  const buttonTriggerRef = useCallback(
+    (el: HTMLButtonElement | null) => {
+      triggerRef(el);
+      if (typeof consumerButtonRef === 'function') {
+        consumerButtonRef(el);
+      } else if (consumerButtonRef) {
+        /* eslint-disable react-compiler/react-compiler -- ref callback: forwarding consumer ref object */
+        consumerButtonRef.current = el;
+        /* eslint-enable react-compiler/react-compiler */
+      }
+    },
+    [triggerRef, consumerButtonRef],
+  );
+
+  const triggerProps: DropdownMenuTriggerProps = {
+    ref: triggerRef,
     id: triggerId,
     onClick: handleButtonClick,
     onClickCapture: handleTriggerClickCapture,
@@ -1611,18 +1659,7 @@ function DropdownMenuPopover({
       ) : (
         <Button
           {...button}
-          ref={el => {
-            buttonRef.current = el;
-            popover.triggerRef(el);
-            const consumerRef = button.ref;
-            if (typeof consumerRef === 'function') {
-              consumerRef(el);
-            } else if (consumerRef) {
-              /* eslint-disable react-compiler/react-compiler -- ref callback: forwarding consumer ref object */
-              consumerRef.current = el;
-              /* eslint-enable react-compiler/react-compiler */
-            }
-          }}
+          ref={buttonTriggerRef}
           xstyle={[
             styles.triggerPressable,
             isOpen && styles.triggerOpen,
@@ -1693,13 +1730,13 @@ function DropdownMenuPopover({
               )?.(event);
               if (event.target === event.currentTarget) {
                 setIsMenuKeyboardFocused(
-                  getInteractionModality() === 'keyboard',
+                  getInteractionModality(event.currentTarget) === 'keyboard',
                 );
               }
             }}
             {...menuPress.menuProps}
             {...mergeProps(
-              themeProps('dropdown-menu'),
+              themeProps('dropdown-menu', {presentation: 'popover'}),
               stylex.props(
                 styles.dropdown,
                 resolvedMaxHeight != null &&
@@ -1753,8 +1790,8 @@ export function DropdownMenu(props: DropdownMenuProps) {
   // Both presentations hang the menu off ONE control.
   useDevWarning(
     'DropdownMenu',
-    '`button` and `trigger` are mutually exclusive: the menu hangs off one ' +
-      'control. `trigger` wins; drop `button`.',
+    '`button` and `renderTrigger` are mutually exclusive: the menu hangs ' +
+      'off one control. `renderTrigger` wins; drop `button`.',
     props.button != null && props.renderTrigger != null,
   );
   const requestedPresentation =

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -70,7 +70,7 @@ export const docs = {
       type: 'boolean',
       default: 'false',
       description:
-        'Whether the item is disabled. Disabled items expose aria-disabled, block activation, and are currently skipped by DropdownMenu arrow-key navigation.',
+        'Whether the item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled) but takes no focus: the arrow keys, typeahead, and the pointer highlight skip it, and activation is blocked.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -134,7 +134,7 @@ export const docsDense = {
     value: 'checked state (controlled, w/ onChange)',
     onChange: 'fired w/ next checked state on toggle',
     isDisabled:
-      'disabled; aria-disabled, no activation; current menu focus skips the row',
+      'disabled (aria-disabled); skipped by arrows/typeahead, not focusable',
     hasCloseOnSelect: 'close menu on toggle (default false, stays open)',
     ref: 'forwarded to the row root (the role="menuitemcheckbox" element)',
     endContent: 'content after label+description',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -37,8 +37,9 @@ import {renderIconSlot, type IconType} from '../Icon';
 import {useIndicator} from '../Indicator';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {focusMenuItemOnHover} from './menuItemHover';
-import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {colorVars, focusVars, spacingVars} from '../theme/tokens.stylex';
 import {composeEventHandlers, mergeProps, themeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 
@@ -55,7 +56,10 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    outline: 'none',
+    // Rows show focus with a translucent overlay, which forced colors replace
+    // with the page color. The standard focus ring (focusOutlineStyles), drawn
+    // inside the row by its own width, marks the focused row in every mode.
+    outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
   },
   disabled: {
     opacity: 0.5,
@@ -110,8 +114,9 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
    */
   onChange?: (checked: boolean) => void;
   /**
-   * Whether the item is disabled. Disabled items expose `aria-disabled`, block
-   * activation, and are currently skipped by DropdownMenu arrow-key navigation.
+   * Whether the item is disabled. A disabled item stays in the accessibility
+   * tree as disabled (`aria-disabled`) but takes no focus: the arrow keys,
+   * typeahead, and the pointer highlight skip it, and activation is blocked.
    * @default false
    */
   isDisabled?: boolean;
@@ -223,7 +228,12 @@ export function DropdownMenuCheckboxItem({
       endContent={endContent}
       onClick={handleClick}
       isDisabled={isDisabled}
-      xstyle={[styles.root, isDisabled && styles.disabled, xstyle]}
+      xstyle={[
+        focusOutlineStyles.focusVisible,
+        styles.root,
+        isDisabled && styles.disabled,
+        xstyle,
+      ]}
       {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
         className,
         style,

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/DropdownMenuItem.tsx

@@ -43,10 +43,12 @@ import {
   spacingVars,
   typographyVars,
   typeScaleVars,
+  focusVars,
 } from '../theme/tokens.stylex';
 import {composeEventHandlers, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {focusMenuItemOnHover} from './menuItemHover';
 import {isModifiedClick} from './menuItemRoles';
 import {themeProps} from '../utils/themeProps';
@@ -81,7 +83,10 @@ const menuItemStyles = stylex.create({
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
     textAlign: 'start',
-    outline: 'none',
+    // Rows show focus with a translucent overlay, which forced colors replace
+    // with the page color. The standard focus ring (focusOutlineStyles), drawn
+    // inside the row by its own width, marks the focused row in every mode.
+    outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
   },
   disabled: {
     opacity: 0.5,
@@ -296,6 +301,7 @@ export function DropdownMenuItem({
       draggable={href != null ? false : undefined}
       isDisabled={isDisabled}
       xstyle={[
+        focusOutlineStyles.focusVisible,
         menuItemStyles.root,
         itemSizeStyles[menuSize],
         isDestructive && menuItemStyles.destructive,

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -52,7 +52,7 @@ export const docs = {
       type: 'boolean',
       default: 'false',
       description:
-        'Whether this individual radio item is disabled. Disabled items expose aria-disabled, block selection, and are currently skipped by DropdownMenu arrow-key navigation.',
+        'Whether this individual radio item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled) but takes no focus: the arrow keys, typeahead, and the pointer highlight skip it, and selection is blocked.',
     },
     {
       name: 'endContent',
@@ -97,7 +97,7 @@ export const docsDense = {
     description: 'secondary text below label',
     icon: 'icon before label',
     isDisabled:
-      'disabled; aria-disabled, blocks selection, skipped by arrow keys',
+      'disabled (aria-disabled); skipped by arrows/typeahead, not focusable',
     endContent: 'content after label+description',
     ref: 'forwarded to the row root (the role="menuitemradio" element)',
   },

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -33,8 +33,9 @@ import {renderIconSlot, type IconType} from '../Icon';
 import {useIndicator} from '../Indicator';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {focusMenuItemOnHover} from './menuItemHover';
-import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {colorVars, focusVars, spacingVars} from '../theme/tokens.stylex';
 import {composeEventHandlers, mergeProps, themeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useDropdownMenuRadioGroupContext} from './DropdownMenuContext';
@@ -52,7 +53,10 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    outline: 'none',
+    // Rows show focus with a translucent overlay, which forced colors replace
+    // with the page color. The standard focus ring (focusOutlineStyles), drawn
+    // inside the row by its own width, marks the focused row in every mode.
+    outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
   },
   disabled: {
     opacity: 0.5,
@@ -103,9 +107,10 @@ export interface DropdownMenuRadioItemProps extends Omit<
    */
   icon?: ReactNode | IconType;
   /**
-   * Whether this individual radio item is disabled. Disabled items expose
-   * `aria-disabled`, block selection, and are currently skipped by
-   * DropdownMenu arrow-key navigation.
+   * Whether this individual radio item is disabled. A disabled item stays in
+   * the accessibility tree as disabled (`aria-disabled`) but takes no focus:
+   * the arrow keys, typeahead, and the pointer highlight skip it, and
+   * selection is blocked.
    * @default false
    */
   isDisabled?: boolean;
@@ -210,7 +215,12 @@ export function DropdownMenuRadioItem({
       endContent={endContent}
       onClick={handleClick}
       isDisabled={isDisabled}
-      xstyle={[styles.root, isDisabled && styles.disabled, xstyle]}
+      xstyle={[
+        focusOutlineStyles.focusVisible,
+        styles.root,
+        isDisabled && styles.disabled,
+        xstyle,
+      ]}
       {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
         className,
         style,

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -89,6 +89,7 @@ import {
   shadowVars,
   typographyVars,
   typeScaleVars,
+  focusVars,
 } from '../theme/tokens.stylex';
 import {
   composeEventHandlers,
@@ -148,7 +149,10 @@ const triggerStyles = stylex.create({
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
     textAlign: 'start',
-    outline: 'none',
+    // Rows show focus with a translucent overlay, which forced colors replace
+    // with the page color. The standard focus ring (focusOutlineStyles), drawn
+    // inside the row by its own width, marks the focused row in every mode.
+    outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
   },
   // While the flyout is open, keep the trigger visibly active so the open
   // branch reads as the current path even when focus has moved into the child.
@@ -1144,7 +1148,7 @@ export function DropdownMenuSubMenu(
         ? // The flyout's frame paints its surface, so the menu target rides
           // on it; a drilled-in view sits inside the root's surface.
           mergeProps(
-            themeProps('dropdown-menu'),
+            themeProps('dropdown-menu', {presentation: 'popover'}),
             stylex.props(regionStyles.frame, regionStyles.flyoutSurface),
           )
         : stylex.props(
@@ -1183,7 +1187,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>) => {
@@ -1229,6 +1235,7 @@ export function DropdownMenuSubMenu(
         onKeyDown={composeEventHandlers(handleTriggerKeyDown, onKeyDown)}
         isDisabled={isDisabled}
         xstyle={[
+          focusOutlineStyles.focusVisible,
           triggerStyles.root,
           triggerSizeStyles[menuSize],
           isOpen && triggerStyles.open,
@@ -1359,7 +1366,7 @@ export function DropdownMenuSubMenu(
                   data-testid={menuDataTestId}
                   {...menuPress.menuProps}
                   {...mergeProps(
-                    themeProps('dropdown-menu'),
+                    themeProps('dropdown-menu', {presentation: 'popover'}),
                     stylex.props(
                       flyoutStyles.menu,
                       hasOverflow

package/src/DropdownMenu/MenuBottomSheetActionList.tsx

@@ -11,14 +11,16 @@
 
 import React, {useRef, type ReactElement} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Divider} from '../Divider';
-import {Heading} from '../Heading';
-import {Icon, renderIconSlot} from '../Icon';
-import {List, ListItem} from '../List';
+import {Divider} from '../Divider/Divider';
+import {Heading} from '../Heading/Heading';
+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';
-import {getInteractionModality} from '../utils/interactionModality';
+import {rtlStyles} from '../utils/rtlStyles';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import type {DropdownMenuItemData, DropdownMenuOption} from './DropdownMenu';
 import {isModifiedClick} from './menuItemRoles';
 
@@ -67,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.
@@ -89,7 +93,7 @@ export function MenuBottomSheetActionList({
         event.preventDefault();
         return;
       }
-      if (getInteractionModality() === 'pointer') {
+      if (readModality() === 'pointer') {
         (event.currentTarget as HTMLElement).blur();
       }
       if (isSubmenu) {
@@ -145,7 +149,7 @@ export function MenuBottomSheetActionList({
 
   return (
     <List
-      ref={listRef}
+      ref={listComposedRef}
       density="spacious"
       xstyle={styles.list}
       {...menuPress.menuProps}>

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -15,6 +15,11 @@
  * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
  * the wrapped component's props and renders nothing until its module loads.
  *
+ * The action list preloads at rest, and the preload's result says whether it
+ * loaded. A failed load is not kept, so the next preload or open asks the
+ * module loader again (a loader that retries then loads it; a browser does not
+ * fetch a native module again once its import failed).
+ *
  * Neither wrapper renders on the server or in the render that hydrates server
  * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
  * leave server markup incomplete and abort hydration. The closed sheet has no
@@ -47,16 +52,40 @@ const LazyMenuBottomSheet = lazy(async () =>
 let actionListModule: typeof ActionListModule | null = null;
 let actionListLoad: Promise<typeof ActionListModule> | null = null;
 async function loadActionList(): Promise<typeof ActionListModule> {
-  actionListLoad ??= import('./MenuBottomSheetActionList').then(module => {
-    actionListModule = module;
-    return module;
-  });
+  actionListLoad ??= import('./MenuBottomSheetActionList').then(
+    module => {
+      actionListModule = module;
+      return module;
+    },
+    (error: unknown) => {
+      // A failed load (a dropped connection) is not kept: the next caller
+      // asks the module loader again.
+      actionListLoad = null;
+      throw error;
+    },
+  );
   return actionListLoad;
 }
 
-/** Starts loading the action list; a sheet menu calls it at rest. */
-export function preloadMenuBottomSheetActionList(): void {
-  void loadActionList();
+/** What a preload of the action list came to: loaded, or failed with the loader's error. */
+export type ActionListPreload =
+  | {readonly isLoaded: true}
+  | {readonly isLoaded: false; readonly error: unknown};
+
+/**
+ * Starts loading the action list; a sheet menu calls it at rest. Its result
+ * says whether the list loaded: a failure (a dropped connection) is that
+ * result, with the loader's error, and never a rejection. The failed load is
+ * not kept, so the first open asks the module loader again, and a load that
+ * fails there reaches the menu through lazy().
+ */
+export async function preloadMenuBottomSheetActionList(): Promise<ActionListPreload> {
+  try {
+    await loadActionList();
+    return {isLoaded: true};
+  } catch (error) {
+    return {isLoaded: false, error};
+  }
 }
 
 const LazyMenuBottomSheetActionList = lazy(async () =>

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -68,6 +68,28 @@ function renderLeafItem(
   return <DropdownMenuItem key={getItemKey(item, index)} {...itemProps} />;
 }
 
+/**
+ * A data item that declares nested `items` becomes a submenu (data-mode
+ * parity with the compound DropdownMenuSubMenu API), at the top level and
+ * inside a section alike; otherwise it's a leaf. renderDropdownItems owns the
+ * recursion and hands the rendered children to DropdownMenuSubMenu, so
+ * DropdownMenuSubMenu never imports this module back (no import cycle).
+ */
+function renderItem(item: DropdownMenuItemData, index: number): ReactElement {
+  if (item.items && item.items.length > 0) {
+    return (
+      <DropdownMenuSubMenu
+        key={getItemKey(item, index)}
+        icon={item.icon}
+        label={item.label}
+        isDisabled={item.isDisabled}>
+        {renderDropdownItems(item.items)}
+      </DropdownMenuSubMenu>
+    );
+  }
+  return renderLeafItem(item, index);
+}
+
 /**
  * Converts data-driven items into DropdownMenuItem components,
  * so both modes share the same rendering and keyboard navigation path.
@@ -96,28 +118,11 @@ export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
               {option.title}
             </div>
           )}
-          {option.items.map(renderLeafItem)}
+          {option.items.map(renderItem)}
         </div>,
       );
     } else if (!('type' in option)) {
-      // A plain item that declares nested `items` becomes a submenu (data-mode
-      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
-      // leaf. renderDropdownItems owns the recursion and hands the rendered
-      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
-      // this module back (no import cycle).
-      if (option.items && option.items.length > 0) {
-        elements.push(
-          <DropdownMenuSubMenu
-            key={getItemKey(option, i)}
-            icon={option.icon}
-            label={option.label}
-            isDisabled={option.isDisabled}>
-            {renderDropdownItems(option.items)}
-          </DropdownMenuSubMenu>,
-        );
-      } else {
-        elements.push(renderLeafItem(option, i));
-      }
+      elements.push(renderItem(option, i));
     }
   }
 

package/src/EmptyState/EmptyState.tsx

@@ -24,7 +24,8 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {AnnounceRenderedText} from '../hooks/AnnounceRenderedText';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({

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