Skip to content

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

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

/**
 * @file timing.ts
 * @input Nothing; data only
 * @output Exports `timing`: the non-spring clocks and curves UIKit uses
 *   (press highlight onset, flash and fade, Core Animation's named Bézier
 *   curves, the navigation bar hide/show duration, the keyboard
 *   notification duration, the Reduced Motion cross-fade)
 * @position The timing domain of the UIKit constants table (motion/uikit)
 *
 * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
 * measured | GUESS); webkit and GUESS values also carry the `@measure` task
 * that will confirm or replace them (MEASUREMENTS.md). uikit.test.ts
 * enforces both.
 *
 * Durations are in ms (the unit of pointer-event timestamps, which these
 * clocks are compared against); curves are cubic-bézier control points
 * [x1, y1, x2, y2].
 *
 * SYNC: When modified, update:
 * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
 * - /packages/core/src/utils/pressGesture.ts (the press clocks are measured
 *   there and must agree; uikit/uikit.test.ts checks it)
 */

import {registerMotionTable} from '../roles';

/**
 * The touch press clocks, its own export so a reader of one clock does not
 * bundle the rest of the table (`architecture:component-style-authoring`
 * INV6).
 */
export const press = {
  /**
   * Highlight onset once a press is believed: none, the highlight is
   * painted in the frame the touch is accepted (after
   * `scroll.delaysContentTouchesMs` inside a scroller).
   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
   *   with real HID touches at 60 fps (touch press model,
   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
   */
  highlightInMs: 0,
  /**
   * A tap released before the onset delay still flashes the highlight at
   * full strength for this long before fading.
   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
   *   with real HID touches at 60 fps (PRESS_FLASH_MS,
   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
   */
  flashMs: 100,
  /**
   * Highlight fade after release: UIKit's deselect cross-fade. Reference
   * only, not played: a press release plays the theme's exit motion tokens
   * (`--duration-exit`, `--ease-exit`).
   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
   *   with real HID touches at 60 fps (touch press model,
   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
   */
  highlightOutMs: 200,
  /**
   * The highlight fade's curve after release: an ease-out that spends the
   * whole clock fading (strength about 0.2 at the midpoint). Reference only,
   * not played: a press release plays the theme's `--ease-exit`.
   * @source GUESS — the release curve the touch press model shipped with,
   *   chosen to read as UIKit's deselect cross-fade, not read from UIKit
   * @measure M-PR1
   */
  highlightOutCurve: [0, 0, 0.2, 1],
  /**
   * A touch on a scroller that moved this recently brakes it instead of
   * pressing.
   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
   *   with real HID touches at 60 fps (PRESS_SCROLL_BRAKE_MS,
   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
   */
  scrollBrakeMs: 150,
  /**
   * UIButton (filled configuration) release: the label cross-fade and the
   * background color both run 0.25 s on `curves.move`.
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
   *   Oct 23 2026
   */
  buttonReleaseMs: 250,
} as const;

/**
 * The Reduce Motion fade, its own export so the animator reads it without
 * the rest of the table (`architecture:component-style-authoring` INV6).
 * `timing` composes it under its table paths, `reducedMotionCrossFadeMs` and
 * `curves.move`, so their roles are unchanged.
 */
export const reducedMotionCrossFade = {
  /**
   * The Reduced Motion cross-fade, in ms, on `curves.move`: under
   * Reduce Motion an entrance, exit, presentation switch or state change
   * becomes an opacity-only cross-fade of this length on a coarse pointer
   * (design:reduced-motion DR2 caps it at 200 ms, by owner decision DEC-1
   * of 2026-10-24, departing from UIKit's own navigation cross-fade,
   * measured below at 0.5 s). Not a role: nothing lengthens it (DR4).
   * @source apple-docs https://developer.apple.com/documentation/uikit/uiaccessibility/preferscrossfadetransitions
   *   (the setting)
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, CAAnimation dump with Reduce Motion and Prefer
   *   Cross-Fade Transitions on (opacity CABasicAnimation 0.5 s,
   *   (0.42, 0, 0.58, 1)), Oct 23 2026
   */
  durationMs: 200,
  /**
   * `easeInEaseOut`; UIKit's default curve (`UIView.AnimationCurve
   * .easeInOut`, "the default curve for most animations").
   * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeineaseout
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
   *   Oct 23 2026
   */
  curve: [0.42, 0, 0.58, 1],
} as const;

