@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/hooks/useFocusTrap.test.tsx

@@ -50,6 +50,39 @@ function EscapeTrap({
   );
 }
 
+function NestedInnerTrap({onEscape}: {onEscape: () => void}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive: true,
+    onEscape,
+  });
+  return (
+    <div ref={containerRef} data-testid="nested-inner">
+      <button type="button">inner-btn</button>
+    </div>
+  );
+}
+
+function NestedTraps({
+  onOuterEscape,
+  onInnerEscape,
+  showInner = true,
+}: {
+  onOuterEscape: () => void;
+  onInnerEscape: () => void;
+  showInner?: boolean;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive: true,
+    onEscape: onOuterEscape,
+  });
+  return (
+    <div ref={containerRef} data-testid="nested-outer">
+      <button type="button">outer-btn</button>
+      {showInner && <NestedInnerTrap onEscape={onInnerEscape} />}
+    </div>
+  );
+}
+
 function RestoreTrap({isActive}: {isActive: boolean}) {
   const {containerRef} = useFocusTrap<HTMLDivElement>({isActive});
   return (
@@ -118,6 +151,47 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     // Focus skips the inert button and lands on the real one.
     expect(screen.getByTestId('real-btn')).toHaveFocus();
   });
+
+  it('ignores an aria-hidden subtree when finding focusables', () => {
+    render(
+      <Trap>
+        <div aria-hidden="true">
+          <button type="button" data-testid="aria-hidden-btn">
+            Hidden from AT
+          </button>
+        </div>
+        <button type="button" data-testid="real-btn">
+          Real
+        </button>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    // An element AT cannot perceive must not be a trap tab stop (WCAG 4.1.2).
+    expect(screen.getByTestId('real-btn')).toHaveFocus();
+  });
+
+  it('excludes an aria-hidden focusable from the Tab wrap boundary', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="visible-last">
+          Visible last
+        </button>
+        <div aria-hidden="true">
+          <button type="button" data-testid="aria-hidden-btn">
+            Hidden from AT
+          </button>
+        </div>
+      </Trap>,
+    );
+    // The last VISIBLE-to-AT element is the wrap boundary: Tab from it wraps
+    // to the first element instead of landing on the aria-hidden button.
+    screen.getByTestId('visible-last').focus();
+    fireEvent.keyDown(document, {key: 'Tab'});
+    expect(screen.getByTestId('first')).toHaveFocus();
+  });
 });
 
 describe('FOCUSABLE_SELECTOR href matching', () => {
@@ -198,6 +272,36 @@ describe('useFocusTrap Escape coordination', () => {
     expect(onEscape).toHaveBeenCalledTimes(1);
   });
 
+  it('resolves Escape to the DOM-nested inner trap when both mount in one commit', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    // Outer and inner mount in the SAME React commit. React runs child
+    // effects before parent effects, so the inner trap is PUSHED first —
+    // DOM containment, not push order, must decide who answers Escape.
+    render(<NestedTraps onOuterEscape={outer} onInnerEscape={inner} />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the outer trap once the nested inner trap unmounts', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    const {rerender} = render(
+      <NestedTraps onOuterEscape={outer} onInnerEscape={inner} />,
+    );
+    rerender(
+      <NestedTraps
+        onOuterEscape={outer}
+        onInnerEscape={inner}
+        showInner={false}
+      />,
+    );
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(outer).toHaveBeenCalledTimes(1);
+    expect(inner).not.toHaveBeenCalled();
+  });
+
   it('does not respond after the trap is deactivated', () => {
     const onEscape = vi.fn();
     const {rerender} = render(

package/src/hooks/useFocusTrap.ts

@@ -26,24 +26,62 @@ import {FOCUSABLE_SELECTOR} from './focusableSelector';
  * Every active `useFocusTrap` used to attach its own document-level `keydown`
  * listener with no coordination, so a single Escape press closed *every* open
  * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
- * traps in a shared stack lets only the most recently activated (top-most)
- * trap respond to Escape.
+ * traps in a shared stack lets only the top-most trap respond to Escape.
+ *
+ * "Top-most" is resolved by DOM containment first, push order second. Push
+ * order alone is not reliable: React runs child effects before parent
+ * effects, so when an outer and an inner (DOM-nested) trap mount in the SAME
+ * commit, the inner trap pushes first and the outer trap would wrongly win a
+ * pure last-pushed comparison.
  */
-const escapeStack: (() => void)[] = [];
+interface EscapeStackEntry {
+  handler: () => void;
+  getContainer: () => HTMLElement | null;
+}
 
-function pushEscapeHandler(handler: () => void): void {
-  escapeStack.push(handler);
+const escapeStack: EscapeStackEntry[] = [];
+
+function pushEscapeHandler(entry: EscapeStackEntry): void {
+  escapeStack.push(entry);
 }
 
 function removeEscapeHandler(handler: () => void): void {
-  const index = escapeStack.lastIndexOf(handler);
-  if (index !== -1) {
-    escapeStack.splice(index, 1);
+  for (let i = escapeStack.length - 1; i >= 0; i--) {
+    if (escapeStack[i].handler === handler) {
+      escapeStack.splice(i, 1);
+      return;
+    }
   }
 }
 
+/**
+ * Resolve the top-most trap: walk the stack in push order, keeping the
+ * deepest container by DOM containment. When a later entry's container
+ * contains the current candidate's container, the candidate is nested inside
+ * it and stays on top; otherwise the later push wins (containment for nested
+ * traps, push order as the tiebreaker for unrelated ones).
+ */
 function isTopEscapeHandler(handler: () => void): boolean {
-  return escapeStack[escapeStack.length - 1] === handler;
+  if (escapeStack.length === 0) {
+    return false;
+  }
+  let top = escapeStack[0];
+  for (let i = 1; i < escapeStack.length; i++) {
+    const entry = escapeStack[i];
+    const topContainer = top.getContainer();
+    const entryContainer = entry.getContainer();
+    if (
+      topContainer != null &&
+      entryContainer != null &&
+      entryContainer !== topContainer &&
+      entryContainer.contains(topContainer)
+    ) {
+      // The current top is nested inside this entry — it stays on top.
+      continue;
+    }
+    top = entry;
+  }
+  return top.handler === handler;
 }
 
 /**
@@ -73,7 +111,9 @@ export function isImeKeyEvent(event: {
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
- * which the browser skips for Tab.
+ * which the browser skips for Tab, and ones inside an `aria-hidden="true"`
+ * subtree, which sighted-keyboard users could Tab to while AT skips them
+ * (WCAG 4.1.2 — focusable content must be exposed to assistive tech).
  */
 function isVisiblyFocusable(el: HTMLElement): boolean {
   if (el.hasAttribute('inert') || el.closest('[inert]')) {
@@ -82,6 +122,10 @@ function isVisiblyFocusable(el: HTMLElement): boolean {
   if (el.hidden || el.closest('[hidden]')) {
     return false;
   }
+  // closest() matches the element itself as well as any ancestor.
+  if (el.closest('[aria-hidden="true"]')) {
+    return false;
+  }
   // offsetParent is null for display:none (and fixed elements); pair with a
   // visibility check via getComputedStyle when available.
   if (typeof window !== 'undefined' && window.getComputedStyle) {
@@ -323,12 +367,17 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
     // Register this trap on the shared Escape stack so only the top-most
     // active trap responds to Escape. A stable identity per active period is
-    // enough — we push on activate and remove on cleanup.
+    // enough — we push on activate and remove on cleanup. The container is
+    // read lazily: the ref may not be attached yet at effect time, and the
+    // stack resolves top-most by DOM containment at keydown time.
     const escapeHandler = () => {
       onEscape?.();
     };
     if (onEscape) {
-      pushEscapeHandler(escapeHandler);
+      pushEscapeHandler({
+        handler: escapeHandler,
+        getContainer: () => containerRef.current,
+      });
     }
 
     const handleKeyDown = (event: KeyboardEvent) => {

package/src/hooks/useGridFocus.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useGridFocus',
   displayName: 'useGridFocus',
@@ -64,8 +64,8 @@ export const docs = {
     {
       name: 'options.isRtl',
       type: 'boolean',
-      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts.',
-      default: 'false',
+      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts. When omitted, auto-detected from the container computed direction on keydown.',
+      default: "undefined (auto-detect from the container's computed direction)",
       required: false,
     },
     {
@@ -124,7 +124,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',
@@ -138,7 +138,7 @@ export const docsDense = {
     'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',
     'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',
     'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',
-    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default false.',
+    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default: auto-detect from container computed direction; explicit boolean wins.',
     'options.hasRovingTabIndex': 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
   },
   returnDescriptions: {

package/src/hooks/useGridFocus.test.tsx

@@ -23,10 +23,12 @@ const NO_DISABLED: number[] = [];
 function Grid({
   disabled = NO_DISABLED,
   seed = 0,
+  dir,
   ...opts
 }: {
   disabled?: number[];
   seed?: number;
+  dir?: 'ltr' | 'rtl';
 } & Partial<Parameters<typeof useGridFocus>[0]>) {
   const {gridRef, handleKeyDown, handleFocus} = useGridFocus<HTMLDivElement>({
     columns: 3,
@@ -41,6 +43,7 @@ function Grid({
     <div
       ref={gridRef}
       role="grid"
+      dir={dir}
       onKeyDown={handleKeyDown}
       onFocus={handleFocus}>
       {Array.from({length: 9}, (_, i) => (
@@ -130,3 +133,41 @@ describe('useGridFocus roving tabindex (hasRovingTabIndex)', () => {
     expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
   });
 });
+
+describe('useGridFocus RTL auto-detection (WCAG 1.3.2)', () => {
+  // jsdom reflects the `dir` attribute into computed style only on the element
+  // that carries it, so tests set dir="rtl" on the grid container itself — the
+  // element the hook reads via gridRef.
+
+  it('auto-detects dir="rtl": ArrowLeft moves forward (next cell)', () => {
+    render(<Grid seed={1} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves backward (previous cell)', () => {
+    render(<Grid seed={1} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-0')).toHaveFocus();
+  });
+
+  it('leaves vertical navigation unaffected under dir="rtl"', () => {
+    render(<Grid seed={0} dir="rtl" />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowDown'});
+    expect(screen.getByTestId('cell-3')).toHaveFocus();
+  });
+
+  it('explicit isRtl={false} overrides a dir="rtl" container', () => {
+    render(<Grid seed={1} dir="rtl" isRtl={false} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+});

package/src/hooks/useGridFocus.ts

@@ -4,9 +4,12 @@
 
 /**
  * @file useGridFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect,
+ *   isRtlElement
  * @output Exports useGridFocus hook for grid keyboard navigation
- * @position Core hook; used by Calendar for date grid navigation
+ * @position Core hook; used by Calendar for date grid navigation. Auto-detects
+ *   RTL from the container's computed direction so horizontal arrow keys
+ *   follow visual direction (WCAG 1.3.2).
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -14,6 +17,7 @@
  */
 
 import {useCallback, useRef} from 'react';
+import {isRtlElement} from './isRtlElement';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 
 /**
@@ -88,7 +92,12 @@ export interface UseGridFocusOptions {
   /**
    * Whether the grid is in a right-to-left context. When true, ArrowLeft and
    * ArrowRight are swapped so horizontal navigation follows visual direction.
-   * @default false
+   *
+   * When omitted, the direction is auto-detected from the container's computed
+   * `direction` (read lazily on keydown, only for horizontal arrow keys), so
+   * grids inside `dir="rtl"` subtrees flip automatically. Pass an explicit
+   * boolean to override detection.
+   * @default undefined (auto-detect from the container)
    */
   isRtl?: boolean;
 
@@ -217,7 +226,7 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
     onNavigateAfter,
     onPageUp,
     onPageDown,
-    isRtl = false,
+    isRtl,
     hasRovingTabIndex = false,
   } = options;
 
@@ -455,13 +464,15 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
 
       // In RTL, ArrowLeft/ArrowRight are swapped so horizontal navigation
       // follows visual direction. Vertical keys (Up/Down) are unaffected.
+      // Direction is resolved lazily — getComputedStyle runs only when a
+      // horizontal arrow key is actually pressed (SSR-safe, no layout thrash
+      // on unrelated keys) — and an explicit `isRtl` always wins.
       let key = e.key;
-      if (isRtl) {
-        if (key === 'ArrowLeft') {
-          key = 'ArrowRight';
-        } else if (key === 'ArrowRight') {
-          key = 'ArrowLeft';
-        }
+      if (
+        (key === 'ArrowLeft' || key === 'ArrowRight') &&
+        (isRtl ?? isRtlElement(gridRef.current))
+      ) {
+        key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';
       }
 
       switch (key) {

package/src/hooks/useHotkeys.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useHotkeys',
   displayName: 'useHotkeys',
@@ -31,7 +31,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref; re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',

package/src/hooks/useHotkeys.ts

@@ -155,6 +155,15 @@ function matchesCombo(
  * definitions live in a ref, so re-renders update behavior without
  * re-subscribing. First matching hotkey wins per event.
  *
+ * Accessibility (WCAG 2.1.4 — Character Key Shortcuts): a shortcut whose
+ * combo is a single unmodified character (letter, digit, punctuation or
+ * symbol — e.g. 'c' or '/') is easily triggered by accident by speech-input
+ * users and keyboard users with motor impairments. If you register one, you
+ * MUST also provide at least one of: (a) a way to turn the shortcut off,
+ * (b) a way to remap it to include a modifier, or (c) scope it so it is only
+ * active while the relevant component has focus. Prefer `mod`-based combos
+ * where possible; the `isDisabled` flag can back a user-facing off switch.
+ *
  * @param hotkeys - Shortcut registrations to listen for.
  *
  * @example

package/src/hooks/useImageMode.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useImageMode',
   displayName: 'useImageMode',
@@ -61,7 +61,7 @@ export const docs = {
   category: 'media',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',

package/src/hooks/useInputContainer.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useInputContainer',
   displayName: 'useInputContainer',
@@ -59,7 +59,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely; clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',

package/src/hooks/useInputContainer.test.tsx

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useInputContainer.test.tsx
+ * @input Uses React Testing Library, useInputContainer
+ * @output Unit tests for focus-vs-click forwarding on container click
+ */
+
+import {fireEvent, render} from '@testing-library/react';
+import {useRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useInputContainer} from './useInputContainer';
+
+/**
+ * Renders a container wired with useInputContainer around a single control.
+ * The control is described by `control`, which receives the ref to attach.
+ */
+function TestContainer({
+  renderControl,
+}: {
+  renderControl: (ref: React.RefObject<HTMLElement | null>) => React.ReactNode;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLElement | null>(null);
+  const {onClick, onMouseUp} = useInputContainer({
+    containerRef,
+    inputRef,
+  });
+  return (
+    <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+      <span data-testid="chrome">chrome</span>
+      {renderControl(inputRef)}
+    </div>
+  );
+}
+
+describe('useInputContainer', () => {
+  it('clicks (not focuses) a role="combobox" aria-haspopup="dialog" text input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            role="combobox"
+            aria-haspopup="dialog"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    // Click the non-interactive chrome so the container handler fires.
+    fireEvent.click(getByTestId('chrome'));
+
+    // A popup trigger must be activated via click, not merely focused —
+    // otherwise DateInput's calendar would never open.
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+
+  it('clicks a control that only advertises aria-haspopup (no combobox role)', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            aria-haspopup="menu"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a plain type="text" input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="text"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a plain type="number" input', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="number"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('focuses (not clicks) a textarea', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <textarea
+            ref={ref as React.RefObject<HTMLTextAreaElement>}
+            data-testid="control"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onControlClick).not.toHaveBeenCalled();
+  });
+
+  it('clicks (not focuses) a checkbox — unchanged behavior', () => {
+    const onFocus = vi.fn();
+    const onControlClick = vi.fn();
+    const {getByTestId} = render(
+      <TestContainer
+        renderControl={ref => (
+          <input
+            ref={ref as React.RefObject<HTMLInputElement>}
+            data-testid="control"
+            type="checkbox"
+            onFocus={onFocus}
+            onClick={onControlClick}
+          />
+        )}
+      />,
+    );
+
+    fireEvent.click(getByTestId('chrome'));
+
+    expect(onControlClick).toHaveBeenCalledTimes(1);
+    expect(onFocus).not.toHaveBeenCalled();
+  });
+});