@astryxdesign/core 0.1.2-canary.bfcbf64 → 0.1.2-canary.c395fca

package/src/MultiSelector/MultiSelector.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} 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 {MultiSelector} from './MultiSelector';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -893,4 +893,153 @@ describe('MultiSelector', () => {
       });
     });
   });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Select a table first"
+          data-testid="fruit-multi-selector"
+        />,
+      );
+
+      const container = screen.getByTestId('fruit-multi-selector');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('Select a table first');
+
+      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(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Select a table first"
+        />,
+      );
+
+      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(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          disabledMessage="Select a table first"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the trigger focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Select a table first"
+        />,
+      );
+      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(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Select a table first"
+        />,
+      );
+      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(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Select a table first"
+        />,
+      );
+
+      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(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      const trigger = screen.getByRole('combobox');
+      expect(trigger).toBeDisabled();
+      expect(trigger).toHaveAttribute('tabIndex', '-1');
+    });
+  });
 });

package/src/MultiSelector/MultiSelector.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file MultiSelector.tsx
- * @input Uses React, StyleX, usePopover, CheckboxInput, Field, Badge, Icon
+ * @input Uses React, StyleX, usePopover, useTooltip, CheckboxInput, Field, Badge, Icon
  * @output Exports MultiSelector component
  * @position Core implementation; consumed by index.ts
  *
@@ -27,6 +27,7 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useTooltip} from '../Tooltip';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import type {IconName} from '../Icon';
 import {
@@ -398,6 +399,30 @@ export interface MultiSelectorProps<
    */
   isDisabled?: boolean;
 
+  /**
+   * Explains why the selector is disabled. When set together with
+   * `isDisabled`, the selector shows a tooltip with this text on hover and
+   * keyboard focus, and the trigger stays focusable (via `aria-disabled`)
+   * so the reason is discoverable by keyboard and assistive technology.
+   * Activation stays blocked.
+   *
+   * Use this instead of wrapping a disabled selector in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <MultiSelector
+   *   label="Columns"
+   *   options={columns}
+   *   value={selected}
+   *   onChange={setSelected}
+   *   isDisabled
+   *   disabledMessage="Select a table first"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The options to display in the selector.
    * Can be strings, objects, dividers, or sections.
@@ -546,6 +571,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   options,
   value,
   onChange,
@@ -593,11 +619,26 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the trigger container (which already exists)
+  // and the trigger button stays perceivable via aria-disabled instead of the
+  // disabled attribute. Activation is blocked by the isDisabled guards in
+  // useMultiCombobox (onTriggerClick / onKeyDown).
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the trigger button, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Build aria-describedby
   const ariaDescribedBy =
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -1190,6 +1231,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       <div
         ref={el => {
           popover.triggerRef(el);
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, and anchor names
+          // compose, so attaching unconditionally is safe.
+          disabledMessageTooltip.ref(el);
         }}
         onClick={onTriggerClick}
         data-testid={testId}
@@ -1230,9 +1275,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           aria-required={isRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
-          disabled={isDisabled}
+          // With a disabledMessage the trigger keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; activation is
+          // still blocked by the isDisabled guards in useMultiCombobox.
+          disabled={isDisabled && !showsDisabledMessage}
+          aria-disabled={showsDisabledMessage ? 'true' : undefined}
           onKeyDown={onKeyDown}
-          tabIndex={isDisabled ? -1 : 0}
+          tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
           {...stylex.props(styles.trigger)}>
           <span {...stylex.props(styles.triggerContent)}>
             {renderTriggerContent()}
@@ -1283,6 +1332,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           xstyle: styles.popover,
         },
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

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,9 +314,7 @@ export function ProgressBar({
           )}
         </div>
       ) : (
-        <span id={labelId} {...stylex.props(styles.visuallyHidden)}>
-          {label}
-        </span>
+        <VisuallyHidden id={labelId}>{label}</VisuallyHidden>
       )}
 
       {/* Progress track */}

package/src/RadioList/RadioList.tsx

