@astryxdesign/core 0.5.0 → 0.5.1-canary.f64186a

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -860,3 +860,107 @@ describe('TopNavMegaMenu — drawer focus ring', () => {
     expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
   });
 });
+
+describe('TopNavMegaMenu pass-through props', () => {
+  it('forwards pass-through props to the trigger button', () => {
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        aria-label="Products mega menu"
+        id="mega-trigger"
+        data-source="nav"
+      />,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products mega menu'});
+    expect(trigger).toHaveAttribute('id', 'mega-trigger');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+
+  it('forwards pass-through props to the drawer trigger', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu label="Products" id="mega-drawer" data-source="nav" />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('id', 'mega-drawer');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+});
+
+describe('TopNavMegaMenu — owned handlers on the trigger', () => {
+  beforeAll(installPopoverApiMock);
+  afterAll(restorePopoverApiMock);
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("composes a caller's onClick with the trigger's own open behavior", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        onClick={handleClick}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.click(trigger);
+
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it("composes a caller's hover handlers with the trigger's hover-open behavior", async () => {
+    vi.useFakeTimers({shouldAdvanceTime: true});
+    const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+    const handleMouseEnter = vi.fn();
+    const handleMouseLeave = vi.fn();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.hover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(handleMouseEnter).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.unhover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(handleMouseLeave).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it("composes a caller's onClick with the drawer section toggle", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+          onClick={handleClick}
+        />
+      </TopNavRenderContext>,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    await user.click(trigger);
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+});

package/src/TopNav/TopNavMegaMenu.tsx

@@ -53,13 +53,14 @@ import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {Grid} from '../Grid/Grid';
 import {Icon} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
@@ -336,6 +337,7 @@ export function TopNavMegaMenu({
   delay = 150,
   hideDelay = 250,
   onOpenChange,
+  ...rest
 }: TopNavMegaMenuProps) {
   const renderMode = useTopNavRenderMode();
 
@@ -350,7 +352,14 @@ export function TopNavMegaMenu({
   // Drawer mode — inline collapsible
   // =========================================================================
   if (renderMode === 'drawer') {
-    return <DrawerMegaMenu label={label} items={items} featured={featured} />;
+    return (
+      <DrawerMegaMenu
+        label={label}
+        items={items}
+        featured={featured}
+        {...rest}
+      />
+    );
   }
 
   // =========================================================================
@@ -365,6 +374,7 @@ export function TopNavMegaMenu({
       delay={delay}
       hideDelay={hideDelay}
       onOpenChange={onOpenChange}
+      {...rest}
     />
   );
 }
@@ -387,6 +397,13 @@ function DefaultMegaMenu({
   delay = 150,
   hideDelay = 250,
   onOpenChange,
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  onMouseEnter: onMouseEnterProp,
+  onMouseLeave: onMouseLeaveProp,
+  ...rest
 }: TopNavMegaMenuProps) {
   const slot = useTopNavSlot();
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
@@ -454,14 +471,27 @@ function DefaultMegaMenu({
       <button
         ref={useMergedRefs(triggerButtonRef, setTriggerEl, ref)}
         type="button"
+        {...rest}
         {...popover.triggerProps}
         {...hoverTriggerProps}
+        onClick={composeEventHandlers(onClickProp, hoverTriggerProps.onClick)}
+        onMouseEnter={composeEventHandlers(
+          onMouseEnterProp,
+          hoverTriggerProps.onMouseEnter,
+        )}
+        onMouseLeave={composeEventHandlers(
+          onMouseLeaveProp,
+          hoverTriggerProps.onMouseLeave,
+        )}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
           focusOutlineProps.focusVisible(
             styles.trigger,
             popover.isOpen && styles.triggerOpen,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {label}
         <Icon
@@ -513,7 +543,13 @@ function DrawerMegaMenu({
   label,
   items,
   featured,
-}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'>) {
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  ...rest
+}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'> &
+  BaseProps<HTMLButtonElement>) {
   const [isExpanded, setIsExpanded] = useState(false);
   const menuId = `mega-menu-${label.toLowerCase().replace(/\s+/g, '-')}`;
 
@@ -522,15 +558,22 @@ function DrawerMegaMenu({
       {/* Header toggle — same pattern as TopNavMenu drawer */}
       <button
         type="button"
-        onClick={() => setIsExpanded(v => !v)}
+        {...rest}
+        onClick={composeEventHandlers(onClickProp, () =>
+          setIsExpanded(v => !v),
+        )}
         aria-expanded={isExpanded}
         aria-controls={`${menuId}-items`}
         {...mergeProps(
           themeProps('top-nav-mega-menu', {mode: 'drawer'}),
           focusOutlineProps.focusVisible(
             navItemStyles.item,
+            interactionOverlayStyles.backgroundColor,
             styles.drawerHeader,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {label}
         <Icon

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -35,6 +35,7 @@ import type {BaseProps} from '../BaseProps';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 // =============================================================================
 // Styles
@@ -57,13 +58,6 @@ const styles = stylex.create({
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    backgroundColor: {
-      default: 'transparent',
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': colorVars['--color-overlay-hover'],
-      },
-      ':active': colorVars['--color-overlay-pressed'],
-    },
     border: 'none',
     color: 'inherit',
     fontFamily: 'inherit',
@@ -218,7 +212,11 @@ export function TopNavMegaMenuItem({
         {...elementProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu-item', {mode: 'drawer'}),
-          focusOutlineProps.focusVisible(navItemStyles.item, styles.drawerItem),
+          focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            interactionOverlayStyles.backgroundColor,
+            styles.drawerItem,
+          ),
         )}>
         {icon && <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>}
         <div {...stylex.props(styles.drawerItemContent)}>
@@ -245,7 +243,10 @@ export function TopNavMegaMenuItem({
       tabIndex={tabIndex}
       {...mergeProps(
         themeProps('top-nav-mega-menu-item'),
-        focusOutlineProps.focusVisible(styles.desktop),
+        focusOutlineProps.focusVisible(
+          styles.desktop,
+          interactionOverlayStyles.backgroundColor,
+        ),
       )}>
       {icon && <div {...stylex.props(styles.desktopIcon)}>{icon}</div>}
       <div {...stylex.props(styles.desktopContent)}>

package/src/TopNav/TopNavMenu.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import * as stylex from '@stylexjs/stylex';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -212,3 +212,135 @@ describe('TopNavMenu — drawer focus ring', () => {
     expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
   });
 });
+
+describe('TopNavMenu pass-through props', () => {
+  it('forwards pass-through props to the trigger button', () => {
+    render(
+      <TopNavMenu
+        label="Products"
+        items={mockItems}
+        aria-label="Products menu"
+        id="products-trigger"
+        data-source="nav"
+      />,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products menu'});
+    expect(trigger).toHaveAttribute('id', 'products-trigger');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+
+  it('forwards pass-through props to the drawer trigger', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu
+          label="Products"
+          items={mockItems}
+          id="products-drawer"
+          data-source="nav"
+        />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('id', 'products-drawer');
+    expect(trigger).toHaveAttribute('data-source', 'nav');
+  });
+
+  it('keeps its own popup wiring when a caller passes the same attributes', () => {
+    render(
+      <TopNavMenu
+        label="Products"
+        items={mockItems}
+        aria-haspopup="dialog"
+        aria-expanded
+        data-source="nav"
+      />,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    expect({
+      hasPopup: trigger.getAttribute('aria-haspopup'),
+      isExpanded: trigger.getAttribute('aria-expanded'),
+      dataSource: trigger.getAttribute('data-source'),
+    }).toEqual({hasPopup: 'true', isExpanded: 'false', dataSource: 'nav'});
+  });
+});
+
+describe('TopNavMenu — owned handlers on the trigger', () => {
+  it("composes a caller's onClick with the trigger's own open behavior", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavMenu label="Products" items={mockItems} onClick={handleClick} />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.click(trigger);
+
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it("composes a caller's hover handlers with the trigger's hover wiring", async () => {
+    vi.useFakeTimers({shouldAdvanceTime: true});
+    const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+    const handleMouseEnter = vi.fn();
+    const handleMouseLeave = vi.fn();
+    render(
+      <TopNavMenu
+        label="Products"
+        items={mockItems}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.hover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(handleMouseEnter).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.unhover(trigger);
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(handleMouseLeave).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    vi.useRealTimers();
+  });
+
+  it("composes a caller's onClick with the drawer section toggle", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} onClick={handleClick} />
+      </TopNavRenderContext>,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Products/});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    await user.click(trigger);
+    expect(handleClick).toHaveBeenCalledOnce();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('still forwards hover handlers the drawer trigger does not own', async () => {
+    const user = userEvent.setup();
+    const handleMouseEnter = vi.fn();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu
+          label="Products"
+          items={mockItems}
+          onMouseEnter={handleMouseEnter}
+        />
+      </TopNavRenderContext>,
+    );
+
+    await user.hover(screen.getByRole('button', {name: /Products/}));
+    expect(handleMouseEnter).toHaveBeenCalledOnce();
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -29,7 +29,7 @@ import {useMenuHover} from '../hooks/useMenuHover';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
 import {Icon} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
@@ -39,6 +39,7 @@ import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {
   colorVars,
   spacingVars,
@@ -332,6 +333,13 @@ export function TopNavMenu({
   items,
   delay = 150,
   hideDelay = 200,
+  xstyle,
+  className,
+  style,
+  onClick: onClickProp,
+  onMouseEnter: onMouseEnterProp,
+  onMouseLeave: onMouseLeaveProp,
+  ...rest
 }: TopNavMenuProps) {
   const renderMode = useTopNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
@@ -440,12 +448,23 @@ export function TopNavMenu({
       <div {...stylex.props(drawerStyles.section)}>
         <button
           type="button"
-          onClick={() => setDrawerExpanded(v => !v)}
+          {...rest}
+          onMouseEnter={onMouseEnterProp}
+          onMouseLeave={onMouseLeaveProp}
+          onClick={composeEventHandlers(onClickProp, () =>
+            setDrawerExpanded(v => !v),
+          )}
           aria-expanded={drawerExpanded}
           aria-controls={`${menuId}-items`}
-          {...focusOutlineProps.focusVisible(
-            navItemStyles.item,
-            drawerStyles.header,
+          {...mergeProps(
+            focusOutlineProps.focusVisible(
+              navItemStyles.item,
+              interactionOverlayStyles.backgroundColor,
+              drawerStyles.header,
+              xstyle,
+            ),
+            className,
+            style,
           )}>
           {label}
           <Icon
@@ -475,6 +494,7 @@ export function TopNavMenu({
                 }}
                 {...focusOutlineProps.focusVisible(
                   navItemStyles.item,
+                  interactionOverlayStyles.backgroundColor,
                   drawerStyles.item,
                 )}>
                 {item.icon && (
@@ -504,14 +524,27 @@ export function TopNavMenu({
       <button
         ref={setTriggerRef}
         type="button"
+        {...rest}
         {...popover.triggerProps}
         {...triggerProps}
+        onClick={composeEventHandlers(onClickProp, triggerProps.onClick)}
+        onMouseEnter={composeEventHandlers(
+          onMouseEnterProp,
+          triggerProps.onMouseEnter,
+        )}
+        onMouseLeave={composeEventHandlers(
+          onMouseLeaveProp,
+          triggerProps.onMouseLeave,
+        )}
         {...mergeProps(
           themeProps('top-nav-menu'),
           focusOutlineProps.focusVisible(
             styles.trigger,
             popover.isOpen && styles.triggerOpen,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {label}
         <Icon

package/src/TreeList/TreeList.test.tsx

@@ -145,6 +145,18 @@ describe('TreeList', () => {
     expect(screen.getByTestId('tree')).toBeInTheDocument();
   });
 
+  it('forwards aria-label to the tree element', () => {
+    render(<TreeList items={simpleItems} aria-label="File tree" />);
+    const tree = screen.getByRole('tree');
+    expect(tree).toHaveAttribute('aria-label', 'File tree');
+  });
+
+  it('forwards id to the root element', () => {
+    render(<TreeList items={simpleItems} id="file-tree" />);
+    const root = screen.getByRole('tree').parentElement;
+    expect(root).toHaveAttribute('id', 'file-tree');
+  });
+
   it('renders description text', () => {
     const items: TreeListItemData[] = [
       {id: 'a', label: 'Label', description: 'Description text'},
@@ -194,6 +206,43 @@ describe('TreeList', () => {
     expect(tree).not.toHaveAttribute('aria-labelledby');
   });
 
+  it('prefers the visible header id over caller aria-labelledby when header exists', () => {
+    render(
+      <TreeList
+        items={simpleItems}
+        header={<span>File Tree</span>}
+        aria-labelledby="external-label"
+      />,
+    );
+    const tree = screen.getByRole('tree');
+    const headerId = tree.getAttribute('aria-labelledby');
+    expect(headerId).toBeTruthy();
+    expect(headerId).not.toBe('external-label');
+    const headerEl = document.getElementById(headerId!);
+    expect(headerEl?.textContent).toBe('File Tree');
+  });
+
+  it('uses caller aria-labelledby on the headerless path', () => {
+    render(<TreeList items={simpleItems} aria-labelledby="external-label" />);
+    const tree = screen.getByRole('tree');
+    expect(tree).toHaveAttribute('aria-labelledby', 'external-label');
+  });
+
+  it('ignores caller aria-label when a header names the tree', () => {
+    render(
+      <TreeList
+        items={simpleItems}
+        header={<span>File Tree</span>}
+        aria-label="External name"
+      />,
+    );
+    const tree = screen.getByRole('tree');
+    expect(tree).not.toHaveAttribute('aria-label');
+    const headerId = tree.getAttribute('aria-labelledby');
+    const headerEl = document.getElementById(headerId!);
+    expect(headerEl?.textContent).toBe('File Tree');
+  });
+
   // ===========================================================================
   // Expansion (internal state)
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -188,7 +188,10 @@ export function TreeList({
   className,
   style,
   'data-testid': testId,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledby,
   ref,
+  ...restProps
 }: TreeListProps) {
   const headerId = useId();
 
@@ -336,7 +339,8 @@ export function TreeList({
         stylex.props(styles.root, xstyle),
         className,
         style,
-      )}>
+      )}
+      {...restProps}>
       {header != null && (
         <div id={headerId} {...stylex.props(styles.header)}>
           {header}
@@ -345,7 +349,8 @@ export function TreeList({
       <ul
         ref={treeRef}
         role="tree"
-        aria-labelledby={header != null ? headerId : undefined}
+        aria-label={header != null ? undefined : ariaLabel}
+        aria-labelledby={header != null ? headerId : ariaLabelledby}
         onKeyDown={handleKeyDown}
         onFocus={handleFocus}
         {...stylex.props(styles.list)}>

package/src/TreeList/TreeListItem.tsx

@@ -25,6 +25,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {Icon} from '../Icon';
 import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
@@ -102,13 +103,6 @@ const styles = stylex.create({
     transitionProperty: 'background-image',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    backgroundImage: {
-      default: null,
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
-      },
-      ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
-    },
   },
   disabled: {
     cursor: 'default',
@@ -592,6 +586,7 @@ export function TreeListItem({
                   styles.contentWrapper,
                   densityStyles[density],
                   styles.interactive,
+                  interactionOverlayStyles.backgroundImage,
                   isDisabled && styles.disabled,
                   isSelected && styles.selected,
                 )

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -65,6 +65,12 @@ export const docs = {
       type: 'number',
       description: 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',
     },
+    {
+      name: 'minQueryLength',
+      type: 'number',
+      description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
+      default: '1',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -179,6 +185,12 @@ export const docsZh = {
       type: 'number',
       description: '下拉菜单的固定像素宽度。菜单不会小于其锚点宽度。',
     },
+    {
+      name: 'minQueryLength',
+      type: 'number',
+      description: '查询搜索源前的最小查询长度。低于该长度不会发起搜索，菜单保持关闭。',
+      default: '1',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -264,6 +276,7 @@ export const docsDense = {
     hasEntriesOnFocus: 'Bootstrap results on focus.',
     maxMenuItems: 'Max dropdown items.',
     menuWidth: 'Fixed dropdown width in pixels.',
+    minQueryLength: 'Min query length before searching. Menu stays closed below it.',
     emptySearchResultsText: 'Text when no results.',
     isDisabled: 'Whether input disabled.',
     hasAutoFocus: 'Auto-focus on mount.',