Skip to content

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

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

'use client';

/**
 * @file useSegmentedSelectionMotion.ts
 * @input The radiogroup, the selected value, the presentation and tracking
 *   flags; the animator, the UIKit table and the touch tracking
 * @output Exports `useSegmentedSelectionMotion`, `SegmentedSelectionMotion`,
 *   the layer custom properties and the segment and title selectors
 * @position SegmentedControl's touch layer
 *
 * SYNC: When modified, update:
 * - /packages/core/src/SegmentedControl/SegmentedControl.tsx (the pseudo-elements)
 * - /packages/core/src/SegmentedControl/SegmentedControlItem.tsx (the title marker)
 * - /packages/core/src/SegmentedControl/useSegmentedTouchTracking.ts
 */

import {
  useCallback,
  useEffect,
  useRef,
  useState,
  type RefCallback,
  type RefObject,
} from 'react';
import {
  createMotionEngine,
  type AnimateOptions,
  type Animator,
  type MotionHandle,
  type MotionValues,
  type SpringTransition,
} from '../motion/animator';
import {
  registerSegmentedTable,
  segmentedControl,
} from '../motion/uikit/segmented';
import {registerSpringsTable, springs} from '../motion/uikit/springs';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {observeResize} from '../utils/sharedResizeObserver';
import {titleOfSegment} from '../privateAttributes/segmentTitle.stylex';
import {mapProgress, mapRange} from '../motion/progress';
import {easedProgress, readThemeTiming} from '../motion/themeTiming';
import {useSegmentedTouchTracking} from './useSegmentedTouchTracking';

/** The segments, in DOM order. */
export const SEGMENT_SELECTOR = '[role="radio"][data-value]';
/**
 * The selected face moves to another segment only when the lens's center is
 * this far past the boundary. The distance is a quarter of that segment's
 * width, at least 8 px.
 */
const FACE_HYSTERESIS_RATIO = 0.25;
const FACE_HYSTERESIS_MIN_PX = 8;

/** The selected surface's paint, copied into a layer's custom properties. */
export const SURFACE_PROPERTIES: ReadonlyArray<string> = [
  'background-color',
  'background-image',
  'background-position',
  'background-size',
  'background-repeat',
  'background-origin',
  'background-clip',
  'box-shadow',
  'border-top-left-radius',
  'border-top-right-radius',
  'border-bottom-right-radius',
  'border-bottom-left-radius',
  'border-top-width',
  'border-right-width',
  'border-bottom-width',
  'border-left-width',
  'border-top-style',
  'border-right-style',
  'border-bottom-style',
  'border-left-style',
  'border-top-color',
  'border-right-color',
  'border-bottom-color',
  'border-left-color',
  'backdrop-filter',
  '-webkit-backdrop-filter',
];

/**
 * The radiogroup's two pseudo-element layers: the lens (::before) and the
 * ::after, which under Reduced Motion shows the surface that fades out where
 * it is.
 */
export type Layer = 'lens' | 'after';

/** Box and visibility of a layer, besides its paint. */
export const LAYER_GEOMETRY: ReadonlyArray<string> = [
  'left',
  'top',
  'width',
  'height',
  'visibility',
];

/** The custom property on the radiogroup that sets `property` of `layer`. */
export function layerVariable(layer: Layer, property: string): string {
  return `--_segmented-${layer}-${property.replace(/^-+/, '')}`;
}

/**
 * What the destination segment shows while the lens carries its surface.
 * Written inline with priority so a theme's rule for the selected segment
 * cannot paint a second surface; borders keep their width so nothing moves.
 */
const HIDDEN_SURFACE: ReadonlyArray<readonly [string, string]> = [
  ['background-color', 'transparent'],
  ['background-image', 'none'],
  ['box-shadow', 'none'],
  ['border-top-color', 'transparent'],
  ['border-right-color', 'transparent'],
  ['border-bottom-color', 'transparent'],
  ['border-left-color', 'transparent'],
  ['backdrop-filter', 'none'],
  ['-webkit-backdrop-filter', 'none'],
];

/** A title's face: what a dragging finger moves between titles. */
interface TitleFace {
  readonly color: string;
  readonly fontWeight: string;
}