@@ -183,7 +183,7 @@ export function RadioList({
 }: RadioListProps) {
   const name = useId();
   const inputID = useId();
-  const labelElementID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -284,7 +284,7 @@ export function RadioList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
-      labelElementID={labelElementID}
+      labelID={labelID}
       isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
@@ -308,7 +308,7 @@ export function RadioList({
       <div
         ref={groupRef}
         role="radiogroup"
-        aria-labelledby={labelElementID}
+        aria-labelledby={labelID}
         onFocus={handleFocus}
         aria-describedby={
           [

package/src/SegmentedControl/SegmentedControl.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file SegmentedControl.tsx
- * @input Uses React, StyleX, SegmentedControlContext
+ * @input Uses React, StyleX, SegmentedControlContext, useListFocus, useKeyboardHint
  * @output Exports SegmentedControl component and SegmentedControlProps type
  * @position Container wrapper; provides context to SegmentedControlItem children
  *
@@ -15,11 +15,12 @@
  * - /packages/cli/templates/blocks/components/SegmentedControl/ (showcase blocks)
  */
 
-import React, {useMemo, useRef, useCallback, type ReactNode} from 'react';
+import React, {useMemo, useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../theme/tokens.stylex';
 import {SegmentedControlContext} from './SegmentedControlContext';
-import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {useListFocus} from '../hooks/useListFocus';
+import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import type {
   SegmentedControlSize,
   SegmentedControlLayout,
@@ -134,63 +135,58 @@ export function SegmentedControl({
   style,
 }: SegmentedControlProps) {
   const size = useSize(sizeProp, 'md');
-  const containerRef = useRef<HTMLDivElement>(null);
 
-  const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (isDisabled) {
-        return;
-      }
+  // Roving tabindex + arrow/Home/End navigation is owned by the shared
+  // useListFocus primitive: it stamps a single tab stop (tabIndex 0/-1) across
+  // the radios, skips disabled ones, wraps at the ends, handles Home/End, and
+  // repairs the tab stop on mount and whenever items mount/disable — replacing
+  // the component's former inline keyboard handler and tab-stop repair effect.
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: '[role="radio"]:not([aria-disabled="true"])',
+    hasRovingTabIndex: true,
+    wrap: true,
+    orientation: 'horizontal',
+  });
 
-      const container = containerRef.current;
-      if (!container) {
-        return;
-      }
+  const hint = useKeyboardHint({
+    orientation: 'horizontal',
+    isEnabled: !isDisabled,
+  });
 
-      const items = Array.from(
-        container.querySelectorAll<HTMLButtonElement>(
-          '[role="radio"]:not([aria-disabled="true"])',
-        ),
-      );
-      if (items.length === 0) {
+  const handleContainerKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      hint.onKeyDown(e);
+      handleKeyDown(e);
+    },
+    [hint, handleKeyDown],
+  );
+
+  // Selection-follows-focus (APG radiogroup): useListFocus only *moves* focus,
+  // so whenever it lands focus on a new radio (arrow/Home/End, or a click) we
+  // select that radio's value. Reading the focused element's data-value here
+  // keeps selection in lockstep with focus without duplicating the navigation
+  // logic. Disabled radios are ignored (they should never become the value),
+  // and the already-selected value is skipped so an initial Tab-in (or a click
+  // on the current segment) is a no-op, matching click behavior.
+  const handleContainerFocus = useCallback(
+    (e: React.FocusEvent) => {
+      hint.onFocus(e);
+      handleFocus(e);
+      if (isDisabled) {
         return;
       }
-
-      const currentIndex = items.findIndex(
-        item => item === document.activeElement,
+      const focused = (e.target as HTMLElement | null)?.closest<HTMLElement>(
+        '[role="radio"][data-value]',
       );
-      let nextIndex: number;
-
-      switch (e.key) {
-        case 'ArrowRight':
-          nextIndex =
-            currentIndex === -1 ? 0 : (currentIndex + 1) % items.length;
-          break;
-        case 'ArrowLeft':
-          nextIndex =
-            currentIndex === -1
-              ? items.length - 1
-              : (currentIndex - 1 + items.length) % items.length;
-          break;
-        case 'Home':
-          nextIndex = 0;
-          break;
-        case 'End':
-          nextIndex = items.length - 1;
-          break;
-        default:
-          return;
+      if (!focused || focused.getAttribute('aria-disabled') === 'true') {
+        return;
       }
-
-      e.preventDefault();
-      const nextItem = items[nextIndex];
-      nextItem.focus();
-      const nextValue = nextItem.dataset.value;
-      if (nextValue != null) {
+      const nextValue = focused.dataset.value;
+      if (nextValue != null && nextValue !== value) {
         onChange(nextValue);
       }
     },
-    [isDisabled, onChange],
+    [hint, handleFocus, isDisabled, onChange, value],
   );
 
   const contextValue = useMemo(
@@ -198,39 +194,16 @@ export function SegmentedControl({
     [value, onChange, size, layout, isDisabled],
   );
 
-  // Tab-stop repair (navigation-6): each item sets tabIndex=0 only when its
-  // value matches the group value, so a stale/unmatched `value` (or a disabled
-  // selected item) can leave every segment at tabIndex=-1 — making the whole
-  // radiogroup unreachable by Tab. After render, if no enabled radio is
-  // tabbable, promote the first enabled radio to tabIndex=0 so the group always
-  // has exactly one tab stop. Mirrors Base UI's Composite tab-stop repair.
-  useIsomorphicLayoutEffect(() => {
-    const container = containerRef.current;
-    if (!container) {
-      return;
-    }
-    const enabled = Array.from(
-      container.querySelectorAll<HTMLButtonElement>(
-        '[role="radio"]:not([aria-disabled="true"])',
-      ),
-    );
-    if (enabled.length === 0) {
-      return;
-    }
-    const hasTabStop = enabled.some(el => el.tabIndex === 0);
-    if (!hasTabStop) {
-      enabled[0].tabIndex = 0;
-    }
-  });
-
   return (
     <SegmentedControlContext value={contextValue}>
       <div
-        ref={mergeRefs(ref, containerRef)}
+        ref={mergeRefs(ref, listRef)}
         role="radiogroup"
         aria-label={label}
         aria-disabled={isDisabled || undefined}
-        onKeyDown={handleKeyDown}
+        onKeyDown={handleContainerKeyDown}
+        onFocus={handleContainerFocus}
+        onBlur={hint.onBlur}
         {...mergeProps(
           themeProps('segmented-control', {size}),
           stylex.props(
@@ -244,6 +217,7 @@ export function SegmentedControl({
           style,
         )}>
         {children}
+        {hint.hintElement}
       </div>
     </SegmentedControlContext>
   );

package/src/Selector/Selector.doc.mjs

@@ -86,6 +86,12 @@ export const docs = {
       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',
@@ -176,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: [
       {
@@ -263,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: [
       {
@@ -350,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';
@@ -652,4 +652,126 @@ describe('Selector', () => {
       }
     });
   });
+
+  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');
+    });
+  });
 });