@astryxdesign/core 0.1.2 → 0.1.3

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -9,12 +9,39 @@
  * SYNC: When SegmentedControl components change, 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 {SegmentedControl} from './SegmentedControl';
 import {SegmentedControlItem} from './SegmentedControlItem';
 
+// 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('SegmentedControl', () => {
   it('renders a radiogroup with radio buttons', () => {
     render(
@@ -56,10 +83,7 @@ describe('SegmentedControl', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
       </SegmentedControl>,
@@ -74,10 +98,7 @@ describe('SegmentedControl', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
       </SegmentedControl>,
@@ -196,6 +217,45 @@ describe('SegmentedControl', () => {
       '-1',
     );
   });
+
+  it('keeps a tab stop when the value matches no item (tab-stop repair)', () => {
+    render(
+      <SegmentedControl
+        value="nonexistent"
+        onChange={() => {}}
+        label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" />
+        <SegmentedControlItem value="table" label="Table" />
+      </SegmentedControl>,
+    );
+
+    // No item is selected, but the group must remain Tab-reachable: the first
+    // enabled radio is promoted to tabIndex=0.
+    expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+      'tabIndex',
+      '0',
+    );
+  });
+
+  it('promotes the first enabled item when the value matches no item and the first is disabled', () => {
+    render(
+      <SegmentedControl
+        value="nonexistent"
+        onChange={() => {}}
+        label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" isDisabled />
+        <SegmentedControlItem value="list" label="List" />
+        <SegmentedControlItem value="table" label="Table" />
+      </SegmentedControl>,
+    );
+
+    // The disabled first item is skipped; the first ENABLED radio is tabbable.
+    expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+      'tabIndex',
+      '0',
+    );
+  });
 });
 
 describe('SegmentedControl keyboard navigation', () => {
@@ -204,10 +264,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -226,10 +283,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="list"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="list" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -248,10 +302,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="table"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="table" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -270,10 +321,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -292,10 +340,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="table"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="table" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -314,10 +359,7 @@ describe('SegmentedControl keyboard navigation', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" />
         <SegmentedControlItem value="table" label="Table" />
@@ -351,6 +393,41 @@ describe('SegmentedControl disabled state', () => {
     );
   });
 
+  it('removes the tab stop from the selected item when the group is disabled (navigation-13)', () => {
+    render(
+      <SegmentedControl
+        value="grid"
+        onChange={() => {}}
+        label="View mode"
+        isDisabled>
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" />
+      </SegmentedControl>,
+    );
+    // Selected segment must not be a focusable-but-dead tab stop when disabled.
+    const selected = screen.getByRole('radio', {name: 'Grid'});
+    expect(selected).toHaveAttribute('tabIndex', '-1');
+    expect(selected).toHaveAttribute('aria-disabled', 'true');
+    // No enabled segment is tabbable either.
+    expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
+      'tabIndex',
+      '-1',
+    );
+  });
+
+  it('removes the tab stop from an individually disabled selected item', () => {
+    render(
+      <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" isDisabled />
+        <SegmentedControlItem value="list" label="List" />
+      </SegmentedControl>,
+    );
+    expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
+      'tabIndex',
+      '-1',
+    );
+  });
+
   it('does not call onChange when group is disabled', async () => {
     const user = userEvent.setup({pointerEventsCheck: 0});
     const handleChange = vi.fn();
@@ -375,10 +452,7 @@ describe('SegmentedControl disabled state', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" isDisabled />
       </SegmentedControl>,
@@ -398,10 +472,7 @@ describe('SegmentedControl disabled state', () => {
     const handleChange = vi.fn();
 
     render(
-      <SegmentedControl
-        value="grid"
-        onChange={handleChange}
-        label="View mode">
+      <SegmentedControl value="grid" onChange={handleChange} label="View mode">
         <SegmentedControlItem value="grid" label="Grid" />
         <SegmentedControlItem value="list" label="List" isDisabled />
         <SegmentedControlItem value="table" label="Table" />
@@ -415,4 +486,105 @@ describe('SegmentedControl disabled state', () => {
     expect(handleChange).toHaveBeenCalledWith('table');
     expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function renderControl(props?: {onChange?: (v: string) => void}) {
+      return render(
+        <SegmentedControl
+          value="grid"
+          onChange={props?.onChange ?? (() => {})}
+          label="View mode"
+          isDisabled
+          disabledMessage="Choose a project to switch views">
+          <SegmentedControlItem value="grid" label="Grid" />
+          <SegmentedControlItem value="list" label="List" />
+        </SegmentedControl>,
+      );
+    }
+
+    it('shows the reason tooltip on hover when the control is disabled with a reason', async () => {
+      renderControl();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('Choose a project to switch views');
+      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();
+      renderControl();
+      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(
+        <SegmentedControl
+          value="grid"
+          onChange={() => {}}
+          label="View mode"
+          disabledMessage="Choose a project to switch views">
+          <SegmentedControlItem value="grid" label="Grid" />
+        </SegmentedControl>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <SegmentedControl
+          value="grid"
+          onChange={() => {}}
+          label="View mode"
+          isDisabled>
+          <SegmentedControlItem value="grid" label="Grid" />
+        </SegmentedControl>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the selected segment focusable when a reason is provided', () => {
+      renderControl();
+      const selected = screen.getByRole('radio', {name: 'Grid', hidden: true});
+      expect(selected).toHaveAttribute('aria-disabled', 'true');
+      expect(selected).toHaveAttribute('tabindex', '0');
+    });
+
+    it('links the reason tooltip from the group via aria-describedby', () => {
+      renderControl();
+      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();
+      renderControl({onChange});
+      const list = screen.getByRole('radio', {name: 'List', hidden: true});
+      fireEvent.click(list);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('drops all segments from the tab order when disabled without a reason', () => {
+      render(
+        <SegmentedControl
+          value="grid"
+          onChange={() => {}}
+          label="View mode"
+          isDisabled>
+          <SegmentedControlItem value="grid" label="Grid" />
+          <SegmentedControlItem value="list" label="List" />
+        </SegmentedControl>,
+      );
+      for (const radio of screen.getAllByRole('radio', h)) {
+        expect(radio).toHaveAttribute('tabindex', '-1');
+      }
+    });
+  });
 });

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,10 +15,13 @@
  * - /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 {useListFocus} from '../hooks/useListFocus';
+import {useKeyboardHint} from '../hooks/useKeyboardHint';
+import {useTooltip} from '../Tooltip';
 import type {
   SegmentedControlSize,
   SegmentedControlLayout,
@@ -62,6 +65,17 @@ export interface SegmentedControlProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the control is disabled. Applies to the whole-group disabled
+   * state (`isDisabled`), not individual segments. When set together with
+   * `isDisabled`, the control shows a tooltip with this text on hover and
+   * keyboard focus, and stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Selection stays blocked.
+   *
+   * Use this instead of wrapping a disabled control in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * SegmentedControlItem children.
    */
@@ -89,6 +103,12 @@ const styles = stylex.create({
     opacity: 0.5,
     pointerEvents: 'none',
   },
+  // Disabled *with* a disabledMessage: keep the dimmed look but leave pointer
+  // events on so the group can receive hover and surface the reason tooltip.
+  // Selection is still blocked by the isDisabled guards.
+  disabledWithMessage: {
+    opacity: 0.5,
+  },
 });
 
 const sizeStyles = stylex.create({
@@ -127,98 +147,126 @@ export function SegmentedControl({
   size: sizeProp,
   layout = 'hug',
   isDisabled = false,
+  disabledMessage,
   children,
   xstyle,
   className,
   style,
 }: SegmentedControlProps) {
   const size = useSize(sizeProp, 'md');
-  const containerRef = useRef<HTMLDivElement>(null);
 
-  const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (isDisabled) {
-        return;
-      }
+  // 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 container keeps pointer events on in this
+  // mode) while the radios stay perceivable via aria-disabled. Selection is
+  // blocked by the isDisabled guards in the click/focus handlers.
+  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 container = containerRef.current;
-      if (!container) {
-        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 items = Array.from(
-        container.querySelectorAll<HTMLButtonElement>(
-          '[role="radio"]:not([aria-disabled="true"])',
-        ),
-      );
-      if (items.length === 0) {
+  const hint = useKeyboardHint({
+    orientation: 'horizontal',
+    isEnabled: !isDisabled,
+  });
+
+  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(
-    () => ({value, onChange, size, layout, isDisabled}),
-    [value, onChange, size, layout, isDisabled],
+    () => ({
+      value,
+      onChange,
+      size,
+      layout,
+      isDisabled,
+      hasDisabledMessage: showsDisabledMessage,
+    }),
+    [value, onChange, size, layout, isDisabled, showsDisabledMessage],
   );
 
   return (
     <SegmentedControlContext value={contextValue}>
       <div
-        ref={mergeRefs(ref, containerRef)}
+        ref={mergeRefs(ref, listRef, disabledMessageTooltip.ref)}
         role="radiogroup"
         aria-label={label}
         aria-disabled={isDisabled || undefined}
-        onKeyDown={handleKeyDown}
+        aria-describedby={
+          showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
+        }
+        onKeyDown={handleContainerKeyDown}
+        onFocus={handleContainerFocus}
+        onBlur={hint.onBlur}
         {...mergeProps(
           themeProps('segmented-control', {size}),
           stylex.props(
             styles.container,
             sizeStyles[size],
             layout === 'fill' && styles.fill,
-            isDisabled && styles.disabled,
+            isDisabled &&
+              (showsDisabledMessage
+                ? styles.disabledWithMessage
+                : styles.disabled),
             xstyle,
           ),
           className,
           style,
         )}>
         {children}
+        {hint.hintElement}
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </SegmentedControlContext>
   );
 }

package/src/SegmentedControl/SegmentedControlContext.ts

@@ -22,6 +22,13 @@ export interface SegmentedControlContextValue {
   size: SegmentedControlSize;
   layout: SegmentedControlLayout;
   isDisabled: boolean;
+  /**
+   * True when the whole control is disabled *and* a `disabledMessage` is set.
+   * In that mode the selected segment stays focusable (via `aria-disabled`
+   * rather than being dropped from the tab order) so the group's disabled-reason
+   * tooltip is keyboard-discoverable; selection is still blocked.
+   */
+  hasDisabledMessage?: boolean;
 }
 
 export const SegmentedControlContext =

package/src/SegmentedControl/SegmentedControlItem.tsx

@@ -173,6 +173,12 @@ export function SegmentedControlItem({
 
   const isSelected = ctx.value === value;
   const isItemDisabled = isDisabled || ctx.isDisabled;
+  // When the whole group is disabled with a disabledMessage, keep the selected
+  // segment focusable so the group's reason tooltip is keyboard-discoverable.
+  // Per-item disabling (`isDisabled` on the item) always drops out of the tab
+  // order. Activation stays blocked by the isItemDisabled guard in handleClick.
+  const keepsSelectedFocusable =
+    isSelected && (ctx.hasDisabledMessage ?? false) && !isDisabled;
   const size: SegmentedControlSize = ctx.size;
   const isFill = ctx.layout === 'fill';
 
@@ -195,7 +201,14 @@ export function SegmentedControlItem({
       aria-disabled={isItemDisabled || undefined}
       aria-label={isLabelHidden ? label : undefined}
       data-value={value}
-      tabIndex={isSelected ? 0 : -1}
+      // Disabled items (including when the whole group is disabled) are not tab
+      // stops — otherwise the selected segment stays keyboard-focusable but is
+      // silently dead (arrows and activation are no-ops) (navigation-13). The
+      // exception is a whole-group disabledMessage, where the selected segment
+      // stays focusable so the reason tooltip is keyboard-discoverable.
+      tabIndex={
+        (isSelected && !isItemDisabled) || keepsSelectedFocusable ? 0 : -1
+      }
       onClick={handleClick}
       {...mergeProps(
         themeProps('segmented-control-item', {

package/src/SelectableCard/SelectableCard.doc.mjs

@@ -46,7 +46,7 @@ export const docs = {
         props: {gap: 1},
         children: [
           {__element: 'XDSHeading', props: {level: 3}, children: 'Pro plan'},
-          {__element: 'XDSText', props: {type: 'body'}, children: '$29/month — unlimited projects and priority support.'},
+          {__element: 'XDSText', props: {type: 'body'}, children: '$29/month, unlimited projects and priority support.'},
         ],
       },
     },