guise/anim/

motion.rs

//! A motion: what moves, from where to where, over how long.
//!
//! This is the declarative half of the animation system and it is pure —
//! `Motion::sample(t)` maps a millisecond offset to a [`Frame`] with no
//! state, no clock, and no gpui. Everything else (the one-shot element, the
//! controllable [`Animator`](super::Animator), the [`Sequence`](super::Sequence))
//! is a way of deciding which `t` to ask for.
//!
//! The shape follows anime.js: timing on the motion, optional per-keyframe
//! overrides, and a loop/alternate pair for repetition.

use super::{AnimValue, Easing, Frame, Prop};
use crate::transition::TransitionKind;

/// How many times a motion runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Loop {
  #[default]
  Once,
  /// Exactly `n` iterations (`0` and `1` both mean once).
  Times(u32),
  Forever,
}

impl Loop {
  /// The iteration count, or `None` when it never ends.
  pub fn count(self) -> Option<u32> {
    match self {
      Loop::Once => Some(1),
      Loop::Times(n) => Some(n.max(1)),
      Loop::Forever => None,
    }
  }
}

/// One destination in a track, with optional overrides for how long the leg
/// to it takes and how it eases.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Keyframe {
  pub value: AnimValue,
  /// Milliseconds for this leg. `None` takes an even share of whatever the
  /// motion's `duration` has left over after the fixed legs.
  pub duration: Option<f32>,
  /// Milliseconds to hold the previous value before this leg starts.
  pub delay: f32,
  /// `None` inherits the motion's easing.
  pub ease: Option<Easing>,
}

impl Keyframe {
  pub fn to(value: impl Into<AnimValue>) -> Self {
    Keyframe {
      value: value.into(),
      duration: None,
      delay: 0.0,
      ease: None,
    }
  }

  pub fn duration(mut self, ms: f32) -> Self {
    self.duration = Some(ms.max(0.0));
    self
  }

  pub fn delay(mut self, ms: f32) -> Self {
    self.delay = ms.max(0.0);
    self
  }

  pub fn ease(mut self, easing: Easing) -> Self {
    self.ease = Some(easing);
    self
  }
}

/// Anything that can stand in for a [`Keyframe`] in a list.
///
/// A list of legs is usually a list of destinations — `[-30.0, 0.0]` — and
/// only sometimes a list of built keyframes with their own timings. Rust
/// arrays are homogeneous either way, so one trait covers both without any
/// wrapping at the call site.
pub trait IntoKeyframe {
  fn into_keyframe(self) -> Keyframe;
}

impl IntoKeyframe for Keyframe {
  fn into_keyframe(self) -> Keyframe {
    self
  }
}

macro_rules! keyframe_from_value {
    ($($ty:ty),* $(,)?) => {
        $(
            impl IntoKeyframe for $ty {
                fn into_keyframe(self) -> Keyframe {
                    Keyframe::to(self)
                }
            }
        )*
    };
}

keyframe_from_value!(
  f32,
  f64,
  i32,
  gpui::Pixels,
  gpui::Hsla,
  gpui::Rgba,
  AnimValue
);

/// One property's path: where it starts, and every leg from there.
#[derive(Debug, Clone, PartialEq)]
pub struct Track {
  pub prop: Prop,
  /// The value before the first leg begins. There is no element to read a
  /// current value off of, so a track always says where it starts.
  pub from: AnimValue,
  pub frames: Vec<Keyframe>,
}

impl Track {
  pub fn new(prop: Prop, from: impl Into<AnimValue>) -> Self {
    Track {
      prop,
      from: from.into(),
      frames: Vec::new(),
    }
  }

  pub fn to(mut self, value: impl Into<AnimValue>) -> Self {
    self.frames.push(Keyframe::to(value));
    self
  }

  pub fn keyframe(mut self, frame: Keyframe) -> Self {
    self.frames.push(frame);
    self
  }

  /// Split `duration` between the legs that didn't ask for a specific one.
  fn leg_duration(&self, duration: f32) -> f32 {
    let mut fixed = 0.0;
    let mut flexible = 0usize;
    for frame in &self.frames {
      fixed += frame.delay;
      match frame.duration {
        Some(d) => fixed += d,
        None => flexible += 1,
      }
    }
    if flexible == 0 {
      0.0
    } else {
      ((duration - fixed) / flexible as f32).max(0.0)
    }
  }

