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

package/src/PowerSearch/PowerSearch.test.tsx

@@ -11,7 +11,7 @@
 
 import {useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
@@ -199,4 +199,100 @@ describe('PowerSearch', () => {
       expect(pasteResults).toEqual(typeResults);
     });
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+    const isOpen = (el: Element) => el.matches(':popover-open');
+
+    function renderSearch(props?: {onChange?: () => void}) {
+      return render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={props?.onChange ?? (() => {})}
+          isDisabled
+          disabledMessage="You need edit access to search"
+        />,
+      );
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      renderSearch();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need edit access to search');
+      const wrapper = screen.getByRole('group');
+      fireEvent.mouseEnter(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+      fireEvent.mouseLeave(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(false));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      renderSearch();
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          disabledMessage="You need edit access to search"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks input while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      input.focus();
+      await user.keyboard('open');
+      expect((input as HTMLInputElement).value).toBe('');
+    });
+
+    it('keeps the input natively disabled when disabled without a reason', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('combobox')).toBeDisabled();
+    });
+  });
 });

package/src/PowerSearch/PowerSearch.tsx

@@ -358,6 +358,16 @@ export interface PowerSearchProps extends Omit<
   isReadOnly?: boolean;
   /** Whether the input is disabled. @default false */
   isDisabled?: boolean;
