@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

package/src/Selector/Selector.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file Selector.test.tsx
  * @input Uses vitest, @testing-library/react, @testing-library/user-event
- * @output Unit tests for Selector
+ * @output Unit tests for Selector behavior and selected-item geometry
  * @position Tests; validates Selector behavior
  *
  * SYNC: When Selector.tsx API changes, update these tests.
@@ -18,24 +18,28 @@ import {
   within,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {useState} from 'react';
 import {Selector} from './Selector';
 import {SelectorOption} from './SelectorOption';
 import {Icon} from '../Icon';
+import {RadioIndicator} from '../Indicator';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 import {defineTheme} from '../theme/defineTheme';
+import {Theme} from '../theme/Theme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
+import {spacingVars} from '../theme/tokens.stylex';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
   return [prose, component].filter(Boolean).join('\n\n');
 }
-function politeRegion(): HTMLElement | null {
-  return document.querySelector('[data-astryx-live-region="polite"]');
-}
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
+  // The live regions are a document-level singleton; start each test clean.
+  __resetLiveRegionsForTest();
   HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
     this.setAttribute('popover-open', '');
     const event = new Event('toggle', {bubbles: false});
@@ -70,6 +74,23 @@ const h = {hidden: true} as const;
 
 const OPTIONS = ['Apple', 'Banana', 'Cherry'];
 