  /// How long this track runs. Never shorter than the fixed legs it
  /// declares, so an over-long keyframe stretches the motion rather than
  /// being cut off.
  pub fn span(&self, duration: f32) -> f32 {
    let each = self.leg_duration(duration);
    self
      .frames
      .iter()
      .map(|frame| frame.delay + frame.duration.unwrap_or(each))
      .sum()
  }

  /// The value at `t` ms into the track. Before the first leg it holds
  /// `from`; after the last it holds the final value.
  pub fn sample(&self, t: f32, duration: f32, ease: Easing) -> AnimValue {
    let each = self.leg_duration(duration);
    let mut value = self.from;
    let mut cursor = 0.0;
    for frame in &self.frames {
      let leg = frame.duration.unwrap_or(each);
      let start = cursor + frame.delay;
      if t <= start {
        return value;
      }
      let end = start + leg;
      if t < end {
        let local = if leg <= 0.0 { 1.0 } else { (t - start) / leg };
        let curve = frame.ease.unwrap_or(ease);
        return value.lerp(frame.value, curve.apply(local));
      }
      value = frame.value;
      cursor = end;
    }
    value
  }
}

/// A set of tracks that run together, with shared timing.
#[derive(Debug, Clone, PartialEq)]
pub struct Motion {
  pub tracks: Vec<Track>,
  /// Milliseconds each track gets, before per-keyframe overrides.
  pub duration: f32,
  /// Milliseconds of stillness before the tracks start. The tracks hold
  /// their `from` value throughout — which is what makes a staggered
  /// entrance stay hidden until its turn.
  pub delay: f32,
  /// Milliseconds of stillness after the tracks finish, inside the
  /// iteration — so a loop pauses at the end instead of snapping back.
  pub end_delay: f32,
  pub ease: Easing,
  pub loops: Loop,
  /// Play every other iteration backwards.
  pub alternate: bool,
  /// Play the whole thing backwards.
  pub reversed: bool,
}

impl Default for Motion {
  fn default() -> Self {
    Motion {
      tracks: Vec::new(),
      duration: 300.0,
      delay: 0.0,
      end_delay: 0.0,
      ease: Easing::default(),
      loops: Loop::Once,
      alternate: false,
      reversed: false,
    }
  }
}

impl Motion {
  pub fn new() -> Self {
    Motion::default()
  }

  /// A single leg from `from` to `to`.
  pub fn tween(mut self, prop: Prop, from: impl Into<AnimValue>, to: impl Into<AnimValue>) -> Self {
    self.tracks.push(Track::new(prop, from).to(to));
    self
  }

  /// A multi-leg path for one property. The legs are destinations, or
  /// [`Keyframe`]s when a leg needs its own duration or easing.
  pub fn keyframes<K: IntoKeyframe>(
    mut self,
    prop: Prop,
    from: impl Into<AnimValue>,
    frames: impl IntoIterator<Item = K>,
  ) -> Self {
    let mut track = Track::new(prop, from);
    track
      .frames
      .extend(frames.into_iter().map(IntoKeyframe::into_keyframe));
    self.tracks.push(track);
    self
  }

  pub fn track(mut self, track: Track) -> Self {
    self.tracks.push(track);
    self
  }

  /// Milliseconds. Springs ignore it — they run for their settle time.
  pub fn duration(mut self, ms: f32) -> Self {
    self.duration = ms.max(0.0);
    self
  }

  pub fn delay(mut self, ms: f32) -> Self {
    self.delay = ms.max(0.0);
    self
  }

  pub fn end_delay(mut self, ms: f32) -> Self {
    self.end_delay = ms.max(0.0);
    self
  }

  pub fn ease(mut self, easing: Easing) -> Self {
    self.ease = easing;
    self
  }

  pub fn loops(mut self, loops: Loop) -> Self {
    self.loops = loops;
    self
  }

  pub fn repeat(mut self, times: u32) -> Self {
    self.loops = Loop::Times(times);
    self
  }

  pub fn repeat_forever(mut self) -> Self {
    self.loops = Loop::Forever;
    self
  }

  pub fn alternate(mut self, alternate: bool) -> Self {
    self.alternate = alternate;
    self
  }

  pub fn reversed(mut self, reversed: bool) -> Self {
    self.reversed = reversed;
    self
  }

  /// The duration of one pass, delays included.
  pub fn iteration_ms(&self) -> f32 {
    let span = self
      .tracks
      .iter()
      .map(|track| track.span(self.duration))
      .fold(0.0_f32, f32::max);
    self.delay + span + self.end_delay
  }

