htui 0.2.0

A terminal HTML/CSS renderer with an embedded JavaScript engine — build interactive TUIs from HTML, CSS and JS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! Pure mouse-interaction logic (hit testing + dispatch), independent of the
//! terminal event source.
//!
//! `input.rs` feeds crossterm mouse events into [`on_click`] / [`on_move`]
//! after converting screen coordinates to canvas coordinates; the tests drive
//! these functions directly with canvas coordinates, so no terminal is needed.

use crate::{script::ScriptEngine, tui::graph_api::RenderCmd};

use super::{EventType, HitMap, HitRegion};

/// Tracks the element currently under the pointer for enter / leave
/// detection.
#[derive(Debug, Default)]
pub struct HoverState {
    current: Option<HitRegion>,
}

impl HoverState {
    /// Create a hover state with no target.
    pub fn new() -> Self {
        Self::default()
    }

    /// Region currently hovered, if any.
    pub fn current(&self) -> Option<&HitRegion> {
        self.current.as_ref()
    }
}

/// Process a pointer move at canvas coordinates `(x, y)`.
///
/// Detects pointer enter / leave against the previous hover target and
/// dispatches the matching events: bubbling [`EventType::MouseOut`] /
/// [`EventType::MouseOver`] plus the non-bubbling [`EventType::MouseLeave`]
/// / [`EventType::MouseEnter`] pair (leave before enter, matching the DOM).
/// When the hover target changes, a `Hover` command is emitted so the render
/// thread can re-style the document for CSS `:hover` rules — with no `:hover`
/// CSS, the command changes nothing visually, exactly like a browser. Returns
/// the render commands to run, in order.
pub fn on_move(
    state: &mut HoverState,
    hit_map: &HitMap,
    engine: &mut ScriptEngine,
    x: u32,
    y: u32,
) -> Vec<RenderCmd> {
    let mut cmds = Vec::new();
    let new_hover = hit_map.hit_test(x, y);
    let hover_changed = new_hover.map(|r| r.node_id) != state.current.as_ref().map(|r| r.node_id);
    if !hover_changed {
        return cmds;
    }
    if let Some(old) = state.current.take() {
        cmds.extend(engine.fire_target(&old, EventType::MouseLeave, x, y));
        cmds.extend(engine.fire(&old, EventType::MouseOut, x, y));
    }
    state.current = new_hover.cloned();
    if let Some(region) = new_hover {
        cmds.extend(engine.fire_target(region, EventType::MouseEnter, x, y));
        cmds.extend(engine.fire(region, EventType::MouseOver, x, y));
    }
    cmds.push(RenderCmd::Hover {
        node_id: new_hover.map(|r| r.node_id),
    });
    cmds
}

/// Dispatch a `MouseDown` event at `(x, y)`.
pub fn on_mouse_down(
    hit_map: &HitMap,
    engine: &mut ScriptEngine,
    x: u32,
    y: u32,
) -> Vec<RenderCmd> {
    let Some(region) = hit_map.hit_test(x, y) else {
        return Vec::new();
    };
    engine.fire(region, EventType::MouseDown, x, y)
}

/// Dispatch a `MouseUp` event at `(x, y)`.
pub fn on_mouse_up(hit_map: &HitMap, engine: &mut ScriptEngine, x: u32, y: u32) -> Vec<RenderCmd> {
    let Some(region) = hit_map.hit_test(x, y) else {
        return Vec::new();
    };
    engine.fire(region, EventType::MouseUp, x, y)
}

/// Dispatch a `MouseMove` event at `(x, y)`. Fires on every call (the input
/// loop's in-flight cap provides the back-pressure), not just on hover change.
pub fn on_mouse_move_dispatch(
    hit_map: &HitMap,
    engine: &mut ScriptEngine,
    x: u32,
    y: u32,
) -> Vec<RenderCmd> {
    let Some(region) = hit_map.hit_test(x, y) else {
        return Vec::new();
    };
    engine.fire(region, EventType::MouseMove, x, y)
}

/// Process a click at canvas coordinates `(x, y)`.
///
/// A click implies the pointer is over the target, so the hover state is
/// synchronised first (emitting a `Hover` command when the target changed, so
/// CSS `:hover` styling stays correct), then the [`EventType::Click`] event is
/// dispatched with bubbling through the script engine.
pub fn on_click(
    state: &mut HoverState,
    hit_map: &HitMap,
    engine: &mut ScriptEngine,
    x: u32,
    y: u32,
) -> Vec<RenderCmd> {
    let mut cmds = Vec::new();
    let Some(region) = hit_map.hit_test(x, y) else {
        return cmds;
    };
    if state.current.as_ref().map(|r| r.node_id) != Some(region.node_id) {
        state.current = Some(region.clone());
        cmds.push(RenderCmd::Hover {
            node_id: Some(region.node_id),
        });
    }
    cmds.extend(engine.fire(region, EventType::Click, x, y));
    cmds
}