makeover-layout 0.56.0

/// Which ambient mode a theme is written for.
///
/// The vocabulary's own spelling of what `makeover` calls a theme's variant,
/// and the duplication is deliberate rather than an oversight. This crate has
/// no dependencies by charter (it emits nothing, reads nothing and resolves
/// nothing) so it cannot take the crate that owns the file format, and a
/// renderer that must group a picker needs the three groups as values.
///
/// The two are kept in step by the app that converts between them, which is a
/// three-arm `match` at each adopter and the price of the layering. If a fourth
/// mode is ever authored, this enum and `makeover::Variant` move together.
///
/// Three, not two: one shipped theme is high contrast, and an app matching on
/// light-or-dark alone files it under the wrong one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[non_exhaustive]
pub enum ThemeVariant {
    /// Written for a light ambient mode.
    Light,
    /// Written for a dark ambient mode.
    Dark,
    /// Written to be legible before it is pretty.
    HighContrast,
}

impl ThemeVariant {
    /// The machine spelling, matching the theme file's own `meta.variant`.
    ///
    /// A data attribute, a stored value, a test assertion. Not a heading: what
    /// a group is *called* on screen is [`heading`](Self::heading).
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            ThemeVariant::Light => "light",
            ThemeVariant::Dark => "dark",
            ThemeVariant::HighContrast => "high-contrast",
        }
    }

    /// What the group of themes in this variant is called on screen.
    ///
    /// Here rather than at each renderer, which is the whole argument for the
    /// member existing: three renderers picking their own headings is one
    /// picker reading three ways, and the spellings below are the ones
    /// goingson's shipped picker used before it was described.
    #[must_use]
    pub const fn heading(self) -> &'static str {
        match self {
            ThemeVariant::Light => "Light",
            ThemeVariant::Dark => "Dark",
            ThemeVariant::HighContrast => "High Contrast",
        }
    }
}

impl std::fmt::Display for ThemeVariant {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// How legible a theme measured, as a picker reports it.
///
/// A measurement carried into the description, which is unusual here and is the
/// one case that earns it: the number comes off the theme's resolved colours,
/// so the layer that loaded the theme is the only party that has it, and an app
/// re-deriving it would be parsing every theme file a second time to learn what
/// was already known. What a renderer does with it is a badge beside the name.
///
/// Ordered worst-first, matching `makeover::ContrastTier`, so the two sort the
/// same way and an adopter's `match` cannot invert an ordering by accident.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[non_exhaustive]
pub enum Contrast {
    /// Muted text below the 3:1 floor for large text and UI parts.
    Low,
    /// Muted text clears 3:1 but not the 4.5:1 bar for normal text.
    Standard,
    /// Muted text meets WCAG AA on every panel ground.
    High,
}

impl Contrast {
    /// The machine spelling, for a data attribute or a test.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Contrast::Low => "low",
            Contrast::Standard => "standard",
            Contrast::High => "high",
        }
    }

    /// The short mark shown beside a theme's name.
    ///
    /// One spelling for the tree, for [`ThemeVariant::heading`]'s reason. These
    /// are the marks audiofiles shipped before its picker was described, which
    /// is the only implementation that ever drew them.
    ///
    /// [`Standard`](Self::Standard) is not the absence of a mark: a reader
    /// scanning a column of badges learns more from three marks than from two
    /// and a gap, and "OK" is the honest reading of a theme that clears the UI
    /// floor and misses the text one.
    #[must_use]
    pub const fn badge(self) -> &'static str {
        match self {
            Contrast::Low => "low",
            Contrast::Standard => "OK",
            Contrast::High => "AA",
        }
    }
}

impl std::fmt::Display for Contrast {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}