  /// The duration of every pass together, or `f32::INFINITY` when it loops
  /// forever.
  pub fn total_ms(&self) -> f32 {
    match self.loops.count() {
      Some(n) => self.iteration_ms() * n as f32,
      None => f32::INFINITY,
    }
  }

  /// The values `t` milliseconds in.
  pub fn sample(&self, t: f32) -> Frame {
    let mut frame = Frame::new();
    self.sample_into(t, &mut frame);
    frame
  }

  /// Sample into an existing frame. Later writers win, which is how a
  /// [`Sequence`](super::Sequence) layers overlapping motions.
  pub fn sample_into(&self, t: f32, frame: &mut Frame) {
    // One walk of the tracks, not two: `total_ms` would recompute the
    // same span, and this runs for every animated element every frame.
    let (local, progress, finished) = fold_time(
      t,
      self.iteration_ms(),
      self.loops,
      self.alternate,
      self.reversed,
    );
    // Negative here means "still in the leading delay", and every track
    // reports its starting value for it — a staggered entrance has to
    // stay hidden until its turn, not flash and then animate.
    let track_time = local - self.delay;
    for track in &self.tracks {
      frame.set(
        track.prop,
        track.sample(track_time, self.duration, self.ease),
      );
    }
    frame.progress = progress;
    frame.finished = finished;
  }
}

/// Fold absolute time into one iteration: resolve the loop count, flip
/// alternating passes, and apply the direction. Shared by [`Motion`] and
/// [`Sequence`](super::Sequence), which repeat by exactly the same rules.
pub(crate) fn fold_time(
  t: f32,
  iteration: f32,
  loops: Loop,
  alternate: bool,
  reversed: bool,
) -> (f32, f32, bool) {
  let total = match loops.count() {
    Some(n) => iteration * n as f32,
    None => f32::INFINITY,
  };
  let t = t.max(0.0);
  let finished = total.is_finite() && t >= total;
  let (index, mut local) = if iteration <= 0.0 {
    (0u32, 0.0)
  } else if finished {
    // Rest on the end of the last iteration rather than wrapping to 0.
    (loops.count().unwrap_or(1).saturating_sub(1), iteration)
  } else {
    ((t / iteration) as u32, t % iteration)
  };

  if alternate && index % 2 == 1 {
    local = iteration - local;
  }
  if reversed {
    local = iteration - local;
  }

  let progress = if total.is_finite() {
    if total <= 0.0 {
      1.0
    } else {
      (t / total).clamp(0.0, 1.0)
    }
  } else if iteration <= 0.0 {
    0.0
  } else {
    (t % iteration) / iteration
  };

  (local, progress, finished)
}

/// How far a slide preset travels, in px.
pub const SLIDE_DISTANCE: f32 = 8.0;

impl Motion {
  /// The entrance [`Transition`](crate::Transition) plays, as a motion you
  /// can retime, delay, stagger or drop into a [`Sequence`](super::Sequence).
  pub fn enter(kind: TransitionKind) -> Self {
    Motion::enter_from(kind, SLIDE_DISTANCE)
  }

  /// [`Motion::enter`] with the slide distance spelled out.
  pub fn enter_from(kind: TransitionKind, distance: f32) -> Self {
    let motion = Motion::new().duration(200.0).tween(Prop::Opacity, 0.0, 1.0);
    match kind {
      TransitionKind::Fade => motion,
      TransitionKind::SlideUp => motion.tween(Prop::Y, distance, 0.0),
      TransitionKind::SlideDown => motion.tween(Prop::Y, -distance, 0.0),
      TransitionKind::SlideLeft => motion.tween(Prop::X, distance, 0.0),
      TransitionKind::SlideRight => motion.tween(Prop::X, -distance, 0.0),
    }
  }

  /// The mirror of [`Motion::enter`] — ends invisible and displaced.
  pub fn exit(kind: TransitionKind) -> Self {
    Motion::exit_to(kind, SLIDE_DISTANCE)
  }

  pub fn exit_to(kind: TransitionKind, distance: f32) -> Self {
    let motion = Motion::new().duration(160.0).tween(Prop::Opacity, 1.0, 0.0);
    match kind {
      TransitionKind::Fade => motion,
      TransitionKind::SlideUp => motion.tween(Prop::Y, 0.0, -distance),
      TransitionKind::SlideDown => motion.tween(Prop::Y, 0.0, distance),
      TransitionKind::SlideLeft => motion.tween(Prop::X, 0.0, -distance),
      TransitionKind::SlideRight => motion.tween(Prop::X, 0.0, distance),
    }
  }

