native_theme_gpui/

lib.rs

//! gpui toolkit connector for native-theme.
//!
//! Maps [`native_theme::ResolvedThemeVariant`] data to gpui-component's theming system.
//!
//! # Quick Start
//!
//! ```ignore
//! use native_theme_gpui::from_preset;
//!
//! let (theme, resolved) = from_preset("catppuccin-mocha", true)?;
//! ```
//!
//! Or from the OS-detected theme:
//!
//! ```ignore
//! use native_theme_gpui::from_system;
//!
//! let (theme, resolved) = from_system()?;
//! ```
//!
//! # Manual Path
//!
//! For full control over the resolve/validate/convert pipeline:
//!
//! ```ignore
//! use native_theme::ThemeSpec;
//! use native_theme_gpui::to_theme;
//!
//! let nt = ThemeSpec::preset("catppuccin-mocha").unwrap();
//! let variant = nt.into_variant(false).unwrap();
//! let resolved = variant.into_resolved().unwrap();
//! let theme = to_theme(&resolved, "Catppuccin Mocha", false);
//! ```
//!
//! # Theme Field Coverage
//!
//! The connector maps a subset of [`ResolvedThemeVariant`] fields to gpui-component's
//! `ThemeColor` (108 color fields) and `ThemeConfig` (font/geometry).
//!
//! | Category | Mapped | Notes |
//! |----------|--------|-------|
//! | `defaults` colors | All 20+ | background, foreground, accent, danger, etc. |
//! | `defaults` geometry | radius, radius_lg, shadow | Font family/size also mapped |
//! | `button` | 4 of 14 | primary_background/foreground, background/foreground (colors only) |
//! | `tab` | 5 of 9 | All colors, sizing not mapped |
//! | `sidebar` | 2 of 2 | background, foreground |
//! | `window` | 2 of 10 | title_bar_background, border |
//! | `input` | 2 of 12 | border, caret |
//! | `scrollbar` | 2 of 7 | thumb, thumb_hover |
//! | `slider`, `switch` | 2 each | fill/thumb colors |
//! | `progress_bar` | 1 of 5 | fill |
//! | `list` | 1 of 11 | alternate_row |
//! | `popover` | 2 of 4 | background, foreground |
//! | 14 other widgets | 0 fields | checkbox, menu, tooltip, dialog, etc. |
//!
//! **Why the gap:** gpui-component's `ThemeColor` is a flat color bag with no per-widget
//! geometry. The connector cannot map most sizing/spacing data because the target type
//! has no corresponding fields. Users who need per-widget geometry can read it directly
//! from the `ResolvedThemeVariant` they passed to [`to_theme()`].

#![warn(missing_docs)]
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]

pub(crate) mod colors;
pub(crate) mod config;
pub(crate) mod derive;
pub mod icons;

// Re-export native-theme types that appear in public signatures so downstream
// crates don't need native-theme as a direct dependency.
pub use native_theme::{
    AnimatedIcon, Error, IconData, IconProvider, IconRole, IconSet, ResolvedThemeVariant,
    SystemTheme, ThemeSpec, ThemeVariant, TransformAnimation,
};

#[cfg(target_os = "linux")]
pub use native_theme::LinuxDesktop;

use gpui::{SharedString, px};
use gpui_component::theme::{Theme, ThemeMode};
use std::rc::Rc;

