Skip to content

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

TypeScript
43.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file sliderTouchController.ts
 * @input The slider's control (and its size), thumbs, fill parts, value
 *   tooltips and value model; the gesture recognizers, the animator and the
 *   UIKit slider table
 * @output Exports `SliderTouchController`, `sliderCoastCurve` and the
 *   `SliderTouchModel` and `SliderTouchParts` types
 * @position Internal to Slider: useSliderTouch attaches it while enabled.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Slider/useSliderTouch.ts
 * - /packages/core/src/Slider/Slider.tsx
 * - /packages/core/src/Slider/useSliderTouch.test.tsx
 */

import {getGestureHost} from '../gestures/GestureHost';
import type {GestureRecognizer} from '../gestures/GestureRecognizer';
import {playHaptic} from '../gestures/haptics';
import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
import {
  PRESS_PROFILES,
  createPressTracker,
  type ControlEvent,
} from '../gestures/PressTracker';
import type {SwipeGestureRecognizer} from '../gestures/SwipeGestureRecognizer';
import {lockSelection} from '../gestures/selectionLock';
import {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';
import type {PointerKind} from '../gestures/types';
import {isRtlElement} from '../hooks/isRtlElement';
import {
  createMotionEngine,
  type Animator,
  type MotionCurve,
  type MotionHandle,
} from '../motion/animator';
import {projectDistance} from '../motion/projection';
import {resolveMotion} from '../motion/resolveMotion';
import {solveSpring, toSpring, type SpringDescription} from '../motion/spring';
import {
  SLIDER_DROP_SPRING,
  SLIDER_LIFT_SPRING,
  SLIDER_RELEASE_SPRING,
  registerSpringsTable,
} from '../motion/uikit/springs';
import {UIKIT_CONTROL, UIKIT_PAN} from '../motion/uikit/gestures';
import {slider as UIKIT_SLIDER} from '../motion/uikit/slider';
import {observeResize} from '../utils/sharedResizeObserver';

/** Frames of a coast before it reports values (the touch hand-off limit). */
const HAND_OFF_FRAMES = 3;

/** A coast shorter than this (px) and slower than 1 px/s is not played. */
const MIN_COAST_PX = 0.5;

/** The parts the controller moves. */
export interface SliderTouchParts {
  readonly control: HTMLElement;
  readonly thumbs: ReadonlyArray<HTMLElement>;
  /** The fill's mover (a range's start) and the fill itself. */
  readonly fillMover: HTMLElement | null;
  readonly fill: HTMLElement | null;
  /** Each thumb's value tooltip while it is mounted, else null. */
  readonly tooltips: ReadonlyArray<HTMLElement | null>;
}

/** What the controller needs from Slider. Read fresh on every use. */
export interface SliderTouchModel {
  readonly min: number;
  readonly max: number;
  readonly isRange: boolean;
  readonly isHorizontal: boolean;
  readonly isDisabled: boolean;
  /** The thumb's size along the travel, px: the travel is inset by half of it. */
  readonly thumbSize: number;
  /** The values the owner rendered. */
  values(): ReadonlyArray<number>;
  /** What thumb `index` becomes for `raw`: snapped, clamped, kept apart. */
  constrain(index: number, raw: number): number;
  /** The range thumb `index` may cover, unsnapped (its ends and the gap). */
  bounds(index: number): readonly [number, number];
  /**
   * `onChange` for thumb `index`. `from` holds the start values when one
   * move changes both range thumbs, as a drag passed between coincident
   * thumbs does.
   */
  change(index: number, value: number, from?: ReadonlyArray<number>): void;
  /** Thumb `index` is under a finger (pressed paint, focus, tooltip), or none. */
  press(index: number | null): void;
  /**
   * The interaction ended. Report thumb `index`'s last `value` through
   * `onChange`, or null when the interaction ends on no value of its own.
   * Report it even when a frame's report already carried it: these handlers
   * run outside React's events, so that report's render can be pending.
   * Release the pressed paint. Then have the owner render it all now, so the
   * parts can return to the stylesheet and `onChangeEnd` carries what the
   * owner rendered.
   */
  commit(index: number, value: number | null): void;
  /** `onChangeEnd`, with the values the owner rendered. */
  reportEnd(): void;
  /**
   * Holds thumb `index`'s value-tooltip anchor where the owner last rendered
   * it, and returns that place as progress along the travel (0 to 1). Null
   * when the thumb has no value tooltip. While held, the owner's renders do
   * not move the anchor, so the tooltip can move with the thumb by translate.
   */
  holdAnchor(index: number): number | null;
  /**
   * The anchors of thumbs `indices` follow the owner's rendered values
   * again. The owner renders them now, so they move in this task.
   */
  releaseAnchors(indices: ReadonlyArray<number>): void;
  /**
   * The value a press at client point (`x`, `y`) on the track means: a
   * mark's value on a mark, else the point along the travel.
   */
  valueAt(x: number, y: number): number;
  /** The thumb a track press at `value` moves. */
  thumbFor(value: number): number;
}

/** The travel's geometry, read once when a finger lands. */
interface Geometry {
  /** The track's length along the travel, CSS px. */
  readonly length: number;
  /** The thumb's travel: the track minus one thumb. */
  readonly travel: number;
  readonly axis: 'x' | 'y';
  /** Screen direction of increasing value along `axis`. */
  readonly sign: 1 | -1;
  /** The control's client rect, for the release's inside test. */
  readonly rect: DOMRect;
}

interface Coast {
  handles: ReadonlyArray<MotionHandle>;
  readonly target: number;
  frames: number;
  raf: number;
  /** The coast in the thumb's px along `travel`, from `at`. */
  curve: MotionCurve;
  travel: number;
  readonly at: number;
  readonly touchRelease: boolean;
}

interface Interaction {
  /** The thumb whose touch target holds the finger. */
  readonly owner: number;
  /** The thumb whose value moves (a coincident pair may hand it over). */
  index: number;
  /** The track as last measured: its length can change mid-gesture. */
  geometry: Geometry;
  /** The value when the pan began. Null until it does. */
  startValue: number | null;
  /**
   * Where the pan's threshold lies along the axis, px from the touch-down
   * point. For a finger, it is the hysteresis on the side the pan began. For
   * a mouse, whose pan begins in any direction, it is the threshold's
   * projection on the axis.
   */
  beganOffset: number;
  /** The last value reported (or rendered when the finger landed). */
  value: number;
  /** Whether the finger is inside the control's tracking bounds. */
  isInside: boolean;
  /** The end the value sits at, for the once-per-entry haptic. */
  atEnd: 'min' | 'max' | null;
  /** The value changed during this interaction. */
  changed: boolean;
  coast: Coast | null;
  /** The pan ended or was cancelled (the release is under way or done). */
  released: boolean;
  /**
   * A mouse holds the thumb: it pans as a finger does, with no lift and no
   * coast, as a mouse drag behaved before.
   */
  readonly isMouse: boolean;
  /**
   * A finger's release coasts. A mouse's or a pen's drag ends at its release,
   * with no coast.
   */
  readonly coasts: boolean;
  /**
   * The drag began on two range thumbs that share a value. It picks its
   * thumb by its first movement and may pass to the other thumb.
   */
  readonly beganCoincident: boolean;
  /** Each held tooltip anchor's place, as progress, by thumb. */
  readonly anchors: Map<number, number | null>;
}

/**
 * The release coast as a curve in the thumb's own px, clamped to the
 * thumb's range. It is a spring from `from` to `to` with `velocity` (px/s).
 * Its value stops at an end instead of passing it, as UISlider clamps its
 * value and the thumb follows it.
 */
export function sliderCoastCurve({
  from,
  to,
  velocity,
  lower,
  upper,
  spring: description = SLIDER_RELEASE_SPRING,
}: {
  from: number;
  to: number;
  velocity: number;
  lower: number;
  upper: number;
  /** The release spring, as the thumb's theme resolves it. */
  spring?: SpringDescription;
}): MotionCurve {
  const spring = solveSpring(toSpring(description), {
    from,
    to,
    velocity,
  });
  const lo = Math.min(lower, upper);
  const hi = Math.max(lower, upper);
  const duration = Math.min(Math.max(spring.settleTime(0.05), 1 / 120), 3);
  return {
    duration,
    at: t => (t >= duration ? to : Math.min(Math.max(spring.value(t), lo), hi)),
    velocity: t => {
      if (t >= duration) {
        return 0;
      }
      const value = spring.value(t);
      return value <= lo || value >= hi ? 0 : spring.velocity(t);
    },
  };
}

/**
 * Where the browser draws an element's translate on one axis in this frame,
 * px: its computed style, which follows the running animation. Null when it
 * draws none.
 */
function drawnTranslate(element: HTMLElement, axis: 'x' | 'y'): number | null {
  const translate =
    element.ownerDocument.defaultView?.getComputedStyle(element).translate ??
    '';
  if (translate === '' || translate === 'none') {
    return null;
  }
  const [x = '0', y = '0'] = translate.split(' ');
  const px = parseFloat(axis === 'x' ? x : y);
  return Number.isFinite(px) ? px : null;
}

/** UISlider's touch tracking for one Slider (both thumbs of a range). */
export class SliderTouchController {
  private model: SliderTouchModel;
  private readonly getParts: () => SliderTouchParts | null;
  private readonly interactions = new Map<number, Interaction>();
  private readonly animators = new Map<HTMLElement, Animator>();
  /** The thumbs whose tooltip anchor an interaction holds. */
  private readonly heldAnchors = new Set<number>();
  /** The owner unmounted the slider: a cancel reports nothing then. */
  private disposed = false;
  /** Thumbs whose current touch is a mouse: Slider's own handlers take it. */
  private readonly mouseOwners = new Set<number>();
  /** The track's tap (see handleTrackTap). Null while detached. */
  private trackTap: TapGestureRecognizer | null = null;

  constructor(
    model: SliderTouchModel,
    getParts: () => SliderTouchParts | null,
  ) {
    this.model = model;
    this.getParts = getParts;
  }

  setModel(model: SliderTouchModel): void {
    this.model = model;
  }

  /**
   * Attaches the recognizers to the thumbs for every pointer. Under a
   * coarse primary pointer each thumb's `::before` is its touch target.
   */
  attach(): () => void {
    this.disposed = false;
    const parts = this.getParts();
    const targets = parts?.thumbs ?? [];
    if (parts == null || targets.length === 0) {
      return () => {};
    }
    // The coast plays a motion role: register the springs table, once.
    registerSpringsTable();
    const host = getGestureHost(parts.control.ownerDocument);
    const detachers: (() => void)[] = [];
    targets.forEach((hit, owner) => {
      const tracker = createPressTracker({
        getBounds: () =>
          this.getParts()?.control.getBoundingClientRect() ?? null,
        view: hit,
        highlightDelay: PRESS_PROFILES.control.highlightDelay,
        quickTapFlash: PRESS_PROFILES.control.quickTapFlash,
        onControlEvent: (event, touch) =>
          this.handleControlEvent(owner, event, touch.pointerType),
        onHighlightChange: isHighlighted =>
          this.handleHighlight(owner, isHighlighted),
        vetoesAncestorRecognizer: recognizer => this.vetoes(recognizer),
        isEnabled: () => !this.model.isDisabled,
      });
      const pan = new PanGestureRecognizer({
        name: `slider-thumb-${owner}`,
        direction: this.model.isHorizontal ? 'horizontal' : 'vertical',
        maximumNumberOfTouches: 1,
        cancelsTouchesInView: false,
        allowedPointerTypes: ['touch', 'pen'],
        // A held thumb does something, so a held finger never starts a text
        // selection or the callout on it. The gesture host takes this lock
        // for each held press and releases it on the lift.
        selectionLock: lockSelection,
      });
      // A mouse drag on a thumb is a pan too, claimed after the same
      // hysteresis but in any direction. A mouse has no page scroll to yield
      // to, so a drag that starts off the travel still moves the thumb.
      const mousePan = new PanGestureRecognizer({
        name: `slider-thumb-${owner}-mouse`,
        maximumNumberOfTouches: 1,
        cancelsTouchesInView: false,
        allowedPointerTypes: ['mouse'],
      });
      const removeListener = pan.addListener(current =>
        this.handlePan(owner, current),
      );
      const removeMouseListener = mousePan.addListener(current =>
        this.handlePan(owner, current),
      );
      detachers.push(
        host.attachConsumer(hit, tracker),
        host.attach(hit, pan),
        host.attach(hit, mousePan),
        removeListener,
        removeMouseListener,
        () => tracker.dispose(),
      );
    });
    // A tap on the track (or a mark) sets the value when it lifts. So a drag
    // is not the only pointer way to operate the slider (WCAG 2.2 SC 2.5.7).
    // UISlider ignores track taps. This departs from it.
    // A touch that moves past the tap's allowance, or that the page takes to
    // scroll, is no tap.
    const tap = new TapGestureRecognizer({
      name: 'slider-track-tap',
      allowedPointerTypes: ['touch', 'pen'],
      cancelsTouchesInView: false,
      // A touch that travels as far as a thumb's pan needs to begin is a
      // swipe, not a tap (UITapGestureRecognizer would allow 45 pt).
      allowableMovement: UIKIT_PAN.hysteresis.value,
      // A finger held on the track does nothing. So the tap takes no
      // selection lock: the control's own `user-select: none` already keeps
      // its text unselectable.
    });
    this.trackTap = tap;
    const removeTapListener = tap.addListener(current => {
      if (current.state === 'ended') {
        this.handleTrackTap(current);
      }
    });
    detachers.push(host.attach(parts.control, tap), removeTapListener, () => {
      this.trackTap = null;
    });
    // A layout can change the track's length mid-gesture, as when a value
    // label beside it takes a digit. The drawn parts follow before the next
    // paint, so nothing jumps at the hand-back.
    detachers.push(
      observeResize(parts.control, () => this.followTrackLength()),
    );
    return () => {
      // Interactions end first, so the cancel the recognizers send as they
      // detach finds nothing left to report.
      const ended = this.endSilently();
      for (const detach of detachers) {
        detach();
      }
      this.cancelLater(ended);
    };
  }

  /** Stops every interaction and animation without reporting (unmount). */
  dispose(): void {
    this.disposed = true;
    this.endSilently();
    for (const animator of this.animators.values()) {
      animator.dispose();
    }
    this.animators.clear();
  }

  /**
   * Ends every live interaction without a word to the owner, and returns
   * them. It runs from an Effect cleanup, where `onChange`, `onChangeEnd` and
   * a synchronous render have no place. A coast stops where it is drawn, and
   * the parts return to the stylesheet at the value the owner last rendered.
   */
  private endSilently(): ReadonlyArray<Interaction> {
    if (this.interactions.size === 0) {
      return [];
    }
    const ended = [...this.interactions.values()];
    const view = this.getParts()?.control.ownerDocument.defaultView;
    for (const interaction of this.interactions.values()) {
      const coast = interaction.coast;
      if (coast != null) {
        interaction.coast = null;
        view?.cancelAnimationFrame(coast.raf);
        for (const handle of coast.handles) {
          handle.stop();
        }
      }
      interaction.released = true;
    }
    this.interactions.clear();
    this.mouseOwners.clear();
    this.handBack();
    return ended;
  }

  /**
   * Ends the interactions a detach cancelled while the slider stays mounted,
   * as when it is disabled mid-drag. Each releases its pressed paint. If any
   * changed the value, `onChangeEnd` reports once. This waits until the
   * cleanup's task ends, and an unmount in the same commit drops it.
   */
  private cancelLater(ended: ReadonlyArray<Interaction>): void {
    if (ended.length === 0) {
      return;
    }
    queueMicrotask(() => {
      if (this.disposed) {
        return;
      }
      for (const interaction of ended) {
        this.model.commit(interaction.index, null);
      }
      this.releaseHeldAnchors();
      if (ended.some(interaction => interaction.changed)) {
        this.model.reportEnd();
      }
    });
  }

  /**
   * After the owner rendered an ended interaction's final value, the thumb
   * and the fill go back to the positions Slider's CSS gives them. Parts that
   * a coast of another thumb still drives stay with it.
   */
  private handBack(): void {
    for (const [element, animator] of this.animators) {
      if (
        [...this.interactions.values()].some(
          interaction =>
            (interaction.coast != null || !interaction.released) &&
            this.partsOf(interaction).has(element),
        )
      ) {
        continue;
      }
      // Ends the animator's translate at identity, then removes the inline
      // property. So the class's progress-driven translate shows again.
      animator.set({x: 0, y: 0});
      element.style.removeProperty('translate');
      // A Reduced Motion cross-fade wrote the opacity: end it at 1 and hand it
      // back too (a caught fade stops part-way).
      if (element.style.getPropertyValue('opacity') !== '') {
        animator.set({opacity: 1});
        element.style.removeProperty('opacity');
      }
      // A value tooltip mounts anew each time it opens.
      if (!element.isConnected) {
        animator.dispose();
        this.animators.delete(element);
      }
    }
  }

  /**
   * Releases the tooltip anchors that no live interaction holds. It runs in
   * the task of the hand-back that ends their tooltips' translates. So
   * anchor positioning takes over at the place each translate held.
   */
  private releaseHeldAnchors(): void {
    const live = [...this.interactions.values()].filter(
      interaction => interaction.coast != null || !interaction.released,
    );
    const released = [...this.heldAnchors].filter(
      index => !live.some(interaction => interaction.anchors.has(index)),
    );
    if (released.length === 0) {
      return;
    }
    for (const index of released) {
      this.heldAnchors.delete(index);
    }
    this.model.releaseAnchors(released);
  }

  // -- events ----------------------------------------------------------------

  private handleControlEvent(
    owner: number,
    event: ControlEvent,
    pointerType: PointerKind,
  ): void {
    if (event === 'touchDown') {
      // A mouse press holds the thumb too. Its highlight never lifts
      // the thumb (handleHighlight).
      const isMouse = pointerType === 'mouse';
      if (isMouse) {
        this.mouseOwners.add(owner);
      } else {
        this.mouseOwners.delete(owner);
      }
      this.begin(owner, isMouse, pointerType === 'touch');
      return;
    }
    const interaction = this.interactions.get(owner);
    if (interaction == null) {
      return;
    }
    switch (event) {
      case 'touchDragInside':
      case 'touchDragEnter':
        interaction.isInside = true;
        return;
      case 'touchDragOutside':
      case 'touchDragExit':
        interaction.isInside = false;
        return;
      case 'touchUpInside':
      case 'touchUpOutside':
        interaction.isInside = event === 'touchUpInside';
        // A press that never became a pan ends here (a tap or a hold).
        if (interaction.startValue == null) {
          this.finish(interaction, true);
        }
        return;
      case 'touchCancel':
        // The browser took the touch to scroll, or the press was cancelled
        // before the pan began. A begun pan reports its own cancel.
        if (interaction.startValue == null) {
          this.finish(interaction, false);
        }
        return;
      default:
        return;
    }
  }

  private handleHighlight(owner: number, isHighlighted: boolean): void {
    if (this.mouseOwners.has(owner)) {
      return;
    }
    const interaction = this.interactions.get(owner);
    const index = interaction?.index ?? owner;
    if (isHighlighted && interaction != null && !interaction.released) {
      this.lift(index);
    } else if (!isHighlighted && interaction == null) {
      this.drop(index);
    }
  }

  private handlePan(owner: number, pan: PanGestureRecognizer): void {
    const interaction = this.interactions.get(owner);
    if (interaction == null || interaction.released) {
      return;
    }
    switch (pan.state) {
      case 'began':
        interaction.startValue = interaction.value;
        {
          const total = pan.totalTranslation();
          const along = total[interaction.geometry.axis];
          const distance = Math.hypot(total.x, total.y);
          interaction.beganOffset = interaction.isMouse
            ? distance > 0
              ? (pan.hysteresis * along) / distance
              : 0
            : (along < 0 ? -1 : 1) * pan.hysteresis;
        }
        if (!interaction.isMouse) {
          this.lift(interaction.index);
        }
        this.track(interaction, pan);
        return;
      case 'changed':
        this.track(interaction, pan);
        return;
      case 'ended':
        interaction.released = true;
        this.release(interaction, pan);
        return;
      case 'cancelled':
        interaction.released = true;
        this.finish(interaction, true);
        return;
      case 'possible':
      case 'failed':
        return;
    }
  }

  /** UISlider's veto: an ancestor's pan or swipe along the travel. */
  private vetoes(recognizer: GestureRecognizer): boolean {
    // A touch on a thumb is the thumb's: a tap there changes nothing.
    if (recognizer === this.trackTap) {
      return true;
    }
    const horizontal = this.model.isHorizontal;
    // Told apart by kind, never by class: a screen-edge pan is a pan.
    if (recognizer.kind === 'swipe') {
      return (recognizer as SwipeGestureRecognizer).directions.some(
        direction =>
          horizontal
            ? direction === 'left' || direction === 'right'
            : direction === 'up' || direction === 'down',
      );
    }
    if (recognizer.kind === 'pan' || recognizer.kind === 'screenEdgePan') {
      const {x, y} = (recognizer as PanGestureRecognizer).translation();
      return horizontal
        ? Math.abs(x) >= Math.abs(y)
        : Math.abs(y) >= Math.abs(x);
    }
    return false;
  }

  // -- the interaction -------------------------------------------------------

  private begin(owner: number, isMouse = false, coasts = false): void {
    const parts = this.getParts();
    if (parts == null || this.model.isDisabled) {
      return;
    }
    // A finger on a coasting thumb stops it where it is: the coast ends on
    // that value, which the owner renders and onChangeEnd reports.
    for (const other of [...this.interactions.values()]) {
      if (other.coast != null) {
        this.finish(other, true, this.stopCoast(other));
      }
    }
    const geometry = this.measure(parts);
    const values = this.model.values();
    const value = values[owner] ?? this.model.min;
    this.interactions.set(owner, {
      owner,
      index: owner,
      geometry,
      startValue: null,
      beganOffset: 0,
      value,
      isInside: true,
      atEnd: this.endOf(value),
      changed: false,
      coast: null,
      released: false,
      isMouse,
      coasts,
      beganCoincident: this.model.isRange && values[0] === values[1],
      anchors: new Map(),
    });
    this.model.press(owner);
  }

  private track(interaction: Interaction, pan: PanGestureRecognizer): void {
    const {geometry} = interaction;
    const {min, max, isRange} = this.model;
    // A collapsed track has no length to map the travel onto.
    if (geometry.length <= 0) {
      return;
    }
    // UISlider counts the translation from the threshold itself (the
    // touch-down point plus the hysteresis, taken along the axis). So the
    // travel of the event that crossed it already counts.
    const translation =
      (pan.totalTranslation()[geometry.axis] - interaction.beganOffset) *
      geometry.sign;
    const startValue = interaction.startValue ?? interaction.value;
    const raw =
      startValue +
      (translation / geometry.length) * (max - min) * UIKIT_SLIDER.trackingGain;
    // A drag that began on two range thumbs sharing a value: its first
    // movement, which crosses the threshold, picks the thumb that can follow
    // it. The thumb on top cannot pass the other. Coming back past the other
    // thumb's value hands the drag to that thumb, which moves on. A drag that
    // began apart stops at the other thumb.
    let from: ReadonlyArray<number> | undefined;
    if (isRange && interaction.beganCoincident && raw !== startValue) {
      const values = this.model.values();
      const current = interaction.index;
      const index =
        values[0] === values[1] && !interaction.changed
          ? raw < startValue
            ? 0
            : 1
          : current === 1 && raw < (values[0] ?? raw)
            ? 0
            : current === 0 && raw > (values[1] ?? raw)
              ? 1
              : current;
      if (index !== current) {
        // Passing back over the other thumb leaves this one against it,
        // however far the move went, and the other moves on: one change
        // reports both.
        if (interaction.changed) {
          const against = this.model.constrain(current, values[index] ?? raw);
          interaction.value = against;
          this.place(interaction);
          const next = [...values];
          next[current] = against;
          from = next;
        }
        this.drop(current);
        interaction.index = index;
        interaction.value = values[index] ?? interaction.value;
        if (!interaction.isMouse) {
          this.lift(index);
        }
        this.model.press(index);
      }
    }
    this.record(interaction, this.model.constrain(interaction.index, raw), {
      from,
    });
    this.place(interaction);
  }

  /**
   * Writes the moving thumb's and the fill's positions for the
   * interaction's value straight to their translates: one visual update per
   * move, with no component render. The parts go back to
   * the stylesheet when the interaction ends (`handBack`).
   */
  private place(interaction: Interaction): void {
    const {geometry} = interaction;
    const {min, max} = this.model;
    const range = max - min;
    const pxPerValue = range > 0 ? geometry.travel / range : 0;
    const px = (interaction.value - min) * pxPerValue;
    for (const {element, at} of this.partMaps(interaction)) {
      this.animatorFor(element).set({[geometry.axis]: geometry.sign * at(px)});
    }
  }

  /**
   * Records a new value and plays the end haptic on entering an end.
   * Reports it through `onChange` unless the interaction's end commits it.
   * Returns whether the value changed.
   */
  private record(
    interaction: Interaction,
    value: number,
    {
      commits = false,
      from,
    }: {commits?: boolean; from?: ReadonlyArray<number>} = {},
  ): boolean {
    if (value === interaction.value) {
      return false;
    }
    interaction.value = value;
    interaction.changed = true;
    if (!commits) {
      this.model.change(interaction.index, value, from);
    }
    const end = this.endOf(value);
    // UISlider's end haptic belongs to a finger's or a pen's drag and its
    // coast. A mouse and a track tap play none.
    if (
      end != null &&
      end !== interaction.atEnd &&
      !interaction.isMouse &&
      interaction.startValue != null
    ) {
      playHaptic(UIKIT_SLIDER.endHaptic);
    }
    interaction.atEnd = end;
    return true;
  }

  private report(interaction: Interaction, value: number): void {
    this.record(interaction, value);
  }

  private release(interaction: Interaction, pan: PanGestureRecognizer): void {
    // A mouse's or a pen's drag ends at its release, where the pointer lets
    // go: only a finger's release coasts. A pen's
    // thumb, lifted while held, drops back first.
    if (!interaction.coasts) {
      if (!interaction.isMouse) {
        this.drop(interaction.index);
      }
      this.model.press(null);
      this.finish(interaction, true);
      return;
    }
    const {geometry, index} = interaction;
    const {min, max} = this.model;
    const range = max - min;
    this.drop(index);
    this.model.press(null);
    const location = pan.location();
    const expansion = UIKIT_CONTROL.trackingExpansion.value;
    const inside =
      location.x >= geometry.rect.left - expansion &&
      location.x <= geometry.rect.right + expansion &&
      location.y >= geometry.rect.top - expansion &&
      location.y <= geometry.rect.bottom + expansion;
    interaction.isInside = inside;
    // Finger velocity along increasing value, px/s.
    const velocity = pan.velocity()[geometry.axis] * geometry.sign;
    const projected = inside
      ? UIKIT_SLIDER.releaseProjectionShare *
        projectDistance(velocity, UIKIT_SLIDER.releaseProjectionRate)
      : 0;
    const from = interaction.value;
    // Value per px of finger travel. A collapsed track maps none, so it
    // coasts nowhere.
    const valuePerPx =
      geometry.length > 0
        ? (range * UIKIT_SLIDER.trackingGain) / geometry.length
        : 0;
    const target = this.model.constrain(index, from + projected * valuePerPx);
    // In the thumb's px: the value's velocity mapped onto the travel.
    const pxPerValue = range > 0 ? geometry.travel / range : 0;
    const valueVelocity = velocity * valuePerPx;
    this.coastTo(interaction, target, valueVelocity * pxPerValue, true);
  }

  /**
   * A tap on the track: the thumb the tap's value picks springs there, on
   * the release spring from rest. It reports as a coast does, and
   * `onChangeEnd` follows. A tap on the thumb's own value changes nothing.
   */
  private handleTrackTap(tap: TapGestureRecognizer): void {
    const parts = this.getParts();
    if (parts == null || this.model.isDisabled || this.interactions.size > 0) {
      return;
    }
    const {x, y} = tap.location();
    const raw = this.model.valueAt(x, y);
    const index = this.model.thumbFor(raw);
    const target = this.model.constrain(index, raw);
    const value = this.model.values()[index] ?? this.model.min;
    if (target === value) {
      return;
    }
    const interaction: Interaction = {
      owner: index,
      index,
      geometry: this.measure(parts),
      startValue: null,
      beganOffset: 0,
      value,
      isInside: true,
      atEnd: this.endOf(value),
      changed: false,
      coast: null,
      released: true,
      isMouse: false,
      coasts: false,
      beganCoincident: false,
      anchors: new Map(),
    };
    this.interactions.set(index, interaction);
    // A tap's value change happens in place. So under Reduce Motion it
    // applies at once, with no spring and no cross-fade.
    const thumb = parts.thumbs[index];
    if (thumb != null && this.animatorFor(thumb).reducedMotion() !== 'off') {
      this.finish(interaction, true, target);
      return;
    }
    this.coastTo(interaction, target, 0, false);
  }

  /**
   * Springs the interaction's thumb from its value to `target`, on the
   * compositor and clamped, starting at `velocityPx` (px/s along the
   * travel). `onChange` follows from the coast's fourth frame, and the
   * interaction ends (`onChangeEnd`) on its last. `touchRelease` means a
   * finger's release started it. Then the coast continues the throw and
   * keeps moving under Reduce Motion. A tap's spring never runs there
   * (`handleTrackTap` sets the value at once).
   */
  private coastTo(
    interaction: Interaction,
    target: number,
    velocityPx: number,
    touchRelease: boolean,
  ): void {
    const {geometry, index} = interaction;
    const {min, max} = this.model;
    const range = max - min;
    const pxPerValue = range > 0 ? geometry.travel / range : 0;
    const from = interaction.value;
    const fromPx = (from - min) * pxPerValue;
    const toPx = (target - min) * pxPerValue;
    const [lowerValue, upperValue] = this.model.bounds(index);
    const curve = sliderCoastCurve({
      from: fromPx,
      to: toPx,
      velocity: velocityPx,
      lower: (lowerValue - min) * pxPerValue,
      upper: (upperValue - min) * pxPerValue,
      // The coast plays the `springs.sliderRelease` role, resolved as it
      // starts.
      spring: resolveMotion(this.getParts()?.control, SLIDER_RELEASE_SPRING),
    });
    const moves =
      Math.abs(toPx - fromPx) >= MIN_COAST_PX ||
      Math.max(Math.abs(curve.at(0.05) - fromPx), 0) >= MIN_COAST_PX;
    if (!moves) {
      this.finish(interaction, true, target);
      return;
    }
    const at = performance.now();
    const handles = this.playCoast(interaction, curve, touchRelease, at);
    if (handles.length === 0) {
      this.finish(interaction, true, target);
      return;
    }
    const coast: Coast = {
      handles,
      target,
      frames: 0,
      raf: 0,
      curve,
      travel: geometry.travel,
      at,
      touchRelease,
    };
    interaction.coast = coast;
    const view = this.getParts()?.control.ownerDocument.defaultView;
    const step = () => {
      if (interaction.coast !== coast) {
        return;
      }
      coast.frames += 1;
      if (coast.frames > HAND_OFF_FRAMES) {
        const {axis, travel} = interaction.geometry;
        const px = Math.abs(coast.handles[0]?.value(axis) ?? 0);
        const value =
          range > 0 && travel > 0
            ? min + (px / travel) * range
            : interaction.value;
        this.report(interaction, this.model.constrain(index, value));
      }
      coast.raf = view?.requestAnimationFrame(step) ?? 0;
    };
    coast.raf = view?.requestAnimationFrame(step) ?? 0;
    this.endCoastWithThumb(interaction, coast);
  }

  /** Ends the coast when its thumb's motion finishes, not when it stops. */
  private endCoastWithThumb(interaction: Interaction, coast: Coast): void {
    const thumbHandle = coast.handles[0];
    void thumbHandle?.finished.then(finished => {
      if (
        interaction.coast !== coast ||
        coast.handles[0] !== thumbHandle ||
        !finished
      ) {
        return;
      }
      this.getParts()?.control.ownerDocument.defaultView?.cancelAnimationFrame(
        coast.raf,
      );
      interaction.coast = null;
      this.finish(interaction, true, coast.target);
    });
  }

  /**
   * After the track's length changed: every live interaction measures it
   * again. A drag writes its parts for the new length, and a coast plays
   * on from where its curve is now, scaled to the new travel.
   */
  private followTrackLength(): void {
    const parts = this.getParts();
    if (parts == null || this.interactions.size === 0) {
      return;
    }
    for (const interaction of this.interactions.values()) {
      const geometry = this.measure(parts);
      if (geometry.length === interaction.geometry.length) {
        continue;
      }
      interaction.geometry = geometry;
      const {coast} = interaction;
      if (coast != null) {
        const scale = coast.travel > 0 ? geometry.travel / coast.travel : 1;
        const {curve} = coast;
        coast.curve = {
          duration: curve.duration,
          at: t => curve.at(t) * scale,
          velocity: t => curve.velocity(t) * scale,
        };
        coast.travel = geometry.travel;
        coast.handles = this.playCoast(
          interaction,
          coast.curve,
          coast.touchRelease,
          coast.at,
        );
        this.endCoastWithThumb(interaction, coast);
      } else if (!interaction.released) {
        this.place(interaction);
      }
    }
  }

  /**
   * Plays the coast on the thumb and the fill parts, on one clock that
   * started at `at`. A re-mapped coast plays on from where its curve is.
   */
  private playCoast(
    interaction: Interaction,
    curve: MotionCurve,
    touchRelease: boolean,
    at: number,
  ): MotionHandle[] {
    const {axis, sign} = interaction.geometry;
    const handles: MotionHandle[] = [];
    for (const {element, at: position, slope} of this.partMaps(interaction)) {
      const partCurve: MotionCurve = {
        duration: curve.duration,
        at: t => sign * position(curve.at(t)),
        velocity: t => sign * slope * curve.velocity(t),
      };
      const animator = this.animatorFor(element);
      animator.set({[axis]: partCurve.at(0)});
      // A release's coast continues the throw: momentum, which keeps moving
      // under Reduce Motion. A tap's spring is a
      // transition.
      handles.push(
        touchRelease
          ? animator.decay({[axis]: partCurve}, {at, touchRelease})
          : animator.play({[axis]: partCurve}, {at}),
      );
    }
    return handles;
  }

  /**
   * The parts that move with the interaction's thumb. Each has its translate
   * as a function of the thumb's px along the travel (`p`), and that
   * function's slope. The formulas are the same as Slider's CSS.
   */
  private partMaps(interaction: Interaction): {
    element: HTMLElement;
    at: (p: number) => number;
    slope: number;
  }[] {
    const parts = this.getParts();
    if (parts == null) {
      return [];
    }
    const {geometry, index} = interaction;
    const {length, travel} = geometry;
    const inset = this.model.thumbSize / 2;
    const values = this.model.values();
    const {min, max, isRange} = this.model;
    const range = max - min;
    const pxPerValue = range > 0 ? travel / range : 0;
    const otherPx = ((values[index === 0 ? 1 : 0] ?? min) - min) * pxPerValue;
    const maps: {
      element: HTMLElement;
      at: (p: number) => number;
      slope: number;
    }[] = [];
    const add = (
      element: HTMLElement | null | undefined,
      at: (p: number) => number,
      slope: number,
    ) => {
      if (element != null) {
        maps.push({element, at, slope});
      }
    };
    add(parts.thumbs[index], p => p, 1);
    const tooltip = parts.tooltips[index];
    if (tooltip != null) {
      const anchored = this.anchorFor(interaction);
      if (anchored != null) {
        // The tooltip's anchor stays where it was held. The tooltip moves
        // with the thumb by translate.
        add(tooltip, p => p - anchored * travel, 1);
      }
    }
    if (isRange) {
      if (index === 0) {
        add(parts.fillMover, p => inset + p, 1);
        add(parts.fill, p => otherPx - p - length, -1);
      } else {
        add(parts.fill, p => p - otherPx - length, 1);
      }
    } else {
      add(parts.fill, p => inset + p - length, 1);
    }
    return maps;
  }

  /**
   * Stops a coast where the browser draws the thumb in this frame. Returns
   * the value there for `finish` to end on, or null when the travel has no
   * length. The animator's own reading can run a frame ahead of or behind
   * what is drawn, and a finger stops what it sees.
   */
  private stopCoast(interaction: Interaction): number | null {
    const coast = interaction.coast;
    if (coast == null) {
      return null;
    }
    interaction.coast = null;
    this.getParts()?.control.ownerDocument.defaultView?.cancelAnimationFrame(
      coast.raf,
    );
    const {geometry, index} = interaction;
    const {min, max} = this.model;
    const thumb = this.getParts()?.thumbs[index];
    const drawn = thumb == null ? null : drawnTranslate(thumb, geometry.axis);
    const px = Math.abs(drawn ?? coast.handles[0]?.value(geometry.axis) ?? 0);
    for (const handle of coast.handles) {
      handle.stop();
    }
    const range = max - min;
    return range > 0 && geometry.travel > 0
      ? this.model.constrain(index, min + (px / geometry.travel) * range)
      : null;
  }

  /**
   * Ends an interaction from the handler that ends it: the lift, the cancel
   * or the coast's last frame. The owner renders the last value at once, and
   * the parts return to the stylesheet. `onChangeEnd` then reports what the
   * owner rendered, unless the browser took the touch before any drag
   * (`report` false).
   */
  private finish(
    interaction: Interaction,
    report: boolean,
    finalValue: number | null = null,
  ): void {
    if (this.interactions.get(interaction.owner) !== interaction) {
      return;
    }
    this.interactions.delete(interaction.owner);
    if (!interaction.released) {
      this.drop(interaction.index);
    }
    interaction.released = true;
    if (finalValue != null) {
      this.record(interaction, finalValue, {commits: true});
    }
    // The owner renders the final value from this handler even when a
    // frame's report already carried it: these handlers run outside React's
    // events. So that report's render can still be pending, and onChangeEnd
    // reads what the owner rendered.
    this.model.commit(interaction.index, finalValue);
    this.handBack();
    this.releaseHeldAnchors();
    if (report) {
      this.model.reportEnd();
    }
  }

  // -- the thumb's lift --------------------------------------------------------

  private lift(index: number): void {
    const thumb = this.getParts()?.thumbs[index];
    if (thumb == null) {
      return;
    }
    const animator = this.animatorFor(thumb);
    // The lift is feedback with no fade of its own. Under Reduce Motion the
    // press shows in the pressed paint alone, and a change of state never
    // scales.
    if (animator.reducedMotion() !== 'off') {
      return;
    }
    animator.animate(
      {scale: UIKIT_SLIDER.liftScale},
      {spring: resolveMotion(this.getParts()?.control, SLIDER_LIFT_SPRING)},
    );
  }

  private drop(index: number): void {
    const thumb = this.getParts()?.thumbs[index];
    if (thumb == null) {
      return;
    }
    const animator = this.animators.get(thumb);
    if (animator == null || animator.get('scale') === 1) {
      return;
    }
    animator.animate(
      {scale: 1},
      {spring: resolveMotion(this.getParts()?.control, SLIDER_DROP_SPRING)},
    );
  }

  // -- helpers -----------------------------------------------------------------

  private measure(parts: SliderTouchParts): Geometry {
    const {control} = parts;
    const horizontal = this.model.isHorizontal;
    // The layout size (unrounded, untransformed): the size the CSS's
    // container units resolve against.
    const style = control.ownerDocument.defaultView?.getComputedStyle(control);
    const rect = control.getBoundingClientRect();
    const used = (horizontal ? style?.width : style?.height) ?? '';
    const length = used.endsWith('px')
      ? parseFloat(used)
      : horizontal
        ? rect.width
        : rect.height;
    return {
      length,
      travel: Math.max(0, length - this.model.thumbSize),
      axis: horizontal ? 'x' : 'y',
      sign: horizontal ? (isRtlElement(control) ? -1 : 1) : -1,
      rect,
    };
  }

  private endOf(value: number): 'min' | 'max' | null {
    if (value <= this.model.min) {
      return 'min';
    }
    if (value >= this.model.max) {
      return 'max';
    }
    return null;
  }

  private animatorFor(element: HTMLElement): Animator {
    let animator = this.animators.get(element);
    if (animator == null) {
      animator = createMotionEngine(element);
      this.animators.set(element, animator);
    }
    return animator;
  }

  /**
   * Where the interaction's thumb's tooltip anchor is held, as progress.
   * The first call for a thumb holds it, where the owner last rendered it.
   */
  private anchorFor(interaction: Interaction): number | null {
    const {anchors, index} = interaction;
    if (!anchors.has(index)) {
      const held = this.model.holdAnchor(index);
      anchors.set(index, held);
      if (held != null) {
        this.heldAnchors.add(index);
      }
    }
    return anchors.get(index) ?? null;
  }

  private partsOf(interaction: Interaction): Set<HTMLElement> {
    const parts = this.getParts();
    const set = new Set<HTMLElement>();
    if (parts == null) {
      return set;
    }
    const thumb = parts.thumbs[interaction.index];
    const tooltip = interaction.anchors.has(interaction.index)
      ? parts.tooltips[interaction.index]
      : null;
    for (const element of [thumb, parts.fillMover, parts.fill, tooltip]) {
      if (element != null) {
        set.add(element);
      }
    }
    return set;
  }
}