@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/MultiSelector/MultiSelector.tsx

@@ -39,7 +39,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {useKeepLayerOpenProps} from '../Layer/useLayer';
 import {InternalInputClearButton} from '../Field/InputClearButton';
@@ -77,10 +76,7 @@ import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
 import {devWarn, warnOnce} from '../utils/devWarning';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
@@ -110,6 +106,7 @@ import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {SelectorBottomSheet} from '../Selector/SelectorBottomSheet';
 import {useSelectorPresentation} from '../Selector/useSelectorPresentation';
 import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 // Sentinel value for the select-all item in keyboard navigation
 const SELECT_ALL_VALUE = '__xds_select_all__';
@@ -807,7 +804,7 @@ export interface MultiSelectorProps<
    * - 'tooltip': message is exposed from the on-field status icon
    * @default 'attached' for input selectors; 'detached' for secondary and ghost selectors
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -905,7 +902,7 @@ export interface MultiSelectorProps<
    * Not called when nothing is selected — the placeholder shows instead — and
    * not called for triggerDisplay 'badges', which renders Badge elements
    * rather than text.
-   * @default items => `${items.length} selected` for 'count', "A, B, C, +N" for 'labels'
+   * @default the translated `@astryx.multiSelector.selectedCount` message ("2 selected") for 'count', "A, B, C, +N" for 'labels'
    */
   formatValue?: (items: MultiSelectorSelectedItem[]) => string;
 
@@ -1192,7 +1189,17 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Read by the live region above so it speaks what this element renders.
   const emptyStateRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLElement>(null);
-  const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);
+  // A hover moves the highlight too, but the focus ring follows the shared
+  // interaction modality (architecture:interaction-modality INV1): it is read
+  // whenever a key or the pointer moves the highlight, so an action cell
+  // highlighted after pointer input keeps the hover treatment and no ring.
+  const triggerModality = useInteractionModalityTracking();
+  const readModality = triggerModality.readModality;
+  const triggerButtonRef = useMergedRefs<HTMLElement>(
+    triggerRef,
+    triggerModality.ref,
+    ref,
+  );
   const searchRef = useRef<HTMLInputElement>(null);
   const listboxRef = useRef<HTMLDivElement>(null);
 
@@ -1215,11 +1222,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isDisabled guards in
-  // useMultiCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip listeners attach to the existing trigger container.
+  // The trigger stays focusable via aria-disabled. Trigger guards and the value
+  // commit guards below block activation, including from an already-open panel.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1450,6 +1455,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    triggerModality,
+    isFocusReturnAlways: hasExternalTrigger,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -1546,21 +1553,27 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Announce the filtered result count from the query-change handler (matching
   // BaseTypeahead) rather than a reactive effect: computing the count for the
   // next query here fires the announcement exactly once per keystroke and does
-  // not re-speak on unrelated re-renders. Reuses the announce instance shared
-  // with the selection-count announcements above.
+  // not re-speak on unrelated re-renders. The count, the create row and the
+  // empty panel's message state one thing, how the search ended, so they go
+  // through the search's own `hasReplace` announcer: one the next keystroke
+  // replaces before it is exposed is withdrawn rather than joined
+  // (`spec:AST-086` FR9, FR13), and keystrokes arriving within one frame,
+  // from a scanner, dictation or automation, say only the last query's.
+  // Selection changes keep the plain announcer above, so they still join.
+  const announceSearch = useAnnounce({hasReplace: true});
   const handleSearchChange = useCallback(
     (nextQuery: string) => {
       setSearchQuery(nextQuery);
       if (nextQuery.length === 0) {
         // Emptying the query clears the region rather than announcing a count.
-        announce('');
+        announceSearch('');
         return;
       }
       // While isLoading the panel deliberately shows nothing, so announcing a
       // result would put a claim in the one channel the screen has gone quiet
       // for.
       if (isLoading) {
-        announce('');
+        announceSearch('');
         return;
       }
       const count = filterOptionsByQuery(selectableItems, nextQuery).length;
@@ -1570,7 +1583,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           // The create row is the one result on screen, so the panel is not
           // empty and the rendered-message route below stays silent; say the
           // row.
-          announce(
+          announceSearch(
             t('@astryx.multiSelector.createOption', {query: nextCreateQuery}),
           );
           return;
@@ -1581,9 +1594,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         // keystroke — an async load landing with nothing that matches.
         return;
       }
-      announce(t('@astryx.multiSelector.resultCount', {count}));
+      announceSearch(t('@astryx.multiSelector.resultCount', {count}));
     },
-    [announce, isLoading, selectableItems, getCreateQuery, t],
+    [announceSearch, isLoading, selectableItems, getCreateQuery, t],
   );
 
   // The panel's empty message is role="presentation" — role="listbox" permits
@@ -1608,12 +1621,20 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const realItemCount = sortedItems.length - leadingCount;
   const isPanelEmpty =
     surface.isOpen && !isLoading && realItemCount === 0 && !hasCreateRow;
-  useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
+  // Through the search's announcer: the empty panel is how the search ended,
+  // so it and the count replace each other while not yet exposed
+  // (`spec:AST-086` FR13).
+  useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery, {
+    announce: announceSearch,
+  });
 
   // Handle toggle
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
   const clearValues = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     onChange([]);
     announceSelection([]);
     if (changeAction) {
@@ -1623,6 +1644,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     onChange,
     changeAction,
     startTransition,
@@ -1651,6 +1673,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
   const handleToggle = useCallback(
     (itemValue: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(itemValue)
         ? optimisticValue.filter(v => v !== itemValue)
         : [...optimisticValue, itemValue];
@@ -1665,6 +1690,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1699,6 +1725,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       : false;
 
   const handleSelectAll = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     let newValue: string[];
     if (allEnabledSelected) {
       // Deselect all enabled items, keep disabled items that are selected
@@ -1724,6 +1753,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     allEnabledSelected,
     enabledItems,
     optimisticValue,
@@ -1740,6 +1770,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // the option the caller adds is visible.
   const commitCreate = useCallback(
     (query: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(query)
         ? optimisticValue
         : [...optimisticValue, query];
@@ -1754,6 +1787,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1824,27 +1858,22 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     ),
   });
 
-  // A hover moves the highlight too, but the focus ring follows the shared
-  // interaction modality (architecture:interaction-modality INV1): it is read
-  // whenever a key or the pointer moves the highlight, so an action cell
-  // highlighted after pointer input keeps the hover treatment and no ring.
-  useInteractionModalityTracking();
   const [isKeyboardHighlight, setIsKeyboardHighlight] = useState(
-    () => getInteractionModality() === 'keyboard',
+    () => readModality() === 'keyboard',
   );
   const onKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLElement>) => {
       onComboboxKeyDown(event);
-      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+      setIsKeyboardHighlight(readModality() === 'keyboard');
     },
-    [onComboboxKeyDown],
+    [onComboboxKeyDown, readModality],
   );
   const onItemMouseEnter = useCallback(
     (...args: Parameters<typeof onComboboxItemMouseEnter>) => {
       onComboboxItemMouseEnter(...args);
-      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+      setIsKeyboardHighlight(readModality() === 'keyboard');
     },
-    [onComboboxItemMouseEnter],
+    [onComboboxItemMouseEnter, readModality],
   );
 
   // The trigger button owns its click so a consumer `onClick`, which lands on
@@ -1890,7 +1919,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         return (
           <span {...stylex.props(styles.triggerText)}>
             {formatValue?.(selectedItems) ??
-              `${optimisticValue.length} selected`}
+              t('@astryx.multiSelector.selectedCount', {
+                count: optimisticValue.length,
+              })}
           </span>
         );
 