  /// Re-express [`Prop::X`]/[`Prop::Y`] as margins.
  ///
  /// Those two are relative insets, which is the right way to move an
  /// element in flow — it slides and its neighbours do not care. But an
  /// element pinned with `absolute()` *is* its inset, so animating one
  /// would drag it off its pin and leave it wherever the motion ended.
  /// Margins offset a pinned element from where it was pinned, which is
  /// the same visible motion without the fight.
  pub fn as_margins(mut self) -> Self {
    for track in &mut self.tracks {
      track.prop = match track.prop {
        Prop::X => Prop::MarginLeft,
        Prop::Y => Prop::MarginTop,
        other => other,
      };
    }
    self
  }

  /// A breathing fade that never stops — the shape of a "working on it"
  /// hint that isn't a spinner.
  pub fn pulse() -> Self {
    Motion::new()
      .duration(900.0)
      .ease(Easing::InOut(super::ease::Curve::Sine))
      .alternate(true)
      .repeat_forever()
      .tween(Prop::Opacity, 1.0, 0.35)
  }
}

#[cfg(test)]
mod tests {
  use super::*;

  fn opacity(motion: &Motion, t: f32) -> f32 {
    motion.sample(t).number(Prop::Opacity).unwrap()
  }

  #[test]
  fn a_tween_runs_from_end_to_end() {
    let motion = Motion::new()
      .duration(100.0)
      .ease(Easing::Linear)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert_eq!(motion.iteration_ms(), 100.0);
    assert_eq!(opacity(&motion, 0.0), 0.0);
    assert!((opacity(&motion, 50.0) - 0.5).abs() < 1e-5);
    assert_eq!(opacity(&motion, 100.0), 1.0);
    assert_eq!(opacity(&motion, 500.0), 1.0);
  }

  #[test]
  fn a_delay_holds_the_starting_value() {
    let motion = Motion::new()
      .duration(100.0)
      .delay(50.0)
      .ease(Easing::Linear)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert_eq!(motion.iteration_ms(), 150.0);
    assert_eq!(opacity(&motion, 0.0), 0.0);
    assert_eq!(opacity(&motion, 49.0), 0.0);
    assert!((opacity(&motion, 100.0) - 0.5).abs() < 1e-5);
    assert_eq!(opacity(&motion, 150.0), 1.0);
  }

  #[test]
  fn unsized_keyframes_split_the_duration_evenly() {
    let motion = Motion::new()
      .duration(300.0)
      .ease(Easing::Linear)
      .keyframes(
        Prop::X,
        0.0,
        [Keyframe::to(10.0), Keyframe::to(20.0), Keyframe::to(30.0)],
      );
    assert_eq!(motion.iteration_ms(), 300.0);
    assert!((motion.sample(100.0).number(Prop::X).unwrap() - 10.0).abs() < 1e-4);
    assert!((motion.sample(200.0).number(Prop::X).unwrap() - 20.0).abs() < 1e-4);
    assert!((motion.sample(300.0).number(Prop::X).unwrap() - 30.0).abs() < 1e-4);
  }

  #[test]
  fn a_fixed_leg_takes_its_time_and_the_rest_share() {
    let motion = Motion::new()
      .duration(300.0)
      .ease(Easing::Linear)
      .keyframes(
        Prop::X,
        0.0,
        [Keyframe::to(10.0).duration(200.0), Keyframe::to(20.0)],
      );
    assert_eq!(motion.iteration_ms(), 300.0);
    assert!((motion.sample(100.0).number(Prop::X).unwrap() - 5.0).abs() < 1e-4);
    assert!((motion.sample(250.0).number(Prop::X).unwrap() - 15.0).abs() < 1e-4);
  }

  #[test]
  fn over_long_legs_stretch_the_motion() {
    let motion =
      Motion::new()
        .duration(100.0)
        .keyframes(Prop::X, 0.0, [Keyframe::to(1.0).duration(400.0)]);
    assert_eq!(motion.iteration_ms(), 400.0);
  }

  #[test]
  fn repeats_replay_the_iteration() {
    let motion = Motion::new()
      .duration(100.0)
      .ease(Easing::Linear)
      .repeat(3)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert_eq!(motion.total_ms(), 300.0);
    assert!((opacity(&motion, 150.0) - 0.5).abs() < 1e-5);
    assert!(!motion.sample(299.0).finished);
    assert!(motion.sample(300.0).finished);
  }

