termcinema-engine 0.1.0

use crate::constants::*;

/// Controls playback behavior of the SVG animation.
///
/// This struct defines timing-related parameters that
/// influence how characters are rendered over time:
///
/// - [`frame_delay`]     → typing interval per character (ms);
/// - [`fade_duration`]   → fade-in duration per character (ms);
/// - [`start_delay`]     → delay before animation begins (ms).
///
/// These values can be customized via CLI arguments or presets.
#[derive(Clone)]
pub struct ControlSpec {
    /// Optional delay per character in milliseconds (typing speed).
    /// If `None`, falls back to [`DEFAULT_CONTROL_FRAME_DELAY`].
    pub frame_delay: Option<u32>,

    /// Optional duration of character fade-in animation (in ms).
    /// If `None`, falls back to [`DEFAULT_CONTROL_FADE_DURATION`].
    pub fade_duration: Option<u32>,

    /// Optional initial delay before animation starts (in ms).
    /// If `None`, falls back to [`DEFAULT_CONTROL_START_DELAY`].
    pub start_delay: Option<u32>,
}

/// Default timing values for [`ControlSpec`].
///
/// These defaults are context-agnostic and used when
/// no override is provided (e.g. from CLI or theme).
impl Default for ControlSpec {
    fn default() -> Self {
        ControlSpec {
            frame_delay: Some(DEFAULT_CONTROL_FRAME_DELAY),
            fade_duration: Some(DEFAULT_CONTROL_FADE_DURATION),
            start_delay: Some(DEFAULT_CONTROL_START_DELAY),
        }
    }
}

/// Unwraps optional control values into concrete timings.
///
/// This utility function extracts the final values used
/// in rendering, applying fallback defaults if any field is `None`.
///
/// Returns a tuple: `(frame_delay, fade_duration, start_delay)`
/// — all in milliseconds.
#[rustfmt::skip]
pub(crate) fn extract_control_primitives(control: &ControlSpec) -> (u32, u32, u32) {
    (
        control.frame_delay.unwrap_or(DEFAULT_CONTROL_FRAME_DELAY),
        control.fade_duration.unwrap_or(DEFAULT_CONTROL_FADE_DURATION),
        control.start_delay.unwrap_or(DEFAULT_CONTROL_START_DELAY),
    )
}