/** A box in the track's padding-box coordinates, in CSS px. */
interface Box {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

interface Carried {
  /** The segment the lens is bound for: it lands there at rest. */
  readonly segment: HTMLElement;
  /**
   * The lens's layout box: the segment's, so it lands at translate 0 from
   * the segment and scale 1, the segment's own size.
   */
  readonly box: Box;
  /**
   * The segment whose surface the lens shows, hidden there meanwhile: the
   * selected one. A touch moves the lens before the new value comes back,
   * so until then this is still the old selection.
   */
  hidden: HTMLElement;
  /** The track's layout size when the box was measured. */
  readonly trackSize: {readonly width: number; readonly height: number};
}

/** A finger's touch, from landing to letting go. */
interface Touch {
  /** The track's geometry when the finger landed (read once). */
  readonly toTrackX: (clientX: number) => number;
  readonly boxes: ReadonlyMap<HTMLElement, Box>;
  /** The segment the finger landed on, if any (the tracker's begin target). */
  readonly origin: HTMLElement | null;
  /** Whether it landed on the selected segment (a drag carries the lens). */
  readonly carriesLens: boolean;
  /** A finger pressed: under Reduced Motion its release cross-fades. */
  readonly isFinger: boolean;
  /** The selected title's face and an unselected one, read at landing. */
  readonly faces: {
    readonly selected: TitleFace;
    readonly unselected: TitleFace;
  } | null;
}

/**
 * The motion a release starts after its commit's click runs. It aims at the
 * destination's box when the new value shows, because the titles' new weights
 * move the segments. Until the value comes back, it aims at the box measured
 * at landing.
 */
interface Pending {
  readonly destination: HTMLElement;
  /** The destination's box when the finger landed. */
  readonly box: Box;
  /** The held lens settles there; otherwise it slides from `from`. */
  readonly isHeld: boolean;
  /** The selected segment's box: where a tap's slide starts. */
  readonly from: Box | null;
  /** A finger released it: under Reduced Motion it cross-fades. */
  readonly touchRelease: boolean;
}

function faceOf(element: HTMLElement): TitleFace {
  const style = getComputedStyle(element);
  return {color: style.color, fontWeight: style.fontWeight};
}

/**
 * A hidden segment's own inline declarations (its `style`) for the properties
 * `hideSurface` overrides: value and priority, restored by `showSurface`.
 */
const ownSurface = new WeakMap<
  HTMLElement,
  ReadonlyArray<readonly [property: string, value: string, priority: string]>
>();

function hideSurface(segment: HTMLElement): void {
  if (!ownSurface.has(segment)) {
    ownSurface.set(
      segment,
      HIDDEN_SURFACE.map(([property]) => [
        property,
        segment.style.getPropertyValue(property),
        segment.style.getPropertyPriority(property),
      ]),
    );
  }
  for (const [property, value] of HIDDEN_SURFACE) {
    segment.style.setProperty(property, value, 'important');
  }
}

/** Gives a hidden segment its surface back, its own inline values included. */
function showSurface(segment: HTMLElement): void {
  const own = ownSurface.get(segment);
  if (own == null) {
    return;
  }
  ownSurface.delete(segment);
  for (const [property, value, priority] of own) {
    if (value === '') {
      segment.style.removeProperty(property);
    } else {
      segment.style.setProperty(property, value, priority);
    }
  }
}

/**
 * Paints `layer` with `segment`'s computed surface. All values are read
 * before any is written. A write to the track's style makes the next
 * computed-style read recompute. Interleaved reads and writes restyle the
 * control once per property.
 */
function paintLayer(
  track: HTMLElement,
  layer: Layer,
  segment: HTMLElement,
): void {
  const style = getComputedStyle(segment);
  const values = SURFACE_PROPERTIES.map(property =>
    style.getPropertyValue(property),
  );
  SURFACE_PROPERTIES.forEach((property, index) => {
    track.style.setProperty(layerVariable(layer, property), values[index]);
  });
}

/** Copies the lens's paint onto the ::after. */
function copyLensPaint(track: HTMLElement): void {
  for (const property of SURFACE_PROPERTIES) {
    track.style.setProperty(
      layerVariable('after', property),
      track.style.getPropertyValue(layerVariable('lens', property)),
    );
  }
}

/** Lays `layer` out on `box` and shows it. */
function placeLayer(track: HTMLElement, layer: Layer, box: Box): void {
  track.style.setProperty(layerVariable(layer, 'left'), `${box.x}px`);
  track.style.setProperty(layerVariable(layer, 'top'), `${box.y}px`);
  track.style.setProperty(layerVariable(layer, 'width'), `${box.width}px`);
  track.style.setProperty(layerVariable(layer, 'height'), `${box.height}px`);
  track.style.setProperty(layerVariable(layer, 'visibility'), 'visible');
}

/** Hides `layer` and drops its custom properties. */
function clearLayer(track: HTMLElement, layer: Layer): void {
  for (const property of [...LAYER_GEOMETRY, ...SURFACE_PROPERTIES]) {
    track.style.removeProperty(layerVariable(layer, property));
  }
}

/**
 * The scale an ancestor transform applies to the track's client rects. The
 * lens lays out untransformed. `offsetWidth` rounds to whole pixels, so a
 * fractional track width reads as a scale slightly off 1. Only a real
 * transform moves it further than that rounding.
 */
function scaleOf(track: HTMLElement, rect: DOMRect): number {
  if (track.offsetWidth <= 0 || rect.width <= 0) {
    return 1;
  }
  return Math.abs(rect.width - track.offsetWidth) <= 1
    ? 1
    : rect.width / track.offsetWidth;
}

/** Boxes relative to the track's padding box. */
function boxesIn(track: HTMLElement): (element: HTMLElement) => Box {
  const trackRect = track.getBoundingClientRect();
  const scale = scaleOf(track, trackRect);
  return element => {
    const rect = element.getBoundingClientRect();
    return {
      x: (rect.left - trackRect.left) / scale - track.clientLeft,
      y: (rect.top - trackRect.top) / scale - track.clientTop,
      width: rect.width / scale,
      height: rect.height / scale,
    };
  };
}

/** Maps a client x to the track's padding-box x, read once per touch. */
function trackXIn(track: HTMLElement): (clientX: number) => number {
  const rect = track.getBoundingClientRect();
  const scale = scaleOf(track, rect);
  return clientX => (clientX - rect.left) / scale - track.clientLeft;
}

function segmentsOf(track: HTMLElement): HTMLElement[] {
  return Array.from(track.querySelectorAll<HTMLElement>(SEGMENT_SELECTOR));
}

function isLaidOut(box: Box): boolean {
  return box.width > 0 && box.height > 0;
}

function center(box: Box): number {
  return box.x + box.width / 2;
}

/** Whether two boxes are the same to a quarter of a pixel. */
function isSameBox(a: Box, b: Box): boolean {
  return (
    Math.abs(a.x - b.x) < 0.25 &&
    Math.abs(a.y - b.y) < 0.25 &&
    Math.abs(a.width - b.width) < 0.25 &&
    Math.abs(a.height - b.height) < 0.25
  );
}

function isEnabledSegment(segment: HTMLElement): boolean {
  return (
    !segment.hasAttribute('disabled') &&
    segment.getAttribute('aria-disabled') !== 'true'
  );
}

const titleOf = titleOfSegment;

/** A theme that gives the segments no transition: the lens lands at once. */
const INSTANT = easedProgress(0.001, progress => progress);

/** What the control reads of its selection motion. */
export interface SegmentedSelection {
  /**
   * A press is down on the control (any pointer's), or its tap's click has
   * not run yet. The press commits through that click, so a focus move it
   * causes selects nothing.
   */
  readonly isPressing: () => boolean;
  /** A key went down: a focus move it causes is the keyboard's, and selects. */
  readonly keyPressed: () => void;
}

export interface SegmentedSelectionMotionOptions {
  /** The animator's clock (ms, document timeline); `performance.now()` by default. */
  readonly now?: () => number;
  /**
   * The animator for the radiogroup's ::after (the surface that fades out
   * under Reduced Motion); one of its own by default.
   */
  readonly afterAnimator?: Animator;
}

function defaultNow(): number {
  return typeof performance === 'undefined' ? Date.now() : performance.now();
}

/**
 * The selection motion of one SegmentedControl, as UIKit's segmented control
 * moves it. It lives outside React's render cycle. Nothing here sets state,
 * so a slide never re-renders anything.
 *
 * At rest, the selected segment paints its own surface, so themes style it
 * as before. For a slide, the lens takes over. The lens is the radiogroup's
 * ::before, painted from custom properties copied from the segment's
 * computed surface. The segment hides its own surface inline, so a theme
 * rule cannot keep it painted. The lens moves with `translate` and `scale`
 * on the compositor animator. Nothing lays out or paints per frame, and the
 * slide keeps moving while JavaScript is busy. The lens lays out on the
 * destination's box. It lands at translate 0 and scale 1 and hands the
 * surface back pixel for pixel. Its position and its size run on separate
 * springs, as UIKit's do. A change mid-flight starts from the presented
 * geometry and its velocities. The titles change with the selection, at
 * once.
 *
 * Under a finger:
 * - A theme role owns a pressed thumb's lift, so a press on the selected
 *   segment lifts nothing here.
 * - A drag from the selected segment carries the lens at its resting size.
 *   Its center chases the finger, at most `dragOvershoot` past the end
 *   segments.
 * - The selected title's color follows the lens's center. It moves to a
 *   neighbor only once the center is a quarter of that segment past the
 *   boundary. Every title keeps its weight until the lift.
 * - The lift commits the segment nearest the finger, through that segment's
 *   click. A lift outside the control commits nothing, and the lens settles
 *   back.
 * - A press on another segment leaves the lens in place until the lift.
 *   Meanwhile that segment shows the shared pressed overlay.
 * - A click that the item cancels sends the lens back at once. Otherwise the
 *   lens waits for the new value, which a parent can adopt later. It goes
 *   back only if the slide settles without the new value.
 * - A cancelled touch puts the lens back.
 *
 * Under a mouse or a pen, the same press commits the same segment, but the
 * theme owns the timing. A click, a key or a new value slides the lens on the
 * theme's duration and easing, as the segments' own transition does. A drag
 * from the selected segment carries the lens on the pointer itself.
 *
 * Under Reduced Motion, a held lens still follows the pointer: that is direct
 * movement, not a transition. Nothing else chases, travels or scales. The lens
 * fades in at the new segment while ::after, painted with the old surface,
 * fades out in place. With a fine pointer under Reduce Motion, a change shows
 * through the theme's transition.
 */
export class SegmentedSelectionMotion {
  private track: HTMLElement | null = null;
  private carried: Carried | null = null;
  /**
   * Segments whose surface the lens carried until a change turned it
   * elsewhere. They keep their surface hidden until the lens lands. A tap's
   * press paint can still fade on such a segment. That paint would cover the
   * lens, which sits under the segments' backgrounds, while the lens crosses
   * it.
   */
  private readonly abandoned = new Set<HTMLElement>();
  /** The segment showing the selected face under a dragging finger. */
  private facedSegment: HTMLElement | null = null;
  /** The frame request that keeps the face on the lens while it is carried. */
  private lensFrame: number | null = null;
  /** Titles wearing the other face's color during a drag. */
  private readonly faceOverrides = new Set<HTMLElement>();
  /** The motions the hand-back waits for. */
  private readonly running = new Set<MotionHandle>();
  /** A finger holds the lens: a drag from the selected segment carries it. */
  private isHeld = false;
  /**
   * The touch presentation applies (a coarse primary pointer), so every
   * change slides on UIKit's springs. When it is off, a change slides on the
   * theme's duration and easing, as the segments' transition does. A drag from
   * the selected segment carries the lens on the pointer itself.
   */
  private isPresenting = true;
  /**
   * Segments whose own transitions are off while a fine pointer's carry is
   * on screen, with their own inline values to give back.
   */
  private readonly stilled = new Map<HTMLElement, readonly [string, string]>();
  /** The frame request that gives the stilled segments their transitions back. */
  private thawFrame: number | null = null;
  private touch: Touch | null = null;
  /**
   * The value a touch already moved the lens to: the selection change that
   * follows (the controlled value coming back) re-aims the lens.
   */
  private committed: string | null = null;
  /**
   * The commit's click ran without a veto: the lens waits for the value
   * until the slide settles.
   */
  private isAwaitingValue = false;
  /** The motion a release starts once its commit's click has run. */
  private pending: Pending | null = null;
  /** The last release was a finger's (decline and re-aim follow it). */
  private releasedByFinger = true;
  /** The ::after shows the leaving surface (Reduced Motion). */
  private isLeavingShown = false;
  /** Bumped by every leaving fade; a finished fade clears only its own. */
  private leaving = 0;

