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

package/src/Selector/Selector.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Selector.tsx
- * @input Uses React, StyleX, usePopover, Icon
+ * @input Uses React, StyleX, usePopover, useTooltip, Icon
  * @output Exports Selector 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 {
@@ -369,6 +370,28 @@ interface SelectorPropsBase<
    */
   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
+   * ```
+   * <Selector
+   *   label="Owner"
+   *   options={owners}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The options to display in the selector.
    * Can be strings, objects, dividers, or sections.
@@ -525,6 +548,7 @@ export function Selector<T extends SelectorOptionType>(
     isOptional = false,
     isRequired = false,
     isDisabled = false,
+    disabledMessage,
     options,
     value,
     onChange,
@@ -567,11 +591,26 @@ export function Selector<T extends SelectorOptionType>(
   const [optimisticValue, setOptimisticValue] = useOptimistic(normalizedValue);
   const isBusy = isLoading || optimisticValue !== normalizedValue;
 
+  // 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
+  // useCombobox (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;
@@ -902,6 +941,10 @@ export function Selector<T extends SelectorOptionType>(
       <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}
@@ -943,9 +986,13 @@ export function Selector<T extends SelectorOptionType>(
           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 useCombobox.
+          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.triggerLabel)}>
             {selectedItem?.label ?? placeholder}
@@ -1012,6 +1059,9 @@ export function Selector<T extends SelectorOptionType>(
           style: popoverOffsetStyle,
         },
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Switch/Switch.tsx

@@ -44,6 +44,7 @@ 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 +180,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';
@@ -416,11 +406,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>
   );
 

package/src/TabList/TabList.test.tsx

@@ -445,6 +445,47 @@ describe('TabList keyboard navigation (roving tabindex)', () => {
     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', () => {

package/src/TabList/TabList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TabList.tsx
- * @input Uses React, StyleX, TabListContext, useListFocus
+ * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint
  * @output Exports TabList component and TabListProps type
  * @position Nav wrapper; provides TabListContext to Tab and TabMenu children.
  *   Owns roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
@@ -17,7 +17,7 @@
  * - /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';
@@ -26,7 +26,7 @@ import type {TabListOrientation, TabListSize} from './TabListContext';
 import {useSize} from '../SizeContext/SizeContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {useListFocus} from '../hooks/useListFocus';
-import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 
@@ -37,13 +37,6 @@ import {themeProps} from '../utils/themeProps';
  */
 const TAB_STOP_SELECTOR = '[data-tab-value],[data-tab-menu]';
 
-function isDisabledStop(el: HTMLElement): boolean {
-  return (
-    el.getAttribute('aria-disabled') === 'true' ||
-    (el instanceof HTMLButtonElement && el.disabled)
-  );
-}
-
 export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
   ref?: React.Ref<HTMLElement>;
   /**
@@ -133,6 +126,12 @@ export function TabList({
   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');
@@ -142,51 +141,78 @@ export function TabList({
   // allowance for tab strips (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp
   // retreat) regardless of the component's `orientation` prop, which only
   // drives the reported `aria-orientation`.
-  const {listRef, handleKeyDown} = useListFocus<HTMLElement>({
+  //
+  // `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],
   );
 
-  // Roving tabindex: the tab strip is a single Tab stop. Individual Tabs set
-  // tabIndex={0} on the selected tab and -1 on the rest (see Tab.tsx). If the
-  // selected value doesn't correspond to any focusable stop (e.g. selection
-  // lives in a collapsed TabMenu that renders no matching stop, or there is no
-  // selection at all), no stop would be tabbable — this effect repairs that by
-  // making the first stop tabbable. useListFocus handles arrow navigation but
-  // not the initial tabbable stop, so this stays. Same pattern as the
-  // SegmentedControl fix.
-  useIsomorphicLayoutEffect(() => {
-    const nav = listRef.current;
-    if (nav == null) {
-      return;
-    }
-    const stops = Array.from(
-      nav.querySelectorAll<HTMLElement>(TAB_STOP_SELECTOR),
-    );
-    if (stops.length === 0) {
-      return;
-    }
-    const hasTabbable = stops.some(el => el.tabIndex === 0);
-    if (!hasTabbable) {
-      const firstEnabled = stops.find(el => !isDisabledStop(el)) ?? stops[0];
-      firstEnabled.tabIndex = 0;
-    }
-  });
+  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={mergeRefs(ref, listRef)}
-        aria-label="Tabs"
+        {...restProps}
+        aria-label={ariaLabel}
         aria-orientation={orientation}
