standout-render 7.1.0

Styled terminal rendering with templates, themes, and adaptive color support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

//! Adaptive themes with automatic light/dark mode support.
//!
//! Themes are named collections of styles that automatically adapt to the user's
//! OS color scheme. Unlike systems with separate "light theme" and "dark theme"
//! files, Standout's themes define mode-specific variations at the style level,
//! eliminating duplication for styles that don't change between modes.
//!
//! ## Design Decision: Style-Level Adaptation
//!
//! Most styles (bold, italic, semantic colors) look fine in both modes. Only a
//! handful need adjustment — typically foreground colors for contrast. By making
//! adaptation per-style rather than per-theme, you define shared styles once and
//! override only what differs:
//!
//! ```yaml
//! # Shared across all modes
//! header:
//!   fg: cyan
//!   bold: true
//!
//! # Mode-specific overrides
//! panel:
//!   fg: gray          # Base (fallback)
//!   light:
//!     fg: black       # Override for light mode
//!   dark:
//!     fg: white       # Override for dark mode
//! ```
//!
//! ## How Merging Works
//!
//! When resolving a style in Dark mode:
//! 1. Start with base attributes (`fg: gray`)
//! 2. Merge dark overrides — each attribute in `dark:` replaces the base
//! 3. Result: `fg: white` (from dark), other attributes preserved from base
//!
//! This is additive: `Some` values in overrides replace, missing values preserve base.
//!
//! ## Color Mode Detection
//!
//! [`detect_color_mode`] queries the OS for the user's preferred scheme. Override
//! it for testing with [`set_theme_detector`]:
//!
//! ```rust,ignore
//! standout_render::set_theme_detector(|| ColorMode::Dark);
//! ```
//!
//! ## Construction
//!
//! Programmatic (for compile-time themes):
//! ```rust
//! use standout_render::Theme;
//! use console::Style;
//!
//! let theme = Theme::new()
//!     .add("header", Style::new().bold().cyan())
//!     .add_adaptive("panel", Style::new(),
//!         Some(Style::new().fg(console::Color::Black)),
//!         Some(Style::new().fg(console::Color::White)));
//! ```
//!
//! YAML (for user-customizable themes):
//! ```rust
//! let theme = standout_render::Theme::from_yaml(r#"
//! header: { fg: cyan, bold: true }
//! panel:
//!   fg: gray
//!   light: { fg: black }
//!   dark: { fg: white }
//! "#).unwrap();
//! ```
//!
//! ## See Also
//!
//! - [`crate::stylesheet`]: YAML parsing details and color format reference
//! - [`crate::style`]: Low-level style primitives and aliasing

mod adaptive;
mod icon_def;
mod icon_mode;
#[allow(clippy::module_inception)]
mod theme;

pub use adaptive::{detect_color_mode, set_theme_detector, ColorMode};
pub use icon_def::{IconDefinition, IconSet};
pub use icon_mode::{detect_icon_mode, set_icon_detector, IconMode};
pub use theme::Theme;