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

package/src/Tokenizer/Tokenizer.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Tokenizer} from './Tokenizer';
 import type {SearchSource, SearchableItem} from '../Typeahead/types';
@@ -763,4 +763,108 @@ describe('Tokenizer', () => {
       expect(screen.getByText('Create "NewTag"')).toBeInTheDocument();
     });
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+    const isOpen = (el: Element) => el.matches(':popover-open');
+
+    function renderTokenizer(props?: {onChange?: () => void}) {
+      return render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={props?.onChange ?? (() => {})}
+          isDisabled
+          disabledMessage="You need edit access to change members"
+        />,
+      );
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      renderTokenizer();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'You need edit access to change members',
+      );
+      const wrapper = screen.getByRole('group', {name: 'Members'});
+      fireEvent.mouseEnter(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+      fireEvent.mouseLeave(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(false));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      renderTokenizer();
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          disabledMessage="You need edit access to change members"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      renderTokenizer();
+      const input = screen.getByRole('combobox');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      renderTokenizer();
+      const input = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks input while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      renderTokenizer({onChange});
+      const input = screen.getByRole('combobox');
+      input.focus();
+      await user.keyboard('Ali');
+      expect((input as HTMLInputElement).value).toBe('');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('keeps the input natively disabled when disabled without a reason', () => {
+      render(
+        <Tokenizer
+          label="Members"
+          searchSource={userSource}
+          value={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('combobox')).toBeDisabled();
+    });
+  });
 });

package/src/Tokenizer/Tokenizer.tsx

@@ -42,6 +42,7 @@ import {Token} from '../Token';
 import {renderIconSlot, type IconType} from '../Icon';
 import {OverflowList} from '../OverflowList';
 import {useLayer} from '../Layer/useLayer';
