@astryxdesign/core 0.4.2-canary.791f395 → 0.4.2

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

@@ -105,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.' },
     ],
   },

package/src/hooks/useContainerReveal.test.tsx

@@ -4,13 +4,16 @@
  * @file useContainerReveal.test.tsx
  * @input Uses vitest, @testing-library/react, useContainerReveal
  * @output Unit tests for the enabled/disabled contract, the dynamic isEnabled
- *   prop, the content-option → style-block mapping, and the promise that a
- *   large flat list mounts without dev warnings.
+ *   prop, the container options (hoverDelay, forceState), the per-element
+ *   option → style-block mapping, and the promise that a large flat list
+ *   mounts without dev warnings.
  * @position Testing; validates useContainerReveal.ts.
  *
  * Nesting isolation is a cascade behavior jsdom does not implement, so it is
  * verified in a real browser (Storybook's NestedIsolation story) rather than
- * asserted here.
+ * asserted here. The same goes for what the dwell and the forced states
+ * actually paint: these tests assert the wiring, the browser proves the pixels
+ * (HoverIntentDelay, ForcedVisibility).
  *
  * SYNC: When useContainerReveal.ts changes, update these tests.
  */
@@ -74,6 +77,70 @@ describe('useContainerReveal', () => {
     expect(clipped).not.toBe(preserved);
   });
 
+  it('forceState pins each end of the container to its own style block', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const auto = result.current.getContainerProps().className;
+    const inactive = result.current.getContainerProps({
+      forceState: 'inactive',
+    }).className;
+    const active = result.current.getContainerProps({
+      forceState: 'active',
+    }).className;
+    expect(new Set([auto, inactive, active]).size).toBe(3);
+  });
+
+  it('forceVisibility pins one element, independent of its reveal mode', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const auto = result.current.getContentRevealProps().className;
+    const shown = result.current.getContentRevealProps({
+      forceVisibility: 'shown',
+    }).className;
+    const hidden = result.current.getContentRevealProps({
+      forceVisibility: 'hidden',
+    }).className;
+    expect(new Set([auto, shown, hidden]).size).toBe(3);
+
+    // The layout-preserved variant has no position to flip, so hidden maps to
+    // its own opacity-only block.
+    expect(
+      result.current.getContentRevealProps({
+        forceVisibility: 'hidden',
+        isLayoutPreserved: true,
+      }).className,
+    ).not.toBe(hidden);
+  });
+
+  it('hoverDelay publishes the dwell as an inline custom property', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const {style} = result.current.getContainerProps({hoverDelay: 120});
+    expect(Object.values(style ?? {})).toContain('120ms');
+    expect(result.current.getContainerProps({hoverDelay: 0}).style).toEqual(
+      result.current.getContainerProps().style,
+    );
+  });
+
+  it('hoverDelay and forceState compose on one container', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const props = result.current.getContainerProps({
+      hoverDelay: 120,
+      forceState: 'inactive',
+    });
+    expect(Object.values(props.style ?? {})).toContain('120ms');
+    expect(props.className).not.toBe(
+      result.current.getContainerProps({hoverDelay: 120}).className,
+    );
+  });
+
+  it('ignores container options while disabled', () => {
+    const {result} = renderHook(() => useContainerReveal({isEnabled: false}));
+    expect(
+      result.current.getContainerProps({
+        hoverDelay: 120,
+        forceState: 'inactive',
+      }),
+    ).toEqual({});
+  });
+
   it('mounts a large flat list without a dev warning', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     function Row() {

package/src/hooks/useContainerReveal.ts

@@ -20,10 +20,21 @@
  * container shadows its ancestor's state for its own subtree. See
  * containerReveal.stylex.ts.
  *
+ * Two levers sit on top of the pointer, both still CSS-only. On the container:
+ * `hoverDelay` (dwell before the reveal starts — the Tooltip / HoverCard
+ * intent gate applied to a reveal) and `forceState` (pin the trigger state a
+ * caller owns: a motion gate, a scroll, an open menu). On a single piece of
+ * content: `forceVisibility`, which pins how THAT element looks. State belongs
+ * to the container because one container feeds children whose looks are
+ * opposite; appearance belongs to the element, where it is unambiguous.
+ * Neither lever can hide content from a keyboard user — see ACCESSIBILITY.
+ *
  * ACCESSIBILITY (WCAG 2.2 by construction):
  * - Revealed content is visually hidden at rest via position + opacity, so it
  *   stays in the accessibility tree and tab order — never display:none.
- * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it — with no dwell
+ *   to wait through, and neither an inactive container nor a forced-hidden
+ *   element can keep it dark.
  * - Touch: always visible on coarse pointers; never gated behind hover.
  * - Concealed (inverted) content is a mouse-only visual swap: it ignores
  *   :focus-within (a keyboard user must never watch content vanish) and stays
@@ -50,6 +61,36 @@ export interface UseContainerRevealOptions {
   isEnabled?: boolean;
 }
 
+export interface ContainerRevealOptions {
+  /**
+   * Pin the container's trigger state instead of letting the pointer drive it.
+   * `'active'` reads as pointed-at and `'inactive'` as at rest; omit it — the
+   * default — to leave the container on hover and focus.
+   *
+   * State, not appearance: what each child then looks like is the child's own
+   * business (revealed content fades in on `'active'`, inverted content fades
+   * out). This is the lever for state a caller owns — a motion gate over a
+   * list, a scroll in progress, a row whose menu is open and must stay lit.
+   *
+   * `'inactive'` never overrides keyboard focus or a coarse pointer: the
+   * container still reveals on :focus-within and stays revealed on touch, so
+   * it cannot hide content from a keyboard or touch user.
+   */
+  forceState?: 'active' | 'inactive';
+  /**
+   * Hover-intent gate, in milliseconds: how long the pointer must rest on the
+   * container before the reveal starts. A pointer that passes through leaves
+   * nothing painted behind it, which is what keeps a list of rows quiet while
+   * the cursor sweeps across it.
+   *
+   * Mouse-only, like Tooltip's and HoverCard's `delay`: keyboard focus and
+   * touch reveal immediately. It survives `prefers-reduced-motion` — an intent
+   * gate is timing, not motion.
+   * @default 0
+   */
+  hoverDelay?: number;
+}
+
 export interface ContentRevealOptions {
   /**
    * Conceal-on-hover instead of reveal-on-hover: content is visible at rest
@@ -64,11 +105,27 @@ export interface ContentRevealOptions {
    * @default false
    */
   isLayoutPreserved?: boolean;
+  /**
+   * Pin THIS element's appearance, whatever the container's state: `'shown'`
+   * keeps it visible, `'hidden'` keeps it out. Omit it — the default — to
+   * follow the container.
+   *
+   * Appearance, not state: it says how one element looks, so it is unambiguous
+   * where the container's `forceState` cannot be (a container feeds revealed
+   * and inverted children at once).
+   *
+   * `'hidden'` yields to focus — a forced-hidden element is still mounted and
+   * tabbable, so it reappears when focus lands inside it.
+   */
+  forceVisibility?: 'shown' | 'hidden';
 }
 
 export interface UseContainerRevealReturn {
   /** Spread onto the container whose hover/focus-within drives the reveal. */
-  getContainerProps: () => {className?: string; style?: CSSProperties};
+  getContainerProps: (options?: ContainerRevealOptions) => {
+    className?: string;
+    style?: CSSProperties;
+  };
   /** Spread onto each revealed / concealed child. */
   getContentRevealProps: (options?: ContentRevealOptions) => {
     className?: string;
@@ -87,7 +144,11 @@ const EMPTY = Object.freeze({});
  *   isEnabled: revealOn === 'hover',
  * });
  *
- * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ * <div
+ *   {...mergeProps(
+ *     getContainerProps({hoverDelay: 120, forceState: gateState}),
+ *     stylex.props(styles.row),
+ *   )}>
  *   {label}
  *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
  *     {actions}
@@ -108,10 +169,21 @@ export function useContainerReveal(
       };
     }
     return {
-      getContainerProps: () => stylex.props(styles.container),
+      getContainerProps: (containerOptions: ContainerRevealOptions = {}) => {
+        const {forceState, hoverDelay = 0} = containerOptions;
+        return stylex.props(
+          styles.container,
+          hoverDelay > 0 && styles.hoverDelay(`${hoverDelay}ms`),
+          forceState === 'inactive' && styles.stateInactive,
+          forceState === 'active' && styles.stateActive,
+        );
+      },
       getContentRevealProps: (contentOptions: ContentRevealOptions = {}) => {
-        const {isRevealInverted = false, isLayoutPreserved = false} =
-          contentOptions;
+        const {
+          isRevealInverted = false,
+          isLayoutPreserved = false,
+          forceVisibility,
+        } = contentOptions;
         const style = isRevealInverted
           ? isLayoutPreserved
             ? styles.concealLayoutPreserved
@@ -119,7 +191,14 @@ export function useContainerReveal(
           : isLayoutPreserved
             ? styles.revealLayoutPreserved
             : styles.reveal;
-        return stylex.props(style);
+        return stylex.props(
+          style,
+          forceVisibility === 'shown' && styles.contentShown,
+          forceVisibility === 'hidden' &&
+            (isLayoutPreserved
+              ? styles.contentHiddenLayoutPreserved
+              : styles.contentHidden),
+        );
       },
     };
   }, [isEnabled]);