@onekeyfe/react-native-native-overlay 3.0.162-alpha.268

package/src/OverlayView.web.tsx

@@ -0,0 +1,356 @@
+import { useEffect, useId, useLayoutEffect, useRef } from 'react';
+import type { ReactNode, SyntheticEvent } from 'react';
+
+import { createPortal } from 'react-dom';
+import { StyleSheet, View } from 'react-native';
+
+import { OverlayLevelProvider } from './OverlayLevelContext';
+import { OVERLAY_LEVEL_ORDER, isBlockingLevel } from './OverlayLevels';
+import { OVERLAY_OWNER_ATTRIBUTE } from './OverlayPageHost.web';
+import { useOverlayController } from './useOverlayController';
+import { animateBackdrop, animateTransition } from './web/animateTransition';
+import {
+  ENTRY_ATTRIBUTE,
+  getOverlayLayerRoot,
+  getOverlayPageHost,
+  registerOverlayDismissRequester,
+  scheduleOverlayInertSync,
+} from './web/overlayLayers';
+import { useKeyboardShift } from './web/useKeyboardShift';
+import { useSheetDrag } from './web/useSheetDrag';
+
+import type { IResolvedOverlayAnimation } from './animation/resolveAnimation';
+import type {
+  IOverlayRequestDismissReason,
+  IOverlaySheetOptions,
+  IOverlayViewProps,
+} from './OverlayViewTypes';
+
+const DEFAULT_BACKDROP_COLOR = 'rgba(0, 0, 0, 0.4)';
+const DEFAULT_SHEET_MAX_HEIGHT = '92vh';
+const DEFAULT_SHEET_CORNER_RADIUS = 24;
+
+// Portaled content still bubbles React events to the caller's ancestors;
+// stop them at the entry so presses cannot reach the page underneath.
+// Mouse and touch events must keep bubbling natively: react-native-web's
+// responder system (PanResponder, gesture responders) listens for them on
+// `document`, and a React stopPropagation also stops the native event.
+const stopPropagation = (event: SyntheticEvent) => event.stopPropagation();
+const ISOLATED_EVENT_HANDLERS = {
+  onClick: stopPropagation,
+  onPointerDown: stopPropagation,
+  onPointerUp: stopPropagation,
+  onKeyDown: stopPropagation,
+};
+
+interface IWebOverlayEntryProps {
+  entryId: string;
+  /** Closed but kept mounted: hidden and inert. */
+  parked?: boolean;
+  stackOrder: number;
+  presented: boolean;
+  animation: IResolvedOverlayAnimation;
+  blocking: boolean;
+  backdropColor: string | undefined;
+  dismissOnBackdropPress: boolean;
+  onPresented: () => void;
+  onDismissed: () => void;
+  onRequestDismiss: (reason: IOverlayRequestDismissReason) => void;
+  /** Set for `presentation="sheet"`. */
+  sheet: IOverlaySheetOptions | undefined;
+  /** Page scope: stacking inside the page host and the owning page. */
+  zIndex: number;
+  ownerKey: string | undefined;
+  testID?: string;
+  children?: ReactNode;
+}
+
+function WebOverlayEntry({
+  entryId,
+  parked = false,
+  stackOrder,
+  presented,
+  animation,
+  blocking,
+  backdropColor,
+  dismissOnBackdropPress,
+  onPresented,
+  onDismissed,
+  onRequestDismiss,
+  sheet,
+  zIndex,
+  ownerKey,
+  testID,
+  children,
+}: IWebOverlayEntryProps) {
+  const sheetRef = useRef<HTMLDivElement>(null);
+  // A pan dismissal already moved the sheet off screen; skip the exit run.
+  const pannedAwayRef = useRef(false);
+  const isSheet = !!sheet;
+  const entryRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const keyboardLayerRef = useRef<HTMLDivElement>(null);
+  const backdropRef = useRef<HTMLDivElement>(null);
+  const directionRef = useRef<'in' | 'out' | undefined>(undefined);
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const callbacksRef = useRef({ onPresented, onDismissed });
+  callbacksRef.current = { onPresented, onDismissed };
+
+  useLayoutEffect(() => {
+    const content = contentRef.current;
+    if (!content) {
+      return;
+    }
+    const direction = presented ? 'in' : 'out';
+    if (directionRef.current === direction) {
+      return;
+    }
+    const neverEntered = directionRef.current === undefined;
+    directionRef.current = direction;
+    scheduleOverlayInertSync();
+    if (direction === 'out' && (neverEntered || pannedAwayRef.current)) {
+      callbacksRef.current.onDismissed();
+      return;
+    }
+    if (direction === 'in' && blocking) {
+      restoreFocusRef.current = document.activeElement as HTMLElement | null;
+      entryRef.current?.focus({ preventScroll: true });
+    }
+    content.getAnimations().forEach((running) => running.cancel());
+    backdropRef.current?.getAnimations().forEach((running) => running.cancel());
+    // A sheet is measured as a whole; other presentations by the children
+    // of the full-window React root.
+    const contentRoot = isSheet
+      ? content
+      : (content.firstElementChild as HTMLElement | null) ?? content;
+    const transition = direction === 'in' ? animation.enter : animation.exit;
+    const running = [
+      animateTransition(content, contentRoot, transition, direction),
+      backdropRef.current
+        ? animateBackdrop(
+            backdropRef.current,
+            animation.backdrop.motion,
+            direction
+          )
+        : undefined,
+    ].filter((item): item is Animation => !!item);
+    void Promise.all(running.map((item) => item.finished))
+      .then(() => {
+        if (directionRef.current !== direction) {
+          return;
+        }
+        if (direction === 'in') {
+          callbacksRef.current.onPresented();
+        } else {
+          restoreFocusRef.current?.focus?.({ preventScroll: true });
+          restoreFocusRef.current = null;
+          callbacksRef.current.onDismissed();
+        }
+      })
+      .catch(() => {
+        // Cancelled by a newer transition; that run reports instead.
+      });
+  }, [presented, animation, blocking, isSheet]);
+
+  useEffect(
+    () => registerOverlayDismissRequester(entryId, onRequestDismiss),
+    [entryId, onRequestDismiss]
+  );
+
+  // A plain DOM listener: the backdrop is a pointer target only; keyboard
+  // users dismiss with Escape through the layer manager.
+  useEffect(() => {
+    const backdropNode = backdropRef.current;
+    if (!backdropNode || !dismissOnBackdropPress) {
+      return;
+    }
+    const onBackdropClick = () => onRequestDismiss('backdrop');
+    backdropNode.addEventListener('click', onBackdropClick);
+    return () => backdropNode.removeEventListener('click', onBackdropClick);
+  }, [dismissOnBackdropPress, onRequestDismiss]);
+
+  useKeyboardShift({
+    layerRef: keyboardLayerRef,
+    sheetRef,
+    contentRef,
+    isSheet,
+    enabled: presented,
+  });
+
+  useSheetDrag({
+    sheetRef,
+    backdropRef,
+    enabled: !!sheet && (sheet.dismissOnPanDown ?? true) && presented,
+    onDismissByPan: () => {
+      pannedAwayRef.current = true;
+      onRequestDismiss('pan');
+    },
+  });
+
+  const showBackdrop = !!backdropColor || blocking;
+  const cornerRadius = sheet?.cornerRadius ?? DEFAULT_SHEET_CORNER_RADIUS;
+
+  return (
+    <div
+      ref={entryRef}
+      {...{ [ENTRY_ATTRIBUTE]: '' }}
+      {...(ownerKey ? { [OVERLAY_OWNER_ATTRIBUTE]: ownerKey } : {})}
+      data-stack-order={stackOrder}
+      data-testid={testID}
+      role={blocking ? 'dialog' : undefined}
+      aria-modal={blocking || undefined}
+      tabIndex={-1}
+      inert={parked || undefined}
+      aria-hidden={parked || undefined}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex,
+        pointerEvents: 'none',
+        outline: 'none',
+        visibility: parked ? 'hidden' : undefined,
+      }}
+      {...ISOLATED_EVENT_HANDLERS}
+    >
+      {showBackdrop ? (
+        <div
+          ref={backdropRef}
+          aria-hidden
+          style={{
+            position: 'absolute',
+            inset: 0,
+            opacity: 0,
+            background: backdropColor ?? 'transparent',
+            pointerEvents: blocking ? 'auto' : 'none',
+          }}
+        />
+      ) : null}
+      {/* The keyboard lift lives on its own layer so it composes with the
+          enter / exit animation on the content below. It only carries a
+          transform while lifted: a transform would re-anchor fixed children. */}
+      <div
+        ref={keyboardLayerRef}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          pointerEvents: 'none',
+          transition: 'transform 250ms ease-out',
+        }}
+      >
+        <div
+          ref={contentRef}
+          style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}
+        >
+          {sheet ? (
+            <div
+              ref={sheetRef}
+              style={{
+                position: 'absolute',
+                left: 0,
+                right: 0,
+                bottom: 0,
+                height: sheet.height,
+                maxHeight: sheet.maxHeight ?? DEFAULT_SHEET_MAX_HEIGHT,
+                display: 'flex',
+                flexDirection: 'column',
+                overflow: 'hidden',
+                pointerEvents: 'auto',
+                touchAction: 'pan-y',
+                background: sheet.backgroundColor
+                  ? String(sheet.backgroundColor)
+                  : undefined,
+                borderTopLeftRadius: cornerRadius,
+                borderTopRightRadius: cornerRadius,
+              }}
+            >
+              {sheet.showHandle ? (
+                <div
+                  style={{
+                    alignSelf: 'center',
+                    width: 36,
+                    height: 5,
+                    marginTop: 8,
+                    borderRadius: 2.5,
+                    background: 'rgba(0, 0, 0, 0.2)',
+                    flexShrink: 0,
+                  }}
+                />
+              ) : null}
+              <View style={{ flexShrink: 1 }}>{children}</View>
+            </div>
+          ) : (
+            <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
+              {children}
+            </View>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function OverlayView(props: IOverlayViewProps) {
+  const {
+    level = 'modal',
+    presentation = 'center',
+    backdrop,
+    blocking,
+    sheet,
+    keepContentMounted = false,
+    children,
+    testID,
+  } = props;
+  const parkedId = useId();
+  const {
+    entry,
+    mounted,
+    presented,
+    animation,
+    onHostPresented,
+    onHostDismissed,
+    onHostRequestDismiss,
+    scope,
+    hostKey,
+    ownerKey,
+  } = useOverlayController(props);
+
+  // Closed with `keepContentMounted`: the same entry stays in the layer,
+  // hidden and inert, so the content keeps its state and can be measured.
+  const parked = !mounted || !entry;
+  if (parked && !keepContentMounted) {
+    return null;
+  }
+
+  const pageHost =
+    !parked && scope === 'page' ? getOverlayPageHost(hostKey) : undefined;
+  return createPortal(
+    <WebOverlayEntry
+      key="entry"
+      parked={parked}
+      entryId={entry?.id ?? parkedId}
+      stackOrder={entry?.seq ?? 0}
+      presented={!parked && presented}
+      animation={animation}
+      blocking={blocking ?? isBlockingLevel(level)}
+      backdropColor={
+        backdrop ? String(backdrop.color ?? DEFAULT_BACKDROP_COLOR) : undefined
+      }
+      dismissOnBackdropPress={backdrop ? !!backdrop.dismissOnPress : false}
+      onPresented={onHostPresented}
+      onDismissed={onHostDismissed}
+      onRequestDismiss={onHostRequestDismiss}
+      sheet={presentation === 'sheet' ? sheet ?? {} : undefined}
+      // Inside a page host all levels share one stacking context.
+      zIndex={
+        pageHost
+          ? OVERLAY_LEVEL_ORDER[level] * 1000 + (entry?.seq ?? 0)
+          : entry?.seq ?? 0
+      }
+      ownerKey={pageHost ? ownerKey : undefined}
+      testID={testID}
+    >
+      <OverlayLevelProvider value={level}>{children}</OverlayLevelProvider>
+    </WebOverlayEntry>,
+    pageHost ?? getOverlayLayerRoot(level)
+  );
+}

package/src/OverlayViewTypes.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from 'react';
+
+import type {
+  IOverlayAnimation,
+  IOverlayPresentation,
+} from './animation/types';
+import type {
+  IOverlayDismissReason,
+  IOverlayLevel,
+  IOverlayScope,
+  IOverlayStatusBarStyle,
+  IOverlayStrategy,
+} from './types';
+import type { ColorValue } from 'react-native';
+
+export type IOverlayRequestDismissReason = 'back' | 'backdrop' | 'pan';
+
+export interface IOverlayBackdrop {
+  /** Include alpha; e.g. the theme `$bgBackdrop`. */
+  color?: ColorValue;
+  dismissOnPress?: boolean;
+}
+
+export interface IOverlaySheetOptions {
+  /** Fixed height; when omitted the sheet fits its content. */
+  height?: number;
+  /** Defaults to 92% of the window height. */
+  maxHeight?: number;
+  cornerRadius?: number;
+  showHandle?: boolean;
+  backgroundColor?: ColorValue;
+  /** Swipe down to close. A pan dismissal cannot be vetoed. */
+  dismissOnPanDown?: boolean;
+}
+
+export interface IOverlayViewProps {
+  /** Desired open state. The overlay may still be queued by its strategy. */
+  visible: boolean;
+  /**
+   * `page` renders in the root-route `OverlayPageHost` and hides while the
+   * owning page is covered. Keys default to the nearest scope providers.
+   */
+  scope?: IOverlayScope;
+  hostKey?: string;
+  ownerKey?: string;
+  level?: IOverlayLevel;
+  strategy?: IOverlayStrategy;
+  priority?: number;
+  replaceKey?: string;
+  presentation?: IOverlayPresentation;
+  animation?: IOverlayAnimation;
+  /** `presentation="sheet"` only. */
+  sheet?: IOverlaySheetOptions;
+  /**
+   * Keep the content mounted (hidden, inert) while closed, so it keeps its
+   * state and callers can measure it before opening, as native-sheet did.
+   */
+  keepContentMounted?: boolean;
+  /** `false` renders no backdrop. */
+  backdrop?: IOverlayBackdrop | false;
+  /** Defaults by level: toast and debug pass touches through. */
+  blocking?: boolean;
+  /**
+   * Status bar content (iOS / Android) while this is the topmost shown
+   * overlay that sets one, e.g. `light` for a dark full-screen overlay.
+   * Unset leaves the status bar to the page below.
+   */
+  statusBarStyle?: IOverlayStatusBarStyle;
+  dismissOnBackPress?: boolean;
+  /**
+   * Back press or backdrop press asked to close. When omitted the overlay
+   * closes itself; when provided the caller decides by toggling `visible`.
+   * A `pan` dismissal already happened natively and always closes.
+   */
+  onRequestDismiss?: (reason: IOverlayRequestDismissReason) => void;
+  onPresented?: () => void;
+  /** The exit animation finished and the content unmounted. */
+  onClose?: (reason: IOverlayDismissReason) => void;
+  children?: ReactNode;
+  testID?: string;
+}

package/src/animation/motionPresets.ts

@@ -0,0 +1,52 @@
+import type { IOverlayMotion, IOverlayMotionPreset } from './types';
+
+const EASE: readonly [number, number, number, number] = [0.25, 0.1, 0.25, 1];
+const EASE_OUT: readonly [number, number, number, number] = [0, 0, 0.58, 1];
+
+function spring(mass: number, stiffness: number, damping: number) {
+  return { type: 'spring', spring: { mass, stiffness, damping } } as const;
+}
+
+function timing(
+  durationMs: number,
+  easing: readonly [number, number, number, number]
+) {
+  return { type: 'timing', timing: { durationMs, easing } } as const;
+}
+
+/**
+ * Native tokens mirror `packages/components/tamagui.animations.native.ts`
+ * (Reanimated driver). `quick` intentionally uses a damping ratio of ~3.16 (no overshoot).
+ */
+export const NATIVE_MOTION_PRESETS: Record<
+  IOverlayMotionPreset,
+  IOverlayMotion
+> = {
+  quick: spring(0.1, 100, 20),
+  popoverQuick: timing(150, [0.215, 0.61, 0.355, 1]),
+  smooth: spring(1, 438, 42),
+  fast: spring(1.2, 250, 20),
+  medium: spring(0.9, 100, 10),
+  slow: spring(1, 60, 20),
+  // @backpackapp-io/react-native-toast: 300ms Easing.inOut(Easing.quad).
+  toastSlide: timing(300, [0.455, 0.03, 0.515, 0.955]),
+  lockFade: timing(150, EASE_OUT),
+};
+
+/**
+ * Web tokens mirror `packages/components/tamagui.animations.web.ts` (CSS
+ * driver). Web keeps its own short curves; converting the native springs
+ * would make web overlays several times slower than today.
+ */
+export const WEB_MOTION_PRESETS: Record<IOverlayMotionPreset, IOverlayMotion> =
+  {
+    quick: timing(150, EASE),
+    popoverQuick: timing(150, [0.215, 0.61, 0.355, 1]),
+    smooth: timing(300, [0.2, 0, 0, 1]),
+    fast: timing(200, EASE_OUT),
+    medium: timing(300, EASE_OUT),
+    slow: timing(450, EASE_OUT),
+    // sonner: transform / opacity 400ms ease.
+    toastSlide: timing(400, EASE),
+    lockFade: timing(150, EASE_OUT),
+  };

package/src/animation/platformMotionPresets.ts

@@ -0,0 +1 @@
+export { NATIVE_MOTION_PRESETS as OVERLAY_MOTION_PRESETS } from './motionPresets';

package/src/animation/platformMotionPresets.web.ts

@@ -0,0 +1 @@
+export { WEB_MOTION_PRESETS as OVERLAY_MOTION_PRESETS } from './motionPresets';

package/src/animation/resolveAnimation.ts

@@ -0,0 +1,103 @@
+import type {
+  IOverlayAnimation,
+  IOverlayMotion,
+  IOverlayMotionInput,
+  IOverlayMotionPreset,
+  IOverlayPresentation,
+  IOverlayTransition,
+} from './types';
+
+export interface IResolvedOverlayTransition
+  extends Omit<IOverlayTransition, 'motion'> {
+  motion: IOverlayMotion;
+}
+
+export interface IResolvedOverlayAnimation {
+  enter: IResolvedOverlayTransition;
+  exit: IResolvedOverlayTransition;
+  backdrop: { motion: IOverlayMotion };
+}
+
+/**
+ * Defaults match today's visuals: Dialog center (scale 0.85 + fade, quick),
+ * Tamagui Sheet (slide from bottom, quick), message toasts (slide from top,
+ * 300ms quad), Popover floating content (scale 0.95 + fade, popoverQuick).
+ */
+export const DEFAULT_OVERLAY_ANIMATIONS: Record<
+  IOverlayPresentation,
+  { enter: IOverlayTransition; backdrop: IOverlayMotionPreset }
+> = {
+  sheet: {
+    enter: { type: 'slide', edge: 'bottom', motion: 'quick' },
+    backdrop: 'quick',
+  },
+  center: {
+    enter: { type: 'scale', scale: 0.85, fade: true, motion: 'quick' },
+    backdrop: 'quick',
+  },
+  toast: {
+    enter: { type: 'slide', edge: 'top', fade: true, motion: 'toastSlide' },
+    backdrop: 'quick',
+  },
+  fullscreen: {
+    enter: { type: 'fade', motion: 'quick' },
+    backdrop: 'quick',
+  },
+  anchored: {
+    enter: {
+      type: 'scale',
+      scale: 0.95,
+      fade: true,
+      origin: 'anchor',
+      motion: 'popoverQuick',
+    },
+    backdrop: 'popoverQuick',
+  },
+};
+
+function resolveMotion(
+  input: IOverlayMotionInput | undefined,
+  fallback: IOverlayMotionInput,
+  presets: Record<IOverlayMotionPreset, IOverlayMotion>
+): IOverlayMotion {
+  const value = input ?? fallback;
+  return typeof value === 'string' ? presets[value] : value;
+}
+
+function resolveTransition(
+  transition: IOverlayTransition,
+  fallbackMotion: IOverlayMotionInput,
+  presets: Record<IOverlayMotionPreset, IOverlayMotion>
+): IResolvedOverlayTransition {
+  return {
+    ...transition,
+    fade: transition.fade ?? transition.type === 'scale',
+    motion: resolveMotion(transition.motion, fallbackMotion, presets),
+  };
+}
+
+/** Fills presentation defaults and turns preset names into concrete curves. */
+export function resolveOverlayAnimation(
+  presentation: IOverlayPresentation,
+  animation: IOverlayAnimation | undefined,
+  presets: Record<IOverlayMotionPreset, IOverlayMotion>
+): IResolvedOverlayAnimation {
+  const defaults = DEFAULT_OVERLAY_ANIMATIONS[presentation];
+  const enterInput = animation?.enter ?? defaults.enter;
+  const fallbackMotion = defaults.enter.motion ?? 'quick';
+  const enter = resolveTransition(enterInput, fallbackMotion, presets);
+  const exit = animation?.exit
+    ? resolveTransition(animation.exit, fallbackMotion, presets)
+    : enter;
+  return {
+    enter,
+    exit,
+    backdrop: {
+      motion: resolveMotion(
+        animation?.backdrop?.motion,
+        defaults.backdrop,
+        presets
+      ),
+    },
+  };
+}

package/src/animation/spring.ts

@@ -0,0 +1,80 @@
+import type { IOverlaySpring } from './types';
+
+export function springNaturalFrequency(spring: IOverlaySpring): number {
+  return Math.sqrt(spring.stiffness / spring.mass);
+}
+
+export function springDampingRatio(spring: IOverlaySpring): number {
+  return spring.damping / (2 * Math.sqrt(spring.stiffness * spring.mass));
+}
+
+/**
+ * Android `SpringForce` assumes unit mass, so it takes
+ * stiffness / mass and the damping ratio.
+ */
+export function springToAndroidSpringForce(spring: IOverlaySpring): {
+  stiffness: number;
+  dampingRatio: number;
+} {
+  return {
+    stiffness: spring.stiffness / spring.mass,
+    dampingRatio: springDampingRatio(spring),
+  };
+}
+
+/** Normalized step response: progress from 0 to 1 at `tMs`, zero start velocity. */
+export function springProgressAt(spring: IOverlaySpring, tMs: number): number {
+  const t = tMs / 1000;
+  const w0 = springNaturalFrequency(spring);
+  const zeta = springDampingRatio(spring);
+  let progress: number;
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    progress =
+      1 -
+      Math.exp(-zeta * w0 * t) *
+        (Math.cos(wd * t) + ((zeta * w0) / wd) * Math.sin(wd * t));
+  } else if (zeta === 1) {
+    progress = 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+  } else {
+    const root = Math.sqrt(zeta * zeta - 1);
+    const r1 = -w0 * (zeta - root);
+    const r2 = -w0 * (zeta + root);
+    progress = 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
+  }
+  return spring.overshootClamping ? Math.min(progress, 1) : progress;
+}
+
+const MAX_SETTLE_MS = 10_000;
+
+/** First time after which the response stays within `epsilon` of the target. */
+export function springSettleTimeMs(
+  spring: IOverlaySpring,
+  epsilon = 0.001
+): number {
+  let lastOutside = 0;
+  for (let t = 0; t <= MAX_SETTLE_MS; t += 1) {
+    if (Math.abs(1 - springProgressAt(spring, t)) >= epsilon) {
+      lastOutside = t;
+    }
+  }
+  return lastOutside + 1;
+}
+
+/**
+ * CSS `linear()` easing sampled from the spring, for the Web Animations API when a
+ * caller passes a custom spring. Presets use `WEB_MOTION_PRESETS` instead.
+ */
+export function springToCssLinear(
+  spring: IOverlaySpring,
+  stops = 40
+): { durationMs: number; easing: string } {
+  const durationMs = springSettleTimeMs(spring);
+  const points: string[] = [];
+  for (let i = 0; i <= stops; i += 1) {
+    const value =
+      i === stops ? 1 : springProgressAt(spring, (durationMs * i) / stops);
+    points.push(String(Math.round(value * 10_000) / 10_000));
+  }
+  return { durationMs, easing: `linear(${points.join(', ')})` };
+}