@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/MultiSelector/MultiSelector.tsx

@@ -28,18 +28,19 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {usePopover} from '../Popover/usePopover';
+import {usePopoverInternal} from '../Popover/usePopover';
 import {useTooltip} from '../Tooltip';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import type {IconName} from '../Icon';
 import {
   Field,
-  InputClearButton,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
   type FieldStatusVariant,
 } from '../Field';
+import {useKeepLayerOpenProps} from '../Layer/useLayer';
+import {InternalInputClearButton} from '../Field/InputClearButton';
 import {Divider} from '../Divider';
 import {Spinner} from '../Spinner';
 import {PanelSearchInput} from '../Field/PanelSearchInput';
@@ -424,6 +425,11 @@ export type MultiSelectorStatusType = 'warning' | 'error' | 'success';
 
 export type {MultiSelectorStatus};
 
+export interface MultiSelectorSelectedItem {
+  value: string;
+  label: string;
+}
+
 export interface MultiSelectorProps<
   T extends MultiSelectorOptionType = MultiSelectorOptionType,
 > extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
@@ -599,6 +605,25 @@ export interface MultiSelectorProps<
    */
   searchPlaceholder?: string;
 
+  /**
+   * Content shown in the panel when there are no options to show, and
+   * announced in a polite live region when the panel opens. Not shown while
+   * `isLoading` — the options have not arrived yet.
+   * @default 'No options'
+   */
+  emptyText?: ReactNode;
+
+  /**
+   * Content shown in the panel when a search query matches no options, and
+   * announced in a polite live region at the same time.
+   *
+   * The panel message is `role="presentation"`, so the live region is the only
+   * route to assistive tech: a string is announced verbatim, a richer node
+   * falls back to the default text since it cannot be spoken.
+   * @default 'No results found'
+   */
+  emptySearchText?: ReactNode;
+
   /**
    * How to display selected items in the trigger.
    * - 'count': "3 selected"
@@ -608,6 +633,17 @@ export interface MultiSelectorProps<
    */
   triggerDisplay?: 'count' | 'labels' | 'badges';
 
