@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Selector/Selector.doc.mjs

@@ -84,11 +84,19 @@ export const docs = {
       name: 'isDisabled',
       type: 'boolean',
       description: 'Disables the selector.',
+      default: 'false',
+    },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Selector in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLabelHidden',
       type: 'boolean',
       description: 'Visually hides the label while keeping it accessible.',
+      default: 'false',
     },
     {
       name: 'description',
@@ -99,11 +107,13 @@ export const docs = {
       name: 'isOptional',
       type: 'boolean',
       description: 'Marks the field as optional.',
+      default: 'false',
     },
     {
       name: 'isRequired',
       type: 'boolean',
       description: 'Marks the field as required.',
+      default: 'false',
     },
     {
       name: 'status',
@@ -172,6 +182,11 @@ export const docs = {
         description:
           'Put more than ~20 options without sections; consider Typeahead for large lists.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
       {
@@ -259,6 +274,11 @@ export const docsZh = {
         description:
           'Put more than ~20 options without sections; consider Typeahead for large lists.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
       {
@@ -346,6 +366,11 @@ export const docsDense = {
         description:
           'Put more than ~20 options without sections; consider Typeahead for large lists.',
       },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
       {

package/src/Selector/Selector.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Selector} from './Selector';
 import {SelectorOption} from './SelectorOption';
@@ -83,7 +83,12 @@ function mockSelectorRects() {
     'innerHeight',
   );
   HTMLElement.prototype.getBoundingClientRect = function () {
-    if (this.getAttribute('role') === 'combobox') {
+    // 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});
     }
     if (this.getAttribute('role') === 'listbox') {
@@ -108,9 +113,7 @@ function mockSelectorRects() {
 
 describe('Selector', () => {
   it('renders with placeholder when no value', () => {
-    render(
-      <Selector label="Fruit" options={OPTIONS} placeholder="Pick one" />,
-    );
+    render(<Selector label="Fruit" options={OPTIONS} placeholder="Pick one" />);
     expect(screen.getByRole('combobox')).toHaveTextContent('Pick one');
   });
 
@@ -147,6 +150,25 @@ describe('Selector', () => {
     expect(screen.getByTestId('option-badge')).toHaveTextContent('Owner');
   });
 
+  it('exposes the popup as a listbox, not a modal dialog', () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        value="Banana"
+        onChange={() => {}}
+      />,
+    );
+    // The combobox trigger keeps DOM focus; the popup must expose its own
+    // role="listbox" and must not be wrapped in a role="dialog" aria-modal
+    // element, which would tell AT the focused trigger is inert.
+    expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();
+    expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();
+    expect(
+      document.querySelector('[aria-modal="true"]'),
+    ).not.toBeInTheDocument();
+  });
+
   it('supports explicit menu placement', () => {
     render(
       <Selector
@@ -310,6 +332,59 @@ describe('Selector', () => {
       expect(onChange).toHaveBeenCalledWith(null);
     });
 
+    it('clears the value via Delete on the focused trigger', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={onChange}
+          hasClear
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      trigger.focus();
+      await user.keyboard('{Delete}');
+      expect(onChange).toHaveBeenCalledWith(null);
+    });
+
+    it('clears the value via Backspace on the focused trigger', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={onChange}
+          hasClear
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      trigger.focus();
+      await user.keyboard('{Backspace}');
+      expect(onChange).toHaveBeenCalledWith(null);
+    });
+
+    it('does not clear via Delete when hasClear is not set', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Banana"
+          onChange={onChange}
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      trigger.focus();
+      await user.keyboard('{Delete}');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
     it('shows placeholder after clearing', () => {
       render(
         <Selector
@@ -355,8 +430,33 @@ describe('Selector', () => {
           hasSearch
         />,
       );
-      await user.click(screen.getByRole('combobox'));
-      expect(screen.getByRole('searchbox', h)).toBeInTheDocument();
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      expect(screen.getByRole('combobox', h)).toBeInTheDocument();
+    });
+
+    it('wires the search input as the combobox with activedescendant (comboboxes-4)', async () => {
+      const user = userEvent.setup();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Apple"
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      const triggerBtn = screen.getByRole('button', {name: 'Fruit'});
+      // In hasSearch mode the trigger is a plain button, not a combobox.
+      expect(triggerBtn).not.toHaveAttribute('role', 'combobox');
+      await user.click(triggerBtn);
+      const search = screen.getByRole('combobox', h);
+      expect(search).toHaveAttribute('aria-autocomplete', 'list');
+      expect(search).toHaveAttribute('aria-expanded', 'true');
+      expect(search).toHaveAttribute('aria-controls');
+      // ArrowDown moves the highlight; the search input reports it via
+      // aria-activedescendant (previously silent on the trigger).
+      await user.keyboard('{ArrowDown}');
+      expect(search).toHaveAttribute('aria-activedescendant');
     });
 
     it('does not render search input when hasSearch is false', async () => {
@@ -369,6 +469,8 @@ describe('Selector', () => {
           onChange={() => {}}
         />,
       );
+      // hasSearch is false, so the trigger itself is the combobox and there is
+      // no separate search input inside the popup.
       await user.click(screen.getByRole('combobox'));
       expect(screen.queryByRole('searchbox', h)).not.toBeInTheDocument();
     });
@@ -384,8 +486,8 @@ describe('Selector', () => {
           hasSearch
         />,
       );
-      await user.click(screen.getByRole('combobox'));
-      await user.type(screen.getByRole('searchbox', h), 'ban');
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      await user.type(screen.getByRole('combobox', h), 'ban');
       const options = screen.getAllByRole('option', h);
       expect(options).toHaveLength(1);
       expect(options[0]).toHaveTextContent('Banana');
@@ -402,8 +504,8 @@ describe('Selector', () => {
           hasSearch
         />,
       );
-      await user.click(screen.getByRole('combobox'));
-      await user.type(screen.getByRole('searchbox', h), 'xyz');
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      await user.type(screen.getByRole('combobox', h), 'xyz');
       expect(screen.queryAllByRole('option', h)).toHaveLength(0);
       expect(screen.getByText('No results found')).toBeInTheDocument();
     });
@@ -420,8 +522,8 @@ describe('Selector', () => {
           hasSearch
         />,
       );
-      await user.click(screen.getByRole('combobox'));
-      await user.type(screen.getByRole('searchbox', h), 'ban');
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      await user.type(screen.getByRole('combobox', h), 'ban');
       await user.click(screen.getByRole('option', {name: /Banana/, ...h}));
       expect(onChange).toHaveBeenCalledWith('Banana');
     });
@@ -441,7 +543,9 @@ describe('Selector', () => {
         </>,
       );
 
-      const trigger = screen.getByRole('combobox');
+      // In hasSearch mode the trigger is a plain button (the popup's search
+      // input is the combobox); it still owns aria-expanded.
+      const trigger = screen.getByRole('button', {name: 'Fruit'});
       await user.click(trigger);
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
 
@@ -461,10 +565,213 @@ describe('Selector', () => {
           searchPlaceholder="Find a fruit..."
         />,
       );
-      await user.click(screen.getByRole('combobox'));
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
       expect(
         screen.getByPlaceholderText('Find a fruit...'),
       ).toBeInTheDocument();
     });
   });
+
+  describe('keyboard accessibility', () => {
+    it('trigger is focusable via Tab when enabled', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} />);
+
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+    });
+
+    it('trigger is not focusable when disabled', () => {
+      render(<Selector label="Fruit" options={OPTIONS} isDisabled />);
+      expect(screen.getByRole('combobox')).toHaveAttribute('tabIndex', '-1');
+    });
+
+    it('opens the listbox with ArrowDown from a focused trigger', async () => {
+      const user = userEvent.setup();
+      render(<Selector label="Fruit" options={OPTIONS} />);
+
+      const trigger = screen.getByRole('combobox');
+      await user.tab();
+      expect(trigger).toHaveFocus();
+
+      await user.keyboard('{ArrowDown}');
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('opens and selects an option with Enter (no mouse)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(<Selector label="Fruit" options={OPTIONS} onChange={onChange} />);
+
+      await user.tab();
+      await user.keyboard('{Enter}'); // open
+      await user.keyboard('{ArrowDown}'); // move highlight
+      await user.keyboard('{Enter}'); // select
+
+      expect(onChange).toHaveBeenCalled();
+    });
+
+    it('clear button is reachable by keyboard', () => {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          value="Apple"
+          onChange={() => {}}
+          hasClear
+        />,
+      );
+      const clear = screen.getByRole('button', {name: 'Clear Fruit'});
+      expect(clear).not.toHaveAttribute('tabIndex', '-1');
+    });
+
+    it('scrolls the highlighted option into view during arrow navigation', async () => {
+      const scrollIntoView = vi.fn();
+      Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+        configurable: true,
+        value: scrollIntoView,
+      });
+      try {
+        const user = userEvent.setup();
+        const longOptions = Array.from(
+          {length: 20},
+          (_, i) => `Option ${i + 1}`,
+        );
+        render(<Selector label="Fruit" options={longOptions} />);
+
+        await user.tab();
+        await user.keyboard('{Enter}'); // open
+        scrollIntoView.mockClear();
+        await user.keyboard('{ArrowDown}'); // move highlight
+        await user.keyboard('{ArrowDown}');
+
+        expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});
+      } finally {
+        delete (HTMLElement.prototype as unknown as {scrollIntoView?: unknown})
+          .scrollIntoView;
+      }
+    });
+  });
+
+  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"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(<Selector label="Fruit" options={OPTIONS} isDisabled />);
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the trigger focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      expect(trigger).not.toBeDisabled();
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+      expect(trigger).toHaveAttribute('tabIndex', '0');
+    });
+
+    it('links the reason tooltip from the trigger via aria-describedby', () => {
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks activation while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+      await user.keyboard('{Enter}');
+      await user.keyboard('{ArrowDown}');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains non-focusable when disabled without a reason', () => {
+      render(<Selector label="Fruit" options={OPTIONS} isDisabled />);
+      const trigger = screen.getByRole('combobox');
+      expect(trigger).toBeDisabled();
+      expect(trigger).toHaveAttribute('tabIndex', '-1');
+    });
+  });
 });