  private readonly now: () => number;
  /** The ::after: the surface fading out under Reduced Motion. */
  private readonly after: Animator;

  constructor(
    private readonly animator: Animator = createMotionEngine(null, {
      pseudoElement: '::before',
    }),
    options: SegmentedSelectionMotionOptions = {},
  ) {
    // The chase plays the shared `springs.fingerTracking` role, which
    // registers as its module loads. The slide plays the segmented role, which
    // registers here before the first animation. A second call does nothing.
    registerSpringsTable();
    registerSegmentedTable();
    this.now = options.now ?? defaultNow;
    this.after =
      options.afterAnimator ??
      createMotionEngine(null, {
        pseudoElement: '::after',
        initial: {opacity: 0},
      });
  }

  /** Attaches the radiogroup whose pseudo-elements are the lens (null detaches). */
  attachTrack(element: HTMLElement | null): void {
    if (element !== this.track) {
      this.settle();
    }
    this.track = element;
    this.animator.attach(element);
    this.after.attach(element);
  }

  /** True while the lens carries the selected surface. */
  get isSliding(): boolean {
    return this.carried != null;
  }

  /** A press (any pointer's) is down on the control, from landing to letting go. */
  get isPressed(): boolean {
    return this.touch != null;
  }

  /**
   * Whether the touch presentation applies. Off, under a fine primary
   * pointer, a change slides on the theme's timing, and a drag from the
   * selected segment still carries the lens. A change of presentation hands
   * anything in flight back.
   */
  present(isPresenting: boolean): void {
    if (this.isPresenting === isPresenting) {
      return;
    }
    this.isPresenting = isPresenting;
    this.settle();
  }

  /** The segment that commits `value`, if the track has one. */
  segmentFor(track: HTMLElement, value: string): HTMLElement | null {
    return (
      segmentsOf(track).find(segment => segment.dataset.value === value) ?? null
    );
  }

