wowlab_types/stats/

timeline_layout.rs

// #t(file: rust_inline_test_module_size) timeline contract tests share private geometry and numeric helpers with this implementation

//! Timeline layout helpers shared by time-vs-event UI (tick placement and lane packing).

use core::cmp::Ordering;

use serde::{Deserialize, Serialize};

/// Target pixel gap between adjacent ticks when no caller preference is set.
pub const DEFAULT_TARGET_PIXELS_PER_TICK: u32 = 100;

const FALLBACK_STEP_MS: f64 = 1_000.0;

#[derive(Clone, Copy)]
struct IndexedInterval {
    original_index: usize,
    start: f64,
    end: f64,
}

#[rustfmt::skip]
const NICE_STEPS_MS: &[f64] = &[
    50.0,
    100.0,
    250.0,
    500.0,
    1_000.0,
    2_000.0,
    5_000.0,
    10_000.0,
    15_000.0,
    30_000.0,
    60_000.0,
    120_000.0,
    300_000.0,
    600_000.0,
    1_800_000.0,
    3_600_000.0,
];

/// Pick "nice" tick positions (ms) inside `[0, duration_ms]` for a timeline axis.
#[must_use]
pub fn compute_timeline_ticks(
    duration_ms: f64,
    pixels_per_ms: f64,
    target_pixels_per_tick: u32,
) -> Vec<f64> {
    if !duration_ms.is_finite() || duration_ms <= 0.0 {
        return Vec::new();
    }

    if !pixels_per_ms.is_finite() || pixels_per_ms <= 0.0 {
        return Vec::new();
    }

    let target_ms = f64::from(target_pixels_per_tick) / pixels_per_ms;
    let largest_step = NICE_STEPS_MS.last().copied().unwrap_or(FALLBACK_STEP_MS);
    let step = NICE_STEPS_MS
        .iter()
        .copied()
        .find(|s| *s >= target_ms)
        .unwrap_or(largest_step);

    let mut out = Vec::new();
    let mut t = 0.0;

    while t <= duration_ms + f64::EPSILON {
        out.push(t);
        t += step;
    }

    out
}

/// Pack `(start, end)` intervals into non-overlapping lanes via greedy scheduling, returning lanes in input order.
#[must_use]
pub fn assign_timeline_lanes(starts: &[f64], ends: &[f64]) -> Vec<u32> {
    let n = starts.len().min(ends.len());

    if n == 0 {
        return Vec::new();
    }

    let mut indexed: Vec<IndexedInterval> = (0..n)
        .filter_map(|index| normalized_interval(index, starts, ends))
        .collect();

    indexed.sort_by(|a, b| a.start.partial_cmp(&b.start).unwrap_or(Ordering::Equal));

    let mut lane_ends: Vec<f64> = Vec::new();
    let mut lanes: Vec<u32> = vec![0; n];

    for IndexedInterval {
        original_index,
        start,
        end,
    } in indexed
    {
        if !start.is_finite() {
            continue;
        }

        let lane_idx = reserve_lane(&mut lane_ends, start, end);
        let lane_u32 = u32::try_from(lane_idx).unwrap_or(u32::MAX);
        // BOUNDS: original_index came from `0..n` and `lanes` has length `n`.

        if let Some(slot) = lanes.get_mut(original_index) {
            *slot = lane_u32;
        }
    }

    lanes
}

fn normalized_interval(index: usize, starts: &[f64], ends: &[f64]) -> Option<IndexedInterval> {
    let start = *starts.get(index)?;
    let end = *ends.get(index)?;

    if !start.is_finite() || !end.is_finite() || end < start {
        return Some(IndexedInterval {
            original_index: index,
            start: f64::NEG_INFINITY,
            end: f64::NEG_INFINITY,
        });
    }

    Some(IndexedInterval {
        original_index: index,
        start,
        end,
    })
}

fn reserve_lane(lane_ends: &mut Vec<f64>, start: f64, end: f64) -> usize {
    let Some(index) = lane_ends.iter().position(|lane_end| *lane_end <= start) else {
        lane_ends.push(end);

        return lane_ends.len() - 1;
    };

    if let Some(lane_end) = lane_ends.get_mut(index) {
        *lane_end = end;
    }

    index
}

