@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/NumberInput/NumberInput.tsx

@@ -27,7 +27,6 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   sizeVars,
@@ -39,11 +38,11 @@ import {
 import {
   Field,
   type InputStatus,
-  type InputStatusType,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -51,6 +50,7 @@ import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 
 const styles = stylex.create({
@@ -207,6 +207,14 @@ 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
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @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();
@@ -427,26 +436,26 @@ export function NumberInput({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+      isInGroup: !!inputGroup,
+    });
 
   const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
     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 && statusVariant !== 'tooltip' && status?.message
+        ? statusMessageID
+        : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
+      units ? unitsID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ],
     inputGroup,
@@ -606,7 +615,7 @@ export function NumberInput({
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
-          status && inputStatusHoverShadowStyles[status.type],
+          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
           inputGroup && groupStyles.inGroup,
           xstyle,
@@ -652,7 +661,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
@@ -670,13 +683,7 @@ export function NumberInput({
           <Icon icon="close" size="sm" color="secondary" />
         </button>
       )}
-      {status && !inputGroup && (
-        <Icon
-          icon={statusIconMap[status.type]}
-          size="md"
-          color={statusIconColorMap[status.type]}
-        />
-      )}
+      {statusIcon}
     </div>
   );
 
@@ -710,6 +717,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}

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/Pagination/Pagination.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file Pagination.tsx
- * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button
+ * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
+ *   Reads i18n direction via useDirection() to flip the prev/next chevrons under RTL.
  * @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
  * @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
  *
@@ -40,6 +41,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n/useTranslator';
+import {useDirection} from '../i18n/useDirection';
 
 // =============================================================================
 // Types
@@ -360,6 +362,12 @@ export function Pagination({
   const label = labelFromProps ?? t('@astryx.pagination.label');
   const previousLabel = t('@astryx.pagination.previous');
   const nextLabel = t('@astryx.pagination.next');
+
+  // Directional icons: under RTL, the "previous" control points right and the
+  // "next" control points left. aria-labels stay semantic (unchanged).
+  const direction = useDirection();
+  const previousIcon = direction === 'rtl' ? 'chevronRight' : 'chevronLeft';
+  const nextIcon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
   const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
   const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
 
@@ -663,7 +671,7 @@ export function Pagination({
           label={previousLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon="chevronLeft" size={isSm ? 'sm' : 'md'} />}
+          icon={<Icon icon={previousIcon} size={isSm ? 'sm' : 'md'} />}
           onClick={handlePrevious}
           isDisabled={isDisabled || !hasPrevious}
           isIconOnly
@@ -675,7 +683,7 @@ export function Pagination({
           label={nextLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon="chevronRight" size={isSm ? 'sm' : 'md'} />}
+          icon={<Icon icon={nextIcon} size={isSm ? 'sm' : 'md'} />}
           onClick={handleNext}
           isDisabled={isDisabled || !hasNext}
           isIconOnly

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,20 @@ 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: '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: 'maxTokenLength',
       type: 'number',
@@ -235,6 +249,19 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '带有类型和可选消息的验证状态对象。',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        '在输入框开头（筛选 token 之前）显示的图标，转发给内部的 Tokenizer。接受语义图标名称、SVG 图标组件或直接传入 ReactNode。',
+    },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -318,6 +345,8 @@ 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.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     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").',