@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,6 +9,8 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -817,3 +819,44 @@ describe('TopNavMegaMenuItem', () => {
     expect(screen.getByRole('link', {name: /Analytics/})).toBeInTheDocument();
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMegaMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: 'Products'}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMegaMenu.tsx

@@ -50,6 +50,7 @@ import {
   borderVars,
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useMenuHover} from '../hooks/useMenuHover';
 import {Grid} from '../Grid/Grid';
 import {Icon} from '../Icon';
 import {mergeProps, mergeRefs} from '../utils';
@@ -370,7 +371,9 @@ TopNavMegaMenu.displayName = 'TopNavMegaMenu';
 // DefaultMegaMenu — desktop popover mode
 // =============================================================================
 
-const CLICK_GUARD_MS = 500;
+/** The panel is a grid of links, not `role="menuitem"` rows. */
+const PANEL_ITEM_SELECTOR =
+  'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
 function DefaultMegaMenu({
   ref,
@@ -382,19 +385,13 @@ function DefaultMegaMenu({
   onOpenChange,
 }: TopNavMegaMenuProps) {
   const slot = useTopNavSlot();
-  const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
-  const hoverOpenedAtRef = useRef(0);
-  const stickyRef = useRef(false);
 
   const handlePopoverShow = useCallback(() => {
     onOpenChange?.(true);
   }, [onOpenChange]);
 
   const handlePopoverHide = useCallback(() => {
-    hoverOpenedAtRef.current = 0;
-    stickyRef.current = false;
     onOpenChange?.(false);
   }, [onOpenChange]);
 
@@ -430,107 +427,31 @@ function DefaultMegaMenu({
     };
   }, [popover]);
 
-  const clearTimeouts = useCallback(() => {
-    if (showTimeoutRef.current) {
-      clearTimeout(showTimeoutRef.current);
-      showTimeoutRef.current = null;
-    }
-    if (hideTimeoutRef.current) {
-      clearTimeout(hideTimeoutRef.current);
-      hideTimeoutRef.current = null;
-    }
-  }, []);
-
-  const scheduleShow = useCallback(() => {
-    clearTimeouts();
-    showTimeoutRef.current = setTimeout(() => {
-      hoverOpenedAtRef.current = Date.now();
-      popover.show({skipAutoFocus: true});
-    }, delay);
-  }, [clearTimeouts, delay, popover]);
-
-  const scheduleHide = useCallback(() => {
-    clearTimeouts();
-    hideTimeoutRef.current = setTimeout(() => {
-      popover.hide();
-    }, hideDelay);
-  }, [clearTimeouts, hideDelay, popover]);
-
-  const focusFirstPanelItem = useCallback(() => {
-    popover.contentRef.current
-      ?.querySelector<HTMLElement>(
-        'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])',
-      )
-      ?.focus();
-  }, [popover.contentRef]);
-
-  const handleTriggerMouseEnter = useCallback(() => {
-    clearTimeouts();
-    if (!popover.isOpen) {
-      scheduleShow();
-    }
-  }, [clearTimeouts, popover.isOpen, scheduleShow]);
-
-  const handlePanelMouseEnter = useCallback(() => {
-    clearTimeouts();
-  }, [clearTimeouts]);
-
-  const handleMouseLeave = useCallback(() => {
-    if (!stickyRef.current) {
-      scheduleHide();
-    }
-  }, [scheduleHide]);
-
-  const handleClick = useCallback(
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-      // Cancel the native invoker toggle so this guard is the single source of
-      // truth for trigger activation. popoverTarget still establishes the
-      // invoker relationship used by native light-dismiss and stacking.
-      event.preventDefault();
-      clearTimeouts();
-
-      if (event.detail === 0) {
-        stickyRef.current = true;
-        hoverOpenedAtRef.current = 0;
-        if (popover.isOpen) {
-          focusFirstPanelItem();
-        } else {
-          popover.show();
-        }
-      } else if (!popover.isOpen) {
-        stickyRef.current = true;
-        popover.show({skipAutoFocus: true});
-      } else if (Date.now() - hoverOpenedAtRef.current < CLICK_GUARD_MS) {
-        // A click that naturally follows a hover-open confirms the open state
-        // instead of toggling the panel shut. From here it behaves like any
-        // other click-open and stays pinned until explicit dismissal.
-        stickyRef.current = true;
-        hoverOpenedAtRef.current = 0;
-      } else {
-        popover.hide();
-        triggerButtonRef.current?.focus();
-      }
-    },
-    [clearTimeouts, focusFirstPanelItem, popover],
-  );
-
-  useEffect(() => {
-    return () => {
-      clearTimeouts();
-    };
-  }, [clearTimeouts]);
+  const {
+    triggerProps: hoverTriggerProps,
+    contentProps,
+    menuRef,
+    setTriggerEl,
+  } = useMenuHover<HTMLDivElement>({
+    show: popover.show,
+    hide: popover.hide,
+    isOpen: popover.isOpen,
+    isEnabled: true,
+    showDelay: delay,
+    hideDelay,
+    itemSelector: PANEL_ITEM_SELECTOR,
+    // Trigger sits outside an auto popover; the invoker relationship exempts it
+    // from light dismiss.
+    popoverId: popover.id,
+  });
 
   return (
     <>
       <button
-        ref={mergeRefs(triggerButtonRef, ref)}
+        ref={mergeRefs(triggerButtonRef, setTriggerEl, ref)}
         type="button"
         {...popover.triggerProps}
-        // Native invoker prevents trigger light-dismiss.
-        popoverTarget={popover.id}
-        onClick={handleClick}
-        onMouseEnter={handleTriggerMouseEnter}
-        onMouseLeave={handleMouseLeave}
+        {...hoverTriggerProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
           focusOutlineProps.focusVisible(
@@ -551,10 +472,10 @@ function DefaultMegaMenu({
           // role="group" — a mega menu is a browsing grid of links, not an
           // ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is
           // for action menus; link mega menus are the documented anti-case).
+          ref={menuRef}
           role="group"
           aria-label={label}
-          onMouseEnter={handlePanelMouseEnter}
-          onMouseLeave={handleMouseLeave}
+          {...contentProps}
           {...stylex.props(styles.panelContainer)}>
           <div {...stylex.props(styles.panelContent)}>
             {/* Menu items section */}
@@ -602,7 +523,10 @@ function DrawerMegaMenu({
         aria-controls={`${menuId}-items`}
         {...mergeProps(
           themeProps('top-nav-mega-menu', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerHeader),
+          focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            styles.drawerHeader,
+          ),
         )}>
         {label}
         <Icon

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -215,7 +215,7 @@ export function TopNavMegaMenuItem({
         {...elementProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu-item', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerItem),
+          focusOutlineProps.focusVisible(navItemStyles.item, styles.drawerItem),
         )}>
         {icon && <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>}
         <div {...stylex.props(styles.drawerItemContent)}>

package/src/TopNav/TopNavMenu.test.tsx

@@ -12,6 +12,9 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {TopNavRenderContext} from './TopNavRenderContext';
 import {TopNavMenu} from './TopNavMenu';
 
 const mockItems = [
@@ -171,3 +174,41 @@ describe('keyboard navigation (APG menu pattern)', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: /Products/}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -342,7 +342,7 @@ export function TopNavMenu({
     role: 'none',
   });
 
-  const {triggerProps, contentProps, menuRef, setTriggerEl} =
+  const {triggerProps, contentProps, menuRef, setTriggerEl, close} =
     useMenuHover<HTMLDivElement>({
       show: popover.show,
       hide: popover.hide,
@@ -350,6 +350,9 @@ export function TopNavMenu({
       isEnabled: true,
       showDelay: delay,
       hideDelay,
+      // Trigger sits outside an auto popover; the invoker relationship exempts
+      // it from light dismiss.
+      popoverId: popover.id,
     });
 
   const setTriggerRef = mergeRefs<HTMLButtonElement>(
@@ -368,7 +371,8 @@ export function TopNavMenu({
     useListFocus<HTMLDivElement>({
       itemSelector: '[role="menuitem"]',
       hasRovingTabIndex: true,
-      onEscape: popover.hide,
+      // Not popover.hide: Escape must also restore focus to the trigger.
+      onEscape: close,
     });
 
   // First-character typeahead over the menu items (menus-11).
@@ -432,7 +436,10 @@ export function TopNavMenu({
           onClick={() => setDrawerExpanded(v => !v)}
           aria-expanded={drawerExpanded}
           aria-controls={`${menuId}-items`}
-          {...stylex.props(navItemStyles.item, drawerStyles.header)}>
+          {...focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            drawerStyles.header,
+          )}>
           {label}
           <Icon
             icon="chevronDown"
@@ -459,7 +466,10 @@ export function TopNavMenu({
                   item.onClick?.();
                   closeMobileNav();
                 }}
-                {...stylex.props(navItemStyles.item, drawerStyles.item)}>
+                {...focusOutlineProps.focusVisible(
+                  navItemStyles.item,
+                  drawerStyles.item,
+                )}>
                 {item.icon && (
                   <span {...stylex.props(drawerStyles.itemIcon)}>
                     {item.icon}

package/src/TreeList/TreeList.doc.mjs

@@ -33,6 +33,7 @@ export const docs = {
     vars: [
       {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
       {name: '--tree-list-row-gap', description: 'Vertical gap between adjacent rows. Default `2px` (var(--spacing-0-5)) gives a subtle separation; set it on the `tree-list` target to widen or close the gap. The connector guides span the gap automatically (the line stays continuous) and do not overhang the last row, so no guide-height tuning is needed.', default: 'var(--spacing-0-5)'},
+      {name: '--_tree-indent', description: 'Distance one row is indented, computed per row from --tree-list-indent and the row depth. Set --tree-list-indent to retune indentation; this is the resolved value.', default: '0px', private: true},
     ],
   },
   components: [

package/src/hooks/containerReveal.stylex.ts

@@ -3,9 +3,9 @@
 /**
  * @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.
+ * @output The container style that publishes the reveal state, the suspended
+ *   and hover-delay container variants, 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
@@ -22,8 +22,14 @@ import {durationVars, easeVars} from '../theme/tokens.stylex';
 
 const REST_DELAY = '0s, ' + durationVars['--duration-fast'];
 
+// The hover-intent gate: how long the pointer must dwell before the hover
+// branch takes effect. Declared on every container so a nested one never
+// inherits its ancestor's dwell.
+const HOVER_DELAY = 'var(--_hover-delay, 0s)';
+
 export const styles = stylex.create({
   container: {
+    '--_hover-delay': '0s',
     '--_reveal-opacity': {
       default: 0,
       ':hover': {'@media (hover: hover)': 1},
@@ -37,13 +43,21 @@ export const styles = stylex.create({
       '@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.
+    // a state-conditional delay: the dwell on entry (flips into flow when the
+    // gate opens, then fades in) and the fade duration on exit (stays in flow
+    // until the fade finishes, then snaps out) — without the exit half the
+    // content would snap out of flow at full opacity and flicker.
     '--_reveal-delay': {
       default: REST_DELAY,
-      ':hover': {'@media (hover: hover)': '0s, 0s'},
+      ':hover': {'@media (hover: hover)': HOVER_DELAY + ', ' + HOVER_DELAY},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    // Reduced motion drops the exit sequencing (there is no fade left to wait
+    // for) but keeps the dwell: an intent gate is timing, not motion.
+    '--_reveal-delay-reduced': {
+      default: '0s, 0s',
+      ':hover': {'@media (hover: hover)': HOVER_DELAY + ', ' + HOVER_DELAY},
       ':focus-within': '0s, 0s',
       '@media (any-pointer: coarse)': '0s, 0s',
     },
@@ -54,7 +68,98 @@ export const styles = stylex.create({
       default: 1,
       ':hover': {'@media (hover: hover)': 0},
     },
+    // Single-value dwell for the opacity-only blocks, which have no discrete
+    // position to sequence.
+    '--_fade-delay': {
+      default: '0s',
+      ':hover': {'@media (hover: hover)': HOVER_DELAY},
+      ':focus-within': '0s',
+      '@media (any-pointer: coarse)': '0s',
+    },
+  },
+  // stateInactive is `container` with the hover branch pinned to its rest
+  // value, so the pointer stops driving the reveal while a caller holds the
+  // container inactive. Keyboard focus and coarse pointers keep their branches:
+  // an inactive container must never hide content from a keyboard or touch
+  // user. Every property repeats the full condition shape of `container` —
+  // StyleX replaces styles per property AND condition, so a plain `default`
+  // here would lose to the earlier block's `:hover` rule.
+  stateInactive: {
+    '--_reveal-opacity': {
+      default: 0,
+      ':hover': {'@media (hover: hover)': 0},
+      ':focus-within': 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    '--_reveal-position': {
+      default: 'absolute',
+      ':hover': {'@media (hover: hover)': 'absolute'},
+      ':focus-within': 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+    '--_reveal-delay': {
+      default: REST_DELAY,
+      ':hover': {'@media (hover: hover)': REST_DELAY},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    '--_reveal-delay-reduced': {
+      default: '0s, 0s',
+      ':hover': {'@media (hover: hover)': '0s, 0s'},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    '--_conceal-opacity': {
+      default: 1,
+      ':hover': {'@media (hover: hover)': 1},
+    },
+    '--_fade-delay': {
+      default: '0s',
+      ':hover': {'@media (hover: hover)': '0s'},
+      ':focus-within': '0s',
+      '@media (any-pointer: coarse)': '0s',
+    },
+  },
+  // stateActive pins the other end: every branch reads as pointed-at, so
+  // revealed content stays in and inverted content stays out, with no dwell to
+  // wait through.
+  stateActive: {
+    '--_reveal-opacity': {
+      default: 1,
+      ':hover': {'@media (hover: hover)': 1},
+      ':focus-within': 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    '--_reveal-position': {
+      default: 'static',
+      ':hover': {'@media (hover: hover)': 'static'},
+      ':focus-within': 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+    '--_reveal-delay': {
+      default: '0s, 0s',
+      ':hover': {'@media (hover: hover)': '0s, 0s'},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    '--_reveal-delay-reduced': {
+      default: '0s, 0s',
+      ':hover': {'@media (hover: hover)': '0s, 0s'},
+      ':focus-within': '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    '--_conceal-opacity': {
+      default: 0,
+      ':hover': {'@media (hover: hover)': 0},
+    },
+    '--_fade-delay': {
+      default: '0s',
+      ':hover': {'@media (hover: hover)': '0s'},
+      ':focus-within': '0s',
+      '@media (any-pointer: coarse)': '0s',
+    },
   },
+  hoverDelay: (delay: string) => ({'--_hover-delay': delay}),
   // The fallbacks make content spread outside a reveal container fail visible
   // rather than invisible.
   reveal: {
@@ -67,7 +172,8 @@ export const styles = stylex.create({
     transitionBehavior: 'allow-discrete',
     transitionDelay: {
       default: 'var(--_reveal-delay, 0s, 0s)',
-      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      '@media (prefers-reduced-motion: reduce)':
+        'var(--_reveal-delay-reduced, 0s, 0s)',
     },
     opacity: 'var(--_reveal-opacity, 1)',
     position: 'var(--_reveal-position, static)',
@@ -79,6 +185,7 @@ export const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
+    transitionDelay: 'var(--_fade-delay, 0s)',
     opacity: 'var(--_reveal-opacity, 1)',
   },
   conceal: {
@@ -88,6 +195,7 @@ export const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
+    transitionDelay: 'var(--_fade-delay, 0s)',
     opacity: 'var(--_conceal-opacity, 1)',
   },
   concealLayoutPreserved: {
@@ -97,6 +205,29 @@ export const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
+    transitionDelay: 'var(--_fade-delay, 0s)',
     opacity: 'var(--_conceal-opacity, 1)',
   },
+  // Per-element overrides. These read no container state at all — they are the
+  // caller saying what THIS element looks like, whatever the container is
+  // doing, so they are plain values rather than custom properties.
+  contentShown: {
+    opacity: 1,
+    position: 'static',
+    transitionDelay: '0s',
+  },
+  // Hidden yields to focus: a forced-hidden element is still mounted and still
+  // tabbable, so it has to reappear when focus lands inside it — otherwise a
+  // keyboard user tabs into something they cannot see.
+  contentHidden: {
+    opacity: {default: 0, ':focus-within': 1},
+    position: {default: 'absolute', ':focus-within': 'static'},
+    transitionDelay: '0s',
+  },
+  // Layout-preserved content has no discrete position to flip, so its hidden
+  // variant is opacity alone.
+  contentHiddenLayoutPreserved: {
+    opacity: {default: 0, ':focus-within': 1},
+    transitionDelay: '0s',
+  },
 });

package/src/hooks/index.ts

@@ -11,7 +11,11 @@
  * SYNC: When modified, update this header
  */
 
-export {useFocusTrap} from './useFocusTrap';
+export {
+  hasActiveFocusTrapEscape,
+  isImeKeyEvent,
+  useFocusTrap,
+} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
 export {useAnnounce} from './useAnnounce';
@@ -101,5 +105,6 @@ export {useContainerReveal} from './useContainerReveal';
 export type {
   UseContainerRevealOptions,
   UseContainerRevealReturn,
+  ContainerRevealOptions,
   ContentRevealOptions,
 } from './useContainerReveal';

package/src/hooks/useContainerReveal.doc.mjs

@@ -23,13 +23,13 @@ export const docs = {
   returns: [
     {
       name: 'getContainerProps',
-      type: '() => {className?: string; style?: CSSProperties}',
-      description: 'Spread onto the container whose hover/focus-within drives the reveal.',
+      type: '(options?: ContainerRevealOptions) => {className?: string; style?: CSSProperties}',
+      description: 'Spread onto the container whose hover/focus-within drives the reveal. Accepts hoverDelay (ms the pointer must dwell before the reveal starts — a hover-intent gate like Tooltip\'s and HoverCard\'s delay, so a cursor sweeping across a list leaves nothing painted behind it) and forceState ("active" | "inactive") to pin the trigger state when a caller owns it — a motion gate, a scroll, a row whose menu is open. "inactive" still yields to keyboard focus and coarse pointers.',
     },
     {
       name: 'getContentRevealProps',
       type: '(options?: ContentRevealOptions) => {className?: string; style?: CSSProperties}',
-      description: 'Spread onto each revealed (or concealed) child. Accepts isRevealInverted to conceal-on-hover instead of reveal-on-hover, and isLayoutPreserved to reserve the layout box while hidden (opacity-only) and avoid layout shift.',
+      description: 'Spread onto each revealed / concealed child. Accepts isRevealInverted to conceal-on-hover instead of reveal-on-hover, isLayoutPreserved to reserve the layout box while hidden (opacity-only) and avoid layout shift, and forceVisibility ("shown" | "hidden") to pin this one element\'s appearance whatever the container is doing. "hidden" yields to focus.',
     },
   ],
   usage: {
@@ -40,6 +40,9 @@ export const docs = {
       { 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; 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: true, description: 'Set a hoverDelay (100-250ms) on rows in a long list, so a cursor travelling across the list does not light up every row it passes; keyboard and touch still reveal immediately.' },
+      { guidance: true, description: 'Reach for forceState when something other than the pointer owns the interaction (a drag, a scroll or motion gate, an open row menu), and forceVisibility when just one element should ignore the container.' },
+      { guidance: false, description: 'Reach past the API into the hook\'s private custom properties (--_reveal-opacity and friends) to suppress a reveal; use forceState / forceVisibility, which survive a rename.' },
       { guidance: false, description: 'Use it to hide content that must always be discoverable; keep essential actions visible instead of gating them behind hover.' },
     ],
   },
@@ -58,8 +61,8 @@ export const docsDense = {
     '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.',
-    getContentRevealProps: 'spread onto each revealed / concealed child. Accepts isRevealInverted (conceal-on-hover) + isLayoutPreserved (reserve layout box while hidden).',
+    getContainerProps: 'spread onto container whose hover/focus-within drives reveal. Accepts hoverDelay (ms dwell before reveal starts — hover-intent gate like Tooltip / HoverCard delay) + forceState ("active" | "inactive") to pin trigger state when a caller owns it. "inactive" yields to keyboard focus + coarse pointers.',
+    getContentRevealProps: 'spread onto each revealed / concealed child. Accepts isRevealInverted (conceal-on-hover), isLayoutPreserved (reserve layout box while hidden) + forceVisibility ("shown" | "hidden") to pin this element regardless of container. "hidden" yields to focus.',
   },
   usage: {
     description:
@@ -69,6 +72,9 @@ export const docsDense = {
       { 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; can change at any time.' },
       { guidance: true, description: 'Pass isLayoutPreserved for absolutely-positioned / overlay content to reserve its box + avoid layout shift.' },
+      { guidance: true, description: 'Set hoverDelay (100-250ms) on rows in a long list so a travelling cursor does not light up every row; keyboard + touch still reveal immediately.' },
+      { guidance: true, description: 'forceState when something else owns the interaction (drag, scroll / motion gate, open row menu); forceVisibility when one element should ignore the container.' },
+      { guidance: false, description: 'Reach past the API into private custom properties (--_reveal-opacity etc) to suppress a reveal; use forceState / forceVisibility.' },
       { guidance: false, description: 'Use to hide content that must always be discoverable; keep essential actions visible instead of gating behind hover.' },
     ],
   },