/// Convert a [`ResolvedThemeVariant`] into a gpui-component [`Theme`].
///
/// Builds a complete Theme by:
/// 1. Mapping all 108 ThemeColor fields via `colors::to_theme_color`
/// 2. Setting font, geometry, and mode fields directly on the Theme
/// 3. Storing a ThemeConfig in light_theme/dark_theme Rc for gpui-component switching
///
/// All Theme fields are set explicitly -- no `apply_config` call is used.
/// This avoids the fragile apply-then-restore pattern where `apply_config`
/// would overwrite all 108 color fields with defaults.
#[must_use = "this returns the theme; it does not apply it"]
pub fn to_theme(resolved: &ResolvedThemeVariant, name: &str, is_dark: bool) -> Theme {
    let theme_color = colors::to_theme_color(resolved, is_dark);
    let mode = if is_dark {
        ThemeMode::Dark
    } else {
        ThemeMode::Light
    };
    let d = &resolved.defaults;

    let mut theme = Theme::from(&theme_color);
    theme.mode = mode;
    theme.font_family = SharedString::from(d.font.family.clone());
    theme.font_size = px(d.font.size);
    theme.mono_font_family = SharedString::from(d.mono_font.family.clone());
    theme.mono_font_size = px(d.mono_font.size);
    theme.radius = px(d.radius);
    theme.radius_lg = px(d.radius_lg);
    theme.shadow = d.shadow_enabled;

    // Store config for gpui-component's theme switching
    let config: Rc<_> = Rc::new(config::to_theme_config(resolved, name, mode));
    if mode == ThemeMode::Dark {
        theme.dark_theme = config;
    } else {
        theme.light_theme = config;
    }
    theme
}

/// Load a bundled preset and convert it to a gpui-component [`Theme`] in one call.
///
/// This is the primary entry point for most users. It handles the full pipeline:
/// load preset, pick variant, resolve, validate, and convert to gpui Theme.
///
/// Returns both the gpui Theme and the [`ResolvedThemeVariant`] so callers can
/// access per-widget metrics (button padding, scrollbar width, etc.) that the
/// flat `ThemeColor` cannot represent.
///
/// The preset name is used as the theme display name.
///
/// # Errors
///
/// Returns an error if the preset name is not recognized or if resolution fails.
///
/// # Examples
///
/// ```ignore
/// let (dark_theme, resolved) = native_theme_gpui::from_preset("dracula", true)?;
/// let (light_theme, _) = native_theme_gpui::from_preset("catppuccin-latte", false)?;
/// ```
#[must_use = "this returns the theme; it does not apply it"]
pub fn from_preset(
    name: &str,
    is_dark: bool,
) -> native_theme::Result<(Theme, ResolvedThemeVariant)> {
    let spec = ThemeSpec::preset(name)?;
    let variant = spec.into_variant(is_dark).ok_or_else(|| {
        native_theme::Error::Format(format!("preset '{name}' has no light or dark variant"))
    })?;
    let resolved = variant.into_resolved()?;
    let theme = to_theme(&resolved, name, is_dark);
    Ok((theme, resolved))
}

/// Detect the OS theme and convert it to a gpui-component [`Theme`] in one call.
///
/// Combines [`SystemTheme::from_system()`](native_theme::SystemTheme::from_system)
/// with [`to_theme()`] using the system-detected name and dark-mode preference.
///
/// Returns both the gpui Theme and the [`ResolvedThemeVariant`] so callers can
/// access per-widget metrics that the flat `ThemeColor` cannot represent.
///
/// # Errors
///
/// Returns an error if the platform theme cannot be read (e.g., unsupported platform,
/// missing desktop environment).
///
/// # Examples
///
/// ```ignore
/// let (theme, resolved) = native_theme_gpui::from_system()?;
/// ```
#[must_use = "this returns the theme; it does not apply it"]
pub fn from_system() -> native_theme::Result<(Theme, ResolvedThemeVariant)> {
    let sys = SystemTheme::from_system()?;
    let is_dark = sys.is_dark;
    let theme = to_theme(sys.active(), &sys.name, sys.is_dark);
    let resolved = if is_dark { sys.dark } else { sys.light };
    Ok((theme, resolved))
}

/// Extension trait for converting a [`SystemTheme`] to a gpui-component [`Theme`].
///
/// Useful when you already have a `SystemTheme` and want method syntax:
///
/// ```ignore
/// use native_theme_gpui::SystemThemeExt;
///
/// let sys = native_theme::SystemTheme::from_system()?;
/// let theme = sys.to_gpui_theme();
/// ```
pub trait SystemThemeExt {
    /// Convert this system theme to a gpui-component [`Theme`].
    ///
    /// Uses the active variant (based on `is_dark`), the theme name,
    /// and the dark-mode flag from the `SystemTheme`.
    #[must_use = "this returns the theme; it does not apply it"]
    fn to_gpui_theme(&self) -> Theme;
}