/// Layout + viewport inputs for a timeline (pixels and milliseconds; `zoom`/`pan_ms` are clamped by the math).
#[derive(Clone, Debug, Deserialize, Serialize)]
#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
#[cfg_attr(feature = "wasm", tsify(from_wasm_abi))]
#[serde(rename_all = "camelCase")]
pub struct TimelineGeometry {
    pub container_width: f64,
    pub gutter_width: f64,
    pub right_gutter: f64,
    pub duration_ms: f64,
    pub pan_ms: f64,
    pub zoom: f64,
    pub min_zoom: f64,
    pub max_zoom: f64,
}

/// Derived pixel/time geometry for one render of a timeline.
#[derive(Clone, Debug, Serialize)]
#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
#[cfg_attr(feature = "wasm", tsify(into_wasm_abi))]
#[serde(rename_all = "camelCase")]
pub struct TimelineMetrics {
    pub track_width: f64,
    pub px_per_ms: f64,
    pub visible_ms: f64,
    pub safe_zoom: f64,
    pub clamped_pan_ms: f64,
    pub max_pan_ms: f64,
    pub visible_start_ms: f64,
    pub visible_end_ms: f64,
    pub ticks: Vec<f64>,
}

/// A timeline viewport: the committed pan offset and zoom factor.
#[derive(Clone, Debug, Serialize)]
#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
#[cfg_attr(feature = "wasm", tsify(into_wasm_abi))]
#[serde(rename_all = "camelCase")]
pub struct TimelineViewport {
    pub pan_ms: f64,
    pub zoom: f64,
}

fn clamp(value: f64, lo: f64, hi: f64) -> f64 {
    value.max(lo).min(hi)
}

/// Derive all pixel/time geometry (including axis ticks) for one timeline render; the source of truth for px<->ms.
#[must_use]
pub fn compute_timeline_metrics(geo: &TimelineGeometry) -> TimelineMetrics {
    let track_width = (geo.container_width - geo.gutter_width - geo.right_gutter).max(0.0);
    let safe_zoom = clamp(geo.zoom, geo.min_zoom, geo.max_zoom);
    let visible_ms = if geo.duration_ms > 0.0 {
        geo.duration_ms / safe_zoom
    } else {
        0.0
    };
    let px_per_ms = if track_width > 0.0 && visible_ms > 0.0 {
        track_width / visible_ms
    } else {
        0.0
    };
    let max_pan_ms = (geo.duration_ms - visible_ms).max(0.0);
    let clamped_pan_ms = clamp(geo.pan_ms, 0.0, max_pan_ms);
    let ticks = compute_timeline_ticks(geo.duration_ms, px_per_ms, DEFAULT_TARGET_PIXELS_PER_TICK);

    TimelineMetrics {
        track_width,
        px_per_ms,
        visible_ms,
        safe_zoom,
        clamped_pan_ms,
        max_pan_ms,
        visible_start_ms: clamped_pan_ms,
        visible_end_ms: clamped_pan_ms + visible_ms,
        ticks,
    }
}

/// Compute the new viewport after a cursor-anchored zoom step (`local_x` pixels from the track left, cursor time fixed).
#[must_use]
pub fn zoom_timeline_at(
    geo: &TimelineGeometry,
    local_x: f64,
    zoom_in: bool,
    zoom_factor: f64,
) -> TimelineViewport {
    let m = compute_timeline_metrics(geo);

    if m.track_width <= 0.0 || geo.duration_ms <= 0.0 || local_x < 0.0 || local_x > m.track_width {
        return TimelineViewport {
            pan_ms: m.clamped_pan_ms,
            zoom: m.safe_zoom,
        };
    }

    let cursor_fraction = local_x / m.track_width;
    let cursor_ms = m.clamped_pan_ms + cursor_fraction * m.visible_ms;
    let factor = if zoom_in {
        zoom_factor
    } else {
        1.0 / zoom_factor
    };
    let next_zoom = clamp(m.safe_zoom * factor, geo.min_zoom, geo.max_zoom);
    let next_visible_ms = geo.duration_ms / next_zoom;
    let next_max_pan = (geo.duration_ms - next_visible_ms).max(0.0);
    let next_pan = clamp(
        cursor_ms - cursor_fraction * next_visible_ms,
        0.0,
        next_max_pan,
    );

    TimelineViewport {
        pan_ms: next_pan,
        zoom: next_zoom,
    }
}

