cranpose-ui 0.1.164

//! Colours and text styles a Wear widget is handed.
//!
//! Cranpose has no theme system, and this module does not start one. There is
//! no composition local, no `MaterialTheme`, no ambient lookup: every Wear
//! widget takes a [`WearColors`] in its spec and a caller passes one down.
//! Building a theme system is a much larger design than a widget set, and the
//! widgets do not need it.
//!
//! What is worth encoding is the part a port gets wrong from reading the Kotlin:
//! which role each slot draws with. `MaterialTheme` provides eight composition
//! locals and `LocalContentColor` is **not** among them — its declaration is
//! `compositionLocalOf { Color.White }` and only `AppScaffold` overrides it. So
//! a bare `Text` on a Wear screen is white, while a `ListHeader` on the same
//! screen is `onBackground`. Two different whites side by side, and a port that
//! resolves both to `onBackground` is wrong by 8 counts of red and 9 of green
//! on every bare `Text`. [`WearColors::content`] is that colour, kept separate
//! for exactly that reason.

use crate::{
    modifier::Color,
    text::{
        FontFamily, FontWeight, TextUnit,
        paragraph::TextAlign,
        style::{
            LineHeightAlignment, LineHeightMode, LineHeightStyle, LineHeightTrim, ParagraphStyle,
            PlatformParagraphStyle, SpanStyle, TextStyle,
        },
    },
    widgets::wear::color_appearance::set_luminance,
};

/// The colour roles these widgets read.
///
/// This is the subset of Wear Material 3's `ColorScheme` that the Settings and
/// Credits screens reach, not the whole scheme — a role nothing draws with is
/// a role nobody can get wrong.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct WearColors {
    /// A filled `Button`'s container, and a checked switch's track.
    pub primary: Color,
    /// A checked `SwitchButton`'s container, and its thumb.
    pub primary_container: Color,
    /// A filled `Button`'s label.
    pub on_primary: Color,
    /// A checked `SwitchButton`'s label.
    pub on_primary_container: Color,
    /// An unchecked `SwitchButton`'s container and track.
    pub surface_container: Color,
    pub on_surface: Color,
    /// A secondary label on an unchecked row.
    pub on_surface_variant: Color,
    /// An unchecked switch's track border and thumb.
    pub outline: Color,
    pub background: Color,
    /// A `ListHeader`'s label.
    pub on_background: Color,
    /// `LocalContentColor`, which `MaterialTheme` does not provide and which is
    /// therefore plain white unless an `AppScaffold` says otherwise. A bare
    /// `Text` in the list draws with this, **not** with `on_background`.
    pub content: Color,
    /// The scroll indicator's thumb: `onBackground` taken to L\* 80.
    ///
    /// Derive it with [`WearColors::with_wear_scroll_indicator`] rather than
    /// picking it — see that method for what Wear's own derivation is and why
    /// the obvious substitute for it is wrong.
    pub indicator_thumb: Color,
    /// The scroll indicator's track: the same colour at L\* 20.
    pub indicator_track: Color,
}

impl Default for WearColors {
    fn default() -> Self {
        Self {
            primary: Color::from_rgb_u8(0xA8, 0xC7, 0xFA),
            primary_container: Color::from_rgb_u8(0x0B, 0x57, 0xD0),
            on_primary: Color::from_rgb_u8(0x00, 0x00, 0x00),
            on_primary_container: Color::from_rgb_u8(0xD3, 0xE3, 0xFD),
            surface_container: Color::from_rgb_u8(0x1E, 0x1F, 0x20),
            on_surface: Color::from_rgb_u8(0xE3, 0xE3, 0xE3),
            on_surface_variant: Color::from_rgb_u8(0xC4, 0xC7, 0xC5),
            outline: Color::from_rgb_u8(0x8E, 0x91, 0x8F),
            background: Color::from_rgb_u8(0x00, 0x00, 0x00),
            on_background: Color::from_rgb_u8(0xE3, 0xE3, 0xE3),
            content: Color::WHITE,
            indicator_thumb: Color::WHITE,
            indicator_track: Color::WHITE,
        }
        .with_wear_scroll_indicator()
    }
}

impl WearColors {
    /// The two scroll-indicator colours Wear derives from this scheme's
    /// `on_background`.
    ///
    /// `ScrollIndicatorDefaults.colors()` reads one token and moves it to two
    /// lightnesses: `setLuminance(fromToken(OnBackground), 80f)` for the thumb
    /// and `setLuminance(..., 20f)` for the track. Nothing else feeds it — not
    /// `outline`, not an alpha over the background — and both come from
    /// `onBackground` rather than from `onSurface` or `primary`.
    ///
    /// The move itself is a **CAM16** round trip, not a CIE L\*a\*b\* one; see
    /// [`crate::widgets::wear::color_appearance::set_luminance`] for the two
    /// models' disagreement and why substituting L\* in Lab passes a check
    /// against the thumb and fails against the track.
    ///
    /// Overriding either afterwards is what
    /// `ScrollIndicatorDefaults.colors(indicatorColor, trackColor)` does: it
    /// copies over the derived pair.
    pub fn with_wear_scroll_indicator(mut self) -> Self {
        self.indicator_thumb = set_luminance(self.on_background, 80.0);
        self.indicator_track = set_luminance(self.on_background, 20.0);
        self
    }
}

/// Wear's `DefaultTextStyle` paragraph policy: no font padding, the leading
/// centred, nothing trimmed — and the font's own extent as a floor, which is
/// the part that makes a 16sp/18sp style lay out in 38 pixels rather than 36.
pub fn wear_line_height_style() -> LineHeightStyle {
    LineHeightStyle {
        alignment: LineHeightAlignment::Center,
        trim: LineHeightTrim::None,
        mode: LineHeightMode::Minimum,
    }
}

