@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/hooks/containerReveal.pool.stylex.ts

@@ -0,0 +1,571 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file containerReveal.pool.stylex.ts
+ * @input Uses StyleX, theme tokens
+ * @output A fixed pool of scoped markers, each paired with its reveal style
+ *   blocks (reveal / conceal, each with a layout-preserved variant) compiled
+ *   against that marker.
+ * @position Internal to useContainerReveal. GENERATED by
+ *   scripts/gen-container-reveal-pool.mjs — do not edit by hand.
+ *
+ * WHY A POOL: `stylex.when.ancestor(':hover', marker)` welds the marker's
+ * class into the compiled selector (`.marker:hover *`), so a marker and the
+ * styles referencing it are inseparable at compile time. A single shared
+ * marker would leak hover/focus across NESTED reveal containers (an ancestor
+ * container's `:hover` matches a descendant container's revealed content).
+ * Pre-declaring N markers lets useContainerReveal hand each concurrently
+ * mounted container a distinct marker (free-list in useContainerReveal),
+ * isolating nested containers without the caller authoring any StyleX.
+ *
+ * SYNC: When the block shape changes, edit
+ * scripts/gen-container-reveal-pool.mjs and useContainerReveal.ts, then
+ * regenerate (node scripts/gen-container-reveal-pool.mjs) and commit.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, easeVars} from '../theme/tokens.stylex';
+
+export const POOL_SIZE = 6;
+
+export const m0 = stylex.defineMarker();
+const s0 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m0)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m0)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m0)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m0)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m1 = stylex.defineMarker();
+const s1 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m1)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m1)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m1)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m1)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m2 = stylex.defineMarker();
+const s2 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m2)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m2)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m2)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m2)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m3 = stylex.defineMarker();
+const s3 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m3)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m3)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m3)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m3)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m4 = stylex.defineMarker();
+const s4 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m4)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m4)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m4)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m4)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m5 = stylex.defineMarker();
+const s5 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch. The position flip is discrete,
+  // so it transitions with allow-discrete + a state-conditional delay: 0 on
+  // entry (flips to static 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: {
+    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: '0s, ' + durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': '0s, 0s'},
+      [stylex.when.ancestor(':focus-within', m5)]: '0s, 0s',
+      '@media (any-pointer: coarse)': '0s, 0s',
+    },
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m5)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m5)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m5)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+// The compiled StyleX style objects carry `when.ancestor` conditionals that
+// the public `StyleXStyles` type does not model, so the slot shape is inferred
+// from the generated blocks rather than annotated.
+export const POOL = [
+  {
+    marker: m0,
+    reveal: s0.reveal,
+    revealLayoutPreserved: s0.revealLayoutPreserved,
+    conceal: s0.conceal,
+    concealLayoutPreserved: s0.concealLayoutPreserved,
+  },
+  {
+    marker: m1,
+    reveal: s1.reveal,
+    revealLayoutPreserved: s1.revealLayoutPreserved,
+    conceal: s1.conceal,
+    concealLayoutPreserved: s1.concealLayoutPreserved,
+  },
+  {
+    marker: m2,
+    reveal: s2.reveal,
+    revealLayoutPreserved: s2.revealLayoutPreserved,
+    conceal: s2.conceal,
+    concealLayoutPreserved: s2.concealLayoutPreserved,
+  },
+  {
+    marker: m3,
+    reveal: s3.reveal,
+    revealLayoutPreserved: s3.revealLayoutPreserved,
+    conceal: s3.conceal,
+    concealLayoutPreserved: s3.concealLayoutPreserved,
+  },
+  {
+    marker: m4,
+    reveal: s4.reveal,
+    revealLayoutPreserved: s4.revealLayoutPreserved,
+    conceal: s4.conceal,
+    concealLayoutPreserved: s4.concealLayoutPreserved,
+  },
+  {
+    marker: m5,
+    reveal: s5.reveal,
+    revealLayoutPreserved: s5.revealLayoutPreserved,
+    conceal: s5.conceal,
+    concealLayoutPreserved: s5.concealLayoutPreserved,
+  },
+] as const;
+
+export type RevealSlot = (typeof POOL)[number];

package/src/hooks/index.ts

@@ -92,3 +92,10 @@ export {useLongPress} from './useLongPress';
 export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';
 
 export {useDevWarning} from './useDevWarning';
+
+export {useContainerReveal} from './useContainerReveal';
+export type {
+  UseContainerRevealOptions,
+  UseContainerRevealReturn,
+  ContentRevealOptions,
+} from './useContainerReveal';

package/src/hooks/useClickableContainer.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useClickableContainer',
   displayName: 'useClickableContainer',
@@ -77,7 +77,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',

package/src/hooks/useContainerReveal.doc.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useContainerReveal',
+  displayName: 'useContainerReveal',
+  keywords: ['reveal', 'hover', 'focus', 'container', 'row', 'actions', 'overlay', 'conceal', 'hidden', 'show'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseContainerRevealOptions',
+      description: 'Configuration object for the reveal container. Optional.',
+      required: false,
+    },
+    {
+      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").',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'getContainerProps',
+      type: '() => {className?: string; style?: CSSProperties}',
+      description: 'Spread onto the container whose hover/focus-within drives the reveal.',
+    },
+    {
+      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.',
+    },
+  ],
+  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.',
+    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: '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.' },
+    ],
+  },
+  relatedComponents: ['Thumbnail'],
+  relatedHooks: ['useClickableContainer'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @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.',
+  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.',
+  },
+  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).',
+  },
+  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.',
+    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: '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.' },
+    ],
+  },
+};