fernctl/domain/
theme.rs

1//! # Complete Theme Definition
2//!
3//! A [`Theme`] is a complete, coherent collection of all design tokens needed
4//! to render the Fern Shell UI. It combines colors, typography, spacing, and
5//! radius into a single validated structure.
6//!
7//! ## Design Rationale
8//!
9//! Rather than scattering token values throughout components, a `Theme` provides
10//! a single source of truth. This ensures:
11//!
12//! 1. **Completeness** — All required tokens are present
13//! 2. **Coherence** — Tokens are designed to work together
14//! 3. **Configurability** — Users can customize via config files
15//!
16//! ## Theme Variants
17//!
18//! Fern supports multiple theme variants:
19//!
20//! - **Dark** — Dark backgrounds with light text (default)
21//! - **Light** — Light backgrounds with dark text
22//! - **Auto** — Follows system preference (future)
23//!
24//! ## Example
25//!
26//! ```rust,ignore
27//! use fernctl::domain::theme::{Theme, ThemeVariant};
28//!
29//! // Load default dark theme
30//! let theme = Theme::dark();
31//!
32//! // Access tokens
33//! let bg = theme.colors.background;
34//! let font = &theme.typography.family;
35//! let radius = theme.radius.button();
36//! ```
37
38use super::tokens::{
39    color::*,
40    radius::RadiusScale,
41    spacing::SpacingValue,
42    typography::Typography,
43};
44use serde::{Deserialize, Serialize};
45
46/// Theme variant selection.
47///
48/// Determines the base color palette for the theme.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
50#[serde(rename_all = "lowercase")]
51pub enum ThemeVariant {
52    /// Dark theme with dark backgrounds and light text.
53    #[default]
54    Dark,
55    /// Light theme with light backgrounds and dark text.
56    Light,
57    /// Automatically follow system preference.
58    Auto,
59}
60
61impl ThemeVariant {
62    /// Returns the variant name.
63    #[must_use]
64    pub const fn name(&self) -> &'static str {
65        match self {
66            Self::Dark => "dark",
67            Self::Light => "light",
68            Self::Auto => "auto",
69        }
70    }
71
72    /// Creates a variant from its name.
73    #[must_use]
74    pub fn from_name(name: &str) -> Option<Self> {
75        match name.to_lowercase().as_str() {
76            "dark" => Some(Self::Dark),
77            "light" => Some(Self::Light),
78            "auto" => Some(Self::Auto),
79            _ => None,
80        }
81    }
82}
83
84/// Color palette for a theme.
85///
86/// Contains all semantic colors used throughout the UI.
87#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
88pub struct ColorPalette {
89    /// Primary background color.
90    pub background: ColorToken<Background>,
91    /// Elevated surface color.
92    pub surface: ColorToken<Surface>,
93    /// Hover state for surfaces.
94    pub surface_hover: ColorToken<SurfaceHover>,
95    /// Primary text color.
96    pub foreground: ColorToken<Foreground>,
97    /// Secondary/dimmed text color.
98    pub foreground_dim: ColorToken<ForegroundDim>,
99    /// Accent color for highlights.
100    pub accent: ColorToken<Accent>,
101    /// Error state color.
102    pub error: ColorToken<Error>,
103    /// Warning state color.
104    pub warning: ColorToken<Warning>,
105    /// Success state color.
106    pub success: ColorToken<Success>,
107    /// Info state color.
108    pub info: ColorToken<Info>,
109}
110
111impl ColorPalette {
112    /// Creates the default dark color palette (Catppuccin Mocha).
113    #[must_use]
114    pub fn dark() -> Self {
115        Self {
116            background: ColorToken::from_hex("#1e1e2e").expect("valid hex"),
117            surface: ColorToken::from_hex("#313244").expect("valid hex"),
118            surface_hover: ColorToken::from_hex("#45475a").expect("valid hex"),
119            foreground: ColorToken::from_hex("#cdd6f4").expect("valid hex"),
120            foreground_dim: ColorToken::from_hex("#a6adc8").expect("valid hex"),
121            accent: ColorToken::from_hex("#89b4fa").expect("valid hex"),
122            error: ColorToken::from_hex("#f38ba8").expect("valid hex"),
123            warning: ColorToken::from_hex("#f9e2af").expect("valid hex"),
124            success: ColorToken::from_hex("#a6e3a1").expect("valid hex"),
125            info: ColorToken::from_hex("#89dceb").expect("valid hex"),
126        }
127    }
128
129    /// Creates the default light color palette (Catppuccin Latte).
130    #[must_use]
131    pub fn light() -> Self {
132        Self {
133            background: ColorToken::from_hex("#eff1f5").expect("valid hex"),
134            surface: ColorToken::from_hex("#e6e9ef").expect("valid hex"),
135            surface_hover: ColorToken::from_hex("#dce0e8").expect("valid hex"),
136            foreground: ColorToken::from_hex("#4c4f69").expect("valid hex"),
137            foreground_dim: ColorToken::from_hex("#6c6f85").expect("valid hex"),
138            accent: ColorToken::from_hex("#1e66f5").expect("valid hex"),
139            error: ColorToken::from_hex("#d20f39").expect("valid hex"),
140            warning: ColorToken::from_hex("#df8e1d").expect("valid hex"),
141            success: ColorToken::from_hex("#40a02b").expect("valid hex"),
142            info: ColorToken::from_hex("#04a5e5").expect("valid hex"),
143        }
144    }
145}
146
147impl Default for ColorPalette {
148    fn default() -> Self {
149        Self::dark()
150    }
151}
152
153/// Bar (panel) configuration.
154#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
155pub struct BarConfig {
156    /// Bar height in pixels.
157    #[serde(default = "default_bar_height")]
158    pub height: u16,
159    /// Bar position (top or bottom).
160    #[serde(default)]
161    pub position: BarPosition,
162    /// Margin from screen edge.
163    #[serde(default)]
164    pub margin: u16,
165}
166
167fn default_bar_height() -> u16 {
168    40
169}
170
171impl Default for BarConfig {
172    fn default() -> Self {
173        Self {
174            height: 40,
175            position: BarPosition::Top,
176            margin: 0,
177        }
178    }
179}
180
181/// Bar position on screen.
182#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
183#[serde(rename_all = "lowercase")]
184pub enum BarPosition {
185    /// Bar at top of screen.
186    #[default]
187    Top,
188    /// Bar at bottom of screen.
189    Bottom,
190}
191
192impl BarPosition {
193    /// Returns the position name.
194    #[must_use]
195    pub const fn name(&self) -> &'static str {
196        match self {
197            Self::Top => "top",
198            Self::Bottom => "bottom",
199        }
200    }
201}
202
203/// A complete theme combining all design tokens.
204///
205/// `Theme` is the central configuration object for the Fern Shell UI.
206/// It contains all colors, typography, spacing, and other visual settings
207/// needed to render the interface consistently.
208///
209/// # Creating a Theme
210///
211/// ```rust
212/// use fernctl::domain::theme::Theme;
213///
214/// // Default dark theme
215/// let theme = Theme::dark();
216///
217/// // Default light theme
218/// let theme = Theme::light();
219///
220/// // From configuration (typically via adapters)
221/// // let theme = Theme::from_config(config)?;
222/// ```
223///
224/// # Accessing Tokens
225///
226/// ```rust
227/// use fernctl::domain::theme::Theme;
228///
229/// let theme = Theme::dark();
230///
231/// // Colors
232/// let bg_color = &theme.colors.background;
233/// let accent = &theme.colors.accent;
234///
235/// // Typography
236/// let font = &theme.typography.family;
237/// let mono = &theme.typography.mono;
238///
239/// // Radius
240/// let button_radius = theme.radius.button();
241/// let module_radius = theme.radius.module();
242///
243/// // Bar
244/// let bar_height = theme.bar.height;
245/// ```
246#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
247pub struct Theme {
248    /// The theme variant (dark, light, auto).
249    #[serde(default)]
250    pub variant: ThemeVariant,
251    /// Color palette.
252    #[serde(default)]
253    pub colors: ColorPalette,
254    /// Typography settings.
255    #[serde(default)]
256    pub typography: Typography,
257    /// Radius scale.
258    #[serde(default)]
259    pub radius: RadiusScale,
260    /// Bar configuration.
261    #[serde(default)]
262    pub bar: BarConfig,
263}
264
265impl Theme {
266    /// Creates a new dark theme with default values.
267    ///
268    /// This is the recommended default theme for Fern Shell.
269    ///
270    /// # Example
271    ///
272    /// ```rust
273    /// use fernctl::domain::theme::Theme;
274    ///
275    /// let theme = Theme::dark();
276    /// assert_eq!(theme.variant.name(), "dark");
277    /// ```
278    #[must_use]
279    pub fn dark() -> Self {
280        Self {
281            variant: ThemeVariant::Dark,
282            colors: ColorPalette::dark(),
283            typography: Typography::default(),
284            radius: RadiusScale::default(),
285            bar: BarConfig::default(),
286        }
287    }
288
289    /// Creates a new light theme with default values.
290    ///
291    /// # Example
292    ///
293    /// ```rust
294    /// use fernctl::domain::theme::Theme;
295    ///
296    /// let theme = Theme::light();
297    /// assert_eq!(theme.variant.name(), "light");
298    /// ```
299    #[must_use]
300    pub fn light() -> Self {
301        Self {
302            variant: ThemeVariant::Light,
303            colors: ColorPalette::light(),
304            typography: Typography::default(),
305            radius: RadiusScale::default(),
306            bar: BarConfig::default(),
307        }
308    }
309
310    /// Returns the default spacing value for modules.
311    ///
312    /// This is a convenience method for common usage.
313    #[must_use]
314    pub const fn module_spacing(&self) -> u16 {
315        SpacingValue::Lg.pixels()
316    }
317
318    /// Returns the default spacing value for buttons.
319    #[must_use]
320    pub const fn button_spacing(&self) -> u16 {
321        SpacingValue::Sm.pixels()
322    }
323}
324
325impl Default for Theme {
326    fn default() -> Self {
327        Self::dark()
328    }
329}
330
331#[cfg(test)]
332mod tests {
333    use super::*;
334
335    #[test]
336    fn theme_dark_default() {
337        let theme = Theme::dark();
338        assert_eq!(theme.variant, ThemeVariant::Dark);
339        assert_eq!(theme.bar.height, 40);
340    }
341
342    #[test]
343    fn theme_light() {
344        let theme = Theme::light();
345        assert_eq!(theme.variant, ThemeVariant::Light);
346    }
347
348    #[test]
349    fn theme_serialization_roundtrip() {
350        let original = Theme::dark();
351        let json = serde_json::to_string_pretty(&original).unwrap();
352        let restored: Theme = serde_json::from_str(&json).unwrap();
353        assert_eq!(original.variant, restored.variant);
354        assert_eq!(original.bar.height, restored.bar.height);
355    }
356
357    #[test]
358    fn theme_variant_from_name() {
359        assert_eq!(ThemeVariant::from_name("dark"), Some(ThemeVariant::Dark));
360        assert_eq!(ThemeVariant::from_name("LIGHT"), Some(ThemeVariant::Light));
361        assert_eq!(ThemeVariant::from_name("invalid"), None);
362    }
363}