@astryxdesign/core 0.1.8 → 0.1.9

package/src/MultiSelector/MultiSelector.tsx

@@ -562,6 +562,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.
@@ -692,15 +709,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 +784,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 +808,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 +1080,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 +1109,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     listboxId,
     searchQuery,
     searchPlaceholder,
+    handleSearchChange,
     onKeyDown,
     popover.isOpen,
     highlightedIndex,

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/NumberInput/NumberInput.test.tsx

@@ -9,11 +9,19 @@
  * 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 {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.
@@ -871,9 +879,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 +888,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'});

package/src/NumberInput/NumberInput.tsx

@@ -311,8 +311,7 @@ type NumberInputPropsClearable = NumberInputPropsBase & {
 };
 
 export type NumberInputProps =
-  | NumberInputPropsNonClearable
-  | NumberInputPropsClearable;
+  NumberInputPropsNonClearable | NumberInputPropsClearable;
 
 /**
  * Parse and validate a string input as a number.

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}

package/src/OverflowList/OverflowList.doc.mjs

@@ -61,6 +61,20 @@ export const docs = {
       description: 'Minimum number of items to always show, even when overflowing.',
       default: '0',
     },
+    {
+      name: 'maxVisibleItems',
+      type: 'number',
+      description:
+        'Maximum number of items to ever show, even when they all fit. The ceiling partner to minVisibleItems; extra items collapse into the overflow indicator. If less than minVisibleItems, the floor wins.',
+      default: 'undefined (no cap)',
+    },
+    {
+      name: 'maxRows',
+      type: 'number',
+      description:
+        'Wrap items across up to this many rows before collapsing the rest into the overflow indicator. A number, not a boolean. Leave undefined (or set 1) for single-line behavior. Assumes uniform row height.',
+      default: 'undefined (single line)',
+    },
     {
       name: 'collapseFrom',
       type: "'start' | 'end'",
@@ -91,8 +105,9 @@ export const docs = {
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [
       { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
-      { guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
-      { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
+      { guidance: true, description: 'Set minVisibleItems to keep key items visible, and maxVisibleItems to cap the row at a fixed count regardless of available width.' },
+      { guidance: true, description: 'Use maxRows to let items wrap onto a bounded number of rows (e.g. a two-row tag cloud) before collapsing the rest into the indicator.' },
+      { guidance: false, description: 'Use OverflowList for a vertical stack; horizontal multi-row wrap is supported via maxRows, but items still flow left-to-right, not top-to-bottom.' },
     ],
   },
 };
@@ -127,6 +142,20 @@ export const docsZh = {
       description: '溢出时始终显示的最小项目数。',
       default: '0',
     },
+    {
+      name: 'maxVisibleItems',
+      type: 'number',
+      description:
+        '始终显示的最大项目数（即使全部都能放下）。它是 minVisibleItems 的上限伙伴；多余项目会折叠进溢出指示器。若小于 minVisibleItems，则以下限为准。',
+      default: 'undefined（无上限）',
+    },
+    {
+      name: 'maxRows',
+      type: 'number',
+      description:
+        '在将其余项目折叠进溢出指示器之前，允许项目换行到的最大行数。是数字而非布尔值。留空（或设为 1）表示单行。假定行高一致。',
+      default: 'undefined（单行）',
+    },
     {
       name: 'collapseFrom',
       type: "'start' | 'end'",
@@ -152,8 +181,9 @@ export const docsZh = {
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [
       { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
-      { guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
-      { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
+      { guidance: true, description: 'Set minVisibleItems to keep key items visible, and maxVisibleItems to cap the row at a fixed count regardless of available width.' },
+      { guidance: true, description: 'Use maxRows to let items wrap onto a bounded number of rows (e.g. a two-row tag cloud) before collapsing the rest into the indicator.' },
+      { guidance: false, description: 'Use OverflowList for a vertical stack; horizontal multi-row wrap is supported via maxRows, but items still flow left-to-right, not top-to-bottom.' },
     ],
   },
 };
@@ -166,8 +196,9 @@ export const docsDense = {
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [
       { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
-      { guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
-      { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
+      { guidance: true, description: 'Set minVisibleItems to keep key items visible, and maxVisibleItems to cap the row at a fixed count regardless of available width.' },
+      { guidance: true, description: 'Use maxRows to let items wrap onto a bounded number of rows (e.g. a two-row tag cloud) before collapsing the rest into the indicator.' },
+      { guidance: false, description: 'Use OverflowList for a vertical stack; horizontal multi-row wrap is supported via maxRows, but items still flow left-to-right, not top-to-bottom.' },
     ],
   },
   propDescriptions: {
@@ -175,6 +206,8 @@ export const docsDense = {
     overflowRenderer: 'renders overflow indicator, receives hidden items w/ index',
     gap: 'item gap as spacing step',
     minVisibleItems: 'min items always shown even when overflowing',
+    maxVisibleItems: 'max items ever shown (cap); extra items collapse to indicator; min wins if smaller',
+    maxRows: 'wrap items across up to N rows then collapse rest (number, not boolean); undefined = single line',
     collapseFrom: 'which end to collapse from',
     behavior: 'observeSelf (default) or observeParent for content-sized containers',
     xstyle: 'StyleX styles, use stylex.create() values only',

package/src/OverflowList/OverflowList.test.tsx

@@ -413,4 +413,115 @@ describe('OverflowList', () => {
       expect(OverflowList.displayName).toBe('OverflowList');
     });
   });
+
+  describe('maxVisibleItems (cap)', () => {
+    it('caps visible items even when they all fit', () => {
+      render(
+        <OverflowList
+          gap={0}
+          data-w="1000"
+          data-testid="ov"
+          maxVisibleItems={2}
+          overflowRenderer={indicator('more:')}>
+          <button type="button" data-w="40">
+            A
+          </button>
+          <button type="button" data-w="40">
+            B
+          </button>
+          <button type="button" data-w="40">
+            C
+          </button>
+          <button type="button" data-w="40">
+            D
+          </button>
+        </OverflowList>,
+      );
+      const vis = visibleContainer();
+      expect(within(vis).getByText('A')).toBeInTheDocument();
+      expect(within(vis).getByText('B')).toBeInTheDocument();
+      expect(within(vis).queryByText('C')).not.toBeInTheDocument();
+      expect(within(vis).getByText('more:2,3')).toBeInTheDocument();
+    });
+
+    it('min wins over a smaller cap (D1)', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      render(
+        <OverflowList
+          gap={0}
+          data-w="1000"
+          data-testid="ov"
+          minVisibleItems={3}
+          maxVisibleItems={1}
+          overflowRenderer={indicator('more:')}>
+          <button type="button" data-w="40">
+            A
+          </button>
+          <button type="button" data-w="40">
+            B
+          </button>
+          <button type="button" data-w="40">
+            C
+          </button>
+          <button type="button" data-w="40">
+            D
+          </button>
+        </OverflowList>,
+      );
+      const vis = visibleContainer();
+      expect(within(vis).getByText('A')).toBeInTheDocument();
+      expect(within(vis).getByText('B')).toBeInTheDocument();
+      expect(within(vis).getByText('C')).toBeInTheDocument();
+      expect(within(vis).queryByText('D')).not.toBeInTheDocument();
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
+  });
+
+  describe('maxRows (multi-row)', () => {
+    it('applies a different container class when maxRows enables wrapping', () => {
+      const {rerender} = render(
+        <OverflowList gap={0} data-w="1000" data-testid="ov">
+          <button type="button" data-w="40">
+            A
+          </button>
+        </OverflowList>,
+      );
+      const singleLine = visibleContainer().getAttribute('class');
+
+      rerender(
+        <OverflowList gap={0} data-w="1000" data-testid="ov" maxRows={2}>
+          <button type="button" data-w="40">
+            A
+          </button>
+        </OverflowList>,
+      );
+      const multiRow = visibleContainer().getAttribute('class');
+      expect(multiRow).not.toEqual(singleLine);
+    });
+
+    it('keeps single-line behavior with maxRows={1}', () => {
+      render(
+        <OverflowList
+          gap={0}
+          data-w="100"
+          data-testid="ov"
+          maxRows={1}
+          overflowRenderer={indicator('more:')}>
+          <button type="button" data-w="40">
+            A
+          </button>
+          <button type="button" data-w="40">
+            B
+          </button>
+          <button type="button" data-w="40">
+            C
+          </button>
+        </OverflowList>,
+      );
+      const vis = visibleContainer();
+      expect(within(vis).getByText('A')).toBeInTheDocument();
+      expect(within(vis).queryByText('B')).not.toBeInTheDocument();
+    });
+  });
 });

package/src/OverflowList/OverflowList.tsx

@@ -9,8 +9,9 @@
  * @position Core implementation; consumed by index.ts
  *
  * Renders a horizontal list of items, hiding those that don't fit in the
- * available width and optionally showing an overflow indicator.
- * Uses a hidden measurement container to avoid flickering.
+ * available width and optionally showing an overflow indicator. Supports an
+ * optional item cap (`maxVisibleItems`) and bounded multi-row wrapping
+ * (`maxRows`). Uses a hidden measurement container to avoid flickering.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/OverflowList/index.ts (exports if types change)
@@ -34,6 +35,14 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     minWidth: 0,
   },
+  containerMultiRow: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignContent: 'flex-start',
+    overflow: 'hidden',
+    whiteSpace: 'normal',
+    minWidth: 0,
+  },
   fillParent: {
     width: '100%',
   },
@@ -52,6 +61,12 @@ const styles = stylex.create({
   },
 });
 
+const multiRowHeight = stylex.create({
+  height: (maxRows: number, rowHeight: number, gapPx: number) => ({
+    maxHeight: `calc(${rowHeight}px * ${maxRows} + ${gapPx}px * ${maxRows - 1})`,
+  }),
+});
+
 const gapStyles = stylex.create({
   0: {gap: spacingVars['--spacing-0']},
   0.5: {gap: spacingVars['--spacing-0-5']},
@@ -112,6 +127,24 @@ export interface OverflowListProps extends BaseProps<HTMLDivElement> {
    */
   minVisibleItems?: number;
 
+  /**
+   * Maximum number of items to ever show, even when they all fit. The ceiling
+   * partner to `minVisibleItems`; extra items collapse into the overflow
+   * indicator. Leave undefined for no cap. If it is less than
+   * `minVisibleItems`, the floor wins (and a dev-only warning is logged).
+   * @default undefined
+   */
+  maxVisibleItems?: number;
+
+  /**
+   * Wrap items across up to this many rows before collapsing the remainder
+   * into the overflow indicator. Leave undefined (or set `1`) for the default
+   * single-line behavior. A number, not a boolean — unbounded wrapping is a
+   * plain flex-wrap layout, not overflow collapse. Assumes uniform row height.
+   * @default undefined
+   */
+  maxRows?: number;
+
   /**
    * Which end to collapse items from.
    * @default 'end'
@@ -180,6 +213,8 @@ export function OverflowList({
   children,
   gap = 2,
   minVisibleItems = 0,
+  maxVisibleItems,
+  maxRows,
   collapseFrom = 'end',
   behavior = 'observeSelf',
   overflowRenderer,
@@ -195,16 +230,17 @@ export function OverflowList({
   const gapPx = spacingToPx[gap];
 
   const observeParent = behavior === 'observeParent';
+  const isMultiRow = maxRows != null && maxRows > 1;
 
-  const {containerRef, measureRef, visibleCount, hasOverflow} = useOverflow(
-    itemCount,
-    {
+  const {containerRef, measureRef, visibleCount, hasOverflow, rowHeight} =
+    useOverflow(itemCount, {
       gap: gapPx,
       minVisibleItems,
+      maxVisibleItems,
+      maxRows,
       collapseFrom,
       behavior,
-    },
-  );
+    });
 
   const allItems: OverflowItem[] = childArray.map((child, index) => ({
     child,
@@ -248,8 +284,12 @@ export function OverflowList({
         {...mergeProps(
           themeProps('overflow-list'),
           stylex.props(
-            styles.container,
+            isMultiRow ? styles.containerMultiRow : styles.container,
             gapStyles[gap],
+            isMultiRow &&
+              rowHeight > 0 &&
+              maxRows != null &&
+              multiRowHeight.height(maxRows, rowHeight, gapPx),
             observeParent && hasOverflow && styles.fillParent,
             xstyle,
           ),

package/src/Popover/Popover.tsx

@@ -26,6 +26,7 @@ import React, {
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {mergeProps} from '../utils';
+import {devWarn} from '../utils/devWarning';
 import type {BaseProps} from '../BaseProps';
 import {usePopover} from './usePopover';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
@@ -410,8 +411,9 @@ export function Popover({
 
     const button = findTriggerButton(el);
     if (!button) {
-      console.warn(
-        'Popover: anchorRef must reference a <button> or [role="button"] element. ' +
+      devWarn(
+        'Popover',
+        'anchorRef must reference a <button> or [role="button"] element. ' +
           'The popover trigger implements the button + dialog ARIA pattern.',
       );
     }
@@ -453,8 +455,9 @@ export function Popover({
     // Find the button inside the wrapper
     const button = findTriggerButton(wrapper);
     if (!button) {
-      console.warn(
-        'Popover: children must contain a <button> or [role="button"] element. ' +
+      devWarn(
+        'Popover',
+        'children must contain a <button> or [role="button"] element. ' +
           'The popover trigger implements the button + dialog ARIA pattern.',
       );
     }

package/src/Popover/usePopover.tsx

@@ -28,6 +28,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
 import {useTranslator} from '../i18n';
+import {useDevWarning} from '../hooks/useDevWarning';
 
 const styles = stylex.create({
   // Default popover surface — background, radius, shadow.
@@ -391,19 +392,14 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
     'aria-controls': layer.id,
   };
 
-  // Dev-time guardrail: a dialog popover should always be labeled. Warn once
-  // per hook instance (in an effect) rather than on every render.
-  const warnedUnnamedDialogRef = useRef(false);
-  useEffect(() => {
-    if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {
-      warnedUnnamedDialogRef.current = true;
-      console.warn(
-        'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' +
-          'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
-          'popups whose content already carries its own role.',
-      );
-    }
-  }, [role, dialogLabel]);
+  // Dev-time guardrail: a dialog popover should always be labeled.
+  useDevWarning(
+    'usePopover',
+    'role="dialog" without a `dialogLabel` renders an unnamed ' +
+      'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
+      'popups whose content already carries its own role.',
+    role === 'dialog' && !dialogLabel,
+  );
 
   // Wrapped render function that includes surface styles and optional hidden close button
   const render = useCallback(

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -83,6 +83,13 @@ export const docs = {
       description:
         'Validation status object with type and optional message.',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        'Icon to display at the start of the input, before any filter tokens. Forwarded to the internal Tokenizer. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly.',
+      slotElements: [{__element: 'Icon', props: {icon: 'search', size: 'sm'}}],
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -235,6 +242,12 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '带有类型和可选消息的验证状态对象。',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        '在输入框开头（筛选 token 之前）显示的图标，转发给内部的 Tokenizer。接受语义图标名称、SVG 图标组件或直接传入 ReactNode。',
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -318,6 +331,7 @@ export const docsDense = {
     isReadOnly: 'Prevent adding, editing, or removing filters.',
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',
+    startIcon: 'Icon at input start, before filter tokens. Forwarded to internal Tokenizer.',
     maxTokenLength: 'Max char length for filter value display in tokens.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID: 'Timezone ID for date formatting (e.g. "America/New_York").',

package/src/PowerSearch/PowerSearch.test.tsx

@@ -16,6 +16,7 @@ import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
+import {TestIcon} from '../__tests__/TestIcon';
 
 // =============================================================================
 // Test infrastructure
@@ -157,6 +158,25 @@ describe('PowerSearch', () => {
     expect(screen.getByRole('combobox')).toHaveFocus();
   });
 
+  describe('startIcon', () => {
+    it('does not render a start icon when omitted', () => {
+      render(<PowerSearch config={config} filters={[]} onChange={() => {}} />);
+      expect(document.querySelector('svg')).not.toBeInTheDocument();
+    });
+
+    it('forwards startIcon to the internal Tokenizer', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          startIcon={<TestIcon data-testid="start-icon" />}
+        />,
+      );
+      expect(screen.getByTestId('start-icon')).toBeInTheDocument();
+    });
+  });
+
   describe('paste behavior', () => {
     it('pasting a field name shows matching field suggestions', async () => {
       const user = userEvent.setup();