Guide API
Skip to main content

tvision_rs/
junction.rs

1//! View-independent vocabulary for joining box-drawing linework: which frame
2//! edge a divider abuts, the weight (single/double) of each line, and the pure
3//! glyph-selector functions that map an (edge, bar-weight, stem-weight) tuple to
4//! the matching box character in [`Glyphs`].
5//!
6//! This is the tvision-rs-local equivalent of Turbo Vision's `frameChars[mask]` table
7//! (`framelin.cpp`): a small finite map with no view dependencies, so it is
8//! exhaustively unit-testable. The owning [`Window`](crate::window::Window)
9//! pushes [`JunctionMark`]s down to its [`Frame`](crate::frame::Frame), which
10//! calls [`frame_junction`] per marked edge cell; the outer
11//! [`Splitter`](crate::widgets::Splitter) calls [`divider_junction`] for its
12//! interior crossings. See the design spec
13//! `docs/superpowers/specs/2026-06-13-splitter-frame-joining-design.md`.
14//!
15//! # Turbo Vision heritage
16//! **tvision-rs extension**: no Turbo Vision counterpart. It joins
17//! [`Splitter`](crate::widgets::Splitter) dividers to the window frame; the
18//! glyph lookup follows the idea of `frameChars[mask]` in `framelin.cpp`.
19
20use crate::theme::Glyphs;
21
22/// Which frame edge a divider abutment (or junction cell) lands on.
23#[derive(Clone, Copy, PartialEq, Eq, Debug)]
24pub enum Edge {
25    Top,
26    Bottom,
27    Left,
28    Right,
29}
30
31/// The drawn weight of a line (a frame border or a divider).
32#[derive(Clone, Copy, PartialEq, Eq, Debug)]
33pub enum Weight {
34    Single,
35    Double,
36}
37
38/// A divider abutment the owning window pushes down to its frame: the divider's
39/// line meets the frame `edge` at frame-local `offset` along that edge, drawn at
40/// the divider's `stem` weight. The frame substitutes the matching tee glyph
41/// (chosen from its own border weight × this `stem`).
42#[derive(Clone, Copy, PartialEq, Eq, Debug)]
43pub struct JunctionMark {
44    /// Which frame edge this lands on.
45    pub edge: Edge,
46    /// Frame-local position along that edge (x for Top/Bottom, y for Left/Right).
47    pub offset: i32,
48    /// The abutting divider's drawn weight.
49    pub stem: Weight,
50}
51
52/// Where two dividers meet in the interior (Site 2). `TeeRight` = a vertical
53/// line with a branch going right (`├`); `TeeDown` = a horizontal line with a
54/// branch going down (`┬`); `Cross` = both perpendicular branches (`┼`). Named
55/// by the visual branch direction, matching the existing `frame_tee_*` glyph
56/// names in [`Glyphs`].
57#[derive(Clone, Copy, PartialEq, Eq, Debug)]
58pub enum Junction {
59    TeeRight,
60    TeeLeft,
61    TeeUp,
62    TeeDown,
63    Cross,
64}
65
66/// Pick the box-drawing junction for a frame edge cell that a divider abuts.
67///
68/// * `edge` — which frame edge the cell is on.
69/// * `bar` — the frame border's own weight (Double when the window is active).
70/// * `stem` — the abutting divider's weight.
71///
72/// The naming key in [`Glyphs`]: `_d` = both double; `_dh`/`_dv` = double bar
73/// with a single perpendicular stem; `_sh`/`_sv` = single bar with a double stem.
74/// For Top/Bottom the bar is horizontal (`_dh`/`_sh`); for Left/Right the bar is
75/// vertical (`_dv`/`_sv`).
76pub fn frame_junction(edge: Edge, bar: Weight, stem: Weight, g: &Glyphs) -> char {
77    use Edge::*;
78    use Weight::*;
79    match (edge, bar, stem) {
80        // Top edge → tee pointing down (┬ family).
81        (Top, Single, Single) => g.frame_tee_t,
82        (Top, Double, Single) => g.frame_tee_t_dh,
83        (Top, Double, Double) => g.frame_tee_t_d,
84        (Top, Single, Double) => g.frame_tee_t_sh,
85        // Bottom edge → tee pointing up (┴ family).
86        (Bottom, Single, Single) => g.frame_tee_b,
87        (Bottom, Double, Single) => g.frame_tee_b_dh,
88        (Bottom, Double, Double) => g.frame_tee_b_d,
89        (Bottom, Single, Double) => g.frame_tee_b_sh,
90        // Left edge → tee pointing right (├ family).
91        (Left, Single, Single) => g.frame_tee_l,
92        (Left, Double, Single) => g.frame_tee_l_dv,
93        (Left, Double, Double) => g.frame_tee_l_d,
94        (Left, Single, Double) => g.frame_tee_l_sv,
95        // Right edge → tee pointing left (┤ family).
96        (Right, Single, Single) => g.frame_tee_r,
97        (Right, Double, Single) => g.frame_tee_r_dv,
98        (Right, Double, Double) => g.frame_tee_r_d,
99        (Right, Single, Double) => g.frame_tee_r_sv,
100    }
101}
102
103/// Pick the box-drawing junction where two dividers meet in the interior.
104///
105/// `dir` is the visual shape (which way the branch points); `weight` is the
106/// shared divider weight. For this feature both the through-divider and the
107/// branching divider carry the same weight at draw time (a divider never changes
108/// weight), so a single `weight` parameter suffices — mixed interior crossings
109/// are out of scope (the spec's non-goals).
110pub fn divider_junction(dir: Junction, weight: Weight, g: &Glyphs) -> char {
111    use Junction::*;
112    use Weight::*;
113    match (dir, weight) {
114        (TeeRight, Single) => g.frame_tee_l,   // ├
115        (TeeRight, Double) => g.frame_tee_l_d, // ╠
116        (TeeLeft, Single) => g.frame_tee_r,    // ┤
117        (TeeLeft, Double) => g.frame_tee_r_d,  // ╣
118        (TeeUp, Single) => g.frame_tee_b,      // ┴
119        (TeeUp, Double) => g.frame_tee_b_d,    // ╩
120        (TeeDown, Single) => g.frame_tee_t,    // ┬
121        (TeeDown, Double) => g.frame_tee_t_d,  // ╦
122        (Cross, Single) => g.frame_cross,      // ┼
123        (Cross, Double) => g.frame_cross_d,    // ╬
124    }
125}
126
127#[cfg(test)]
128mod tests {
129    use super::*;
130    use crate::theme::Glyphs;
131
132    fn g() -> Glyphs {
133        Glyphs::default()
134    }
135
136    #[test]
137    fn frame_junction_single_bar_single_stem() {
138        let g = g();
139        assert_eq!(
140            frame_junction(Edge::Top, Weight::Single, Weight::Single, &g),
141            '┬'
142        );
143        assert_eq!(
144            frame_junction(Edge::Bottom, Weight::Single, Weight::Single, &g),
145            '┴'
146        );
147        assert_eq!(
148            frame_junction(Edge::Left, Weight::Single, Weight::Single, &g),
149            '├'
150        );
151        assert_eq!(
152            frame_junction(Edge::Right, Weight::Single, Weight::Single, &g),
153            '┤'
154        );
155    }
156
157    #[test]
158    fn frame_junction_double_bar_single_stem_is_mixed() {
159        let g = g();
160        assert_eq!(
161            frame_junction(Edge::Top, Weight::Double, Weight::Single, &g),
162            '╤'
163        );
164        assert_eq!(
165            frame_junction(Edge::Bottom, Weight::Double, Weight::Single, &g),
166            '╧'
167        );
168        assert_eq!(
169            frame_junction(Edge::Left, Weight::Double, Weight::Single, &g),
170            '╟' // U+255F — double bar + single right stem
171        );
172        assert_eq!(
173            frame_junction(Edge::Right, Weight::Double, Weight::Single, &g),
174            '╢' // U+2562 — double bar + single left stem
175        );
176    }
177
178    #[test]
179    fn frame_junction_double_bar_double_stem() {
180        let g = g();
181        assert_eq!(
182            frame_junction(Edge::Top, Weight::Double, Weight::Double, &g),
183            '╦'
184        );
185        assert_eq!(
186            frame_junction(Edge::Bottom, Weight::Double, Weight::Double, &g),
187            '╩'
188        );
189        assert_eq!(
190            frame_junction(Edge::Left, Weight::Double, Weight::Double, &g),
191            '╠'
192        );
193        assert_eq!(
194            frame_junction(Edge::Right, Weight::Double, Weight::Double, &g),
195            '╣'
196        );
197    }
198
199    #[test]
200    fn frame_junction_single_bar_double_stem_is_rare_mixed() {
201        let g = g();
202        assert_eq!(
203            frame_junction(Edge::Top, Weight::Single, Weight::Double, &g),
204            '╥'
205        );
206        assert_eq!(
207            frame_junction(Edge::Bottom, Weight::Single, Weight::Double, &g),
208            '╨'
209        );
210        assert_eq!(
211            frame_junction(Edge::Left, Weight::Single, Weight::Double, &g),
212            '╞' // U+255E — single bar + double right stem
213        );
214        assert_eq!(
215            frame_junction(Edge::Right, Weight::Single, Weight::Double, &g),
216            '╡' // U+2561 — single bar + double left stem
217        );
218    }
219
220    #[test]
221    fn divider_junction_all_directions() {
222        let g = g();
223        assert_eq!(
224            divider_junction(Junction::TeeRight, Weight::Single, &g),
225            '├'
226        );
227        assert_eq!(divider_junction(Junction::TeeLeft, Weight::Single, &g), '┤');
228        assert_eq!(divider_junction(Junction::TeeUp, Weight::Single, &g), '┴');
229        assert_eq!(divider_junction(Junction::TeeDown, Weight::Single, &g), '┬');
230        assert_eq!(divider_junction(Junction::Cross, Weight::Single, &g), '┼');
231        assert_eq!(
232            divider_junction(Junction::TeeRight, Weight::Double, &g),
233            '╠'
234        );
235        assert_eq!(divider_junction(Junction::TeeLeft, Weight::Double, &g), '╣');
236        assert_eq!(divider_junction(Junction::TeeUp, Weight::Double, &g), '╩');
237        assert_eq!(divider_junction(Junction::TeeDown, Weight::Double, &g), '╦');
238        assert_eq!(divider_junction(Junction::Cross, Weight::Double, &g), '╬');
239    }
240}