blockworx/tutorial/

script.rs

//! Declarative instruction-animation scripts. A [`Script`] is a sequence of
//! timed [`Step`]s; playback is the pure [`Script::sample`] — a function of
//! elapsed seconds only, so the whole engine is testable with a fake clock.
//! Cursor positions stay symbolic ([`CueTarget`]) because a glide can span
//! coordinate spaces (toolbar button → canvas); the drawing pass resolves both
//! endpoints to screen space and lerps there.

use egui::Pos2;

use crate::grid::{GRID_SIZE, px};
use crate::schema::model as schema;
use crate::tools::names::ToolName;

/// The world-space position of a grid cell's corner — for authoring canvas
/// targets in the same units the level KDL uses.
pub fn grid_pos(x: i32, y: i32) -> Pos2 {
    egui::pos2(px(x), px(y))
}

/// A cue target on the canvas, in grid cells: `at(8, 6)`. Shipped scripts are
/// authored in level KDL; these constructors serve the tests.
#[cfg(test)]
pub fn at(x: i32, y: i32) -> CueTarget {
    CueTarget::World(grid_pos(x, y))
}

/// A cue target on the toolbar: `tool(NewBlock)`.
#[cfg(test)]
pub fn tool(name: ToolName) -> CueTarget {
    CueTarget::ToolButton(name)
}

/// A cue target at the live position of the block with this title: `block("core")`.
#[cfg(test)]
pub fn block(title: &'static str) -> CueTarget {
    CueTarget::Block(title)
}

/// A cue target on a live block's resize handle: `corner("core", RightBottom)`.
#[cfg(test)]
pub fn corner(title: &'static str, handle: Handle) -> CueTarget {
    CueTarget::Corner(title, handle)
}

/// Which resize handle of a block a cue points at.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Handle {
    LeftTop,
    RightTop,
    LeftBottom,
    RightBottom,
}

