Skip to main content

ftui_style/
stylesheet.rs

1#![forbid(unsafe_code)]
2
3//! StyleSheet registry for named styles.
4//!
5//! StyleSheet provides named style registration similar to CSS classes.
6//! This enables themeable applications and consistent style reuse without
7//! hardcoding colors.
8//!
9//! # Example
10//! ```
11//! use ftui_style::{Style, StyleSheet, StyleId};
12//! use ftui_render::cell::PackedRgba;
13//!
14//! let mut sheet = StyleSheet::new();
15//!
16//! // Define named styles
17//! sheet.define("error", Style::new().fg(PackedRgba::rgb(255, 0, 0)).bold());
18//! sheet.define("warning", Style::new().fg(PackedRgba::rgb(255, 165, 0)));
19//!
20//! // Look up by name
21//! let error_style = sheet.get("error").unwrap();
22//!
23//! // Compose multiple styles (later ones take precedence)
24//! let composed = sheet.compose(&["base", "error"]);
25//! ```
26
27use crate::style::Style;
28use ahash::AHashMap;
29use ftui_render::cell::PackedRgba;
30use std::sync::RwLock;
31
32/// Identifier for a named style in a StyleSheet.
33///
34/// StyleId is a simple string-based identifier for named styles.
35/// We use `&str` for lookups and `String` for storage to balance
36/// ergonomics and performance.
37#[derive(Debug, Clone, PartialEq, Eq, Hash)]
38pub struct StyleId(pub String);
39
40impl StyleId {
41    /// Create a new StyleId from a string.
42    #[inline]
43    pub fn new(name: impl Into<String>) -> Self {
44        Self(name.into())
45    }
46
47    /// Get the name as a string slice.
48    #[inline]
49    pub fn as_str(&self) -> &str {
50        &self.0
51    }
52}
53
54impl From<&str> for StyleId {
55    fn from(s: &str) -> Self {
56        Self(s.to_string())
57    }
58}
59
60impl From<String> for StyleId {
61    fn from(s: String) -> Self {
62        Self(s)
63    }
64}
65
66impl AsRef<str> for StyleId {
67    fn as_ref(&self) -> &str {
68        &self.0
69    }
70}
71
72/// A registry of named styles for consistent theming.
73///
74/// StyleSheet allows defining styles by name and looking them up later.
75/// This decouples visual appearance from widget logic, allowing themes
76/// to override the stylesheet without changing widget code.
77///
78/// # Thread Safety
79///
80/// StyleSheet uses an internal RwLock for thread-safe read access
81/// after initialization. Multiple readers can access styles concurrently.
82#[derive(Debug, Default)]
83pub struct StyleSheet {
84    styles: RwLock<AHashMap<String, Style>>,
85}
86
87impl StyleSheet {
88    /// Create a new empty StyleSheet.
89    #[inline]
90    pub fn new() -> Self {
91        Self {
92            styles: RwLock::new(AHashMap::new()),
93        }
94    }
95
96    /// Create a StyleSheet with default semantic styles.
97    ///
98    /// This provides a base set of commonly-used style names:
99    /// - `error`: Red, bold
100    /// - `warning`: Orange/yellow
101    /// - `info`: Blue
102    /// - `success`: Green
103    /// - `muted`: Gray/dim
104    /// - `highlight`: Yellow background
105    /// - `link`: Blue, underline
106    #[must_use]
107    pub fn with_defaults() -> Self {
108        let sheet = Self::new();
109
110        // Error: Red, bold
111        sheet.define(
112            "error",
113            Style::new().fg(PackedRgba::rgb(255, 85, 85)).bold(),
114        );
115
116        // Warning: Orange/yellow
117        sheet.define("warning", Style::new().fg(PackedRgba::rgb(255, 170, 0)));
118
119        // Info: Blue
120        sheet.define("info", Style::new().fg(PackedRgba::rgb(85, 170, 255)));
121
122        // Success: Green
123        sheet.define("success", Style::new().fg(PackedRgba::rgb(85, 255, 85)));
124
125        // Muted: Gray, dim
126        sheet.define(
127            "muted",
128            Style::new().fg(PackedRgba::rgb(128, 128, 128)).dim(),
129        );
130
131        // Highlight: Yellow background
132        sheet.define(
133            "highlight",
134            Style::new()
135                .bg(PackedRgba::rgb(255, 255, 0))
136                .fg(PackedRgba::rgb(0, 0, 0)),
137        );
138
139        // Link: Blue, underline
140        sheet.define(
141            "link",
142            Style::new().fg(PackedRgba::rgb(85, 170, 255)).underline(),
143        );
144
145        sheet
146    }
147
148    /// Define a named style.
149    ///
150    /// If a style with this name already exists, it is replaced.
151    pub fn define(&self, name: impl Into<String>, style: Style) {
152        let name = name.into();
153        let mut styles = self.styles.write().expect("StyleSheet lock poisoned");
154        styles.insert(name, style);
155    }
156
157    /// Remove a named style.
158    ///
159    /// Returns the removed style if it existed.
160    pub fn remove(&self, name: &str) -> Option<Style> {
161        let mut styles = self.styles.write().expect("StyleSheet lock poisoned");
162        styles.remove(name)
163    }
164
165    /// Get a named style.
166    ///
167    /// Returns `None` if the style is not defined.
168    pub fn get(&self, name: &str) -> Option<Style> {
169        let styles = self.styles.read().expect("StyleSheet lock poisoned");
170        styles.get(name).copied()
171    }
172
173    /// Get a named style, returning a default if not found.
174    pub fn get_or_default(&self, name: &str) -> Style {
175        self.get(name).unwrap_or_default()
176    }
177
178    /// Check if a style with the given name exists.
179    pub fn contains(&self, name: &str) -> bool {
180        let styles = self.styles.read().expect("StyleSheet lock poisoned");
181        styles.contains_key(name)
182    }
183
184    /// Get the number of defined styles.
185    pub fn len(&self) -> usize {
186        let styles = self.styles.read().expect("StyleSheet lock poisoned");
187        styles.len()
188    }
189
190    /// Check if the stylesheet is empty.
191    pub fn is_empty(&self) -> bool {
192        self.len() == 0
193    }
194
195    /// Get all style names.
196    pub fn names(&self) -> Vec<String> {
197        let styles = self.styles.read().expect("StyleSheet lock poisoned");
198        styles.keys().cloned().collect()
199    }
200
201    /// Compose multiple styles by name, merging them in order.
202    ///
203    /// Styles are merged left-to-right, with later styles taking
204    /// precedence over earlier ones for conflicting properties.
205    ///
206    /// Missing style names are silently ignored.
207    ///
208    /// # Example
209    /// ```
210    /// use ftui_style::{Style, StyleSheet};
211    /// use ftui_render::cell::PackedRgba;
212    ///
213    /// let sheet = StyleSheet::new();
214    /// sheet.define("base", Style::new().fg(PackedRgba::WHITE));
215    /// sheet.define("bold", Style::new().bold());
216    ///
217    /// // Compose: base + bold = white text that's bold
218    /// let composed = sheet.compose(&["base", "bold"]);
219    /// ```
220    pub fn compose(&self, names: &[&str]) -> Style {
221        let styles = self.styles.read().expect("StyleSheet lock poisoned");
222        let mut result = Style::default();
223
224        for name in names {
225            if let Some(style) = styles.get(*name) {
226                result = style.merge(&result);
227            }
228        }
229
230        result
231    }
232
233    /// Compose styles with fallback for missing names.
234    ///
235    /// Like `compose`, but returns `None` if any named style is missing.
236    pub fn compose_strict(&self, names: &[&str]) -> Option<Style> {
237        let styles = self.styles.read().expect("StyleSheet lock poisoned");
238        let mut result = Style::default();
239
240        for name in names {
241            let style = styles.get(*name)?;
242            result = style.merge(&result);
243        }
244
245        Some(result)
246    }
247
248    /// Extend this stylesheet with styles from another.
249    ///
250    /// Styles from `other` override styles with the same name in `self`.
251    pub fn extend(&self, other: &StyleSheet) {
252        if std::ptr::eq(self, other) {
253            return;
254        }
255        let other_styles = {
256            let other_styles = other.styles.read().expect("StyleSheet lock poisoned");
257            other_styles.clone()
258        };
259        let mut self_styles = self.styles.write().expect("StyleSheet lock poisoned");
260        self_styles.extend(other_styles);
261    }
262
263    /// Clear all styles from the stylesheet.
264    pub fn clear(&self) {
265        let mut styles = self.styles.write().expect("StyleSheet lock poisoned");
266        styles.clear();
267    }
268}
269
270impl Clone for StyleSheet {
271    fn clone(&self) -> Self {
272        let styles = self.styles.read().expect("StyleSheet lock poisoned");
273        Self {
274            styles: RwLock::new(styles.clone()),
275        }
276    }
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282    use crate::style::StyleFlags;
283
284    #[test]
285    fn new_stylesheet_is_empty() {
286        let sheet = StyleSheet::new();
287        assert!(sheet.is_empty());
288        assert_eq!(sheet.len(), 0);
289    }
290
291    #[test]
292    fn define_and_get_style() {
293        let sheet = StyleSheet::new();
294        let style = Style::new().fg(PackedRgba::rgb(255, 0, 0)).bold();
295
296        sheet.define("error", style);
297
298        assert!(!sheet.is_empty());
299        assert_eq!(sheet.len(), 1);
300        assert!(sheet.contains("error"));
301
302        let retrieved = sheet.get("error").unwrap();
303        assert_eq!(retrieved, style);
304    }
305
306    #[test]
307    fn get_nonexistent_returns_none() {
308        let sheet = StyleSheet::new();
309        assert!(sheet.get("nonexistent").is_none());
310    }
311
312    #[test]
313    fn get_or_default_returns_default_for_missing() {
314        let sheet = StyleSheet::new();
315        let style = sheet.get_or_default("missing");
316        assert!(style.is_empty());
317    }
318
319    #[test]
320    fn define_replaces_existing() {
321        let sheet = StyleSheet::new();
322
323        sheet.define("test", Style::new().bold());
324        assert!(sheet.get("test").unwrap().has_attr(StyleFlags::BOLD));
325
326        sheet.define("test", Style::new().italic());
327        let style = sheet.get("test").unwrap();
328        assert!(!style.has_attr(StyleFlags::BOLD));
329        assert!(style.has_attr(StyleFlags::ITALIC));
330    }
331
332    #[test]
333    fn remove_style() {
334        let sheet = StyleSheet::new();
335        sheet.define("test", Style::new().bold());
336
337        let removed = sheet.remove("test");
338        assert!(removed.is_some());
339        assert!(!sheet.contains("test"));
340
341        let removed_again = sheet.remove("test");
342        assert!(removed_again.is_none());
343    }
344
345    #[test]
346    fn names_returns_all_style_names() {
347        let sheet = StyleSheet::new();
348        sheet.define("a", Style::new());
349        sheet.define("b", Style::new());
350        sheet.define("c", Style::new());
351
352        let names = sheet.names();
353        assert_eq!(names.len(), 3);
354        assert!(names.contains(&"a".to_string()));
355        assert!(names.contains(&"b".to_string()));
356        assert!(names.contains(&"c".to_string()));
357    }
358
359    #[test]
360    fn compose_merges_styles() {
361        let sheet = StyleSheet::new();
362        sheet.define("base", Style::new().fg(PackedRgba::WHITE));
363        sheet.define("bold", Style::new().bold());
364
365        let composed = sheet.compose(&["base", "bold"]);
366
367        assert_eq!(composed.fg, Some(PackedRgba::WHITE));
368        assert!(composed.has_attr(StyleFlags::BOLD));
369    }
370
371    #[test]
372    fn compose_later_wins_on_conflict() {
373        let sheet = StyleSheet::new();
374        let red = PackedRgba::rgb(255, 0, 0);
375        let blue = PackedRgba::rgb(0, 0, 255);
376
377        sheet.define("red", Style::new().fg(red));
378        sheet.define("blue", Style::new().fg(blue));
379
380        let composed = sheet.compose(&["red", "blue"]);
381        assert_eq!(composed.fg, Some(blue));
382    }
383
384    #[test]
385    fn compose_later_wins() {
386        compose_later_wins_on_conflict();
387    }
388
389    #[test]
390    fn compose_ignores_missing() {
391        let sheet = StyleSheet::new();
392        sheet.define("exists", Style::new().bold());
393
394        let composed = sheet.compose(&["missing", "exists"]);
395        assert!(composed.has_attr(StyleFlags::BOLD));
396    }
397
398    #[test]
399    fn compose_strict_fails_on_missing() {
400        let sheet = StyleSheet::new();
401        sheet.define("exists", Style::new().bold());
402
403        let result = sheet.compose_strict(&["exists", "missing"]);
404        assert!(result.is_none());
405    }
406
407    #[test]
408    fn compose_strict_succeeds_when_all_present() {
409        let sheet = StyleSheet::new();
410        sheet.define("a", Style::new().bold());
411        sheet.define("b", Style::new().italic());
412
413        let result = sheet.compose_strict(&["a", "b"]);
414        assert!(result.is_some());
415
416        let style = result.unwrap();
417        assert!(style.has_attr(StyleFlags::BOLD));
418        assert!(style.has_attr(StyleFlags::ITALIC));
419    }
420
421    #[test]
422    fn with_defaults_has_semantic_styles() {
423        let sheet = StyleSheet::with_defaults();
424
425        assert!(sheet.contains("error"));
426        assert!(sheet.contains("warning"));
427        assert!(sheet.contains("info"));
428        assert!(sheet.contains("success"));
429        assert!(sheet.contains("muted"));
430        assert!(sheet.contains("highlight"));
431        assert!(sheet.contains("link"));
432
433        // Check error is red and bold
434        let error = sheet.get("error").unwrap();
435        assert!(error.has_attr(StyleFlags::BOLD));
436        assert!(error.fg.is_some());
437    }
438
439    #[test]
440    fn extend_merges_stylesheets() {
441        let sheet1 = StyleSheet::new();
442        sheet1.define("a", Style::new().bold());
443
444        let sheet2 = StyleSheet::new();
445        sheet2.define("b", Style::new().italic());
446
447        sheet1.extend(&sheet2);
448
449        assert!(sheet1.contains("a"));
450        assert!(sheet1.contains("b"));
451    }
452
453    #[test]
454    fn extend_overrides_existing() {
455        let sheet1 = StyleSheet::new();
456        sheet1.define("test", Style::new().bold());
457
458        let sheet2 = StyleSheet::new();
459        sheet2.define("test", Style::new().italic());
460
461        sheet1.extend(&sheet2);
462
463        let style = sheet1.get("test").unwrap();
464        assert!(!style.has_attr(StyleFlags::BOLD));
465        assert!(style.has_attr(StyleFlags::ITALIC));
466    }
467
468    #[test]
469    fn concurrent_bidirectional_extend_completes() {
470        use std::sync::{Arc, Barrier, mpsc};
471        use std::time::Duration;
472
473        let sheet1 = Arc::new(StyleSheet::new());
474        sheet1.define("a", Style::new().bold());
475
476        let sheet2 = Arc::new(StyleSheet::new());
477        sheet2.define("b", Style::new().italic());
478
479        let barrier = Arc::new(Barrier::new(3));
480        let (done_tx, done_rx) = mpsc::channel();
481
482        let sheet1_to_sheet2 = {
483            let barrier = Arc::clone(&barrier);
484            let done_tx = done_tx.clone();
485            let sheet1 = Arc::clone(&sheet1);
486            let sheet2 = Arc::clone(&sheet2);
487            std::thread::spawn(move || {
488                barrier.wait();
489                sheet1.extend(&sheet2);
490                done_tx.send(()).expect("completion signal");
491            })
492        };
493
494        let sheet2_to_sheet1 = {
495            let barrier = Arc::clone(&barrier);
496            let done_tx = done_tx.clone();
497            let sheet1 = Arc::clone(&sheet1);
498            let sheet2 = Arc::clone(&sheet2);
499            std::thread::spawn(move || {
500                barrier.wait();
501                sheet2.extend(&sheet1);
502                done_tx.send(()).expect("completion signal");
503            })
504        };
505
506        barrier.wait();
507
508        for _ in 0..2 {
509            done_rx
510                .recv_timeout(Duration::from_secs(1))
511                .expect("cross-extend should complete without deadlocking");
512        }
513
514        sheet1_to_sheet2.join().expect("sheet1 extend thread");
515        sheet2_to_sheet1.join().expect("sheet2 extend thread");
516
517        assert!(sheet1.contains("b"));
518        assert!(sheet2.contains("a"));
519    }
520
521    #[test]
522    fn clear_removes_all_styles() {
523        let sheet = StyleSheet::with_defaults();
524        assert!(!sheet.is_empty());
525
526        sheet.clear();
527        assert!(sheet.is_empty());
528    }
529
530    #[test]
531    fn clone_creates_independent_copy() {
532        let sheet1 = StyleSheet::new();
533        sheet1.define("test", Style::new().bold());
534
535        let sheet2 = sheet1.clone();
536        sheet1.define("other", Style::new());
537
538        assert!(sheet1.contains("other"));
539        assert!(!sheet2.contains("other"));
540    }
541
542    #[test]
543    fn style_id_from_str() {
544        let id: StyleId = "error".into();
545        assert_eq!(id.as_str(), "error");
546    }
547
548    #[test]
549    fn style_id_from_string() {
550        let id: StyleId = String::from("error").into();
551        assert_eq!(id.as_str(), "error");
552    }
553
554    #[test]
555    fn style_id_equality() {
556        let id1 = StyleId::new("error");
557        let id2 = StyleId::new("error");
558        let id3 = StyleId::new("warning");
559
560        assert_eq!(id1, id2);
561        assert_ne!(id1, id3);
562    }
563
564    #[test]
565    fn stylesheet_thread_safe_reads() {
566        use std::sync::Arc;
567        use std::thread;
568
569        let sheet = Arc::new(StyleSheet::new());
570        sheet.define("test", Style::new().bold());
571
572        let handles: Vec<_> = (0..4)
573            .map(|_| {
574                let sheet = Arc::clone(&sheet);
575                thread::spawn(move || {
576                    for _ in 0..100 {
577                        let _ = sheet.get("test");
578                    }
579                })
580            })
581            .collect();
582
583        for handle in handles {
584            handle.join().unwrap();
585        }
586    }
587
588    #[test]
589    fn stylesheet_thread_safe_writes() {
590        use std::sync::Arc;
591        use std::thread;
592
593        let sheet = Arc::new(StyleSheet::new());
594
595        let handles: Vec<_> = (0..4)
596            .map(|i| {
597                let sheet = Arc::clone(&sheet);
598                thread::spawn(move || {
599                    for j in 0..25 {
600                        let name = format!("style_{}_{}", i, j);
601                        sheet.define(&name, Style::new().bold());
602                    }
603                })
604            })
605            .collect();
606
607        for handle in handles {
608            handle.join().unwrap();
609        }
610
611        // Should have 100 styles (4 threads * 25 each)
612        assert_eq!(sheet.len(), 100);
613    }
614
615    #[test]
616    fn compose_empty_list_returns_default() {
617        let sheet = StyleSheet::new();
618        sheet.define("test", Style::new().bold());
619
620        let composed = sheet.compose(&[]);
621        assert!(composed.is_empty());
622    }
623
624    #[test]
625    fn compose_strict_empty_list_returns_some_default() {
626        let sheet = StyleSheet::new();
627        sheet.define("test", Style::new().bold());
628
629        let result = sheet.compose_strict(&[]);
630        assert!(result.is_some());
631        assert!(result.unwrap().is_empty());
632    }
633
634    #[test]
635    fn extend_self_is_noop() {
636        let sheet = StyleSheet::new();
637        sheet.define("test", Style::new().bold());
638
639        // Extending self should not panic or change anything
640        sheet.extend(&sheet);
641
642        assert_eq!(sheet.len(), 1);
643        assert!(sheet.contains("test"));
644    }
645
646    #[test]
647    fn stylesheet_default_is_empty() {
648        let sheet = StyleSheet::default();
649        assert!(sheet.is_empty());
650    }
651
652    #[test]
653    fn define_with_empty_name() {
654        let sheet = StyleSheet::new();
655        sheet.define("", Style::new().bold());
656
657        assert!(sheet.contains(""));
658        assert!(sheet.get("").unwrap().has_attr(StyleFlags::BOLD));
659    }
660
661    #[test]
662    fn style_id_as_ref_str() {
663        let id = StyleId::new("test");
664        let s: &str = id.as_ref();
665        assert_eq!(s, "test");
666    }
667
668    #[test]
669    fn style_id_clone() {
670        let id1 = StyleId::new("test");
671        let id2 = id1.clone();
672        assert_eq!(id1, id2);
673    }
674
675    #[test]
676    fn style_id_debug_impl() {
677        let id = StyleId::new("test");
678        let debug = format!("{:?}", id);
679        assert!(debug.contains("test"));
680    }
681
682    #[test]
683    fn stylesheet_debug_impl() {
684        let sheet = StyleSheet::new();
685        sheet.define("test", Style::new());
686        let debug = format!("{:?}", sheet);
687        assert!(debug.contains("StyleSheet"));
688    }
689
690    #[test]
691    fn with_defaults_error_style_is_red() {
692        let sheet = StyleSheet::with_defaults();
693        let error = sheet.get("error").unwrap();
694        if let Some(fg) = error.fg {
695            // Red component should be high
696            assert!(fg.r() > 200, "error style should have red foreground");
697        }
698    }
699
700    #[test]
701    fn with_defaults_link_style_is_underlined() {
702        let sheet = StyleSheet::with_defaults();
703        let link = sheet.get("link").unwrap();
704        assert!(
705            link.has_attr(StyleFlags::UNDERLINE),
706            "link style should be underlined"
707        );
708    }
709
710    #[test]
711    fn with_defaults_muted_style_is_dim() {
712        let sheet = StyleSheet::with_defaults();
713        let muted = sheet.get("muted").unwrap();
714        assert!(muted.has_attr(StyleFlags::DIM), "muted style should be dim");
715    }
716
717    #[test]
718    fn with_defaults_highlight_has_background() {
719        let sheet = StyleSheet::with_defaults();
720        let highlight = sheet.get("highlight").unwrap();
721        assert!(
722            highlight.bg.is_some(),
723            "highlight style should have background"
724        );
725    }
726
727    #[test]
728    fn compose_three_styles_in_order() {
729        let sheet = StyleSheet::new();
730        sheet.define("base", Style::new().fg(PackedRgba::WHITE));
731        sheet.define("bold", Style::new().bold());
732        sheet.define("red", Style::new().fg(PackedRgba::rgb(255, 0, 0)));
733
734        // red should override base's fg, bold should add attribute
735        let composed = sheet.compose(&["base", "bold", "red"]);
736
737        assert_eq!(composed.fg, Some(PackedRgba::rgb(255, 0, 0)));
738        assert!(composed.has_attr(StyleFlags::BOLD));
739    }
740
741    #[test]
742    fn compose_layered_precedence_preserves_unset_fields() {
743        let sheet = StyleSheet::new();
744        let base_bg = PackedRgba::rgb(10, 10, 10);
745        let theme_fg = PackedRgba::rgb(200, 50, 50);
746
747        sheet.define("base", Style::new().fg(PackedRgba::WHITE).bg(base_bg));
748        sheet.define("theme", Style::new().fg(theme_fg));
749        sheet.define("widget", Style::new().underline());
750
751        let composed = sheet.compose(&["base", "theme", "widget"]);
752
753        // Later theme overrides base fg, base bg remains, widget adds attrs.
754        assert_eq!(composed.fg, Some(theme_fg));
755        assert_eq!(composed.bg, Some(base_bg));
756        assert!(composed.has_attr(StyleFlags::UNDERLINE));
757    }
758
759    #[test]
760    fn get_or_default_returns_defined_style() {
761        let sheet = StyleSheet::new();
762        let style = Style::new().bold();
763        sheet.define("test", style);
764
765        let retrieved = sheet.get_or_default("test");
766        assert!(retrieved.has_attr(StyleFlags::BOLD));
767    }
768
769    #[test]
770    fn names_returns_empty_for_empty_sheet() {
771        let sheet = StyleSheet::new();
772        let names = sheet.names();
773        assert!(names.is_empty());
774    }
775
776    #[test]
777    fn style_id_hash_consistency() {
778        use std::collections::HashSet;
779
780        let id1 = StyleId::new("test");
781        let id2 = StyleId::new("test");
782        let id3 = StyleId::new("other");
783
784        let mut set = HashSet::new();
785        set.insert(id1.clone());
786
787        assert!(set.contains(&id2));
788        assert!(!set.contains(&id3));
789    }
790}