-        onKeyDown={handleKeyDown}
+        onKeyDown={handleRootKeyDown}
+        onFocus={handleRootFocus}
+        onBlur={handleRootBlur}
         {...{[EDGE_COMP_ATTR]: ''}}
-        {...restProps}
         {...mergeProps(
           themeProps('tab-list', {size}),
           stylex.props(
@@ -199,6 +225,7 @@ export function TabList({
           style,
         )}>
         {children}
+        {hintElement}
       </nav>
     </TabListContext>
   );

package/src/Table/tableContextMenu.tsx

@@ -107,7 +107,6 @@ function LazyTableContextMenu({
   return (
     <ContextMenu
       items={options ?? []}
-      hasAutoFocus={false}
       onOpenChange={open => {
         // Resolve actions when opening; clear on close so state derived later
         // (e.g. current sort direction) is always fresh next open.
@@ -135,12 +134,9 @@ export function wrapInTableContextMenu(
   if (!actions || actions.length === 0) {
     return element;
   }
-  // hasAutoFocus={false}: a right-click menu shouldn't pre-highlight the first
   // item (it looked like "ascending" was always selected). Focus moves only
   // when the user arrow-keys into the menu.
   return (
-    <ContextMenu items={toContextMenuOptions(actions)} hasAutoFocus={false}>
-      {element}
-    </ContextMenu>
+    <ContextMenu items={toContextMenuOptions(actions)}>{element}</ContextMenu>
   );
 }

package/src/TextArea/TextArea.tsx

@@ -49,6 +49,7 @@ import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
@@ -93,17 +94,6 @@ const styles = stylex.create({
   counterError: {
     color: colorVars['--color-error'],
   },
-  srOnly: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0,0,0,0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   statusIcon: {
     position: 'absolute',
     top: spacingVars['--spacing-2'],
@@ -451,13 +441,13 @@ export function TextArea({
             optimisticValue.length > maxLength && styles.counterError,
           )}>
           {optimisticValue.length}/{maxLength}
-          <span aria-live="polite" {...stylex.props(styles.srOnly)}>
+          <VisuallyHidden aria-live="polite">
             {optimisticValue.length >= maxLength * COUNTER_WARNING_THRESHOLD
               ? optimisticValue.length > maxLength
                 ? `${optimisticValue.length - maxLength} characters over limit`
                 : `${maxLength - optimisticValue.length} characters remaining`
               : ''}
-          </span>
+          </VisuallyHidden>
         </div>
       )}
     </Field>

package/src/Toolbar/Toolbar.test.tsx

@@ -71,9 +71,12 @@ describe('Toolbar', () => {
     expect(screen.getByTestId('center')).toBeInTheDocument();
     expect(screen.getByTestId('end')).toBeInTheDocument();
 
-    // Three-slot layout produces 3 child divs
+    // Three-slot layout produces 3 child divs (plus the aria-hidden
+    // keyboard-hint popover, which is excluded here as an implementation detail)
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.children).toHaveLength(3);
+    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
+      3,
+    );
   });
 
   it('renders two-slot layout without centerContent', () => {
@@ -87,9 +90,12 @@ describe('Toolbar', () => {
     expect(screen.getByTestId('start')).toBeInTheDocument();
     expect(screen.getByTestId('end')).toBeInTheDocument();
 
-    // Two-slot layout produces 2 child divs
+    // Two-slot layout produces 2 child divs (plus the aria-hidden
+    // keyboard-hint popover, excluded here)
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.children).toHaveLength(2);
+    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
+      2,
+    );
   });
 
   it('renders start-only layout', () => {
@@ -101,7 +107,9 @@ describe('Toolbar', () => {
     );
     expect(screen.getByTestId('start')).toBeInTheDocument();
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.children).toHaveLength(1);
+    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
+      1,
+    );
   });
 
   it('renders end-only layout', () => {
@@ -113,7 +121,9 @@ describe('Toolbar', () => {
     );
     expect(screen.getByTestId('end')).toBeInTheDocument();
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.children).toHaveLength(1);
+    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
+      1,
+    );
   });
 
   it('sets aria-orientation to horizontal by default', () => {
@@ -301,4 +311,52 @@ describe('Toolbar', () => {
     // Caret movement stays in the input; focus is not stolen by the toolbar.
     expect(document.activeElement).toBe(inputEl);
   });
+
+  it('composes consumer onKeyDown with internal arrow navigation', async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+
+    render(
+      <Toolbar
+        label="Actions"
+        onKeyDown={onKeyDown}
+        startContent={
+          <>
+            <button type="button">Cut</button>
+            <button type="button">Copy</button>
+          </>
+        }
+      />,
+    );
+
+    const buttons = screen.getAllByRole('button');
+    buttons[0].focus();
+    await user.keyboard('{ArrowRight}');
+
+    expect(onKeyDown).toHaveBeenCalled();
+    expect(buttons[1]).toHaveFocus();
+  });
+
+  it('respects preventDefault from consumer onKeyDown', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Toolbar
+        label="Actions"
+        onKeyDown={e => e.preventDefault()}
+        startContent={
+          <>
+            <button type="button">Cut</button>
+            <button type="button">Copy</button>
+          </>
+        }
+      />,
+    );
+
+    const buttons = screen.getAllByRole('button');
+    buttons[0].focus();
+    await user.keyboard('{ArrowRight}');
+
+    expect(buttons[0]).toHaveFocus();
+  });
 });

package/src/Toolbar/Toolbar.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Toolbar.tsx
- * @input Uses Section, SizeContext, useListFocus, StyleX, spacingVars, sizeVars
+ * @input Uses Section, SizeContext, useListFocus, useKeyboardHint, StyleX, spacingVars, sizeVars
  * @output Exports Toolbar component and ToolbarProps
  * @position Core implementation; consumed by index.ts
  *
@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/Toolbar/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {useCallback, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import type {SectionVariant} from '../Section/Section';
 import type {SpacingStep} from '../utils/types';
@@ -26,6 +26,7 @@ import {spacingVars, sizeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {Section} from '../Section/Section';
 import {useListFocus} from '../hooks/useListFocus';
+import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import {SizeProvider} from '../SizeContext/SizeContext';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
@@ -227,6 +228,12 @@ export function Toolbar({
   className,
   style,
   ref,
+  onKeyDown: onKeyDownProp,
+  onFocus: onFocusProp,
+  onBlur: onBlurProp,
+  role: _role,
+  'aria-label': _ariaLabel,
+  'aria-orientation': _ariaOrientation,
   ...props
 }: ToolbarProps) {
   const hasCenterContent = centerContent != null;
@@ -242,6 +249,48 @@ export function Toolbar({
     hasCaretGuard: true,
   });
 
+  const {
+    hintElement,
+    onKeyDown: onHintKeyDown,
+    onFocus: onHintFocus,
+    onBlur: onHintBlur,
+  } = useKeyboardHint({orientation});
+
+  const handleToolbarKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      onKeyDownProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintKeyDown(e);
+      handleKeyDown(e);
+    },
+    [onKeyDownProp, onHintKeyDown, handleKeyDown],
+  );
+
+  const handleToolbarFocus = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      onFocusProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintFocus(e);
+      handleFocus(e);
+    },
+    [onFocusProp, onHintFocus, handleFocus],
+  );
+
+  const handleToolbarBlur = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      onBlurProp?.(e);
+      if (e.defaultPrevented) {
+        return;
+      }
+      onHintBlur(e);
+    },
+    [onBlurProp, onHintBlur],
+  );
+
   return (
     <SizeProvider value={size}>
       <Section
@@ -257,8 +306,9 @@ export function Toolbar({
           role="toolbar"
           aria-label={label}
           aria-orientation={orientation}
-          onKeyDown={handleKeyDown}
-          onFocus={handleFocus}
+          onKeyDown={handleToolbarKeyDown}
+          onFocus={handleToolbarFocus}
+          onBlur={handleToolbarBlur}
           {...mergeProps(
             themeProps('toolbar', {size}),
             stylex.props(
@@ -323,6 +373,7 @@ export function Toolbar({
               )}
             </>
           )}
+          {hintElement}
         </div>
       </Section>
     </SizeProvider>