@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Overlay/Overlay.tsx

@@ -17,7 +17,7 @@
 
 import type {ReactNode, Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useOverlay} from './useOverlay';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';
@@ -30,6 +30,7 @@ import type {
   OverlayShowOn,
 } from './OverlayScrim';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export interface OverlayProps extends Pick<
   BaseProps<HTMLDivElement>,
   'xstyle' | 'className' | 'style'
@@ -113,7 +114,7 @@ export function Overlay({
 
   return (
     <div
-      ref={mergeRefs(ref, overlay.containerRef)}
+      ref={useMergedRefs(ref, overlay.containerRef)}
       {...mergeProps(
         themeProps('overlay'),
         stylex.props(overlayScope, overlayContainerStyles.root, xstyle),

package/src/Pagination/Pagination.test.tsx

@@ -613,7 +613,7 @@ describe('Pagination', () => {
       expect(box).toHaveAttribute('aria-valuemax', '10');
     });
 
-    it('commits a typed page on Enter and rejects an over-range entry', async () => {
+    it('commits a typed page on Enter and clamps an over-range entry', async () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
       render(
@@ -633,9 +633,10 @@ describe('Pagination', () => {
       onChange.mockClear();
       await user.clear(box);
       // The box is a NumberInput bounded to [1, totalPages]: an over-max entry
-      // is rejected and never navigates past the last page.
+      // lands on the last page rather than navigating past it.
       await user.type(box, '99{Enter}');
       expect(onChange).not.toHaveBeenCalledWith(99);
+      expect(onChange).toHaveBeenCalledWith(10);
     });
 
     it('commits on blur', async () => {

package/src/Popover/usePopover.tsx

@@ -19,6 +19,7 @@ import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {useLayer, type ContextRenderProps} from '../Layer/useLayer';
 import {useFocusTrap} from '../hooks/useFocusTrap';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   colorVars,
@@ -436,34 +437,36 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
           : surfaceProps.className;
 
       return layer.render(
-        <div
-          ref={contentRef}
-          role={role === 'dialog' ? 'dialog' : undefined}
-          aria-modal={role === 'dialog' && isModal ? true : undefined}
-          aria-label={role === 'dialog' ? dialogLabel : undefined}
-          {...mergeProps(
-            {...surfaceProps, className: surfaceClassName},
-            stylex.props(
-              styles.contentWrapper,
-              hasSurface && styles.surface,
-              xstyle,
-            ),
-          )}>
-          {children}
-          {hasCloseButton && (
-            <div
-              {...stylex.props(
-                styles.closeButtonWrapper,
-                rtlStyles.centerInline('100%'),
-              )}>
-              <Button
-                variant="secondary"
-                label={closeButtonLabel}
-                onClick={layer.hide}
-              />
-            </div>
-          )}
-        </div>,
+        <LayerDepthProvider>
+          <div
+            ref={contentRef}
+            role={role === 'dialog' ? 'dialog' : undefined}
+            aria-modal={role === 'dialog' && isModal ? true : undefined}
+            aria-label={role === 'dialog' ? dialogLabel : undefined}
+            {...mergeProps(
+              {...surfaceProps, className: surfaceClassName},
+              stylex.props(
+                styles.contentWrapper,
+                hasSurface && styles.surface,
+                xstyle,
+              ),
+            )}>
+            {children}
+            {hasCloseButton && (
+              <div
+                {...stylex.props(
+                  styles.closeButtonWrapper,
+                  rtlStyles.centerInline('100%'),
+                )}>
+                <Button
+                  variant="secondary"
+                  label={closeButtonLabel}
+                  onClick={layer.hide}
+                />
+              </div>
+            )}
+          </div>
+        </LayerDepthProvider>,
         {...props, xstyle: props?.xstyle},
       );
     },

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);
+    });
+  });
+});