@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/hooks/useHotkeys.doc.mjs

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useHotkeys',
+  displayName: 'useHotkeys',
+  keywords: ['hotkey', 'shortcut', 'keyboard', 'keydown', 'command', 'palette', 'mod', 'cmd', 'ctrl', 'kbd'],
+  params: [
+    {
+      name: 'hotkeys',
+      type: 'Hotkey[]',
+      description:
+        'Shortcut registrations. Each entry: `{ keys, onPress, allowInInputs?, isDisabled? }`. `keys` is a "+"-separated combo like "mod+k", "shift+/", "escape" — "mod" is ⌘ on macOS and Ctrl elsewhere. `onPress` receives the KeyboardEvent after preventDefault(). `allowInInputs` (default false) lets the hotkey fire while typing in inputs/textareas/selects/contenteditable. `isDisabled` temporarily disables the entry.',
+      required: true,
+    },
+  ],
+  returns: [],
+  usage: {
+    description:
+      'Registers global keyboard shortcuts with a single window keydown listener per hook instance. Handlers live in a ref, so re-renders never re-subscribe. Skips events from typing targets (input, textarea, select, contenteditable) unless allowInInputs, skips defaultPrevented events, and calls preventDefault() on match. SSR-safe.',
+    bestPractices: [
+      { guidance: true, description: 'Use for app-level shortcuts like command palettes (mod+k), help overlays (shift+/), and navigation keys.' },
+      { guidance: true, description: 'Pair with the Kbd component to display the same combo you register — both resolve "mod" per platform identically.' },
+      { guidance: true, description: 'Use isDisabled to suspend shortcuts while a modal or wizard owns the keyboard, instead of unmounting the hook.' },
+      { guidance: false, description: 'Use for focus-scoped keyboard navigation inside a widget; use useListFocus or useGridFocus instead.' },
+    ],
+  },
+  relatedComponents: ['Kbd'],
+  relatedHooks: ['useListFocus', 'useGridFocus'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('../docs-types').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.',
+  paramDescriptions: {
+    hotkeys:
+      'array of { keys, onPress, allowInInputs?, isDisabled? }. keys = "+"-separated combo ("mod+k", "shift+/", "escape").',
+  },
+  usage: {
+    description:
+      'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets unless allowInInputs, skips defaultPrevented, preventDefault() on match. SSR-safe.',
+    bestPractices: [
+      { guidance: true, description: 'Use for app-level shortcuts: command palettes (mod+k), help overlays (shift+/), navigation keys.' },
+      { guidance: true, description: 'Pair w/ Kbd component to display same combo registered — both resolve "mod" per platform identically.' },
+      { guidance: true, description: 'Use isDisabled to suspend shortcuts while modal/wizard owns keyboard, instead of unmounting hook.' },
+      { guidance: false, description: 'Use for focus-scoped keyboard nav inside widget; use useListFocus / useGridFocus instead.' },
+    ],
+  },
+};

package/src/hooks/useHotkeys.test.ts

