@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

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

@@ -14,6 +14,7 @@ import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import React, {useRef} from 'react';
 import {Popover} from './Popover';
+import type {UsePopoverReturn} from './usePopover';
 import {Dialog} from '../Dialog';
 import {SegmentedControl, SegmentedControlItem} from '../SegmentedControl';
 
@@ -55,6 +56,19 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+describe('usePopover public return type', () => {
+  it('keeps dismissal internals out of the public contract', () => {
+    const hasKeepOpenProps: 'keepOpenProps' extends keyof UsePopoverReturn
+      ? true
+      : false = false;
+    const hasDismissalGuard: 'wasJustDismissed' extends keyof UsePopoverReturn
+      ? true
+      : false = false;
+    expect(hasKeepOpenProps).toBe(false);
+    expect(hasDismissalGuard).toBe(false);
+  });
+});
+
 describe('Popover', () => {
   it('renders trigger element', () => {
     render(

package/src/Popover/Popover.tsx

@@ -322,16 +322,12 @@ export function Popover({
 }: PopoverProps): ReactElement {
   const wrapperRef = useRef<HTMLDivElement>(null);
   const isControlled = isOpen !== undefined;
-  // Track when the popover was last hidden by light dismiss to prevent
-  // the trigger click from immediately re-opening it.
-  const lastHideTimeRef = useRef(0);
 
   const handlePopoverShow = useCallback(() => {
     onOpenChange?.(true);
   }, [onOpenChange]);
 
   const handlePopoverHide = useCallback(() => {
-    lastHideTimeRef.current = Date.now();
     onOpenChange?.(false);
   }, [onOpenChange]);
 
@@ -353,11 +349,7 @@ export function Popover({
     if (!isEnabled) {
       return;
     }
-    // If the popover was just closed by light dismiss (clicking outside),
-    // the trigger click fires in the same event — skip re-opening.
-    if (Date.now() - lastHideTimeRef.current < 50) {
-      return;
-    }
+    // `toggle` absorbs a click that belongs to its own light dismiss.
     popover.toggle();
   }, [isEnabled, popover]);
 

package/src/Popover/usePopover.tsx

@@ -5,7 +5,7 @@
 /**
  * @file usePopover.tsx
  * @input Uses useLayer, useFocusTrap, React hooks
- * @output Exports usePopover hook for popover dialogs with focus trapping
+ * @output Exports usePopover and a package-internal trigger-aware variant.
  * @position Higher-level layer utility; used by DatePicker, Combobox, etc.
  *
  * Combines popover layer behavior with focus trap for dialog-like popovers.
@@ -17,8 +17,9 @@
 
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {useLayer, type ContextRenderProps} from '../Layer/useLayer';
+import {useLayerInternal, type ContextRenderProps} from '../Layer/useLayer';
 import {useFocusTrap} from '../hooks/useFocusTrap';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   colorVars,
@@ -282,6 +283,10 @@ export interface UsePopoverReturn {
   };
 }
 
+interface InternalUsePopoverReturn extends UsePopoverReturn {
+  wasJustDismissed: () => boolean;
+}
+
 /**
  * Hook for creating popover dialogs with focus trapping.
  *
@@ -322,7 +327,9 @@ export interface UsePopoverReturn {
  * }
  * ```
  */
-export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
+function usePopoverImplementation(
+  options: UsePopoverOptions = {},
+): InternalUsePopoverReturn {
   const {
     onShow,
     onHide,
@@ -350,7 +357,7 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
   const skipAutoFocusRef = useRef(false);
 
   // Core layer for popover positioning
-  const layer = useLayer({
+  const layer = useLayerInternal({
     mode: 'context',
     lightDismiss: hasLightDismiss,
     onShow,
@@ -399,6 +406,9 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
 
   // Toggle function
   const toggle = useCallback(() => {
+    if (layer.wasJustDismissed()) {
+      return;
+    }
     if (layer.isOpen) {
       layer.hide();
     } else {
@@ -436,34 +446,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},
       );
     },
@@ -488,9 +500,22 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
     show,
     hide: layer.hide,
     toggle,
+    wasJustDismissed: layer.wasJustDismissed,
     isOpen: layer.isOpen,
     id: layer.id,
     render,
     triggerProps,
   };
 }
+
+export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
+  const {wasJustDismissed: _, ...popover} = usePopoverImplementation(options);
+  return popover;
+}
+
+/** @internal Used by trigger components; not exported from package barrels. */
+export function usePopoverInternal(
+  options: UsePopoverOptions = {},
+): InternalUsePopoverReturn {
+  return usePopoverImplementation(options);
+}

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.',
   },
 };