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

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -6,7 +6,17 @@ export const docs = {
   name: 'PowerSearch',
   displayName: 'Power Search',
   category: 'Data Input',
-  keywords: ["powersearch","search","searchbar","filter","filterbar","faceted","querybuilder","structured","omnibar"],
+  keywords: [
+    'powersearch',
+    'search',
+    'searchbar',
+    'filter',
+    'filterbar',
+    'faceted',
+    'querybuilder',
+    'structured',
+    'omnibar',
+  ],
   props: [
     {
       name: 'config',
@@ -43,8 +53,7 @@ export const docs = {
     {
       name: 'placeholder',
       type: 'string',
-      description:
-        'Placeholder text shown when no filters are selected.',
+      description: 'Placeholder text shown when no filters are selected.',
       default: "'Search...'",
     },
     {
@@ -80,8 +89,7 @@ export const docs = {
     {
       name: 'status',
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
-      description:
-        'Validation status object with type and optional message.',
+      description: 'Validation status object with type and optional message.',
     },
     {
       name: 'startIcon',
@@ -103,6 +111,26 @@ export const docs = {
       description: 'Max character length for filter value display in tokens.',
       default: '40',
     },
+    {
+      name: 'maxOperatorMenuItems',
+      type: 'number',
+      description:
+        'Maximum suggestions shown in string and entity value typeaheads. Does not affect the main field search menu or enum value menus.',
+      default: '10',
+    },
+    {
+      name: 'maxSearchResults',
+      type: 'number',
+      description:
+        'Max ranked results for a non-empty query. Does not affect a field value editor. Browsing with an empty query shows up to 1,000 fields.',
+      default: '10',
+    },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description:
+        'Width in pixels for the main field/search menu. Does not affect field value editors.',
+    },
     {
       name: 'popoverSaveButtonLabel',
       type: 'string',
@@ -142,6 +170,32 @@ export const docs = {
       description: 'Size of the search input and tokens.',
       default: "'md'",
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: 'Maximum width for the operator/value dropdown menu in pixels.',
+    },
+    {
+      name: 'maxOperatorMenuItems',
+      type: 'number',
+      description: 'Maximum number of items displayed in the operator dropdown.',
+    },
+    {
+      name: 'tokenOverflowBehavior',
+      type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
+      description: 'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
+      default: "'none'",
+    },
+    {
+      name: 'onFocus',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus enters the search input.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus leaves the search input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -153,16 +207,30 @@ export const docs = {
     description:
       'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
     bestPractices: [
-      { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
-      { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
-      { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
-      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Define clear, descriptive field names and aliases so users can quickly find the filter they need.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a result count to give users feedback on how their filters affect the data set.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   theming: {
-    targets: [
-      {className: 'astryx-power-search'},
-    ],
+    targets: [{className: 'astryx-power-search'}],
   },
 };
 
@@ -268,6 +336,25 @@ export const docsZh = {
       description: '令牌中过滤器值显示的最大字符长度。',
       default: '40',
     },
+    {
+      name: 'maxOperatorMenuItems',
+      type: 'number',
+      description:
+        '字符串和实体值预输入菜单中显示的最大建议数。不影响主字段搜索菜单或枚举值菜单。',
+      default: '10',
+    },
+    {
+      name: 'maxSearchResults',
+      type: 'number',
+      description:
+        '非空查询的最大排名结果数。不影响字段值编辑器。使用空查询浏览时最多显示 1,000 个字段。',
+      default: '10',
+    },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: '主字段/搜索菜单的像素宽度。不影响字段值编辑器。',
+    },
     {
       name: 'popoverSaveButtonLabel',
       type: 'string',
@@ -282,7 +369,8 @@ export const docsZh = {
     {
       name: 'handleRef',
       type: 'Ref<PowerSearchHandle>',
-      description: '提供 focusTypeahead() 和 blurTypeahead() 方法的命令式句柄。',
+      description:
+        '提供 focusTypeahead() 和 blurTypeahead() 方法的命令式句柄。',
     },
     {
       name: 'endContent',
@@ -311,10 +399,26 @@ export const docsZh = {
     description:
       'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
     bestPractices: [
-      { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
-      { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
-      { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
-      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Define clear, descriptive field names and aliases so users can quickly find the filter they need.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a result count to give users feedback on how their filters affect the data set.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -327,16 +431,33 @@ export const docsDense = {
     description:
       'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
     bestPractices: [
-      { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
-      { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
-      { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
-      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Define clear, descriptive field names and aliases so users can quickly find the filter they need.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a result count to give users feedback on how their filters affect the data set.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
     config: 'Configuration defining available fields, operators, value types.',
     filters: 'Currently active filters.',
-    onChange: "Called on filter change. changeType is 'add', 'edit', or 'remove'. index is affected filter position.",
+    onChange:
+      "Called on filter change. changeType is 'add', 'edit', or 'remove'. index is affected filter position.",
     label: 'Accessible label for search input.',
     isLabelHidden: 'Visually hides label while keeping accessible.',
     placeholder: 'Text shown when no filters selected.',
@@ -345,15 +466,26 @@ 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.',
+    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.',
+    maxOperatorMenuItems:
+      'Max suggestions in string/entity value typeaheads; excludes main field search + enum menus.',
+    maxSearchResults:
+      'Max ranked results for a non-empty query; excludes value editors.',
+    menuWidth: 'Main field/search menu width in pixels.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID: 'Timezone ID for date formatting (e.g. "America/New_York").',
-    handleRef: 'Imperative handle w/ focusTypeahead() + blurTypeahead() methods.',
-    endContent: 'Content at end of input row. Useful for action buttons or controls.',
-    resultCount: 'Result count matching current filters. Number formatted as "N results"; string displayed as-is.',
+    handleRef:
+      'Imperative handle w/ focusTypeahead() + blurTypeahead() methods.',
+    endContent:
+      'Content at end of input row. Useful for action buttons or controls.',
+    resultCount:
+      'Result count matching current filters. Number formatted as "N results"; string displayed as-is.',
     size: 'Search input+token size.',
-    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+    xstyle:
+      'StyleX styles for layout customization. Must be stylex.create() value.',
   },
 };

package/src/PowerSearch/PowerSearch.test.tsx

@@ -11,7 +11,14 @@
 
 import {useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
-import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
+import {
+  render,
+  screen,
+  act,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -492,3 +499,235 @@ describe('PowerSearch statusVariant forwarding', () => {
     );
   });
 });
+
+describe('maxOperatorMenuItems', () => {
+  it('caps entity suggestions after selecting a field', async () => {
+    const people = Array.from({length: 6}, (_, index) => ({
+      id: `person-${index}`,
+      label: `Person ${index}`,
+    }));
+    const config: PowerSearchConfig = {
+      name: 'PeopleSearch',
+      fields: [
+        {
+          key: 'person',
+          label: 'Person',
+          defaultOperator: 'is_any_of',
+          operators: [
+            {
+              key: 'is_any_of',
+              label: 'is any of',
+              value: {
+                type: 'entity_list',
+                searchSource: {
+                  search: query =>
+                    people.filter(person => person.label.includes(query)),
+                  bootstrap: () => people,
+                },
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const user = userEvent.setup();
+    render(
+      <PowerSearch
+        config={config}
+        filters={[
+          {
+            field: 'person',
+            operator: 'is_any_of',
+            value: {type: 'entity_list', value: [people[0]]},
+          },
+        ]}
+        onChange={() => {}}
+        maxOperatorMenuItems={2}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Person: is any of'}));
+    const inputs = screen.getAllByRole('combobox', {hidden: true});
+    const valueInput = inputs[inputs.length - 1];
+    await user.type(valueInput, 'Person');
+
+    const listboxID = valueInput.getAttribute('aria-controls');
+    expect(listboxID).not.toBeNull();
+    const listbox = document.getElementById(listboxID!);
+    expect(listbox).not.toBeNull();
+    await waitFor(() => {
+      expect(
+        within(listbox!).getAllByRole('option', {hidden: true}),
+      ).toHaveLength(2);
+    });
+  });
+});
+
+describe('field menu sizing', () => {
+  const FIELD_COUNT = 25;
+  const manyFields: PowerSearchConfig = {
+    name: 'ManyFields',
+    fields: Array.from({length: FIELD_COUNT}, (_, i) => ({
+      key: `field_${i}`,
+      label: `Zebra ${String(i).padStart(2, '0')}`,
+      defaultOperator: 'is',
+      operators: [{key: 'is', label: 'is', value: {type: 'string'} as const}],
+    })),
+  };
+
+  async function openMenu(
+    props?: {maxSearchResults?: number; menuWidth?: number},
+    config: PowerSearchConfig = manyFields,
+  ) {
+    const user = userEvent.setup();
+    render(
+      <PowerSearch
+        config={config}
+        filters={[]}
+        onChange={() => {}}
+        {...props}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+    await waitFor(() => {
+      expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();
+    });
+    return user;
+  }
+
+  const optionCount = () =>
+    screen.getAllByRole('option', {hidden: true}).length;
+
+  it('shows every field in a normal field list while browsing', async () => {
+    await openMenu();
+    expect(optionCount()).toBe(FIELD_COUNT);
+  });
+
+  it('caps an extreme field list at the 1,000-row browsing ceiling', async () => {
+    const extremeConfig: PowerSearchConfig = {
+      name: 'ExtremeFields',
+      fields: Array.from({length: 1001}, (_, i) => ({
+        key: `extreme_${i}`,
+        label: `Extreme ${i}`,
+        defaultOperator: 'is',
+        operators: [{key: 'is', label: 'is', value: {type: 'string'} as const}],
+      })),
+    };
+
+    await openMenu(undefined, extremeConfig);
+    expect(optionCount()).toBe(1000);
+  });
+
+  it('caps ranked results while typing', async () => {
+    const user = await openMenu();
+    // "zebra" matches every field label.
+    await user.type(screen.getByRole('combobox'), 'zebra');
+    await waitFor(() => {
+      expect(optionCount()).toBe(10);
+    });
+  });
+
+  it('caps ranked results at maxSearchResults while typing', async () => {
+    const user = await openMenu({maxSearchResults: 3});
+    await user.type(screen.getByRole('combobox'), 'zebra');
+    await waitFor(() => {
+      expect(optionCount()).toBe(3);
+    });
+  });
+
+  it('does not apply maxSearchResults while browsing', async () => {
+    await openMenu({maxSearchResults: 3});
+    expect(optionCount()).toBe(FIELD_COUNT);
+  });
+
+  it('applies menuWidth to the main field menu', async () => {
+    await openMenu({menuWidth: 480});
+    const listbox = screen.getByRole('listbox', {hidden: true});
+    const popover = listbox.closest('[popover]');
+    expect(popover).not.toBeNull();
+    expect((popover as HTMLElement).style.getPropertyValue('--x-width')).toBe(
+      '480px',
+    );
+  });
+});
+
+describe('field menu grouping', () => {
+  const groupedConfig: PowerSearchConfig = {
+    name: 'GroupedSearch',
+    fields: [
+      field('team_a', 'Field Team A', 'Team'),
+      field('plain_a', 'Field Plain A'),
+      field('time_a', 'Field Time A', 'Time'),
+      field('team_b', 'Field Team B', 'Team'),
+      field('plain_b', 'Field Plain B'),
+      field('time_b', 'Field Time B', 'Time'),
+    ],
+  };
+
+  function field(key: string, label: string, group?: string) {
+    return {
+      key,
+      label,
+      group,
+      operators: [{key: 'is', label: 'is', value: {type: 'string'} as const}],
+    };
+  }
+
+  async function openMenu() {
+    const user = userEvent.setup();
+    render(
+      <PowerSearch config={groupedConfig} filters={[]} onChange={() => {}} />,
+    );
+    await user.click(screen.getByRole('combobox'));
+    await waitFor(() => {
+      expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();
+    });
+    return user;
+  }
+
+  it('renders ungrouped fields first and named sections after them', async () => {
+    await openMenu();
+    const listbox = screen.getByRole('listbox', {hidden: true});
+    expect(
+      within(listbox)
+        .getAllByRole('option', {hidden: true})
+        .map(option => option.textContent),
+    ).toEqual([
+      'Field Plain A',
+      'Field Plain B',
+      'Field Team A',
+      'Field Team B',
+      'Field Time A',
+      'Field Time B',
+    ]);
+    expect(
+      within(listbox)
+        .getAllByRole('group', {hidden: true})
+        .map(group => group.getAttribute('aria-label')),
+    ).toEqual(['Team', 'Time']);
+  });
+
+  it('keeps keyboard navigation flat across section boundaries', async () => {
+    const user = await openMenu();
+    const input = screen.getByRole('combobox');
+    await user.keyboard('{ArrowDown}{ArrowDown}');
+    const activeId = input.getAttribute('aria-activedescendant');
+    expect(activeId).not.toBeNull();
+    expect(document.getElementById(activeId!)?.textContent).toBe(
+      'Field Team A',
+    );
+  });
+
+  it('keeps ranked results flat while typing', async () => {
+    const user = await openMenu();
+    await user.type(screen.getByRole('combobox'), 'field');
+    await waitFor(() => {
+      expect(
+        within(screen.getByRole('listbox', {hidden: true})).queryAllByRole(
+          'group',
+          {hidden: true},
+        ),
+      ).toHaveLength(0);
+    });
+  });
+});

package/src/PowerSearch/PowerSearch.tsx

@@ -46,7 +46,6 @@ import {
   typeScaleVars,
   fontWeightVars,
 } from '../theme/tokens.stylex';
-import {mergeRefs} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInternalConfig} from './useInternalConfig';
 import {usePowerSearchSource} from './usePowerSearchSource';
@@ -75,10 +74,19 @@ import type {
   PowerSearchComponents,
 } from './types';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Icon mapping for typeahead entries
 // =============================================================================
 
+// Ranked suggestions shown for a non-empty query. The field list itself is
+// never capped -- see the maxSearchResults prop.
+const DEFAULT_MAX_SEARCH_RESULTS = 10;
+
+// Empty-query browsing gets a high safety ceiling, matching XDS. This shows
+// every practical field list without allowing an accidental unbounded DOM.
+const MAX_BROWSE_MENU_ITEMS = 1000;
+
 const OPERATOR_VALUE_TYPE_TO_ICON: Record<string, IconName> = {
   string: 'search',
   string_list: 'search',
@@ -109,7 +117,12 @@ const tokenValueStyles = stylex.create({
 const popoverLayerStyles = stylex.create({
   layer: {
     width: 'anchor-size(width)',
-    minWidth: 400,
+    // Floor for comfortable editing, yielding when the available inline
+    // space cannot fit it, so the editor stays on-screen at narrow viewport
+    // widths (#4761). Percentages resolve against the position-area region
+    // (anchor start edge to viewport end), falling back to the viewport
+    // where area sizing is not honored.
+    minWidth: `min(400px, calc(100% - ${spacingVars['--spacing-4']}))`,
   },
 });
 
@@ -401,8 +414,14 @@ export interface PowerSearchProps extends Omit<
   menuWidth?: number;
   /** Max display length for filter token values. @default 40 */
   maxTokenLength?: number;
-  /** Max items in operator dropdown. */
+  /** Max suggestions in string and entity value typeaheads. @default 10 */
   maxOperatorMenuItems?: number;
+  /**
+   * Max ranked results shown for a non-empty query. This does not affect the
+   * value editor shown after selecting a field. Browsing the field list with
+   * an empty query shows up to 1,000 fields. @default 10
+   */
+  maxSearchResults?: number;
   /** Label for the save button in edit popover. @default 'Apply' */
   popoverSaveButtonLabel?: string;
   /** Timezone ID for date formatting. */
@@ -542,7 +561,10 @@ export function PowerSearch({
   onBlur,
   status,
   statusVariant = 'attached',
+  menuWidth,
   maxTokenLength = 40,
+  maxOperatorMenuItems,
+  maxSearchResults = DEFAULT_MAX_SEARCH_RESULTS,
   popoverSaveButtonLabel: popoverSaveButtonLabelFromProps,
   timezoneID,
   tokenOverflowBehavior,
@@ -559,7 +581,7 @@ export function PowerSearch({
 }: PowerSearchProps) {
   const size = useSize(sizeProp, 'md');
   const config = useInternalConfig(configProp);
-  const searchSource = usePowerSearchSource(config);
+  const searchSource = usePowerSearchSource(config, maxSearchResults);
   const t = useTranslator();
   const locale = useLocale();
   const label = labelFromProps ?? t('@astryx.powersearch.label');
@@ -962,6 +984,7 @@ export function PowerSearch({
         onSave={handlePopoverSave}
         onCancel={handlePopoverCancel}
         saveButtonLabel={popoverSaveButtonLabel}
+        maxMenuItems={maxOperatorMenuItems}
         isReadOnly={isReadOnly}
       />
     );
@@ -974,6 +997,7 @@ export function PowerSearch({
     handlePopoverSave,
     handlePopoverCancel,
     popoverSaveButtonLabel,
+    maxOperatorMenuItems,
     isReadOnly,
   ]);
 
@@ -1029,7 +1053,10 @@ export function PowerSearch({
   return (
     <>
       <div
-        ref={mergeRefs(ref, popover.triggerRef as React.Ref<HTMLDivElement>)}
+        ref={useMergedRefs(
+          ref,
+          popover.triggerRef as React.Ref<HTMLDivElement>,
+        )}
         {...themeProps('power-search')}>
         <Tokenizer
           handleRef={tokenizerRef}
@@ -1040,6 +1067,8 @@ export function PowerSearch({
           onChange={handleTokenizerChange}
           renderToken={renderToken}
           renderItem={renderItem}
+          maxMenuItems={MAX_BROWSE_MENU_ITEMS}
+          menuWidth={menuWidth}
           placeholder={filters.length === 0 ? placeholder : ''}
           hasAutoFocus={hasAutoFocus}
           hasClear={hasClear && !isReadOnly}