@astryxdesign/core 0.1.8 → 0.1.9-canary.1887ee2

package/src/MultiSelector/MultiSelector.test.tsx

@@ -10,7 +10,13 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MultiSelector} from './MultiSelector';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -360,6 +366,30 @@ describe('MultiSelector', () => {
     expect(activeId).toBeTruthy();
   });
 
+  it('End/Home jump the highlight to the last/first option (non-search)', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+
+    const trigger = screen.getByRole('combobox');
+    await user.click(trigger);
+    const options = screen.getAllByRole('option', h);
+
+    await user.keyboard('{End}');
+    expect(trigger).toHaveAttribute(
+      'aria-activedescendant',
+      options[options.length - 1].id,
+    );
+    await user.keyboard('{Home}');
+    expect(trigger).toHaveAttribute('aria-activedescendant', options[0].id);
+  });
+
   it('toggles item with Enter key', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
@@ -535,6 +565,65 @@ describe('MultiSelector', () => {
     expect(options).toHaveLength(1);
   });
 
+  it('PageDown/PageUp jump the highlight to the last/first filtered option', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    const searchInput = screen.getByRole('combobox', h);
+    // Filter to Banana and Orange so "last" means last *visible* option.
+    await user.type(searchInput, 'an');
+    const options = screen.getAllByRole('option', h);
+    expect(options).toHaveLength(2);
+
+    await user.keyboard('{PageDown}');
+    expect(searchInput).toHaveAttribute(
+      'aria-activedescendant',
+      options[options.length - 1].id,
+    );
+    await user.keyboard('{PageUp}');
+    expect(searchInput).toHaveAttribute('aria-activedescendant', options[0].id);
+  });
+
+  it('Home/End move the search caret, not the option highlight', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    const searchInput = screen.getByRole<HTMLInputElement>('combobox', h);
+    await user.type(searchInput, 'an');
+    expect(searchInput.selectionStart).toBe(2);
+    const activeBefore = searchInput.getAttribute('aria-activedescendant');
+    // Home/End stay on the input for caret movement (APG editable combobox);
+    // the option highlight must not move.
+    await user.keyboard('{Home}');
+    expect(searchInput.selectionStart).toBe(0);
+    expect(searchInput.getAttribute('aria-activedescendant')).toBe(
+      activeBefore,
+    );
+    await user.keyboard('{End}');
+    expect(searchInput.selectionStart).toBe(2);
+    expect(searchInput.getAttribute('aria-activedescendant')).toBe(
+      activeBefore,
+    );
+  });
+
   it('shows empty state when search has no results', async () => {
     const user = userEvent.setup();
     render(
@@ -551,7 +640,85 @@ describe('MultiSelector', () => {
     const searchInput = screen.getByRole('combobox', h);
     await user.type(searchInput, 'xyz');
 
-    expect(screen.getByText('No results found')).toBeInTheDocument();
+    expect(
+      within(screen.getByRole('listbox', h)).getByText('No results found'),
+    ).toBeInTheDocument();
+  });
+
+  describe('result announcements', () => {
+    it('announces the match count politely while searching', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      // "an" matches Banana and Orange.
+      await user.type(screen.getByRole('combobox', h), 'an');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('2 results');
+      });
+    });
+
+    it('announces the singular form when one option matches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      // "app" matches only Apple. Anchored so it cannot pass on "1 results".
+      await user.type(screen.getByRole('combobox', h), 'app');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent(/^1 result$/);
+      });
+    });
+
+    it('announces "No results found" when nothing matches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      await user.type(screen.getByRole('combobox', h), 'xyz');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('No results found');
+      });
+    });
+
+    it('does not announce results until the user searches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      // Popover closed: nothing announced.
+      expect(politeRegion()?.textContent ?? '').toBe('');
+      // Open with an empty query: still nothing announced.
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
   });
 
   it('renders with description', () => {
@@ -1072,7 +1239,32 @@ describe('MultiSelector', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });
+
+
+describe('MultiSelector statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/MultiSelector/MultiSelector.tsx

@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {Spinner} from '../Spinner';
@@ -479,6 +480,13 @@ export interface MultiSelectorProps<
    * Status indicator for the selector.
    */
   status?: MultiSelectorStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -562,6 +570,23 @@ export interface MultiSelectorProps<
   'data-testid'?: string;
 }
 
+// Case-insensitive substring filter over the selectable options. Shared by the
+// `filteredItems` memo (rendering) and the search-change handler, which needs
+// the count for the *next* query synchronously to announce it exactly once per
+// keystroke rather than reacting to state in an effect.
+function filterOptionsByQuery(
+  items: MultiSelectorOptionData[],
+  query: string,
+): MultiSelectorOptionData[] {
+  if (!query) {
+    return items;
+  }
+  const q = query.toLowerCase();
+  return items.filter(item =>
+    (item.label ?? item.value).toLowerCase().includes(q),
+  );
+}
+
 /**
  * A multi-select dropdown component with checkboxes for choosing
  * multiple items from a list of options.
@@ -593,6 +618,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasClear = false,
@@ -692,15 +718,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   );
 
   // Filter items by search query
-  const filteredItems = useMemo(() => {
-    if (!searchQuery) {
-      return selectableItems;
-    }
-    const query = searchQuery.toLowerCase();
-    return selectableItems.filter(item =>
-      (item.label ?? item.value).toLowerCase().includes(query),
-    );
-  }, [selectableItems, searchQuery]);
+  const filteredItems = useMemo(
+    () => filterOptionsByQuery(selectableItems, searchQuery),
+    [selectableItems, searchQuery],
+  );
 
   // Single source of truth for item order. Both the hook (keyboard navigation)
   // and renderOptions (DOM rendering) consume this list — no independent sorting.
@@ -772,8 +793,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const handleLayerHide = useCallback(() => {
     setSearchQuery('');
     setSelectedAtOpen(null);
+    // Clear any lingering result count when the popover closes so stale status
+    // text does not linger in the a11y tree.
+    announce('');
     triggerRef.current?.focus();
-  }, []);
+  }, [announce]);
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -793,6 +817,30 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
   }, []);
 
+  // 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.
+  const handleSearchChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const nextQuery = event.target.value;
+      setSearchQuery(nextQuery);
+      if (nextQuery.length === 0) {
+        // Emptying the query clears the region rather than announcing a count.
+        announce('');
+        return;
+      }
+      const count = filterOptionsByQuery(selectableItems, nextQuery).length;
+      announce(
+        count === 0
+          ? 'No results found'
+          : `${count} result${count === 1 ? '' : 's'}`,
+      );
+    },
+    [announce, selectableItems],
+  );
+
   // Handle toggle
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
@@ -1041,14 +1089,17 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           aria-label={t('@astryx.multiSelector.searchOptions')}
           type="text"
           value={searchQuery}
-          onChange={e => setSearchQuery(e.target.value)}
+          onChange={handleSearchChange}
           onKeyDown={e => {
             // Arrow keys navigate options; Enter toggles; Escape/Tab close.
             // Space and Home/End are left to the input (type a space / move
-            // the caret), not forwarded to option navigation.
+            // the caret) per the APG editable combobox; PageUp/PageDown are
+            // the sanctioned substitute for jumping to the first/last option.
             if (
               e.key === 'ArrowDown' ||
               e.key === 'ArrowUp' ||
+              e.key === 'PageUp' ||
+              e.key === 'PageDown' ||
               e.key === 'Enter' ||
               e.key === 'Escape' ||
               e.key === 'Tab'
@@ -1067,6 +1118,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     listboxId,
     searchQuery,
     searchPlaceholder,
+    handleSearchChange,
     onKeyDown,
     popover.isOpen,
     highlightedIndex,
@@ -1383,6 +1435,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {multiSelectorContent}

package/src/MultiSelector/hooks.ts

@@ -192,6 +192,23 @@ export function useMultiCombobox({
           }
           break;
 
+        // PageUp/PageDown mirror Home/End. In search mode Home/End stay on
+        // the input for caret movement (APG editable combobox), so these are
+        // the sanctioned substitute for jumping to the first/last option.
+        case 'PageUp':
+          e.preventDefault();
+          if (isOpen && enabledIndices.length > 0) {
+            setHighlightedIndex(enabledIndices[0]);
+          }
+          break;
+
+        case 'PageDown':
+          e.preventDefault();
+          if (isOpen && enabledIndices.length > 0) {
+            setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
+          }
+          break;
+
         case 'Delete':
         case 'Backspace':
           // Keyboard equivalent of the clear button (comboboxes-2): clear all

package/src/NavMenu/NavHeadingMenuItem.tsx

@@ -49,7 +49,7 @@ const styles = stylex.create({
     },
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
     textDecoration: 'none',
   },

package/src/NumberInput/NumberInput.doc.mjs

@@ -94,6 +94,13 @@ export const docs = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: 'Validation status with optional message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -275,6 +282,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '带可选消息的验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -402,6 +416,7 @@ export const docsDense = {
     startIcon: 'Icon at input start.',
     labelIcon: 'Icon before label text.',
     status: 'Validation status w/ optional message.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     min: 'Minimum value allowed.',
     max: 'Maximum value allowed.',
     step: 'Step increment.',

package/src/NumberInput/NumberInput.test.tsx

@@ -9,11 +9,20 @@
  * SYNC: When NumberInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
 import {NumberInput} from './NumberInput';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
 // disabledMessage tooltip.
@@ -328,6 +337,33 @@ describe('NumberInput', () => {
       expect(screen.queryByText('%')).not.toBeInTheDocument();
       expect(screen.queryByText('GB')).not.toBeInTheDocument();
     });
+
+    it('includes the units text in the accessible description (WCAG 1.3.1)', () => {
+      render(
+        <NumberInput
+          label="Storage"
+          value={50}
+          onChange={() => {}}
+          units="GB"
+        />,
+      );
+      expect(screen.getByRole('spinbutton')).toHaveAccessibleDescription(/GB/);
+    });
+
+    it('combines units with the description in the accessible description', () => {
+      render(
+        <NumberInput
+          label="Discount"
+          value={10}
+          onChange={() => {}}
+          description="Applied at checkout"
+          units="%"
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      expect(input).toHaveAccessibleDescription(/Applied at checkout/);
+      expect(input).toHaveAccessibleDescription(/%/);
+    });
   });
 
   describe('event callbacks', () => {
@@ -455,6 +491,26 @@ describe('NumberInput', () => {
       expect(screen.getByText('Value must be positive')).toBeInTheDocument();
     });
 
+    it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+      // Inside an InputGroup no Field renders, so the status message element
+      // does not exist; aria-describedby must not reference its id.
+      render(
+        <InputGroup label="Price">
+          <NumberInput
+            label="Amount"
+            value={null}
+            onChange={() => {}}
+            status={{type: 'error', message: 'Value must be positive'}}
+          />
+        </InputGroup>,
+      );
+      const input = screen.getByRole('spinbutton');
+      const describedBy = input.getAttribute('aria-describedby') ?? '';
+      for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+        expect(document.getElementById(idToken)).not.toBeNull();
+      }
+    });
+
     it('does not render status message when not provided', () => {
       render(
         <NumberInput
@@ -871,9 +927,7 @@ describe('NumberInput', () => {
 describe('keyboard clearing with hasClear (#3599)', () => {
   it('commits null when the input is emptied and blurred', () => {
     const onChange = vi.fn();
-    render(
-      <NumberInput label="Qty" hasClear value={42} onChange={onChange} />,
-    );
+    render(<NumberInput label="Qty" hasClear value={42} onChange={onChange} />);
     const input = screen.getByLabelText('Qty');
     fireEvent.change(input, {target: {value: ''}});
     fireEvent.blur(input);
@@ -882,9 +936,7 @@ describe('keyboard clearing with hasClear (#3599)', () => {
 
   it('commits null when the input is emptied and Enter is pressed', () => {
     const onChange = vi.fn();
-    render(
-      <NumberInput label="Qty" hasClear value={42} onChange={onChange} />,
-    );
+    render(<NumberInput label="Qty" hasClear value={42} onChange={onChange} />);
     const input = screen.getByLabelText('Qty');
     fireEvent.change(input, {target: {value: ''}});
     fireEvent.keyDown(input, {key: 'Enter'});
@@ -912,3 +964,26 @@ describe('keyboard clearing with hasClear (#3599)', () => {
     expect((input as HTMLInputElement).value).toBe('42');
   });
 });
+
+
+describe('NumberInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/NumberInput/NumberInput.tsx

@@ -44,6 +44,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -207,6 +208,13 @@ interface NumberInputPropsBase extends Omit<
    * If message is provided, displays a floating message box below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * The size of the input.
    * - 'sm': Compact size (28px height)
@@ -311,8 +319,7 @@ type NumberInputPropsClearable = NumberInputPropsBase & {
 };
 
 export type NumberInputProps =
-  | NumberInputPropsNonClearable
-  | NumberInputPropsClearable;
+  NumberInputPropsNonClearable | NumberInputPropsClearable;
 
 /**
  * Parse and validate a string input as a number.
@@ -375,6 +382,7 @@ export function NumberInput({
   startIcon,
   labelIcon,
   status,
+  statusVariant = 'attached',
   size: sizeProp,
   onChange,
   value,
@@ -406,6 +414,7 @@ export function NumberInput({
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  const unitsID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const inputGroup = useInputGroup();
@@ -446,7 +455,10 @@ export function NumberInput({
     inputLabelID,
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      // The status message element is rendered by Field, which is skipped
+      // inside an InputGroup — only reference it when it actually exists.
+      !inputGroup && status?.message ? statusMessageID : null,
+      units ? unitsID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ],
     inputGroup,
@@ -652,7 +664,11 @@ export function NumberInput({
           !isInputValid && styles.inputInvalid,
         )}
       />
-      {units && <span {...stylex.props(styles.units)}>{units}</span>}
+      {units && (
+        <span id={unitsID} {...stylex.props(styles.units)}>
+          {units}
+        </span>
+      )}
       {/*
         Live region announcing invalid typed input to assistive technology.
         The value silently reverts on blur, so without this a screen-reader
@@ -710,6 +726,7 @@ export function NumberInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}

package/src/Outline/Outline.tsx

@@ -299,7 +299,6 @@ function getIndentStyle(level: number) {
  * @example
  * ```
  * const scrollContainerRef = useRef<HTMLDivElement>(null);
- *
  * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
  * <Outline
  *   items={items}