  /** The selection moved from `from` to `to`; the DOM already shows `to`. */
  select(track: HTMLElement, from: string, to: string): void {
    if (this.track !== track) {
      return;
    }
    const origin = this.segmentFor(track, from);
    const destination = this.segmentFor(track, to);
    const isTouchCommit = this.committed === to;
    // The commit's own styles take over from a drag's borrowed faces.
    this.clearFaces();
    this.committed = null;
    this.isAwaitingValue = false;
    if (isTouchCommit) {
      if (this.pending?.destination === destination && destination != null) {
        // Adopted during the click: the lens moves now, on the box the
        // destination has with the new value shown.
        this.startPending(destination, boxesIn(track)(destination));
      }
      // The new selection now paints the surface the lens carries, and its
      // titles' weights may have moved the segments since the lens set off.
      const carried = this.carried;
      if (carried != null && carried.segment === destination) {
        if (carried.hidden !== destination) {
          showSurface(carried.hidden);
          paintLayer(track, 'lens', destination);
          hideSurface(destination);
          carried.hidden = destination;
        }
        this.reaim(track, destination);
      }
      return;
    }
    if (!this.slidesChanges()) {
      // A fine pointer under Reduce Motion: the theme's transition shows the
      // change.
      this.settle();
      return;
    }
    if (destination == null) {
      // Nothing is selected any more: no surface to carry.
      this.settle();
      return;
    }
    if (this.carried == null && origin == null) {
      // Nothing was selected: there is no surface to slide from.
      return;
    }
    const boxOf = boxesIn(track);
    const to_ = boxOf(destination);
    if (!isLaidOut(to_)) {
      this.settle();
      return;
    }
    const from_ = this.carried == null ? boxOf(origin as HTMLElement) : null;
    if (this.animator.reducedMotion() !== 'off') {
      this.crossFadeTo(destination, to_, from_, destination, false);
      return;
    }
    const at = this.carry(destination, to_, from_, destination);
    // A programmatic or keyboard change: the whole box slides.
    this.settleLens(destination, {at});
  }

  /**
   * Whether a change of value slides the lens. A fine pointer under Reduce
   * Motion leaves the change to the theme's transition.
   */
  private slidesChanges(): boolean {
    return this.isPresenting || this.animator.reducedMotion() === 'off';
  }

  /**
   * A press landed on `origin`, the segment the action-group tracker resolved
   * for it (null: none). It reads the track's geometry and title faces once.
   * Under Reduced Motion a finger's release cross-fades.
   */
  begin(track: HTMLElement, origin: HTMLElement | null, isFinger = true): void {
    const segments = segmentsOf(track);
    const boxOf = boxesIn(track);
    const boxes = new Map(segments.map(segment => [segment, boxOf(segment)]));
    const toTrackX = trackXIn(track);
    const selected =
      segments.find(
        segment => segment.getAttribute('aria-checked') === 'true',
      ) ?? null;
    const carriesLens = origin != null && origin === selected;
    const selectedTitle = selected != null ? titleOf(selected) : null;
    // An enabled segment's unselected face: a disabled title has its own.
    const other = segments.find(
      segment => segment !== selected && isEnabledSegment(segment),
    );
    const otherTitle = other != null ? titleOf(other) : null;
    const faces =
      selectedTitle != null && otherTitle != null
        ? {selected: faceOf(selectedTitle), unselected: faceOf(otherTitle)}
        : null;
    this.touch = {
      toTrackX,
      boxes,
      origin,
      carriesLens,
      isFinger,
      faces,
    };
  }

  /**
   * The finger moved to `clientX`. A drag from the selected segment carries
   * the lens at its resting size. A touch elsewhere leaves the lens alone,
   * and that segment shows the shared pressed overlay.
   */
  drag(clientX: number): void {
    const touch = this.touch;
    if (touch == null || !touch.carriesLens) {
      return;
    }
    this.hold();
    if (!this.isHeld) {
      return;
    }
    this.chase(clientX);
    this.followLens();
  }

  /**
   * The first move of a drag from the selected segment binds the lens there,
   * at its resting size. Under Reduced Motion too: the lens follows the hand,
   * and only the release cross-fades.
   */
  private hold(): void {
    const touch = this.touch;
    if (touch == null || touch.origin == null || this.isHeld) {
      return;
    }
    const box = touch.boxes.get(touch.origin) as Box;
    if (!isLaidOut(box)) {
      return;
    }
    this.carry(touch.origin, box, null, touch.origin);
    this.isHeld = true;
  }

  /**
   * The selected face follows the held lens: it goes to the segment under the
   * lens's presented center. Hysteresis around each boundary keeps a finger
   * that rests on a boundary from flipping it. This runs every frame while
   * the lens is held, so the face keeps up as the lens settles under a still
   * finger.
   */
  private followLens(): void {
    const touch = this.touch;
    const carried = this.carried;
    if (
      touch == null ||
      !touch.carriesLens ||
      !this.isHeld ||
      carried == null ||
      touch.origin == null
    ) {
      this.lensFrame = null;
      return;
    }
    const lensCenter = this.presented(carried.box, this.now()).center;
    const spans = [...touch.boxes.entries()]
      .filter(([segment]) => isEnabledSegment(segment))
      .sort((a, b) => a[1].x - b[1].x);
    const current = this.facedSegment ?? touch.origin;
    const at = spans.findIndex(([segment]) => segment === current);
    if (at >= 0) {
      const edge = (i: number) =>
        (spans[i][1].x + spans[i][1].width + spans[i + 1][1].x) / 2;
      let next = at;
      while (next + 1 < spans.length && lensCenter > edge(next)) {
        next += 1;
      }
      while (next > 0 && lensCenter < edge(next - 1)) {
        next -= 1;
      }
      if (next !== at) {
        const boundary = next > at ? edge(at) : edge(at - 1);
        const hysteresis = Math.max(
          FACE_HYSTERESIS_MIN_PX,
          FACE_HYSTERESIS_RATIO * spans[next][1].width,
        );
        if (Math.abs(lensCenter - boundary) >= hysteresis) {
          const segment = spans[next][0];
          this.showFaceAt(segment === touch.origin ? null : segment);
        }
      }
    }
    const view = this.track?.ownerDocument.defaultView;
    if (this.lensFrame == null && view != null) {
      this.lensFrame = view.requestAnimationFrame(() => {
        this.lensFrame = null;
        this.followLens();
      });
    }
  }

