@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Selector/Selector.test.tsx

@@ -20,8 +20,11 @@ import {
 import userEvent from '@testing-library/user-event';
 import {Selector} from './Selector';
 import {SelectorOption} from './SelectorOption';
+import {Icon} from '../Icon';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -503,6 +506,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(
@@ -694,6 +749,119 @@ describe('Selector', () => {
         expect(politeRegion()?.textContent ?? '').toBe('');
       });
     });
+
+    describe('grouped search', () => {
+      const GROUPED = [
+        {
+          type: 'section' as const,
+          title: 'Citrus',
+          options: [
+            {value: 'orange', label: 'Orange'},
+            {value: 'lemon', label: 'Lemon'},
+          ],
+        },
+        {
+          type: 'section' as const,
+          title: 'Berries',
+          options: [
+            {value: 'strawberry', label: 'Strawberry'},
+            {value: 'blueberry', label: 'Blueberry'},
+          ],
+        },
+      ];
+
+      it('keeps the group header above matching items while searching', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={GROUPED}
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        // "orange" only matches within the Citrus group.
+        await user.type(screen.getByRole('combobox', h), 'orange');
+
+        expect(
+          screen.getByRole('group', {name: 'Citrus', ...h}),
+        ).toBeInTheDocument();
+        const options = screen.getAllByRole('option', h);
+        expect(options).toHaveLength(1);
+        expect(options[0]).toHaveTextContent('Orange');
+      });
+
+      it('hides a group whose items have no match', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={GROUPED}
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        // "berry" only matches items inside the Berries group.
+        await user.type(screen.getByRole('combobox', h), 'berry');
+
+        expect(
+          screen.getByRole('group', {name: 'Berries', ...h}),
+        ).toBeInTheDocument();
+        expect(
+          screen.queryByRole('group', {name: 'Citrus', ...h}),
+        ).not.toBeInTheDocument();
+        expect(screen.getAllByRole('option', h)).toHaveLength(2);
+      });
+
+      it('lands keyboard focus on the correct option after filtering', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={GROUPED}
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        const search = screen.getByRole('combobox', h);
+        // "berry" leaves Strawberry, Blueberry (in that document order).
+        await user.type(search, 'berry');
+        const options = screen.getAllByRole('option', h);
+        expect(options.map(o => o.textContent)).toEqual([
+          'Strawberry',
+          'Blueberry',
+        ]);
+        await user.keyboard('{ArrowDown}');
+        expect(search).toHaveAttribute('aria-activedescendant', options[0].id);
+        await user.keyboard('{ArrowDown}');
+        expect(search).toHaveAttribute('aria-activedescendant', options[1].id);
+      });
+
+      it('shows the empty state when no group has a match', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={GROUPED}
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        await user.type(screen.getByRole('combobox', h), 'zzz');
+        expect(screen.queryAllByRole('option', h)).toHaveLength(0);
+        expect(
+          screen.queryByRole('group', {name: 'Citrus', ...h}),
+        ).not.toBeInTheDocument();
+        const listbox = screen.getByRole('listbox', h);
+        expect(
+          within(listbox).getByText('No results found'),
+        ).toBeInTheDocument();
+      });
+    });
   });
 
   describe('keyboard accessibility', () => {
@@ -722,6 +890,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();
@@ -1004,3 +1189,235 @@ describe('Selector', () => {
     });
   });
 });
