@astryxdesign/core 0.3.0 → 0.4.0

package/src/Typeahead/Typeahead.test.tsx

@@ -171,6 +171,28 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  it('exposes the empty state as a themeable target', async () => {
+    const {container} = render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+        emptySearchResultsText="No results found"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+    await waitFor(() => {
+      const emptyState = container.querySelector(
+        '.astryx-typeahead-empty-state',
+      );
+      expect(emptyState).not.toBeNull();
+      expect(emptyState).toHaveTextContent('No results found');
+    });
+  });
+
   describe('empty results active descendant (#4059)', () => {
     it('does not set aria-activedescendant when search has 0 results', async () => {
       render(
@@ -198,6 +220,45 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  describe('IME composition guard (#4828)', () => {
+    it('does not select the highlighted result on a composing Enter', async () => {
+      const onChange = vi.fn();
+      render(
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={onChange}
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'App'}});
+      await waitFor(() => {
+        expect(input).toHaveAttribute('aria-expanded', 'true');
+      });
+
+      // The browser fires this composing keydown for the Enter that commits
+      // an IME candidate (isComposing: true, or legacy keyCode 229) before
+      // compositionend writes the pending syllable into the input. Without
+      // the guard this both selects the highlighted result AND clears the
+      // input via handleSelect, so the syllable that compositionend then
+      // writes lands in an emptied field instead of being part of the word.
+      fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('App');
+
+      fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('App');
+
+      // A real, non-composing Enter still selects normally.
+      fireEvent.keyDown(input, {key: 'Enter'});
+      expect(onChange).toHaveBeenCalledWith(
+        expect.objectContaining({label: 'Apple'}),
+      );
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead
@@ -1038,11 +1099,16 @@ describe('Typeahead disabledMessage', () => {
   });
 });
 
-
 describe('Typeahead statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -1052,7 +1118,14 @@ describe('Typeahead statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',

package/src/hooks/containerReveal.stylex.ts

@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file containerReveal.stylex.ts
+ * @input Uses StyleX, theme tokens
+ * @output The container style that publishes the reveal state, and the four
+ *   content style blocks (reveal / conceal, each with a layout-preserved
+ *   variant) that read it.
+ * @position Internal to useContainerReveal.
+ *
+ * HOW THE SCOPING WORKS: the container declares its own reveal state as
+ * inherited custom properties on itself, and content reads them. Because a
+ * nested container re-declares the same properties on itself, its subtree sees
+ * the inner value and never the ancestor's — nesting isolation falls out of the
+ * cascade, with one static style block for any number of containers.
+ *
+ * SYNC: When the block shape changes, update useContainerReveal.ts.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, easeVars} from '../theme/tokens.stylex';
+
+const REST_DELAY = '0s, ' + durationVars['--duration-fast'];
+
+export const styles = stylex.create({
+  container: {
+    '--_reveal-opacity': {
+      default: 0,
+      ':hover': {'@media (hover: hover)': 1},
+      ':focus-within': 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    '--_reveal-position': {
+      default: 'absolute',
+      ':hover': {'@media (hover: hover)': 'static'},
+      ':focus-within': 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+    // The position flip is discrete, so it transitions with allow-discrete and
+    // a state-conditional delay: 0 on entry (flips into flow immediately, then
+    // fades in) and the fade duration on exit (stays in flow until the fade
+    // finishes, then snaps out) — without this the exit would snap out of flow
+    // at full opacity and flicker.
+    '--_reveal-delay': {
+      default: REST_DELAY,
+      ':hover': {'@media (hover: hover)': '0s, 0s'},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    // Conceal is a mouse-only visual swap, so it reads hover alone: no
+    // :focus-within (a keyboard user must never watch content vanish) and no
+    // coarse-pointer branch (it stays visible on touch).
+    '--_conceal-opacity': {
+      default: 1,
+      ':hover': {'@media (hover: hover)': 0},
+    },
+  },
+  // The fallbacks make content spread outside a reveal container fail visible
+  // rather than invisible.
+  reveal: {
+    transitionProperty: 'opacity, position',
+    transitionDuration: {
+      default: durationVars['--duration-fast'] + ', 0s',
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    transitionBehavior: 'allow-discrete',
+    transitionDelay: {
+      default: 'var(--_reveal-delay, 0s, 0s)',
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+    },
+    opacity: 'var(--_reveal-opacity, 1)',
+    position: 'var(--_reveal-position, static)',
+  },
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: 'var(--_reveal-opacity, 1)',
+  },
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: 'var(--_conceal-opacity, 1)',
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: 'var(--_conceal-opacity, 1)',
+  },
+});

package/src/hooks/index.ts

@@ -17,6 +17,9 @@ export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 export {useAnnounce} from './useAnnounce';
 export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';
 
+export {useClipboard} from './useClipboard';
+export type {UseClipboardOptions, UseClipboardReturn} from './useClipboard';
+
 export {useGridFocus} from './useGridFocus';
 export type {UseGridFocusOptions, UseGridFocusReturn} from './useGridFocus';
 
@@ -92,6 +95,7 @@ export {useLongPress} from './useLongPress';
 export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';
 
 export {useDevWarning} from './useDevWarning';
+export {useIndicatorFocusRing} from './useIndicatorFocusRing';
 
 export {useContainerReveal} from './useContainerReveal';
 export type {

package/src/hooks/useClipboard.doc.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useClipboard',
+  displayName: 'useClipboard',
+  keywords: [
+    'clipboard', 'copy', 'copied', 'paste', 'writeText', 'copy-to-clipboard',
+    'copy button', 'announce', 'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseClipboardOptions',
+      description: 'Configuration object.',
+      required: false,
+    },
+    {
+      name: 'options.announce',
+      type: 'string',
+      description:
+        'Message announced to a polite live region on a successful copy. A swapped aria-label alone is not reliably announced, so pass the localized confirmation (e.g. "Copied") to have it spoken. Omit to skip the announcement.',
+      required: false,
+    },
+    {
+      name: 'options.resetAfterMs',
+      type: 'number',
+      description:
+        'Milliseconds isCopied stays true after a successful copy before reverting.',
+      default: '2000',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'copy',
+      type: '(text: string) => Promise<boolean>',
+      description:
+        'Writes text to the clipboard. On success flips isCopied to true, announces the configured message, restarts the reset timer, and resolves true. A clipboard rejection is a silent no-op that leaves the copied state unchanged and resolves false.',
+    },
+    {
+      name: 'isCopied',
+      type: 'boolean',
+      description:
+        'True for resetAfterMs after the most recent successful copy, then reverts. Drive the copied confirmation (e.g. a copy → check icon flip) off this.',
+    },
+  ],
+  usage: {
+    description:
+      'Copy-to-clipboard behavior: the clipboard write, a transient isCopied flag with its own reset timer, and an optional polite screen-reader announcement. Extracted so every copy affordance is a thin control over one implementation instead of re-deriving the timer and announcement. Rapid re-copies restart the reset timer so the confirmation always lasts the full duration, and the timer is cleaned up on unmount. CodeBlock and Timestamp build their built-in copy buttons on it; reach for it directly when building a copy affordance that is not a plain icon button (a menu item, a labeled text button, a copy-on-click value chip).',
+    bestPractices: [
+      { guidance: true, description: 'Drive the copied confirmation (copy → check icon, label swap) off the returned isCopied flag rather than tracking your own state.' },
+      { guidance: true, description: 'Pass a localized announce message so the copy is spoken by screen readers; swapping the button aria-label alone is not reliably announced.' },
+      { guidance: true, description: 'For the common compact icon copy button, render a ghost IconButton with a "Copy" tooltip and wire onClick to copy(); the tooltip stays "Copy" and the icon flip is the confirmation.' },
+      { guidance: false, description: 'Track a separate copied useState alongside the hook; isCopied already reflects the copied window and resets itself.' },
+    ],
+  },
+  relatedComponents: ['CodeBlock', 'Timestamp', 'IconButton'],
+  relatedHooks: ['useAnnounce'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Copy-to-clipboard behavior: clipboard write + transient isCopied flag with reset timer + optional polite SR announcement. One implementation shared by copy affordances instead of re-deriving timer/announce. Rapid re-copies restart the timer; timer cleaned up on unmount. CodeBlock/Timestamp build their copy buttons on it.',
+  paramDescriptions: {
+    options: 'config object.',
+    'options.announce': 'polite live-region message on successful copy (e.g. "Copied"); aria-label swap alone is not reliably announced. Omit to skip.',
+    'options.resetAfterMs': 'ms isCopied stays true after a copy before reverting.',
+  },
+  returnDescriptions: {
+    copy: '(text) => Promise<boolean>: writes text, flips isCopied, announces, restarts reset timer, resolves true; silent no-op resolving false on rejection.',
+    isCopied: 'true for resetAfterMs after the last successful copy; drive the copy → check confirmation off it.',
+  },
+  usage: {
+    description:
+      'Copy-to-clipboard behavior (write + isCopied flag with reset timer + optional polite SR announce). Thin controls over one implementation. Rapid re-copies restart the timer; cleaned up on unmount. Use directly for copy affordances that are not plain icon buttons (menu item, labeled text button, value chip).',
+    bestPractices: [
+      { guidance: true, description: 'Drive the copy → check confirmation off the returned isCopied, not your own state.' },
+      { guidance: true, description: 'Pass a localized announce so the copy is spoken (aria-label swap alone is not reliably announced).' },
+      { guidance: true, description: 'For a compact icon copy button, use a ghost IconButton with a "Copy" tooltip and wire onClick to copy(); the tooltip stays "Copy" and the icon flip is the confirmation.' },
+      { guidance: false, description: 'Track a separate copied useState alongside the hook.' },
+    ],
+  },
+};

package/src/hooks/useClipboard.test.tsx

@@ -0,0 +1,151 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useClipboard.test.tsx
+ * @input Uses vitest, @testing-library/react, useClipboard hook
+ * @output Unit tests for the useClipboard copy behavior
+ * @position Testing; validates useClipboard.ts
+ *
+ * SYNC: When useClipboard.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {act, renderHook, waitFor} from '@testing-library/react';
+import {useClipboard} from './useClipboard';
+import {__resetLiveRegionsForTest} from './useAnnounce';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+
+describe('useClipboard', () => {
+  beforeEach(() => {
+    // jsdom does not implement the async Clipboard API.
+    Object.assign(navigator, {
+      clipboard: {writeText: vi.fn().mockResolvedValue(undefined)},
+    });
+  });
+
+  afterEach(() => {
+    __resetLiveRegionsForTest();
+    vi.restoreAllMocks();
+  });
+
+  it('writes the given text to the clipboard and resolves true', async () => {
+    const {result} = renderHook(() => useClipboard());
+    let outcome: boolean | undefined;
+    await act(async () => {
+      outcome = await result.current.copy('hello world');
+    });
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith('hello world');
+    expect(outcome).toBe(true);
+  });
+
+  it('flips isCopied to true after a successful copy', async () => {
+    const {result} = renderHook(() => useClipboard());
+    expect(result.current.isCopied).toBe(false);
+    await act(async () => {
+      await result.current.copy('x');
+    });
+    expect(result.current.isCopied).toBe(true);
+  });
+
+  it('reverts isCopied after resetAfterMs', async () => {
+    vi.useFakeTimers();
+    try {
+      const {result} = renderHook(() => useClipboard({resetAfterMs: 1000}));
+      await act(async () => {
+        await result.current.copy('x');
+      });
+      expect(result.current.isCopied).toBe(true);
+      act(() => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(result.current.isCopied).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('keeps isCopied true for the full window after a rapid re-copy', async () => {
+    vi.useFakeTimers();
+    try {
+      const {result} = renderHook(() => useClipboard({resetAfterMs: 2000}));
+      await act(async () => {
+        await result.current.copy('x');
+      });
+      expect(result.current.isCopied).toBe(true);
+
+      // Re-copy partway through the window.
+      act(() => {
+        vi.advanceTimersByTime(1500);
+      });
+      await act(async () => {
+        await result.current.copy('x');
+      });
+
+      // 600ms after the second copy (2.1s after the first): the first copy's
+      // timer must not have reverted it early.
+      act(() => {
+        vi.advanceTimersByTime(600);
+      });
+      expect(result.current.isCopied).toBe(true);
+
+      // It resets 2s after the most recent copy.
+      act(() => {
+        vi.advanceTimersByTime(1400);
+      });
+      expect(result.current.isCopied).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('announces the configured message to a polite live region', async () => {
+    const {result} = renderHook(() => useClipboard({announce: 'Copied'}));
+    await act(async () => {
+      await result.current.copy('x');
+    });
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copied');
+    });
+  });
+
+  it('does not announce when no announce message is configured', async () => {
+    const {result} = renderHook(() => useClipboard());
+    await act(async () => {
+      await result.current.copy('x');
+    });
+    // No announce option → no live region is ever created.
+    expect(politeRegion()).toBeNull();
+  });
+
+  it('is a silent no-op that resolves false when the clipboard rejects', async () => {
+    (
+      navigator.clipboard.writeText as ReturnType<typeof vi.fn>
+    ).mockRejectedValue(new Error('denied'));
+    const {result} = renderHook(() => useClipboard({announce: 'Copied'}));
+    let outcome: boolean | undefined;
+    await act(async () => {
+      outcome = await result.current.copy('x');
+    });
+    expect(outcome).toBe(false);
+    expect(result.current.isCopied).toBe(false);
+    expect(politeRegion()).toBeNull();
+  });
+
+  it('clears a pending reset timer on unmount', async () => {
+    vi.useFakeTimers();
+    const clearSpy = vi.spyOn(globalThis, 'clearTimeout');
+    try {
+      const {result, unmount} = renderHook(() => useClipboard());
+      await act(async () => {
+        await result.current.copy('x');
+      });
+      unmount();
+      expect(clearSpy).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/hooks/useClipboard.ts

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useClipboard.ts
+ * @input Uses React state/effect/callback; navigator.clipboard; useAnnounce
+ * @output Exports useClipboard hook plus its options/return types
+ * @position Core behavior hook; owns the copy-to-clipboard behavior shared by
+ *   CodeBlock and Timestamp — the clipboard write, the transient "copied"
+ *   flag with its reset timer, and the polite screen-reader announcement — so
+ *   each call site is a thin control over one implementation instead of
+ *   re-deriving the timer/announce details independently.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useClipboard.doc.mjs
+ * - /packages/core/src/hooks/useClipboard.test.tsx
+ */
+
+import {useCallback, useEffect, useRef, useState} from 'react';
+import {useAnnounce} from './useAnnounce';
+
+/**
+ * How long `isCopied` stays true after a successful copy before reverting.
+ * Long enough for the copied confirmation (e.g. a copy → check icon flip) to
+ * register without lingering.
+ */
+const DEFAULT_RESET_AFTER_MS = 2000;
+
+/**
+ * Options for {@link useClipboard}.
+ */
+export interface UseClipboardOptions {
+  /**
+   * Message announced to a polite live region on a successful copy. Swapping a
+   * control's `aria-label` alone is not reliably announced by screen readers,
+   * so pass the localized confirmation (e.g. "Copied") to have it spoken.
+   * Omit to skip the announcement.
+   */
+  announce?: string;
+  /**
+   * Milliseconds `isCopied` stays true after a successful copy before it
+   * reverts to false.
+   * @default 2000
+   */
+  resetAfterMs?: number;
+}
+
+/**
+ * Return value of {@link useClipboard}.
+ */
+export interface UseClipboardReturn {
+  /**
+   * Write `text` to the clipboard. On success, flips `isCopied` to true,
+   * announces the configured message, and (re)starts the reset timer;
+   * resolves `true`. A clipboard rejection is a silent no-op that leaves the
+   * copied state unchanged and resolves `false`.
+   */
+  copy: (text: string) => Promise<boolean>;
+  /** True for `resetAfterMs` after the most recent successful copy. */
+  isCopied: boolean;
+}
+
+/**
+ * Copy-to-clipboard behavior: the clipboard write, a transient `isCopied`
+ * flag with its own reset timer, and an optional polite screen-reader
+ * announcement — the block otherwise re-derived at every copy affordance.
+ *
+ * Per [API Conventions → Behaviors: Hooks Over Wrappers], the behavior is a
+ * hook and the control (an icon button, a menu item, a value chip) is a thin
+ * shell over it. Rapid re-copies restart the reset timer so the confirmation
+ * always lasts the full duration, and the timer is cleaned up on unmount.
+ *
+ * @example
+ * ```
+ * function CopyButton({text}: {text: string}) {
+ *   const {copy, isCopied} = useClipboard({announce: 'Copied'});
+ *   return (
+ *     <IconButton
+ *       label={isCopied ? 'Copied' : 'Copy'}
+ *       tooltip="Copy"
+ *       icon={<Icon icon={isCopied ? 'check' : 'copy'} />}
+ *       onClick={() => void copy(text)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useClipboard(
+  options: UseClipboardOptions = {},
+): UseClipboardReturn {
+  const {announce: announceMessage, resetAfterMs = DEFAULT_RESET_AFTER_MS} =
+    options;
+  const announce = useAnnounce();
+  const [isCopied, setIsCopied] = useState(false);
+  const resetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clear a pending "copied" reset when the consumer unmounts.
+  useEffect(() => {
+    return () => {
+      if (resetTimerRef.current != null) {
+        clearTimeout(resetTimerRef.current);
+      }
+    };
+  }, []);
+
+  const copy = useCallback(
+    async (text: string): Promise<boolean> => {
+      try {
+        await navigator.clipboard.writeText(text);
+        setIsCopied(true);
+        if (announceMessage) {
+          announce(announceMessage);
+        }
+        // Restart the reset timer on every copy — otherwise a rapid re-copy
+        // is reverted early by the previous copy's timer.
+        if (resetTimerRef.current != null) {
+          clearTimeout(resetTimerRef.current);
+        }
+        resetTimerRef.current = setTimeout(() => {
+          resetTimerRef.current = null;
+          setIsCopied(false);
+        }, resetAfterMs);
+        return true;
+      } catch {
+        // Clipboard failures leave the copied state unchanged.
+        return false;
+      }
+    },
+    [announce, announceMessage, resetAfterMs],
+  );
+
+  return {copy, isCopied};
+}

package/src/hooks/useContainerReveal.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
     {
       name: 'options.isEnabled',
       type: 'boolean',
-      description: 'When false the hook is inert: no marker is applied and content getters return no styles, so content is always shown. Lets a component gate reveal on its own prop (e.g. revealOn === "hover").',
+      description: 'When false the hook is inert: the container gets no styles and content getters return no styles, so content is always shown. Read on every render, so a component can flip it after mount (e.g. revealOn === "hover").',
       default: 'true',
       required: false,
     },
@@ -34,11 +34,11 @@ export const docs = {
   ],
   usage: {
     description:
-      'A headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it when the container is hovered or receives keyboard focus: the classic "row actions appear on hover" pattern. The reveal is CSS-only: no hover state lives in React and hovering never triggers a re-render. The caller authors no StyleX for the reveal itself; the hook hands out a scoped marker and matching styles, so nested containers never leak hover/focus into one another. Accessible by construction: revealed content is visually hidden at rest with position and opacity (never display:none), so it stays mounted, keeps its place in the tab order, and is announced to assistive technology; it reveals on :focus-within so keyboard users see it when tabbing in, stays visible on touch (never gated behind hover on coarse pointers), and honors prefers-reduced-motion.',
+      'A headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it when the container is hovered or receives keyboard focus: the classic "row actions appear on hover" pattern. The reveal is CSS-only: no hover state lives in React and hovering never triggers a re-render. The caller authors no StyleX for the reveal itself; the hook hands out the container and content styles, and a nested container shadows its ancestor, so nested containers never leak hover/focus into one another. Accessible by construction: revealed content is visually hidden at rest with position and opacity (never display:none), so it stays mounted, keeps its place in the tab order, and is announced to assistive technology; it reveals on :focus-within so keyboard users see it when tabbing in, stays visible on touch (never gated behind hover on coarse pointers), and honors prefers-reduced-motion.',
     bestPractices: [
       { guidance: true, description: 'Destructure getContainerProps and getContentRevealProps; spread getContainerProps() on the container (via mergeProps with your own stylex.props) and getContentRevealProps() on the content to reveal.' },
       { guidance: true, description: 'Use for secondary affordances: reveal-on-hover row actions (edit/copy/remove on list or table rows) and overlay controls on a card or media tile (e.g. Thumbnail\'s remove button).' },
-      { guidance: true, description: 'Gate the reveal with isEnabled when a consumer prop decides whether content is revealed on hover or always shown.' },
+      { guidance: true, description: 'Gate the reveal with isEnabled when a consumer prop decides whether content is revealed on hover or always shown; it can change at any time.' },
       { guidance: true, description: 'Pass isLayoutPreserved for absolutely-positioned or overlay content to reserve its box and avoid layout shift when it appears.' },
       { guidance: false, description: 'Use it to hide content that must always be discoverable; keep essential actions visible instead of gating them behind hover.' },
     ],
@@ -52,10 +52,10 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out a scoped marker + matching styles, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
+    'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out container + content styles; a nested container shadows its ancestor, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
   paramDescriptions: {
     options: 'config for reveal container. optional.',
-    'options.isEnabled': 'when false hook is inert: no marker, content getters return no styles, content always shown. Lets component gate reveal on its own prop.',
+    'options.isEnabled': 'when false hook is inert: no container styles, content getters return no styles, content always shown. Read every render, so it can flip after mount.',
   },
   returnDescriptions: {
     getContainerProps: 'spread onto container whose hover/focus-within drives reveal.',
@@ -63,11 +63,11 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out a scoped marker + matching styles, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
+      'Headless hover/focus reveal primitive. Gives a container a scoped trigger that reveals (or conceals) content inside it on hover / keyboard focus: the "row actions appear on hover" pattern. CSS-only: no hover state in React, no re-render on hover. Caller authors no StyleX; hook hands out container + content styles; a nested container shadows its ancestor, so nested containers never leak hover/focus. Accessible: revealed content visually hidden at rest via position + opacity (never display:none), stays mounted + in tab order + announced; reveals on :focus-within, stays visible on touch, honors prefers-reduced-motion.',
     bestPractices: [
       { guidance: true, description: 'Destructure getContainerProps + getContentRevealProps; spread getContainerProps() on container (via mergeProps w/ your stylex.props) + getContentRevealProps() on content to reveal.' },
       { guidance: true, description: 'Use for secondary affordances: reveal-on-hover row actions (edit/copy/remove on list / table rows) + overlay controls on card / media tile (e.g. Thumbnail remove button).' },
-      { guidance: true, description: 'Gate reveal w/ isEnabled when a consumer prop decides revealed-on-hover vs always shown.' },
+      { guidance: true, description: 'Gate reveal w/ isEnabled when a consumer prop decides revealed-on-hover vs always shown; can change at any time.' },
       { guidance: true, description: 'Pass isLayoutPreserved for absolutely-positioned / overlay content to reserve its box + avoid layout shift.' },
       { guidance: false, description: 'Use to hide content that must always be discoverable; keep essential actions visible instead of gating behind hover.' },
     ],