+  /**
+   * Explains why the search is disabled. When set together with `isDisabled`,
+   * the search shows a tooltip with this text on hover and keyboard focus, and
+   * the input stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Input stays blocked.
+   *
+   * Use this instead of wrapping a disabled PowerSearch in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -508,6 +518,7 @@ export function PowerSearch({
   hasClear = true,
   isReadOnly = false,
   isDisabled = false,
+  disabledMessage,
   startIcon,
   onFocus,
   onBlur,
@@ -546,6 +557,9 @@ export function PowerSearch({
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own listbox/menu content is the exposed semantics; focus
+    // stays on the tokenizer input, so a modal dialog wrapper is incorrect.
+    role: 'none',
   });
 
   // Wrapper that manages layer visibility and tokenizer focus alongside state
@@ -795,9 +809,7 @@ export function PowerSearch({
         filter.value.value[0].photo
       ) {
         const entity = filter.value.value[0];
-        tokenIcon = (
-          <Avatar src={entity.photo} name={entity.label} size={16} />
-        );
+        tokenIcon = <Avatar src={entity.photo} name={entity.label} size={16} />;
       }
 
       return (
@@ -982,6 +994,7 @@ export function PowerSearch({
           startIcon={startIcon}
           endContent={combinedEndContent}
           isDisabled={isDisabled}
+          disabledMessage={disabledMessage}
           size={size}
           tokenOverflowBehavior={tokenOverflowBehavior}
           hasEntriesOnFocus

package/src/ProgressBar/ProgressBar.test.tsx

@@ -7,11 +7,19 @@ import {ProgressBar} from './ProgressBar';
 describe('ProgressBar', () => {
   it('renders with default props', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toBeInTheDocument();
-    expect(meter).toHaveAttribute('aria-valuenow', '50');
-    expect(meter).toHaveAttribute('aria-valuemin', '0');
-    expect(meter).toHaveAttribute('aria-valuemax', '100');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toBeInTheDocument();
+    expect(progressbar).toHaveAttribute('aria-valuenow', '50');
+    expect(progressbar).toHaveAttribute('aria-valuemin', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '100');
+  });
+
+  it('uses role="progressbar" (not "meter") for determinate progress', () => {
+    // A determinate ProgressBar conveys task completion, so it must be a
+    // progressbar (announced on update), not a meter (a static gauge).
+    render(<ProgressBar value={50} label="Progress" />);
+    expect(screen.getByRole('progressbar')).toBeInTheDocument();
+    expect(screen.queryByRole('meter')).not.toBeInTheDocument();
   });
 
   it('renders visible label by default', () => {
@@ -23,8 +31,8 @@ describe('ProgressBar', () => {
     render(<ProgressBar value={50} label="Hidden label" isLabelHidden />);
     const label = screen.getByText('Hidden label');
     expect(label).toBeInTheDocument();
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-labelledby');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-labelledby');
   });
 
   it('shows value label when hasValueLabel is true', () => {
@@ -43,33 +51,33 @@ describe('ProgressBar', () => {
       />,
     );
     expect(screen.getByText('3 GB / 5 GB')).toBeInTheDocument();
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuetext', '3 GB / 5 GB');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuetext', '3 GB / 5 GB');
   });
 
   it('sets aria-valuetext from formatValueLabel', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuetext', '50%');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuetext', '50%');
   });
 
   it('respects custom max', () => {
     render(<ProgressBar value={3} max={10} label="Steps" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '3');
-    expect(meter).toHaveAttribute('aria-valuemax', '10');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '3');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '10');
   });
 
   it('clamps value to [0, max]', () => {
     const {rerender} = render(
       <ProgressBar value={150} max={100} label="Over" />,
     );
-    let meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '100');
+    let progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '100');
 
     rerender(<ProgressBar value={-10} max={100} label="Under" />);
-    meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '0');
+    progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
   });
 
   it('forwards ref to outer container', () => {
@@ -79,9 +87,7 @@ describe('ProgressBar', () => {
   });
 
   it('passes data-testid', () => {
-    render(
-      <ProgressBar value={50} label="Test" data-testid="my-progress" />,
-    );
+    render(<ProgressBar value={50} label="Test" data-testid="my-progress" />);
     expect(screen.getByTestId('my-progress')).toBeInTheDocument();
   });
 
@@ -97,14 +103,14 @@ describe('ProgressBar', () => {
       const {unmount} = render(
         <ProgressBar value={50} label={variant} variant={variant} />,
       );
-      expect(screen.getByRole('meter')).toBeInTheDocument();
+      expect(screen.getByRole('progressbar')).toBeInTheDocument();
       unmount();
     }
   });
 
   it('renders at fixed 8px track height', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    expect(screen.getByRole('meter')).toBeInTheDocument();
+    expect(screen.getByRole('progressbar')).toBeInTheDocument();
   });
 
   it('shows value label with hidden label', () => {
@@ -115,11 +121,23 @@ describe('ProgressBar', () => {
     expect(screen.getByText('Hidden')).toBeInTheDocument();
   });
 
+  it('renders no visible value label when isLabelHidden without hasValueLabel', () => {
+    // Mirrors the intended "accessible label only" composition: the text
+    // label is kept for assistive tech (visually hidden) while no extra
+    // visible value label is surfaced.
+    render(<ProgressBar value={42} label="Context usage" isLabelHidden />);
+    expect(screen.queryByText('42%')).not.toBeInTheDocument();
+    const label = screen.getByText('Context usage');
+    expect(label).toBeInTheDocument();
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-labelledby', label.id);
+  });
+
   it('handles zero max gracefully', () => {
     render(<ProgressBar value={0} max={0} label="Empty" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '0');
-    expect(meter).toHaveAttribute('aria-valuemax', '0');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '0');
   });
 
   // Disabled state
@@ -128,7 +146,7 @@ describe('ProgressBar', () => {
       render(
         <ProgressBar value={50} label="Canceled" isDisabled hasValueLabel />,
       );
-      expect(screen.getByRole('meter')).toBeInTheDocument();
+      expect(screen.getByRole('progressbar')).toBeInTheDocument();
       expect(screen.getByText('50%')).toBeInTheDocument();
     });
 

package/src/ProgressBar/ProgressBar.tsx

@@ -31,6 +31,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 /**
  * Extensible variant map for ProgressBar.
@@ -313,14 +314,12 @@ export function ProgressBar({
           )}
         </div>
       ) : (
-        <span id={labelId} {...stylex.props(styles.visuallyHidden)}>
-          {label}
-        </span>
+        <VisuallyHidden id={labelId}>{label}</VisuallyHidden>
       )}
 
       {/* Progress track */}
       <div
-        role={isIndeterminate ? 'progressbar' : 'meter'}
+        role="progressbar"
         aria-valuenow={isIndeterminate ? undefined : clampedValue}
         aria-valuemin={isIndeterminate ? undefined : 0}
         aria-valuemax={isIndeterminate ? undefined : max}

package/src/RadioList/RadioList.doc.mjs

@@ -74,6 +74,12 @@ export const docs = {
       description: 'Whether all radio items are disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isRequired',
       type: 'boolean',
@@ -121,6 +127,7 @@ export const docs = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -142,6 +149,7 @@ export const docsZh = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -165,6 +173,7 @@ export const docsDense = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},