// `timing` composes the fade from bindings, not property reads, so a bundle
// that reads only the fade drops the rest of the table.
const {durationMs: reducedMotionCrossFadeMs, curve: move} =
  reducedMotionCrossFade;

export const timing = {
  press,
  curves: {
    /**
     * `CAMediaTimingFunctionName.default`: "the timing of … most system
     * animations" that are not springs.
     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/default
     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
     *   Oct 23 2026
     */
    viewChange: [0.25, 0.1, 0.25, 1],
    // The Reduce Motion fade's curve, sourced on `reducedMotionCrossFade`.
    move,
    /**
     * `easeIn`.
     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easein
     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
     *   Oct 23 2026
     */
    exit: [0.42, 0, 1, 1],
    /**
     * `easeOut`.
     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeout
     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
     *   Oct 23 2026
     */
    entrance: [0, 0, 0.58, 1],
  },
  /**
   * `UINavigationController.hideShowBarDuration`, in ms.
   * @source apple-docs https://developer.apple.com/documentation/uikit/uinavigationcontroller/hideshowbarduration
   *   (the constant, not its value)
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, read, Oct 23 2026
   */
  navigationBarHideShowMs: 200,
  /**
   * The duration the keyboard notifications report
   * (UIKeyboardAnimationDurationUserInfoKey, with curve 7), show and hide
   * alike, in ms. The frame follows `springs.keyboard`, cut at this time.
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, UIKeyboardWillShow / WillHide / WillChangeFrame read,
   *   Oct 23 2026
   */
  keyboardNotificationMs: 383.3,
  /**
   * Core Animation's implicit animation duration
   * (`CATransaction.animationDuration()`), in ms.
   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
   *   iPhone 17 Pro, read, Oct 23 2026
   */
  stateChangeMs: 250,
  // The Reduce Motion fade's length, sourced on `reducedMotionCrossFade`.
  reducedMotionCrossFadeMs,
} as const;

/**
 * Registers the springs, durations and curves above that spec:AST-094 FR4
 * names as internal motion roles (motion/roles.ts). Nothing registers on import: the touch code that
 * animates with this table calls it once (it is idempotent), so a page that
 * never does ships no registry.
 */
export function registerTimingTable(): void {
  registerMotionTable('timing', timing, {
    // Arbitration: who gets the touch, not how anything moves; the Reduced
    // Motion fade, which nothing may lengthen (design:reduced-motion DR4);
    // and the keyboard's own timing, which motion in step with the keyboard
    // rides (spec:AST-094 FR4).
    exclude: [
      'press.scrollBrakeMs',
      'reducedMotionCrossFadeMs',
      'keyboardNotificationMs',
    ],
    // The motion roles: only the ones spec:AST-094 FR4 names. The press
    // clocks and every other value are internal measured constants.
    roles: [
      'stateChangeMs',
      'curves.viewChange',
      'curves.exit',
      'curves.entrance',
      'curves.move',
    ],
  });
}

// The fade's curve under its table path, for registerReducedMotionCrossFade.
const reducedMotionCrossFadeRoles = {curves: {move}};

/**
 * Registers only the Reduce Motion fade's curve as its role,
 * `timing.curves.move`, for code that reads the fade without the rest of the
 * table (the animator, reducedMotionFade()). The fade's length is not a role.
 */
export function registerReducedMotionCrossFade(): void {
  registerMotionTable('timing', reducedMotionCrossFadeRoles, {
    roles: ['curves.move'],
  });
}