  /** The held lens's center chases the finger at `clientX`. */
  private chase(clientX: number): void {
    const touch = this.touch;
    const carried = this.carried;
    if (touch == null || carried == null) {
      return;
    }
    const centers = [...touch.boxes.values()].map(center);
    const reach = segmentedControl.dragOvershoot;
    const target = Math.min(
      Math.max(touch.toTrackX(clientX), Math.min(...centers) - reach),
      Math.max(...centers) + reach,
    );
    if (!this.isPresenting || this.animator.reducedMotion() !== 'off') {
      // A mouse or a pen holds the lens directly, as a finger does under
      // Reduce Motion. Each move writes the pointer's position.
      this.animator.set({x: target - center(carried.box)});
      return;
    }
    // Start each chase at the call. A chase from rest waits for the browser
    // to start it. Android Chrome sends the next move first, so the lens
    // would stick.
    const at = this.now();
    this.springLens(
      {x: target - center(carried.box)},
      this.springFrom({x: target - center(carried.box)}, 'tracking'),
      {at},
    );
  }

  /**
   * The finger let go on `target`, the segment the tracker resolved for it
   * (null: none, or a disabled one). Moves the lens there and returns its
   * value when it is not the selected one (the tracker's lift commits it
   * through its click), else null.
   */
  release(target: HTMLElement | null): string | null {
    const touch = this.touch;
    this.touch = null;
    if (touch == null) {
      return null;
    }
    const selected =
      [...touch.boxes.keys()].find(
        segment => segment.getAttribute('aria-checked') === 'true',
      ) ?? null;
    // A disabled segment never commits: the lens settles back on the
    // selection.
    const destination =
      (target != null && isEnabledSegment(target) ? target : null) ?? selected;
    if (destination == null) {
      this.clearFaces();
      if (this.isHeld) {
        this.isHeld = false;
        this.settle();
      }
      return null;
    }
    const box = touch.boxes.get(destination) as Box;
    const value =
      destination !== selected ? (destination.dataset.value ?? null) : null;
    // A drag's borrowed face stays only if the lift commits (the commit
    // takes it over).
    if (value == null) {
      this.clearFaces();
    }
    const isHeld = touch.carriesLens && this.isHeld;
    this.committed = value;
    this.isAwaitingValue = false;
    this.releasedByFinger = touch.isFinger;
    if (value == null) {
      if (isHeld) {
        // The held lens settles back on the selection.
        this.moveLensTo(
          destination,
          box,
          selected ?? destination,
          touch.isFinger,
        );
      }
      return null;
    }
    // The commit follows at once, through the segment's click; the lens
    // moves once it has run, on the box the destination has then. A held
    // lens settles there; a tap (or a drag that started elsewhere) slides
    // there from the selected segment.
    // A fine pointer under Reduce Motion moves only a held lens.
    if (isHeld || (selected != null && this.slidesChanges())) {
      this.pending = {
        destination,
        box,
        isHeld,
        from:
          !isHeld && selected != null
            ? (touch.boxes.get(selected) as Box)
            : null,
        touchRelease: touch.isFinger,
      };
    }
    return value;
  }

  /**
   * The commit's click for `value` has run. A click that the item's
   * `onClick` cancels sends the lens back at once. Otherwise the lens waits
   * for the value, which a parent can adopt later.
   */
  clicked(track: HTMLElement, value: string, isCancelled: boolean): void {
    if (this.committed !== value) {
      // Adopted during the click, or superseded.
      return;
    }
    if (isCancelled) {
      this.pending = null;
      this.decline(track, value);
      return;
    }
    this.isAwaitingValue = true;
    // React can render the click's change only after the event that
    // dispatched it ends: a click inside a touch handler is batched with it.
    // Wait one turn. If the value is adopted by then, the lens already moves
    // on the new box. Otherwise it aims at the box measured at landing and
    // re-aims when the value comes back.
    queueMicrotask(() => {
      if (this.committed === value && this.pending != null) {
        this.startPending(this.selectedIn(track));
      }
    });
  }

  /**
   * The value the finger let go on was not adopted. The item's `onClick`
   * cancelled it, or a controlled parent kept its value. The lens goes back
   * to the selected segment. The next change to that value slides as any
   * change does.
   */
  decline(track: HTMLElement, value: string): void {
    if (this.committed !== value) {
      return;
    }
    this.committed = null;
    this.isAwaitingValue = false;
    this.pending = null;
    this.clearFaces();
    const selected =
      segmentsOf(track).find(
        segment => segment.getAttribute('aria-checked') === 'true',
      ) ?? null;
    if (selected == null || this.carried == null) {
      this.settle();
      return;
    }
    const box = boxesIn(track)(selected);
    if (!isLaidOut(box)) {
      this.settle();
      return;
    }
    this.moveLensTo(selected, box, selected, this.releasedByFinger);
  }

  /** The touch was taken away (the page scrolled): the lens goes back. */
  cancel(): void {
    const touch = this.touch;
    this.touch = null;
    this.clearFaces();
    if (
      touch == null ||
      !touch.carriesLens ||
      touch.origin == null ||
      !this.isHeld
    ) {
      // Nothing was held: nothing to put back.
      return;
    }
    const box = touch.boxes.get(touch.origin) as Box;
    this.moveLensTo(touch.origin, box, touch.origin, touch.isFinger);
  }

  /** Hands the surface back to its segment now and hides the lens. */
  settle(): void {
    this.endLeaving();
    this.isHeld = false;
    this.pending = null;
    const carried = this.carried;
    if (carried != null) {
      this.carried = null;
      this.running.clear();
      this.animator.stop();
      this.after.stop();
      showSurface(carried.hidden);
      for (const segment of this.abandoned) {
        showSurface(segment);
      }
      this.abandoned.clear();
      if (this.track != null) {
        clearLayer(this.track, 'lens');
        clearLayer(this.track, 'after');
      }
      this.isLeavingShown = false;
    }
    // Once the surfaces are back on screen, so nothing fades in.
    this.thawTransitions();
  }

