fernctl/domain/tokens/
typography.rs

1//! # Typography Tokens
2//!
3//! This module provides type-safe typography tokens for font families and
4//! size scales used throughout the Fern design system.
5//!
6//! ## Font Categories
7//!
8//! Fern uses three font categories:
9//!
10//! | Category | Purpose | Default |
11//! |----------|---------|---------|
12//! | Primary | UI text, labels | Inter |
13//! | Monospace | Code, terminal icons | JetBrainsMono Nerd Font |
14//! | Icon | Material icons | Material Symbols Rounded |
15//!
16//! ## Font Size Scale
17//!
18//! Font sizes follow a semantic scale rather than arbitrary pixel values:
19//!
20//! | Token | Pixels | Use Case |
21//! |-------|--------|----------|
22//! | `Xs` | 10px | Captions, legal text |
23//! | `Sm` | 12px | Labels, secondary text |
24//! | `Md` | 14px | Body text (default) |
25//! | `Lg` | 16px | Subheadings |
26//! | `Xl` | 20px | Headings |
27//! | `Xxl` | 24px | Large headings |
28
29use serde::{Deserialize, Serialize};
30use std::fmt;
31
32/// A font family specification.
33///
34/// `FontFamily` represents a font family name that can be used in the UI.
35/// It stores the family name as a string and provides validation.
36///
37/// # Example
38///
39/// ```rust
40/// use fernctl::domain::tokens::typography::FontFamily;
41///
42/// let font = FontFamily::new("Inter");
43/// assert_eq!(font.name(), "Inter");
44/// ```
45#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
46#[serde(transparent)]
47pub struct FontFamily {
48    name: String,
49}
50
51impl FontFamily {
52    /// Creates a new font family from a name.
53    ///
54    /// # Arguments
55    ///
56    /// * `name` — The font family name (e.g., "Inter", "JetBrainsMono Nerd Font")
57    ///
58    /// # Example
59    ///
60    /// ```rust
61    /// use fernctl::domain::tokens::typography::FontFamily;
62    ///
63    /// let font = FontFamily::new("Inter");
64    /// ```
65    #[must_use]
66    pub fn new(name: impl Into<String>) -> Self {
67        Self { name: name.into() }
68    }
69
70    /// Returns the font family name.
71    ///
72    /// # Example
73    ///
74    /// ```rust
75    /// use fernctl::domain::tokens::typography::FontFamily;
76    ///
77    /// let font = FontFamily::new("Inter");
78    /// assert_eq!(font.name(), "Inter");
79    /// ```
80    #[must_use]
81    pub fn name(&self) -> &str {
82        &self.name
83    }
84
85    /// Returns the default primary (UI) font family.
86    ///
87    /// # Example
88    ///
89    /// ```rust
90    /// use fernctl::domain::tokens::typography::FontFamily;
91    ///
92    /// let font = FontFamily::default_primary();
93    /// assert_eq!(font.name(), "Inter");
94    /// ```
95    #[must_use]
96    pub fn default_primary() -> Self {
97        Self::new("Inter")
98    }
99
100    /// Returns the default monospace font family.
101    ///
102    /// # Example
103    ///
104    /// ```rust
105    /// use fernctl::domain::tokens::typography::FontFamily;
106    ///
107    /// let font = FontFamily::default_mono();
108    /// assert_eq!(font.name(), "JetBrainsMono Nerd Font");
109    /// ```
110    #[must_use]
111    pub fn default_mono() -> Self {
112        Self::new("JetBrainsMono Nerd Font")
113    }
114
115    /// Returns the default icon font family.
116    ///
117    /// # Example
118    ///
119    /// ```rust
120    /// use fernctl::domain::tokens::typography::FontFamily;
121    ///
122    /// let font = FontFamily::default_icon();
123    /// assert_eq!(font.name(), "Material Symbols Rounded");
124    /// ```
125    #[must_use]
126    pub fn default_icon() -> Self {
127        Self::new("Material Symbols Rounded")
128    }
129}
130
131impl Default for FontFamily {
132    fn default() -> Self {
133        Self::default_primary()
134    }
135}
136
137impl fmt::Display for FontFamily {
138    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
139        write!(f, "{}", self.name)
140    }
141}
142
143impl From<&str> for FontFamily {
144    fn from(s: &str) -> Self {
145        Self::new(s)
146    }
147}
148
149impl From<String> for FontFamily {
150    fn from(s: String) -> Self {
151        Self::new(s)
152    }
153}
154
155/// Font size scale with semantic sizes.
156///
157/// This enum represents the available font sizes in the design system.
158/// Using semantic names rather than pixel values ensures consistency
159/// and makes it easy to adjust the entire scale.
160///
161/// # Example
162///
163/// ```rust
164/// use fernctl::domain::tokens::typography::FontSize;
165///
166/// let size = FontSize::Md;
167/// assert_eq!(size.pixels(), 14);
168/// ```
169#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
170#[serde(rename_all = "lowercase")]
171pub enum FontSize {
172    /// Extra-small (10px) — Captions, legal text
173    Xs,
174    /// Small (12px) — Labels, secondary text
175    Sm,
176    /// Medium (14px) — Body text (default)
177    Md,
178    /// Large (16px) — Subheadings
179    Lg,
180    /// Extra-large (20px) — Headings
181    Xl,
182    /// Double extra-large (24px) — Large headings
183    Xxl,
184}
185
186impl FontSize {
187    /// Returns the size in pixels.
188    ///
189    /// # Example
190    ///
191    /// ```rust
192    /// use fernctl::domain::tokens::typography::FontSize;
193    ///
194    /// assert_eq!(FontSize::Xs.pixels(), 10);
195    /// assert_eq!(FontSize::Sm.pixels(), 12);
196    /// assert_eq!(FontSize::Md.pixels(), 14);
197    /// assert_eq!(FontSize::Lg.pixels(), 16);
198    /// assert_eq!(FontSize::Xl.pixels(), 20);
199    /// assert_eq!(FontSize::Xxl.pixels(), 24);
200    /// ```
201    #[must_use]
202    pub const fn pixels(&self) -> u16 {
203        match self {
204            Self::Xs => 10,
205            Self::Sm => 12,
206            Self::Md => 14,
207            Self::Lg => 16,
208            Self::Xl => 20,
209            Self::Xxl => 24,
210        }
211    }
212
213    /// Returns the semantic name of this size.
214    ///
215    /// # Example
216    ///
217    /// ```rust
218    /// use fernctl::domain::tokens::typography::FontSize;
219    ///
220    /// assert_eq!(FontSize::Md.name(), "md");
221    /// ```
222    #[must_use]
223    pub const fn name(&self) -> &'static str {
224        match self {
225            Self::Xs => "xs",
226            Self::Sm => "sm",
227            Self::Md => "md",
228            Self::Lg => "lg",
229            Self::Xl => "xl",
230            Self::Xxl => "xxl",
231        }
232    }
233
234    /// Creates a font size from its name.
235    ///
236    /// # Example
237    ///
238    /// ```rust
239    /// use fernctl::domain::tokens::typography::FontSize;
240    ///
241    /// assert_eq!(FontSize::from_name("md"), Some(FontSize::Md));
242    /// assert_eq!(FontSize::from_name("invalid"), None);
243    /// ```
244    #[must_use]
245    pub fn from_name(name: &str) -> Option<Self> {
246        match name.to_lowercase().as_str() {
247            "xs" => Some(Self::Xs),
248            "sm" => Some(Self::Sm),
249            "md" => Some(Self::Md),
250            "lg" => Some(Self::Lg),
251            "xl" => Some(Self::Xl),
252            "xxl" => Some(Self::Xxl),
253            _ => None,
254        }
255    }
256
257    /// Returns all font sizes in order from smallest to largest.
258    #[must_use]
259    pub const fn all() -> &'static [FontSize] {
260        &[
261            Self::Xs,
262            Self::Sm,
263            Self::Md,
264            Self::Lg,
265            Self::Xl,
266            Self::Xxl,
267        ]
268    }
269}
270
271impl Default for FontSize {
272    fn default() -> Self {
273        Self::Md
274    }
275}
276
277impl fmt::Display for FontSize {
278    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
279        write!(f, "{}px", self.pixels())
280    }
281}
282
283/// Complete font size scale with pixel values.
284///
285/// While [`FontSize`] provides semantic names, `FontSizeScale` allows
286/// customizing the actual pixel values via configuration.
287///
288/// # Example
289///
290/// ```rust
291/// use fernctl::domain::tokens::typography::FontSizeScale;
292///
293/// let scale = FontSizeScale::default();
294/// assert_eq!(scale.md, 14);
295/// ```
296#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
297pub struct FontSizeScale {
298    /// Extra-small size in pixels.
299    #[serde(default = "default_xs")]
300    pub xs: u16,
301    /// Small size in pixels.
302    #[serde(default = "default_sm")]
303    pub sm: u16,
304    /// Medium size in pixels.
305    #[serde(default = "default_md")]
306    pub md: u16,
307    /// Large size in pixels.
308    #[serde(default = "default_lg")]
309    pub lg: u16,
310    /// Extra-large size in pixels.
311    #[serde(default = "default_xl")]
312    pub xl: u16,
313    /// Double extra-large size in pixels.
314    #[serde(default = "default_xxl")]
315    pub xxl: u16,
316}
317
318fn default_xs() -> u16 {
319    FontSize::Xs.pixels()
320}
321fn default_sm() -> u16 {
322    FontSize::Sm.pixels()
323}
324fn default_md() -> u16 {
325    FontSize::Md.pixels()
326}
327fn default_lg() -> u16 {
328    FontSize::Lg.pixels()
329}
330fn default_xl() -> u16 {
331    FontSize::Xl.pixels()
332}
333fn default_xxl() -> u16 {
334    FontSize::Xxl.pixels()
335}
336
337impl FontSizeScale {
338    /// Creates a new font size scale with default values.
339    #[must_use]
340    pub const fn new() -> Self {
341        Self {
342            xs: 10,
343            sm: 12,
344            md: 14,
345            lg: 16,
346            xl: 20,
347            xxl: 24,
348        }
349    }
350
351    /// Returns the pixel value for a given semantic size.
352    #[must_use]
353    pub const fn get(&self, size: FontSize) -> u16 {
354        match size {
355            FontSize::Xs => self.xs,
356            FontSize::Sm => self.sm,
357            FontSize::Md => self.md,
358            FontSize::Lg => self.lg,
359            FontSize::Xl => self.xl,
360            FontSize::Xxl => self.xxl,
361        }
362    }
363}
364
365impl Default for FontSizeScale {
366    fn default() -> Self {
367        Self::new()
368    }
369}
370
371/// Typography configuration combining fonts and sizes.
372///
373/// This struct contains all typography-related settings for the theme.
374///
375/// # Example
376///
377/// ```rust
378/// use fernctl::domain::tokens::typography::Typography;
379///
380/// let typography = Typography::default();
381/// assert_eq!(typography.family.name(), "Inter");
382/// assert_eq!(typography.size.md, 14);
383/// ```
384#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
385pub struct Typography {
386    /// Primary (UI) font family.
387    #[serde(default = "FontFamily::default_primary")]
388    pub family: FontFamily,
389    /// Monospace font family.
390    #[serde(default = "FontFamily::default_mono")]
391    pub mono: FontFamily,
392    /// Icon font family.
393    #[serde(default = "FontFamily::default_icon")]
394    pub icon: FontFamily,
395    /// Font size scale.
396    #[serde(default)]
397    pub size: FontSizeScale,
398}
399
400impl Typography {
401    /// Creates typography configuration with default values.
402    #[must_use]
403    pub fn new() -> Self {
404        Self {
405            family: FontFamily::default_primary(),
406            mono: FontFamily::default_mono(),
407            icon: FontFamily::default_icon(),
408            size: FontSizeScale::default(),
409        }
410    }
411}
412
413impl Default for Typography {
414    fn default() -> Self {
415        Self::new()
416    }
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422
423    #[test]
424    fn font_family_creation() {
425        let font = FontFamily::new("Test Font");
426        assert_eq!(font.name(), "Test Font");
427    }
428
429    #[test]
430    fn font_family_defaults() {
431        assert_eq!(FontFamily::default_primary().name(), "Inter");
432        assert_eq!(
433            FontFamily::default_mono().name(),
434            "JetBrainsMono Nerd Font"
435        );
436        assert_eq!(FontFamily::default_icon().name(), "Material Symbols Rounded");
437    }
438
439    #[test]
440    fn font_size_pixels() {
441        assert_eq!(FontSize::Xs.pixels(), 10);
442        assert_eq!(FontSize::Sm.pixels(), 12);
443        assert_eq!(FontSize::Md.pixels(), 14);
444        assert_eq!(FontSize::Lg.pixels(), 16);
445        assert_eq!(FontSize::Xl.pixels(), 20);
446        assert_eq!(FontSize::Xxl.pixels(), 24);
447    }
448
449    #[test]
450    fn font_size_from_name() {
451        assert_eq!(FontSize::from_name("md"), Some(FontSize::Md));
452        assert_eq!(FontSize::from_name("XL"), Some(FontSize::Xl));
453        assert_eq!(FontSize::from_name("invalid"), None);
454    }
455
456    #[test]
457    fn font_size_scale_get() {
458        let scale = FontSizeScale::default();
459        assert_eq!(scale.get(FontSize::Md), 14);
460        assert_eq!(scale.get(FontSize::Xl), 20);
461    }
462
463    #[test]
464    fn typography_serialization() {
465        let typography = Typography::default();
466        let json = serde_json::to_string(&typography).unwrap();
467        let restored: Typography = serde_json::from_str(&json).unwrap();
468        assert_eq!(typography.family, restored.family);
469    }
470}