  #[test]
  fn alternate_runs_odd_iterations_backwards() {
    let motion = Motion::new()
      .duration(100.0)
      .ease(Easing::Linear)
      .repeat(2)
      .alternate(true)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert!((opacity(&motion, 50.0) - 0.5).abs() < 1e-5);
    assert!((opacity(&motion, 150.0) - 0.5).abs() < 1e-5);
    assert!(opacity(&motion, 120.0) > 0.75);
  }

  #[test]
  fn reversed_plays_from_the_far_end() {
    let motion = Motion::new()
      .duration(100.0)
      .ease(Easing::Linear)
      .reversed(true)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert_eq!(opacity(&motion, 0.0), 1.0);
    assert_eq!(opacity(&motion, 100.0), 0.0);
  }

  #[test]
  fn forever_never_finishes() {
    let motion = Motion::pulse();
    assert!(motion.total_ms().is_infinite());
    let frame = motion.sample(10_000.0);
    assert!(!frame.finished);
    assert!((0.0..=1.0).contains(&frame.progress));
  }

  #[test]
  fn end_delay_holds_the_final_value_inside_the_iteration() {
    let motion = Motion::new()
      .duration(100.0)
      .end_delay(100.0)
      .ease(Easing::Linear)
      .tween(Prop::Opacity, 0.0, 1.0);
    assert_eq!(motion.iteration_ms(), 200.0);
    assert_eq!(opacity(&motion, 150.0), 1.0);
  }

  #[test]
  fn as_margins_moves_the_offsets_off_the_inset() {
    let motion = Motion::enter(TransitionKind::SlideUp).as_margins();
    let start = motion.sample(0.0);
    assert_eq!(start.number(Prop::Y), None);
    assert_eq!(start.number(Prop::MarginTop), Some(SLIDE_DISTANCE));
    // Opacity is untouched — only the two offsets move.
    assert_eq!(start.number(Prop::Opacity), Some(0.0));
  }

  #[test]
  fn presets_start_hidden_and_end_settled() {
    for kind in [
      TransitionKind::Fade,
      TransitionKind::SlideUp,
      TransitionKind::SlideDown,
      TransitionKind::SlideLeft,
      TransitionKind::SlideRight,
    ] {
      let motion = Motion::enter(kind);
      let start = motion.sample(0.0);
      let end = motion.sample(motion.total_ms());
      assert_eq!(start.number(Prop::Opacity), Some(0.0));
      assert_eq!(end.number(Prop::Opacity), Some(1.0));
      if kind != TransitionKind::Fade {
        let moved = end.number(Prop::X).or(end.number(Prop::Y)).unwrap();
        assert_eq!(moved, 0.0);
      }
    }
  }
}

#[cfg(test)]
mod bench {
  use super::*;
  use std::time::Instant;

  /// Not an assertion about wall-clock — a way to re-measure the sampling
  /// path when it changes. Ignored by default; run it with
  /// `cargo test --release -p guise-ui bench -- --ignored --nocapture`.
  ///
  /// For reference, on an M-series laptop: a two-track motion samples in
  /// ~19ns and a three-entry sequence in ~71ns, neither touching the heap.
  #[test]
  #[ignore = "a measurement, not a test"]
  fn sampling_cost() {
    let simple = Motion::enter(crate::TransitionKind::SlideUp);
    let heavy = Motion::new().duration(900.0).keyframes(
      Prop::Y,
      0.0,
      [
        Keyframe::to(10.0),
        Keyframe::to(20.0),
        Keyframe::to(30.0),
        Keyframe::to(40.0),
      ],
    );
    let sequence = crate::Sequence::new()
      .add(simple.clone())
      .add(heavy.clone())
      .add(simple.clone());

    type Case = (&'static str, Box<dyn Fn(f32)>);
    let cases: [Case; 3] = [
      (
        "motion(2 tracks)",
        Box::new(move |t| {
          simple.sample(t);
        }),
      ),
      (
        "motion(4 legs)",
        Box::new(move |t| {
          heavy.sample(t);
        }),
      ),
      (
        "sequence(3)",
        Box::new(move |t| {
          sequence.sample(t);
        }),
      ),
    ];
    for (name, run) in cases {
      let start = Instant::now();
      for i in 0..100_000 {
        run(i as f32 * 0.01);
      }
      let each = start.elapsed().as_secs_f64() * 1e9 / 100_000.0;
      println!("{name:20} {each:8.1} ns/sample");
    }
  }
}