  /**
   * The control resized. The lens aims at boxes measured when its motion
   * began, so it hands the surface back rather than land somewhere stale.
   * Two cases keep the motion. In the first, the track keeps its measured
   * size: a new title weight resized a content-sized control before the box
   * was measured. In the second, a finger holds the lens.
   */
  resized(track: HTMLElement): void {
    const carried = this.carried;
    // A finger that holds the lens reflows the titles itself, because the
    // selected face moves to the title under it. The lens follows the finger,
    // and the commit measures the destination again.
    if (carried == null || this.touch != null) {
      return;
    }
    if (
      Math.abs(track.offsetWidth - carried.trackSize.width) < 0.5 &&
      Math.abs(track.offsetHeight - carried.trackSize.height) < 0.5
    ) {
      return;
    }
    this.settle();
  }

  /**
   * Ends everything in flight (unmount). The controller stays usable, so an
   * effect cleanup followed by a setup (StrictMode's extra mount) loses
   * nothing.
   */
  stop(): void {
    this.touch = null;
    if (this.lensFrame != null) {
      this.track?.ownerDocument.defaultView?.cancelAnimationFrame(
        this.lensFrame,
      );
      this.lensFrame = null;
    }
    this.committed = null;
    this.isAwaitingValue = false;
    this.clearFaces();
    this.settle();
    this.cancelThaw();
    this.restoreTransitions();
  }

  /**
   * A fine pointer's carry. The segments' own transitions go off while the
   * lens is on screen, so the borrowed surface does not fade out and back in.
   * Under a finger, the touch presentation already turns them off.
   */
  private stillTransitions(): void {
    const track = this.track;
    if (track == null) {
      return;
    }
    this.cancelThaw();
    for (const segment of segmentsOf(track)) {
      if (!this.stilled.has(segment)) {
        this.stilled.set(segment, [
          segment.style.getPropertyValue('transition-property'),
          segment.style.getPropertyPriority('transition-property'),
        ]);
      }
      segment.style.setProperty('transition-property', 'none', 'important');
    }
  }

  /**
   * Gives the stilled segments their transitions back two frames after the
   * hand-back, once the surfaces it gave back have been on screen.
   */
  private thawTransitions(): void {
    if (this.stilled.size === 0 || this.thawFrame != null) {
      return;
    }
    const view = this.track?.ownerDocument.defaultView;
    if (view == null) {
      this.restoreTransitions();
      return;
    }
    this.thawFrame = view.requestAnimationFrame(() => {
      this.thawFrame = view.requestAnimationFrame(() => {
        this.thawFrame = null;
        this.restoreTransitions();
      });
    });
  }

  private cancelThaw(): void {
    if (this.thawFrame != null) {
      this.track?.ownerDocument.defaultView?.cancelAnimationFrame(
        this.thawFrame,
      );
      this.thawFrame = null;
    }
  }

  private restoreTransitions(): void {
    for (const [segment, [value, priority]] of this.stilled) {
      if (value === '') {
        segment.style.removeProperty('transition-property');
      } else {
        segment.style.setProperty('transition-property', value, priority);
      }
    }
    this.stilled.clear();
  }

  /** The selected segment, as the DOM shows it now. */
  private selectedIn(track: HTMLElement): HTMLElement | null {
    return (
      segmentsOf(track).find(
        segment => segment.getAttribute('aria-checked') === 'true',
      ) ?? null
    );
  }

  /**
   * Starts the motion the release left pending: on `box` (the destination's
   * box now) or the box measured at landing, showing `paint`'s surface (the
   * selected segment's).
   */
  private startPending(paint: HTMLElement | null, box?: Box): void {
    const pending = this.pending;
    this.pending = null;
    if (pending == null) {
      return;
    }
    const to = box ?? pending.box;
    const surface = this.carried?.hidden ?? paint ?? pending.destination;
    if (pending.isHeld) {
      this.moveLensTo(pending.destination, to, surface, pending.touchRelease);
    } else if (pending.from != null) {
      this.slideTo(
        pending.destination,
        to,
        pending.from,
        surface,
        pending.touchRelease,
      );
    }
  }

  /**
   * Aims the lens at `destination`'s box as it is now: a value adopted
   * after its click (mid-flight) moves the segments with its titles' new
   * weights.
   */
  private reaim(track: HTMLElement, destination: HTMLElement): void {
    const carried = this.carried;
    if (carried == null) {
      return;
    }
    const box = boxesIn(track)(destination);
    if (!isLaidOut(box) || isSameBox(box, carried.box)) {
      return;
    }
    this.moveLensTo(destination, box, carried.hidden, this.releasedByFinger);
  }

  /**
   * Binds the lens for `segment`, with `box` as its layout box and `paint`'s
   * surface, the selected segment's. It keeps what is on screen. With nothing
   * carried, it starts from `from`, a segment's resting box. Otherwise it
   * starts from the presented geometry, re-based onto the new box with its
   * velocities.
   */
  private carry(
    segment: HTMLElement,
    box: Box,
    from: Box | null,
    paint: HTMLElement,
  ): number | undefined {
    const track = this.track;
    if (track == null) {
      return undefined;
    }
    if (!this.isPresenting) {
      // Before the surface is borrowed: it must not fade out.
      this.stillTransitions();
    }
    const previous = this.carried;
    let start: MotionValues;
    // Motion already on screen continues from this instant; a start from
    // rest waits for the browser to commit it (the animator's rule).
    let at: number | undefined;
    this.velocity = {};
    if (previous != null) {
      at = this.now();
      const presented = this.presented(previous.box, at);
      start = {
        x: presented.center - center(box),
        scaleX: presented.width / box.width,
        scaleY: presented.height / box.height,
      };
      this.velocity = {
        x: this.animator.getVelocity('x', at),
        scaleX:
          (this.animator.getVelocity('scaleX', at) * previous.box.width) /
          box.width,
        scaleY:
          (this.animator.getVelocity('scaleY', at) * previous.box.height) /
          box.height,
      };
    } else {
      const origin = from ?? box;
      start = {
        x: center(origin) - center(box),
        scaleX: origin.width / box.width,
        scaleY: origin.height / box.height,
      };
    }
    if (previous?.hidden !== paint) {
      if (previous != null) {
        this.abandoned.add(previous.hidden);
      }
      // A segment abandoned mid-flight still has its surface hidden: read
      // its paint with it shown.
      if (this.abandoned.has(paint)) {
        showSurface(paint);
      }
      paintLayer(track, 'lens', paint);
      hideSurface(paint);
      this.abandoned.delete(paint);
    }
    placeLayer(track, 'lens', box);
    this.carried = {
      segment,
      box,
      hidden: paint,
      trackSize: {width: track.offsetWidth, height: track.offsetHeight},
    };
    // Opaque, whatever a Reduce Motion fade left.
    this.animator.set({...start, opacity: 1});
    return at;
  }