/// Where a cue points: a toolbar button (screen space, resolved from the
/// toolbar's stashed button rects), a fixed canvas position (world space), or a
/// spot anchored to the *live* document — the block with a given title, which
/// follows the block wherever the user actually put it.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum CueTarget {
    ToolButton(ToolName),
    World(Pos2),
    /// Center of the block with this title.
    Block(&'static str),
    /// A corner (resize handle) of the block with this title.
    Corner(&'static str, Handle),
}

impl CueTarget {
    /// The world position this target names, resolved against the projected
    /// document. `None` for screen-space targets ([`CueTarget::ToolButton`])
    /// and for document anchors naming a block that doesn't exist (yet).
    pub fn world(self, doc: &schema::Document) -> Option<Pos2> {
        let title_name =
            |b: &schema::Block| b.title.as_ref().map_or("", |l| l.name.as_str()).to_owned();
        let block_rect = |title: &str| {
            doc.blocks.iter().find(|b| title_name(b) == title).map(|b| {
                egui::Rect::from_min_size(
                    egui::pos2(b.x as f32, b.y as f32) * GRID_SIZE,
                    egui::vec2(b.w as f32, b.h as f32) * GRID_SIZE,
                )
            })
        };
        match self {
            CueTarget::ToolButton(_) => None,
            CueTarget::World(p) => Some(p),
            CueTarget::Block(title) => block_rect(title).map(|r| r.center()),
            CueTarget::Corner(title, handle) => block_rect(title).map(|r| match handle {
                Handle::LeftTop => r.left_top(),
                Handle::RightTop => r.right_top(),
                Handle::LeftBottom => r.left_bottom(),
                Handle::RightBottom => r.right_bottom(),
            }),
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum ClickCount {
    Single,
    Double,
}

impl ClickCount {
    fn presses(self) -> u32 {
        match self {
            ClickCount::Single => 1,
            ClickCount::Double => 2,
        }
    }
}

/// Seconds per animated click press (a [`Step::Click`] lasts one press per
/// [`ClickCount`]).
pub const CLICK_PRESS_SECS: f32 = 0.3;

#[derive(Clone, Copy)]
pub enum Step {
    /// Pulse a ring around the target; the cursor stays where it was.
    Highlight {
        target: CueTarget,
        secs: f32,
    },
    /// Glide the cursor to the target, button up.
    MoveTo {
        target: CueTarget,
        secs: f32,
    },
    /// Park the cursor on the target, button up — depicts hovering.
    Hover {
        target: CueTarget,
        secs: f32,
    },
    /// Flash the button at the target: one press per [`ClickCount`].
    Click {
        target: CueTarget,
        count: ClickCount,
    },
    /// Glide with the button held — depicts a drag.
    Drag {
        from: CueTarget,
        to: CueTarget,
        secs: f32,
    },
    /// Depict typing into an editor a previous step opened: `text` appears at
    /// the target a character at a time. The cursor stays where it was.
    Type {
        target: CueTarget,
        text: &'static str,
        secs: f32,
    },
    Pause {
        secs: f32,
    },
}

impl Step {
    fn secs(&self) -> f32 {
        match self {
            Step::Highlight { secs, .. }
            | Step::MoveTo { secs, .. }
            | Step::Hover { secs, .. }
            | Step::Drag { secs, .. }
            | Step::Type { secs, .. }
            | Step::Pause { secs } => *secs,
            Step::Click { count, .. } => count.presses() as f32 * CLICK_PRESS_SECS,
        }
    }

    /// Where the cursor rests once this step completes; `None` leaves it where
    /// the previous steps put it.
    fn end_cursor(&self) -> Option<CueTarget> {
        match self {
            Step::Highlight { .. } | Step::Type { .. } | Step::Pause { .. } => None,
            Step::MoveTo { target, .. }
            | Step::Hover { target, .. }
            | Step::Click { target, .. } => Some(*target),
            Step::Drag { to, .. } => Some(*to),
        }
    }
}

/// The fake cursor's position this frame. `Between` keeps both endpoints
/// symbolic so the draw pass can lerp them in screen space.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum CursorPos {
    At(CueTarget),
    Between {
        from: CueTarget,
        to: CueTarget,
        t: f32,
    },
}

#[derive(Clone, Copy, PartialEq, Debug)]
pub enum ButtonState {
    Up,
    /// Held through a drag.
    Down,
    /// A click press; `t` runs 0..1 through the press (drives the flash ring).
    Flash {
        t: f32,
    },
}

/// Text mid-entry: the prefix of a [`Step::Type`]'s text typed so far, and
/// where the editor receiving it sits.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct TypingCue {
    pub target: CueTarget,
    pub typed: &'static str,
}

/// One sampled animation frame.
#[derive(Clone, Copy, PartialEq, Debug)]
pub struct CueFrame {
    /// `None` until a step first establishes a cursor position (e.g. during an
    /// opening `Highlight`).
    pub cursor: Option<CursorPos>,
    pub button: ButtonState,
    pub highlight: Option<CueTarget>,
    pub typing: Option<TypingCue>,
}

#[derive(Clone)]
pub struct Script {
    steps: Vec<Step>,
}

fn ease(t: f32) -> f32 {
    t * t * (3.0 - 2.0 * t)
}

/// Assembles a [`Script`] one step at a time, so a test's script reads as a
/// sentence instead of a struct literal. Shipped scripts come from level KDL
/// (see [`super::level`]); the builder survives as the tests' authoring
/// surface.
#[cfg(test)]
#[derive(Default)]
pub struct ScriptBuilder {
    steps: Vec<Step>,
}

// A test utility keeps its full step vocabulary even when no current test
// exercises every method.
#[cfg(test)]
#[allow(dead_code)]
impl ScriptBuilder {
    #[must_use]
    pub fn highlight(self, target: CueTarget, secs: f32) -> Self {
        self.step(Step::Highlight { target, secs })
    }

    #[must_use]
    pub fn move_to(self, target: CueTarget, secs: f32) -> Self {
        self.step(Step::MoveTo { target, secs })
    }

    #[must_use]
    pub fn hover(self, target: CueTarget, secs: f32) -> Self {
        self.step(Step::Hover { target, secs })
    }

    #[must_use]
    pub fn click(self, target: CueTarget) -> Self {
        self.step(Step::Click {
            target,
            count: ClickCount::Single,
        })
    }

    #[must_use]
    pub fn double_click(self, target: CueTarget) -> Self {
        self.step(Step::Click {
            target,
            count: ClickCount::Double,
        })
    }

    #[must_use]
    pub fn drag(self, from: CueTarget, to: CueTarget, secs: f32) -> Self {
        self.step(Step::Drag { from, to, secs })
    }

    #[must_use]
    pub fn type_text(self, target: CueTarget, text: &'static str, secs: f32) -> Self {
        self.step(Step::Type { target, text, secs })
    }

    #[must_use]
    pub fn pause(self, secs: f32) -> Self {
        self.step(Step::Pause { secs })
    }

    pub fn build(self) -> Script {
        Script::new(self.steps)
    }

    #[must_use]
    fn step(mut self, step: Step) -> Self {
        self.steps.push(step);
        self
    }
}

#[cfg(test)]
impl From<ScriptBuilder> for Script {
    fn from(builder: ScriptBuilder) -> Self {
        builder.build()
    }
}

impl Script {
    #[cfg(test)]
    pub fn builder() -> ScriptBuilder {
        ScriptBuilder::default()
    }

    pub fn new(steps: Vec<Step>) -> Self {
        Self { steps }
    }

    /// One script playing `scripts` back to back — the whole-level demo
    /// derived from the per-stage scripts.
    pub fn concat<'a>(scripts: impl IntoIterator<Item = &'a Script>) -> Script {
        Script::new(
            scripts
                .into_iter()
                .flat_map(|s| s.steps.iter().copied())
                .collect(),
        )
    }

    pub fn steps(&self) -> &[Step] {
        &self.steps
    }

    pub fn total_secs(&self) -> f32 {
        self.steps.iter().map(Step::secs).sum()
    }

    /// The frame at `elapsed` seconds into the script, or `None` once the
    /// script has finished — it plays once; replaying is the caller re-anchoring
    /// its start time.
    pub fn sample(&self, elapsed: f64) -> Option<CueFrame> {
        if elapsed < 0.0 {
            return None;
        }
        let mut remaining = elapsed as f32;
        // The resting position accumulated from completed steps.
        let mut cursor: Option<CueTarget> = None;
        for step in &self.steps {
            let secs = step.secs();
            if remaining < secs {
                let p = remaining / secs.max(f32::EPSILON);
                return Some(Self::frame(step, cursor, p, remaining));
            }
            remaining -= secs;
            if let Some(c) = step.end_cursor() {
                cursor = Some(c);
            }
        }
        None
    }

    /// The frame `into_step` seconds (progress `p` in 0..1) into `step`, with
    /// the cursor previously resting at `prev`.
    fn frame(step: &Step, prev: Option<CueTarget>, p: f32, into_step: f32) -> CueFrame {
        let parked = prev.map(CursorPos::At);
        let base = CueFrame {
            cursor: parked,
            button: ButtonState::Up,
            highlight: None,
            typing: None,
        };
        match step {
            Step::Highlight { target, .. } => CueFrame {
                highlight: Some(*target),
                ..base
            },
            Step::Pause { .. } => base,
            Step::Hover { target, .. } => CueFrame {
                cursor: Some(CursorPos::At(*target)),
                ..base
            },
            Step::Type { target, text, .. } => CueFrame {
                typing: Some(TypingCue {
                    target: *target,
                    typed: typed_prefix(text, p),
                }),
                ..base
            },
            Step::MoveTo { target, .. } => CueFrame {
                // With no prior position the cursor appears at the target.
                cursor: Some(match prev {
                    Some(from) => CursorPos::Between {
                        from,
                        to: *target,
                        t: ease(p),
                    },
                    None => CursorPos::At(*target),
                }),
                ..base
            },
            Step::Click { target, .. } => CueFrame {
                cursor: Some(CursorPos::At(*target)),
                button: ButtonState::Flash {
                    t: (into_step / CLICK_PRESS_SECS).fract(),
                },
                ..base
            },
            Step::Drag { from, to, .. } => CueFrame {
                cursor: Some(CursorPos::Between {
                    from: *from,
                    to: *to,
                    t: ease(p),
                }),
                button: ButtonState::Down,
                ..base
            },
        }
    }
}

/// The characters of `text` entered by progress `p` through a [`Step::Type`].
/// Shared with the lowering pass, which types the same prefixes into the
/// captured editor buffer.
pub(super) fn typed_prefix(text: &'static str, p: f32) -> &'static str {
    let entered = (p.clamp(0.0, 1.0) * text.chars().count() as f32).ceil() as usize;
    let end = text
        .char_indices()
        .nth(entered)
        .map_or(text.len(), |(i, _)| i);
    &text[..end]
}

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

    fn demo() -> Script {
        Script::new(vec![
            Step::Highlight {
                target: CueTarget::ToolButton(ToolName::NewBlock),
                secs: 1.0,
            },
            Step::Click {
                target: CueTarget::ToolButton(ToolName::NewBlock),
                count: ClickCount::Double,
            },
            Step::Drag {
                from: CueTarget::World(grid_pos(0, 0)),
                to: CueTarget::World(grid_pos(8, 0)),
                secs: 2.0,
            },
            Step::Pause { secs: 0.5 },
        ])
    }

    #[test]
    fn totals_sum_step_durations() {
        // 1.0 highlight + 2 presses * 0.3 + 2.0 drag + 0.5 pause.
        let total = demo().total_secs();
        assert!((total - 4.1).abs() < 1e-6, "{total}");
    }

    #[test]
    fn highlight_has_no_cursor_until_one_is_established() {
        let frame = demo().sample(0.5).unwrap();
        assert_eq!(frame.cursor, None);
        assert_eq!(
            frame.highlight,
            Some(CueTarget::ToolButton(ToolName::NewBlock))
        );
        assert_eq!(frame.button, ButtonState::Up);
    }

    #[test]
    fn double_click_flashes_twice() {
        let script = demo();
        // First press: just after the highlight ends.
        let first = script.sample(1.0 + 0.1).unwrap();
        // Second press: one press-length later.
        let second = script.sample(1.0 + CLICK_PRESS_SECS as f64 + 0.1).unwrap();
        for frame in [first, second] {
            assert!(matches!(frame.button, ButtonState::Flash { .. }));
            assert_eq!(
                frame.cursor,
                Some(CursorPos::At(CueTarget::ToolButton(ToolName::NewBlock)))
            );
        }
        // The flash phase restarts for the second press.
        let ButtonState::Flash { t: t1 } = first.button else {
            unreachable!()
        };
        let ButtonState::Flash { t: t2 } = second.button else {
            unreachable!()
        };
        assert!((t1 - t2).abs() < 1e-3, "{t1} vs {t2}");
    }

    #[test]
    fn drag_interpolates_between_endpoints_with_button_down() {
        let script = demo();
        let drag_start = 1.0 + 2.0 * f64::from(CLICK_PRESS_SECS);
        let frame = script.sample(drag_start + 1.0).unwrap();
        assert_eq!(frame.button, ButtonState::Down);
        let Some(CursorPos::Between { t, .. }) = frame.cursor else {
            panic!("expected a lerping cursor, got {:?}", frame.cursor);
        };
        // Halfway through the eased glide.
        assert!((t - 0.5).abs() < 1e-3, "{t}");
    }

    #[test]
    fn pause_keeps_the_cursor_where_the_drag_left_it() {
        let script = demo();
        let pause_at = f64::from(script.total_secs()) - 0.25;
        let frame = script.sample(pause_at).unwrap();
        assert_eq!(
            frame.cursor,
            Some(CursorPos::At(CueTarget::World(grid_pos(8, 0))))
        );
    }

    #[test]
    fn doc_anchored_targets_follow_the_projected_block() {
        let doc = schema::Document::parse_kdl(
            r#"
top "b0"

block "b0" x=0 y=0 w=28 h=20 {
    title "sheet"
    children "b1"
}

block "b1" x=4 y=4 w=8 h=7 {
    title "core"
}
"#,
            "test",
        )
        .unwrap();
        assert_eq!(
            block("core").world(&doc),
            Some(grid_pos(8, 7).lerp(grid_pos(8, 8), 0.5))
        );
        assert_eq!(
            corner("core", Handle::RightBottom).world(&doc),
            Some(grid_pos(12, 11))
        );
        assert_eq!(block("missing").world(&doc), None);
        assert_eq!(tool(ToolName::NewBlock).world(&doc), None);
        assert_eq!(at(3, 5).world(&doc), Some(grid_pos(3, 5)));
    }

    #[test]
    fn typing_reveals_characters_and_leaves_the_cursor_parked() {
        let script = Script::new(vec![
            Step::MoveTo {
                target: CueTarget::World(grid_pos(4, 0)),
                secs: 1.0,
            },
            Step::Type {
                target: CueTarget::World(grid_pos(0, 0)),
                text: "CPU",
                secs: 3.0,
            },
        ]);
        let at = |t: f64| script.sample(1.0 + t).unwrap();
        assert_eq!(at(0.5).typing.unwrap().typed, "C");
        assert_eq!(at(1.5).typing.unwrap().typed, "CP");
        assert_eq!(at(2.9).typing.unwrap().typed, "CPU");
        assert_eq!(
            at(1.5).cursor,
            Some(CursorPos::At(CueTarget::World(grid_pos(4, 0))))
        );
    }

    #[test]
    fn finished_and_negative_times_yield_no_frame() {
        let script = demo();
        assert!(script.sample(-0.1).is_none());
        assert!(
            script
                .sample(f64::from(script.total_secs()) + 0.01)
                .is_none()
        );
    }
}