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

package/src/Switch/Switch.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Switch.tsx
- * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus
+ * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
  * @output Exports Switch component, SwitchProps, SwitchLabelPosition, SwitchLabelSpacing
  * @position Core implementation; consumed by index.ts, tested by Switch.test.tsx
  *
@@ -39,11 +39,13 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
-import {mergeProps} from '../utils';
+import {useTooltip} from '../Tooltip';
+import {mergeProps, mergeRefs} from '../utils';
 import {switchScope} from './switch.markers.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 // Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)
 const SWITCH_WIDTH = 40;
@@ -179,17 +181,6 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-supporting-size'],
     color: colorVars['--color-text-secondary'],
   },
-  srOnly: {
-    position: 'absolute',
-    width: 1,
-    height: 1,
-    padding: 0,
-    margin: -1,
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
 });
 
 export type SwitchLabelPosition = 'start' | 'end';
@@ -237,6 +228,27 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the switch is disabled. When set together with `isDisabled`,
+   * the switch shows a tooltip with this text on hover and keyboard focus, and
+   * the control 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 switch in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <Switch
+   *   label="Enable notifications"
+   *   value={enabled}
+   *   isDisabled
+   *   disabledMessage="Notifications are turned off org-wide"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /**
    * Whether the field is optional. Mutually exclusive with isRequired.
    * @default false
@@ -322,6 +334,7 @@ export function Switch({
   isLoading = false,
   value,
   isDisabled = false,
+  disabledMessage,
   isOptional = false,
   isRequired = false,
   onFocus,
@@ -347,6 +360,19 @@ export function Switch({
 
   const isOn = optimisticValue === true;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the switch row (which already exists) and the
+  // native checkbox stays perceivable via aria-disabled instead of the disabled
+  // attribute. Toggling is blocked by the isDisabled guard in onChange.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container row is not naturally focusable; focusin bubbles up from the
+    // native input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Build aria-describedby from description and status message
   // Only include descriptionID when the element actually renders
   const describedByParts: string[] = [];
@@ -356,21 +382,28 @@ export function Switch({
   if (status?.message) {
     describedByParts.push(statusMessageID);
   }
+  if (showsDisabledMessage) {
+    describedByParts.push(disabledMessageTooltip.describedBy);
+  }
   const ariaDescribedBy =
     describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
 
   const switchElement = (
     <div {...stylex.props(styles.switchWrapper)}>
       <input
-        ref={ref}
+        ref={mergeRefs(ref, disabledMessageTooltip.positionRef)}
         id={id}
         type="checkbox"
         role="switch"
         checked={isOn}
-        disabled={isDisabled}
+        // With a disabledMessage the switch keeps focusability via aria-disabled
+        // so the reason is focus-discoverable; toggling is still blocked by the
+        // isDisabled guard in onChange below.
+        disabled={isDisabled && !showsDisabledMessage}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
         required={isRequired}
         onChange={e => {
-          if (isBusy) {
+          if (isDisabled || isBusy) {
             return;
           }
           const checked = e.target.checked;
@@ -416,11 +449,7 @@ export function Switch({
           {isBusy && <Spinner size="sm" />}
         </div>
       </div>
-      {isBusy && (
-        <span {...stylex.props(styles.srOnly)} role="status">
-          Loading
-        </span>
-      )}
+      {isBusy && <VisuallyHidden role="status">Loading</VisuallyHidden>}
     </div>
   );
 
@@ -453,6 +482,15 @@ export function Switch({
         style,
       )}>
       <div
+        ref={el => {
+          // Interaction (hover/focus) listeners for the disabled-message
+          // tooltip attach to the whole row for a larger trigger target;
+          // positioning anchors on the switch itself (above) so the tooltip
+          // appears next to the control, not the far edge of the row.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.interactionRef(el);
+        }}
         {...stylex.props(
           styles.container,
           labelSpacing === 'spread' && styles.containerSpread,
@@ -481,6 +519,8 @@ export function Switch({
           />
         </div>
       )}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </div>
   );
 }

package/src/TabList/Tab.tsx

@@ -259,7 +259,13 @@ export function Tab({
     ...restProps,
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
+    'data-tab-value': value,
     'aria-current': isSelected ? ('page' as const) : undefined,
+    // Roving tabindex: the tab strip is a single Tab stop. The selected tab is
+    // the tabbable one; the rest are reachable via arrow keys (handled by
+    // TabList's onKeyDown). When no tab is selected, TabList's repair effect
+    // makes the first stop tabbable.
+    tabIndex: isSelected ? 0 : -1,
     ...mergeProps(
       themeProps('tab', {
         selected: isSelected ? 'selected' : null,

package/src/TabList/TabList.doc.mjs

@@ -43,12 +43,24 @@ export const docs = {
       description: 'Size variant applied to all child tabs.',
       default: "'md'",
     },
+    {
+      name: 'layout',
+      type: "'hug' | 'fill'",
+      description: "Layout mode for tab sizing. 'hug': each tab hugs its content width. 'fill': tabs stretch equally to fill the container width.",
+      default: "'hug'",
+    },
     {
       name: 'hasDivider',
       type: 'boolean',
       description: 'Whether to show a bottom border divider under the tab list.',
       default: 'false',
     },
+    {
+      name: 'orientation',
+      type: "'horizontal' | 'vertical'",
+      description: "Orientation of the tab strip, controlling which arrow keys move focus between tabs and the reported aria-orientation. 'horizontal': ArrowLeft/ArrowRight. 'vertical': ArrowUp/ArrowDown. Both axes' arrows are accepted regardless.",
+      default: "'horizontal'",
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/TabList/TabList.test.tsx

@@ -280,6 +280,214 @@ describe('TabList', () => {
   });
 });
 
+describe('TabList keyboard navigation (roving tabindex)', () => {
+  it('exposes the tab strip as a single Tab stop (only selected tab is tabbable)', () => {
+    render(
+      <TabList value="settings" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+        <Tab value="profile" label="Profile" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
+      'tabindex',
+      '-1',
+    );
+    expect(screen.getByRole('button', {name: 'Settings'})).toHaveAttribute(
+      'tabindex',
+      '0',
+    );
+    expect(screen.getByRole('button', {name: 'Profile'})).toHaveAttribute(
+      'tabindex',
+      '-1',
+    );
+  });
+
+  it('makes the first tab tabbable when the selected value matches no tab', () => {
+    render(
+      <TabList value="__none__" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
+      'tabindex',
+      '0',
+    );
+    expect(screen.getByRole('button', {name: 'Settings'})).toHaveAttribute(
+      'tabindex',
+      '-1',
+    );
+  });
+
+  it('moves focus with ArrowRight and ArrowLeft', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+        <Tab value="profile" label="Profile" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const settings = screen.getByRole('button', {name: 'Settings'});
+    const profile = screen.getByRole('button', {name: 'Profile'});
+
+    home.focus();
+    expect(home).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(settings).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(profile).toHaveFocus();
+
+    await user.keyboard('{ArrowLeft}');
+    expect(settings).toHaveFocus();
+  });
+
+  it('supports ArrowDown and ArrowUp as forward/backward as well', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const settings = screen.getByRole('button', {name: 'Settings'});
+
+    home.focus();
+    await user.keyboard('{ArrowDown}');
+    expect(settings).toHaveFocus();
+
+    await user.keyboard('{ArrowUp}');
+    expect(home).toHaveFocus();
+  });
+
+  it('jumps to first and last tab with Home and End', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="settings" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+        <Tab value="profile" label="Profile" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const settings = screen.getByRole('button', {name: 'Settings'});
+    const profile = screen.getByRole('button', {name: 'Profile'});
+
+    settings.focus();
+
+    await user.keyboard('{End}');
+    expect(profile).toHaveFocus();
+
+    await user.keyboard('{Home}');
+    expect(home).toHaveFocus();
+  });
+
+  it('wraps around at the ends', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+        <Tab value="profile" label="Profile" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const profile = screen.getByRole('button', {name: 'Profile'});
+
+    home.focus();
+    await user.keyboard('{ArrowLeft}');
+    expect(profile).toHaveFocus();
+
+    await user.keyboard('{ArrowRight}');
+    expect(home).toHaveFocus();
+  });
+
+  it('skips disabled tabs during arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" aria-disabled="true" />
+        <Tab value="profile" label="Profile" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const profile = screen.getByRole('button', {name: 'Profile'});
+
+    home.focus();
+    await user.keyboard('{ArrowRight}');
+    expect(profile).toHaveFocus();
+  });
+
+  it('does not intercept unrelated keys', async () => {
+    const user = userEvent.setup();
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    home.focus();
+    await user.keyboard('a');
+    expect(home).toHaveFocus();
+  });
+
+  it('composes consumer onKeyDown with internal arrow navigation', async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+
+    render(
+      <TabList value="home" onChange={() => {}} onKeyDown={onKeyDown}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    const settings = screen.getByRole('button', {name: 'Settings'});
+
+    home.focus();
+    await user.keyboard('{ArrowRight}');
+
+    expect(onKeyDown).toHaveBeenCalled();
+    expect(settings).toHaveFocus();
+  });
+
+  it('respects preventDefault from consumer onKeyDown', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <TabList
+        value="home"
+        onChange={() => {}}
+        onKeyDown={e => e.preventDefault()}>
+        <Tab value="home" label="Home" />
+        <Tab value="settings" label="Settings" />
+      </TabList>,
+    );
+
+    const home = screen.getByRole('button', {name: 'Home'});
+    home.focus();
+    await user.keyboard('{ArrowRight}');
+
+    expect(home).toHaveFocus();
+  });
+});
+
 describe('Tab polymorphic link', () => {
   it('renders custom component when href and as are provided', () => {
     render(

package/src/TabList/TabList.tsx

@@ -4,9 +4,11 @@
 
 /**
  * @file TabList.tsx
- * @input Uses React, StyleX, TabListContext
+ * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint
  * @output Exports TabList component and TabListProps type
- * @position Nav wrapper; provides TabListContext to Tab and TabMenu children
+ * @position Nav wrapper; provides TabListContext to Tab and TabMenu children.
+ *   Owns roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
+ *   strip via the shared useListFocus hook so it is a single Tab stop.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TabList/TabList.doc.mjs
@@ -15,21 +17,27 @@
  * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
  */
 