/// Compute the new viewport after dragging the track by `delta_px` pixels (zoom unchanged).
#[must_use]
pub fn pan_timeline_by(
    geo: &TimelineGeometry,
    start_pan_ms: f64,
    delta_px: f64,
) -> TimelineViewport {
    let m = compute_timeline_metrics(geo);

    if m.track_width <= 0.0 {
        return TimelineViewport {
            pan_ms: m.clamped_pan_ms,
            zoom: m.safe_zoom,
        };
    }

    let delta_ms = -(delta_px / m.track_width) * m.visible_ms;
    let next_pan = clamp(start_pan_ms + delta_ms, 0.0, m.max_pan_ms);

    TimelineViewport {
        pan_ms: next_pan,
        zoom: m.safe_zoom,
    }
}

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

    use super::*;

    const TOL: f64 = 1e-9;

    #[gtest]
    fn ticks_empty_for_zero_duration() -> Result<()> {
        verify_that!(compute_timeline_ticks(0.0, 1.0, 100), is_empty())
    }

    #[gtest]
    fn ticks_empty_for_zero_zoom() -> Result<()> {
        verify_that!(compute_timeline_ticks(10_000.0, 0.0, 100), is_empty())
    }

    #[gtest]
    fn ticks_pick_one_second_step_at_typical_zoom() -> Result<()> {
        let ticks = compute_timeline_ticks(10_000.0, 0.1, 100);

        verify_that!(
            ticks,
            container_eq([
                0.0, 1_000.0, 2_000.0, 3_000.0, 4_000.0, 5_000.0, 6_000.0, 7_000.0, 8_000.0,
                9_000.0, 10_000.0,
            ])
        )
    }

    #[gtest]
    fn ticks_pick_ten_second_step_when_zoomed_out() -> Result<()> {
        let ticks = compute_timeline_ticks(60_000.0, 0.01, 100);

        verify_that!(
            ticks,
            container_eq([
                0.0, 10_000.0, 20_000.0, 30_000.0, 40_000.0, 50_000.0, 60_000.0
            ])
        )
    }

    #[gtest]
    fn ticks_pick_fine_step_when_zoomed_in() -> Result<()> {
        let ticks = compute_timeline_ticks(200.0, 2.0, 100);

        verify_that!(ticks, container_eq([0.0, 50.0, 100.0, 150.0, 200.0]))
    }

    #[gtest]
    fn lanes_single_lane_for_disjoint_events() -> Result<()> {
        let starts = vec![0.0, 1_000.0, 2_000.0];
        let ends = vec![500.0, 1_500.0, 2_500.0];
        let lanes = assign_timeline_lanes(&starts, &ends);

        verify_that!(lanes, container_eq([0, 0, 0]))
    }

    #[gtest]
    fn lanes_stack_overlapping_events() -> Result<()> {
        let starts = vec![0.0, 500.0, 2_000.0];
        let ends = vec![1_000.0, 1_500.0, 3_000.0];
        let lanes = assign_timeline_lanes(&starts, &ends);

        verify_that!(lanes, elements_are![eq(&0u32), eq(&1u32), eq(&0u32)])
    }

    #[gtest]
    fn lanes_handles_three_concurrent_events() -> Result<()> {
        let starts = vec![0.0, 100.0, 200.0];
        let ends = vec![1_000.0, 1_000.0, 1_000.0];
        let lanes = assign_timeline_lanes(&starts, &ends);
        let mut sorted = lanes.clone();

        sorted.sort_unstable();

        verify_that!(sorted, container_eq([0, 1, 2]))
    }

    #[gtest]
    fn lanes_empty_input() -> Result<()> {
        verify_that!(assign_timeline_lanes(&[], &[]), is_empty())
    }

    #[gtest]
    fn lanes_preserves_input_order() -> Result<()> {
        let starts = vec![2_000.0, 0.0, 500.0];
        let ends = vec![3_000.0, 1_000.0, 1_500.0];
        let lanes = assign_timeline_lanes(&starts, &ends);

        verify_that!(lanes, elements_are![eq(&0u32), eq(&0u32), eq(&1u32)])
    }

    #[gtest]
    fn lanes_ignore_invalid_intervals_without_consuming_lanes() -> Result<()> {
        let starts = vec![f64::NAN, 0.0, 500.0, 2_000.0];
        let ends = vec![1_000.0, 1_000.0, 100.0, 3_000.0];

        verify_that!(
            assign_timeline_lanes(&starts, &ends),
            container_eq([0, 0, 0, 0])
        )
    }

    #[gtest]
    fn lanes_use_only_the_shared_input_prefix() -> Result<()> {
        verify_that!(
            assign_timeline_lanes(&[0.0, 100.0], &[50.0]),
            container_eq([0])
        )
    }

    fn geo(zoom: f64, pan_ms: f64) -> TimelineGeometry {
        TimelineGeometry {
            container_width: 1_000.0,
            gutter_width: 0.0,
            right_gutter: 0.0,
            duration_ms: 10_000.0,
            pan_ms,
            zoom,
            min_zoom: 1.0,
            max_zoom: 200.0,
        }
    }

    #[gtest]
    fn metrics_fit_to_track() -> Result<()> {
        let m = compute_timeline_metrics(&geo(1.0, 0.0));

        wowlab_test_support::verify_all!(
            m.track_width => near(1_000.0, TOL),
            m.visible_ms => near(10_000.0, TOL),
            m.max_pan_ms => near(0.0, TOL),
            m.clamped_pan_ms => near(0.0, TOL),
            m.visible_end_ms => near(10_000.0, TOL),
            m.px_per_ms => near(0.1, 1e-12),
            m.ticks.len() => eq(11),
        )
    }

    #[gtest]
    fn metrics_gutters_reduce_track_width() -> Result<()> {
        let mut g = geo(1.0, 0.0);

        g.gutter_width = 80.0;
        g.right_gutter = 8.0;
        let m = compute_timeline_metrics(&g);

        verify_that!(m.track_width, near(912.0, TOL))
    }

    #[gtest]
    fn metrics_clamp_pan_to_window() -> Result<()> {
        let m = compute_timeline_metrics(&geo(2.0, 999_999.0));

        wowlab_test_support::verify_all!(
            m.visible_ms => near(5_000.0, TOL),
            m.max_pan_ms => near(5_000.0, TOL),
            m.clamped_pan_ms => near(5_000.0, TOL),
            m.visible_end_ms => near(10_000.0, TOL),
        )
    }

    #[gtest]
    fn metrics_zero_duration_is_empty() -> Result<()> {
        let mut g = geo(1.0, 0.0);

        g.duration_ms = 0.0;
        let m = compute_timeline_metrics(&g);

        wowlab_test_support::verify_all!(
            m.px_per_ms => near(0.0, TOL),
            m.visible_ms => near(0.0, TOL),
            m.ticks => is_empty(),
        )
    }

    #[gtest]
    fn zoom_in_keeps_cursor_time_fixed() -> Result<()> {
        let v = zoom_timeline_at(&geo(1.0, 0.0), 500.0, true, 2.0);

        verify_that!(v.zoom, near(2.0, TOL))?;
        verify_that!(v.pan_ms, near(2_500.0, TOL))?;
        let after = compute_timeline_metrics(&geo(v.zoom, v.pan_ms));
        let cursor = after.clamped_pan_ms + 0.5 * after.visible_ms;

        verify_that!(cursor, near(5_000.0, TOL))
    }

    #[gtest]
    fn zoom_out_clamps_to_min_zoom() -> Result<()> {
        let v = zoom_timeline_at(&geo(1.0, 0.0), 500.0, false, 2.0);

        wowlab_test_support::verify_all!(
            v.zoom => near(1.0, TOL),
            v.pan_ms => near(0.0, TOL),
        )
    }

    #[gtest]
    fn zoom_in_clamps_to_max_zoom() -> Result<()> {
        let v = zoom_timeline_at(&geo(200.0, 0.0), 500.0, true, 2.0);

        verify_that!(v.zoom, near(200.0, TOL))
    }

    #[gtest]
    fn zoom_ignores_cursor_outside_track() -> Result<()> {
        let v = zoom_timeline_at(&geo(1.0, 0.0), 2_000.0, true, 2.0);

        wowlab_test_support::verify_all!(
            v.zoom => near(1.0, TOL),
            v.pan_ms => near(0.0, TOL),
        )
    }

    #[gtest]
    fn pan_drag_right_moves_window_earlier() -> Result<()> {
        let v = pan_timeline_by(&geo(2.0, 2_000.0), 2_000.0, 100.0);

        wowlab_test_support::verify_all!(
            v.zoom => near(2.0, TOL),
            v.pan_ms => near(1_500.0, TOL),
        )
    }

    #[gtest]
    fn pan_clamps_at_zero() -> Result<()> {
        let v = pan_timeline_by(&geo(2.0, 0.0), 0.0, 100.0);

        verify_that!(v.pan_ms, near(0.0, TOL))
    }
}