/// One of Wear Material 3's type-scale entries.
///
/// `size` and `line_height` are in sp; `tracking` is letter spacing in sp.
/// `weight` is both the `FontWeight` and the `wght` variation axis — the tokens
/// set them to the same number.
///
/// `align` is not part of Wear's type scale — every token leaves it unset and a
/// call site states it. It lives here anyway because the alternative is for
/// every caller to reach into the resolved [`TextStyle`]'s paragraph style and
/// overwrite one field, which is how a type scale stops being the thing that
/// describes the text.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct WearTextStyle {
    pub size_sp: f32,
    pub line_height_sp: f32,
    pub weight: u16,
    pub tracking_sp: f32,
    /// `TextAlign::Unspecified` on every scale entry, as in the tokens.
    pub align: TextAlign,
}

impl WearTextStyle {
    /// The family Wear's type scale resolves to on a real device.
    ///
    /// Wear's `TypefaceTokens.Brand` is `DeviceFontFamilyName("roboto-flex")`,
    /// and naming that here would be the faithful-looking answer and the wrong
    /// one. On the Wear OS 5 system image these widgets are measured against,
    /// `/system/etc/fonts.xml` declares a `roboto-flex` family whose every entry
    /// points at `RobotoFlex-Regular.ttf` — **a file the image does not ship**.
    /// A family whose files cannot be opened is dropped, so the token does not
    /// resolve and the platform falls back to `sans-serif`, which is Roboto.
    /// That is what the pixels show, and it is what this names.
    ///
    /// Naming a family at all is not optional. A `TextStyle` that leaves
    /// `font_family` as `None` only draws if some face happens to answer for the
    /// default, and an app that registers the system fonts under their own
    /// families — which is what a port matching Android's text has to do — has
    /// no such face. The text then measures, lays out and rasterises to nothing:
    /// a screen with correct geometry and no glyphs on it.
    pub const BRAND_FAMILY: FontFamily = FontFamily::SansSerif;

    /// `titleMedium` — what a `ListHeader` draws with.
    pub const TITLE_MEDIUM: Self = Self {
        size_sp: 16.0,
        line_height_sp: 18.0,
        weight: 550,
        tracking_sp: 0.4,
        align: TextAlign::Unspecified,
    };
    /// `labelMedium` — a `Button` label and a `SwitchButton` label.
    pub const LABEL_MEDIUM: Self = Self {
        size_sp: 15.0,
        line_height_sp: 18.0,
        weight: 500,
        tracking_sp: 0.4,
        align: TextAlign::Unspecified,
    };
    /// `labelSmall` — a secondary label.
    pub const LABEL_SMALL: Self = Self {
        size_sp: 13.0,
        line_height_sp: 16.0,
        weight: 500,
        tracking_sp: 0.4,
        align: TextAlign::Unspecified,
    };
    /// `bodyLarge` — the theme default, which a bare `Text` inherits. Note that
    /// a bare `Text` that overrides only its `fontSize` keeps **this** line
    /// height: a 12sp glyph in an 18sp line box is a real Wear screen, not a
    /// mistake to unify away.
    pub const BODY_LARGE: Self = Self {
        size_sp: 16.0,
        line_height_sp: 18.0,
        weight: 450,
        tracking_sp: 0.4,
        align: TextAlign::Unspecified,
    };

    /// The same style at another glyph size, keeping the line height.
    ///
    /// This is the shape of Wear's `Text(text, fontSize = 12.sp)` — an override
    /// of the size alone.
    pub const fn at_size(self, size_sp: f32) -> Self {
        Self { size_sp, ..self }
    }

    /// The same style with its line height stated outright.
    pub const fn with_line_height(self, line_height_sp: f32) -> Self {
        Self {
            line_height_sp,
            ..self
        }
    }

    /// The same style aligned in its own width.
    ///
    /// Wear's own `Text(text, textAlign = TextAlign.Center)` — the shape every
    /// credit line and every centred blurb on a watch screen takes.
    pub const fn aligned(self, align: TextAlign) -> Self {
        Self { align, ..self }
    }

    /// The Cranpose [`TextStyle`] this entry resolves to.
    ///
    /// The sizes stay in `Sp`, so the framework applies the user's text-size
    /// setting once, at measure time. Pre-scaling them here and handing the
    /// result to a `Text` would apply it twice.
    pub fn resolve(self, color: Color) -> TextStyle {
        self.resolve_in(color, Self::BRAND_FAMILY)
    }

    /// The same, drawn in a family the caller names.
    ///
    /// For a device whose `roboto-flex` really does resolve, or an app that
    /// registered Wear's brand face under a name of its own.
    pub fn resolve_in(self, color: Color, family: FontFamily) -> TextStyle {
        TextStyle {
            span_style: SpanStyle {
                color: Some(color),
                font_size: TextUnit::Sp(self.size_sp),
                font_weight: Some(FontWeight(self.weight)),
                letter_spacing: TextUnit::Sp(self.tracking_sp),
                font_family: Some(family),
                ..SpanStyle::default()
            },
            paragraph_style: ParagraphStyle {
                line_height: TextUnit::Sp(self.line_height_sp),
                text_align: self.align,
                line_height_style: Some(wear_line_height_style()),
                platform_style: Some(PlatformParagraphStyle {
                    include_font_padding: Some(false),
                    shaping: None,
                }),
                ..ParagraphStyle::default()
            },
        }
    }
}

#[cfg(test)]
#[path = "tests/theme_tests.rs"]
mod tests;