  /** Velocities captured by the last `carry`, in the new box's units. */
  private velocity: Partial<Record<'x' | 'scaleX' | 'scaleY', number>> = {};

  /** A spring transition that keeps the captured velocities of `values`. */
  private springFrom(
    values: MotionValues,
    kind: 'selection' | 'tracking',
  ): SpringTransition {
    const spring =
      kind === 'selection'
        ? segmentedControl.selectionSpring
        : springs.fingerTracking;
    const velocity: Record<string, number> = {};
    for (const key of Object.keys(values) as (keyof typeof this.velocity)[]) {
      const v = this.velocity[key];
      if (v != null && v !== 0) {
        velocity[key] = v;
      }
    }
    // A captured velocity is spent by the first call that drives its channel.
    this.velocity = Object.fromEntries(
      Object.entries(this.velocity).filter(([key]) => !(key in values)),
    );
    return Object.keys(velocity).length > 0 ? {spring, velocity} : {spring};
  }

  /**
   * The lens settles at its resting place on `segment`. Under a finger it
   * springs on the slide spring. Under a fine pointer it takes the theme's
   * duration and easing, as the segments' own transition does.
   */
  private settleLens(segment: HTMLElement, options: AnimateOptions): void {
    const rest = {x: 0, scaleX: 1, scaleY: 1} as const;
    if (this.isPresenting) {
      this.springLens(rest, this.springFrom(rest, 'selection'), options);
      return;
    }
    this.velocity = {};
    // The segment's own transition carries the theme's duration and easing.
    // They stay readable while a carry turns its property off.
    const progress = readThemeTiming(segment) ?? INSTANT;
    const at = options.at;
    // Unclamped, so an easing that overshoots carries the lens with it.
    const toward = (from: number, to: number) =>
      mapProgress(progress, mapRange([0, 1], [from, to], {clamp: false}));
    this.trackHandle(
      this.animator.play(
        {
          x: toward(this.animator.get('x', at), 0),
          scaleX: toward(this.animator.get('scaleX', at), 1),
          scaleY: toward(this.animator.get('scaleY', at), 1),
        },
        options,
      ),
    );
  }

  /** Springs the lens toward `values`. */
  private springLens(
    values: MotionValues,
    transition: SpringTransition,
    options?: AnimateOptions,
  ): void {
    this.trackHandle(this.animator.animate(values, transition, options));
  }

  /** The lens's presented center and size, from the animator. */
  private presented(
    box: Box,
    at: number,
  ): {center: number; width: number; height: number} {
    return {
      center: center(box) + this.animator.get('x', at),
      width: box.width * this.animator.get('scaleX', at),
      height: box.height * this.animator.get('scaleY', at),
    };
  }

  /**
   * The lens settles on `segment`, at its resting size. Under Reduced Motion
   * a finger's release (`touchRelease`) cross-fades on any primary pointer. A
   * mouse's or a pen's lands at once under a fine one.
   */
  private moveLensTo(
    segment: HTMLElement,
    box: Box,
    paint: HTMLElement,
    touchRelease: boolean,
  ): void {
    this.isHeld = false;
    if (!isLaidOut(box)) {
      this.settle();
      return;
    }
    if (this.animator.reducedMotion({touchRelease}) !== 'off') {
      this.crossFadeTo(
        segment,
        box,
        null,
        this.carried?.hidden ?? paint,
        touchRelease,
      );
      return;
    }
    const at = this.carry(segment, box, null, this.carried?.hidden ?? paint);
    this.settleLens(segment, {at});
  }

  /**
   * A tap's slide: from `from` to `segment` on the slide spring. Under Reduced
   * Motion there is no travel, and a finger's tap (`touchRelease`) fades.
   */
  private slideTo(
    segment: HTMLElement,
    box: Box,
    from: Box,
    paint: HTMLElement,
    touchRelease: boolean,
  ): void {
    if (!isLaidOut(box)) {
      this.settle();
      return;
    }
    if (this.animator.reducedMotion({touchRelease}) !== 'off') {
      this.crossFadeTo(
        segment,
        box,
        this.carried == null ? from : null,
        this.carried?.hidden ?? paint,
        touchRelease,
      );
      return;
    }
    const at = this.carry(
      segment,
      box,
      this.carried == null ? from : null,
      this.carried?.hidden ?? paint,
    );
    this.settleLens(segment, {at});
  }

  /**
   * Under Reduced Motion, the lens lands on `segment` and fades in there, as
   * an animator entrance. The surface on screen fades out in place on the
   * same clock. That surface is the lens when it was carried, else `from`'s
   * resting surface. The animator decides whether anything fades. On a fine
   * pointer, both change at once unless a touch released the change
   * (`touchRelease`).
   */
  private crossFadeTo(
    segment: HTMLElement,
    box: Box,
    from: Box | null,
    paint: HTMLElement,
    touchRelease: boolean,
  ): void {
    const track = this.track;
    if (track == null) {
      return;
    }
    // What is on screen before the lens is rebound.
    let leaving: Box | null = null;
    let opacity = 1;
    const previous = this.carried;
    if (previous != null) {
      const now = this.now();
      const presented = this.presented(previous.box, now);
      leaving = {
        x: presented.center - presented.width / 2,
        y: previous.box.y,
        width: presented.width,
        height: previous.box.height,
      };
      opacity = this.animator.get('opacity', now);
    } else if (from != null) {
      leaving = from;
    }
    this.isHeld = false;
    this.endLeaving();
    this.after.stop();
    clearLayer(track, 'after');
    this.isLeavingShown = false;
    const fades =
      leaving != null &&
      opacity > 0 &&
      this.animator.reducedMotion({touchRelease}) === 'crossfade';
    if (fades) {
      this.leave(track, previous != null, paint, leaving as Box, opacity, box);
    }
    const at = this.carry(segment, box, from, paint);
    this.velocity = {};
    this.trackHandle(
      this.animator.animate(
        {x: 0, scaleX: 1, scaleY: 1},
        {spring: segmentedControl.selectionSpring},
        {at, crossfadeAs: 'entrance', touchRelease},
      ),
    );
    if (fades) {
      this.fadeLeaving(box, leaving as Box, at, touchRelease);
    }
  }

