animations

kiln-tui/src/animation.rs

@@ -0,0 +1,44 @@
+//! The [`Animation`] trait and supporting types.
+//!
+//! An animation encapsulates a time-bounded visual effect: it advances via
+//! [`update`](Animation::update), renders via [`draw`](Animation::draw), and
+//! reports its layer and which [`InputMode`] to enter when it finishes.
+//!
+//! **While any animation is running, all input is ignored.** The front-end checks
+//! [`Ui::active_animation`](crate::ui::Ui::active_animation) before dispatching events.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use crate::input::InputMode;
+
+/// Which region of the terminal an animation occupies.
+pub enum AnimationLayer {
+    /// Renders in the inner board area, replacing the board (e.g. the wipe transition).
+    Board,
+    /// Renders over the full terminal area on top of the board (e.g. scroll open/close).
+    Overlay,
+}
+
+/// A time-bounded visual effect managed by [`Ui`](crate::ui::Ui).
+pub trait Animation {
+    /// Advance the animation by `dt` seconds. Returns `true` when the animation is done.
+    fn update(&mut self, dt: f32) -> bool;
+    /// Draw the current animation frame into `area` on `buf`.
+    fn draw(&self, area: Rect, buf: &mut Buffer);
+    /// Which region this animation draws to (board area vs. full overlay).
+    fn layer(&self) -> AnimationLayer;
+    /// Which [`InputMode`] to enter when the animation finishes.
+    fn input_mode_after(&self) -> InputMode;
+}
+
+/// Wraps a `&dyn Animation` as a ratatui [`Widget`] so it can be passed to
+/// `frame.render_widget`. The animation's [`draw`](Animation::draw) is called
+/// with the area provided by the layout.
+pub struct AnimWidget<'a>(pub &'a dyn Animation);
+
+impl Widget for AnimWidget<'_> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.0.draw(area, buf);
+    }
+}