tui_splitflap/

cell.rs

//! Per-cell animation state and flip phase logic.

use crate::CharSet;

/// Animation behavior for a cell flip.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlipStyle {
    /// Cycles through each intermediate character in CharSet order.
    /// Total duration = distance * flip_speed_ms.
    Sequential,

    /// Fixed split-block animation regardless of character distance.
    /// Total duration = flip_speed_ms.
    Mechanical { frames: u8 },

    /// Mechanical split-block phase, then sequential character roll.
    /// Total duration = distance * flip_speed_ms (same as Sequential,
    /// but the first step is replaced by a mechanical animation).
    Combined { frames: u8 },
}

/// What a cell is currently doing — determines how the widget renders it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlipPhase {
    Settled,
    Pending,
    Mechanical { frame: u8, total_frames: u8 },
    Sequential,
}

/// Per-cell animation state for a single split-flap tile.
#[derive(Debug, Clone)]
pub struct FlapCell {
    settled: char,
    display: char,
    target: char,
    elapsed_ms: u64,
    total_ms: u64,
    pending_ms: u64,
    distance: usize,
    flip_speed_ms: u64,
    /// Some for Mechanical/Combined styles, None for Sequential.
    mechanical_frames: Option<u8>,
}

impl FlapCell {
    pub fn new(ch: char) -> Self {
        Self {
            settled: ch,
            display: ch,
            target: ch,
            elapsed_ms: 0,
            total_ms: 0,
            pending_ms: 0,
            distance: 0,
            flip_speed_ms: 0,
            mechanical_frames: None,
        }
    }

    pub(crate) fn set_target(
        &mut self,
        target: char,
        style: FlipStyle,
        charset: &CharSet,
        flip_speed_ms: u64,
        pending_ms: u64,
    ) {
        if self.is_animating() {
            let resolved = self.resolve_interrupt();
            self.settled = resolved;
            self.display = resolved;
        }

        let target = charset.sanitize(target);
        let distance = charset.distance(self.display, target);

        self.target = target;

        if distance == 0 {
            self.distance = 0;
            return;
        }

        self.configure_for_style(style, distance, flip_speed_ms, pending_ms);
    }

    fn configure_for_style(
        &mut self,
        style: FlipStyle,
        distance: usize,
        flip_speed_ms: u64,
        pending_ms: u64,
    ) {
        self.distance = distance;
        self.flip_speed_ms = flip_speed_ms;
        self.elapsed_ms = 0;
        self.pending_ms = pending_ms;

        self.mechanical_frames = match style {
            FlipStyle::Sequential => None,
            FlipStyle::Mechanical { frames } | FlipStyle::Combined { frames } => Some(frames),
        };

        self.total_ms = match style {
            FlipStyle::Sequential | FlipStyle::Combined { .. } => distance as u64 * flip_speed_ms,
            FlipStyle::Mechanical { .. } => flip_speed_ms,
        };
    }

    pub(crate) fn tick(&mut self, mut delta_ms: u64, charset: &CharSet) -> bool {
        if !self.is_animating() || delta_ms == 0 {
            return self.is_animating();
        }

        if self.pending_ms > 0 {
            if delta_ms <= self.pending_ms {
                self.pending_ms -= delta_ms;
                return true;
            }

            delta_ms -= self.pending_ms;
            self.pending_ms = 0;
        }

        self.elapsed_ms += delta_ms;

        if self.elapsed_ms >= self.total_ms {
            self.complete();
            return false;
        }

        self.update_display(charset);
        true
    }

    pub fn is_animating(&self) -> bool {
        self.distance > 0 && (self.pending_ms > 0 || self.elapsed_ms < self.total_ms)
    }

    pub fn phase(&self) -> FlipPhase {
        if !self.is_animating() {
            return FlipPhase::Settled;
        }

        if self.pending_ms > 0 {
            return FlipPhase::Pending;
        }

        match self.mechanical_frames {
            None => FlipPhase::Sequential,
            Some(frames) if self.in_mechanical_phase() => {
                let frame = mechanical_frame(self.elapsed_ms, self.flip_speed_ms, frames);
                FlipPhase::Mechanical {
                    frame,
                    total_frames: frames,
                }
            }
            Some(_) => FlipPhase::Sequential,
        }
    }