+  /**
+   * Formats the trigger text when triggerDisplay is 'count' or 'labels'.
+   * Receives the selected items (value plus resolved label, in selection
+   * order) and returns the full trigger text; the count is `items.length`.
+   * 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'
+   */
+  formatValue?: (items: MultiSelectorSelectedItem[]) => string;
+
   /**
    * Maximum number of badges to show before showing "+N".
    * Only used when triggerDisplay is 'badges'.
@@ -710,7 +746,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   selectAllLabel: selectAllLabelFromProps,
   hasSearch = false,
   searchPlaceholder: searchPlaceholderFromProps,
+  emptyText: emptyTextFromProps,
+  emptySearchText: emptySearchTextFromProps,
   triggerDisplay = 'count',
+  formatValue,
   maxBadges = 3,
   renderOption,
   indicatorPosition = 'start',
@@ -730,6 +769,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     selectAllLabelFromProps ?? t('@astryx.multiSelector.selectAll');
   const searchPlaceholder =
     searchPlaceholderFromProps ?? t('@astryx.multiSelector.searchPlaceholder');
+  const emptyText = emptyTextFromProps ?? t('@astryx.multiSelector.empty');
+  const emptySearchText =
+    emptySearchTextFromProps ?? t('@astryx.multiSelector.emptySearchResults');
   const size = useSize(sizeProp, 'md');
   const effectiveStatusVariant =
     variant === 'ghost' && statusVariant === 'attached'
@@ -804,6 +846,19 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Announce selection-count changes politely (comboboxes-7 announce path).
   // Toggling options / select-all previously produced no audible feedback.
   const announce = useAnnounce();
+
+  // The panel's empty message is role="presentation" and reaches assistive tech
+  // only through this live region, so the region has to speak whatever the
+  // panel shows. A ReactNode override cannot be spoken; fall back to the
+  // catalog copy for that case rather than announcing nothing.
+  const emptyAnnouncement =
+    typeof emptyText === 'string'
+      ? emptyText
+      : t('@astryx.multiSelector.empty');
+  const emptySearchAnnouncement =
+    typeof emptySearchText === 'string'
+      ? emptySearchText
+      : t('@astryx.multiSelector.emptySearchResults');
   const announceSelection = useCallback(
     (nextValue: string[]) => {
       const total = selectableItems.length;
@@ -889,7 +944,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     triggerRef.current?.focus();
   }, [announce]);
 
-  const popover = usePopover({
+  const popover = usePopoverInternal({
     hasLightDismiss: true,
     onHide: handleLayerHide,
     hasCloseButton: false,
@@ -901,6 +956,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // `usePopover` owns — not on the scrolling list inside it.
     surfaceTarget: 'multi-selector-popup',
   });
+  const keepOpenProps = useKeepLayerOpenProps(popover.id, popover.isOpen);
 
   // Open dropdown on mount when isDefaultOpen is true
   useEffect(() => {
@@ -923,16 +979,54 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         announce('');
         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('');
+        return;
+      }
       const count = filterOptionsByQuery(selectableItems, nextQuery).length;
       announce(
         count === 0
-          ? t('@astryx.multiSelector.emptySearchResults')
+          ? emptySearchAnnouncement
           : t('@astryx.multiSelector.resultCount', {count}),
       );
     },
-    [announce, selectableItems, t],
+    [announce, isLoading, selectableItems, emptySearchAnnouncement, t],
   );
 
+  // The panel's empty message is role="presentation", so this region is the
+  // only route to assistive tech. It has to watch the STATE rather than the
+  // open event: the panel can become empty either on open or when a fetch
+  // lands with nothing in it, and an open-only announcement leaves the second
+  // case silent while the message sits on screen. The ref makes it fire once
+  // per arrival at that state rather than on every re-render.
+  const announcedEmptyRef = useRef<string | null>(null);
+  useEffect(() => {
+    const isPanelEmpty =
+      popover.isOpen &&
+      !isLoading &&
+      searchQuery === '' &&
+      selectableItems.length === 0;
+    if (!isPanelEmpty) {
+      announcedEmptyRef.current = null;
+      return;
+    }
+    if (announcedEmptyRef.current === emptyAnnouncement) {
+      return;
+    }
+    announcedEmptyRef.current = emptyAnnouncement;
+    announce(emptyAnnouncement);
+  }, [
+    popover.isOpen,
+    isLoading,
+    searchQuery,
+    selectableItems.length,
+    emptyAnnouncement,
+    announce,
+  ]);
+
   // Handle toggle
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
@@ -1070,6 +1164,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onKeyDown,
     onItemMouseEnter,
   } = useMultiCombobox({
+    wasJustDismissed: popover.wasJustDismissed,
     selectableItems: sortedItems,
     isDisabled,
     isOpen: popover.isOpen,
@@ -1107,13 +1202,18 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   }, [popover.isOpen, highlightedIndex, getItemId]);
 
   // Build trigger display content
-  const selectedLabels = useMemo(() => {
+  const selectedItems = useMemo(() => {
     return optimisticValue.map(v => {
       const item = selectableItems.find(i => i.value === v);
-      return item?.label ?? v;
+      return {value: v, label: item?.label ?? v};
     });
   }, [optimisticValue, selectableItems]);
 
+  const selectedLabels = useMemo(
+    () => selectedItems.map(item => item.label),
+    [selectedItems],
+  );
+
   const renderTriggerContent = useCallback(() => {
     if (optimisticValue.length === 0) {
       return <span {...stylex.props(styles.triggerText)}>{placeholder}</span>;
@@ -1123,7 +1223,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       case 'count':
         return (
           <span {...stylex.props(styles.triggerText)}>
-            {optimisticValue.length} selected
+            {formatValue?.(selectedItems) ??
+              `${optimisticValue.length} selected`}
           </span>
         );
 
@@ -1134,7 +1235,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           remaining > 0
             ? `${displayed.join(', ')}, +${remaining}`
             : displayed.join(', ');
-        return <span {...stylex.props(styles.triggerText)}>{text}</span>;
+        return (
+          <span {...stylex.props(styles.triggerText)}>
+            {formatValue?.(selectedItems) ?? text}
+          </span>
+        );
       }
 
       case 'badges': {
@@ -1154,7 +1259,15 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         );
       }
     }
-  }, [optimisticValue, triggerDisplay, selectedLabels, placeholder, maxBadges]);
+  }, [
+    optimisticValue,
+    triggerDisplay,
+    selectedItems,
+    selectedLabels,
+    placeholder,
+    formatValue,
+    maxBadges,
+  ]);
 
   // Render search input
   const renderSearch = useCallback(() => {
@@ -1381,7 +1494,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // message out of the listbox's accessibility tree (role="listbox" only
     // permits option/group children); the no-results outcome is announced
     // via the result-count live region instead.
-    if (realItemCount === 0) {
+    // While isLoading the options have not arrived yet, so asserting either
+    // message would be a claim the component cannot make; the trigger's
+    // spinner covers it.
+    if (realItemCount === 0 && !isLoading) {
       elements.push(
         <div
           key="empty"
@@ -1390,7 +1506,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             themeProps('multi-selector-empty-state'),
             stylex.props(styles.emptyState),
           )}>
-          No results found
+          {searchQuery ? emptySearchText : emptyText}
         </div>,
       );
       return elements;
@@ -1420,8 +1536,17 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         // A standalone divider between groups would orphan itself once its
         // neighbors are filtered out, so skip it while searching.
         if (!isSearching) {
+          // role="listbox" only permits option/group children; the divider
+          // carries no information the options don't, so it's hidden from
+          // the accessibility tree entirely rather than exposing
+          // role="separator" as a disallowed listbox child (axe
+          // aria-required-children).
           elements.push(
-            <Divider key={`divider-${i}`} xstyle={styles.divider} />,
+            <Divider
+              key={`divider-${i}`}
+              aria-hidden="true"
+              xstyle={styles.divider}
+            />,
           );
         }
       } else if (isSection(option)) {
@@ -1471,7 +1596,16 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     flushPending();
 
     return elements;
-  }, [options, renderItem, sortedItems, searchQuery, hasSelectAll]);
+  }, [
+    options,
+    renderItem,
+    sortedItems,
+    searchQuery,
+    hasSelectAll,
+    isLoading,
+    emptyText,
+    emptySearchText,
+  ]);
 
   // The detached message box renders its own leading status icon, so the
   // on-field icon would duplicate it — keep the chevron indicator instead.
@@ -1573,7 +1707,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           ))}
         {isBusy && <Spinner size="sm" />}
         {hasClear && value.length > 0 && !isDisabled && (
-          <InputClearButton
+          <InternalInputClearButton
+            {...keepOpenProps}
             label={t('@astryx.multiSelector.clearAll', {label})}
             onClick={handleClear}
             iconClassName={stableClassName('multi-selector-clear-icon')}
@@ -1592,6 +1727,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
               type="button"
               aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
               aria-describedby={statusTooltip.describedBy}
+              {...keepOpenProps}
               onClick={e => e.stopPropagation()}
               {...stylex.props(
                 focusOutlineStyles.focusVisible,

package/src/MultiSelector/hooks.ts

@@ -34,6 +34,12 @@ interface UseMultiComboboxOptions {
    * The Delete/Backspace clear path is skipped when false.
    */
   hasValue?: boolean;
+  /**
+   * Whether the browser's light dismiss just closed the popup. The trigger
+   * click that follows belongs to that same press, so acting on it would
+   * reopen the popup the user just closed.
+   */
+  wasJustDismissed?: () => boolean;
   listboxId: string;
 }
 
@@ -62,6 +68,7 @@ export function useMultiCombobox({
   onToggle,
   onClear,
   hasValue = false,
+  wasJustDismissed,
   listboxId,
 }: UseMultiComboboxOptions): UseMultiComboboxResult {
   const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
@@ -87,7 +94,7 @@ export function useMultiCombobox({
   }, [onClose]);
 
   const onTriggerClick = useCallback(() => {
-    if (isDisabled) {
+    if (isDisabled || wasJustDismissed?.()) {
       return;
     }
     if (isOpen) {
@@ -98,7 +105,7 @@ export function useMultiCombobox({
         setHighlightedIndex(0);
       }
     }
-  }, [isDisabled, isOpen, onOpen, closeAndReset, hasSearch]);
+  }, [isDisabled, wasJustDismissed, isOpen, onOpen, closeAndReset, hasSearch]);
 
   const onItemMouseEnter = useCallback(
     (item: MultiSelectorOptionData, index: number) => {

package/src/MultiSelector/index.ts

@@ -13,6 +13,7 @@ export {
   type MultiSelectorProps,
   type MultiSelectorSize,
   type MultiSelectorStatusType,
+  type MultiSelectorSelectedItem,
 } from './MultiSelector';
 export type {
   MultiSelectorOptionType,

package/src/NavIcon/NavIcon.doc.mjs

@@ -22,7 +22,10 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-navicon'},
+      {className: 'astryx-nav-icon'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},
     ],
   },
   usage: {
@@ -51,7 +54,10 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-navicon'},
+      {className: 'astryx-nav-icon'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},
     ],
   },
   usage: {

package/src/NavIcon/NavIcon.test.tsx

@@ -30,3 +30,12 @@ describe('NavIcon', () => {
     expect(screen.getByTestId('nav-icon')).toBeInTheDocument();
   });
 });
+
+describe('NavIcon theme target names', () => {
+  it('renders the deprecated class beside the current one', () => {
+    render(<NavIcon icon={<span>Icon</span>} data-testid="nav-icon" />);
+    const root = screen.getByTestId('nav-icon');
+    expect(root).toHaveClass('astryx-nav-icon');
+    expect(root).toHaveClass('astryx-navicon');
+  });
+});

package/src/NavIcon/NavIcon.tsx

@@ -79,7 +79,11 @@ export function NavIcon({
     <span
       ref={ref}
       {...mergeProps(
-        themeProps('navicon'),
+        themeProps('nav-icon', undefined, {
+          // `navicon` ran the compound name together; themes styling it keep
+          // working until the next major.
+          legacyNames: ['navicon'],
+        }),
         stylex.props(styles.base, xstyle),
         className,
         style,

package/src/NavMenu/NavHeadingMenu.test.tsx

@@ -321,3 +321,33 @@ describe('context forwarding', () => {
     expect(closeMenu).toHaveBeenCalledOnce();
   });
 });
+
+describe('NavHeadingMenu pass-through props', () => {
+  it('forwards pass-through props to the menu element', () => {
+    render(
+      <NavHeadingMenu aria-label="Products" id="products" data-source="nav">
+        <NavHeadingMenuItem label="First" />
+      </NavHeadingMenu>,
+    );
+    const menu = screen.getByRole('menu');
+    expect(menu).toHaveAttribute('aria-label', 'Products');
+    expect(menu).toHaveAttribute('id', 'products');
+    expect(menu).toHaveAttribute('data-source', 'nav');
+  });
+
+  it('runs a caller onKeyDown alongside the menu keyboard model', async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+    render(
+      <NavHeadingMenu onKeyDown={onKeyDown}>
+        <NavHeadingMenuItem label="First" />
+        <NavHeadingMenuItem label="Second" />
+      </NavHeadingMenu>,
+    );
+    const items = screen.getAllByRole('menuitem');
+    items[0].focus();
+    await user.keyboard('{ArrowDown}');
+    expect(onKeyDown).toHaveBeenCalled();
+    expect(items[1]).toHaveFocus();
+  });
+});

package/src/NavMenu/NavHeadingMenu.tsx

@@ -15,7 +15,7 @@
 import React, {useCallback, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
@@ -26,6 +26,7 @@ import {
   type NavHeadingMenuSize,
 } from './NavMenuContext';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   root: {
     display: 'flex',
@@ -95,6 +96,8 @@ export function NavHeadingMenu({
   className,
   style: styleProp,
   'data-testid': testId,
+  onKeyDown: onKeyDownProp,
+  ...rest
 }: NavHeadingMenuProps) {
   const closeCtx = useNavHeadingCloseContext();
   const closeMenu = closeCtx?.closeMenu;
@@ -162,16 +165,17 @@ export function NavHeadingMenu({
   return (
     <NavHeadingMenuContext value={ctx}>
       <div
-        ref={mergeRefs(ref, listRef)}
-        role="menu"
-        onKeyDown={listKeyDown}
+        ref={useMergedRefs(ref, listRef)}
         data-testid={testId}
         {...mergeProps(
           themeProps('nav-heading-menu', {size}),
           stylex.props(styles.root, sizeStyles[size], xstyle),
           className,
           inlineStyle,
-        )}>
+        )}
+        {...rest}
+        role="menu"
+        onKeyDown={composeEventHandlers(onKeyDownProp, listKeyDown)}>
         {children}
       </div>
     </NavHeadingMenuContext>

package/src/NumberInput/NumberInput.doc.mjs

@@ -35,7 +35,7 @@ export const docs = {
       name: 'onChange',
       type: '(value: number) => void',
       description:
-        'Callback fired when input value changes (only on valid input).',
+        'Callback fired when a valid text edit commits on blur or Enter, or when a step or clear control changes the value.',
       required: true,
     },
     {
@@ -61,6 +61,11 @@ export const docs = {
       description:
         'Whether the field is optional (mutually exclusive with isRequired).',
     },
+    {
+      name: 'onKeyDown',
+      type: '(e: KeyboardEvent<HTMLInputElement>) => void',
+      description: 'Callback fired on keydown events on the input.',
+    },
     {
       name: 'isRequired',
       type: 'boolean',
@@ -123,12 +128,14 @@ export const docs = {
     {
       name: 'min',
       type: 'number | null',
-      description: 'Minimum value allowed.',
+      description:
+        'Minimum value allowed. A smaller entry commits at this value on blur or Enter.',
     },
     {
       name: 'max',
       type: 'number | null',
-      description: 'Maximum value allowed.',
+      description:
+        'Maximum value allowed. A larger entry commits at this value on blur or Enter.',
     },
     {
       name: 'step',
@@ -237,6 +244,11 @@ export const docs = {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Let people paste formatted numbers: a pasted 1,234,234,234 is read under the field's locale and commits as 1234234234 on blur. Typing is never intercepted.",
+      },
       {
         guidance: true,
         description:
@@ -318,7 +330,8 @@ export const docsZh = {
     {
       name: 'onChange',
       type: '(value: number) => void',
-      description: '输入值变化时触发的回调（仅在输入有效时触发）。',
+      description:
+        '有效文本编辑在失焦或按 Enter 时提交；步进或清除控件更改值时也会触发回调。',
       required: true,
     },
     {
@@ -400,12 +413,12 @@ export const docsZh = {
     {
       name: 'min',
       type: 'number | null',
-      description: '允许的最小值。',
+      description: '允许的最小值。更小的输入会在失焦或按 Enter 时提交为该值。',
     },
     {
       name: 'max',
       type: 'number | null',
-      description: '允许的最大值。',
+      description: '允许的最大值。更大的输入会在失焦或按 Enter 时提交为该值。',
     },
     {
       name: 'step',
@@ -504,6 +517,11 @@ export const docsZh = {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
+      {
+        guidance: true,
+        description:
+          '可以直接粘贴带格式的数字：粘贴 1,234,234,234 会按字段所在区域设置解析，失去焦点时提交为 1234234234。输入过程中不会拦截按键。',
+      },
       {
         guidance: true,
         description:
@@ -573,6 +591,11 @@ export const docsDense = {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Pasted formatted numbers parse: 1,234,234,234 commits as 1234234234 under the field's locale. Typing is never intercepted.",
+      },
       {
         guidance: true,
         description:
@@ -635,7 +658,8 @@ export const docsDense = {
   propDescriptions: {
     label: 'Label text (always rendered for accessibility).',
     value: 'Current input value.',
-    onChange: 'Callback on valid input change.',
+    onChange:
+      'Callback when a valid text edit commits on blur/Enter, or a step/clear control changes the value.',
     size: 'Size variant.',
     isLabelHidden: 'Visually hide label (still accessible to screen readers).',
     description: 'Text between label + input.',