Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(hooks): useContainerReveal — remove exit flicker on default reveal (#4630)

Cindy Zhangc5281ccac120
diff --git a/.changeset/fix-container-reveal-exit-flicker.md b/.changeset/fix-container-reveal-exit-flicker.md
new file mode 100644
index 0000000000..7bfef9a0fb
--- /dev/null
+++ b/.changeset/fix-container-reveal-exit-flicker.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] useContainerReveal: eliminate the exit flicker on the default (non-layout-preserved) reveal. Hidden content flips `position: static -> absolute` discretely, which previously snapped it out of layout flow at full opacity before the fade could run. The flip now participates in the transition with `transition-behavior: allow-discrete` and a state-conditional delay, so it stays in flow until the opacity fade finishes on exit while remaining immediate on entry. Content stays in the accessibility tree and tab order throughout.
+
+@cixzhang
diff --git a/packages/core/src/hooks/containerReveal.pool.stylex.ts b/packages/core/src/hooks/containerReveal.pool.stylex.ts
index 70ec1c13b6..936705c60d 100644
--- a/packages/core/src/hooks/containerReveal.pool.stylex.ts
+++ b/packages/core/src/hooks/containerReveal.pool.stylex.ts
@@ -6,23 +6,21 @@
* @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.
+ * @position Internal to useContainerReveal. GENERATED by
+ * scripts/gen-container-reveal-pool.mjs — do not edit by hand.
*
- * WHY A POOL OF LITERAL BLOCKS: `stylex.when.ancestor(':hover', marker)` is
- * resolved by the StyleX compiler, which welds the marker's class into the
- * emitted selector (`.marker:hover *`). A marker and the styles referencing it
- * are therefore inseparable at build time — the marker cannot be passed as a
- * runtime argument, so the blocks cannot be produced by a loop or a helper and
- * must be written out literally per marker. A single shared marker would leak
- * hover/focus across NESTED reveal containers (an ancestor container's :hover
- * matches a descendant container's revealed content), so useContainerReveal
- * hands each concurrently mounted container a distinct marker from this pool
- * (see the free-list there).
+ * 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.
*
- * The reveal recipe hides content with `position: absolute` (removed from
- * layout flow, so it reserves no space) plus `opacity: 0`. Both keep the
- * content in the accessibility tree and tab order — unlike display/visibility
- * — so it stays reachable by keyboard and assistive tech while hidden.
+ * 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';
@@ -34,14 +32,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -104,14 +114,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -174,14 +196,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -244,14 +278,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -314,14 +360,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -384,14 +442,26 @@ 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.
+ // 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',
+ transitionProperty: 'opacity, position',
transitionDuration: {
- default: durationVars['--duration-fast'],
- '@media (prefers-reduced-motion: reduce)': '0s',
+ 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},
@@ -450,15 +520,52 @@ const s5 = stylex.create({
},
});
-// The compiled StyleX objects carry `when.ancestor` conditionals the public
-// `StyleXStyles` type does not model, so the slot shape is inferred.
+// 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},
+ {
+ 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];
diff --git a/packages/core/src/hooks/useContainerReveal.doc.mjs b/packages/core/src/hooks/useContainerReveal.doc.mjs
index 6092c890cf..58e9504d8f 100644
--- a/packages/core/src/hooks/useContainerReveal.doc.mjs
+++ b/packages/core/src/hooks/useContainerReveal.doc.mjs
@@ -34,7 +34,7 @@ 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 with a clip recipe (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 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).' },
@@ -52,7 +52,7 @@ 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 via clip (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 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.',
@@ -63,7 +63,7 @@ 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 via clip (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 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).' },
diff --git a/packages/core/src/hooks/useContainerReveal.ts b/packages/core/src/hooks/useContainerReveal.ts
index e410448812..2df4fbe436 100644
--- a/packages/core/src/hooks/useContainerReveal.ts
+++ b/packages/core/src/hooks/useContainerReveal.ts
@@ -16,7 +16,7 @@
* marker + matching reveal styles from a pre-compiled pool.
*
* ACCESSIBILITY (WCAG 2.2 by construction):
- * - Revealed content is visually hidden at rest via the clip recipe, so it
+ * - 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.
* - Touch: always visible on coarse pointers; never gated behind hover.
@@ -102,9 +102,10 @@ export interface UseContainerRevealReturn {
/** Spread onto the container whose hover/focus-within drives the reveal. */
getContainerProps: () => {className?: string; style?: CSSProperties};
/** Spread onto each revealed / concealed child. */
- getContentRevealProps: (
- options?: ContentRevealOptions,
- ) => {className?: string; style?: CSSProperties};
+ getContentRevealProps: (options?: ContentRevealOptions) => {
+ className?: string;
+ style?: CSSProperties;
+ };
}
const EMPTY = Object.freeze({});
diff --git a/scripts/gen-container-reveal-pool.mjs b/scripts/gen-container-reveal-pool.mjs
index 0e66f2f766..b101bcdb92 100644
--- a/scripts/gen-container-reveal-pool.mjs
+++ b/scripts/gen-container-reveal-pool.mjs
@@ -16,7 +16,7 @@ import {writeFileSync} from 'node:fs';
import {fileURLToPath} from 'node:url';
import {dirname, join} from 'node:path';
-const POOL_SIZE = 8;
+const POOL_SIZE = 6;
const OUT = join(
dirname(fileURLToPath(import.meta.url)),
'../packages/core/src/hooks/containerReveal.pool.stylex.ts',
@@ -38,27 +38,57 @@ function toggled(m, hidden, shown) {
}`;
}
+// `position` is discrete, so it cannot tween. To avoid an exit flicker — where
+// `static -> absolute` snaps at full opacity and yanks the element out of flow
+// before it can fade — the flip participates in the transition with
+// `allow-discrete`, and its `transition-delay` is state-conditional: 0 on entry
+// (destination = shown) so it enters flow immediately and fades in, but the
+// fade duration on exit (destination = rest) so it stays in flow until the
+// opacity fade finishes, then snaps out. Under reduced motion both collapse to
+// 0s so nothing lingers visible-but-empty.
+function positionDelay(m) {
+ return `{
+ default: '0s, ' + durationVars['--duration-fast'],
+ '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+ [stylex.when.ancestor(':hover', ${m})]: {'@media (hover: hover)': '0s, 0s'},
+ [stylex.when.ancestor(':focus-within', ${m})]: '0s, 0s',
+ '@media (any-pointer: coarse)': '0s, 0s',
+ }`;
+}
+
function block(i) {
const m = `m${i}`;
return `
export const ${m} = stylex.defineMarker();
const s${i} = 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: {
- ${transition}
+ transitionProperty: 'opacity, position',
+ transitionDuration: {
+ default: durationVars['--duration-fast'] + ', 0s',
+ '@media (prefers-reduced-motion: reduce)': '0s, 0s',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ transitionBehavior: 'allow-discrete',
+ transitionDelay: ${positionDelay(m)},
opacity: ${toggled(m, '0', '1')},
position: ${toggled(m, "'absolute'", "'static'")},
- width: ${toggled(m, "'1px'", "'auto'")},
- height: ${toggled(m, "'1px'", "'auto'")},
- margin: ${toggled(m, "'-1px'", "'0'")},
- overflow: ${toggled(m, "'hidden'", "'visible'")},
- clip: ${toggled(m, "'rect(0, 0, 0, 0)'", "'auto'")},
- whiteSpace: ${toggled(m, "'nowrap'", "'normal'")},
},
+ // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+ // content that is already positioned (e.g. an absolute overlay).
revealLayoutPreserved: {
${transition}
opacity: ${toggled(m, '0', '1')},
- pointerEvents: ${toggled(m, "'none'", "'auto'")},
},
+ // 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: {
${transition}
opacity: {
@@ -118,12 +148,18 @@ export const POOL = [
${Array.from(
{length: POOL_SIZE},
(_, i) =>
- ` {marker: m${i}, reveal: s${i}.reveal, revealLayoutPreserved: s${i}.revealLayoutPreserved, conceal: s${i}.conceal, concealLayoutPreserved: s${i}.concealLayoutPreserved},`,
+ ` {
+ marker: m${i},
+ reveal: s${i}.reveal,
+ revealLayoutPreserved: s${i}.revealLayoutPreserved,
+ conceal: s${i}.conceal,
+ concealLayoutPreserved: s${i}.concealLayoutPreserved,
+ },`,
).join('\n')}
] as const;
export type RevealSlot = (typeof POOL)[number];
`;
-writeFileSync(OUT, header + '\n' + blocks + footer);
+writeFileSync(OUT, header + blocks + footer);
console.log(`Wrote ${OUT}`);