+import {useTooltip} from '../Tooltip';
 import {
   colorVars,
   spacingVars,
@@ -145,6 +146,17 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   emptySearchResultsText?: string;
   /** Whether the input is disabled. @default false */
   isDisabled?: boolean;
+  /**
+   * Explains why the tokenizer is disabled. When set together with
+   * `isDisabled`, the tokenizer shows a tooltip with this text on hover and
+   * keyboard focus, and the input stays focusable (via `aria-disabled`) so the
+   * reason is discoverable by keyboard and assistive technology. Input stays
+   * blocked.
+   *
+   * Use this instead of wrapping a disabled tokenizer in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /** Show clear button (clears all tokens). @default false */
   hasClear?: boolean;
   /**
@@ -365,6 +377,7 @@ export function Tokenizer<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  disabledMessage,
   hasClear = false,
   endContent,
   hasAutoFocus,
@@ -390,6 +403,19 @@ export function Tokenizer<T extends SearchableItem>({
   const inputRef = useRef<HTMLInputElement>(null);
   const wrapperRef = useRef<HTMLDivElement>(null);
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input wrapper and the typeahead input stays
+  // perceivable via aria-disabled instead of the disabled attribute. Input is
+  // blocked by the isDisabled guards in BaseTypeahead and handleWrapperClick.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The wrapper is not naturally focusable; focusin bubbles up from the
+    // input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   useImperativeHandle(handleRef, () => ({
     focus() {
       inputRef.current?.focus();
@@ -620,6 +646,7 @@ export function Tokenizer<T extends SearchableItem>({
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -659,7 +686,13 @@ export function Tokenizer<T extends SearchableItem>({
 
   const wrapperContent = (
     <div
-      ref={wrapperRef}
+      ref={el => {
+        wrapperRef.current = el;
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, so attaching
+        // unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      }}
       role="group"
       aria-label={label}
       onClick={handleWrapperClick}
@@ -710,6 +743,7 @@ export function Tokenizer<T extends SearchableItem>({
         maxMenuItems={maxMenuItems}
         emptySearchResultsText={emptySearchResultsText}
         isDisabled={isDisabled}
+        isFocusableDisabled={showsDisabledMessage}
         hasAutoFocus={hasAutoFocus}
         inputId={inputId}
         ariaDescribedBy={ariaDescribedBy}
@@ -831,6 +865,8 @@ export function Tokenizer<T extends SearchableItem>({
       className={className}
       style={style}>
       {tokenizerContent}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </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', () => {
@@ -256,4 +266,97 @@ describe('Toolbar', () => {
     render(<Toolbar label="Actions" data-testid="my-toolbar" />);
     expect(screen.getByTestId('my-toolbar')).toBe(screen.getByRole('toolbar'));
   });
+
+  it('is a single tab stop — only one item is tabbable (navigation-3)', () => {
+    render(
+      <Toolbar
+        label="Actions"
+        startContent={
+          <>
+            <button type="button">Cut</button>
+            <button type="button">Copy</button>
+            <button type="button">Paste</button>
+          </>
+        }
+      />,
+    );
+    const buttons = screen.getAllByRole('button');
+    const tabbable = buttons.filter(b => b.getAttribute('tabindex') === '0');
+    expect(tabbable).toHaveLength(1);
+    expect(buttons[0]).toHaveAttribute('tabindex', '0');
+    expect(buttons[1]).toHaveAttribute('tabindex', '-1');
+    expect(buttons[2]).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('does not steal caret keys from a text input mid-line (navigation-4)', async () => {
+    const user = userEvent.setup();
+    render(
+      <Toolbar
+        label="Search"
+        startContent={
+          <>
+            <input type="text" aria-label="Query" defaultValue="hello" />
+            <button type="button">Go</button>
+          </>
+        }
+      />,
+    );
+    const inputEl = screen.getByLabelText('Query');
+    if (!(inputEl instanceof HTMLInputElement)) {
+      throw new Error('expected an input');
+    }
+    inputEl.focus();
+    inputEl.setSelectionRange(1, 1); // caret mid-line
+    await user.keyboard('{ArrowRight}');
+    // 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;
@@ -235,11 +242,55 @@ export function Toolbar({
 
   const gapVar = spacingVars[spacingStepToVar[gap]] as string;
 
-  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
-    itemSelector: 'button, input, [tabindex="0"]',
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: 'button, input, [tabindex]',
     orientation,
+    hasRovingTabIndex: true,
+    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
@@ -255,7 +306,9 @@ export function Toolbar({
           role="toolbar"
           aria-label={label}
           aria-orientation={orientation}
-          onKeyDown={handleKeyDown}
+          onKeyDown={handleToolbarKeyDown}
+          onFocus={handleToolbarFocus}
+          onBlur={handleToolbarBlur}
           {...mergeProps(
             themeProps('toolbar', {size}),
             stylex.props(
@@ -320,6 +373,7 @@ export function Toolbar({
               )}
             </>
           )}
+          {hintElement}
         </div>
       </Section>
     </SizeProvider>

package/src/Tooltip/Tooltip.test.tsx

@@ -153,4 +153,72 @@ describe('Tooltip', () => {
       });
     });
   });
+
+  describe('WCAG 1.4.13 — content on hover or focus', () => {
+    it('dismisses on Escape while visible (dismissible)', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Dismiss me" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('ignores Escape during IME composition', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Stay" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
+      // Give any (incorrect) async hide a chance to run.
+      await new Promise(r => setTimeout(r, 20));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+
+    it('stays open when the pointer moves onto the tooltip surface (hoverable)', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Hover me" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      // Pointer leaves the trigger but enters the tooltip surface before the
+      // hover-bridge grace period elapses — the tooltip must not hide.
+      fireEvent.mouseLeave(trigger);
+      const layer = screen.getByRole('tooltip', {hidden: true});
+      fireEvent.mouseEnter(layer);
+
+      await new Promise(r => setTimeout(r, 150));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+  });
 });

package/src/Tooltip/useTooltip.tsx

@@ -37,6 +37,13 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 
+/**
+ * Grace period (ms) before hiding on pointer-leave when no explicit `hideDelay`
+ * is set, so the pointer can travel across the small gap from the trigger onto
+ * the tooltip surface without the tooltip disappearing (WCAG 1.4.13 hoverable).
+ */
+const HOVER_BRIDGE_DELAY = 100;
+
 const styles = stylex.create({
   // Base container styles - inverted colors for high contrast
   container: {
@@ -291,21 +298,29 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, layer, delay]);
 
-  // Schedule hide with delay (suppressed when isOpen is true)
+  // Schedule hide with delay (suppressed when isOpen is true).
+  // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
+  // trigger onto the tooltip surface without the tooltip vanishing — required
+  // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
   const scheduleHide = useCallback(() => {
     if (isOpen === true) {
       return;
     }
     clearTimeouts();
-    if (hideDelay > 0) {
-      hideTimeoutRef.current = setTimeout(() => {
-        layer.hide();
-      }, hideDelay);
-    } else {
+    const effectiveHideDelay = hideDelay > 0 ? hideDelay : HOVER_BRIDGE_DELAY;
+    hideTimeoutRef.current = setTimeout(() => {
       layer.hide();
-    }
+    }, effectiveHideDelay);
   }, [isOpen, clearTimeouts, layer, hideDelay]);
 
+  // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
+  const cancelHide = useCallback(() => {
+    if (hideTimeoutRef.current) {
+      clearTimeout(hideTimeoutRef.current);
+      hideTimeoutRef.current = null;
+    }
+  }, []);
+
   // Event handlers
   const handleMouseEnter = useCallback(() => {
     // Suppress tooltips on touch devices — hover is simulated and eats a tap
@@ -420,6 +435,32 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }
   }, [isOpen, clearTimeouts, layer]);
 
+  // Dismiss on Escape (WCAG 1.4.13 — dismissible). Uncontrolled tooltips only;
+  // a controlled tooltip's visibility is owned by the consumer. The listener is
+  // mounted for the lifetime of an uncontrolled tooltip rather than gated on
+  // `layer.isOpen` (React state, which can lag a frame behind the DOM) —
+  // `layer.hide()` self-guards and no-ops when the layer is already closed.
+  // Guarded against IME composition-cancel.
+  useEffect(() => {
+    if (isOpen !== undefined) {
+      return;
+    }
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') {
+        return;
+      }
+      if (e.isComposing || e.keyCode === 229) {
+        return;
+      }
+      clearTimeouts();
+      layer.hide();
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen, layer, clearTimeouts]);
+
   // Render function that wraps layer.render with tooltip styling
   const renderTooltip = useCallback(
     (children: ReactNode, props?: ContextRenderProps): ReactNode => {
@@ -430,6 +471,12 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         role: 'tooltip',
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
         className: themeProps('tooltip').className,
+        // Keep the tooltip open while the pointer is over the surface itself
+        // (WCAG 1.4.13 hoverable). These sit on the layer container — the
+        // element the user actually hovers — not the inner content div, since
+        // mouseenter/leave do not bubble.
+        onMouseEnter: cancelHide,
+        onMouseLeave: scheduleHide,
       };
 
       return layer.render(
@@ -437,7 +484,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         renderProps,
       );
     },
-    [layer, placement, alignment, popoverXstyle],
+    [layer, placement, alignment, popoverXstyle, cancelHide, scheduleHide],
   );
 
   return {