+
+describe('Selector statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Selector
+        label="Fruit"
+        options={['Apple', 'Banana']}
+        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(
+      <Selector
+        label="Fruit"
+        options={['Apple', 'Banana']}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});
+
+describe('Selector clear icon theme target', () => {
+  // Resolve the clear glyph span (the astryx-icon element inside the clear
+  // button), independent of the theme target class.
+  const getClearIcon = (): HTMLElement => {
+    const button = screen.getByRole('button', {name: 'Clear Fruit'});
+    const icon = button.querySelector('.astryx-icon');
+    if (icon == null) {
+      throw new Error('clear icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  it('renders the astryx-selector-clear-icon target on the clear glyph', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        hasClear
+      />,
+    );
+    // The stable theme target lands on the icon element itself (not the
+    // button), so a theme can restyle just this glyph (color, size, hover)
+    // via `defineTheme` — a button-level target could not reach the icon's
+    // own color/size.
+    const icon = getClearIcon();
+    expect(icon).toHaveClass('astryx-selector-clear-icon');
+    expect(icon).toHaveClass('astryx-icon');
+  });
+
+  it('keeps the clear button functional alongside the target', () => {
+    const onChange = vi.fn();
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={onChange}
+        hasClear
+      />,
+    );
+    const clear = screen.getByRole('button', {name: 'Clear Fruit'});
+    expect(clear.tagName).toBe('BUTTON');
+    fireEvent.click(clear);
+    expect(onChange).toHaveBeenCalledWith(null);
+  });
+
+  it('renders the default icon (secondary color, sm size) byte-identically', () => {
+    // Pixel-identical default guard: the clear glyph must carry the exact same
+    // StyleX color/size classes as a standalone secondary/sm icon. The added
+    // target class is purely additive — it changes nothing until a theme
+    // targets it.
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        hasClear
+      />,
+    );
+    const icon = getClearIcon();
+
+    const {container: refContainer} = render(
+      <Icon icon="close" size="sm" color="secondary" />,
+    );
+    const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+
+    const styleClasses = (el: HTMLElement) =>
+      el.className
+        .split(' ')
+        .filter(c => c !== 'astryx-selector-clear-icon')
+        .sort();
+
+    expect(styleClasses(icon)).toEqual(styleClasses(refIcon));
+  });
+
+  it('exposes selector-clear-icon so a theme reaches the icon color, size, and hover', () => {
+    // jsdom cannot resolve the @layer cascade, so the DOM-class assertion above
+    // (target lands on the icon element) plus this generation assertion (the
+    // theme emits same-element icon rules in @layer astryx-theme) together
+    // prove the seam: a same-element theme rule wins over the icon's own
+    // base-layer color/size.
+    const theme = defineTheme({
+      name: 'selector-clear-icon-test',
+      components: {
+        'selector-clear-icon': {
+          base: {
+            width: '12px',
+            height: '12px',
+            fontSize: '12px',
+            color: 'var(--color-icon-secondary)',
+            ':hover': {color: 'var(--color-icon-primary)'},
+          },
+        },
+      },
+    });
+    const css = generateThemeCSSFlat(theme);
+    expect(css).toContain('.astryx-selector-clear-icon {');
+    expect(css).toContain('width: 12px');
+    expect(css).toContain('height: 12px');
+    expect(css).toContain('.astryx-selector-clear-icon:hover {');
+    expect(css).toContain('color: var(--color-icon-primary)');
+  });
+});
+
+describe('Selector indicator (chevron) icon theme target', () => {
+  const getIndicatorIcon = (container: HTMLElement): HTMLElement => {
+    // The chevron is the only glyph carrying the indicator target class.
+    const icon = container.querySelector('.astryx-selector-indicator-icon');
+    if (icon == null) {
+      throw new Error('indicator icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  it('renders the astryx-selector-indicator-icon target on the chevron glyph', () => {
+    const {container} = render(
+      <Selector label="Fruit" options={OPTIONS} onChange={() => {}} />,
+    );
+    // The stable theme target lands on the icon element itself (not the trigger
+    // button), so a theme can restyle just this glyph (color, size, hover) —
+    // and each open/closed state — via `defineTheme`. A button-level target
+    // could not reach the icon's own color/size.
+    const icon = getIndicatorIcon(container);
+    expect(icon).toHaveClass('astryx-selector-indicator-icon');
+    expect(icon).toHaveClass('astryx-icon');
+    // Open/closed state is reflected so a theme can target each state alone.
+    expect(icon).toHaveAttribute('data-state', 'collapsed');
+  });
+
+  it('reflects the expanded state on the chevron when the popover is open', async () => {
+    const user = userEvent.setup();
+    const {container} = render(
+      <Selector label="Fruit" options={OPTIONS} onChange={() => {}} />,
+    );
+    await user.click(screen.getByRole('combobox'));
+    await waitFor(() => {
+      expect(getIndicatorIcon(container)).toHaveAttribute(
+        'data-state',
+        'expanded',
+      );
+    });
+  });
+
+  it('renders the default icon (inherit color, sm size) byte-identically', () => {
+    // Pixel-identical default guard: the chevron glyph must carry the exact
+    // same StyleX color/size classes as a standalone inherit/sm icon. The added
+    // target class + data-state are purely additive — they change nothing until
+    // a theme targets them.
+    const {container} = render(
+      <Selector label="Fruit" options={OPTIONS} onChange={() => {}} />,
+    );
+    const icon = getIndicatorIcon(container);
+
+    const {container: refContainer} = render(
+      <Icon icon="chevronDown" size="sm" color="inherit" />,
+    );
+    const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+
+    // Exclude the additive theme-target classes (the stable target + its
+    // reflected state class) so only the StyleX color/size classes remain.
+    const themeTargetClasses = new Set([
+      'astryx-selector-indicator-icon',
+      'collapsed',
+      'expanded',
+    ]);
+    const styleClasses = (el: HTMLElement) =>
+      el.className
+        .split(' ')
+        .filter(c => !themeTargetClasses.has(c))
+        .sort();
+
+    expect(styleClasses(icon)).toEqual(styleClasses(refIcon));
+  });
+
+  it('exposes selector-indicator-icon so a theme reaches the icon size and per-state color', () => {
+    // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+    // above (target lands on the icon element) plus this generation assertion
+    // (the theme emits same-element icon rules in @layer astryx-theme) together
+    // prove the seam: a same-element theme rule wins over the icon's own
+    // base-layer color/size.
+    const theme = defineTheme({
+      name: 'selector-indicator-icon-test',
+      components: {
+        'selector-indicator-icon': {
+          base: {width: '14px', height: '14px', fontSize: '14px'},
+          'state:expanded': {color: 'var(--color-icon-primary)'},
+        },
+      },
+    });
+    const css = generateThemeCSSFlat(theme);
+    expect(css).toContain('.astryx-selector-indicator-icon {');
+    expect(css).toContain('width: 14px');
+    expect(css).toContain('height: 14px');
+    expect(css).toContain('.astryx-selector-indicator-icon.expanded');
+    expect(css).toContain('color: var(--color-icon-primary)');
+  });
+});

package/src/Selector/Selector.tsx

@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
@@ -253,7 +254,7 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
   },
   itemContent: {
@@ -433,6 +434,13 @@ interface SelectorPropsBase<
    * If message is provided, displays a message box below the selector.
    */
   status?: SelectorStatus;
+  /**
+   * 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;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -537,6 +545,21 @@ function DefaultOption({option}: {option: SelectorOptionData}) {
   );
 }
 
+// Case-insensitive substring match for a single option. The one predicate used
+// by both the flat filter (count + keyboard nav) and the grouped renderer, so
+// what is shown while searching stays in lockstep with the announced count.
+function optionMatchesQuery(
+  option: SelectorOptionData,
+  query: string,
+): boolean {
+  if (!query) {
+    return true;
+  }
+  return (option.label ?? option.value)
+    .toLowerCase()
+    .includes(query.toLowerCase());
+}
+
 // Case-insensitive substring filter over the selectable options. Shared by the
 // `filteredItems` memo (rendering) and the search-change handler, which needs
 // the count for the *next* query synchronously to announce it exactly once per
@@ -548,10 +571,7 @@ function filterOptionsByQuery(
   if (!query) {
     return items;
   }
-  const q = query.toLowerCase();
-  return items.filter(item =>
-    (item.label ?? item.value).toLowerCase().includes(q),
-  );
+  return items.filter(item => optionMatchesQuery(item, query));
 }
 
 /**
@@ -588,6 +608,7 @@ export function Selector<T extends SelectorOptionType>(
     placeholder: placeholderFromProps,
     size: sizeProp,
     status,
+    statusVariant = 'attached',
     labelTooltip,
     startIcon,
     htmlName,
@@ -858,10 +879,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'
@@ -934,16 +959,15 @@ export function Selector<T extends SelectorOptionType>(
 
   // Render all options (handling sections/dividers)
   const renderOptions = useCallback(() => {
-    // When search is active, render filtered items flat (no sections/dividers)
-    if (hasSearch && searchQuery) {
-      if (filteredItems.length === 0) {
-        return [
-          <div key="empty" {...stylex.props(styles.emptyState)}>
-            No results found
-          </div>,
-        ];
-      }
-      return filteredItems.map((item, index) => renderItem(item, index));
+    const isSearching = hasSearch && Boolean(searchQuery);
+
+    // Nothing matched across every group/option: show the empty state.
+    if (isSearching && filteredItems.length === 0) {
+      return [
+        <div key="empty" {...stylex.props(styles.emptyState)}>
+          No results found
+        </div>,
+      ];
     }
 
     let flatIndex = 0;
@@ -953,13 +977,27 @@ export function Selector<T extends SelectorOptionType>(
       const option = options[i];
 
       if (isDivider(option)) {
+        // While searching, a standalone divider between groups would orphan
+        // itself once its neighbors are filtered out, so skip it.
+        if (isSearching) {
+          continue;
+        }
         elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
       } else if (isSection(option)) {
         const sectionItems: ReactNode[] = [];
         for (const opt of option.options) {
-          sectionItems.push(renderItem(normalizeOption(opt), flatIndex));
+          const normalized = normalizeOption(opt);
+          if (isSearching && !optionMatchesQuery(normalized, searchQuery)) {
+            continue;
+          }
+          sectionItems.push(renderItem(normalized, flatIndex));
           flatIndex++;
         }
+        // Hide a group entirely (header + wrapper) when none of its items
+        // match the query, so no header is left standing over nothing.
+        if (sectionItems.length === 0) {
+          continue;
+        }
         if (option.title) {
           elements.push(
             <Divider
@@ -975,7 +1013,11 @@ export function Selector<T extends SelectorOptionType>(
           </div>,
         );
       } else if (isOptionData(option)) {
-        elements.push(renderItem(normalizeOption(option), flatIndex));
+        const normalized = normalizeOption(option);
+        if (isSearching && !optionMatchesQuery(normalized, searchQuery)) {
+          continue;
+        }
+        elements.push(renderItem(normalized, flatIndex));
         flatIndex++;
       }
     }
@@ -1004,7 +1046,7 @@ export function Selector<T extends SelectorOptionType>(
             isDisabled && inputWrapperStyles.disabled,
             !selectedItem && styles.triggerPlaceholder,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             inputGroup && groupStyles.inGroup,
             xstyle,
           ),
@@ -1067,7 +1109,17 @@ export function Selector<T extends SelectorOptionType>(
             onClick={handleClear}
             aria-label={t('@astryx.selector.clearLabel', {label})}
             {...stylex.props(styles.clearButton)}>
-            <Icon icon="close" size="sm" color="secondary" />
+            <Icon
+              icon="close"
+              size="sm"
+              color="secondary"
+              // Stable theme target on the clear glyph itself, so a theme can
+              // restyle just this icon (color, size, hover) via `defineTheme`.
+              // Same-element rules in @layer astryx-theme win over the icon's
+              // own base color/size, which a button-level target could not
+              // reach.
+              {...themeProps('selector-clear-icon')}
+            />
           </button>
         )}
         <span
@@ -1083,7 +1135,19 @@ export function Selector<T extends SelectorOptionType>(
               color={STATUS_ICON_COLOR_MAP[status.type]}
             />
           ) : (
-            <Icon icon="chevronDown" size="sm" color="inherit" />
+            <Icon
+              icon="chevronDown"
+              size="sm"
+              color="inherit"
+              // Stable theme target on the chevron glyph itself, so a theme can
+              // restyle just this icon (color, size, hover) — and its
+              // open/closed state — via `defineTheme`. Same-element rules in
+              // @layer astryx-theme win over the icon's own base color/size,
+              // which a button-level target could not reach.
+              {...themeProps('selector-indicator-icon', {
+                state: popover.isOpen ? 'expanded' : 'collapsed',
+              })}
+            />
           )}
         </span>
       </div>
@@ -1150,6 +1214,7 @@ export function Selector<T extends SelectorOptionType>(
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {selectorContent}

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