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
165/// Total number of border style variants (7 named presets + 1 [`Custom`](BorderType::Custom)).
166/// Cited by the README and claims ledger.
167pub const BORDER_STYLE_COUNT: usize = 8;
168
169impl BorderType {
170    /// The number of built-in named border styles (every variant except the
171    /// open-ended [`Custom`](BorderType::Custom)). Cited by the README and the
172    /// `border_type_variant_count_matches_readme` test.
173    pub const NAMED_STYLE_COUNT: usize = 7;
174
175    /// The total number of border style variants including [`Custom`](BorderType::Custom).
176    pub const BORDER_STYLE_COUNT: usize = 8;
177
178    /// Convert this border type to its corresponding border character set.
179    pub fn to_border_set(&self) -> BorderSet {
180        match self {
181            BorderType::Square => BorderSet::SQUARE,
182            BorderType::Ascii => BorderSet::ASCII,
183            BorderType::Rounded => BorderSet::ROUNDED,
184            BorderType::Double => BorderSet::DOUBLE,
185            BorderType::Heavy => BorderSet::HEAVY,
186            BorderType::Dashed => BorderSet::DASHED,
187            BorderType::HeavyDashed => BorderSet::HEAVY_DASHED,
188            BorderType::Custom(set) => *set,
189        }
190    }
191}
192
193#[cfg(test)]
194mod tests {
195    use super::*;
196    use proptest::prelude::*;
197
198    #[test]
199    fn ascii_is_ascii_only() {
200        let set = BorderSet::ASCII;
201        let chars = [
202            set.vertical,
203            set.horizontal,
204            set.top_left,
205            set.top_right,
206            set.bottom_left,
207            set.bottom_right,
208            set.tee_up,
209            set.tee_down,
210            set.tee_left,
211            set.tee_right,
212            set.cross,
213        ];
214        assert!(chars.iter().all(|c| c.is_ascii()));
215    }
216
217    #[test]
218    fn square_has_box_drawing() {
219        let set = BorderSet::SQUARE;
220        assert_eq!(set.horizontal, '─');
221        assert_eq!(set.vertical, '│');
222        assert_eq!(set.cross, '┼');
223    }
224
225    #[test]
226    fn rounded_has_round_corners() {
227        let set = BorderSet::ROUNDED;
228        assert_eq!(set.top_left, '╭');
229        assert_eq!(set.top_right, '╮');
230        assert_eq!(set.bottom_left, '╰');
231        assert_eq!(set.bottom_right, '╯');
232        assert_eq!(set.horizontal, '─');
233        assert_eq!(set.vertical, '│');
234    }
235
236    #[test]
237    fn double_has_double_lines() {
238        let set = BorderSet::DOUBLE;
239        assert_eq!(set.horizontal, '═');
240        assert_eq!(set.vertical, '║');
241        assert_eq!(set.top_left, '╔');
242        assert_eq!(set.top_right, '╗');
243        assert_eq!(set.bottom_left, '╚');
244        assert_eq!(set.bottom_right, '╝');
245        assert_eq!(set.cross, '╬');
246    }
247
248    #[test]
249    fn heavy_has_heavy_lines() {
250        let set = BorderSet::HEAVY;
251        assert_eq!(set.horizontal, '━');
252        assert_eq!(set.vertical, '┃');
253        assert_eq!(set.top_left, '┏');
254        assert_eq!(set.top_right, '┓');
255        assert_eq!(set.bottom_left, '┗');
256        assert_eq!(set.bottom_right, '┛');
257        assert_eq!(set.cross, '╋');
258    }
259
260    #[test]
261    fn all_border_sets_have_11_fields() {
262        for set in [
263            BorderSet::ASCII,
264            BorderSet::ROUNDED,
265            BorderSet::SQUARE,
266            BorderSet::DOUBLE,
267            BorderSet::HEAVY,
268        ] {
269            let chars = [
270                set.vertical,
271                set.horizontal,
272                set.top_left,
273                set.top_right,
274                set.bottom_left,
275                set.bottom_right,
276                set.tee_up,
277                set.tee_down,
278                set.tee_left,
279                set.tee_right,
280                set.cross,
281            ];
282            assert_eq!(chars.len(), 11);
283            // horizontal and vertical are distinct in all sets
284            assert_ne!(set.horizontal, set.vertical);
285        }
286    }
287
288    #[test]
289    fn box_drawing_sets_have_distinct_corners() {
290        // Non-ASCII sets use unique box drawing chars for each corner
291        for set in [
292            BorderSet::ROUNDED,
293            BorderSet::SQUARE,
294            BorderSet::DOUBLE,
295            BorderSet::HEAVY,
296        ] {
297            let corners = [
298                set.top_left,
299                set.top_right,
300                set.bottom_left,
301                set.bottom_right,
302            ];
303            for (i, a) in corners.iter().enumerate() {
304                for (j, b) in corners.iter().enumerate() {
305                    if i != j {
306                        assert_ne!(a, b, "corners {i} and {j} should differ");
307                    }
308                }
309            }
310        }
311    }
312
313    #[test]
314    fn ascii_set_reuses_plus_for_junctions() {
315        let set = BorderSet::ASCII;
316        // ASCII uses '+' for all corners, tees, and cross
317        assert_eq!(set.top_left, '+');
318        assert_eq!(set.top_right, '+');
319        assert_eq!(set.bottom_left, '+');
320        assert_eq!(set.bottom_right, '+');
321        assert_eq!(set.tee_up, '+');
322        assert_eq!(set.tee_down, '+');
323        assert_eq!(set.tee_left, '+');
324        assert_eq!(set.tee_right, '+');
325        assert_eq!(set.cross, '+');
326    }
327
328    #[test]
329    fn border_type_to_border_set_roundtrip() {
330        assert_eq!(BorderType::Square.to_border_set(), BorderSet::SQUARE);
331        assert_eq!(BorderType::Ascii.to_border_set(), BorderSet::ASCII);
332        assert_eq!(BorderType::Rounded.to_border_set(), BorderSet::ROUNDED);
333        assert_eq!(BorderType::Double.to_border_set(), BorderSet::DOUBLE);
334        assert_eq!(BorderType::Heavy.to_border_set(), BorderSet::HEAVY);
335        assert_eq!(BorderType::Dashed.to_border_set(), BorderSet::DASHED);
336        assert_eq!(
337            BorderType::HeavyDashed.to_border_set(),
338            BorderSet::HEAVY_DASHED
339        );
340    }
341
342    #[test]
343    fn dashed_to_border_set_matches_const() {
344        let set = BorderType::Dashed.to_border_set();
345        assert_eq!(set, BorderSet::DASHED);
346        // Dashed edges with plain square corners and junctions.
347        assert_eq!(BorderSet::DASHED.horizontal, '┄');
348        assert_eq!(BorderSet::DASHED.vertical, '┆');
349        assert_eq!(set.horizontal, '┄');
350        assert_eq!(set.vertical, '┆');
351        assert_eq!(set.top_left, BorderSet::SQUARE.top_left);
352        assert_eq!(set.top_right, BorderSet::SQUARE.top_right);
353        assert_eq!(set.bottom_left, BorderSet::SQUARE.bottom_left);
354        assert_eq!(set.bottom_right, BorderSet::SQUARE.bottom_right);
355        assert_eq!(set.cross, BorderSet::SQUARE.cross);
356    }
357
358    #[test]
359    fn heavy_dashed_matches_const() {
360        let set = BorderType::HeavyDashed.to_border_set();
361        assert_eq!(set, BorderSet::HEAVY_DASHED);
362        assert_eq!(set.horizontal, '┅');
363        assert_eq!(set.vertical, '┇');
364        assert_eq!(set.top_left, '┏');
365        assert_eq!(set.cross, '╋');
366    }
367
368    #[test]
369    fn border_type_variant_count_matches_readme() {
370        // Seven named styles plus the open-ended `Custom`.
371        const ALL: &[BorderType] = &[
372            BorderType::Square,
373            BorderType::Ascii,
374            BorderType::Rounded,
375            BorderType::Double,
376            BorderType::Heavy,
377            BorderType::Dashed,
378            BorderType::HeavyDashed,
379            BorderType::Custom(BorderSet::SQUARE),
380        ];
381        assert_eq!(ALL.len(), BORDER_STYLE_COUNT);
382        assert_eq!(ALL.len(), BorderType::BORDER_STYLE_COUNT);
383
384        // Exhaustive match over ALL to guarantee every variant is represented:
385        for b in ALL {
386            match b {
387                BorderType::Square
388                | BorderType::Ascii
389                | BorderType::Rounded
390                | BorderType::Double
391                | BorderType::Heavy
392                | BorderType::Dashed
393                | BorderType::HeavyDashed
394                | BorderType::Custom(_) => {}
395            }
396        }
397
398        let named = [
399            BorderType::Square,
400            BorderType::Ascii,
401            BorderType::Rounded,
402            BorderType::Double,
403            BorderType::Heavy,
404            BorderType::Dashed,
405            BorderType::HeavyDashed,
406        ];
407        assert_eq!(named.len(), BorderType::NAMED_STYLE_COUNT);
408        assert_eq!(BorderType::NAMED_STYLE_COUNT, 7);
409        // Every named style resolves to a border set, and they are all distinct.
410        let sets: Vec<BorderSet> = named.iter().map(BorderType::to_border_set).collect();
411        for (i, a) in sets.iter().enumerate() {
412            for b in &sets[i + 1..] {
413                assert_ne!(a, b, "named border sets must be distinct");
414            }
415        }
416    }
417
418    #[test]
419    fn border_type_default_is_square() {
420        assert_eq!(BorderType::default(), BorderType::Square);
421    }
422
423    #[test]
424    fn custom_border_set_round_trips() {
425        let set = BorderSet {
426            top_left: '#',
427            horizontal: '+',
428            top_right: '-',
429            vertical: '|',
430            bottom_left: '=',
431            bottom_right: 'T',
432            tee_up: '^',
433            tee_down: '<',
434            tee_left: '>',
435            tee_right: '*',
436            cross: '~',
437        };
438        assert_eq!(BorderType::Custom(set).to_border_set(), set);
439    }
440
441    #[test]
442    fn border_type_custom_uses_provided_set() {
443        let custom = BorderSet {
444            vertical: '!',
445            horizontal: '-',
446            top_left: '/',
447            top_right: '\\',
448            bottom_left: '\\',
449            bottom_right: '/',
450            tee_up: '+',
451            tee_down: '+',
452            tee_left: '+',
453            tee_right: '+',
454            cross: '*',
455        };
456
457        assert_eq!(BorderType::Custom(custom).to_border_set(), custom);
458    }
459
460    #[test]
461    fn borders_none_is_zero() {
462        assert!(Borders::NONE.is_empty());
463        assert_eq!(Borders::NONE.bits(), 0);
464    }
465
466    #[test]
467    fn borders_all_contains_all_sides() {
468        assert!(Borders::ALL.contains(Borders::TOP));
469        assert!(Borders::ALL.contains(Borders::RIGHT));
470        assert!(Borders::ALL.contains(Borders::BOTTOM));
471        assert!(Borders::ALL.contains(Borders::LEFT));
472    }
473
474    #[test]
475    fn borders_individual_bits_are_distinct() {
476        let sides = [Borders::TOP, Borders::RIGHT, Borders::BOTTOM, Borders::LEFT];
477        for (i, a) in sides.iter().enumerate() {
478            for (j, b) in sides.iter().enumerate() {
479                if i != j {
480                    assert!(!a.contains(*b), "side {i} should not contain side {j}");
481                }
482            }
483        }
484    }
485
486    #[test]
487    fn borders_union_and_intersection() {
488        let top_left = Borders::TOP | Borders::LEFT;
489        assert!(top_left.contains(Borders::TOP));
490        assert!(top_left.contains(Borders::LEFT));
491        assert!(!top_left.contains(Borders::RIGHT));
492
493        let top_right = Borders::TOP | Borders::RIGHT;
494        let intersection = top_left & top_right;
495        assert!(intersection.contains(Borders::TOP));
496        assert!(!intersection.contains(Borders::LEFT));
497        assert!(!intersection.contains(Borders::RIGHT));
498    }
499
500    #[test]
501    fn borders_default_is_none() {
502        assert_eq!(Borders::default(), Borders::NONE);
503    }
504
505    #[test]
506    fn non_ascii_sets_have_no_ascii_chars() {
507        for set in [
508            BorderSet::ROUNDED,
509            BorderSet::SQUARE,
510            BorderSet::DOUBLE,
511            BorderSet::HEAVY,
512        ] {
513            let chars = [
514                set.vertical,
515                set.horizontal,
516                set.top_left,
517                set.top_right,
518                set.bottom_left,
519                set.bottom_right,
520                set.tee_up,
521                set.tee_down,
522                set.tee_left,
523                set.tee_right,
524                set.cross,
525            ];
526            assert!(
527                chars.iter().all(|c| !c.is_ascii()),
528                "non-ASCII border set should have no ASCII chars"
529            );
530        }
531    }
532
533    #[test]
534    fn border_set_tees_are_consistent() {
535        for set in [
536            BorderSet::ASCII,
537            BorderSet::SQUARE,
538            BorderSet::ROUNDED,
539            BorderSet::DOUBLE,
540            BorderSet::HEAVY,
541            BorderSet::DASHED,
542            BorderSet::HEAVY_DASHED,
543        ] {
544            let tees = [set.tee_up, set.tee_down, set.tee_left, set.tee_right];
545            for tee in tees {
546                assert_eq!(
547                    ftui_core::text_width::grapheme_width(&tee.to_string()),
548                    1,
549                    "tee glyph {tee} must have display width 1"
550                );
551            }
552            if set != BorderSet::ASCII {
553                for (i, a) in tees.iter().enumerate() {
554                    for (j, b) in tees.iter().enumerate() {
555                        if i != j {
556                            assert_ne!(a, b, "tees {i} and {j} should differ");
557                        }
558                    }
559                }
560            }
561            let copied = set;
562            assert_eq!(copied, set);
563        }
564    }
565
566    fn arb_border_type() -> impl Strategy<Value = BorderType> {
567        let ascii_char = (0x20u8..=0x7Eu8).prop_map(|b| b as char);
568        let arb_custom = (
569            ascii_char.clone(),
570            ascii_char.clone(),
571            ascii_char.clone(),
572            ascii_char.clone(),
573            ascii_char.clone(),
574            ascii_char.clone(),
575            ascii_char.clone(),
576            ascii_char.clone(),
577            ascii_char.clone(),
578            ascii_char.clone(),
579            ascii_char,
580        )
581            .prop_map(|(v, h, tl, tr, bl, br, tu, td, tlft, trgt, cr)| {
582                BorderType::Custom(BorderSet {
583                    vertical: v,
584                    horizontal: h,
585                    top_left: tl,
586                    top_right: tr,
587                    bottom_left: bl,
588                    bottom_right: br,
589                    tee_up: tu,
590                    tee_down: td,
591                    tee_left: tlft,
592                    tee_right: trgt,
593                    cross: cr,
594                })
595            });
596
597        prop_oneof![
598            Just(BorderType::Square),
599            Just(BorderType::Ascii),
600            Just(BorderType::Rounded),
601            Just(BorderType::Double),
602            Just(BorderType::Heavy),
603            Just(BorderType::Dashed),
604            Just(BorderType::HeavyDashed),
605            arb_custom,
606        ]
607    }
608
609    proptest! {
610        #![proptest_config(ProptestConfig::with_cases(256))]
611
612        #[test]
613        fn prop_any_border_type_has_width_one_glyphs(bt in arb_border_type()) {
614            let set = bt.to_border_set();
615            let glyphs = [
616                set.vertical,
617                set.horizontal,
618                set.top_left,
619                set.top_right,
620                set.bottom_left,
621                set.bottom_right,
622                set.tee_up,
623                set.tee_down,
624                set.tee_left,
625                set.tee_right,
626                set.cross,
627            ];
628            for g in glyphs {
629                prop_assert_eq!(
630                    ftui_core::text_width::grapheme_width(&g.to_string()),
631                    1,
632                    "glyph {} has display width != 1", g
633                );
634            }
635        }
636    }
637}
638
639bitflags::bitflags! {
640    /// Bitflags for which borders to render.
641    #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
642    pub struct Borders: u8 {
643        /// No borders.
644        const NONE   = 0b0000;
645        /// Top border.
646        const TOP    = 0b0001;
647        /// Right border.
648        const RIGHT  = 0b0010;
649        /// Bottom border.
650        const BOTTOM = 0b0100;
651        /// Left border.
652        const LEFT   = 0b1000;
653        /// All four borders.
654        const ALL    = Self::TOP.bits() | Self::RIGHT.bits() | Self::BOTTOM.bits() | Self::LEFT.bits();
655    }
656}