Skip to main content

ftui_widgets/
borders.rs

1//! Border styling primitives.
2
3/// Border characters for drawing.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub struct BorderSet {
6    /// Vertical border character.
7    pub vertical: char,
8    /// Horizontal border character.
9    pub horizontal: char,
10    /// Top-left corner character.
11    pub top_left: char,
12    /// Top-right corner character.
13    pub top_right: char,
14    /// Bottom-left corner character.
15    pub bottom_left: char,
16    /// Bottom-right corner character.
17    pub bottom_right: char,
18    /// Upward tee junction character.
19    pub tee_up: char,
20    /// Downward tee junction character.
21    pub tee_down: char,
22    /// Leftward tee junction character.
23    pub tee_left: char,
24    /// Rightward tee junction character.
25    pub tee_right: char,
26    /// Cross junction character.
27    pub cross: char,
28}
29
30impl BorderSet {
31    /// ASCII fallback border (+, -, |).
32    pub const ASCII: Self = Self {
33        vertical: '|',
34        horizontal: '-',
35        top_left: '+',
36        top_right: '+',
37        bottom_left: '+',
38        bottom_right: '+',
39        tee_up: '+',
40        tee_down: '+',
41        tee_left: '+',
42        tee_right: '+',
43        cross: '+',
44    };
45
46    /// Rounded corners (╭, ╮, ╯, ╰).
47    pub const ROUNDED: Self = Self {
48        vertical: '│',
49        horizontal: '─',
50        top_left: '╭',
51        top_right: '╮',
52        bottom_left: '╰',
53        bottom_right: '╯',
54        tee_up: '┴',
55        tee_down: '┬',
56        tee_left: '┤',
57        tee_right: '├',
58        cross: '┼',
59    };
60
61    /// Square single-line border.
62    pub const SQUARE: Self = Self {
63        vertical: '│',
64        horizontal: '─',
65        top_left: '┌',
66        top_right: '┐',
67        bottom_left: '└',
68        bottom_right: '┘',
69        tee_up: '┴',
70        tee_down: '┬',
71        tee_left: '┤',
72        tee_right: '├',
73        cross: '┼',
74    };
75
76    /// Double lines (║, ═).
77    pub const DOUBLE: Self = Self {
78        vertical: '║',
79        horizontal: '═',
80        top_left: '╔',
81        top_right: '╗',
82        bottom_left: '╚',
83        bottom_right: '╝',
84        tee_up: '╩',
85        tee_down: '╦',
86        tee_left: '╣',
87        tee_right: '╠',
88        cross: '╬',
89    };
90
91    /// Heavy lines (┃, ━).
92    pub const HEAVY: Self = Self {
93        vertical: '┃',
94        horizontal: '━',
95        top_left: '┏',
96        top_right: '┓',
97        bottom_left: '┗',
98        bottom_right: '┛',
99        tee_up: '┻',
100        tee_down: '┳',
101        tee_left: '┫',
102        tee_right: '┣',
103        cross: '╋',
104    };
105
106    /// Single line with dashed edges (┄, ┆); square corners and junctions.
107    pub const DASHED: Self = Self {
108        vertical: '┆',
109        horizontal: '┄',
110        top_left: '┌',
111        top_right: '┐',
112        bottom_left: '└',
113        bottom_right: '┘',
114        tee_up: '┴',
115        tee_down: '┬',
116        tee_left: '┤',
117        tee_right: '├',
118        cross: '┼',
119    };
120
121    /// Heavy line with dashed edges (┅, ┇); heavy corners and junctions.
122    pub const HEAVY_DASHED: Self = Self {
123        vertical: '┇',
124        horizontal: '┅',
125        top_left: '┏',
126        top_right: '┓',
127        bottom_left: '┗',
128        bottom_right: '┛',
129        tee_up: '┻',
130        tee_down: '┳',
131        tee_left: '┫',
132        tee_right: '┣',
133        cross: '╋',
134    };
135}
136
137/// Border style presets.
138///
139/// Eight variants: seven named glyph sets — `Square` (default), `Ascii`,
140/// `Rounded`, `Double`, `Heavy`, `Dashed`, `HeavyDashed` — plus `Custom`, which
141/// accepts any [`BorderSet`], so arbitrary corner/edge/junction glyphs are
142/// supported without a new variant. This doc comment is the source of truth for
143/// the "border styles" count cited in the README.
144#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
145pub enum BorderType {
146    /// No border (but space reserved if Borders::ALL is set).
147    #[default]
148    Square,
149    /// ASCII fallback border.
150    Ascii,
151    /// Single line border with rounded corners.
152    Rounded,
153    /// Double line border.
154    Double,
155    /// Heavy line border.
156    Heavy,
157    /// Single line border with dashed edges (┄, ┆).
158    Dashed,
159    /// Heavy line border with dashed edges (┅, ┇).
160    HeavyDashed,
161    /// Custom border character set.
162    Custom(BorderSet),
163}
164
165impl BorderType {
166    /// The number of built-in named border styles (every variant except the
167    /// open-ended [`Custom`](BorderType::Custom)). Cited by the README and the
168    /// `border_type_variant_count_matches_readme` test.
169    pub const NAMED_STYLE_COUNT: usize = 7;
170
171    /// Convert this border type to its corresponding border character set.
172    pub fn to_border_set(&self) -> BorderSet {
173        match self {
174            BorderType::Square => BorderSet::SQUARE,
175            BorderType::Ascii => BorderSet::ASCII,
176            BorderType::Rounded => BorderSet::ROUNDED,
177            BorderType::Double => BorderSet::DOUBLE,
178            BorderType::Heavy => BorderSet::HEAVY,
179            BorderType::Dashed => BorderSet::DASHED,
180            BorderType::HeavyDashed => BorderSet::HEAVY_DASHED,
181            BorderType::Custom(set) => *set,
182        }
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    #[test]
191    fn ascii_is_ascii_only() {
192        let set = BorderSet::ASCII;
193        let chars = [
194            set.vertical,
195            set.horizontal,
196            set.top_left,
197            set.top_right,
198            set.bottom_left,
199            set.bottom_right,
200            set.tee_up,
201            set.tee_down,
202            set.tee_left,
203            set.tee_right,
204            set.cross,
205        ];
206        assert!(chars.iter().all(|c| c.is_ascii()));
207    }
208
209    #[test]
210    fn square_has_box_drawing() {
211        let set = BorderSet::SQUARE;
212        assert_eq!(set.horizontal, '─');
213        assert_eq!(set.vertical, '│');
214        assert_eq!(set.cross, '┼');
215    }
216
217    #[test]
218    fn rounded_has_round_corners() {
219        let set = BorderSet::ROUNDED;
220        assert_eq!(set.top_left, '╭');
221        assert_eq!(set.top_right, '╮');
222        assert_eq!(set.bottom_left, '╰');
223        assert_eq!(set.bottom_right, '╯');
224        assert_eq!(set.horizontal, '─');
225        assert_eq!(set.vertical, '│');
226    }
227
228    #[test]
229    fn double_has_double_lines() {
230        let set = BorderSet::DOUBLE;
231        assert_eq!(set.horizontal, '═');
232        assert_eq!(set.vertical, '║');
233        assert_eq!(set.top_left, '╔');
234        assert_eq!(set.top_right, '╗');
235        assert_eq!(set.bottom_left, '╚');
236        assert_eq!(set.bottom_right, '╝');
237        assert_eq!(set.cross, '╬');
238    }
239
240    #[test]
241    fn heavy_has_heavy_lines() {
242        let set = BorderSet::HEAVY;
243        assert_eq!(set.horizontal, '━');
244        assert_eq!(set.vertical, '┃');
245        assert_eq!(set.top_left, '┏');
246        assert_eq!(set.top_right, '┓');
247        assert_eq!(set.bottom_left, '┗');
248        assert_eq!(set.bottom_right, '┛');
249        assert_eq!(set.cross, '╋');
250    }
251
252    #[test]
253    fn all_border_sets_have_11_fields() {
254        for set in [
255            BorderSet::ASCII,
256            BorderSet::ROUNDED,
257            BorderSet::SQUARE,
258            BorderSet::DOUBLE,
259            BorderSet::HEAVY,
260        ] {
261            let chars = [
262                set.vertical,
263                set.horizontal,
264                set.top_left,
265                set.top_right,
266                set.bottom_left,
267                set.bottom_right,
268                set.tee_up,
269                set.tee_down,
270                set.tee_left,
271                set.tee_right,
272                set.cross,
273            ];
274            assert_eq!(chars.len(), 11);
275            // horizontal and vertical are distinct in all sets
276            assert_ne!(set.horizontal, set.vertical);
277        }
278    }
279
280    #[test]
281    fn box_drawing_sets_have_distinct_corners() {
282        // Non-ASCII sets use unique box drawing chars for each corner
283        for set in [
284            BorderSet::ROUNDED,
285            BorderSet::SQUARE,
286            BorderSet::DOUBLE,
287            BorderSet::HEAVY,
288        ] {
289            let corners = [
290                set.top_left,
291                set.top_right,
292                set.bottom_left,
293                set.bottom_right,
294            ];
295            for (i, a) in corners.iter().enumerate() {
296                for (j, b) in corners.iter().enumerate() {
297                    if i != j {
298                        assert_ne!(a, b, "corners {i} and {j} should differ");
299                    }
300                }
301            }
302        }
303    }
304
305    #[test]
306    fn ascii_set_reuses_plus_for_junctions() {
307        let set = BorderSet::ASCII;
308        // ASCII uses '+' for all corners, tees, and cross
309        assert_eq!(set.top_left, '+');
310        assert_eq!(set.top_right, '+');
311        assert_eq!(set.bottom_left, '+');
312        assert_eq!(set.bottom_right, '+');
313        assert_eq!(set.tee_up, '+');
314        assert_eq!(set.tee_down, '+');
315        assert_eq!(set.tee_left, '+');
316        assert_eq!(set.tee_right, '+');
317        assert_eq!(set.cross, '+');
318    }
319
320    #[test]
321    fn border_type_to_border_set_roundtrip() {
322        assert_eq!(BorderType::Square.to_border_set(), BorderSet::SQUARE);
323        assert_eq!(BorderType::Ascii.to_border_set(), BorderSet::ASCII);
324        assert_eq!(BorderType::Rounded.to_border_set(), BorderSet::ROUNDED);
325        assert_eq!(BorderType::Double.to_border_set(), BorderSet::DOUBLE);
326        assert_eq!(BorderType::Heavy.to_border_set(), BorderSet::HEAVY);
327        assert_eq!(BorderType::Dashed.to_border_set(), BorderSet::DASHED);
328        assert_eq!(
329            BorderType::HeavyDashed.to_border_set(),
330            BorderSet::HEAVY_DASHED
331        );
332    }
333
334    #[test]
335    fn dashed_to_border_set_matches_const() {
336        let set = BorderType::Dashed.to_border_set();
337        assert_eq!(set, BorderSet::DASHED);
338        // Dashed edges with plain square corners and junctions.
339        assert_eq!(set.horizontal, '┄');
340        assert_eq!(set.vertical, '┆');
341        assert_eq!(set.top_left, '┌');
342        assert_eq!(set.top_right, '┐');
343        assert_eq!(set.cross, '┼');
344    }
345
346    #[test]
347    fn heavy_dashed_matches_const() {
348        let set = BorderType::HeavyDashed.to_border_set();
349        assert_eq!(set, BorderSet::HEAVY_DASHED);
350        assert_eq!(set.horizontal, '┅');
351        assert_eq!(set.vertical, '┇');
352        assert_eq!(set.top_left, '┏');
353        assert_eq!(set.cross, '╋');
354    }
355
356    #[test]
357    fn border_type_variant_count_matches_readme() {
358        // Seven named styles plus the open-ended `Custom`. If a variant is
359        // added or removed, update this count and the README together.
360        let named = [
361            BorderType::Square,
362            BorderType::Ascii,
363            BorderType::Rounded,
364            BorderType::Double,
365            BorderType::Heavy,
366            BorderType::Dashed,
367            BorderType::HeavyDashed,
368        ];
369        assert_eq!(named.len(), BorderType::NAMED_STYLE_COUNT);
370        assert_eq!(BorderType::NAMED_STYLE_COUNT, 7);
371        // Every named style resolves to a border set, and they are all distinct.
372        let sets: Vec<BorderSet> = named.iter().map(BorderType::to_border_set).collect();
373        for (i, a) in sets.iter().enumerate() {
374            for b in &sets[i + 1..] {
375                assert_ne!(a, b, "named border sets must be distinct");
376            }
377        }
378    }
379
380    #[test]
381    fn border_type_default_is_square() {
382        assert_eq!(BorderType::default(), BorderType::Square);
383    }
384
385    #[test]
386    fn border_type_custom_uses_provided_set() {
387        let custom = BorderSet {
388            vertical: '!',
389            horizontal: '-',
390            top_left: '/',
391            top_right: '\\',
392            bottom_left: '\\',
393            bottom_right: '/',
394            tee_up: '+',
395            tee_down: '+',
396            tee_left: '+',
397            tee_right: '+',
398            cross: '*',
399        };
400
401        assert_eq!(BorderType::Custom(custom).to_border_set(), custom);
402    }
403
404    #[test]
405    fn borders_none_is_zero() {
406        assert!(Borders::NONE.is_empty());
407        assert_eq!(Borders::NONE.bits(), 0);
408    }
409
410    #[test]
411    fn borders_all_contains_all_sides() {
412        assert!(Borders::ALL.contains(Borders::TOP));
413        assert!(Borders::ALL.contains(Borders::RIGHT));
414        assert!(Borders::ALL.contains(Borders::BOTTOM));
415        assert!(Borders::ALL.contains(Borders::LEFT));
416    }
417
418    #[test]
419    fn borders_individual_bits_are_distinct() {
420        let sides = [Borders::TOP, Borders::RIGHT, Borders::BOTTOM, Borders::LEFT];
421        for (i, a) in sides.iter().enumerate() {
422            for (j, b) in sides.iter().enumerate() {
423                if i != j {
424                    assert!(!a.contains(*b), "side {i} should not contain side {j}");
425                }
426            }
427        }
428    }
429
430    #[test]
431    fn borders_union_and_intersection() {
432        let top_left = Borders::TOP | Borders::LEFT;
433        assert!(top_left.contains(Borders::TOP));
434        assert!(top_left.contains(Borders::LEFT));
435        assert!(!top_left.contains(Borders::RIGHT));
436
437        let top_right = Borders::TOP | Borders::RIGHT;
438        let intersection = top_left & top_right;
439        assert!(intersection.contains(Borders::TOP));
440        assert!(!intersection.contains(Borders::LEFT));
441        assert!(!intersection.contains(Borders::RIGHT));
442    }
443
444    #[test]
445    fn borders_default_is_none() {
446        assert_eq!(Borders::default(), Borders::NONE);
447    }
448
449    #[test]
450    fn non_ascii_sets_have_no_ascii_chars() {
451        for set in [
452            BorderSet::ROUNDED,
453            BorderSet::SQUARE,
454            BorderSet::DOUBLE,
455            BorderSet::HEAVY,
456        ] {
457            let chars = [
458                set.vertical,
459                set.horizontal,
460                set.top_left,
461                set.top_right,
462                set.bottom_left,
463                set.bottom_right,
464                set.tee_up,
465                set.tee_down,
466                set.tee_left,
467                set.tee_right,
468                set.cross,
469            ];
470            assert!(
471                chars.iter().all(|c| !c.is_ascii()),
472                "non-ASCII border set should have no ASCII chars"
473            );
474        }
475    }
476
477    #[test]
478    fn border_set_tees_are_consistent() {
479        // For SQUARE: tees should share chars with edges
480        let set = BorderSet::SQUARE;
481        // tee_up (┴) connects vertical and horizontal lines going up
482        // tee_down (┬) connects going down
483        // They should all be distinct from each other and from corners
484        let tees = [set.tee_up, set.tee_down, set.tee_left, set.tee_right];
485        for (i, a) in tees.iter().enumerate() {
486            for (j, b) in tees.iter().enumerate() {
487                if i != j {
488                    assert_ne!(a, b, "tees {i} and {j} should differ");
489                }
490            }
491        }
492    }
493}
494
495bitflags::bitflags! {
496    /// Bitflags for which borders to render.
497    #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
498    pub struct Borders: u8 {
499        /// No borders.
500        const NONE   = 0b0000;
501        /// Top border.
502        const TOP    = 0b0001;
503        /// Right border.
504        const RIGHT  = 0b0010;
505        /// Bottom border.
506        const BOTTOM = 0b0100;
507        /// Left border.
508        const LEFT   = 0b1000;
509        /// All four borders.
510        const ALL    = Self::TOP.bits() | Self::RIGHT.bits() | Self::BOTTOM.bits() | Self::LEFT.bits();
511    }
512}