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

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;
   /**
@@ -222,7 +234,10 @@ const styles = stylex.create({
   },
   endSection: {
     position: 'absolute',
-    insetInlineEnd: `calc(${spacingVars['--spacing-1']} - 1px)`,
+    // Match the field's inline padding (inputWrapperStyles.base uses
+    // spacing-2) so end content (clear button, resultCount) lines up with
+    // the text/start-icon inset instead of hugging the border at ~3px.
+    insetInlineEnd: spacingVars['--spacing-2'],
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
@@ -362,6 +377,7 @@ export function Tokenizer<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  disabledMessage,
   hasClear = false,
   endContent,
   hasAutoFocus,
@@ -387,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();
@@ -617,6 +646,7 @@ export function Tokenizer<T extends SearchableItem>({
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -656,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}
@@ -707,6 +743,7 @@ export function Tokenizer<T extends SearchableItem>({
         maxMenuItems={maxMenuItems}
         emptySearchResultsText={emptySearchResultsText}
         isDisabled={isDisabled}
+        isFocusableDisabled={showsDisabledMessage}
         hasAutoFocus={hasAutoFocus}
         inputId={inputId}
         ariaDescribedBy={ariaDescribedBy}
@@ -828,6 +865,8 @@ export function Tokenizer<T extends SearchableItem>({
       className={className}
       style={style}>
       {tokenizerContent}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Toolbar/Toolbar.doc.mjs

@@ -7,6 +7,25 @@ export const docs = {
   displayName: 'Toolbar',
   category: 'Action',
   keywords: ['toolbar', 'nav', 'bar', 'actions', 'buttonbar', 'header', 'footer', 'action-bar', 'control-bar'],
+  playground: {
+    defaults: {
+      label: 'Table actions',
+      size: 'sm',
+      dividers: ['bottom'],
+      startContent: {
+        __element: 'TabList',
+        props: {value: 'overview'},
+        children: [
+          {__element: 'Tab', props: {label: 'Overview', value: 'overview'}},
+          {__element: 'Tab', props: {label: 'Activity', value: 'activity'}},
+        ],
+      },
+      endContent: [
+        {__element: 'Selector', props: {label: 'Status', isLabelHidden: true, placeholder: 'Status', size: 'sm', options: ['Open', 'In progress', 'Done']}},
+        {__element: 'Button', props: {label: 'New item', variant: 'primary', size: 'sm'}},
+      ],
+    },
+  },
   theming: {
     targets: [
       {className: 'astryx-toolbar', states: ['size']},
@@ -29,21 +48,62 @@ export const docs = {
           name: 'startContent',
           type: 'ReactNode',
           description: 'Content aligned to the start (left in LTR).',
-          slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+          slotElements: [
+            {__element: 'Text', props: {type: 'body', weight: 'bold'}, children: 'Title'},
+            {__element: 'Button', props: {label: 'Back', variant: 'ghost', size: 'sm'}},
+            {__element: 'IconButton', props: {label: 'Filter', icon: {__element: 'Icon', props: {icon: 'check', size: 'sm'}}, variant: 'ghost', size: 'sm'}},
+            {
+              __element: 'TabList',
+              props: {value: 'overview'},
+              children: [
+                {__element: 'Tab', props: {label: 'Overview', value: 'overview'}},
+                {__element: 'Tab', props: {label: 'Activity', value: 'activity'}},
+              ],
+            },
+            {
+              __element: 'SegmentedControl',
+              props: {label: 'View', value: 'list'},
+              children: [
+                {__element: 'SegmentedControlItem', props: {label: 'List', value: 'list'}},
+                {__element: 'SegmentedControlItem', props: {label: 'Grid', value: 'grid'}},
+              ],
+            },
+            {__element: 'Selector', props: {label: 'Status', isLabelHidden: true, placeholder: 'Status', size: 'sm', options: ['Open', 'In progress', 'Done']}},
+          ],
         },
         {
           name: 'centerContent',
           type: 'ReactNode',
           description:
             'Centered content. Switches layout to CSS grid (1fr auto 1fr).',
-          slotElements: [{__element: 'Text', props: {type: 'body', weight: 'bold'}, children: 'Center'}],
+          slotElements: [
+            {__element: 'Text', props: {type: 'body', weight: 'bold'}, children: 'Center'},
+            {
+              __element: 'SegmentedControl',
+              props: {label: 'View', value: 'list'},
+              children: [
+                {__element: 'SegmentedControlItem', props: {label: 'List', value: 'list'}},
+                {__element: 'SegmentedControlItem', props: {label: 'Grid', value: 'grid'}},
+              ],
+            },
+            {
+              __element: 'TabList',
+              props: {value: 'overview'},
+              children: [
+                {__element: 'Tab', props: {label: 'Overview', value: 'overview'}},
+                {__element: 'Tab', props: {label: 'Activity', value: 'activity'}},
+              ],
+            },
+          ],
         },
         {
           name: 'endContent',
           type: 'ReactNode',
           description: 'Content aligned to the end (right in LTR).',
           slotElements: [
-            {__element: 'Icon', props: {icon: 'chevronDown', size: 'sm'}},
+            {__element: 'Button', props: {label: 'Save', variant: 'primary', size: 'sm'}},
+            {__element: 'IconButton', props: {label: 'More', icon: {__element: 'Icon', props: {icon: 'chevronDown', size: 'sm'}}, variant: 'ghost', size: 'sm'}},
+            {__element: 'Selector', props: {label: 'Sort', isLabelHidden: true, placeholder: 'Sort by', size: 'sm', options: ['Newest', 'Oldest', 'A–Z']}},
             {__element: 'Badge', props: {label: '3'}},
           ],
         },
@@ -51,14 +111,14 @@ export const docs = {
           name: 'size',
           type: "'sm' | 'md' | 'lg'",
           description:
-            'Size of the toolbar. Controls minimum height and coordinates with Button, TextInput, TabList, and Selector — children inherit this size as their default via SizeContext.',
+            'Size of the toolbar. Controls minimum height and coordinates with Button, TextInput, TabList, and Selector; children inherit this size as their default via SizeContext.',
           default: "'md'",
         },
         {
           name: 'gap',
           type: 'SpacingStep',
           description: 'Gap between items within each slot.',
-          default: '2',
+          default: '1',
         },
         {
           name: 'orientation',

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

@@ -55,6 +55,19 @@ describe('Tooltip', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
+  it('gives the tooltip layer role="tooltip" linked from the trigger', () => {
+    render(
+      <Tooltip content="Tooltip text">
+        <button type="button">Trigger</button>
+      </Tooltip>,
+    );
+    const layer = screen.getByRole('tooltip', {hidden: true});
+    expect(layer).toHaveTextContent('Tooltip text');
+    // ARIA tooltip pattern: trigger references the layer via aria-describedby.
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger.getAttribute('aria-describedby')).toBe(layer.id);
+  });
+
   it('calls onOpenChange(true) when shown via hover', async () => {
     const onOpenChange = vi.fn();
     render(
@@ -140,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);
+    });
+  });
 });