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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/docs/specs/components/Popover/Popover.spec.md b/docs/specs/components/Popover/Popover.spec.mdindex 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 ananchored, 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 contextdiff --git a/packages/core/src/motion/opacityFloor.ts b/packages/core/src/motion/opacityFloor.tsnew file mode 100644index 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;