    pub fn display(&self) -> char {
        self.display
    }

    pub fn settled(&self) -> char {
        self.settled
    }

    pub fn target(&self) -> char {
        self.target
    }

    /// Normalized animation progress in [0.0, 1.0].
    pub fn progress(&self) -> f32 {
        if self.total_ms == 0 {
            return 0.0;
        }

        (self.elapsed_ms as f32 / self.total_ms as f32).min(1.0)
    }

    pub(crate) fn reset(&mut self, ch: char) {
        self.settled = ch;
        self.display = ch;
        self.target = ch;
        self.elapsed_ms = 0;
        self.total_ms = 0;
        self.pending_ms = 0;
        self.distance = 0;
    }

    fn resolve_interrupt(&self) -> char {
        match self.mechanical_frames {
            None => self.display,

            Some(_) if self.in_mechanical_phase() => {
                let mech_progress = if self.flip_speed_ms == 0 {
                    1.0
                } else {
                    self.elapsed_ms as f32 / self.flip_speed_ms as f32
                };

                if mech_progress < 0.5 {
                    self.settled
                } else {
                    self.target
                }
            }

            // Combined, past mechanical phase — sequential rule
            Some(_) => self.display,
        }
    }

    fn in_mechanical_phase(&self) -> bool {
        self.mechanical_frames.is_some() && self.elapsed_ms < self.flip_speed_ms
    }

    fn update_display(&mut self, charset: &CharSet) {
        match self.mechanical_frames {
            None => {
                // Sequential: each flap takes flip_speed_ms to land
                let step = clamped_step(self.elapsed_ms, self.flip_speed_ms, self.distance);
                self.display = charset.step_forward(self.settled, step);
            }

            Some(_) if self.in_mechanical_phase() => {
                // Mechanical phase: widget handles visuals via phase()
            }

            Some(_) => {
                // Combined: mechanical phase consumed step 0, so +1 offset
                let seq_elapsed = self.elapsed_ms - self.flip_speed_ms;
                let step = clamped_step(seq_elapsed, self.flip_speed_ms, self.distance) + 1;
                self.display = charset.step_forward(self.settled, step.min(self.distance));
            }
        }
    }

    fn complete(&mut self) {
        self.elapsed_ms = self.total_ms;
        self.display = self.target;
        self.settled = self.target;
        self.distance = 0;
    }
}

/// How many flaps have landed: `floor(elapsed / speed)`, capped at `max`.
fn clamped_step(elapsed_ms: u64, flip_speed_ms: u64, max: usize) -> usize {
    if flip_speed_ms == 0 {
        return max;
    }

    ((elapsed_ms / flip_speed_ms) as usize).min(max)
}