@@ -1933,6 +1964,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     placeholder,
     formatValue,
     maxBadges,
+    t,
   ]);
 
   // Render search input
@@ -2499,20 +2531,24 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       ...(ariaLabelledByProp != null
         ? {'aria-labelledby': ariaLabelledByProp}
         : null),
-      ref: mergeRefs<HTMLElement>(el => {
-        popover.triggerRef(el);
-        triggerRef.current = el;
-        // A control that takes no focus has nowhere for focus to return to
-        // when the panel closes, and focus would land on the body — the
-        // person loses their place in the page. Making it programmatically
-        // focusable repairs the return without putting it in the tab order,
-        // which is the caller's decision to make. It does not make the
-        // control openable from the keyboard: only a real control does
-        // that, which is what the warning below is for.
-        if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
-          el.tabIndex = -1;
-        }
-      }, ref),
+      ref: mergeRefs<HTMLElement>(
+        el => {
+          popover.triggerRef(el);
+          triggerRef.current = el;
+          // A control that takes no focus has nowhere for focus to return to
+          // when the panel closes, and focus would land on the body — the
+          // person loses their place in the page. Making it programmatically
+          // focusable repairs the return without putting it in the tab order,
+          // which is the caller's decision to make. It does not make the
+          // control openable from the keyboard: only a real control does
+          // that, which is what the warning below is for.
+          if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
+            el.tabIndex = -1;
+          }
+        },
+        triggerModality.ref,
+        ref,
+      ),
       id: triggerId,
       onClick: isEffectivelyReadOnly
         ? onClick

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]
 | Behavior                | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu.                 |
 | End-user impact         | Users switch products or accounts from the heading menu by pointer or keyboard; disabled rows are skipped by keyboard and typeahead.                                                                                                                                  |
 | Builder impact          | None.                                                                                                                                                                                                                                                                 |
-| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact).                                                                                                                                                                       |
+| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact).                                                                                                                                                                       |
 | Review checks           | Reject losing `menu`/`menuitem` roles to caller props, keyboard focus landing on a disabled item, or a caller `onKeyDown` that silently disables the keyboard model.                                                                                                  |
 | Governing rules         | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`.                                                                                                                    |
 
@@ -81,10 +81,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   `role="menu"` sits directly inside the heading's own `role="menu"` wrapper.
   WAI-ARIA 1.2 allows a `menu` to own only `menuitem`-family items and groups,
   so assistive technology meets a menu nested in a menu.
-- **Inside a heading, arrow keys move twice.** Inside SideNavHeading or
-  TopNavHeading, the heading's own list handler also moves focus over every
-  `menuitem`, so one ArrowDown moves two items, and in a two-item menu ArrowDown
-  never moves focus. The APG menu pattern moves focus one item per arrow press.
 - **The menu has no name of its own.** NavHeadingMenu's `menu` carries no
   accessible name unless the caller passes `aria-label`; inside a heading only
   the heading's wrapper `menu` is named. The APG menu pattern, which

package/src/NavMenu/NavHeadingMenuItem.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/NavMenu/index.ts
  */
 
-import React, {useCallback, useRef, type ReactNode} from 'react';
+import React, {useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Text} from '../Text';
@@ -23,7 +23,8 @@ import {
   typeScaleVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
+import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
 import type {BaseProps} from '../BaseProps';
 import {useNavHeadingMenuContext} from './NavMenuContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
@@ -156,43 +157,8 @@ export function NavHeadingMenuItem({
   const Element = href ? (isDisabled ? 'a' : LinkComponent) : 'div';
 
   // The element type above changes when `isDisabled` flips, so React replaces
-  // the row. Carry focus over to the replacement when the outgoing node held it
-  // (spec:AST-085 FR4). The ref cleanup runs before the old node is removed, so
-  // `activeElement` is still readable there. Only a different node replacing a
-  // removed one takes focus, and only if focus has fallen to the page: React
-  // also detaches and re-attaches the same node (for example when an <Activity>
-  // boundary hides and reveals the row), and neither case may pull focus back
-  // after the person has moved elsewhere.
-  const focusedNodeRef = useRef<HTMLElement | null>(null);
-  const itemRef = useCallback(
-    (node: HTMLElement | null) => {
-      if (node === null) {
-        return;
-      }
-      const outgoing = focusedNodeRef.current;
-      focusedNodeRef.current = null;
-      // Focus only follows the swap when it has fallen to the page. If the
-      // person moved focus elsewhere in the meantime (for example while an
-      // <Activity> boundary kept the row hidden), leave it alone.
-      const focusFell =
-        document.activeElement === null ||
-        document.activeElement === document.body;
-      if (
-        outgoing !== null &&
-        outgoing !== node &&
-        !outgoing.isConnected &&
-        focusFell
-      ) {
-        node.focus();
-      }
-      const release = mergeRefs<HTMLElement>(ref)(node);
-      return () => {
-        focusedNodeRef.current = document.activeElement === node ? node : null;
-        release?.();
-      };
-    },
-    [ref],
-  );
+  // the row; focus follows to the replacement (spec:AST-085 FR4).
+  const itemRef = useFocusAcrossSwap<HTMLElement>(ref);
 
   return (
     <Element

package/src/NumberInput/NumberInput.doc.mjs

@@ -160,7 +160,7 @@ export const docs = {
       name: 'hasNumberSteppers',
       type: 'boolean',
       description:
-        'Shows increment and decrement buttons at the end of the input.',
+        'Shows increment and decrement buttons at the end of the input on fine pointers. Hidden on coarse pointers (such as touch screens); text entry and keyboard stepping remain available.',
       default: 'false',
     },
     {
@@ -226,12 +226,14 @@ export const docs = {
     {
       name: 'containerClassName',
       type: 'string',
-      description: 'Class name for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Class name for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'containerStyle',
       type: 'CSSProperties',
-      description: 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Inline styles for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'controlXstyle',
@@ -474,7 +476,8 @@ export const docsZh = {
     {
       name: 'hasNumberSteppers',
       type: 'boolean',
-      description: '是否在输入框末尾显示递增和递减按钮。',
+      description:
+        '在精细指针设备上于输入框末尾显示递增和递减按钮。粗指针设备（例如触摸屏）上隐藏按钮；仍可直接输入数值或使用键盘步进。',
       default: 'false',
     },
     {
@@ -720,10 +723,12 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    containerXstyle: 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+    containerXstyle:
+      'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
     containerClassName: 'Class name for the field container.',
     containerStyle: 'Inline styles for the field container.',
-    controlXstyle: 'StyleX styles for the visual control box (border, background, icons); not the native input.',
+    controlXstyle:
+      'StyleX styles for the visual control box (border, background, icons); not the native input.',
     controlClassName: 'Class name for the visual control box.',
     controlStyle: 'Inline styles for the visual control box.',
     label: 'Label text (always rendered for accessibility).',
@@ -754,7 +759,8 @@ export const docsDense = {
       'Formats committed value at rest; raw number is shown while editing.',
     isWheelEnabled:
       'Allow focused wheel gestures to step value. Defaults to true.',
-    hasNumberSteppers: 'Show increment + decrement buttons. Defaults to false.',
+    hasNumberSteppers:
+      'Show increment + decrement buttons on fine pointers; hidden on coarse pointers. Defaults to false.',
     units: 'Units suffix (e.g. "%" or "GB").',
     isIntegerOnly: 'Only allow integer values.',
     hasClear: