@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -103,6 +103,12 @@ export const docs = {
           description: 'How to display selected items in the trigger.',
           default: "'count'",
         },
+        {
+          name: 'formatValue',
+          type: '(items: {value: string; label: string}[]) => string',
+          description:
+            'Formats the trigger text when triggerDisplay="count" or "labels". Receives the selected items (value plus resolved label); the count is items.length. Not used by triggerDisplay="badges".',
+        },
         {
           name: 'maxBadges',
           type: 'number',
@@ -207,6 +213,23 @@ export const docs = {
           description:
             'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
         },
+        {
+          name: 'startIcon',
+          type: 'IconType | ReactNode',
+          description: 'Icon displayed at the start of the selector trigger.',
+        },
+        {
+          name: 'hasClear',
+          type: 'boolean',
+          description: 'Shows a clear button when values are selected.',
+          default: 'false',
+        },
+        {
+          name: 'isDefaultOpen',
+          type: 'boolean',
+          description: 'Whether the dropdown starts open on mount.',
+          default: 'false',
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',
@@ -284,6 +307,8 @@ export const docsZh = {
         placeholder: '未选择值时显示的占位文本。',
         size: '选择器的尺寸变体。',
         triggerDisplay: '在触发器中显示选中项的方式。',
+        formatValue:
+          '格式化 triggerDisplay="count" 或 "labels" 时的触发器文本。接收选中项（value 及解析后的 label），数量为 items.length。triggerDisplay="badges" 不使用此属性。',
         maxBadges:
           '显示"+N"之前的最大徽章数。仅适用于 triggerDisplay="badges"。',
         hasSelectAll: '是否显示全选复选框。',
@@ -420,6 +445,8 @@ export const docsDense = {
         variant:
           'visual trigger style: input bordered control or ghost toolbar control',
         triggerDisplay: 'how to show selected in trigger',
+        formatValue:
+          'formats count/labels trigger text; receives selected items',
         maxBadges: 'max badges before "+N"; badges mode only',
         hasSelectAll: 'show select-all checkbox',
         selectAllLabel: 'select-all label',

package/src/MultiSelector/MultiSelector.test.tsx

@@ -128,6 +128,90 @@ describe('MultiSelector', () => {
     expect(screen.getByText('2 selected')).toBeInTheDocument();
   });
 
+  it('formats the count display with formatValue', () => {
+    render(
+      <MultiSelector
+        label="Spaces"
+        options={defaultOptions}
+        value={['Apple', 'Banana']}
+        onChange={() => {}}
+        formatValue={items => `${items.length} spaces selected`}
+      />,
+    );
+    expect(screen.getByText('2 spaces selected')).toBeInTheDocument();
+  });
+
+  it('passes selected values and resolved labels to formatValue', () => {
+    const formatValue = vi.fn(
+      (items: {value: string; label: string}[]) =>
+        `${items[0].label} and ${items.length - 1} more`,
+    );
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={[
+          {value: 'a', label: 'Apple'},
+          {value: 'b', label: 'Banana'},
+        ]}
+        value={['a', 'b']}
+        onChange={() => {}}
+        formatValue={formatValue}
+      />,
+    );
+    expect(formatValue).toHaveBeenCalledWith([
+      {value: 'a', label: 'Apple'},
+      {value: 'b', label: 'Banana'},
+    ]);
+    expect(screen.getByText('Apple and 1 more')).toBeInTheDocument();
+  });
+
+  it('formats the labels display with formatValue', () => {
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={['Apple', 'Banana', 'Orange']}
+        onChange={() => {}}
+        triggerDisplay="labels"
+        formatValue={items => items.map(item => item.label).join(' & ')}
+      />,
+    );
+    expect(screen.getByText('Apple & Banana & Orange')).toBeInTheDocument();
+  });
+
+  it('ignores formatValue in badges display', () => {
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={['Apple', 'Banana']}
+        onChange={() => {}}
+        triggerDisplay="badges"
+        formatValue={() => 'formatted'}
+      />,
+    );
+    expect(screen.queryByText('formatted')).not.toBeInTheDocument();
+    const trigger = within(screen.getByRole('combobox'));
+    expect(trigger.getByText('Apple')).toBeInTheDocument();
+    expect(trigger.getByText('Banana')).toBeInTheDocument();
+  });
+
+  it('shows the placeholder rather than calling formatValue when empty', () => {
+    const formatValue = vi.fn(() => 'formatted');
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        placeholder="Pick fruits..."
+        formatValue={formatValue}
+      />,
+    );
+    expect(screen.getByText('Pick fruits...')).toBeInTheDocument();
+    expect(formatValue).not.toHaveBeenCalled();
+  });
+
   it('shows labels display', () => {
     render(
       <MultiSelector
@@ -353,6 +437,7 @@ describe('MultiSelector', () => {
 
     await user.keyboard('{Tab}');
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.getByRole('button', {name: 'Next'})).toHaveFocus();
   });
 
   it('supports keyboard navigation with ArrowDown/ArrowUp', async () => {
@@ -1981,6 +2066,27 @@ describe('MultiSelector list structure', () => {
         Node.DOCUMENT_POSITION_FOLLOWING,
     ).toBeTruthy();
   });
+
+  it('hides a standalone divider from the accessibility tree (#4994)', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={['Apple', {type: 'divider'}, 'Banana']}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+
+    // role="listbox" only permits option/group children. The divider still
+    // renders role="separator" (unchanged visual/DOM), but must be excluded
+    // from the accessibility tree so it never reaches the listbox's exposed
+    // children (axe aria-required-children).
+    const divider = document.querySelector('[role="separator"]');
+    expect(divider).toBeTruthy();
+    expect(divider).toHaveAttribute('aria-hidden', 'true');
+  });
 });
 
 describe('MultiSelector search affordances', () => {

package/src/MultiSelector/MultiSelector.tsx

@@ -424,6 +424,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'> {
@@ -608,6 +613,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'.
@@ -711,6 +727,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   hasSearch = false,
   searchPlaceholder: searchPlaceholderFromProps,
   triggerDisplay = 'count',
+  formatValue,
   maxBadges = 3,
   renderOption,
   indicatorPosition = 'start',
@@ -1107,13 +1124,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 +1145,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 +1157,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 +1181,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(() => {
@@ -1420,8 +1455,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)) {

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.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 {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',
@@ -162,7 +163,7 @@ export function NavHeadingMenu({
   return (
     <NavHeadingMenuContext value={ctx}>
       <div
-        ref={mergeRefs(ref, listRef)}
+        ref={useMergedRefs(ref, listRef)}
         role="menu"
         onKeyDown={listKeyDown}
         data-testid={testId}

package/src/NumberInput/NumberInput.doc.mjs

@@ -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',
@@ -237,6 +242,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:
@@ -504,6 +514,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 +588,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:

package/src/NumberInput/NumberInput.tsx

@@ -9,6 +9,7 @@
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/NumberInput/numberParser.ts (locale-aware parsing)
  * - /packages/core/src/NumberInput/NumberInput.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/NumberInput/NumberInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/NumberInput/index.ts (exports if types change)
@@ -213,7 +214,9 @@ import {isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator, useLocale} from '../i18n';
+import {formatEditableNumber, parseLocaleNumber} from './numberParser';
+import type {Locale} from '../i18n';
 
 interface NumberInputPropsBase extends Omit<
   BaseProps,
@@ -426,7 +429,8 @@ export type NumberInputProps =
   NumberInputPropsNonClearable | NumberInputPropsClearable;
 
 /**
- * Parse and validate a string input as a number.
+ * Read the typed or pasted text as a number, then apply the field's
+ * constraints.
  * Returns null if the input is not a valid number or fails validation.
  */
 function parseNumberInput(
@@ -435,15 +439,16 @@ function parseNumberInput(
     min?: number | null;
     max?: number | null;
     isIntegerOnly?: boolean;
+    locale?: Locale;
   },
 ): number | null {
   const trimmed = input.trim();
-  if (trimmed === '' || trimmed === '-') {
+  if (trimmed === '') {
     return null;
   }
 
-  const num = Number(trimmed);
-  if (!Number.isFinite(num)) {
+  const num = parseLocaleNumber(trimmed, options.locale);
+  if (num == null || !Number.isFinite(num)) {
     return null;
   }
 
@@ -599,6 +604,7 @@ export function NumberInput({
   ...rest
 }: NumberInputProps) {
   const t = useTranslator();
+  const locale = useLocale();
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
   const id = useId();
@@ -653,6 +659,11 @@ export function NumberInput({
     inputGroup,
   );
 
+  const parseInput = useCallback(
+    (text: string) => parseNumberInput(text, {min, max, isIntegerOnly, locale}),
+    [isIntegerOnly, locale, max, min],
+  );
+
   const formattedValue = useMemo(() => {
     if (value == null) {
       return '';
@@ -669,16 +680,16 @@ export function NumberInput({
     if (value == null) {
       return '';
     }
-    return isFocused ? String(value) : formattedValue;
-  }, [formattedValue, isFocused, pendingInput, value]);
+    return isFocused ? formatEditableNumber(value, locale) : formattedValue;
+  }, [formattedValue, isFocused, locale, pendingInput, value]);
 
   // Check if current pending input is valid (for styling purposes)
   const isInputValid = useMemo(() => {
     if (pendingInput === null || !pendingInput.trim()) {
       return true;
     }
-    return parseNumberInput(pendingInput, {min, max, isIntegerOnly}) !== null;
-  }, [pendingInput, min, max, isIntegerOnly]);
+    return parseInput(pendingInput) !== null;
+  }, [pendingInput, parseInput]);
 
   // Handle input text change - update immediately if valid
   const handleInputChange = useCallback(
@@ -693,12 +704,12 @@ export function NumberInput({
       setPendingInput(newValue);
 
       // If the input is valid, update immediately
-      const parsed = parseNumberInput(newValue, {min, max, isIntegerOnly});
+      const parsed = parseInput(newValue);
       if (parsed !== null && parsed !== value) {
         onChange(parsed);
       }
     },
-    [value, onChange, min, max, isIntegerOnly, isDisabled, isReadOnly],
+    [value, onChange, parseInput, isDisabled, isReadOnly],
   );
 
   // Handle focus
@@ -721,11 +732,7 @@ export function NumberInput({
             onChange(null);
           }
         } else {
-          const parsed = parseNumberInput(pendingInput, {
-            min,
-            max,
-            isIntegerOnly,
-          });
+          const parsed = parseInput(pendingInput);
           if (parsed !== null && parsed !== value) {
             onChange(parsed);
           }
@@ -737,7 +744,7 @@ export function NumberInput({
       setIsFocused(false);
       onBlur?.(e);
     },
-    [pendingInput, value, onChange, min, max, isIntegerOnly, onBlur, hasClear],
+    [pendingInput, value, onChange, parseInput, onBlur, hasClear],
   );
 
   const valueForStepping = useMemo(() => {
@@ -747,10 +754,8 @@ export function NumberInput({
     if (pendingInput.trim() === '') {
       return null;
     }
-    return (
-      parseNumberInput(pendingInput, {min, max, isIntegerOnly}) ?? value ?? null
-    );
-  }, [isIntegerOnly, max, min, pendingInput, value]);
+    return parseInput(pendingInput) ?? value ?? null;
+  }, [parseInput, pendingInput, value]);
 
   const getNextValue = useCallback(
     (direction: StepDirection) =>
@@ -815,11 +820,7 @@ export function NumberInput({
               onChange(null);
             }
           } else {
-            const parsed = parseNumberInput(pendingInput, {
-              min,
-              max,
-              isIntegerOnly,
-            });
+            const parsed = parseInput(pendingInput);
             if (parsed !== null && parsed !== value) {
               onChange(parsed);
             }
@@ -833,9 +834,7 @@ export function NumberInput({
       pendingInput,
       value,
       onChange,
-      min,
-      max,
-      isIntegerOnly,
+      parseInput,
       onEnter,
       onKeyDown,
       hasClear,