@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

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

package/src/SelectableCard/SelectableCard.tsx

@@ -14,6 +14,7 @@
  * - /apps/storybook/stories/SelectableCard.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Card/SelectableCardShowcase.tsx (showcase block)
  * - /packages/cli/templates/blocks/components/Card/SelectableCardMulti.tsx (block)
+ * - /packages/cli/templates/blocks/components/Card/SelectableCardElevated.tsx (block)
  *
  * Composes Card for all visual styling. Adds selection state with
  * an inset box-shadow (zero layout jitter) and useClickableContainer
@@ -36,7 +37,7 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
@@ -103,51 +104,54 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     borderWidth: 0,
   },
-  // Selection indicator — inset box-shadow for the thick inner ring (zero layout
-  // jitter) plus borderColor change on the card's own border for a cohesive look.
+  // Selection indicator — an inset ring drawn via the card's --_card-ring
+  // shadow slot (zero layout jitter) plus a borderColor change on the card's
+  // own border for a cohesive look. Routing the ring through --_card-ring
+  // (rather than box-shadow directly) lets it compose with the card's
+  // elevation instead of clobbering it.
   selected: {
     borderColor: colorVars['--color-accent'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-accent']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-accent']}`,
   },
   selectedBlue: {
     borderColor: colorVars['--color-border-blue'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-blue']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-blue']}`,
   },
   selectedCyan: {
     borderColor: colorVars['--color-border-cyan'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-cyan']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-cyan']}`,
   },
   selectedGray: {
     borderColor: colorVars['--color-border-gray'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-gray']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-gray']}`,
   },
   selectedGreen: {
     borderColor: colorVars['--color-border-green'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-green']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-green']}`,
   },
   selectedOrange: {
     borderColor: colorVars['--color-border-orange'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-orange']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-orange']}`,
   },
   selectedPink: {
     borderColor: colorVars['--color-border-pink'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-pink']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-pink']}`,
   },
   selectedPurple: {
     borderColor: colorVars['--color-border-purple'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-purple']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-purple']}`,
   },
   selectedRed: {
     borderColor: colorVars['--color-border-red'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-red']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-red']}`,
   },
   selectedTeal: {
     borderColor: colorVars['--color-border-teal'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-teal']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-teal']}`,
   },
   selectedYellow: {
     borderColor: colorVars['--color-border-yellow'],
-    boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-yellow']}`,
+    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-yellow']}`,
   },
 });
 
@@ -228,6 +232,13 @@ export interface SelectableCardProps extends Omit<BaseProps, 'onChange'> {
    */
   variant?: CardVariant;
 
+  /**
+   * Resting elevation — the shadow depth the card sits at.
+   * The selection ring composes on top, so a selected card keeps its shadow.
+   * @default 'none'
+   */
+  elevation?: Elevation;
+
   /** Width of the card. */
   width?: SizeValue;
 
@@ -278,6 +289,7 @@ export function SelectableCard({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   width,
   height,
   maxWidth,
@@ -328,6 +340,7 @@ export function SelectableCard({
       maxWidth={maxWidth}
       padding={padding}
       variant={variant}
+      elevation={elevation}
       {...mergeProps(
         themeProps('selectable-card', {
           variant,

package/src/Selector/Selector.test.tsx

@@ -503,6 +503,58 @@ describe('Selector', () => {
       expect(search).toHaveAttribute('aria-activedescendant');
     });
 
+    it('PageDown/PageUp jump the highlight to the last/first filtered option', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Apple"
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      const search = screen.getByRole('combobox', h);
+      // Filter to Apple and Banana so "last" means last *visible* option.
+      await user.type(search, 'a');
+      const options = screen.getAllByRole('option', h);
+      expect(options).toHaveLength(2);
+      await user.keyboard('{PageDown}');
+      expect(search).toHaveAttribute(
+        'aria-activedescendant',
+        options[options.length - 1].id,
+      );
+      await user.keyboard('{PageUp}');
+      expect(search).toHaveAttribute('aria-activedescendant', options[0].id);
+    });
+
+    it('Home/End move the search caret, not the option highlight', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Apple"
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      const search = screen.getByRole<HTMLInputElement>('combobox', h);
+      await user.type(search, 'an');
+      expect(search.selectionStart).toBe(2);
+      const activeBefore = search.getAttribute('aria-activedescendant');
+      // Home/End stay on the input for caret movement (APG editable
+      // combobox); the option highlight must not move.
+      await user.keyboard('{Home}');
+      expect(search.selectionStart).toBe(0);
+      expect(search.getAttribute('aria-activedescendant')).toBe(activeBefore);
+      await user.keyboard('{End}');
+      expect(search.selectionStart).toBe(2);
+      expect(search.getAttribute('aria-activedescendant')).toBe(activeBefore);
+    });
+
     it('does not render search input when hasSearch is false', async () => {
       const user = userEvent.setup();
       render(
@@ -722,6 +774,23 @@ describe('Selector', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
     });
 
+    it('End/Home jump the highlight to the last/first option (non-search)', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.click(trigger);
+      const options = screen.getAllByRole('option', h);
+
+      await user.keyboard('{End}');
+      expect(trigger).toHaveAttribute(
+        'aria-activedescendant',
+        options[options.length - 1].id,
+      );
+      await user.keyboard('{Home}');
+      expect(trigger).toHaveAttribute('aria-activedescendant', options[0].id);
+    });
+
     it('opens and selects an option with Enter (no mouse)', async () => {
       const user = userEvent.setup();
       const onChange = vi.fn();

package/src/Selector/Selector.tsx

@@ -858,10 +858,14 @@ export function Selector<T extends SelectorOptionType>(
           onChange={handleSearchChange}
           onKeyDown={e => {
             // Arrow keys navigate options; Enter selects; Escape/Tab close.
-            // Home/End are left to the input for caret movement.
+            // Home/End are left to the input for caret movement (APG editable
+            // combobox); PageUp/PageDown are the sanctioned substitute for
+            // jumping to the first/last option.
             if (
               e.key === 'ArrowDown' ||
               e.key === 'ArrowUp' ||
+              e.key === 'PageUp' ||
+              e.key === 'PageDown' ||
               e.key === 'Enter' ||
               e.key === 'Escape' ||
               e.key === 'Tab'

package/src/Selector/SelectorOption.doc.mjs

@@ -20,7 +20,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon displayed before the label. See `npx astryx docs icons` for valid semantic names.',
+        'Icon displayed before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'description',

package/src/Selector/hooks.ts

@@ -318,6 +318,23 @@ export function useCombobox({
           }
           break;
 
+        // PageUp/PageDown mirror Home/End. In search mode Home/End stay on
+        // the input for caret movement (APG editable combobox), so these are
+        // the sanctioned substitute for jumping to the first/last option.
+        case 'PageUp':
+          e.preventDefault();
+          if (isOpen && enabledIndices.length > 0) {
+            setHighlightedIndex(enabledIndices[0]);
+          }
+          break;
+
+        case 'PageDown':
+          e.preventDefault();
+          if (isOpen && enabledIndices.length > 0) {
+            setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
+          }
+          break;
+
         case 'Delete':
         case 'Backspace':
           // Keyboard equivalent of the clear button (comboboxes-2): clear the