impl SystemThemeExt for SystemTheme {
    fn to_gpui_theme(&self) -> Theme {
        to_theme(self.active(), &self.name, self.is_dark)
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;

    fn test_resolved() -> ResolvedThemeVariant {
        let nt = ThemeSpec::preset("catppuccin-mocha").expect("preset must exist");
        let variant = nt
            .into_variant(false)
            .expect("preset must have light variant");
        variant
            .into_resolved()
            .expect("resolved preset must validate")
    }

    #[test]
    fn to_theme_produces_valid_theme() {
        let resolved = test_resolved();
        let theme = to_theme(&resolved, "Test", false);

        // Theme should have the correct mode
        assert!(!theme.is_dark());
    }

    #[test]
    fn to_theme_dark_mode() {
        let nt = ThemeSpec::preset("catppuccin-mocha").expect("preset must exist");
        let variant = nt
            .into_variant(true)
            .expect("preset must have dark variant");
        let resolved = variant
            .into_resolved()
            .expect("resolved preset must validate");
        let theme = to_theme(&resolved, "DarkTest", true);

        assert!(theme.is_dark());
    }

    #[test]
    fn to_theme_applies_font_and_geometry() {
        let resolved = test_resolved();
        let theme = to_theme(&resolved, "Test", false);

        assert_eq!(theme.font_family.to_string(), resolved.defaults.font.family);
        assert_eq!(theme.font_size, px(resolved.defaults.font.size));
        assert_eq!(
            theme.mono_font_family.to_string(),
            resolved.defaults.mono_font.family
        );
        assert_eq!(theme.mono_font_size, px(resolved.defaults.mono_font.size));
        assert_eq!(theme.radius, px(resolved.defaults.radius));
        assert_eq!(theme.radius_lg, px(resolved.defaults.radius_lg));
        assert_eq!(theme.shadow, resolved.defaults.shadow_enabled);
    }

    // -- from_preset tests --

    #[test]
    fn from_preset_valid_light() {
        let (theme, _resolved) =
            from_preset("catppuccin-mocha", false).expect("preset should load");
        assert!(!theme.is_dark());
    }

    #[test]
    fn from_preset_valid_dark() {
        let (theme, _resolved) = from_preset("catppuccin-mocha", true).expect("preset should load");
        assert!(theme.is_dark());
    }

    #[test]
    fn from_preset_returns_resolved() {
        let (_theme, resolved) = from_preset("catppuccin-mocha", true).expect("preset should load");
        // ResolvedThemeVariant should have populated defaults
        assert!(resolved.defaults.font.size > 0.0);
    }

    #[test]
    fn from_preset_invalid_name() {
        let result = from_preset("nonexistent-preset", false);
        assert!(result.is_err(), "invalid preset should return Err");
    }

    // -- SystemThemeExt + from_system tests --

    #[test]
    fn system_theme_ext_to_gpui_theme() {
        // from_system() may fail on CI (no desktop env) -- skip gracefully
        let Ok(sys) = SystemTheme::from_system() else {
            return;
        };
        let theme = sys.to_gpui_theme();
        assert_eq!(
            theme.is_dark(),
            sys.is_dark,
            "to_gpui_theme() is_dark should match SystemTheme.is_dark"
        );
    }

    #[test]
    fn from_system_does_not_panic() {
        // Just verify no panic -- result may be Err on CI
        let _ = from_system();
    }

    #[test]
    fn from_system_returns_tuple() {
        let Ok((theme, resolved)) = from_system() else {
            return;
        };
        // Theme and resolved should agree on basic properties
        assert!(resolved.defaults.font.size > 0.0);
        // Theme mode should be set
        let _ = theme.is_dark();
    }

    #[test]
    fn from_system_matches_manual_path() {
        let Ok(sys) = SystemTheme::from_system() else {
            return;
        };
        let via_convenience = sys.to_gpui_theme();
        let via_manual = to_theme(sys.active(), &sys.name, sys.is_dark);
        // Both paths should produce identical results
        assert_eq!(
            via_convenience.is_dark(),
            via_manual.is_dark(),
            "convenience and manual paths should agree on is_dark"
        );
    }
}