@astryxdesign/core 0.7.5 → 0.7.6-canary.bb18c81

package/src/gestures/__tests__/arenaPinchSwipeEdge.test.ts

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file arenaPinchSwipeEdge.test.ts
+ * @input GestureArena with pinches, swipes, edge pans and pans, driven by
+ *   synthetic touches with explicit timestamps
+ * @output Simultaneous recognition (pinch + pan), the first to recognize
+ *   winning without permission, edge pan vs inner pan, swipe vs pan, and a
+ *   delayed touch delivery
+ * @position Unit tests of packages/core/src/gestures/GestureArena.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {UIKIT_PINCH, UIKIT_SWIPE} from '../../motion/uikit/gestures';
+import {GestureRecognizer} from '../GestureRecognizer';
+import {PanGestureRecognizer} from '../PanGestureRecognizer';
+import {PinchGestureRecognizer} from '../PinchGestureRecognizer';
+import {ScreenEdgePanGestureRecognizer} from '../ScreenEdgePanGestureRecognizer';
+import {SwipeGestureRecognizer} from '../SwipeGestureRecognizer';
+import {createHarness, RecordingConsumer} from './harness';
+
+/**
+ * A recognizer that stays possible, even past its finger's lift, until the
+ * test fails it: something another recognizer can wait on.
+ */
+class Held extends GestureRecognizer {
+  private isWaiting = true;
+
+  override isInvolved(): boolean {
+    return super.isInvolved() || this.isWaiting;
+  }
+
+  fail(): void {
+    this.isWaiting = false;
+    this.setState('failed');
+  }
+}
+
+describe('conflict matrix', () => {
+  it('pinch + pan recognize simultaneously when allowed', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    pinch.recognizeSimultaneouslyWith(pan);
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(1).move(80, 120, 16);
+    h.finger(2).move(240, 120, 16);
+    expect(h.log.slice(0, 2)).toEqual(['pinch:began@16', 'pan:began@16']);
+    // Span 100 -> 160, measured against 100 + 8.
+    expect(pinch.scale).toBeCloseTo(160 / 108, 5);
+    // The pan began at the first finger's move, centroid (-10, 10), which
+    // the hysteresis swallows; the second finger's move brought it to (10, 20).
+    expect(pan.translation()).toEqual({x: 20, y: 10});
+  });
+
+  it('pinch vs pan without permission: the first to recognize wins', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(1).move(80, 120, 16);
+    h.finger(2).move(240, 120, 16);
+    expect(h.log.slice(0, 2)).toEqual(['pinch:began@16', 'pan:failed@16']);
+  });
+
+  it('edge pan vs inner pan: in the band the edge pan wins, elsewhere the inner pan runs undelayed', () => {
+    const band = createHarness();
+    const edge = new ScreenEdgePanGestureRecognizer({name: 'edge'});
+    const inner = new PanGestureRecognizer({
+      name: 'inner',
+      direction: 'horizontal',
+    });
+    inner.requireToFail(edge);
+    // A thin edge view: the edge zone, where the pan takes its axis.
+    band.environment.view = {width: edge.edgeRegion, height: 844};
+    band.finger(1).down(8, 300, 0, {recognizers: [inner, edge]});
+    band.finger(1).drag(60, 2, 60, 6);
+    // The edge pan's own hysteresis is 15 px: the second 10 px step.
+    expect(band.log.slice(0, 2)).toEqual(['edge:began@20', 'inner:failed@20']);
+
+    const middle = createHarness();
+    const edge2 = new ScreenEdgePanGestureRecognizer({name: 'edge'});
+    const inner2 = new PanGestureRecognizer({
+      name: 'inner',
+      direction: 'horizontal',
+    });
+    inner2.requireToFail(edge2);
+    middle.finger(1).down(150, 300, 0, {recognizers: [inner2, edge2]});
+    // Failed at touch-down, before any movement: nothing waits on it.
+    expect(middle.log).toEqual(['edge:failed@0']);
+    middle.finger(1).drag(60, 2, 60, 6);
+    expect(middle.log[1]).toBe('inner:began@10');
+  });
+
+  it('swipe vs pan: the pan wins by default, the swipe when the pan requires it to fail', () => {
+    const plain = createHarness();
+    const swipe = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    plain
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe, pan]})
+      .drag(80, 0, 60, 6);
+    expect(plain.log.slice(0, 2)).toEqual(['pan:began@10', 'swipe:failed@10']);
+
+    const ordered = createHarness();
+    const swipe2 = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan2 = new PanGestureRecognizer({name: 'pan'});
+    pan2.requireToFail(swipe2);
+    ordered
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe2, pan2]})
+      .drag(80, 0, 60, 8);
+    expect(ordered.log.slice(0, 2)).toEqual([
+      'swipe:ended@37.5',
+      'pan:failed@37.5',
+    ]);
+
+    const slow = createHarness();
+    const swipe3 = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan3 = new PanGestureRecognizer({name: 'pan'});
+    pan3.requireToFail(swipe3);
+    slow
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe3, pan3]})
+      .drag(30, 0, 300, 3);
+    expect(pan3.state).toBe('possible');
+    slow.advance(500);
+    // The swipe ran out of time; the waiting pan begins with what it has.
+    expect(slow.log.slice(0, 2)).toEqual(['swipe:failed@500', 'pan:began@500']);
+  });
+});
+
+describe('a recognizer waiting on another', () => {
+  it('a swipe holds its recognition past its lift and its deadline (spec:AST-094 FR15)', () => {
+    const h = createHarness();
+    const held = new Held({name: 'held'});
+    const swipe = new SwipeGestureRecognizer({name: 'swipe'});
+    swipe.requireToFail(held);
+    h.finger(1)
+      .down(0, 0, 0, {recognizers: [swipe, held]})
+      .drag(80, 0, 60, 8)
+      .up(70);
+    h.advance(UIKIT_SWIPE.maximumDuration.value + 100);
+    expect(swipe.state).toBe('possible');
+    expect(h.log.some(entry => entry.startsWith('swipe:failed'))).toBe(false);
+    held.fail();
+    expect(h.log).toContain(
+      `swipe:ended@${UIKIT_SWIPE.maximumDuration.value + 100}`,
+    );
+    expect(swipe.recognizedDirection).toBe('right');
+  });
+
+  it('a pinch keeps its start once it passes the hysteresis, so it begins at the scale its fingers show (spec:AST-094 FR15)', () => {
+    const h = createHarness();
+    const held = new Held({name: 'held'});
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    pinch.requireToFail(held);
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, held]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, held]});
+    // Span 100 -> 120 -> 140 -> 160 while the pinch waits.
+    h.finger(2).move(220, 100, 16);
+    h.finger(2).move(240, 100, 32);
+    h.finger(2).move(260, 100, 48);
+    expect(pinch.state).toBe('possible');
+    held.fail();
+    expect(h.log).toContain('pinch:began@48');
+    // Measured against 100 + 8 once, not re-based on every move.
+    const hysteresis = UIKIT_PINCH.hysteresis.value;
+    expect(pinch.scale).toBeCloseTo(160 / (100 + hysteresis), 5);
+  });
+});
+
+describe('delivery to the view', () => {
+  it('holds the began with delaysTouchesBegan until the recognizer fails', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const swipe = new SwipeGestureRecognizer({
+      name: 'swipe',
+      delaysTouchesBegan: true,
+    });
+    h.finger(1).down(0, 0, 0, {recognizers: [swipe], consumer});
+    expect(consumer.events).toEqual([]);
+    h.advance(UIKIT_SWIPE.maximumDuration.value);
+    expect(consumer.events).toEqual(['began:1']);
+  });
+});

package/src/gestures/__tests__/harness.ts

@@ -40,7 +40,13 @@ export interface Harness {
   claims: number[];
   /** Deferred clicks as they resolved. */
   deferredClicks: {id: number; allowed: boolean; time: number}[];
-  environment: {width: number; height: number; rtl: boolean};
+  environment: {
+    width: number;
+    height: number;
+    rtl: boolean;
+    /** The box every recognizer's view measures, when a test sets one. */
+    view?: {left?: number; top?: number; width: number; height: number};
+  };
   finger(id: number): Finger;
   /** Advance the clock and run every timer due by `time`. */
   advance(time: number): void;
@@ -51,7 +57,11 @@ export function createHarness(): Harness {
   const log: string[] = [];
   const claims: number[] = [];
   const deferredClicks: Harness['deferredClicks'] = [];
-  const environment = {width: 390, height: 844, rtl: false};
+  const environment: Harness['environment'] = {
+    width: 390,
+    height: 844,
+    rtl: false,
+  };
   const fingers = new Map<number, Finger>();
   const env: GestureEnvironment = {
     viewportSize: () => ({
@@ -59,6 +69,15 @@ export function createHarness(): Harness {
       height: environment.height,
     }),
     isRtl: () => environment.rtl,
+    viewRect: () =>
+      environment.view == null
+        ? null
+        : {
+            left: environment.view.left ?? 0,
+            top: environment.view.top ?? 0,
+            width: environment.view.width,
+            height: environment.view.height,
+          },
   };
   const arena: GestureArena = new GestureArena({
     clock,

package/src/gestures/types.ts

@@ -46,13 +46,6 @@ export interface NativeScrollProbe {
    * lets the browser pan that axis).
    */
   canScroll(dx: number, dy: number): boolean;
-  /**
-   * How much further (px) the scroller that would move for a finger moving
-   * by (dx, dy) can scroll before it reaches its edge; 0 when none would.
-   * Lets a reader place the point where the content runs out between two
-   * samples instead of at the next one.
-   */
-  distanceToEdge?(dx: number, dy: number): number;
   /** Whether any element under the touch can scroll natively at all. */
   readonly isInsideScroller: boolean;
   /**
@@ -127,6 +120,17 @@ export interface GestureEventContext {
 export interface GestureEnvironment {
   viewportSize(): {readonly width: number; readonly height: number};
   isRtl(view: unknown): boolean;
+  /**
+   * The box of a recognizer's view in viewport coordinates, or null when it
+   * has none to measure. A screen-edge pan reads it to tell a view within
+   * its edge band from any other.
+   */
+  viewRect?(view: unknown): {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
 }
 
 export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
@@ -136,8 +140,18 @@ export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
     }
     return {width: window.innerWidth, height: window.innerHeight};
   },
-  isRtl() {
-    return false;
+  isRtl(view) {
+    if (typeof window === 'undefined' || !(view instanceof Element)) {
+      return false;
+    }
+    return window.getComputedStyle(view).direction === 'rtl';
+  },
+  viewRect(view) {
+    if (typeof Element === 'undefined' || !(view instanceof Element)) {
+      return null;
+    }
+    const {left, top, width, height} = view.getBoundingClientRect();
+    return {left, top, width, height};
   },
 };
 

package/src/hooks/useAdaptivePresentation.ts

@@ -7,7 +7,10 @@
  * @input Uses React's external-store subscription over window.matchMedia
  *   and the touch presentation's compact-touch query
  * @output Resolves popover/bottom-sheet presentation policy
- * @position Internal overlay policy shared across component families
+ * @position Internal overlay policy shared across component families. A
+ *   component that also switches input modes under a finger resolves its
+ *   `presentation` with usePresentation (utils/presentation.ts), whose
+ *   surface is this one's
  */
 
 import {useCallback, useSyncExternalStore} from 'react';

package/src/hooks/useMenuHover.ts

@@ -288,6 +288,20 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     }
   }, [hide, menuRef]);
 
+  // A menu placed in the content can own its own list keys (NavHeadingMenu
+  // runs useListFocus over the same `menuitem`s); a key it consumed must not
+  // move focus a second time here as it bubbles out (APG menu: one item per
+  // arrow press).
+  const handleContentKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.defaultPrevented) {
+        return;
+      }
+      handleListKeyDown(event);
+    },
+    [handleListKeyDown],
+  );
+
   useEffect(() => {
     escapeHandlerRef.current = () => {
       clearTimeouts();
@@ -535,7 +549,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     contentProps: {
       onMouseEnter: handleContentMouseEnter,
       onMouseLeave: handleMouseLeave,
-      onKeyDown: handleListKeyDown,
+      onKeyDown: handleContentKeyDown,
     },
     menuRef,
     focusFirst,

package/src/i18n/generated-locales/en.generated.ts

@@ -233,6 +233,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.tabList.label': 'Tabs',
   '@astryx.table.label': 'Table',
   '@astryx.table.noData': 'No data',
+  '@astryx.table.columnResize.resizeColumn': 'Resize column {label}',
   '@astryx.table.filter.allPlaceholder': 'All',
   '@astryx.table.filter.reset': 'Reset',
   '@astryx.table.filter.apply': 'Apply',
@@ -427,6 +428,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.tableTree.expandRow': 'Expand row',
   '@astryx.tableTree.collapseAllRows': 'Collapse all rows',
   '@astryx.tableTree.expandAllRows': 'Expand all rows',
+  '@astryx.textArea.counter': '{count, number}/{limit, number}',
   '@astryx.textArea.charactersRemaining':
     '{count, number} {count, plural, one {character} other {characters}} remaining',
   '@astryx.textArea.charactersOverLimit':
@@ -449,6 +451,8 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.multiSelector.allSelected': 'All selected',
   '@astryx.multiSelector.selectionCount':
     '{count, number} of {total, number} selected',
+  '@astryx.multiSelector.selectedCount':
+    '{count, plural, one {# selected} other {# selected}}',
   '@astryx.multiSelector.createOption': 'Create "{query}"',
   '@astryx.multiSelector.optionCreated': '{label} created',
   '@astryx.multiSelector.emptySearchResults': 'No results found',

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -239,6 +239,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.tabList.label': '⟦Ţàƀš⟧',
   '@astryx.table.label': '⟦Ţàƀłé⟧',
   '@astryx.table.noData': '⟦Ñó ðàţà⟧',
+  '@astryx.table.columnResize.resizeColumn': '⟦Řéšížé çółúɱñ {label}⟧',
   '@astryx.table.filter.allPlaceholder': '⟦Àłł⟧',
   '@astryx.table.filter.reset': '⟦Řéšéţ⟧',
   '@astryx.table.filter.apply': '⟦Àþþłý⟧',
@@ -436,6 +437,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.tableTree.expandRow': '⟦Éẋþàñð řóŵ⟧',
   '@astryx.tableTree.collapseAllRows': '⟦Çółłàþšé àłł řóŵš⟧',
   '@astryx.tableTree.expandAllRows': '⟦Éẋþàñð àłł řóŵš⟧',
+  '@astryx.textArea.counter': '⟦{count, number}/{limit, number}⟧',
   '@astryx.textArea.charactersRemaining':
     '⟦{count, number} {count, plural, one {character} other {characters}} řéɱàíñíñĝ⟧',
   '@astryx.textArea.charactersOverLimit':
@@ -458,6 +460,8 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.multiSelector.allSelected': '⟦Àłł šéłéçţéð⟧',
   '@astryx.multiSelector.selectionCount':
     '⟦{count, number} óƒ {total, number} šéłéçţéð⟧',
+  '@astryx.multiSelector.selectedCount':
+    '⟦{count, plural, one {# selected} other {# selected}}⟧',
   '@astryx.multiSelector.createOption': '⟦Çřéàţé "{query}"⟧',
   '@astryx.multiSelector.optionCreated': '⟦{label} çřéàţéð⟧',
   '@astryx.multiSelector.emptySearchResults': '⟦Ñó řéšúłţš ƒóúñð⟧',

package/src/motion/README.md

@@ -81,7 +81,10 @@ await handle.finished; // true if it ran to the end, false if interrupted
 - Promotion: every animation the animator creates, and every `set`, gives its
   channels a compositing layer in the same task (inline `will-change`, merged
   with the element's own), cleared 500 ms after the last motion. Mobile Safari
-  needs it to run a curve through a blocked main thread.
+  needs it to run a curve through a blocked main thread. A pseudo-element is
+  promoted through `--astryx-motion-will-change-<pseudo>` on its host; its
+  style opts in with
+  `willChange: 'var(--astryx-motion-will-change-before, auto)'`.
 - `atRest(properties)` resolves once none of them is moving, after the last
   curve ends, whoever started it.
 - `rebase({y: -shift})` moves properties at once, as a layout shift does; a
@@ -121,6 +124,13 @@ await handle.finished; // true if it ran to the end, false if interrupted
 - `animatorFor(element)` returns the one animator for an element, so code
   that animates it from several places (a swipe on x, a removal on y)
   composes in one `translate` track.
+- `createAnimator(dialog, {pseudoElement: '::backdrop'})` drives a
+  pseudo-element; with no inline style to hold it, a static filling animation
+  holds its end value until the next animation replaces it, while the
+  pseudo-element exists. A dialog's `::backdrop` is made again each time the
+  dialog opens, so a presentation `set`s its starting value right after
+  `showModal()`, in the same task (a `set` before it lands on the backdrop
+  the open replaces).
 
 ### How it stays on the compositor
 

package/src/motion/animator.test.ts

@@ -67,18 +67,23 @@ const requestFrame = (callback: () => void) => {
  * properties, so the page is modeled here).
  */
 let stylesheet: Record<string, string> = {};
+/** The stylesheet's values for a pseudo-element of the element. */
+let pseudoStylesheet: Record<string, string> = {};
 
 beforeEach(() => {
   clock = 1000;
   recorded = [];
   frameQueue = [];
   stylesheet = {};
+  pseudoStylesheet = {};
   vi.spyOn(window, 'getComputedStyle').mockImplementation(
-    element =>
+    (element, pseudo) =>
       ({
         getPropertyValue: (property: string) =>
-          (element as HTMLElement).style.getPropertyValue(property) ||
-          (stylesheet[property] ?? ''),
+          pseudo != null
+            ? (pseudoStylesheet[property] ?? '')
+            : (element as HTMLElement).style.getPropertyValue(property) ||
+              (stylesheet[property] ?? ''),
       }) as unknown as CSSStyleDeclaration,
   );
   vi.useFakeTimers();
@@ -799,6 +804,12 @@ describe('animatorFor: one animator per element', () => {
     const b = document.createElement('div');
     expect(animatorFor(a)).toBe(animatorFor(a));
     expect(animatorFor(a)).not.toBe(animatorFor(b));
+    expect(animatorFor(a, {pseudoElement: '::backdrop'})).toBe(
+      animatorFor(a, {pseudoElement: '::backdrop'}),
+    );
+    expect(animatorFor(a, {pseudoElement: '::backdrop'})).not.toBe(
+      animatorFor(a),
+    );
   });
 
   it('composes two callers’ axes in one translate track', async () => {
@@ -902,6 +913,24 @@ describe('promotion: a compositing layer while it moves', () => {
     expect(element.style.willChange).toBe('');
   });
 
+  it('promotes a pseudo-element through a custom property on its host', async () => {
+    const {animator, element} = setup({pseudoElement: '::backdrop'});
+    animator.set({opacity: 0});
+    // set() promotes a pseudo-element too.
+    expect(
+      element.style.getPropertyValue('--astryx-motion-will-change-backdrop'),
+    ).toBe('opacity');
+    animator.animate({opacity: 1}, {spring: springs.alertPresent});
+    expect(
+      element.style.getPropertyValue('--astryx-motion-will-change-backdrop'),
+    ).toBe('opacity');
+    expect(element.style.willChange).toBe('');
+    await advance(5000 + PROMOTION_LINGER_MS);
+    expect(
+      element.style.getPropertyValue('--astryx-motion-will-change-backdrop'),
+    ).toBe('');
+  });
+
   it('ends promotion on the element it leaves', () => {
     const {animator, element} = setup();
     animator.animate({x: 50}, {spring: springs.settle});
@@ -1937,6 +1966,75 @@ describe('Reduced Motion (design:reduced-motion)', () => {
     expect(element.style.translate).toBe('100px 0px');
   });
 
+  it("a pseudo-element's dip borrows its own opacity and hands it back without touching the host", async () => {
+    for (const role of [undefined, 'exit'] as const) {
+      const {animator, element} = setup({
+        reduced: true,
+        coarse: true,
+        pseudoElement: '::before',
+      });
+      element.style.opacity = '0.5'; // the host's own, untouched
+      pseudoStylesheet = {opacity: '0.3'};
+      animator.animate(
+        {x: 100},
+        {spring: springs.navigationPush},
+        role == null ? {} : {crossfadeAs: role},
+      );
+      await commitFrame(clock);
+      const [fadeLayer] = live('opacity');
+      const values = fadeLayer.keyframes.map(k => Number(k.opacity));
+      expect(Math.max(...values)).toBeCloseTo(0.3, 9);
+      await advance(fade * 2 + END_HOLD_MS + 1);
+      expect(animator.get('x')).toBe(100);
+      // The pseudo-element's stylesheet owns its opacity again; the host
+      // keeps its own.
+      expect(live('opacity')).toEqual([]);
+      expect(element.style.opacity).toBe('0.5');
+    }
+  });
+
+  it("a pseudo-element's identity hold follows a node replacement", () => {
+    const {animator, element} = setup({pseudoElement: '::backdrop'});
+    pseudoStylesheet = {opacity: '0'};
+    animator.set({opacity: 1});
+    animator.attach(null);
+    const next = document.createElement('div');
+    document.body.append(next);
+    animator.attach(next);
+    const held = live('opacity').filter(
+      animation => animation.element === next,
+    );
+    expect(held).toHaveLength(1);
+    expect(Number(held[0].keyframes.at(-1)!.opacity)).toBe(1);
+    expect(live('opacity').some(a => a.element === element)).toBe(false);
+    next.remove();
+  });
+
+  it('a pseudo-element shown over a hiding stylesheet keeps its own opacity through a move', async () => {
+    for (const role of [undefined, 'entrance'] as const) {
+      const {animator} = setup({
+        reduced: true,
+        coarse: true,
+        pseudoElement: '::backdrop',
+      });
+      pseudoStylesheet = {opacity: '0'};
+      animator.set({opacity: 1});
+      animator.animate(
+        {x: 100},
+        {spring: springs.navigationPush},
+        role == null ? {} : {crossfadeAs: role},
+      );
+      await commitFrame(clock);
+      for (let step = 0; step < 8; step++) {
+        await advance(fade / 4);
+      }
+      expect(animator.get('x')).toBe(100);
+      expect(animator.get('opacity')).toBe(1);
+      const [held] = live('opacity');
+      expect(Number(held.keyframes.at(-1)?.opacity)).toBe(1);
+    }
+  });
+
   it('a move dips: fades out, lands while transparent, fades back in', async () => {
     const {animator, element} = reduced();
     animator.animate({x: 100}, {spring: springs.navigationPush});
@@ -2555,6 +2653,56 @@ describe('decay: momentum curves (a coast)', () => {
   });
 });
 
+describe('pseudoElement: a dialog\u2019s ::backdrop', () => {
+  it('targets the pseudo-element, writes no inline style and holds the end state', async () => {
+    const {animator, element} = setup({pseudoElement: '::backdrop'});
+    animator.set({opacity: 0});
+    const [held] = live('opacity');
+    expect(held.options).toMatchObject({
+      fill: 'both',
+      pseudoElement: '::backdrop',
+    });
+    expect(held.keyframes.map(k => k.opacity)).toEqual(['0', '0']);
+    expect(element.style.opacity).toBe('');
+
+    animator.animate({opacity: 1}, {spring: springs.alertPresent});
+    // The new animation exists before the hold goes: no frame in between.
+    expect(held.cancelled).toBe(true);
+    const [fade] = live('opacity');
+    expect(fade.options).toMatchObject({
+      fill: 'both',
+      pseudoElement: '::backdrop',
+    });
+    expect(fade.keyframes[fade.keyframes.length - 1].opacity).toBe('1');
+    expect(element.style.opacity).toBe('');
+    await advance(Number(fade.options.duration) + 1000);
+    // Past the curve's end, a static animation holds the end value.
+    expect(fade.cancelled).toBe(true);
+    const [rest] = live('opacity');
+    expect(rest.options).toMatchObject({
+      fill: 'both',
+      pseudoElement: '::backdrop',
+    });
+    expect(rest.keyframes.map(k => k.opacity)).toEqual(['1', '1']);
+    expect(animator.get('opacity')).toBe(1);
+  });
+
+  it('an exit holds 0 until the next animation replaces it', async () => {
+    const {animator} = setup({
+      pseudoElement: '::backdrop',
+      initial: {opacity: 1},
+    });
+    animator.animate({opacity: 0}, {spring: springs.alertDismiss});
+    const [fade] = live('opacity');
+    await advance(Number(fade.options.duration) + 1000);
+    const [rest] = live('opacity');
+    expect(rest.keyframes.map(k => k.opacity)).toEqual(['0', '0']);
+    animator.animate({opacity: 1}, {spring: springs.alertPresent});
+    expect(rest.cancelled).toBe(true);
+    expect(live('opacity')).toHaveLength(1);
+  });
+});
+
 describe('attach', () => {
   it('keeps state without an element and resumes the curve on attach', () => {
     const animator = createAnimator(null, {