-import React, {useMemo, type ReactNode} from 'react';
+import React, {useCallback, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {borderVars, colorVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {TabListContext} from './TabListContext';
-import type {TabListSize} from './TabListContext';
+import type {TabListOrientation, TabListSize} from './TabListContext';
 import {useSize} from '../SizeContext/SizeContext';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
+import {useListFocus} from '../hooks/useListFocus';
+import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 
-export interface TabListProps extends Omit<
-  BaseProps<HTMLElement>,
-  'onChange'
-> {
+/**
+ * Selector matching the focusable stops in the tab strip: every Tab
+ * (`[data-tab-value]`) and every TabMenu trigger (`[data-tab-menu]`),
+ * in DOM order. Disabled stops are filtered out by the handler.
+ */
+const TAB_STOP_SELECTOR = '[data-tab-value],[data-tab-menu]';
+
+export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
   ref?: React.Ref<HTMLElement>;
   /**
    * The currently selected tab value.
@@ -57,6 +65,15 @@ export interface TabListProps extends Omit<
    * @default false
    */
   hasDivider?: boolean;
+  /**
+   * Orientation of the tab strip, controlling which arrow keys move
+   * focus between tabs.
+   * - `'horizontal'` (default): ArrowLeft / ArrowRight (ArrowUp / ArrowDown
+   *   also work per the WAI-ARIA APG).
+   * - `'vertical'`: ArrowUp / ArrowDown (ArrowLeft / ArrowRight also work).
+   * @default 'horizontal'
+   */
+  orientation?: TabListOrientation;
   /**
    * Tab and TabMenu children.
    */
@@ -104,26 +121,98 @@ export function TabList({
   size: sizeProp,
   layout = 'hug',
   hasDivider = false,
+  orientation = 'horizontal',
   xstyle,
   className,
   style,
   children,
+  onKeyDown: onKeyDownProp,
+  onFocus: onFocusProp,
+  onBlur: onBlurProp,
+  'aria-label': ariaLabel = 'Tabs',
+  'aria-orientation': _ariaOrientation,
+  [EDGE_COMP_ATTR]: _edgeCompAttr,
   ...restProps
 }: TabListProps) {
   const size = useSize(sizeProp, 'md');
 
+  // Roving-tabindex keyboard navigation across the tab strip via the shared
+  // hook. `orientation: 'both'` accepts both arrow axes per the WAI-ARIA APG
+  // allowance for tab strips (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp
+  // retreat) regardless of the component's `orientation` prop, which only
+  // drives the reported `aria-orientation`.
+  //
+  // `hasRovingTabIndex` makes the hook own the single tab stop: it stamps
+  // tabindex 0/-1, repairs the stop on mount and as stops mount/unmount or
+  // toggle disabled, and — via `handleFocus` on the nav — keeps the stop in
+  // sync after clicks or programmatic focus. Individual Tabs still render
+  // `tabIndex={isSelected ? 0 : -1}` (see Tab.tsx) as the initial source of
+  // truth; the hook's repair preserves an existing tab stop and only promotes
+  // the first enabled stop when none is tabbable.
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLElement>({
+    itemSelector: TAB_STOP_SELECTOR,
+    orientation: 'both',
+    hasRovingTabIndex: true,
+  });
+
+  const {
+    hintElement,
+    onKeyDown: onHintKeyDown,
+    onFocus: onHintFocus,
+    onBlur: onHintBlur,
+  } = useKeyboardHint({orientation});
+
   const contextValue = useMemo(
     () => ({value, onChange, size, layout}),
     [value, onChange, size, layout],
   );
 
+  const handleRootKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      onKeyDownProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintKeyDown(e);
+      handleKeyDown(e);
+    },
+    [onKeyDownProp, onHintKeyDown, handleKeyDown],
+  );
+
+  const handleRootFocus = useCallback(
+    (e: React.FocusEvent<HTMLElement>) => {
+      onFocusProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintFocus(e);
+      handleFocus(e);
+    },
+    [onFocusProp, onHintFocus, handleFocus],
+  );
+
+  const handleRootBlur = useCallback(
+    (e: React.FocusEvent<HTMLElement>) => {
+      onBlurProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintBlur(e);
+    },
+    [onBlurProp, onHintBlur],
+  );
+
   return (
     <TabListContext value={contextValue}>
       <nav
-        ref={ref}
-        aria-label="Tabs"
-        {...{[EDGE_COMP_ATTR]: ''}}
+        ref={mergeRefs(ref, listRef)}
         {...restProps}
+        aria-label={ariaLabel}
+        aria-orientation={orientation}
+        onKeyDown={handleRootKeyDown}
+        onFocus={handleRootFocus}
+        onBlur={handleRootBlur}
+        {...{[EDGE_COMP_ATTR]: ''}}
         {...mergeProps(
           themeProps('tab-list', {size}),
           stylex.props(
@@ -136,6 +225,7 @@ export function TabList({
           style,
         )}>
         {children}
+        {hintElement}
       </nav>
     </TabListContext>
   );

package/src/TabList/TabListContext.ts

@@ -26,6 +26,12 @@ export type TabListSize = 'sm' | 'md' | 'lg';
  */
 export type TabListLayout = 'hug' | 'fill';
 
+/**
+ * Orientation of the tab strip. Controls which arrow keys move focus
+ * between tabs and the reported `aria-orientation`.
+ */
+export type TabListOrientation = 'horizontal' | 'vertical';
+
 /**
  * Context for communicating value/onChange/size/layout from TabList to children.
  */
@@ -36,9 +42,7 @@ export interface TabListContextValue {
   layout: TabListLayout;
 }
 
-export const TabListContext = createContext<TabListContextValue | null>(
-  null,
-);
+export const TabListContext = createContext<TabListContextValue | null>(null);
 TabListContext.displayName = 'TabListContext';
 
 /**

package/src/TabList/TabMenu.tsx

@@ -267,6 +267,9 @@ export function TabMenu({
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="menu" is the exposed semantics; a modal dialog
+    // wrapper would announce an unnamed dialog around the menu.
+    role: 'none',
   });
 
   const {listRef, handleKeyDown: handleListKeyDown} =
@@ -306,6 +309,8 @@ export function TabMenu({
         aria-haspopup="menu"
         aria-expanded={popover.isOpen}
         aria-controls={menuId}
+        data-tab-menu=""
+        tabIndex={hasSelectedOption ? 0 : -1}
         onClick={handleToggle}
         {...mergeProps(
           themeProps('tab-menu'),
@@ -390,9 +395,7 @@ export function TabMenu({
                     })}
                   {option.label}
                 </span>
-                {isSelected && (
-                  <Icon icon="check" size="sm" color="accent" />
-                )}
+                {isSelected && <Icon icon="check" size="sm" color="accent" />}
               </div>
             );
           })}