package/src/RadioList/RadioList.test.tsx

@@ -9,12 +9,39 @@
  * SYNC: When RadioList.tsx or RadioListItem.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {RadioList} from './RadioList';
 import {RadioListItem} from './RadioListItem';
 
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
 describe('RadioList', () => {
   it('renders with label', () => {
     render(
@@ -104,11 +131,7 @@ describe('RadioList', () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
     render(
-      <RadioList
-        label="Preference"
-        value=""
-        onChange={handleChange}
-        isDisabled>
+      <RadioList label="Preference" value="" onChange={handleChange} isDisabled>
         <RadioListItem label="Option A" value="a" />
       </RadioList>,
     );
@@ -257,11 +280,7 @@ describe('RadioList', () => {
   it('supports data-testid on RadioListItem', () => {
     render(
       <RadioList label="Preference" value="" onChange={() => {}}>
-        <RadioListItem
-          label="Option A"
-          value="a"
-          data-testid="my-radio-item"
-        />
+        <RadioListItem label="Option A" value="a" data-testid="my-radio-item" />
       </RadioList>,
     );
     expect(screen.getByTestId('my-radio-item')).toBeInTheDocument();
@@ -279,11 +298,32 @@ describe('RadioList', () => {
     );
     const label = screen.getByText('Hidden label');
     expect(label).toBeInTheDocument();
-    // The radiogroup should still be labeled
-    expect(screen.getByRole('radiogroup')).toHaveAttribute(
-      'aria-label',
-      'Hidden label',
+    // The radiogroup is named by the label element via aria-labelledby (not a
+    // duplicated aria-label), so its accessible name is still "Hidden label".
+    expect(
+      screen.getByRole('radiogroup', {name: 'Hidden label'}),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('radiogroup')).toHaveAttribute('aria-labelledby');
+    expect(screen.getByRole('radiogroup')).not.toHaveAttribute('aria-label');
+  });
+
+  it('renders the group label as a span, not a label element (forms-14)', () => {
+    render(
+      <RadioList label="Plan" value="" onChange={() => {}}>
+        <RadioListItem label="Free" value="free" />
+        <RadioListItem label="Pro" value="pro" />
+      </RadioList>,
     );
+    // A radiogroup's accessible name must not come from a literal `<label>`
+    // element — a `<label>` names a single control and can't be associated
+    // with a group. It is rendered as a `<span>` and referenced via
+    // aria-labelledby (with no orphaned htmlFor).
+    const labelEl = screen.getByText('Plan');
+    expect(labelEl.tagName).toBe('SPAN');
+    expect(labelEl.closest('label')).toBeNull();
+    expect(labelEl).not.toHaveAttribute('for');
+    const group = screen.getByRole('radiogroup', {name: 'Plan'});
+    expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
   });
 
   it('renders description on items', () => {
@@ -340,4 +380,200 @@ describe('RadioList', () => {
       'true',
     );
   });
+
+  describe('focus management (no-selection tab stop)', () => {
+    it('keeps focus on the selected radio when a value is selected', () => {
+      render(
+        <RadioList label="Preference" value="b" onChange={() => {}}>
+          <RadioListItem label="Option A" value="a" />
+          <RadioListItem label="Option B" value="b" />
+          <RadioListItem label="Option C" value="c" />
+        </RadioList>,
+      );
+      const selected = screen.getByLabelText('Option B');
+      // A selected value provides a deterministic native tab stop; focusing it
+      // must not be redirected elsewhere.
+      selected.focus();
+      expect(selected).toHaveFocus();
+    });
+
+    it('redirects to the first radio when focus enters an unselected group forward', () => {
+      render(
+        <>
+          <button type="button">before</button>
+          <RadioList label="Preference" value="" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+            <RadioListItem label="Option B" value="b" />
+            <RadioListItem label="Option C" value="c" />
+          </RadioList>
+        </>,
+      );
+      const radios = screen.getAllByRole('radio');
+      const outside = screen.getByText('before');
+      outside.focus();
+      // Forward entry: the browser lands on a leading radio; the group keeps the
+      // first radio as the deterministic tab stop.
+      radios[0].focus();
+      expect(radios[0]).toHaveFocus();
+
+      // Landing on a middle radio from outside is normalized to the first.
+      outside.focus();
+      radios[1].focus();
+      expect(radios[0]).toHaveFocus();
+    });
+
+    it('redirects to the last radio when focus enters an unselected group backward', () => {
+      render(
+        <>
+          <RadioList label="Preference" value="" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+            <RadioListItem label="Option B" value="b" />
+            <RadioListItem label="Option C" value="c" />
+          </RadioList>
+          <button type="button">after</button>
+        </>,
+      );
+      const radios = screen.getAllByRole('radio');
+      const outside = screen.getByText('after');
+      outside.focus();
+      // Backward (Shift+Tab) entry: the browser focuses the last radio; the
+      // group keeps it as the deterministic tab stop rather than jumping away.
+      radios[radios.length - 1].focus();
+      expect(radios[radios.length - 1]).toHaveFocus();
+    });
+
+    it('does not hijack focus moving between radios within the group', () => {
+      render(
+        <RadioList label="Preference" value="" onChange={() => {}}>
+          <RadioListItem label="Option A" value="a" />
+          <RadioListItem label="Option B" value="b" />
+          <RadioListItem label="Option C" value="c" />
+        </RadioList>,
+      );
+      const radios = screen.getAllByRole('radio');
+      // Enter the group from outside, then move to a middle radio as arrow-key
+      // navigation would. Intra-group movement must not be redirected back.
+      radios[0].focus();
+      radios[1].focus();
+      expect(radios[1]).toHaveFocus();
+      radios[2].focus();
+      expect(radios[2]).toHaveFocus();
+    });
+
+    it('skips disabled radios when choosing the deterministic tab stop', () => {
+      render(
+        <>
+          <button type="button">before</button>
+          <RadioList label="Preference" value="" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" isDisabled />
+            <RadioListItem label="Option B" value="b" />
+            <RadioListItem label="Option C" value="c" />
+            <RadioListItem label="Option D" value="d" />
+          </RadioList>
+        </>,
+      );
+      const outside = screen.getByText('before');
+      const optionB = screen.getByLabelText('Option B');
+      const optionC = screen.getByLabelText('Option C');
+      // A middle enabled radio (C) entered from outside is normalized to the
+      // first *enabled* radio (B) — the disabled Option A is skipped.
+      outside.focus();
+      optionC.focus();
+      expect(optionB).toHaveFocus();
+    });
+  });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function renderGroup(props?: {onChange?: (v: string) => void}) {
+      return render(
+        <RadioList
+          label="Plan"
+          value="free"
+          onChange={props?.onChange ?? (() => {})}
+          isDisabled
+          disabledMessage="Upgrade your account to change plans">
+          <RadioListItem label="Free" value="free" />
+          <RadioListItem label="Pro" value="pro" />
+        </RadioList>,
+      );
+    }
+
+    it('shows the reason tooltip on hover when the group is disabled with a reason', async () => {
+      renderGroup();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('Upgrade your account to change plans');
+      const group = screen.getByRole('radiogroup');
+      fireEvent.mouseEnter(group);
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(group);
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      renderGroup();
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <RadioList
+          label="Plan"
+          value="free"
+          onChange={() => {}}
+          disabledMessage="Upgrade your account to change plans">
+          <RadioListItem label="Free" value="free" />
+        </RadioList>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
+          <RadioListItem label="Free" value="free" />
+        </RadioList>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps radios focusable via aria-disabled when a reason is provided', () => {
+      renderGroup();
+      for (const radio of screen.getAllByRole('radio', h)) {
+        expect(radio).not.toBeDisabled();
+        expect(radio).toHaveAttribute('aria-disabled', 'true');
+      }
+    });
+
+    it('links the reason tooltip from the group via aria-describedby', () => {
+      renderGroup();
+      const group = screen.getByRole('radiogroup');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks selection while focusable-disabled', () => {
+      const onChange = vi.fn();
+      renderGroup({onChange});
+      const pro = screen.getByRole('radio', {name: 'Pro', hidden: true});
+      fireEvent.click(pro);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('keeps radios natively disabled when disabled without a reason', () => {
+      render(
+        <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
+          <RadioListItem label="Free" value="free" />
+          <RadioListItem label="Pro" value="pro" />
+        </RadioList>,
+      );
+      for (const radio of screen.getAllByRole('radio', h)) {
+        expect(radio).toBeDisabled();
+      }
+    });
+  });
 });