/// Which mechanical frame we're on (0-based).
fn mechanical_frame(elapsed_ms: u64, flip_speed_ms: u64, frames: u8) -> u8 {
    if flip_speed_ms == 0 {
        return frames.saturating_sub(1);
    }

    let frame = (elapsed_ms * frames as u64 / flip_speed_ms) as u8;
    frame.min(frames.saturating_sub(1))
}

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

    fn default_charset() -> CharSet {
        CharSet::default()
    }

    // --- Sequential ---

    #[test]
    fn sequential_cycles_through_intermediates() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Sequential, &cs, 80, 0);

        // A→F distance is 6: B, C, D, Ð, E, F
        let expected = ['B', 'C', 'D', 'Ð', 'E', 'F'];

        for &ch in &expected[..5] {
            cell.tick(80, &cs);
            assert_eq!(cell.display(), ch, "expected intermediate {ch}");
        }

        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'F');
        assert!(!cell.is_animating());
    }

    #[test]
    fn sequential_duration_scales_with_distance() {
        let cs = default_charset();

        let mut short = FlapCell::new('A');
        short.set_target('B', FlipStyle::Sequential, &cs, 80, 0);

        let mut long = FlapCell::new('A');
        long.set_target('Z', FlipStyle::Sequential, &cs, 80, 0);

        // Tick both to 80ms — short should be done, long should not
        short.tick(80, &cs);
        long.tick(80, &cs);

        assert!(!short.is_animating());
        assert!(long.is_animating());
    }

    #[test]
    fn sequential_identical_chars_no_animation() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('A', FlipStyle::Sequential, &cs, 80, 0);

        assert!(!cell.is_animating());
        assert_eq!(cell.display(), 'A');
    }

    #[test]
    fn sequential_wraps_forward() {
        let cs = default_charset();
        let mut cell = FlapCell::new('Z');
        cell.set_target('A', FlipStyle::Sequential, &cs, 80, 0);

        // Z→A wraps forward through Ƶ, 0-9, punctuation, space, A
        assert!(cell.is_animating());

        // First step: Ƶ (variant glyph immediately after Z)
        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'Ƶ');
    }

    // --- Mechanical ---

    #[test]
    fn mechanical_constant_duration() {
        let cs = default_charset();
        let style = FlipStyle::Mechanical { frames: 4 };

        let mut short = FlapCell::new('A');
        short.set_target('B', style, &cs, 80, 0);

        let mut long = FlapCell::new('A');
        long.set_target('Z', style, &cs, 80, 0);

        // Both should complete at exactly 80ms
        short.tick(80, &cs);
        long.tick(80, &cs);

        assert!(!short.is_animating());
        assert!(!long.is_animating());
    }

    #[test]
    fn mechanical_frame_sequence() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);

        // 4 frames over 80ms = 20ms per frame
        for expected_frame in 0..4u8 {
            assert_eq!(
                cell.phase(),
                FlipPhase::Mechanical {
                    frame: expected_frame,
                    total_frames: 4
                }
            );
            cell.tick(20, &cs);
        }

        assert!(!cell.is_animating());
        assert_eq!(cell.display(), 'Z');
    }

    #[test]
    fn mechanical_display_unchanged_during_flip() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);

        // Display stays as settled during mechanical phase
        cell.tick(40, &cs);
        assert_eq!(cell.display(), 'A');
        assert!(cell.is_animating());
    }

    // --- Combined ---

    #[test]
    fn combined_mechanical_then_sequential() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);

        // Distance = 6 (B,C,D,Ð,E,F), total = 480ms
        // Mechanical phase: 0-79ms
        assert!(matches!(cell.phase(), FlipPhase::Mechanical { .. }));

        cell.tick(80, &cs);
        assert_eq!(cell.phase(), FlipPhase::Sequential);
        assert_eq!(cell.display(), 'B');

        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'C');

        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'D');

        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'Ð');

        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'E');
        assert!(cell.is_animating());

        cell.tick(80, &cs);
        assert!(!cell.is_animating());
        assert_eq!(cell.display(), 'F');
    }

    #[test]
    fn combined_same_total_duration_as_sequential() {
        let cs = default_charset();

        let mut seq = FlapCell::new('A');
        seq.set_target('F', FlipStyle::Sequential, &cs, 80, 0);

        let mut comb = FlapCell::new('A');
        comb.set_target('F', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);

        // Both should complete at 480ms (distance 6 × 80ms)
        seq.tick(480, &cs);
        comb.tick(480, &cs);

        assert!(!seq.is_animating());
        assert!(!comb.is_animating());
    }

    #[test]
    fn combined_distance_one_no_sequential_phase() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('B', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);

        // Distance 1, total = 80ms, all mechanical
        assert!(matches!(cell.phase(), FlipPhase::Mechanical { .. }));

        cell.tick(80, &cs);
        assert!(!cell.is_animating());
        assert_eq!(cell.display(), 'B');
    }

    // --- General behavior ---

    #[test]
    fn progress_range() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Sequential, &cs, 80, 0);

        assert_eq!(cell.progress(), 0.0);

        cell.tick(200, &cs);
        let p = cell.progress();
        assert!(
            p > 0.0 && p < 1.0,
            "mid-flip progress should be in (0, 1), got {p}"
        );

        cell.tick(300, &cs);
        assert!(!cell.is_animating());
    }

    #[test]
    fn tick_past_completion_clamps() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('B', FlipStyle::Sequential, &cs, 80, 0);

        // Tick way past completion
        cell.tick(10_000, &cs);
        assert!(!cell.is_animating());
        assert_eq!(cell.display(), 'B');
    }

    #[test]
    fn tick_zero_is_noop() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Sequential, &cs, 80, 0);

        let progress_before = cell.progress();
        cell.tick(0, &cs);
        assert_eq!(cell.progress(), progress_before);
    }

    #[test]
    fn settled_cell_renders_character() {
        let cell = FlapCell::new('X');
        assert_eq!(cell.phase(), FlipPhase::Settled);
        assert_eq!(cell.display(), 'X');
    }

    // --- Interrupt resolution ---

    #[test]
    fn interrupt_sequential_starts_from_display() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Sequential, &cs, 80, 0);

        // step_forward(A, 14) = M (passes B,C,D,Ð,E,F,G,H,I,Ɨ,J,K,L,M)
        cell.tick(80 * 14, &cs);
        assert_eq!(cell.display(), 'M');

        // Interrupt with new target 'B'
        cell.set_target('B', FlipStyle::Sequential, &cs, 80, 0);

        // Should start from M, not snap back to A
        assert_eq!(cell.settled(), 'M');
        assert_eq!(cell.target(), 'B');

        // First intermediate after M should be N
        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'N');
    }

    #[test]
    fn interrupt_mechanical_early_resolves_to_settled() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);

        // Frame 1 of 4 = progress 0.25 (< 0.5) → resolve to settled
        cell.tick(20, &cs);

        cell.set_target('B', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);
        assert_eq!(cell.settled(), 'A');
    }

    #[test]
    fn interrupt_mechanical_late_resolves_to_target() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);

        // Frame 3 of 4 = progress 0.75 (>= 0.5) → resolve to target
        cell.tick(60, &cs);

        cell.set_target('B', FlipStyle::Mechanical { frames: 4 }, &cs, 80, 0);
        assert_eq!(cell.settled(), 'Z');
    }

    #[test]
    fn interrupt_combined_mechanical_phase_resolves_like_mechanical() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);

        // Still in mechanical phase (elapsed < flip_speed_ms)
        // Late in mechanical phase: 60ms of 80ms → resolve to target
        cell.tick(60, &cs);
        assert!(cell.in_mechanical_phase());

        cell.set_target('B', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);
        assert_eq!(cell.settled(), 'Z');
    }

    #[test]
    fn interrupt_combined_sequential_phase_starts_from_display() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);

        // Past mechanical phase, into sequential
        // At elapsed 160: seq_elapsed=80, step=2, display=step_forward(A,2)=C
        cell.tick(160, &cs);
        assert_eq!(cell.phase(), FlipPhase::Sequential);
        assert_eq!(cell.display(), 'C');

        cell.set_target('B', FlipStyle::Combined { frames: 3 }, &cs, 80, 0);
        assert_eq!(cell.settled(), 'C');
    }

    // --- Stagger ---

    #[test]
    fn pending_delay_consumed_before_animation() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Sequential, &cs, 80, 100);

        assert_eq!(cell.phase(), FlipPhase::Pending);

        // 60ms of pending consumed
        cell.tick(60, &cs);
        assert_eq!(cell.phase(), FlipPhase::Pending);

        // 40ms more → pending consumed, 0ms of animation elapsed
        cell.tick(40, &cs);
        assert_eq!(cell.phase(), FlipPhase::Sequential);
        assert_eq!(cell.display(), 'A');

        // After one full step, first flap lands
        cell.tick(80, &cs);
        assert_eq!(cell.display(), 'B');
    }

    #[test]
    fn pending_overflow_applies_to_animation() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('F', FlipStyle::Sequential, &cs, 80, 50);

        // Tick 130ms: 50ms pending + 80ms animation
        cell.tick(130, &cs);
        assert_eq!(cell.display(), 'B');
    }

    // --- Reset ---

    #[test]
    fn reset_clears_to_char() {
        let cs = default_charset();
        let mut cell = FlapCell::new('A');
        cell.set_target('Z', FlipStyle::Sequential, &cs, 80, 0);
        cell.tick(80, &cs);

        cell.reset(' ');
        assert_eq!(cell.display(), ' ');
        assert_eq!(cell.settled(), ' ');
        assert!(!cell.is_animating());
        assert_eq!(cell.progress(), 0.0);
    }
}