@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

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

package/src/RadioList/RadioList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file RadioList.tsx
- * @input Uses React useId, createContext, ReactNode, Field, InputStatus
+ * @input Uses React useId, useCallback, useRef, createContext, ReactNode, Field, InputStatus
  * @output Exports RadioList component, RadioListProps, RadioListContext
  * @position Core implementation; consumed by index.ts, tested by RadioList.test.tsx
  *
@@ -16,11 +16,19 @@
  * - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
-import React, {createContext, useId, useMemo, type ReactNode} from 'react';
+import React, {
+  createContext,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
+import {useTooltip} from '../Tooltip';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -36,13 +44,21 @@ export interface RadioListContextValue {
   value: string;
   onChange: (value: string) => void;
   isDisabled: boolean;
+  /**
+   * True when the whole group is disabled *and* a `disabledMessage` is set. In
+   * that mode radios stay focusable via `aria-disabled` (instead of the native
+   * `disabled` attribute) so the disabled-reason tooltip is keyboard- and
+   * AT-discoverable; selection is still blocked in the item's onChange guard.
+   */
+  hasDisabledMessage: boolean;
   isRequired: boolean;
   size: RadioListSize;
   status?: InputStatus;
 }
 
-export const RadioListContext =
-  createContext<RadioListContextValue | null>(null);
+export const RadioListContext = createContext<RadioListContextValue | null>(
+  null,
+);
 RadioListContext.displayName = 'RadioListContext';
 
 const styles = stylex.create({
@@ -95,6 +111,17 @@ export interface RadioListProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the radio group is disabled. Applies to the whole-group
+   * disabled state (`isDisabled`), not individual items. When set together with
+   * `isDisabled`, the group shows a tooltip with this text on hover and keyboard
+   * focus, and its radios stay focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Selection stays blocked.
+   *
+   * Use this instead of wrapping a disabled group in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * Whether the radio group is required.
    * @default false
@@ -161,6 +188,7 @@ export function RadioList({
   onChange,
   orientation = 'vertical',
   isDisabled = false,
+  disabledMessage,
   isRequired = false,
   isOptional = false,
   size = 'md',
@@ -175,12 +203,129 @@ export function RadioList({
 }: RadioListProps) {
   const name = useId();
   const inputID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
+  const groupRef = useRef<HTMLDivElement>(null);
+
+  // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+  // controls swallow pointer events, so the tooltip listeners attach to the
+  // radiogroup container and the radios stay perceivable via aria-disabled
+  // instead of the disabled attribute. Selection is blocked in the item's
+  // onChange guard.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The radiogroup container is not naturally focusable; focusin bubbles up
+    // from the radios, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const contextValue = useMemo<RadioListContextValue>(
-    () => ({name, value, onChange, isDisabled, isRequired, size, status}),
-    [name, value, onChange, isDisabled, isRequired, size, status],
+    () => ({
+      name,
+      value,
+      onChange,
+      isDisabled,
+      hasDisabledMessage: showsDisabledMessage,
+      isRequired,
+      size,
+      status,
+    }),
+    [
+      name,
+      value,
+      onChange,
+      isDisabled,
+      showsDisabledMessage,
+      isRequired,
+      size,
+      status,
+    ],
+  );
+
+  /**
+   * Make the tab stop deterministic when a radio group has no selected value.
+   *
+   * Native `<input type="radio">` groups (same `name`) implement roving
+   * tabindex for free: when a value is selected, that radio is the single tab
+   * stop and receives focus, so no correction is needed there. But the ARIA
+   * radio-group pattern (APG) also requires a deterministic tab stop when the
+   * group has *no* selection — and browsers disagree here. Chrome, when
+   * Shift+Tab moves focus backward into an unselected group, lands on the
+   * *last* radio; forward Tab lands on the *first*. To keep the entry point
+   * predictable we redirect focus:
+   *   - forward entry  → first enabled radio (APG default)
+   *   - backward entry → last enabled radio (matches Chrome's backward tab)
+   *
+   * The redirect only runs when focus arrives from *outside* the group's own
+   * radios (guarded via `relatedTarget` containment). Moving between radios
+   * inside the group — arrow keys, clicks, programmatic focus of a sibling —
+   * is never hijacked.
+   */
+  const handleFocus = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      // Only correct the no-selection case; a selected value already provides
+      // a deterministic native tab stop.
+      if (value !== '') {
+        return;
+      }
+
+      const group = groupRef.current;
+      if (!group) {
+        return;
+      }
+
+      // Ignore focus moving *within* the group. `relatedTarget` is the element
+      // losing focus; if it was inside the group, this is intra-group movement
+      // (arrow keys, clicking a sibling) and must not be hijacked. Some browsers
+      // report a null `relatedTarget`; fall back to checking whether the group
+      // already contained the active element before this focus landed.
+      const relatedTarget = e.relatedTarget as Node | null;
+      if (relatedTarget) {
+        if (group.contains(relatedTarget)) {
+          return;
+        }
+      } else if (
+        document.activeElement &&
+        document.activeElement !== e.target &&
+        group.contains(document.activeElement)
+      ) {
+        return;
+      }
+
+      const radios = Array.from(
+        group.querySelectorAll<HTMLInputElement>(
+          'input[type="radio"]:not([disabled])',
+        ),
+      );
+      if (radios.length === 0) {
+        return;
+      }
+
+      const target = e.target as HTMLElement;
+      const targetIndex = radios.findIndex(radio => radio === target);
+      // Only correct when the focus target is one of our enabled radios (not a
+      // nested control such as end-content).
+      if (targetIndex === -1) {
+        return;
+      }
+
+      // Infer tab direction from which end the browser chose. On a backward
+      // (Shift+Tab) entry into an unselected group, browsers focus the *last*
+      // radio; keep it as the deterministic backward tab stop. Any other entry
+      // (forward Tab, or a browser that lands mid-group) is normalized to the
+      // *first* enabled radio, the APG default.
+      const isBackwardEntry = targetIndex === radios.length - 1;
+      const intended = isBackwardEntry ? radios[radios.length - 1] : radios[0];
+
+      if (target !== intended) {
+        intended.focus();
+      }
+    },
+    [value],
   );
 
   return (
@@ -191,6 +336,8 @@ export function RadioList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
+      labelID={labelID}
+      isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}
@@ -211,12 +358,21 @@ export function RadioList({
       className={className}
       style={style}>
       <div
+        ref={el => {
+          groupRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.ref(el);
+        }}
         role="radiogroup"
-        aria-label={label}
+        aria-labelledby={labelID}
+        onFocus={handleFocus}
         aria-describedby={
           [
             description ? descriptionID : null,
             status?.message ? statusMessageID : null,
+            showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
           ]
             .filter(Boolean)
             .join(' ') || undefined
@@ -230,10 +386,10 @@ export function RadioList({
             orientation === 'vertical' ? styles.vertical : styles.horizontal,
           ),
         )}>
-        <RadioListContext value={contextValue}>
-          {children}
-        </RadioListContext>
+        <RadioListContext value={contextValue}>{children}</RadioListContext>
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/RadioList/RadioListItem.tsx

@@ -230,6 +230,12 @@ export function RadioListItem({
   const id = useId();
   const descriptionID = useId();
   const isDisabled = context.isDisabled || isItemDisabled;
+  // When the whole group is disabled with a disabledMessage, radios stay
+  // focusable via aria-disabled (instead of native `disabled`) so the group's
+  // reason tooltip is keyboard-discoverable. Per-item disabling is unaffected
+  // and always uses the native disabled attribute.
+  const keepsFocusableForMessage =
+    context.hasDisabledMessage && !isItemDisabled;
   const isChecked = context.value === value;
   const size = context.size;
 
@@ -246,9 +252,15 @@ export function RadioListItem({
         name={context.name}
         value={value}
         checked={isChecked}
-        disabled={isDisabled}
+        disabled={isDisabled && !keepsFocusableForMessage}
+        aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
         required={context.isRequired}
-        onChange={() => context.onChange(value)}
+        onChange={() => {
+          if (isDisabled) {
+            return;
+          }
+          context.onChange(value);
+        }}
         aria-describedby={description ? descriptionID : undefined}
         {...stylex.props(
           styles.input,

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -65,6 +65,12 @@ export const docs = {
       description: 'Whether the entire control is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -97,6 +103,7 @@ export const docs = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -111,6 +118,7 @@ export const docsZh = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -125,6 +133,7 @@ export const docsDense = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {