@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/src/internal/SheetConfirmation.tsx

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file SheetConfirmation.tsx
+ * @input Dialog, Layout, Heading, Text, Button; caller-owned copy
+ * @output SheetConfirmation — the confirmation a touch sheet opens over
+ *   itself for Clear all and for discarding a changed draft
+ * @position Core-internal, shared by the Tokenizer sheet and the PowerSearch
+ *   sheets; not a public export
+ *
+ * AlertDialog fixes its purpose to form and its safe action to ghost. A touch
+ * sheet's confirmation allows scrim dismissal. Its two full-width large
+ * actions are stacked and separated: the destructive action first in reading
+ * order, the safe action focused first. The alert-dialog theme target stays.
+ */
+
+import {useId} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Button} from '../Button/Button';
+import {Dialog} from '../Dialog/Dialog';
+import {Heading} from '../Heading/Heading';
+import {Layout} from '../Layout/Layout';
+import {LayoutContent} from '../Layout/LayoutContent';
+import {LayoutFooter} from '../Layout/LayoutFooter';
+import {Stack} from '../Stack/Stack';
+import {Text} from '../Text/Text';
+import {themeProps} from '../utils/themeProps';
+
+export interface SheetConfirmationProps {
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+  title: string;
+  description: string;
+  cancelLabel: string;
+  actionLabel: string;
+  onAction: () => void;
+}
+
+const styles = stylex.create({
+  action: {width: '100%'},
+});
+
+export function SheetConfirmation({
+  isOpen,
+  onOpenChange,
+  title,
+  description,
+  cancelLabel,
+  actionLabel,
+  onAction,
+}: SheetConfirmationProps) {
+  const titleId = useId();
+  const descriptionId = useId();
+  return (
+    <Dialog
+      {...themeProps('alert-dialog')}
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      purpose="info"
+      role="alertdialog"
+      aria-labelledby={titleId}
+      aria-describedby={descriptionId}
+      width={400}>
+      <Layout
+        content={
+          <LayoutContent>
+            <Heading level={2} id={titleId}>
+              {title}
+            </Heading>
+            <Text type="body" color="secondary" id={descriptionId}>
+              {description}
+            </Text>
+          </LayoutContent>
+        }
+        footer={
+          <LayoutFooter>
+            <Stack direction="vertical" gap={4} hAlign="stretch">
+              <Button
+                label={actionLabel}
+                variant="destructive"
+                size="lg"
+                onClick={onAction}
+                xstyle={styles.action}
+              />
+              <Button
+                label={cancelLabel}
+                variant="secondary"
+                size="lg"
+                onClick={() => onOpenChange(false)}
+                data-autofocus
+                xstyle={styles.action}
+              />
+            </Stack>
+          </LayoutFooter>
+        }
+      />
+    </Dialog>
+  );
+}

package/src/internal/indicatorPress.stylex.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file indicatorPress.stylex.ts
+ * @input Uses StyleX
+ * @output Exports `indicatorPressScope`, the marker of a first-party
+ *   indicator that paints its own press
+ * @position Internal entry for Astryx's own replacement indicators;
+ *   CheckboxInput reads it
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Marks a first-party replacement indicator that paints its own press, for
+ * a shape that CheckboxInput's rounded-square press layer would tint past,
+ * such as a circle. CheckboxInput leaves that layer off over an indicator
+ * with this marker.
+ *
+ * @internal Not public API: the touch press reaches the indicator through a
+ * private property.
+ */
+export const indicatorPressScope: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/internal/sheetDraft.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file sheetDraft.ts
+ * @input A sheet's selection at open, its draft, and the last edit made
+ * @output SheetDraftChange, hasSameSelection, nameSheetDraftChange — the
+ *   rules a touch sheet's Save and dismissal share
+ * @position Core-internal, shared by the Tokenizer sheet and the Lab sheets
+ *   through `internal/touch-sheet`; not a public export
+ *
+ * A touch sheet edits a draft and reports it once, on Save, with one change:
+ * the last edit that still holds, else the nearest net add or remove. A
+ * dismissal asks before discarding only while the draft differs from the
+ * selection at open, as a set: a row unchecked and checked again is no change.
+ */
+
+interface SheetDraftItem {
+  id: string | number;
+}
+
+/** An edit of a sheet's draft, and the shape Save reports. */
+export type SheetDraftChange<T> = {
+  item: T;
+  type: 'add' | 'create' | 'remove';
+};
+
+/** Whether two selections hold the same items, in any order. */
+export function hasSameSelection<T extends SheetDraftItem>(
+  a: ReadonlyArray<T>,
+  b: ReadonlyArray<T>,
+): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  const ids = new Set(a.map(item => item.id));
+  return b.every(item => ids.has(item.id));
+}
+
+/**
+ * The change Save reports for a draft that differs from the selection at
+ * open, or `null` when nothing differs. The last edit names it when it still
+ * holds: its item is in the draft and was not selected at open, or was
+ * selected at open and is gone. Otherwise, after a removal, a `remove` names
+ * an item that is gone; otherwise an `add` (`create` when the last edit
+ * created that item) names an item that is new; otherwise a `remove` names
+ * an item that is gone.
+ */
+export function nameSheetDraftChange<T extends SheetDraftItem>(
+  valueAtOpen: ReadonlyArray<T>,
+  draftValue: ReadonlyArray<T>,
+  lastDraftChange: SheetDraftChange<T> | null,
+): SheetDraftChange<T> | null {
+  const wasSelected = (id: T['id']) => valueAtOpen.some(item => item.id === id);
+  const isSelected = (id: T['id']) => draftValue.some(item => item.id === id);
+  const added = draftValue.find(item => !wasSelected(item.id));
+  const removed = valueAtOpen.find(item => !isSelected(item.id));
+  const lastChangeIsNet =
+    lastDraftChange != null &&
+    (lastDraftChange.type === 'remove'
+      ? wasSelected(lastDraftChange.item.id) &&
+        !isSelected(lastDraftChange.item.id)
+      : isSelected(lastDraftChange.item.id) &&
+        !wasSelected(lastDraftChange.item.id));
+  if (lastChangeIsNet) {
+    return lastDraftChange;
+  }
+  if (lastDraftChange?.type === 'remove' && removed != null) {
+    return {item: removed, type: 'remove'};
+  }
+  if (added != null) {
+    const type: SheetDraftChange<T>['type'] =
+      lastDraftChange?.item.id === added.id && lastDraftChange.type === 'create'
+        ? 'create'
+        : 'add';
+    return {item: added, type};
+  }
+  if (removed != null) {
+    return {item: removed, type: 'remove'};
+  }
+  return null;
+}

package/src/internal/touch-sheet.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file touch-sheet.ts
+ * @input The touch sheets' shared confirmation, search-drag dismissal and
+ *   draft rules
+ * @output `@astryxdesign/core/internal/touch-sheet`: SheetConfirmation,
+ *   useDismissSearchOnTouchDrag, hasSameSelection and nameSheetDraftChange,
+ *   re-exported by name for Lab's sheets
+ * @position An internal entry reserved for Astryx's own packages:
+ *   undocumented, outside the public API and its compatibility promise,
+ *   versioned in lockstep with Core, and allowed only in Core and Lab by the
+ *   `@astryx/no-core-internal-import` lint rule. Core components import the
+ *   same modules by relative path. Named re-exports only.
+ *
+ * SYNC: When modified, update scripts/sync-exports.js.
+ */
+export {SheetConfirmation} from './SheetConfirmation';
+export type {SheetConfirmationProps} from './SheetConfirmation';
+export {useDismissSearchOnTouchDrag} from './useDismissSearchOnTouchDrag';
+export {hasSameSelection, nameSheetDraftChange} from './sheetDraft';
+export type {SheetDraftChange} from './sheetDraft';

package/src/internal/useDismissSearchOnTouchDrag.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDismissSearchOnTouchDrag.ts
+ * @input Caller-owned search inputs, a focus target, and touch events from a
+ *   separate results list
+ * @output useDismissSearchOnTouchDrag — touch handlers for the results list
+ * @position Core-internal, shared by the touch sheets; not a public export
+ *
+ * A direct vertical touch drag on the results moves focus off a focused
+ * search input. The on-screen keyboard then leaves and the rows come into
+ * view; the query stays. Focus goes to the caller's target (the sheet's
+ * panel), never to the page body behind an open modal. Scroll events are not
+ * observed: filtering can clamp scrollTop and fire scroll while someone is
+ * typing. Small moves, taps and multi-touch gestures leave focus alone.
+ */
+
+import {useRef, type TouchEvent} from 'react';
+
+const DRAG_THRESHOLD_PX = 8;
+
+type SearchInput = HTMLInputElement | null | undefined;
+
+export function useDismissSearchOnTouchDrag(
+  getSearchInputs: () => ReadonlyArray<SearchInput>,
+  getFocusTarget?: () => HTMLElement | null | undefined,
+) {
+  const startYRef = useRef<number | null>(null);
+  const reset = () => {
+    startYRef.current = null;
+  };
+
+  return {
+    onTouchStart: (event: TouchEvent<HTMLElement>) => {
+      startYRef.current =
+        event.touches.length === 1 ? event.touches[0].clientY : null;
+    },
+    onTouchMove: (event: TouchEvent<HTMLElement>) => {
+      if (event.touches.length !== 1) {
+        reset();
+        return;
+      }
+      const startY = startYRef.current;
+      if (
+        startY == null ||
+        Math.abs(event.touches[0].clientY - startY) < DRAG_THRESHOLD_PX
+      ) {
+        return;
+      }
+      reset();
+      const focusedSearch = getSearchInputs().find(
+        input => input != null && input === document.activeElement,
+      );
+      if (focusedSearch == null) {
+        return;
+      }
+      const target = getFocusTarget?.();
+      if (target != null) {
+        target.focus({preventScroll: true});
+      } else {
+        focusedSearch.blur();
+      }
+    },
+    onTouchEnd: reset,
+    onTouchCancel: reset,
+  };
+}

package/src/motion/MEASUREMENTS.md

@@ -219,6 +219,13 @@ Bookmarks sheet.
 | M-SG18 | iPad S1 (touch; pointer if available)                                                                                                       | tap, hold, drag; hover                                                                                                                                                                                                                                                                                                                                                                            | differences from iPhone                                                                                                                               | B      |
 | M-SG19 | Safari showing the segmented stories vs S1                                                                                                  | the segmented storyboards side by side                                                                                                                                                                                                                                                                                                                                                            | synced recordings (parity proof)                                                                                                                      | B      |
 
+Done (UIKit lab, iOS 26.2 simulator, Oct 23–24 2026; in the segmented control's
+own table, `uikit/segmented.ts`, tagged `measured:`): M-SG02 (the selection
+spring and the drag clamp; the tracking spring is the shared
+`springs.fingerTracking`; the lift was measured too and is not in the table,
+since a pressed thumb's lift is a theme's) and M-SG03 (the tap's frames,
+fitted per frame).
+
 ## Sheets (UISheetPresentationController)
 
 Probe app "SheetProbe" on an iPhone 16 Pro (iPad Pro 11" for M-SH11 / M-SH20 /

package/src/motion/README.md

@@ -19,9 +19,11 @@ roles through `resolveMotion`.
 | `uikit/scroll.ts`                                | UIScrollView: deceleration rates, rubber band, bounce-back spring, `delaysContentTouches`, scroll to top.                                                            |
 | `uikit/timing.ts`                                | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade.                                                   |
 | `uikit/paging.ts`                                | A paging UIScrollView: the integrator that settles a release on its page, the page rule, the catch, `setContentOffset(animated:)`.                                   |
+| `uikit/alert.ts`                                 | UIAlertController: how a finger is tracked across the actions (highlight onset and bounds).                                                                          |
 | `uikit/navigation.ts`                            | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                                                             |
 | `uikit/progressBar.ts`                           | UIProgressView's fill: the whole-track duration and curve, its minimum length and empty alpha; the reduced-motion pulse (three roles).                               |
 | `uikit/gestures.ts`                              | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc).                                              |
+| `uikit/segmented.ts`                             | UISegmentedControl: the selection indicator's spring; under Reduce Motion the animator's cross-fade replaces it.                                                     |
 | `uikit/switch.ts`                                | UISwitch on iOS 26.2: geometry, the lift, settle, travel and tracking springs, the flip distance, the track colour.                                                  |
 | `roles.ts`                                       | The internal motion roles: the springs, durations and curves `spec:AST-094` FR4 names, registered by the shared tables, and a role's CSS form read back.             |
 | `roleValue.ts`                                   | A role's CSS form, written: a spring's duration and bounce, a duration in ms, a curve's `cubic-bezier()`.                                                            |
@@ -63,7 +65,7 @@ the timings that decide who gets a touch are not roles.
 ## Animator
 
 ```
-import {createAnimator} from '../motion/animator';
+import {createMotionAnimator} from '../motion/animator';
 import {coast} from '../motion/coast';
 import {solveSpringTowardRamp, toSpring} from '../motion/spring';
 import {resolveMotion} from '../motion/resolveMotion';
@@ -72,7 +74,7 @@ import {registerSpringsTable, springs} from '../motion/uikit';
 // Once, so the springs are registered as their roles:
 registerSpringsTable();
 
-const animator = createAnimator(sheet);
+const animator = createMotionAnimator(sheet);
 // The animator plays a motion role (spec:AST-094 FR4), its table value, as the
 // per-role tables stay internal (DEC-15); math on a spring reads the role with
 // resolveMotion.
@@ -137,8 +139,10 @@ await handle.finished; // true if it ran to the end, false if interrupted
   presented call's second frame) runs on over two frames, the start moves to
   the call's first read after it, with every call of that task. Everything
   the call starts shares that start
-  (`handle.started`); a retarget keeps an explicit one, and `{at}` puts
-  several animators on one clock. `{start: 'commit'}` lets the browser date
+  (`handle.started`); a retarget of a curve that still moves keeps an
+  explicit one, while one on a tail that already shows as at rest (within two
+  sample tolerances of its target, and slower than one a frame) counts as a
+  call from rest. `{at}` puts several animators on one clock. `{start: 'commit'}` lets the browser date
   a retarget too; `{start: 'presented'}` waits two frames, until the
   element at rest has been presented. `handle.curve(property)` is the curve
   a call plays, for a companion to follow. `{additive: true}` retargets the
@@ -167,7 +171,7 @@ 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
+- `createMotionAnimator(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

package/src/motion/animator.ts

@@ -4,11 +4,12 @@
  * @file animator.ts
  * @input An element, target values, and a spring, momentum curves (coast.ts)
  *   or any closed-form curve
- * @output Exports `createAnimator`: a compositor animator for translate,
- *   rotate, scale and opacity, with presentation values and velocities read
- *   from the analytic curves, velocity-preserving retargeting, freeze-in-place
- *   `stop`, completion promises, a shared clock, and UIKit's Reduced Motion
- *   substitution; plus its option, handle and transition types
+ * @output Exports `createMotionAnimator`, a compositor animator for
+ *   translate, rotate, scale and opacity, and its option, handle and
+ *   transition types. It reads presentation values and velocities from the
+ *   analytic curves. It retargets with the velocity kept, freezes in place on
+ *   `stop`, and gives completion promises, a shared clock, and UIKit's
+ *   Reduced Motion substitution.
  * @position Motion foundation (DOM). Internal to core: components use it for
  *   every touch-presentation animation; not exported from the package entry
  *
@@ -244,18 +245,18 @@ export interface AnimateOptions {
   crossfadeAs?: 'entrance' | 'exit';
   /**
    * When the call's animations start. By default a call from rest starts
-   * when the browser commits it, and a call that continues motion on screen
-   * (a retarget) starts now, from the value on screen. Ignored with `at`.
+   * when the browser commits it. A call that continues motion on screen (a
+   * retarget) starts now, from the value on screen. A curve whose tail
+   * already shows as at rest counts as rest. Ignored with `at`.
    * - `'commit'`: a call that continues motion also starts when the browser
-   *   commits it, dated by the browser rather than by the main thread, as a
-   *   call from rest is.
-   * - `'presented'`: a call from rest leaves its element at rest and creates
-   *   its animations two frames later, once the frame that carries the
-   *   element at rest has been presented; they then start at their commit. A
-   *   busy UI process delays the motion instead of skipping into it, for two
-   *   frames more before an idle start. Any other change to the animator
-   *   before then creates the animations first, in call order. A call that
-   *   continues motion on screen (a retarget) starts now, as by default.
+   *   commits it. The browser dates it, as it dates a call from rest.
+   * - `'presented'`: a call from rest leaves its element at rest. Its
+   *   animations are created two frames later, once the frame with the
+   *   element at rest has been presented. They then start at their commit,
+   *   so a busy UI process delays the motion instead of skipping into it.
+   *   Any other change to the animator before then creates the animations
+   *   first, in call order. A call that continues motion on screen starts
+   *   now, as by default.
    */
   start?: 'commit' | 'presented';
   /**
@@ -297,7 +298,7 @@ export interface MotionCurve {
 }
 
 /**
- * Options of `createAnimator`.
+ * Options of `createMotionAnimator`.
  */
 /** How `set` puts values in place. */
 export interface SetOptions {
@@ -652,6 +653,18 @@ const SAMPLE_TOLERANCE: Record<MotionProperty, number> = {
 /** Keyframes start on this grid (ms) and are split where the curve needs it. */
 const SAMPLE_GRID_MS = 1000 / 30;
 
+/**
+ * A curve within this many sample tolerances of its target can show as at
+ * rest. A call on it then starts as one from rest does, at the browser's start.
+ */
+const REST_DISTANCE_TOLERANCES = 2;
+
+/**
+ * A curve shows as at rest only while it moves at most one `SAMPLE_TOLERANCE`
+ * a frame at this rate.
+ */
+const REST_FRAMES_PER_SECOND = 60;
+
 /** A curve that has not settled by then (an undamped spring) snaps. */
 const MAX_DURATION_MS = 30_000;
 
@@ -803,7 +816,7 @@ export function animatorFor(
   const key = options.pseudoElement ?? '';
   let animator = byPseudo.get(key);
   if (animator == null) {
-    animator = createAnimator(element, options);
+    animator = createMotionAnimator(element, options);
     byPseudo.set(key, animator);
   }
   return animator;
@@ -920,7 +933,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  *
  * @example
  * ```
- * const animator = createAnimator(sheet);
+ * const animator = createMotionAnimator(sheet);
  * // finger lifts at 1200 px/s heading for the detent at 0 (a component
  * // passes the spring of its motion role):
  * animator.animate({y: 0}, {spring: {response: 0.45, dampingRatio: 0.9}, velocity: {y: 1200}});
@@ -929,7 +942,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  * animator.stop(['y']);
  * ```
  */
-export function createAnimator(
+export function createMotionAnimator(
   element: HTMLElement | null,
   options: AnimatorOptions = {},
 ): Animator {
@@ -1165,6 +1178,22 @@ export function createAnimator(
     return curveAt(property, time);
   };
 
+  /**
+   * Whether a curve's tail already shows as at rest at `time`. Under a
+   * starved main thread the browser commits a call late. A call that starts
+   * at its own time then skips that far into its curve. One that starts at
+   * the commit holds an element that hardly moves.
+   */
+  const showsAtRest = (
+    property: MotionProperty,
+    segment: Segment,
+    time: number,
+  ): boolean =>
+    Math.abs(valueAt(property, time) - segment.target) <=
+      REST_DISTANCE_TOLERANCES * SAMPLE_TOLERANCE[property] &&
+    Math.abs(velocityAt(property, time)) <=
+      SAMPLE_TOLERANCE[property] * REST_FRAMES_PER_SECOND;
+
   const velocityAt = (property: MotionProperty, time: number): number => {
     const held = segments.get(property);
     if (held != null && isHeld(held)) {
@@ -2033,10 +2062,10 @@ export function createAnimator(
   // -- starting from rest ---------------------------------------------------
 
   /**
-   * A call starts from rest when nothing on the channels it drives is moving
-   * (a curve still waiting for its first frame counts as rest) and nothing
-   * pins its clock (`at`). Returns its start group, or null for an explicit
-   * start.
+   * A call starts from rest when nothing on the channels it drives moves on
+   * screen and nothing pins its clock (`at`). A curve still waiting for its
+   * first frame counts as rest, as does one whose tail already shows as at
+   * rest. Returns its start group, or null for an explicit start.
    */
   const beginGroup = (
     time: number,
@@ -2070,10 +2099,12 @@ export function createAnimator(
       }
       return null;
     }
-    // A call that continues motion starts now unless it asks for the
-    // browser's start (`commit`). `presented` asks only for a call from rest:
-    // an element still moving is not at rest, so a retarget starts now, from
-    // the value and velocity on screen (spec:AST-094 FR6).
+    // A call that continues motion starts now, unless it asks for the
+    // browser's start (`commit`). `presented` asks only for a call from rest.
+    // A curve that still moves is not at rest, so a call on it starts now,
+    // from the value and velocity on screen. A tail that shows as at rest
+    // counts as rest, so a call on it waits, under `presented` for its two
+    // frames.
     for (const channel of start === 'commit' ? [] : channels) {
       for (const property of CHANNELS[channel]) {
         const segment = segments.get(property);
@@ -2084,7 +2115,8 @@ export function createAnimator(
           time < endOf(property, segment) &&
           (segment.group == null ||
             segment.group.resolved ||
-            shownSince(property, segment) != null)
+            shownSince(property, segment) != null) &&
+          !showsAtRest(property, segment, time)
         ) {
           return null;
         }

package/src/motion/reducedMotion.ts

@@ -4,7 +4,7 @@
  * @file reducedMotion.ts
  * @input The Reduced Motion preference, the primary pointer, the motion tables
  * @output reducedMotionFade (the fade the animator would play, for motion it
- *   does not drive) and the two media queries a StyleX transition spells
+ *   does not drive), playReducedMotionDip, and the queries a transition spells
  * @position The one Reduced Motion policy (design:reduced-motion) for code
  *   beside the animator: a raw Web Animations fade, a CSS transition
  *
@@ -102,3 +102,81 @@ export function reducedMotionFade(
     easing: `cubic-bezier(${curve.join(', ')})`,
   };
 }
+
+/** A running Reduced Motion dip. */
+export interface ReducedMotionDip {
+  /** Stops the dip. A change that has not landed yet never lands. */
+  cancel(): void;
+}
+
+/**
+ * Plays `fade` on `element` as a dip, and runs `land` at its middle: the
+ * fade-out, the change, then the fade-in. The fade-out holds at 0 until `land`
+ * has run, and the fade-in starts only after it. So the change never shows at
+ * full opacity, however late the main thread runs. A timer at the middle can
+ * fire after the fade-in has begun.
+ *
+ * `land` must apply the change before it returns: the fade-in starts right
+ * after it. `from` is the opacity the fade-out starts at: a leaving element
+ * fades out from where it is.
+ *
+ * @example
+ * ```
+ * const dip = playReducedMotionDip(scroller, fade, () => scroller.scrollTo({top}));
+ * // A newer change replaces it:
+ * dip.cancel();
+ * ```
+ */
+export function playReducedMotionDip(
+  element: Element,
+  fade: ReducedMotionFade,
+  land: () => void,
+  from = 1,
+): ReducedMotionDip {
+  const half = fade.duration / 2;
+  let isCancelled = false;
+  let fadeIn: Animation | null = null;
+  const fadeOut = element.animate(
+    [{opacity: from, easing: fade.easing}, {opacity: 0}],
+    {duration: half, fill: 'forwards'},
+  );
+  fadeOut.finished.then(
+    () => {
+      if (isCancelled) {
+        return;
+      }
+      land();
+      // The fade-in holds 0 until it starts: after a long stall, its start can
+      // come after the frame that runs this.
+      fadeIn = element.animate(
+        [{opacity: 0, easing: fade.easing}, {opacity: 1}],
+        {duration: half, fill: 'backwards'},
+      );
+      // The fade-in keeps the dip's own schedule: it starts where the fade-out
+      // ended, so the dip keeps its length. The clock is read after the
+      // landing, because a frame's timestamp does not count the landing's own
+      // work. After a long stall, half of the fade-in still plays.
+      const fadeOutEnd = endTime(fadeOut, half);
+      if (fadeOutEnd != null) {
+        fadeIn.startTime = Math.max(fadeOutEnd, performance.now() - half / 2);
+      }
+      // The fade-in now holds the opacity, so the held 0 can go.
+      fadeOut.cancel();
+    },
+    // A cancelled fade-out rejects `finished`: nothing lands.
+    () => {},
+  );
+  return {
+    cancel() {
+      isCancelled = true;
+      fadeOut.cancel();
+      fadeIn?.cancel();
+    },
+  };
+}
+
+/** When `animation` was due to end, on its timeline (ms), if it has started. */
+function endTime(animation: Animation, duration: number): number | null {
+  const start = animation.startTime;
+  return typeof start === 'number' ? start + duration : null;
+}

package/src/motion/roles.ts

@@ -5,7 +5,8 @@
  * @input The motion tables (motion/uikit and each component's own table)
  * @output registerMotionTable, motionRoleOf, motionRoleIn, listMotionRoles,
  *   motionRoleVariable, and the CSS form of a role's value
- *   (formatMotionRoleValue, parseMotionRoleValue)
+ *   (formatMotionRoleValue, parseMotionRoleValue), and parseCssEasing for a
+ *   CSS transition's easing
  * @position Motion foundation, internal to core: read by the code that
  *   resolves a role when a motion starts. No public API writes a role: touch
  *   motion stays internal until the public motion-token set is decided.
@@ -260,3 +261,21 @@ export function parseMotionRoleValue(
     ? points
     : null;
 }
+
+/** The CSS easing keywords, as the control points CSS gives them. */
+const EASING_KEYWORDS: Readonly<Record<string, MotionCurvePoints>> = {
+  linear: [0, 0, 1, 1],
+  ease: [0.25, 0.1, 0.25, 1],
+  'ease-in': [0.42, 0, 1, 1],
+  'ease-out': [0, 0, 0.58, 1],
+  'ease-in-out': [0.42, 0, 0.58, 1],
+};
+
+/**
+ * Reads a CSS easing, a keyword or a `cubic-bezier()`, as a curve role's value
+ * is read. Returns null for any other easing, such as `steps()`.
+ */
+export function parseCssEasing(text: string): MotionCurvePoints | null {
+  const value = text.trim();
+  return EASING_KEYWORDS[value] ?? parseMotionRoleValue('curve', value);
+}