Skip to content

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

TypeScript

fix(Popover): the touch growth shows its content from its first frame (#10757)

Christopher Chedeaub6509b17937e
diff --git a/.changeset/popover-growth-first-frames.md b/.changeset/popover-growth-first-frames.md
new file mode 100644
index 0000000000..e94271eebb
--- /dev/null
+++ b/.changeset/popover-growth-first-frames.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Under a finger, Popover's growth shows its content from its first frame. The growth starts at opacity 0.001 rather than 0: Chromium skips drawing a layer at exactly 0, so the first frames of a growth from 0 showed the popover without its content. No 8-bit pixel differs from transparent at 0.001.
+
+@vjeux
diff --git a/docs/specs/components/Popover/Popover.spec.md b/docs/specs/components/Popover/Popover.spec.md
index 1199c8259e..88b0f72f3a 100644
--- a/docs/specs/components/Popover/Popover.spec.md
+++ b/docs/specs/components/Popover/Popover.spec.md
@@ -17,6 +17,7 @@ verified_by:
packages/core/src/Popover/usePopover.doc.mjs,
packages/core/src/hooks/useFocusTrap.test.tsx,
packages/core/src/Popover/PopoverPresentation.test.tsx,
+ packages/core/src/Popover/__tests__/PopoverTouchMotion.interaction.browser.spec.ts,
packages/cli/foundation/discovery/theming-targets.mjs,
packages/cli/foundation/discovery/theming-targets.test.mjs,
scripts/check-knowledge.mjs,
@@ -267,6 +268,10 @@ table owns their semantic effect.
touch growth and shrink do no Layout or Paint per frame. Known platform cost:
in Chromium, a page with its own `requestAnimationFrame` loop makes an
anchored, animating layer lay out and paint every frame.
+- **PR5 — The touch growth's first frames.** Under a finger, the growth starts
+ at opacity 0.001 rather than 0, since Chromium skips drawing a layer at
+ exactly 0. The first frame then shows its content, and no 8-bit pixel differs
+ from transparent.
## Accessibility contract
@@ -373,6 +378,7 @@ consumers that need distinct theme reachability provide and document an owned
| FR8 | `Popover.test.tsx` surface-padding suite | Default rung, `0`, an explicit rung, a direct hook composition with and without a rung | A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. | `audit:Popover/theming` |
| FR9 | `spec:AST-094` verification for FR31 and FR35 | Under a finger: open, close, a touch during growth; a mouse | A Popover that does not grow from and shrink into its trigger, a changed dismissal, or a changed mouse path fails. | `audit:Popover/behavior` |
| PR4 | `spec:AST-094` verification for FR5 | The touch growth and shrink in a Chromium trace, on a page with no other frame work | A Layout or a Paint during either motion on such a page | `audit:Popover/resources` |
+| PR5 | `PopoverTouchMotion.interaction.browser.spec.ts` "the growth shows its content from its first frames", from the compositor's record of each frame it presents (Chromium) | A tap that opens the popover; a tap outside while it grows | A growth whose first opacity keyframe is 0 presents a frame without the popover's content among its first five | `audit:Popover/resources` |
| FR5 | `Popover.test.tsx` scheduling and observer-lifecycle suites | Closed, opened, repeated signals, cleanup | Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. | `audit:Popover/resources` |
| FR6, FR7 and theming anatomy | `Popover.test.tsx`, `Popover.doc.mjs`, `usePopover.doc.mjs`, `astryx theme targets Popover --json`, and `scripts/check-knowledge.mjs` | One real surface with canonical `popover` plus composed-component refinements | A fake anatomy part, missing canonical output, or an active target without a real owner fails review or validation. | `audit:Popover/theming` |
| AR5 | `Popover.stories.tsx` manual-AT fixture and PR #5373 test record | Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result | A fixture without recorded AT/browser observations cannot be cited as announcement proof. | `audit:Popover/at-evidence` |
diff --git a/packages/core/src/Popover/__tests__/PopoverTouchMotion.interaction.browser.spec.ts b/packages/core/src/Popover/__tests__/PopoverTouchMotion.interaction.browser.spec.ts
index 03b1e016a1..055d0351ad 100644
--- a/packages/core/src/Popover/__tests__/PopoverTouchMotion.interaction.browser.spec.ts
+++ b/packages/core/src/Popover/__tests__/PopoverTouchMotion.interaction.browser.spec.ts
@@ -903,6 +903,98 @@ test('the task that opens it lays out no more than a mouse opening does: the pre
}
});
+/**
+ * The frames the compositor presents while `body` runs and for `ms` after it,
+ * in order. Each says whether the frame was presented with content missing: a
+ * tile not yet rasterized. It reads the compositor's own record of each frame
+ * (`PipelineReporter`), so it is Chromium-only.
+ */
+async function presentedFrames(
+ page: Page,
+ body: () => Promise<unknown>,
+ ms: number,
+): Promise<{sequence: number; missingContent: boolean}[]> {
+ const cdp = await page.context().newCDPSession(page);
+ const events: {name: string; ph?: string; args?: Record<string, unknown>}[] =
+ [];
+ cdp.on('Tracing.dataCollected', ({value}) => {
+ events.push(...(value as unknown as typeof events));
+ });
+ const complete = new Promise<void>(resolve =>
+ cdp.once('Tracing.tracingComplete', () => resolve()),
+ );
+ await cdp.send('Tracing.start', {
+ transferMode: 'ReportEvents',
+ traceConfig: {
+ includedCategories: [
+ 'cc',
+ 'benchmark',
+ 'viz',
+ 'disabled-by-default-devtools.timeline.frame',
+ ],
+ excludedCategories: ['*'],
+ },
+ });
+ await body();
+ await page.waitForTimeout(ms);
+ await cdp.send('Tracing.end');
+ await complete;
+ await cdp.detach();
+ const frames = new Map<number, boolean>();
+ for (const event of events) {
+ const report = (
+ event.args as {frame_reporter?: Record<string, unknown>} | undefined
+ )?.frame_reporter;
+ if (
+ event.name !== 'PipelineReporter' ||
+ event.ph === 'e' ||
+ report == null ||
+ !String(report.state).includes('PRESENTED')
+ ) {
+ continue;
+ }
+ frames.set(
+ Number(report.frame_sequence),
+ report.has_missing_content === true,
+ );
+ }
+ return [...frames.entries()]
+ .sort(([a], [b]) => a - b)
+ .map(([sequence, missingContent]) => ({sequence, missingContent}));
+}
+
+for (const tapOutside of [false, true]) {
+ test(`the growth shows its content from its first frames${
+ tapOutside ? ', with a tap outside while it grows' : ''
+ }`, async ({page, browserName}) => {
+ test.skip(
+ browserName !== 'chromium',
+ 'the compositor frame record is Chromium-only',
+ );
+ const story = await openDefault(page);
+ const outside = outsidePoint(page);
+ const frames = await presentedFrames(
+ page,
+ async () => {
+ await story.driver.tap(story.center);
+ if (tapOutside) {
+ await story.driver.tap(outside);
+ }
+ },
+ 700,
+ );
+ // Chromium does not draw a layer at opacity 0. A growth that started
+ // there showed its first frames without its content.
+ const first = frames.slice(0, 5);
+ expect(first, 'frames presented').toHaveLength(5);
+ expect(
+ first.filter(frame => frame.missingContent).map(frame => frame.sequence),
+ 'first frames presented with content missing',
+ ).toEqual([]);
+ await expect(story.trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+}
+
test('a style read after the opening tap finds no CSS entrance running on the layer', async ({
page,
}) => {
diff --git a/packages/core/src/Popover/popoverSurfaceMotion.test.ts b/packages/core/src/Popover/popoverSurfaceMotion.test.ts
index 7727160f21..836a87c5e2 100644
--- a/packages/core/src/Popover/popoverSurfaceMotion.test.ts
+++ b/packages/core/src/Popover/popoverSurfaceMotion.test.ts
@@ -16,6 +16,7 @@
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {isInHeldLayer, isInputShield} from '../Layer/inputHold';
import {cubicBezier} from '../motion/bezier';
+import {ENTRANCE_OPACITY_FLOOR} from '../motion/opacityFloor';
import {parseCssEasing, parseMotionRoleValue} from '../motion/roles';
import {popover, timing} from '../motion/uikit';
import {findPopoverExitCopy} from '../privateAttributes/popoverExit.stylex';
@@ -370,8 +371,11 @@ describe('createPopoverSurfaceMotion', () => {
expect(endMs).toBeLessThanOrEqual(ENTRANCE.ms + 1);
expect(endMs).toBeGreaterThan(ENTRANCE.ms * 0.8);
expect(peak).toBeLessThanOrEqual(1);
+ // It starts at the floor, not at 0: Chromium draws the start frame.
const [opacityAnimation] = live('opacity');
- expect(Number(opacityAnimation.keyframes[0].opacity)).toBe(0);
+ expect(Number(opacityAnimation.keyframes[0].opacity)).toBe(
+ ENTRANCE_OPACITY_FLOOR,
+ );
expect(Number(opacityAnimation.keyframes.at(-1)!.opacity)).toBe(1);
});
diff --git a/packages/core/src/Popover/popoverSurfaceMotion.ts b/packages/core/src/Popover/popoverSurfaceMotion.ts
index a274885fdf..f254ce0749 100644
--- a/packages/core/src/Popover/popoverSurfaceMotion.ts
+++ b/packages/core/src/Popover/popoverSurfaceMotion.ts
@@ -27,6 +27,7 @@ import {
type MotionHandle,
} from '../motion/animator';
import {holdInput} from '../Layer/inputHold';
+import {ENTRANCE_OPACITY_FLOOR} from '../motion/opacityFloor';
import {mapProgress, mapRange} from '../motion/progress';
import {
easedProgress,
@@ -62,18 +63,20 @@ function surfaceCurves(
to: SurfaceState,
axis: 'x' | 'y',
progress: MotionCurve,
+ opacityFloor = 0,
): Record<'scaleX' | 'scaleY' | 'opacity', MotionCurve> {
// Unclamped, so an easing that overshoots carries the channels with it.
const lerp = (a: number, b: number) =>
mapRange([0, 1], [a, b], {clamp: false});
const scale = lerp(from.scale, to.scale);
const length = lerp(from.length, to.length);
+ const opacity = lerp(from.opacity, to.opacity);
const across = mapProgress(progress, scale);
const along = mapProgress(progress, p => scale(p) * length(p));
return {
scaleX: axis === 'x' ? along : across,
scaleY: axis === 'y' ? along : across,
- opacity: mapProgress(progress, lerp(from.opacity, to.opacity)),
+ opacity: mapProgress(progress, p => Math.max(opacityFloor, opacity(p))),
};
}
@@ -308,8 +311,17 @@ export function createPopoverSurfaceMotion(
'transform-origin',
`${next.originX}px ${next.originY}px`,
);
+ // The growth fades in from the floor, so Chromium draws its first frame.
+ // The start values keep opacity 0. Reduce Motion replaces this curve with a
+ // cross-fade, which then starts from transparent.
const handle = animator.play(
- surfaceCurves(start, PRESENTED, next.axis, timing),
+ surfaceCurves(
+ start,
+ PRESENTED,
+ next.axis,
+ timing,
+ ENTRANCE_OPACITY_FLOOR,
+ ),
);
presentHandle = handle;
endHold();
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index ec824d0b31..f094c86363 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -48,6 +48,7 @@ roles through `resolveMotion`.
| `progress.ts` | A spring's progress, one curve mapped from another (companions, clamped ranges), the velocity that continues a motion. |
| `presentation.ts` | Where each moving element is drawn relative to where the engine hit-tests it, reported by the animator while translate runs; read by the gesture host at touch-down. |
| `reducedMotionPlan.ts` | The animator's Reduce Motion planner: what one call becomes, a cross-fade whose travel lands while transparent or at once. |
+| `opacityFloor.ts` | The lowest opacity a compositor entrance fades in from: Chromium skips drawing a layer at exactly 0 as its animation starts. |
| `__tests__/animator.interaction.browser.spec.ts` | Browser proofs on the interaction harness (Chromium and WebKit): busy main thread, end state through a block, no Layout / Paint, seeked curves, a dialog's backdrop. |
Component-specific values (a sheet's detents, a switch's geometry, a context
diff --git a/packages/core/src/motion/opacityFloor.ts b/packages/core/src/motion/opacityFloor.ts
new file mode 100644
index 0000000000..ffe73aed7a
--- /dev/null
+++ b/packages/core/src/motion/opacityFloor.ts
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file opacityFloor.ts
+ * @input None
+ * @output Exports `ENTRANCE_OPACITY_FLOOR`
+ * @position A motion constant for entrances that fade in from transparent as
+ * Web Animations
+ *
+ * Chromium skips drawing a layer at exactly opacity 0 as its animation starts.
+ * It rasterizes the layer again once the fade makes it visible, so the first
+ * frames show the layer without its content. An entrance that fades in from
+ * this floor draws its start frame. The floor is a quarter of one step of an
+ * 8-bit channel, so it changes no pixel.
+ */
+
+/** The lowest opacity a compositor entrance fades in from. */
+export const ENTRANCE_OPACITY_FLOOR = 0.001;