Struct Theme 

pub struct Theme { /* private fields */ }

A named collection of styles used when rendering templates.

Themes can be constructed programmatically or loaded from YAML files. They support adaptive styles that vary based on the user’s color mode.

Example: Programmatic Construction

use standout_render::Theme;
use console::Style;

let theme = Theme::new()
    // Visual layer - concrete styles
    .add("muted", Style::new().dim())
    .add("accent", Style::new().cyan().bold())
    // Presentation layer - aliases
    .add("disabled", "muted")
    .add("highlighted", "accent")
    // Semantic layer - aliases to presentation
    .add("timestamp", "disabled");

Example: From YAML

use standout_render::Theme;

let theme = Theme::from_yaml(r#"
panel:
  bg: gray
  light:
    bg: white
  dark:
    bg: black
header:
  fg: cyan
  bold: true
"#).unwrap();

Implementations

impl Theme

pub fn new() -> Self

Creates an empty, unnamed theme.

pub fn named(name: impl Into<String>) -> Self

Creates an empty theme with the given name.

pub fn with_name(self, name: impl Into<String>) -> Self

Sets the name on this theme, returning self for chaining.

This is useful when loading themes from content where the name is known separately (e.g., from a filename).

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, StylesheetError>

Loads a theme from a YAML file.

The theme name is derived from the filename (without extension). The source path is stored for refresh support.

Errors

Returns a StylesheetError if the file cannot be read or parsed.

Example

use standout_render::Theme;

let theme = Theme::from_file("./themes/darcula.yaml")?;
assert_eq!(theme.name(), Some("darcula"));

pub fn from_yaml(yaml: &str) -> Result<Self, StylesheetError>

Creates a theme from YAML content.

The YAML format supports:

• Simple styles: header: { fg: cyan, bold: true }
• Shorthand: bold_text: bold or warning: "yellow italic"
• Aliases: disabled: muted
• Adaptive styles with light: and dark: sections

Errors

Returns a StylesheetError if parsing fails.

Example

use standout_render::Theme;

let theme = Theme::from_yaml(r#"
header:
  fg: cyan
  bold: true

footer:
  dim: true
  light:
    fg: black
  dark:
    fg: white
"#).unwrap();

pub fn from_variants(variants: ThemeVariants) -> Self

Creates a theme from pre-parsed theme variants.

pub fn name(&self) -> Option<&str>

Returns the theme name, if set.

The name is typically derived from the source filename when using from_file, or set explicitly with named.

pub fn source_path(&self) -> Option<&Path>

Returns the source file path, if this theme was loaded from a file.

pub fn refresh(&mut self) -> Result<(), StylesheetError>

Reloads the theme from its source file.

This is useful for hot-reloading during development. If the theme was not loaded from a file, this method returns an error.

Errors

Returns a StylesheetError if:

• The theme has no source file (wasn’t loaded with from_file)
• The file cannot be read or parsed

Example

let mut theme = Theme::from_file("./themes/darcula.yaml")?;

// After editing the file...
theme.refresh()?;

pub fn add<V: Into<StyleValue>>(self, name: &str, value: V) -> Self

Adds a named style, returning an updated theme for chaining.

The value can be either a concrete Style or a &str/String alias to another style name, enabling layered styling.

Non-Adaptive

Styles added via this method are non-adaptive (same in all modes). For adaptive styles, use add_adaptive or YAML.

Example

use standout_render::Theme;
use console::Style;

let theme = Theme::new()
    // Visual layer - concrete styles
    .add("muted", Style::new().dim())
    .add("accent", Style::new().cyan().bold())
    // Presentation layer - aliases
    .add("disabled", "muted")
    .add("highlighted", "accent")
    // Semantic layer - aliases to presentation
    .add("timestamp", "disabled");

pub fn add_adaptive( self, name: &str, base: Style, light: Option<Style>, dark: Option<Style>, ) -> Self

Adds an adaptive style with separate light and dark variants.

The base style is used when no mode override exists or when mode detection fails. Light and dark variants, if provided, override the base in their respective modes.

Example

use standout_render::Theme;
use console::Style;

let theme = Theme::new()
    .add_adaptive(
        "panel",
        Style::new().dim(),                    // Base
        Some(Style::new().fg(console::Color::Black)),  // Light mode
        Some(Style::new().fg(console::Color::White)),  // Dark mode
    );

pub fn resolve_styles(&self, mode: Option<ColorMode>) -> Styles

Resolves styles for the given color mode.

Returns a Styles collection with the appropriate style for each defined style name:

• For styles with a mode-specific override, uses the override
• For styles without an override, uses the base style
• Aliases are preserved for resolution during rendering

Example

use standout_render::{Theme, ColorMode};
use console::Style;

let theme = Theme::new()
    .add("header", Style::new().cyan())
    .add_adaptive(
        "panel",
        Style::new(),
        Some(Style::new().fg(console::Color::Black)),
        Some(Style::new().fg(console::Color::White)),
    );

// Get styles for dark mode
let dark_styles = theme.resolve_styles(Some(ColorMode::Dark));

pub fn validate(&self) -> Result<(), StyleValidationError>

Validates that all style aliases in this theme resolve correctly.

This is called automatically at render time, but can be called explicitly for early error detection.

pub fn is_empty(&self) -> bool

Returns true if no styles are defined.

pub fn len(&self) -> usize

Returns the number of defined styles (base + aliases).

pub fn get_style(&self, name: &str, mode: Option<ColorMode>) -> Option<Style>

Resolves a single style for the given mode.

This is a convenience wrapper around resolve_styles.

pub fn light_override_count(&self) -> usize

Returns the number of light mode overrides.

pub fn dark_override_count(&self) -> usize

Returns the number of dark mode overrides.

pub fn merge(self, other: Theme) -> Self

Merges another theme into this one.

Styles from other take precedence over styles in self. This allows layering themes, e.g., loading a base theme and applying user overrides.

Example

use standout_render::Theme;
use console::Style;

let base = Theme::new().add("text", Style::new().dim());
let user = Theme::new().add("text", Style::new().bold());

let merged = base.merge(user);
// "text" is now bold (from user)

Trait Implementations

impl Clone for Theme

fn clone(&self) -> Theme

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Theme

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Theme

fn default() -> Self

Returns the “default value” for a type.