@astryxdesign/core 0.1.8 → 0.1.9-canary.08c278e

package/src/OverflowList/OverflowList.tsx

@@ -9,8 +9,9 @@
  * @position Core implementation; consumed by index.ts
  *
  * Renders a horizontal list of items, hiding those that don't fit in the
- * available width and optionally showing an overflow indicator.
- * Uses a hidden measurement container to avoid flickering.
+ * available width and optionally showing an overflow indicator. Supports an
+ * optional item cap (`maxVisibleItems`) and bounded multi-row wrapping
+ * (`maxRows`). Uses a hidden measurement container to avoid flickering.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/OverflowList/index.ts (exports if types change)
@@ -34,6 +35,14 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     minWidth: 0,
   },
+  containerMultiRow: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignContent: 'flex-start',
+    overflow: 'hidden',
+    whiteSpace: 'normal',
+    minWidth: 0,
+  },
   fillParent: {
     width: '100%',
   },
@@ -52,6 +61,12 @@ const styles = stylex.create({
   },
 });
 
+const multiRowHeight = stylex.create({
+  height: (maxRows: number, rowHeight: number, gapPx: number) => ({
+    maxHeight: `calc(${rowHeight}px * ${maxRows} + ${gapPx}px * ${maxRows - 1})`,
+  }),
+});
+
 const gapStyles = stylex.create({
   0: {gap: spacingVars['--spacing-0']},
   0.5: {gap: spacingVars['--spacing-0-5']},
@@ -112,6 +127,24 @@ export interface OverflowListProps extends BaseProps<HTMLDivElement> {
    */
   minVisibleItems?: number;
 
+  /**
+   * Maximum number of items to ever show, even when they all fit. The ceiling
+   * partner to `minVisibleItems`; extra items collapse into the overflow
+   * indicator. Leave undefined for no cap. If it is less than
+   * `minVisibleItems`, the floor wins (and a dev-only warning is logged).
+   * @default undefined
+   */
+  maxVisibleItems?: number;
+
+  /**
+   * Wrap items across up to this many rows before collapsing the remainder
+   * into the overflow indicator. Leave undefined (or set `1`) for the default
+   * single-line behavior. A number, not a boolean — unbounded wrapping is a
+   * plain flex-wrap layout, not overflow collapse. Assumes uniform row height.
+   * @default undefined
+   */
+  maxRows?: number;
+
   /**
    * Which end to collapse items from.
    * @default 'end'
@@ -180,6 +213,8 @@ export function OverflowList({
   children,
   gap = 2,
   minVisibleItems = 0,
+  maxVisibleItems,
+  maxRows,
   collapseFrom = 'end',
   behavior = 'observeSelf',
   overflowRenderer,
@@ -195,16 +230,17 @@ export function OverflowList({
   const gapPx = spacingToPx[gap];
 
   const observeParent = behavior === 'observeParent';
+  const isMultiRow = maxRows != null && maxRows > 1;
 
-  const {containerRef, measureRef, visibleCount, hasOverflow} = useOverflow(
-    itemCount,
-    {
+  const {containerRef, measureRef, visibleCount, hasOverflow, rowHeight} =
+    useOverflow(itemCount, {
       gap: gapPx,
       minVisibleItems,
+      maxVisibleItems,
+      maxRows,
       collapseFrom,
       behavior,
-    },
-  );
+    });
 
   const allItems: OverflowItem[] = childArray.map((child, index) => ({
     child,
@@ -248,8 +284,12 @@ export function OverflowList({
         {...mergeProps(
           themeProps('overflow-list'),
           stylex.props(
-            styles.container,
+            isMultiRow ? styles.containerMultiRow : styles.container,
             gapStyles[gap],
+            isMultiRow &&
+              rowHeight > 0 &&
+              maxRows != null &&
+              multiRowHeight.height(maxRows, rowHeight, gapPx),
             observeParent && hasOverflow && styles.fillParent,
             xstyle,
           ),

package/src/Pagination/Pagination.tsx

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

package/src/Popover/Popover.tsx

@@ -26,6 +26,7 @@ import React, {
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {mergeProps} from '../utils';
+import {devWarn} from '../utils/devWarning';
 import type {BaseProps} from '../BaseProps';
 import {usePopover} from './usePopover';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
@@ -410,8 +411,9 @@ export function Popover({
 
     const button = findTriggerButton(el);
     if (!button) {
-      console.warn(
-        'Popover: anchorRef must reference a <button> or [role="button"] element. ' +
+      devWarn(
+        'Popover',
+        'anchorRef must reference a <button> or [role="button"] element. ' +
           'The popover trigger implements the button + dialog ARIA pattern.',
       );
     }
@@ -453,8 +455,9 @@ export function Popover({
     // Find the button inside the wrapper
     const button = findTriggerButton(wrapper);
     if (!button) {
-      console.warn(
-        'Popover: children must contain a <button> or [role="button"] element. ' +
+      devWarn(
+        'Popover',
+        'children must contain a <button> or [role="button"] element. ' +
           'The popover trigger implements the button + dialog ARIA pattern.',
       );
     }

package/src/Popover/usePopover.tsx

@@ -28,6 +28,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
 import {useTranslator} from '../i18n';
+import {useDevWarning} from '../hooks/useDevWarning';
 
 const styles = stylex.create({
   // Default popover surface — background, radius, shadow.
@@ -391,19 +392,14 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
     'aria-controls': layer.id,
   };
 
-  // Dev-time guardrail: a dialog popover should always be labeled. Warn once
-  // per hook instance (in an effect) rather than on every render.
-  const warnedUnnamedDialogRef = useRef(false);
-  useEffect(() => {
-    if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {
-      warnedUnnamedDialogRef.current = true;
-      console.warn(
-        'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' +
-          'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
-          'popups whose content already carries its own role.',
-      );
-    }
-  }, [role, dialogLabel]);
+  // Dev-time guardrail: a dialog popover should always be labeled.
+  useDevWarning(
+    'usePopover',
+    'role="dialog" without a `dialogLabel` renders an unnamed ' +
+      'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
+      'popups whose content already carries its own role.',
+    role === 'dialog' && !dialogLabel,
+  );
 
   // Wrapped render function that includes surface styles and optional hidden close button
   const render = useCallback(

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -83,6 +83,20 @@ export const docs = {
       description:
         'Validation status object with type and optional message.',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        'Icon to display at the start of the input, before any filter tokens. Forwarded to the internal Tokenizer. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly.',
+      slotElements: [{__element: 'Icon', props: {icon: 'search', size: 'sm'}}],
+    },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -235,6 +249,19 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '带有类型和可选消息的验证状态对象。',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        '在输入框开头（筛选 token 之前）显示的图标，转发给内部的 Tokenizer。接受语义图标名称、SVG 图标组件或直接传入 ReactNode。',
+    },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -318,6 +345,8 @@ export const docsDense = {
     isReadOnly: 'Prevent adding, editing, or removing filters.',
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',
+    startIcon: 'Icon at input start, before filter tokens. Forwarded to internal Tokenizer.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     maxTokenLength: 'Max char length for filter value display in tokens.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID: 'Timezone ID for date formatting (e.g. "America/New_York").',

package/src/PowerSearch/PowerSearch.test.tsx

@@ -16,6 +16,7 @@ import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
+import {TestIcon} from '../__tests__/TestIcon';
 
 // =============================================================================
 // Test infrastructure
@@ -157,6 +158,25 @@ describe('PowerSearch', () => {
     expect(screen.getByRole('combobox')).toHaveFocus();
   });
 
+  describe('startIcon', () => {
+    it('does not render a start icon when omitted', () => {
+      render(<PowerSearch config={config} filters={[]} onChange={() => {}} />);
+      expect(document.querySelector('svg')).not.toBeInTheDocument();
+    });
+
+    it('forwards startIcon to the internal Tokenizer', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          startIcon={<TestIcon data-testid="start-icon" />}
+        />,
+      );
+      expect(screen.getByTestId('start-icon')).toBeInTheDocument();
+    });
+  });
+
   describe('paste behavior', () => {
     it('pasting a field name shows matching field suggestions', async () => {
       const user = userEvent.setup();
@@ -404,3 +424,26 @@ describe('PowerSearch', () => {
     });
   });
 });
+
+
+describe('PowerSearch statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/PowerSearch/PowerSearch.tsx

@@ -37,7 +37,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
-import type {InputStatus} from '../Field';
+import type {InputStatus, FieldStatusVariant} from '../Field';
 import {usePopover} from '../Popover/usePopover';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {
@@ -383,6 +383,13 @@ export interface PowerSearchProps extends Omit<
   onBlur?: (e: React.FocusEvent) => void;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /** Max width for dropdown menu. */
   menuWidth?: number;
   /** Max display length for filter token values. @default 40 */
@@ -527,6 +534,7 @@ export function PowerSearch({
   onFocus,
   onBlur,
   status,
+  statusVariant = 'attached',
   maxTokenLength = 40,
   popoverSaveButtonLabel: popoverSaveButtonLabelFromProps,
   timezoneID,
@@ -1033,6 +1041,7 @@ export function PowerSearch({
           hasEntriesOnFocus
           debounceMs={0}
           status={status}
+          statusVariant={statusVariant}
           onFocus={onFocus}
           onBlur={onBlur}
           xstyle={xstyle}

package/src/PowerSearch/PowerSearchEditPopover.test.tsx

@@ -13,6 +13,8 @@ import {
 import {render, screen, fireEvent, act} from '@testing-library/react';
 import React, {useState} from 'react';
 import {PowerSearch} from './PowerSearch';
+import {PowerSearchEditPopover} from './PowerSearchEditPopover';
+import {useInternalConfig} from './useInternalConfig';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
 
 // =============================================================================
@@ -216,4 +218,69 @@ describe('PowerSearch', () => {
     expect(popoverText).toContain('Priority');
     expect(popoverText).toContain('equals');
   });
+
+  it('does not save/close edit popover when Enter is consumed by child listbox option selection', () => {
+    const multiConfig: PowerSearchConfig = {
+      name: 'test-multi',
+      fields: [
+        {
+          key: 'status',
+          label: 'Status',
+          operators: [
+            {
+              key: 'any_of',
+              label: 'is any of',
+              value: {
+                type: 'enum_list',
+                values: [
+                  {value: 'open', label: 'Open'},
+                  {value: 'closed', label: 'Closed'},
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const onSave = vi.fn();
+    const onCancel = vi.fn();
+
+    function MultiSelectHarness() {
+      const internalConfig = useInternalConfig(multiConfig);
+      return (
+        <PowerSearchEditPopover
+          config={internalConfig}
+          filter={{
+            field: 'status',
+            operator: 'any_of',
+            value: {type: 'enum_list', value: ['open']},
+          }}
+          mode="edit"
+          onSave={onSave}
+          onCancel={onCancel}
+        />
+      );
+    }
+
+    const {container} = render(<MultiSelectHarness />);
+
+    const input = container.querySelector('input');
+    expect(input).not.toBeNull();
+
+    // Fire an Enter event that has been defaultPrevented (e.g. child typeahead option selection)
+    const enterEvent = new KeyboardEvent('keydown', {
+      key: 'Enter',
+      bubbles: true,
+      cancelable: true,
+    });
+    enterEvent.preventDefault();
+
+    act(() => {
+      input?.dispatchEvent(enterEvent);
+    });
+
+    // onSave should NOT be called because the event was already consumed (defaultPrevented)
+    expect(onSave).not.toHaveBeenCalled();
+  });
 });

package/src/PowerSearch/PowerSearchEditPopover.tsx

@@ -702,7 +702,7 @@ export function PowerSearchEditPopover({
   // Handle Enter to save, Escape to cancel
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
-      if (e.key === 'Enter' && !isSaveDisabled) {
+      if (e.key === 'Enter' && !isSaveDisabled && !e.defaultPrevented) {
         e.preventDefault();
         handleSave();
       } else if (e.key === 'Escape' && !e.defaultPrevented) {

package/src/PowerSearch/usePowerSearchSource.ts

@@ -76,8 +76,7 @@ export function usePowerSearchSource(
 
           // Check each field+operator combo against the query
           for (const op of field.operators) {
-            const combinedLabel =
-              `${field.label} ${opLabel(op)}`.toLowerCase();
+            const combinedLabel = `${field.label} ${opLabel(op)}`.toLowerCase();
             if (combinedLabel.includes(lower)) {
               const id = `${field.key}:${op.key}`;
               if (!seen.has(id)) {

package/src/SelectableCard/SelectableCard.doc.mjs

@@ -27,6 +27,7 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. The selection ring composes on top, so a selected card keeps its shadow.', default: "'none'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},
     {name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},
@@ -71,6 +72,7 @@ export const docsDense = {
     isDisabled: 'disables card',
     padding: 'inner padding',
     variant: 'background color variant',
+    elevation: 'resting shadow depth: none|low|med|high; selection ring composes on top',
     width: 'card width',
     height: 'card height',
     maxWidth: 'max card width',

package/src/SelectableCard/SelectableCard.test.tsx

@@ -85,8 +85,7 @@ describe('SelectableCard', () => {
         label="Disabled"
         isSelected={false}
         onChange={handleChange}
-        isDisabled
-      >
+        isDisabled>
         Content
       </SelectableCard>,
     );
@@ -101,12 +100,55 @@ describe('SelectableCard', () => {
         label="Disabled"
         isSelected={false}
         onChange={handleChange}
-        isDisabled
-      >
+        isDisabled>
         <span>Content</span>
       </SelectableCard>,
     );
     fireEvent.click(screen.getByText('Content'));
     expect(handleChange).not.toHaveBeenCalled();
   });
+
+  describe('elevation', () => {
+    const noop = () => {};
+
+    it('forwards a distinct elevation class to the card for each level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <SelectableCard
+            label="Card"
+            isSelected={false}
+            onChange={noop}
+            elevation={elevation}>
+            Content
+          </SelectableCard>,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('still varies elevation while selected (ring composes with elevation)', () => {
+      const selectedClassFor = (elevation: 'none' | 'med') => {
+        const {container} = render(
+          <SelectableCard
+            label="Card"
+            isSelected
+            onChange={noop}
+            elevation={elevation}>
+            Content
+          </SelectableCard>,
+        );
+        return container.firstElementChild!.className;
+      };
+      // A selected card at 'med' must differ from a selected card at 'none' —
+      // proving the selection ring does not clobber the elevation shadow.
+      expect(selectedClassFor('med')).not.toBe(selectedClassFor('none'));
+    });
+  });
 });