@@ -0,0 +1,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useHotkeys.test.ts
+ * @input Uses vitest, @testing-library/react, useHotkeys hook
+ * @output Unit tests for useHotkeys hook
+ * @position Testing; validates useHotkeys.ts implementation
+ *
+ * SYNC: When useHotkeys.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {renderHook} from '@testing-library/react';
+import {useHotkeys, type Hotkey} from './useHotkeys';
+
+function stubApplePlatform() {
+  // jsdom's navigator has no userAgentData; platform drives detection.
+  vi.stubGlobal('navigator', {platform: 'MacIntel'});
+}
+
+function stubOtherPlatform() {
+  vi.stubGlobal('navigator', {platform: 'Win32'});
+}
+
+function press(
+  key: string,
+  init: KeyboardEventInit & {target?: HTMLElement} = {},
+): KeyboardEvent {
+  const {target, ...eventInit} = init;
+  const event = new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    ...eventInit,
+  });
+  (target ?? window).dispatchEvent(event);
+  return event;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  document.body.innerHTML = '';
+});
+
+describe('useHotkeys', () => {
+  it('fires on mod+k via metaKey on Apple platforms', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const event = press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(onPress).toHaveBeenCalledWith(event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('maps mod to ctrlKey on non-Apple platforms', () => {
+    stubOtherPlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    press('k', {ctrlKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire a bare key when modifiers are held', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'k', onPress}]));
+
+    press('k', {metaKey: true});
+    press('k', {ctrlKey: true});
+    press('k', {altKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    press('k');
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('matches named keys: escape, enter, space, arrows', () => {
+    stubApplePlatform();
+    const onEscape = vi.fn();
+    const onEnter = vi.fn();
+    const onSpace = vi.fn();
+    const onDown = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'escape', onPress: onEscape},
+        {keys: 'enter', onPress: onEnter},
+        {keys: 'space', onPress: onSpace},
+        {keys: 'down', onPress: onDown},
+      ]),
+    );
+
+    press('Escape');
+    press('Enter');
+    press(' ');
+    press('ArrowDown');
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onEnter).toHaveBeenCalledTimes(1);
+    expect(onSpace).toHaveBeenCalledTimes(1);
+    expect(onDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('requires shift when specified and ignores shift otherwise', () => {
+    stubApplePlatform();
+    const onSlash = vi.fn();
+    const onLetter = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'shift+/', onPress: onSlash},
+        {keys: 'c', onPress: onLetter},
+      ]),
+    );
+
+    press('/');
+    expect(onSlash).not.toHaveBeenCalled();
+    press('/', {shiftKey: true});
+    expect(onSlash).toHaveBeenCalledTimes(1);
+
+    // Shift not specified → matches regardless of shift state.
+    press('C', {shiftKey: true});
+    press('c');
+    expect(onLetter).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips typing targets by default', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    press('k', {metaKey: true, target: input});
+    expect(onPress).not.toHaveBeenCalled();
+
+    const textarea = document.createElement('textarea');
+    document.body.appendChild(textarea);
+    press('k', {metaKey: true, target: textarea});
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('fires in typing targets when allowInInputs is true', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() =>
+      useHotkeys([{keys: 'escape', onPress, allowInInputs: true}]),
+    );
+
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    press('Escape', {target: input});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects isDisabled', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    const {rerender} = renderHook(
+      ({isDisabled}: {isDisabled: boolean}) =>
+        useHotkeys([{keys: 'mod+k', onPress, isDisabled}]),
+      {initialProps: {isDisabled: true}},
+    );
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    rerender({isDisabled: false});
+    press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips events that are already defaultPrevented', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const event = new KeyboardEvent('keydown', {
+      key: 'k',
+      metaKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    event.preventDefault();
+    window.dispatchEvent(event);
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribes on unmount', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+    const {unmount} = renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    unmount();
+    expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function));
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('does not re-subscribe on re-render, but uses latest handlers', () => {
+    stubApplePlatform();
+    const addSpy = vi.spyOn(window, 'addEventListener');
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const {rerender} = renderHook(
+      ({hotkeys}: {hotkeys: Hotkey[]}) => useHotkeys(hotkeys),
+      {initialProps: {hotkeys: [{keys: 'mod+k', onPress: first}]}},
+    );
+
+    const keydownSubscriptions = () =>
+      addSpy.mock.calls.filter(([type]) => type === 'keydown').length;
+    const initialCount = keydownSubscriptions();
+
+    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
+    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
+    expect(keydownSubscriptions()).toBe(initialCount);
+
+    press('k', {metaKey: true});
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('only fires the first matching hotkey per event', () => {
+    stubApplePlatform();
+    const first = vi.fn();
+    const second = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'mod+k', onPress: first},
+        {keys: 'mod+k', onPress: second},
+      ]),
+    );
+
+    press('k', {metaKey: true});
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useHotkeys.ts

@@ -0,0 +1,203 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useHotkeys.ts
+ * @input Uses React useEffect, useRef
+ * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts
+ * @position Core hook; used by consumers for app-level keyboard shortcuts
+ *
+ * Registers a single window keydown listener per hook instance. Handlers
+ * are kept in a ref so re-renders never re-subscribe (subscribe once on
+ * mount, unsubscribe on unmount). SSR-safe — window is only touched
+ * inside the effect.
+ *
+ * Skips events that are already handled (defaultPrevented) and events
+ * targeting typing surfaces (input, textarea, select, contenteditable)
+ * unless a hotkey opts in via `allowInInputs`.
+ *
+ * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
+ * ctrlKey elsewhere — mirrors the detection used by Kbd.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useHotkeys.doc.mjs
+ */
+
+import {useEffect, useRef} from 'react';
+
+/**
+ * A single keyboard shortcut registration.
+ */
+export interface Hotkey {
+  /**
+   * Key combo, e.g. 'mod+k', 'shift+/', 'c', 'escape'.
+   * 'mod' = ⌘ on macOS, Ctrl elsewhere.
+   *
+   * Format: '+'-separated modifiers (mod, ctrl, meta, shift, alt) followed
+   * by a final key compared case-insensitively against event.key.
+   * Named keys: 'escape', 'enter', 'space', 'up', 'down', 'left', 'right'
+   * (arrow names map to ArrowUp/ArrowDown/ArrowLeft/ArrowRight).
+   * Use 'plus' for a literal '+' key.
+   *
+   * Shift semantics: when 'shift' is not specified, shift state is ignored,
+   * so single letters match regardless of shift. When 'shift' is specified,
+   * shiftKey must be pressed and the final key is still compared against
+   * event.key — for punctuation that shift transforms (e.g. shift+/ produces
+   * '?' on US layouts), prefer registering the produced character instead.
+   */
+  keys: string;
+  /** Called when the combo matches. The event has preventDefault() applied. */
+  onPress: (event: KeyboardEvent) => void;
+  /**
+   * Fire even when focus is in an input/textarea/select/contenteditable.
+   * @default false
+   */
+  allowInInputs?: boolean;
+  /** Temporarily disable this hotkey without unregistering it. */
+  isDisabled?: boolean;
+}
+
+/** Aliases for the final key of a combo, normalized to event.key values. */
+const KEY_ALIASES: Record<string, string> = {
+  esc: 'escape',
+  space: ' ',
+  up: 'arrowup',
+  down: 'arrowdown',
+  left: 'arrowleft',
+  right: 'arrowright',
+  return: 'enter',
+  plus: '+',
+};
+
+/**
+ * Detects whether the current platform is macOS/iOS.
+ * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
+ * falls back to navigator.platform (deprecated but universally supported).
+ * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
+ */
+function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
+  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
+    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+  }
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
+}
+
+/**
+ * Whether the event target is a typing surface where global shortcuts
+ * should stay silent by default.
+ */
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  if (target.isContentEditable) {
+    return true;
+  }
+  const tag = target.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+}
+
+/**
+ * Whether a keydown event matches a '+'-separated combo string.
+ */
+function matchesCombo(
+  keys: string,
+  event: KeyboardEvent,
+  isApple: boolean,
+): boolean {
+  const parts = keys
+    .toLowerCase()
+    .split('+')
+    .map(part => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    return false;
+  }
+
+  const key = parts[parts.length - 1];
+  const mods = new Set(parts.slice(0, -1));
+
+  const wantsMod = mods.has('mod');
+  const wantsCtrl = mods.has('ctrl') || (wantsMod && !isApple);
+  const wantsMeta = mods.has('meta') || (wantsMod && isApple);
+  const wantsAlt = mods.has('alt');
+  const wantsShift = mods.has('shift');
+
+  // Non-shift modifiers must match exactly so 'k' doesn't fire on 'mod+k'.
+  if (event.ctrlKey !== wantsCtrl) {
+    return false;
+  }
+  if (event.metaKey !== wantsMeta) {
+    return false;
+  }
+  if (event.altKey !== wantsAlt) {
+    return false;
+  }
+  // Shift is only enforced when specified — see Hotkey.keys docs.
+  if (wantsShift && !event.shiftKey) {
+    return false;
+  }
+
+  const expected = KEY_ALIASES[key] ?? key;
+  return event.key.toLowerCase() === expected;
+}
+
+/**
+ * Registers global keyboard shortcuts on window.
+ *
+ * A single keydown listener is attached per hook instance; the hotkey
+ * definitions live in a ref, so re-renders update behavior without
+ * re-subscribing. First matching hotkey wins per event.
+ *
+ * @param hotkeys - Shortcut registrations to listen for.
+ *
+ * @example
+ * ```
+ * useHotkeys([
+ *   { keys: 'mod+k', onPress: () => openCommandPalette() },
+ *   { keys: 'escape', onPress: () => closePanel(), allowInInputs: true },
+ *   { keys: 'c', onPress: () => compose(), isDisabled: isModalOpen },
+ * ]);
+ * ```
+ */
+export function useHotkeys(hotkeys: Hotkey[]): void {
+  const hotkeysRef = useRef(hotkeys);
+
+  // Keep the latest definitions available to the stable listener.
+  useEffect(() => {
+    hotkeysRef.current = hotkeys;
+  });
+
+  useEffect(() => {
+    const isApple = isApplePlatform();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) {
+        return;
+      }
+      const isTyping = isTypingTarget(event.target);
+      for (const hotkey of hotkeysRef.current) {
+        if (hotkey.isDisabled) {
+          continue;
+        }
+        if (isTyping && !hotkey.allowInInputs) {
+          continue;
+        }
+        if (matchesCombo(hotkey.keys, event, isApple)) {
+          event.preventDefault();
+          hotkey.onPress(event);
+          return;
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, []);
+}

package/src/hooks/useInteractiveRole.ts

@@ -11,11 +11,14 @@
  * Centralizes the "what element should I render as?" decision for
  * polymorphic components. The priority order:
  *
- *   1. href → 'link' (navigation always wins)
+ *   1. href → 'link' (navigation always wins, unless disabled)
  *   2. onClick → 'button' (explicit interactivity)
  *   3. interactive trigger context → 'button' (implicit via parent)
  *   4. else → 'inert' (non-interactive)
  *
+ * A disabled `href` is excluded at step 1 and therefore resolves via the
+ * remaining steps — 'inert' when no onClick or context applies.
+ *
  * This hook is the single place to add new context-based triggers
  * (e.g., Popover, DropdownMenu, Disclosure). Components that consume
  * this hook never need updating when new trigger contexts are added.
@@ -49,8 +52,12 @@ export interface UseInteractiveRoleOptions {
   onClick?: ((...args: never[]) => unknown) | null;
 
   /**
-   * Whether the component is disabled. When true and href is provided,
-   * falls back to button (disabled links are an a11y anti-pattern).
+   * Whether the component is disabled. When true, an `href` is ignored for
+   * role resolution (a disabled link is an a11y anti-pattern), so the role is
+   * decided by the remaining inputs: `onClick` → `'button'`, an interactive
+   * context → its role, otherwise `'inert'`. In particular a disabled `href`
+   * with no `onClick` and no context override resolves to `'inert'`, not a
+   * link or a button.
    * @default false
    */
   isDisabled?: boolean;
@@ -83,7 +90,8 @@ export function useInteractiveRole({
 }: UseInteractiveRoleOptions): InteractiveRole {
   const contextRole = useInteractiveRoleContext();
 
-  // 1. href → link (unless disabled — disabled links fall through to button)
+  // 1. href → link (unless disabled — a disabled href is skipped here and
+  // resolved by the checks below, landing on 'inert' if nothing else applies)
   if (href != null && !isDisabled) {
     return 'link';
   }

package/src/hooks/useKeyboardHint.doc.mjs

@@ -38,7 +38,7 @@ export const docs = {
     {
       name: 'hintElement',
       type: 'ReactNode',
-      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility — render it unconditionally.',
+      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility; render it unconditionally.',
     },
     {
       name: 'onFocus',
@@ -58,12 +58,12 @@ export const docs = {
   ],
   usage: {
     description:
-      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically — reach for the hook directly only when building a custom roving-tabindex widget.',
+      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically; reach for the hook directly only when building a custom roving-tabindex widget.',
     bestPractices: [
-      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them — call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
+      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them: call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
       { guidance: true, description: 'Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree.' },
       { guidance: true, description: 'Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons.' },
-      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation — the hint only makes sense where arrows move focus within a group.' },
+      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation; the hint only makes sense where arrows move focus within a group.' },
     ],
   },
   relatedComponents: ['Toolbar', 'TabList', 'SegmentedControl'],
@@ -83,7 +83,7 @@ export const docsDense = {
     'options.isEnabled': 'whether the hint is enabled; false suppresses it (e.g. disabled/read-only widget).',
   },
   returnDescriptions: {
-    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing — render unconditionally.',
+    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing; render unconditionally.',
     onFocus: 'container onFocus: shows hint on first :focus-visible entry from outside.',
     onBlur: 'container onBlur: hides on leaving the composite; re-anchors on internal moves.',
     onKeyDown: 'container onKeyDown: dismisses on first arrow press. Never prevents default.',
@@ -92,7 +92,7 @@ export const docsDense = {
     description:
       'Ephemeral "← → to navigate" hint on first keyboard focus of a roving-tabindex composite. Top-layer anchored popover, aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; no re-show. Toolbar/TabList/SegmentedControl wire it in automatically.',
     bestPractices: [
-      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first — it only dismisses).' },
+      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first; it only dismisses).' },
       { guidance: true, description: 'Render hintElement as last child; top-layer + aria-hidden, no layout/a11y impact.' },
       { guidance: true, description: 'Match orientation to the arrows the widget responds to.' },
       { guidance: false, description: 'Use for single controls / non-roving widgets.' },