  /**
   * Paints the ::after with the surface on screen (the lens's paint, or
   * `paint`'s resting surface) where it is (`from`, at `opacity`).
   */
  private leave(
    track: HTMLElement,
    fromLens: boolean,
    paint: HTMLElement,
    from: Box,
    opacity: number,
    box: Box,
  ): void {
    if (fromLens) {
      copyLensPaint(track);
    } else {
      paintLayer(track, 'after', paint);
    }
    placeLayer(track, 'after', {...from, y: box.y, height: box.height});
    this.isLeavingShown = true;
    this.after.set({x: 0, scaleX: 1, scaleY: 1, opacity});
  }

  /**
   * The ::after fades out in place while the lens fades in on `box`. As a
   * leaving travel, it fades on the animator's Reduce Motion clock. It lands
   * only once it is invisible.
   */
  private fadeLeaving(
    box: Box,
    from: Box,
    at: number | undefined,
    touchRelease: boolean,
  ): void {
    const id = ++this.leaving;
    const handle = this.after.animate(
      {x: center(box) - center(from), opacity: 0},
      {spring: segmentedControl.selectionSpring},
      {at, touchRelease},
    );
    void handle.finished.then(() => {
      if (this.leaving === id) {
        this.endLeaving();
      }
    });
  }

  private endLeaving(): void {
    if (!this.isLeavingShown) {
      return;
    }
    this.isLeavingShown = false;
    this.leaving++;
    this.after.stop();
    if (this.track != null) {
      clearLayer(this.track, 'after');
    }
  }

  /**
   * Waits for `handle`; the surface goes back when nothing is left. A
   * touch's value still waiting to come back when the motion settles goes
   * back instead: the settled slide bounds the wait.
   */
  private trackHandle(handle: MotionHandle): void {
    this.running.add(handle);
    void handle.finished.then(() => {
      this.running.delete(handle);
      if (this.running.size > 0 || this.isHeld || this.touch != null) {
        return;
      }
      const committed = this.committed;
      if (this.isAwaitingValue && committed != null && this.track != null) {
        this.decline(this.track, committed);
        return;
      }
      if (this.committed == null) {
        this.settle();
      }
    });
  }

  /**
   * Gives `segment`'s title the selected face and the selected segment's
   * title an unselected one (none for null or the selected segment), at once.
   */
  private showFaceAt(segment: HTMLElement | null): void {
    const touch = this.touch;
    const selected = touch?.origin ?? null;
    if (segment === this.facedSegment) {
      return;
    }
    this.clearFaces();
    if (
      touch?.faces == null ||
      selected == null ||
      segment == null ||
      segment === selected
    ) {
      return;
    }
    const title = titleOf(segment);
    const selectedTitle = titleOf(selected);
    if (title == null || selectedTitle == null) {
      return;
    }
    this.wearFace(title, touch.faces.selected);
    this.wearFace(selectedTitle, touch.faces.unselected);
    this.facedSegment = segment;
  }

  /**
   * Mid-drag, the face is the color alone. A weight swap changes the titles'
   * widths, which moves the segments under the finger and shakes the
   * boundary. The commit's own styles give the new weight at the lift.
   */
  private wearFace(title: HTMLElement, face: TitleFace): void {
    title.style.color = face.color;
    this.faceOverrides.add(title);
  }

  /** Every title back to its own face. */
  private clearFaces(): void {
    for (const title of this.faceOverrides) {
      title.style.removeProperty('color');
    }
    this.faceOverrides.clear();
    this.facedSegment = null;
  }
}

/**
 * Wires `SegmentedSelectionMotion` to a SegmentedControl. While enabled,
 * every change of `value` slides the selection in the commit that shows the
 * new value, so no frame shows it unanimated. A press drives the lens while
 * `isTracking`.
 */
export function useSegmentedSelectionMotion(
  trackRef: RefObject<HTMLElement | null>,
  value: string,
  isPresenting: boolean,
  isTracking: boolean,
): {
  readonly selection: SegmentedSelection;
  /** The radiogroup's callback ref: it attaches the animators to the node. */
  readonly attachTrack: RefCallback<HTMLElement>;
} {
  const [motion] = useState(() => new SegmentedSelectionMotion());
  const previousValueRef = useRef(value);
  // The lens is the radiogroup's own pseudo-elements. The animators attach to
  // it while the touch presentation applies or while a press can drag it,
  // which any pointer can.
  const isEnabled = isPresenting || isTracking;

  // Syncs the lens animators with the pointer presentation: a flip hands any
  // motion in flight back.
  useIsomorphicLayoutEffect(() => {
    motion.present(isPresenting);
  }, [isPresenting, motion]);

  useIsomorphicLayoutEffect(() => {
    const from = previousValueRef.current;
    previousValueRef.current = value;
    const track = trackRef.current;
    if (!isEnabled || track == null || from === value) {
      return;
    }
    motion.select(track, from, value);
  }, [isEnabled, motion, trackRef, value]);

  // Stops the animators that drive the radiogroup's pseudo-elements.
  useEffect(() => () => motion.stop(), [motion]);

  // Every pointer's press is tracked. The lift commits the segment nearest
  // the pointer, through that segment's click.
  const clickWait = useSegmentedTouchTracking(trackRef, motion, isTracking);

  // The animators attach to the radiogroup while enabled. The lens aims at
  // boxes measured when its motion began, so a resize hands the surface back.
  const attachTrack = useCallback(
    (track: HTMLElement | null) => {
      if (track == null || !isEnabled) {
        return undefined;
      }
      motion.attachTrack(track);
      const unobserve = observeResize(track, () => motion.resized(track));
      return () => {
        unobserve();
        motion.settle();
        motion.attachTrack(null);
      };
    },
    [isEnabled, motion],
  );

  const [selection] = useState<SegmentedSelection>(() => ({
    isPressing: () => motion.isPressed || clickWait.isAwaiting(),
    keyPressed: clickWait.end,
  }));
  return {selection, attachTrack};
}