+// Mirrors useTypeahead's default resetMs — how long the typed buffer survives.
+const TYPEAHEAD_RESET_MS = 750;
+
+const politeRegion = () =>
+  document.querySelector('[data-astryx-live-region="polite"]');
+
+/**
+ * Type onto an element with no awaits between keystrokes. Typeahead only
+ * accumulates while keys land inside the reset window, so an awaited
+ * `user.keyboard` per character would put CI stalls on the critical path.
+ */
+function type(text: string, element: HTMLElement) {
+  for (const key of text) {
+    fireEvent.keyDown(element, {key});
+  }
+}
+
 function rect({
   top,
   bottom,
@@ -98,36 +119,103 @@ function rect({
   };
 }
 
-function mockSelectorRects() {
+function mockSelectorRects({
+  anchor = rect({top: 160, bottom: 190, height: 30}),
+  trigger = rect({top: 160, bottom: 190, height: 30}),
+  listbox = rect({top: 190, bottom: 310, height: 120}),
+  selectedItem = rect({top: 220, bottom: 250, height: 30}),
+  listboxLayoutHeight = listbox.height,
+  selectedItemLayoutTop = selectedItem.top - listbox.top,
+  selectedItemLayoutHeight = selectedItem.height,
+  viewportHeight = 200,
+}: {
+  anchor?: DOMRect;
+  trigger?: DOMRect;
+  listbox?: DOMRect;
+  selectedItem?: DOMRect;
+  listboxLayoutHeight?: number;
+  selectedItemLayoutTop?: number;
+  selectedItemLayoutHeight?: number;
+  viewportHeight?: number;
+} = {}) {
   const originalGetBoundingClientRect =
     HTMLElement.prototype.getBoundingClientRect;
   const originalInnerHeight = Object.getOwnPropertyDescriptor(
     window,
     'innerHeight',
   );
+  const originalOffsetTop = Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    'offsetTop',
+  );
+  const originalOffsetHeight = Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    'offsetHeight',
+  );
   HTMLElement.prototype.getBoundingClientRect = function () {
+    if (this.classList.contains('astryx-selector')) {
+      return anchor;
+    }
     // The trigger is role="combobox" by default, or a plain button with
     // aria-haspopup="listbox" in hasSearch mode — match either.
     if (
       this.getAttribute('role') === 'combobox' ||
       this.getAttribute('aria-haspopup') === 'listbox'
     ) {
-      return rect({top: 160, bottom: 190, height: 30});
+      return trigger;
     }
     if (this.getAttribute('role') === 'listbox') {
-      return rect({top: 190, bottom: 310, height: 120});
+      return listbox;
     }
     if (this.id.endsWith('-item-1')) {
-      return rect({top: 220, bottom: 250, height: 30});
+      return selectedItem;
     }
     return originalGetBoundingClientRect.call(this);
   };
+  Object.defineProperty(HTMLElement.prototype, 'offsetTop', {
+    configurable: true,
+    get() {
+      if (this.getAttribute('role') === 'listbox') {
+        return 0;
+      }
+      if (this.id.endsWith('-item-1')) {
+        return selectedItemLayoutTop;
+      }
+      return 0;
+    },
+  });
+  Object.defineProperty(HTMLElement.prototype, 'offsetHeight', {
+    configurable: true,
+    get() {
+      if (this.getAttribute('role') === 'listbox') {
+        return listboxLayoutHeight;
+      }
+      if (this.id.endsWith('-item-1')) {
+        return selectedItemLayoutHeight;
+      }
+      return 0;
+    },
+  });
   Object.defineProperty(window, 'innerHeight', {
-    value: 200,
+    value: viewportHeight,
     configurable: true,
   });
   return () => {
     HTMLElement.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+    if (originalOffsetTop) {
+      Object.defineProperty(
+        HTMLElement.prototype,
+        'offsetTop',
+        originalOffsetTop,
+      );
+    }
+    if (originalOffsetHeight) {
+      Object.defineProperty(
+        HTMLElement.prototype,
+        'offsetHeight',
+        originalOffsetHeight,
+      );
+    }
     if (originalInnerHeight) {
       Object.defineProperty(window, 'innerHeight', originalInnerHeight);
     }
@@ -152,6 +240,60 @@ describe('Selector', () => {
     expect(screen.getByRole('combobox')).toHaveTextContent('Banana');
   });
 
+  it('draws the selected mark through the check indicator', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+      />,
+    );
+
+    const selected = screen.getByRole('option', {name: /Banana/, hidden: true});
+    // The default check indicator IS the glyph — no wrapper element, so the
+    // host's theme target sits on the same node as astryx-icon.
+    const mark = selected.querySelector('.astryx-selector-check');
+    expect(mark).not.toBeNull();
+    expect(mark).toHaveClass('astryx-icon');
+  });
+
+  it('lets a theme replace the mark with a radio, which draws when unselected too', () => {
+    // The point of the indicator layer: one theme entry, and every
+    // single-selection mark becomes a radio — including the empty circle on
+    // rows that are NOT selected, which a check-only mark never drew.
+    const theme = defineTheme({
+      name: 'selector-radio-mark-test',
+      indicators: {check: RadioIndicator},
+    });
+
+    render(
+      <Theme theme={theme}>
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={() => {}}
+        />
+      </Theme>,
+    );
+
+    const options = screen.getAllByRole('option', {hidden: true});
+    expect(options.length).toBeGreaterThan(1);
+
+    // Every row has a radio, selected or not.
+    for (const option of options) {
+      expect(option.querySelector('.astryx-radio')).not.toBeNull();
+    }
+
+    // And exactly the selected one is filled.
+    const filled = options.filter(
+      o => o.querySelector('.astryx-radio-dot') != null,
+    );
+    expect(filled).toHaveLength(1);
+    expect(filled[0]).toHaveTextContent('Banana');
+  });
+
   it('renders custom option endContent', async () => {
     const user = userEvent.setup();
     render(
@@ -265,6 +407,81 @@ describe('Selector', () => {
     }
   });
 
+  it('aligns the selected item using untransformed layout geometry', async () => {
+    const restoreRects = mockSelectorRects({
+      anchor: rect({top: 160, bottom: 192, height: 32}),
+      trigger: rect({top: 166, bottom: 186, height: 20}),
+      // Simulate the 0.95 entry scale in visual rects while retaining the
+      // untransformed 120px list / 36px item offset used for positioning.
+      listbox: rect({top: 190, bottom: 304, height: 114}),
+      selectedItem: rect({
+        top: 224.2,
+        bottom: 254.6,
+        height: 30.4,
+      }),
+      listboxLayoutHeight: 120,
+      selectedItemLayoutTop: 36,
+      selectedItemLayoutHeight: 32,
+      viewportHeight: 900,
+    });
+    const user = userEvent.setup();
+    try {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={() => {}}
+        />,
+      );
+
+      await user.click(screen.getByRole('combobox'));
+      const popover = screen
+        .getByRole('listbox', {hidden: true})
+        .closest('[popover]');
+      await waitFor(() => {
+        // 68px geometric alignment plus the 1px optical correction.
+        expect(popover?.getAttribute('style')).toContain(
+          'margin-block-start: -69px',
+        );
+      });
+    } finally {
+      restoreRects();
+    }
+  });
+
+  it('adds the border inset only to input-variant dropdowns', async () => {
+    const user = userEvent.setup();
+    const {unmount} = render(
+      <Selector
+        label="Input fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+      />,
+    );
+
+    await user.click(screen.getByRole('combobox'));
+    const inputDropdownClass = screen.getByRole('listbox', h).className;
+    unmount();
+
+    render(
+      <Selector
+        label="Ghost fruit"
+        options={OPTIONS}
+        value="Banana"
+        variant="ghost"
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+    const ghostDropdownClass = screen.getByRole('listbox', h).className;
+
+    // The bordered input gets one extra StyleX rule for its border-width
+    // correction; the borderless ghost keeps the base menu inset.
+    expect(inputDropdownClass).not.toBe(ghostDropdownClass);
+  });
+
   it('does not apply selected-item overlay offset when placement is explicit', async () => {
     const restoreRects = mockSelectorRects();
     const user = userEvent.setup();
@@ -293,6 +510,89 @@ describe('Selector', () => {
     }
   });
 
+  describe('menu clearance', () => {
+    it('clears the trigger by the standard menu offset when placement is explicit', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={() => {}}
+          placement="above"
+        />,
+      );
+
+      await user.click(screen.getByRole('combobox'));
+      const popover = screen
+        .getByRole('listbox', {hidden: true})
+        .closest('[popover]') as HTMLElement;
+      // Both block edges, so the gap survives a position-try-fallbacks flip
+      // to the opposite side (#4803).
+      await waitFor(() => {
+        expect(popover.style.getPropertyValue('--x-marginBlockStart')).toBe(
+          spacingVars['--spacing-1'],
+        );
+      });
+      expect(popover.style.getPropertyValue('--x-marginBlockEnd')).toBe(
+        spacingVars['--spacing-1'],
+      );
+    });
+
+    it('clears the trigger in search mode', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+
+      // In hasSearch mode the trigger is a plain button, not a combobox.
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      const popover = screen
+        .getByRole('listbox', {hidden: true})
+        .closest('[popover]') as HTMLElement;
+      await waitFor(() => {
+        expect(popover.style.getPropertyValue('--x-marginBlockStart')).toBe(
+          spacingVars['--spacing-1'],
+        );
+      });
+    });
+
+    it('stays flush in the default selected-item overlay', async () => {
+      const restoreRects = mockSelectorRects();
+      const user = userEvent.setup();
+      try {
+        render(
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Banana"
+            onChange={() => {}}
+          />,
+        );
+
+        await user.click(screen.getByRole('combobox'));
+        const popover = screen
+          .getByRole('listbox', {hidden: true})
+          .closest('[popover]') as HTMLElement;
+        await waitFor(() => {
+          expect(popover.getAttribute('style')).toContain(
+            'margin-block-start: -110px',
+          );
+        });
+        expect(popover.style.getPropertyValue('--x-marginBlockStart')).toBe('');
+        expect(popover.style.getPropertyValue('--x-marginBlockEnd')).toBe('');
+      } finally {
+        restoreRects();
+      }
+    });
+  });
+
   describe('hasClear', () => {
     it('shows selected value label when hasClear is enabled', () => {
       render(
@@ -988,101 +1288,627 @@ describe('Selector', () => {
     });
   });
 
-  describe('InputGroup integration', () => {
-    it('uses the group Field chrome and composes group and selector labels', () => {
-      render(
-        <InputGroup
-          label="Destination"
-          description="Where the alert should route"
-          status={{type: 'error', message: 'Destination is required'}}>
-          <InputGroupText>#</InputGroupText>
-          <Selector
-            label="Channel"
-            isLabelHidden
-            options={OPTIONS}
-            placeholder="Choose a channel"
-          />
-        </InputGroup>,
-      );
+  describe('typeahead', () => {
+    it('selects the matching option by typing on the closed trigger', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(<Selector label="Fruit" options={OPTIONS} onChange={onChange} />);
 
-      const group = screen.getByRole('group', {name: 'Destination'});
-      const groupLabelID = group.getAttribute('aria-labelledby');
-      const trigger = screen.getByRole('combobox', {
-        name: 'Destination Channel',
-      });
-      const labelledByIDs =
-        trigger.getAttribute('aria-labelledby')?.split(' ') ?? [];
+      await user.tab();
+      await user.keyboard('c');
 
-      expect(labelledByIDs).toHaveLength(2);
-      expect(labelledByIDs[0]).toBe(groupLabelID);
-      expect(document.getElementById(labelledByIDs[1])).toHaveTextContent(
-        'Channel',
-      );
-      expect(trigger).toHaveAttribute(
-        'aria-describedby',
-        group.getAttribute('aria-describedby'),
+      expect(onChange).toHaveBeenCalledWith('Cherry');
+      // Native select parity: the value changes without opening the menu.
+      expect(screen.getByRole('combobox')).toHaveAttribute(
+        'aria-expanded',
+        'false',
       );
-      expect(screen.getByText('#')).toBeInTheDocument();
     });
 
-    it('keeps disabled reasons described when grouped', () => {
-      render(
-        <InputGroup label="Destination">
-          <InputGroupText>#</InputGroupText>
+    it('cycles through options sharing a first letter on repeated presses', async () => {
+      const user = userEvent.setup();
+      function Harness() {
+        const [value, setValue] = useState<string | undefined>(undefined);
+        return (
           <Selector
-            label="Channel"
-            isLabelHidden
-            options={OPTIONS}
-            isDisabled
-            disabledMessage="Choose a project first"
+            label="City"
+            options={['Austin', 'Chicago', 'Cleveland', 'Columbus']}
+            value={value}
+            onChange={setValue}
           />
-        </InputGroup>,
-      );
+        );
+      }
+      render(<Harness />);
 
-      const trigger = screen.getByRole('combobox', {
-        name: 'Destination Channel',
-      });
-      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      await user.keyboard('c');
+      expect(screen.getByRole('combobox')).toHaveTextContent('Chicago');
+      await user.keyboard('c');
+      expect(screen.getByRole('combobox')).toHaveTextContent('Cleveland');
+      await user.keyboard('c');
+      expect(screen.getByRole('combobox')).toHaveTextContent('Columbus');
+      // Wraps back around past non-matching options.
+      await user.keyboard('c');
+      expect(screen.getByRole('combobox')).toHaveTextContent('Chicago');
+    });
 
-      expect(trigger).not.toBeDisabled();
-      expect(trigger).toHaveAttribute('aria-disabled', 'true');
-      expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);
+    it('advances past the current selection on a fresh single-letter press', async () => {
+      const user = userEvent.setup();
+      function Harness() {
+        const [value, setValue] = useState<string | undefined>('Chicago');
+        return (
+          <Selector
+            label="City"
+            options={['Austin', 'Chicago', 'Cleveland', 'Columbus']}
+            value={value}
+            onChange={setValue}
+          />
+        );
+      }
+      render(<Harness />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      // Native select parity: the selected option's own initial moves on to
+      // the next match. Anchoring the search AT the selection instead of after
+      // it re-matches the current value, and the duplicate-select guard then
+      // swallows the keystroke entirely.
+      type('c', trigger);
+
+      expect(trigger).toHaveTextContent('Cleveland');
     });
-  });
 
-  describe('disabledMessage', () => {
-    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+    it('advances the highlight past the current one with the menu open', async () => {
+      const user = userEvent.setup();
       render(
         <Selector
-          label="Fruit"
-          options={OPTIONS}
-          isDisabled
-          disabledMessage="You need the Editor role"
-          data-testid="fruit-selector"
+          label="City"
+          options={['Austin', 'Chicago', 'Cleveland', 'Columbus']}
+          value="Chicago"
+          onChange={() => {}}
         />,
       );
 
-      const container = screen.getByTestId('fruit-selector');
-      const tooltip = screen.getByRole('tooltip', h);
-      expect(tooltip).toHaveTextContent('You need the Editor role');
-
-      fireEvent.mouseEnter(container);
-      await waitFor(() => {
-        expect(tooltip).toHaveAttribute('popover-open');
-      });
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      await user.keyboard('{Enter}'); // opens with the highlight on Chicago
+      type('c', trigger);
 
-      fireEvent.mouseLeave(container);
-      await waitFor(() => {
-        expect(tooltip).not.toHaveAttribute('popover-open');
-      });
+      const activeId = trigger.getAttribute('aria-activedescendant');
+      expect(document.getElementById(activeId ?? '')).toHaveTextContent(
+        'Cleveland',
+      );
     });
 
-    it('shows the reason tooltip on keyboard focus', async () => {
+    it('treats a space mid-buffer as part of the match, not as open', async () => {
       const user = userEvent.setup();
+      const onChange = vi.fn();
       render(
         <Selector
-          label="Fruit"
-          options={OPTIONS}
+          label="State"
+          options={['New Jersey', 'New York']}
+          onChange={onChange}
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      // Synchronous keydowns: the buffer only accumulates while keystrokes
+      // land inside the TYPEAHEAD_RESET_MS window, and awaiting between them
+      // would put a CI stall on the critical path.
+      type('new y', trigger);
+
+      expect(onChange).toHaveBeenLastCalledWith('New York');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('opens and seeds the search input when typing on a closed hasSearch trigger', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} hasSearch />);
+
+      await user.tab();
+      await user.keyboard('c');
+
+      const search = screen.getByPlaceholderText('Search…');
+      expect(search).toHaveValue('c');
+      await waitFor(() => expect(search).toHaveFocus());
+    });
+
+    it('accumulates a multi-character prefix and resets it after the timeout', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      // Controlled: the committed value has to feed back in, or the match
+      // anchor stays -1 for the whole test and never gets exercised.
+      function Harness() {
+        const [value, setValue] = useState<string | undefined>(undefined);
+        return (
+          <Selector
+            label="Fruit"
+            options={['Apple', 'Banana', 'Blueberry']}
+            value={value}
+            onChange={next => {
+              setValue(next);
+              onChange(next);
+            }}
+          />
+        );
+      }
+      render(<Harness />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('b', trigger);
+      expect(trigger).toHaveTextContent('Banana');
+      // Within the window the buffer accumulates: "bl" → Blueberry. A
+      // multi-character buffer refines, so it may keep the current match.
+      type('l', trigger);
+      expect(trigger).toHaveTextContent('Blueberry');
+
+      // Past the window the buffer starts fresh: "a" → Apple. A surviving
+      // buffer would search "bla" and match nothing, so only a real reset
+      // gets here — worth the one real wait in the suite.
+      await new Promise(resolve =>
+        setTimeout(resolve, TYPEAHEAD_RESET_MS + 100),
+      );
+      type('a', trigger);
+      expect(trigger).toHaveTextContent('Apple');
+    });
+
+    it('skips disabled options when matching', async () => {
+      const user = userEvent.setup();
+      function Harness() {
+        const [value, setValue] = useState<string | undefined>(undefined);
+        return (
+          <Selector
+            label="Fruit"
+            options={[{value: 'Cherry', disabled: true}, 'Coconut']}
+            value={value}
+            onChange={setValue}
+          />
+        );
+      }
+      render(<Harness />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('c', trigger);
+      expect(trigger).toHaveTextContent('Coconut');
+
+      // The skip has to survive cycling too: with Coconut current, the next
+      // press wraps onto the disabled Cherry and must pass over it.
+      type('c', trigger);
+      expect(trigger).toHaveTextContent('Coconut');
+      expect(trigger).not.toHaveTextContent('Cherry');
+    });
+
+    it('moves the highlight without committing when typing with the menu open', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="City"
+          options={['Austin', 'Chicago', 'Cleveland']}
+          onChange={onChange}
+        />,
+      );
+
+      await user.tab();
+      await user.keyboard('{Enter}'); // open
+      const trigger = screen.getByRole('combobox');
+
+      await user.keyboard('c');
+      let activeId = trigger.getAttribute('aria-activedescendant');
+      expect(document.getElementById(activeId ?? '')).toHaveTextContent(
+        'Chicago',
+      );
+
+      // Repeated press cycles the highlight, still without committing.
+      await user.keyboard('c');
+      activeId = trigger.getAttribute('aria-activedescendant');
+      expect(document.getElementById(activeId ?? '')).toHaveTextContent(
+        'Cleveland',
+      );
+      expect(onChange).not.toHaveBeenCalled();
+      // aria-activedescendant already announces each match, so announcing
+      // again here would make a screen reader say every match twice.
+      // useAnnounce writes its text in a rAF callback, so let a frame pass —
+      // asserting before it runs would pass no matter what the code does.
+      await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
+      expect(politeRegion()?.textContent ?? '').toBe('');
+
+      await user.keyboard('{Enter}');
+      expect(onChange).toHaveBeenCalledWith('Cleveland');
+    });
+
+    it('does not fire onChange when the only match is already selected', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Cherry"
+          onChange={onChange}
+        />,
+      );
+
+      await user.tab();
+      await user.keyboard('c');
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('ignores printable keys pressed with ctrl or meta modifiers', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(<Selector label="Fruit" options={OPTIONS} onChange={onChange} />);
+
+      await user.tab();
+      await user.keyboard('{Control>}c{/Control}{Meta>}b{/Meta}');
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('announces the committed option to screen readers', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} onChange={() => {}} />);
+
+      await user.tab();
+      await user.keyboard('c');
+
+      // The trigger keeps focus and the menu never opens, so nothing else
+      // prompts a re-read. The polite live region carries the new value.
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Cherry');
+      });
+    });
+
+    it('does not select while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Ask an admin"
+        />,
+      );
+
+      // aria-disabled keeps the trigger focusable, so keydowns still arrive.
+      screen.getByRole('combobox').focus();
+      await user.keyboard('c');
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('cycles without duplicating changeAction while an action is pending', async () => {
+      const user = userEvent.setup();
+      const calls: string[] = [];
+      render(
+        <Selector
+          label="City"
+          options={['Chicago', 'Cleveland', 'Columbus']}
+          value={undefined}
+          changeAction={async value => {
+            calls.push(value);
+            // Never settles, so the value prop never catches up to what the
+            // trigger already shows.
+            await new Promise<void>(() => {});
+          }}
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('ccc', trigger);
+
+      // The anchor must come from the optimistic value, not the stale prop.
+      // Three options make that observable: with a stale anchor every press
+      // re-matches Chicago, which the duplicate guard then swallows.
+      expect(calls).toEqual(['Chicago', 'Cleveland', 'Columbus']);
+    });
+
+    it('starts a fresh buffer after selecting from the open menu', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Animal"
+          options={['Cat', 'Dog']}
+          onChange={onChange}
+        />,
+      );
+
+      await user.tab();
+      await user.keyboard('{Enter}'); // open
+      await user.keyboard('d'); // highlight Dog
+      await user.keyboard('{Enter}'); // commit Dog, closes
+      onChange.mockClear();
+
+      // The stale 'd' must not linger: 'c' is a fresh buffer, not "dc".
+      await user.keyboard('c');
+      expect(onChange).toHaveBeenCalledWith('Cat');
+    });
+
+    it('starts a fresh buffer after the value is cleared', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      function Harness() {
+        const [value, setValue] = useState<string | null>('Dog');
+        return (
+          <Selector
+            label="Animal"
+            options={['Cat', 'Dog']}
+            hasClear
+            value={value}
+            onChange={next => {
+              setValue(next);
+              onChange(next);
+            }}
+          />
+        );
+      }
+      render(<Harness />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      // Fills the buffer with 'd' without committing — Dog is already current.
+      type('d', trigger);
+      fireEvent.keyDown(trigger, {key: 'Delete'});
+      expect(onChange).toHaveBeenLastCalledWith(null);
+
+      // The stale 'd' must not survive the clear: 'c' is a fresh buffer, not
+      // "dc", which would match nothing and leave the value cleared.
+      type('c', trigger);
+      expect(onChange).toHaveBeenLastCalledWith('Cat');
+    });
+
+    it('matches on the label and commits the value', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      // Values deliberately crossed against labels: a native select matches
+      // the rendered text and reports the value.
+      function Harness() {
+        const [value, setValue] = useState<string | undefined>(undefined);
+        return (
+          <Selector
+            label="Fruit"
+            options={[
+              {value: 'zzz', label: 'Apple'},
+              {value: 'apple', label: 'Zebra'},
+            ]}
+            value={value}
+            onChange={next => {
+              setValue(next);
+              onChange(next);
+            }}
+          />
+        );
+      }
+      render(<Harness />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('a', trigger);
+
+      expect(onChange).toHaveBeenCalledWith('zzz');
+      expect(trigger).toHaveTextContent('Apple');
+
+      // No other label starts with "a" — the option whose *value* is 'apple'
+      // is labelled Zebra — so a second press stays put and commits nothing.
+      type('a', trigger);
+      expect(onChange).toHaveBeenCalledTimes(1);
+    });
+
+    it('matches across sections, ignoring dividers and group titles', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={[
+            'Almond',
+            {type: 'divider'},
+            {
+              type: 'section',
+              title: 'Tropical',
+              options: [
+                {value: 'mango', label: 'Mango'},
+                {value: 'papaya', label: 'Papaya'},
+              ],
+            },
+          ]}
+          onChange={onChange}
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('p', trigger);
+      expect(onChange).toHaveBeenCalledWith('papaya');
+
+      // The section title "Tropical" is decoration, not an option.
+      onChange.mockClear();
+      type('t', trigger);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('keeps aria-activedescendant on the matched option across a section', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={[
+            'Almond',
+            {type: 'divider'},
+            {
+              type: 'section',
+              title: 'Berries',
+              options: [{value: 'blueberry', label: 'Blueberry'}],
+            },
+          ]}
+          value="Almond"
+          onChange={() => {}}
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      await user.keyboard('{Enter}'); // opens on Almond
+      type('b', trigger);
+
+      const activeId = trigger.getAttribute('aria-activedescendant');
+      expect(document.getElementById(activeId ?? '')).toHaveTextContent(
+        'Blueberry',
+      );
+    });
+
+    it('anchors at the top when the value matches no option', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={['Apple', 'Apricot']}
+          value="Durian"
+          onChange={onChange}
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      type('a', trigger);
+
+      // Nothing is really selected, so the first match must stay reachable.
+      expect(onChange).toHaveBeenCalledWith('Apple');
+    });
+
+    it('lets Space open the menu after an abandoned typeahead', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      await user.keyboard('{Enter}'); // open
+      await user.keyboard('z'); // no match; buffer holds "z"
+      await user.keyboard('{Escape}'); // close, abandoning the buffer
+
+      // A live "z" buffer would swallow Space as a match character.
+      await user.keyboard(' ');
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('seeds every character typed before the search input takes focus', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} hasSearch />);
+
+      await user.tab();
+      // The popup opens on the first key, but focus only moves to the search
+      // input on the next frame — the second key still lands on the trigger.
+      await user.keyboard('ch');
+
+      const search = screen.getByPlaceholderText('Search…');
+      await waitFor(() => expect(search).toHaveValue('ch'));
+    });
+  });
+
+  describe('InputGroup integration', () => {
+    it('uses the group Field chrome and composes group and selector labels', () => {
+      render(
+        <InputGroup
+          label="Destination"
+          description="Where the alert should route"
+          status={{type: 'error', message: 'Destination is required'}}>
+          <InputGroupText>#</InputGroupText>
+          <Selector
+            label="Channel"
+            isLabelHidden
+            options={OPTIONS}
+            placeholder="Choose a channel"
+          />
+        </InputGroup>,
+      );
+
+      const group = screen.getByRole('group', {name: 'Destination'});
+      const groupLabelID = group.getAttribute('aria-labelledby');
+      const trigger = screen.getByRole('combobox', {
+        name: 'Destination Channel',
+      });
+      const labelledByIDs =
+        trigger.getAttribute('aria-labelledby')?.split(' ') ?? [];
+
+      expect(labelledByIDs).toHaveLength(2);
+      expect(labelledByIDs[0]).toBe(groupLabelID);
+      expect(document.getElementById(labelledByIDs[1])).toHaveTextContent(
+        'Channel',
+      );
+      expect(trigger).toHaveAttribute(
+        'aria-describedby',
+        group.getAttribute('aria-describedby'),
+      );
+      expect(screen.getByText('#')).toBeInTheDocument();
+    });
+
+    it('keeps disabled reasons described when grouped', () => {
+      render(
+        <InputGroup label="Destination">
+          <InputGroupText>#</InputGroupText>
+          <Selector
+            label="Channel"
+            isLabelHidden
+            options={OPTIONS}
+            isDisabled
+            disabledMessage="Choose a project first"
+          />
+        </InputGroup>,
+      );
+
+      const trigger = screen.getByRole('combobox', {
+        name: 'Destination Channel',
+      });
+      const tooltip = screen.getByRole('tooltip', h);
+
+      expect(trigger).not.toBeDisabled();
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+      expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+  });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          isDisabled
+          disabledMessage="You need the Editor role"
+          data-testid="fruit-selector"
+        />,
+      );
+
+      const container = screen.getByTestId('fruit-selector');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(container);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(container);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
           isDisabled
           disabledMessage="You need the Editor role"
         />,
@@ -1318,6 +2144,28 @@ describe('Selector statusVariant forwarding', () => {
   });
 });
 
+describe('Selector empty-state theme target', () => {
+  const OPTIONS = ['Apple', 'Banana', 'Cherry'];
+
+  it('renders the astryx-selector-empty-state target on the "No results found" element', async () => {
+    const user = userEvent.setup();
+    const {container} = render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    await user.type(screen.getByRole('combobox', h), 'xyz');
+
+    const empty = container.querySelector('.astryx-selector-empty-state');
+    expect(empty).not.toBeNull();
+    expect(empty).toHaveTextContent('No results found');
+  });
+});
+
 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.
@@ -1330,7 +2178,7 @@ describe('Selector clear icon theme target', () => {
     return icon as HTMLElement;
   };
 
-  it('renders the astryx-selector-clear-icon target on the clear glyph', () => {
+  it('renders the astryx-input-clear-icon target (plus the legacy alias) on the clear glyph', () => {
     render(
       <Selector
         label="Fruit"
@@ -1340,11 +2188,13 @@ describe('Selector clear icon theme target', () => {
         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.
+    // The canonical 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. The original per-component name rides along for a
+    // deprecation window.
     const icon = getClearIcon();
+    expect(icon).toHaveClass('astryx-input-clear-icon');
     expect(icon).toHaveClass('astryx-selector-clear-icon');
     expect(icon).toHaveClass('astryx-icon');
   });
@@ -1366,11 +2216,13 @@ describe('Selector clear icon theme target', () => {
     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.
+  it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {
+    // The clear affordance now composes the shared InputClearButton (a ghost
+    // Button with a secondary/sm glyph), so the icon carries the canonical
+    // `astryx-input-clear-icon` target and — for a deprecation window — the
+    // original `astryx-selector-clear-icon`. Aside from those target classes
+    // it matches the shared button's own `close`/`sm`/`secondary` glyph
+    // exactly, so the default look is defined in one place.
     render(
       <Selector
         label="Fruit"
@@ -1381,6 +2233,8 @@ describe('Selector clear icon theme target', () => {
       />,
     );
     const icon = getClearIcon();
+    expect(icon).toHaveClass('astryx-input-clear-icon');
+    expect(icon).toHaveClass('astryx-selector-clear-icon');
 
     const {container: refContainer} = render(
       <Icon icon="close" size="sm" color="secondary" />,
@@ -1390,7 +2244,11 @@ describe('Selector clear icon theme target', () => {
     const styleClasses = (el: HTMLElement) =>
       el.className
         .split(' ')
-        .filter(c => c !== 'astryx-selector-clear-icon')
+        .filter(
+          c =>
+            c !== 'astryx-input-clear-icon' &&
+            c !== 'astryx-selector-clear-icon',
+        )
         .sort();
 
     expect(styleClasses(icon)).toEqual(styleClasses(refIcon));
@@ -1464,9 +2322,12 @@ describe('Selector indicator (chevron) icon theme target', () => {
     });
   });
 
-  it('renders the default icon (inherit color, sm size) byte-identically', () => {
+  it('renders the default icon (secondary 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
+    // same StyleX color/size classes as a standalone secondary/sm icon. The
+    // glyph now sets --color-icon-secondary itself rather than inheriting it
+    // from a wrapper span that set the same token, so the rendered color is
+    // unchanged. The added
     // target class + data-state are purely additive — they change nothing until
     // a theme targets them.
     const {container} = render(
@@ -1475,12 +2336,12 @@ describe('Selector indicator (chevron) icon theme target', () => {
     const icon = getIndicatorIcon(container);
 
     const {container: refContainer} = render(
-      <Icon icon="chevronDown" size="sm" color="inherit" />,
+      <Icon icon="chevronDown" size="sm" color="secondary" />,
     );
     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.
+    // reflected state class) so only StyleX classes remain.
     const themeTargetClasses = new Set([
       'astryx-selector-indicator-icon',
       'collapsed',
@@ -1492,7 +2353,14 @@ describe('Selector indicator (chevron) icon theme target', () => {
         .filter(c => !themeTargetClasses.has(c))
         .sort();
 
-    expect(styleClasses(icon)).toEqual(styleClasses(refIcon));
+    // A superset, not an exact match: the chevron additionally carries the
+    // rotation styles, which live on the glyph precisely so a theme can reach
+    // the transform through the same selector as the color. The guard that
+    // matters is that every color/size class of a standalone icon is still
+    // present — i.e. the default look has not drifted.
+    expect(styleClasses(icon)).toEqual(
+      expect.arrayContaining(styleClasses(refIcon)),
+    );
   });
 
   it('exposes selector-indicator-icon so a theme reaches the icon size and per-state color', () => {
@@ -1519,7 +2387,165 @@ describe('Selector indicator (chevron) icon theme target', () => {
   });
 });
 
+describe('Selector section headings', () => {
+  it('renders a section title as a plain heading inside the group, not a divider', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector
+        label="Fruit"
+        options={[
+          {
+            type: 'section',
+            title: 'Citrus',
+            options: [
+              {value: 'orange', label: 'Orange'},
+              {value: 'lemon', label: 'Lemon'},
+            ],
+          },
+        ]}
+        value={undefined}
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+
+    // A labeled Divider used to stand in for the heading; it rendered a
+    // role="separator" as a direct child of the listbox and stacked a second
+    // rule under the search row's own.
+    expect(document.querySelectorAll('[role="separator"]')).toHaveLength(0);
+
+    const group = screen.getByRole('group', {name: 'Citrus', hidden: true});
+    const heading = group.querySelector('.astryx-selector-section-heading');
+    expect(heading).toBeTruthy();
+    expect(heading).toHaveTextContent('Citrus');
+    // The group already carries the title as its accessible name, so the
+    // visible heading must not announce it a second time.
+    expect(heading).toHaveAttribute('aria-hidden', 'true');
+  });
+});
+
+describe('Selector search focus ring', () => {
+  // The ring is for keyboard focus only. `:focus-visible` cannot express that
+  // on its own: per CSS Selectors 4 a pointer-focused text input matches it
+  // too (verified in Chromium), which is why a modality gate sits alongside
+  // it. jsdom does not implement `:focus-visible`, so these assert the gate;
+  // the painted ring is verified in real Chromium.
+  //
+  // Focus moves into the search input on the frame after the panel opens, and
+  // the gate is read at that moment: every case must wait for the focus to
+  // land before asserting or typing, or a slow frame reads the modality of
+  // whatever the test did next.
+  beforeEach(() => {
+    __resetInteractionModalityForTest();
+  });
+
+  const field = () =>
+    screen.getByRole('combobox', {hidden: true}).parentElement;
+
+  const waitForSearchFocus = async () =>
+    waitFor(() =>
+      expect(screen.getByRole('combobox', {hidden: true})).toHaveFocus(),
+    );
+
+  it('does not ring when the panel is opened by mouse', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value={undefined}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    await waitForSearchFocus();
+    expect(field()).not.toHaveAttribute('data-keyboard-focus');
+  });
+
+  it('does not ring when the query is typed after a mouse open', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value={undefined}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    await waitForSearchFocus();
+    await user.keyboard('an');
+    // Typing does not retroactively make a pointer focus a keyboard one; the
+    // caret already shows where the text is going.
+    expect(field()).not.toHaveAttribute('data-keyboard-focus');
+  });
+
+  it('rings when the panel is opened from the keyboard', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value={undefined}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.tab();
+    await user.keyboard('{Enter}');
+    await waitForSearchFocus();
+    expect(field()).toHaveAttribute('data-keyboard-focus', 'true');
+  });
+});
+
 describe('Selector search affordances', () => {
+  it('renders the search row seamlessly — no nested input box, a divider under it', async () => {
+    const user = userEvent.setup();
+    const {container} = render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Apple"
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+
+    const search = screen.getByRole('combobox', {hidden: true});
+    // The row is the outer gutter; the input sits inside the rounded field.
+    const row = search.closest('.astryx-selector-search');
+    const field = search.parentElement;
+    if (!row || !field) {
+      throw new Error('search row not found');
+    }
+    // The panel is already a bordered surface: the field inside it must not be
+    // a second bordered box (this used to render a TextInput).
+    expect(row).not.toHaveClass('astryx-text-input');
+    expect(search.closest('.astryx-text-input')).toBeNull();
+    // The field is a rounded box inset from the panel edge, shaped like the
+    // option rows under it — not a full-bleed header strip.
+    expect(field).not.toBe(row);
+    expect(getComputedStyle(field).borderRadius).not.toBe('');
+    // ...and a divider separates it from the options.
+    const separator =
+      container.ownerDocument.querySelector('[role="separator"]');
+    if (!separator) {
+      throw new Error('divider not found');
+    }
+    // Order: row, then divider, then the listbox.
+    expect(
+      row.compareDocumentPosition(separator) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    const listbox = screen.getByRole('listbox', {hidden: true});
+    expect(
+      separator.compareDocumentPosition(listbox) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
   it('renders a decorative (aria-hidden) magnifier icon whenever hasSearch is on', async () => {
     const user = userEvent.setup();
     render(
@@ -1533,8 +2559,7 @@ describe('Selector search affordances', () => {
     );
     await user.click(screen.getByRole('button', {name: 'Fruit'}));
     const search = screen.getByRole('combobox', {hidden: true});
-    // The search field is a TextInput; the magnifier is its startIcon, so it
-    // sits inside the input container as a sibling of the <input>.
+    // The magnifier leads the search row, as a sibling of the <input>.
     const container = search.parentElement;
     const magnifier = container?.querySelector('.astryx-icon');
     expect(magnifier).toBeTruthy();
@@ -1640,3 +2665,272 @@ describe('Selector search affordances', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
   });
 });
+
+describe('Selector selected-marker theme target (selector-check)', () => {
+  const openOptions = (): HTMLElement[] => screen.getAllByRole('option', h);
+
+  it('renders the astryx-selector-check target on the selected row only', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        isDefaultOpen
+      />,
+    );
+    const options = openOptions();
+    const selected = options.find(
+      o => o.getAttribute('aria-selected') === 'true',
+    )!;
+    const check = selected.querySelector('.astryx-selector-check');
+    expect(check).toBeInTheDocument();
+    // The target lands on the checkmark glyph itself, so a theme can restyle or
+    // hide it (e.g. to compose its own selected indicator via renderOption).
+    expect(check).toHaveClass('astryx-icon');
+
+    const unselected = options.filter(
+      o => o.getAttribute('aria-selected') !== 'true',
+    );
+    for (const row of unselected) {
+      expect(
+        row.querySelector('.astryx-selector-check'),
+      ).not.toBeInTheDocument();
+    }
+  });
+
+  it('renders the default checkmark byte-identically aside from the target class', () => {
+    // The added target class is purely additive — it changes nothing about the
+    // glyph's own color/size until a theme targets it.
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        isDefaultOpen
+      />,
+    );
+    const selected = screen
+      .getAllByRole('option', h)
+      .find(o => o.getAttribute('aria-selected') === 'true')!;
+    const check = selected.querySelector(
+      '.astryx-selector-check',
+    ) as HTMLElement;
+
+    const {container: refContainer} = render(
+      <Icon icon="check" size="sm" color="accent" />,
+    );
+    const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+    const styleClasses = (el: HTMLElement) =>
+      el.className
+        .split(' ')
+        .filter(c => c !== 'astryx-selector-check')
+        .sort();
+    expect(styleClasses(check)).toEqual(styleClasses(refIcon));
+  });
+
+  it('exposes selector-check so a theme can hide or restyle the marker', () => {
+    const theme = defineTheme({
+      name: 'selector-check-test',
+      components: {
+        'selector-check': {
+          base: {display: 'none'},
+        },
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-selector-check {');
+    expect(css).toContain('display: none');
+  });
+});
+
+describe('Selector disabled state theme target', () => {
+  const getSelectorRoot = (container: HTMLElement): HTMLElement => {
+    const root = container.querySelector('.astryx-selector');
+    if (root == null) {
+      throw new Error('selector root not found');
+    }
+    return root as HTMLElement;
+  };
+
+  it('reflects data-disabled="disabled" on the root when disabled', () => {
+    const {container} = render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    expect(getSelectorRoot(container)).toHaveAttribute(
+      'data-disabled',
+      'disabled',
+    );
+  });
+
+  it('omits the disabled class/attribute when enabled', () => {
+    const {container} = render(
+      <Selector label="Fruit" options={OPTIONS} onChange={() => {}} />,
+    );
+    const root = getSelectorRoot(container);
+    expect(root).not.toHaveAttribute('data-disabled');
+    expect(root).not.toHaveClass('disabled');
+  });
+
+  it('exposes the disabled state so a theme can key on it', () => {
+    const theme = defineTheme({
+      name: 'selector-disabled-state-test',
+      components: {
+        selector: {
+          'disabled:disabled': {opacity: '0.4'},
+        },
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-selector.disabled');
+    expect(css).toContain('opacity: 0.4');
+  });
+});
+
+describe('Selector indicatorPosition', () => {
+  const openRows = (): HTMLElement[] => screen.getAllByRole('option', h);
+  const rowFor = (label: string): HTMLElement =>
+    openRows().find(row => row.textContent?.includes(label))!;
+
+  it('draws the mark after the option content by default', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        isDefaultOpen
+      />,
+    );
+    const row = rowFor('Banana');
+    const mark = row.querySelector('.astryx-selector-check')!;
+    const content = row.querySelector('.astryx-selector-option')!;
+    expect(
+      content.compareDocumentPosition(mark) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it('draws the mark before the option content when set to start', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        indicatorPosition="start"
+        isDefaultOpen
+      />,
+    );
+    const row = rowFor('Banana');
+    const mark = row.querySelector('.astryx-selector-check')!;
+    const content = row.querySelector('.astryx-selector-option')!;
+    expect(
+      content.compareDocumentPosition(mark) & Node.DOCUMENT_POSITION_PRECEDING,
+    ).toBeTruthy();
+  });
+
+  it('reserves the mark column on every row, at either position', () => {
+    // The default check draws nothing when unchecked, so without a reserved
+    // column the chosen row would be laid out differently from the rest —
+    // indented at the start, truncating earlier at the end. Every row is two
+    // children wide either way, so a row's geometry does not depend on whether
+    // it happens to be the chosen one.
+    const {unmount} = render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        indicatorPosition="start"
+        isDefaultOpen
+      />,
+    );
+    for (const row of openRows()) {
+      expect(row.children).toHaveLength(2);
+    }
+    unmount();
+
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+        isDefaultOpen
+      />,
+    );
+    for (const row of openRows()) {
+      expect(row.children).toHaveLength(2);
+    }
+  });
+
+  it('positions a themed replacement indicator the same way', () => {
+    const theme = defineTheme({
+      name: 'selector-start-radio-mark-test',
+      indicators: {check: RadioIndicator},
+    });
+    render(
+      <Theme theme={theme}>
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={() => {}}
+          indicatorPosition="start"
+          isDefaultOpen
+        />
+      </Theme>,
+    );
+    for (const row of openRows()) {
+      const radio = row.querySelector('.astryx-radio')!;
+      const content = row.querySelector('.astryx-selector-option')!;
+      expect(
+        content.compareDocumentPosition(radio) &
+          Node.DOCUMENT_POSITION_PRECEDING,
+      ).toBeTruthy();
+    }
+  });
+});
+
+describe('Selector popup theme target', () => {
+  // The surface is the same element whether or not the popup has a search
+  // field — which is the reason the target lives there. Rendered on the
+  // component's own content, it would land on the listbox in one branch and
+  // on a wrapper in the other, so one theme rule would style two different
+  // boxes.
+  it.each([
+    ['without search', false],
+    ['with search', true],
+  ])(
+    'puts astryx-selector-popup on the painting surface, %s',
+    async (_label, hasSearch) => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={['Apple', 'Banana']}
+          value="Apple"
+          onChange={() => {}}
+          hasSearch={hasSearch}
+        />,
+      );
+      // The trigger is a combobox in the plain variant and a listbox-popup
+      // button in the search variant; the surface is the same either way.
+      await user.click(
+        screen.queryByRole('combobox') ??
+          screen.getByRole('button', {name: /Fruit/}),
+      );
+
+      const popup = document.querySelector('.astryx-selector-popup');
+      expect(popup).not.toBeNull();
+      expect(popup).toHaveClass('astryx-popover-surface');
+      expect(popup?.querySelector('[role="listbox"]')).not.toBeNull();
+    },
+  );
+});