sqlly_datatable/grid/

theme.rs

//! `GridTheme` — typed color set used by the widget, plus the two shipped
//! theme families.
//!
//! Two complete families ship with the crate, each with a light and a dark
//! variant that follows the OS window appearance:
//!
//! - **Neutral** ([`GridThemePair::neutral`]) — chroma-free surfaces with a
//!   restrained azure accent. Blends into a host application; the default.
//! - **Signature** ([`GridThemePair::signature`]) — the crate's own look,
//!   built around a teal anchor (`oklch(0.47 0.115 195)`): tinted neutrals and
//!   a committed accent carrying selection, chips, and totals.
//!
//! Every color is a public field, so downstream code can construct a fully
//! custom theme (or derive one from a host app's palette) and pass it on the
//! [`crate::grid::GridState`] or via the widget builder. All shipped palettes
//! are designed in OKLCH (noted per field) and converted to `Hsla`; text
//! roles meet WCAG AA contrast (≥ 4.5:1) against every surface they are
//! painted on — see the `wcag` test module at the bottom of this file, which
//! verifies the full matrix for all four palettes.

use gpui::{Hsla, WindowAppearance};

#[derive(Clone, Debug, PartialEq)]
pub struct GridTheme {
    pub bg: Hsla,
    pub header_bg: Hsla,
    pub filter_bg: Hsla,
    pub filter_active_bg: Hsla,
    pub row_header_bg: Hsla,
    pub selection_bg: Hsla,
    pub alt_row_bg: Hsla,
    pub grid_line: Hsla,
    pub header_fg: Hsla,
    pub text_fg: Hsla,
    pub negative_fg: Hsla,
    pub sort_indicator: Hsla,
    pub filter_cursor: Hsla,
    /// Background fill of the right-click context menu / filter popup surface.
    pub menu_bg: Hsla,
    /// Fill drawn behind the menu item currently under the pointer (hover).
    pub menu_hover_bg: Hsla,
    /// Foreground color for menu item labels.
    pub menu_fg: Hsla,
    /// Muted text color for labels, placeholders, and secondary text inside
    /// the filter panel and context menu. Chosen for legibility against
    /// `menu_bg` / `bg` in both light and dark palettes.
    pub muted_text: Hsla,
    /// Foreground for the null-value placeholder (see
    /// [`crate::config::NullFormat`]).
    pub null_fg: Hsla,
    /// Distinctive background painted behind null-value cells when the
    /// column's [`crate::config::NullFormat::background`] is enabled.
    pub null_bg: Hsla,
    /// Background of pivot group-header rows (expanded groups).
    pub pivot_group_bg: Hsla,
    /// Background of pivot subtotal cells (collapsed groups, "Total"
    /// columns).
    pub pivot_subtotal_bg: Hsla,
    /// Background of the pivot grand-total row/column.
    pub pivot_grand_total_bg: Hsla,
    /// Foreground for pivot subtotal / grand-total values and labels.
    pub pivot_total_fg: Hsla,
    /// Resting background of a sidebar drop zone.
    pub pivot_drop_zone_bg: Hsla,
    /// Background of a drop zone while a compatible chip hovers over it.
    pub pivot_drop_zone_active_bg: Hsla,
    /// Background of a field chip in the pivot sidebar.
    pub pivot_chip_bg: Hsla,
    /// Label color of a field chip in the pivot sidebar.
    pub pivot_chip_fg: Hsla,
    /// Fill of the scrollbar thumb (the track uses `row_header_bg`). Kept at
    /// ≥ 3:1 contrast against the track in the shipped palettes.
    pub scrollbar_thumb: Hsla,
    /// Translucent scrim painted behind modal overlays (e.g. the pivot
    /// format dialog) to dim the content beneath. The only intentionally
    /// non-opaque color in the theme.
    pub overlay_scrim: Hsla,
}

impl Default for GridTheme {
    fn default() -> Self {
        Self::neutral_light()
    }
}

fn hsla(h: f32, s: f32, l: f32, a: f32) -> Hsla {
    Hsla { h, s, l, a }
}

/// A light/dark pair forming one theme family. [`GridThemePair::for_appearance`]
/// picks the variant matching the OS window appearance, so a host app can
/// supply its own pair and keep automatic light/dark following.
#[derive(Clone, Debug, PartialEq)]
pub struct GridThemePair {
    pub light: GridTheme,
    pub dark: GridTheme,
}

impl Default for GridThemePair {
    fn default() -> Self {
        Self::neutral()
    }
}

impl GridThemePair {
    /// The Neutral family: chroma-free surfaces, one restrained azure accent.
    #[must_use]
    pub fn neutral() -> Self {
        Self {
            light: GridTheme::neutral_light(),
            dark: GridTheme::neutral_dark(),
        }
    }

    /// The Signature family: teal-anchored tinted neutrals with a committed
    /// accent.
    #[must_use]
    pub fn signature() -> Self {
        Self {
            light: GridTheme::signature_light(),
            dark: GridTheme::signature_dark(),
        }
    }

    /// Pick the variant that matches the OS window appearance. `Dark` and
    /// `VibrantDark` resolve to `self.dark`; everything else to `self.light`.
    #[must_use]
    pub fn for_appearance(&self, appearance: WindowAppearance) -> GridTheme {
        match appearance {
            WindowAppearance::Dark | WindowAppearance::VibrantDark => self.dark.clone(),
            WindowAppearance::Light | WindowAppearance::VibrantLight => self.light.clone(),
        }
    }
}

impl GridTheme {
    /// Neutral light: pure-white canvas, gray ramp at zero chroma, azure
    /// accent reserved for selection, sort, and filter state.
    #[must_use]
    pub fn neutral_light() -> Self {
        Self {
            bg: hsla(0.0, 0.0, 1.0, 1.0),                            // oklch(1 0 0)
            header_bg: hsla(0.0, 0.0, 0.941, 1.0),                   // oklch(0.955 0 0)
            filter_bg: hsla(0.0, 0.0, 0.941, 1.0),                   // oklch(0.955 0 0)
            filter_active_bg: hsla(0.5778, 1.0, 0.8778, 1.0),        // oklch(0.90 0.06 250)
            row_header_bg: hsla(0.0, 0.0, 0.9215, 1.0),              // oklch(0.94 0 0)
            selection_bg: hsla(0.5786, 1.0, 0.8972, 1.0),            // oklch(0.915 0.05 250)
            alt_row_bg: hsla(0.0, 0.0, 0.9632, 1.0),                 // oklch(0.972 0 0)
            grid_line: hsla(0.0, 0.0, 0.8634, 1.0),                  // oklch(0.895 0 0)
            header_fg: hsla(0.0, 0.0, 0.1599, 1.0),                  // oklch(0.28 0 0)
            text_fg: hsla(0.0, 0.0, 0.0476, 1.0),                    // oklch(0.155 0 0)
            negative_fg: hsla(0.9991, 0.7103, 0.4152, 1.0),          // oklch(0.50 0.185 27)
            sort_indicator: hsla(0.5763, 1.0, 0.3224, 1.0),          // oklch(0.46 0.145 250)
            filter_cursor: hsla(0.0, 0.0, 0.0476, 1.0),              // oklch(0.155 0 0)
            menu_bg: hsla(0.0, 0.0, 1.0, 1.0),                       // oklch(1 0 0)
            menu_hover_bg: hsla(0.5798, 1.0, 0.9166, 1.0),           // oklch(0.93 0.04 250)
            menu_fg: hsla(0.0, 0.0, 0.0476, 1.0),                    // oklch(0.155 0 0)
            muted_text: hsla(0.0, 0.0, 0.3447, 1.0),                 // oklch(0.46 0 0)
            null_fg: hsla(0.1215, 0.0996, 0.3291, 1.0),              // oklch(0.46 0.02 90)
            null_bg: hsla(0.1324, 0.7485, 0.9213, 1.0),              // oklch(0.965 0.032 95)
            pivot_group_bg: hsla(0.5863, 0.7823, 0.9366, 1.0),       // oklch(0.945 0.022 250)
            pivot_subtotal_bg: hsla(0.5862, 0.724, 0.9011, 1.0),     // oklch(0.915 0.032 250)
            pivot_grand_total_bg: hsla(0.5858, 0.7776, 0.8434, 1.0), // oklch(0.865 0.055 250)
            pivot_total_fg: hsla(0.585, 0.4177, 0.0724, 1.0),        // oklch(0.18 0.02 250)
            pivot_drop_zone_bg: hsla(0.0, 0.0, 0.954, 1.0),          // oklch(0.965 0 0)
            pivot_drop_zone_active_bg: hsla(0.5756, 1.0, 0.9004, 1.0), // oklch(0.92 0.05 250)
            pivot_chip_bg: hsla(0.5798, 1.0, 0.9166, 1.0),           // oklch(0.93 0.04 250)
            pivot_chip_fg: hsla(0.5844, 0.4223, 0.1374, 1.0),        // oklch(0.25 0.035 250)
            scrollbar_thumb: hsla(0.0, 0.0, 0.5021, 1.0),            // oklch(0.60 0 0)
            overlay_scrim: hsla(0.0, 0.0, 0.0, 0.35),
        }
    }

    /// Neutral dark: near-black gray ramp; depth comes from surface
    /// lightness, accents are slightly desaturated to sit on dark.
    #[must_use]
    pub fn neutral_dark() -> Self {
        Self {
            bg: hsla(0.0, 0.0, 0.0817, 1.0),        // oklch(0.195 0 0)
            header_bg: hsla(0.0, 0.0, 0.1409, 1.0), // oklch(0.26 0 0)
            filter_bg: hsla(0.0, 0.0, 0.1409, 1.0), // oklch(0.26 0 0)
            filter_active_bg: hsla(0.583, 0.4915, 0.2685, 1.0), // oklch(0.38 0.07 250)
            row_header_bg: hsla(0.0, 0.0, 0.1268, 1.0), // oklch(0.245 0 0)
            selection_bg: hsla(0.5823, 0.5446, 0.2618, 1.0), // oklch(0.375 0.075 250)
            alt_row_bg: hsla(0.0, 0.0, 0.1085, 1.0), // oklch(0.225 0 0)
            grid_line: hsla(0.0, 0.0, 0.2089, 1.0), // oklch(0.33 0 0)
            header_fg: hsla(0.0, 0.0, 0.806, 1.0),  // oklch(0.85 0 0)
            text_fg: hsla(0.0, 0.0, 0.9085, 1.0),   // oklch(0.93 0 0)
            negative_fg: hsla(0.0076, 0.8612, 0.6827, 1.0), // oklch(0.70 0.165 25)
            sort_indicator: hsla(0.5751, 0.8029, 0.6722, 1.0), // oklch(0.74 0.115 245)
            filter_cursor: hsla(0.0, 0.0, 0.9085, 1.0), // oklch(0.93 0 0)
            menu_bg: hsla(0.0, 0.0, 0.1315, 1.0),   // oklch(0.25 0 0)
            menu_hover_bg: hsla(0.5834, 0.4685, 0.2583, 1.0), // oklch(0.37 0.065 250)
            menu_fg: hsla(0.0, 0.0, 0.9085, 1.0),   // oklch(0.93 0 0)
            muted_text: hsla(0.0, 0.0, 0.6326, 1.0), // oklch(0.71 0 0)
            null_fg: hsla(0.132, 0.2549, 0.6858, 1.0), // oklch(0.79 0.045 95)
            null_bg: hsla(0.1318, 0.3896, 0.1459, 1.0), // oklch(0.30 0.038 95)
            pivot_group_bg: hsla(0.5853, 0.2639, 0.1806, 1.0), // oklch(0.295 0.028 250)
            pivot_subtotal_bg: hsla(0.5847, 0.3421, 0.2171, 1.0), // oklch(0.33 0.042 250)
            pivot_grand_total_bg: hsla(0.584, 0.3998, 0.2911, 1.0), // oklch(0.40 0.062 250)
            pivot_total_fg: hsla(0.0, 0.0, 0.941, 1.0), // oklch(0.955 0 0)
            pivot_drop_zone_bg: hsla(0.0, 0.0, 0.1268, 1.0), // oklch(0.245 0 0)
            pivot_drop_zone_active_bg: hsla(0.5835, 0.4628, 0.2375, 1.0), // oklch(0.35 0.06 250)
            pivot_chip_bg: hsla(0.584, 0.4202, 0.2379, 1.0), // oklch(0.35 0.055 250)
            pivot_chip_fg: hsla(0.0, 0.0, 0.9345, 1.0), // oklch(0.95 0 0)
            scrollbar_thumb: hsla(0.0, 0.0, 0.4447, 1.0), // oklch(0.55 0 0)
            overlay_scrim: hsla(0.0, 0.0, 0.0, 0.45),
        }
    }

    /// Signature light: pure-white canvas with teal-tinted neutrals; the
    /// teal anchor (`oklch(0.47 0.115 195)` family) carries selection,
    /// chips, and the totals hierarchy.
    #[must_use]
    pub fn signature_light() -> Self {
        Self {
            bg: hsla(0.0, 0.0, 1.0, 1.0),                            // oklch(1 0 0)
            header_bg: hsla(0.4955, 0.2665, 0.917, 1.0),             // oklch(0.945 0.012 195)
            filter_bg: hsla(0.4955, 0.2665, 0.917, 1.0),             // oklch(0.945 0.012 195)
            filter_active_bg: hsla(0.4978, 0.5936, 0.7861, 1.0),     // oklch(0.89 0.065 195)
            row_header_bg: hsla(0.4956, 0.2469, 0.8956, 1.0),        // oklch(0.93 0.014 195)
            selection_bg: hsla(0.497, 0.5728, 0.8399, 1.0),          // oklch(0.915 0.048 195)
            alt_row_bg: hsla(0.4952, 0.2997, 0.9568, 1.0),           // oklch(0.972 0.007 195)
            grid_line: hsla(0.4957, 0.1778, 0.8359, 1.0),            // oklch(0.885 0.016 195)
            header_fg: hsla(0.5, 0.6775, 0.1233, 1.0),               // oklch(0.30 0.045 195)
            text_fg: hsla(0.4982, 0.397, 0.0491, 1.0),               // oklch(0.17 0.015 195)
            negative_fg: hsla(0.015, 0.7339, 0.4008, 1.0),           // oklch(0.50 0.175 30)
            sort_indicator: hsla(0.502, 1.0, 0.217, 1.0),            // oklch(0.47 0.115 195)
            filter_cursor: hsla(0.4982, 0.397, 0.0491, 1.0),         // oklch(0.17 0.015 195)
            menu_bg: hsla(0.0, 0.0, 1.0, 1.0),                       // oklch(1 0 0)
            menu_hover_bg: hsla(0.4968, 0.5969, 0.8663, 1.0),        // oklch(0.93 0.042 195)
            menu_fg: hsla(0.4982, 0.397, 0.0491, 1.0),               // oklch(0.17 0.015 195)
            muted_text: hsla(0.4975, 0.1546, 0.3177, 1.0),           // oklch(0.46 0.03 195)
            null_fg: hsla(0.1119, 0.1325, 0.3271, 1.0),              // oklch(0.46 0.025 85)
            null_bg: hsla(0.1176, 0.7869, 0.9237, 1.0),              // oklch(0.962 0.03 88)
            pivot_group_bg: hsla(0.4962, 0.5099, 0.8971, 1.0),       // oklch(0.942 0.028 195)
            pivot_subtotal_bg: hsla(0.4969, 0.5164, 0.8345, 1.0),    // oklch(0.908 0.045 195)
            pivot_grand_total_bg: hsla(0.4983, 0.5319, 0.7204, 1.0), // oklch(0.85 0.075 195)
            pivot_total_fg: hsla(0.5035, 1.0, 0.0689, 1.0),          // oklch(0.22 0.06 195)
            pivot_drop_zone_bg: hsla(0.4953, 0.2775, 0.9468, 1.0),   // oklch(0.965 0.008 195)
            pivot_drop_zone_active_bg: hsla(0.4974, 0.6519, 0.8275, 1.0), // oklch(0.915 0.058 195)
            pivot_chip_bg: hsla(0.4973, 0.5837, 0.8185, 1.0),        // oklch(0.905 0.055 195)
            pivot_chip_fg: hsla(0.503, 1.0, 0.1024, 1.0),            // oklch(0.28 0.075 195)
            scrollbar_thumb: hsla(0.4975, 0.1513, 0.4634, 1.0),      // oklch(0.60 0.04 195)
            overlay_scrim: hsla(0.5019, 1.0, 0.0092, 0.35),          // oklch(0.10 0.02 195)
        }
    }

    /// Signature dark: teal-tinted near-black; surfaces keep the anchor hue
    /// at whisper chroma, and the accent brightens to hold on dark.
    #[must_use]
    pub fn signature_dark() -> Self {
        Self {
            bg: hsla(0.4974, 0.2284, 0.0687, 1.0), // oklch(0.19 0.012 195)
            header_bg: hsla(0.4977, 0.2102, 0.1219, 1.0), // oklch(0.255 0.018 195)
            filter_bg: hsla(0.4977, 0.2102, 0.1219, 1.0), // oklch(0.255 0.018 195)
            filter_active_bg: hsla(0.5016, 1.0, 0.1547, 1.0), // oklch(0.375 0.085 195)
            row_header_bg: hsla(0.4976, 0.2111, 0.1053, 1.0), // oklch(0.235 0.016 195)
            selection_bg: hsla(0.5016, 1.0, 0.1547, 1.0), // oklch(0.375 0.085 195)
            alt_row_bg: hsla(0.4975, 0.207, 0.0917, 1.0), // oklch(0.218 0.014 195)
            grid_line: hsla(0.4975, 0.1743, 0.1906, 1.0), // oklch(0.33 0.022 195)
            header_fg: hsla(0.4959, 0.1709, 0.7876, 1.0), // oklch(0.85 0.02 195)
            text_fg: hsla(0.4953, 0.1483, 0.9013, 1.0), // oklch(0.93 0.008 195)
            negative_fg: hsla(0.0092, 0.8161, 0.6929, 1.0), // oklch(0.71 0.15 25)
            sort_indicator: hsla(0.5, 0.5555, 0.5112, 1.0), // oklch(0.76 0.115 195)
            filter_cursor: hsla(0.4953, 0.1483, 0.9013, 1.0), // oklch(0.93 0.008 195)
            menu_bg: hsla(0.4975, 0.1954, 0.1145, 1.0), // oklch(0.245 0.016 195)
            menu_hover_bg: hsla(0.5011, 1.0, 0.1462, 1.0), // oklch(0.365 0.075 195)
            menu_fg: hsla(0.4953, 0.1483, 0.9013, 1.0), // oklch(0.93 0.008 195)
            muted_text: hsla(0.4965, 0.1256, 0.6067, 1.0), // oklch(0.71 0.028 195)
            null_fg: hsla(0.1175, 0.3234, 0.6993, 1.0), // oklch(0.80 0.05 88)
            null_bg: hsla(0.1183, 0.3763, 0.1477, 1.0), // oklch(0.295 0.035 88)
            pivot_group_bg: hsla(0.4992, 0.4103, 0.1392, 1.0), // oklch(0.295 0.035 195)
            pivot_subtotal_bg: hsla(0.5, 0.6646, 0.1444, 1.0), // oklch(0.33 0.05 195)
            pivot_grand_total_bg: hsla(0.5005, 1.0, 0.164, 1.0), // oklch(0.40 0.072 195)
            pivot_total_fg: hsla(0.4952, 0.1907, 0.9421, 1.0), // oklch(0.96 0.006 195)
            pivot_drop_zone_bg: hsla(0.4975, 0.2029, 0.1099, 1.0), // oklch(0.24 0.016 195)
            pivot_drop_zone_active_bg: hsla(0.5009, 1.0, 0.1335, 1.0), // oklch(0.345 0.068 195)
            pivot_chip_bg: hsla(0.5013, 1.0, 0.1383, 1.0), // oklch(0.35 0.075 195)
            pivot_chip_fg: hsla(0.4954, 0.2469, 0.9254, 1.0), // oklch(0.95 0.01 195)
            scrollbar_thumb: hsla(0.4967, 0.0942, 0.4236, 1.0), // oklch(0.55 0.024 195)
            overlay_scrim: hsla(0.5019, 1.0, 0.0011, 0.45), // oklch(0.05 0.01 195)
        }
    }

    /// The Neutral light palette. Identical to [`GridTheme::default`];
    /// provided as a named constructor so callers can be explicit about
    /// intent.
    #[must_use]
    pub fn light() -> Self {
        Self::neutral_light()
    }

    /// The Neutral dark palette, tuned to pair with [`GridTheme::light`].
    #[must_use]
    pub fn dark() -> Self {
        Self::neutral_dark()
    }

    /// Pick the Neutral-family palette that matches the OS window
    /// appearance. `Dark` and `VibrantDark` resolve to
    /// [`GridTheme::neutral_dark`]; everything else to
    /// [`GridTheme::neutral_light`]. For other families use
    /// [`GridThemePair::for_appearance`].
    #[must_use]
    pub fn for_appearance(appearance: WindowAppearance) -> Self {
        GridThemePair::neutral().for_appearance(appearance)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn all_palettes() -> [(&'static str, GridTheme); 4] {
        [
            ("neutral_light", GridTheme::neutral_light()),
            ("neutral_dark", GridTheme::neutral_dark()),
            ("signature_light", GridTheme::signature_light()),
            ("signature_dark", GridTheme::signature_dark()),
        ]
    }

    /// The context menu must be paintable from the theme (not a hardcoded
    /// color), and its hover fill must be visually distinct from the menu
    /// background so a mouse-over state is actually perceivable. The label
    /// color must also contrast with the background. This guards the
    /// dark/light theming + hover-state regression, for every shipped
    /// palette.
    #[test]
    fn every_palette_exposes_distinct_menu_colors() {
        for (name, t) in all_palettes() {
            // Menu surface must be opaque so it fully covers content beneath.
            assert_eq!(t.menu_bg.a, 1.0, "{name}: menu background must be opaque");
            assert_ne!(
                t.menu_hover_bg, t.menu_bg,
                "{name}: menu hover fill must differ from the menu background"
            );
            assert_ne!(
                t.menu_fg, t.menu_bg,
                "{name}: menu label color must contrast with the menu background"
            );
        }
    }

    /// `light()`/`default()` must equal the Neutral light palette, `dark()`
    /// the Neutral dark palette, and dark variants must be genuinely dark
    /// (light text on a dark surface). This guards the OS light/dark
    /// following and the back-compat aliases.
    #[test]
    fn aliases_and_dark_variants_hold() {
        assert_eq!(
            GridTheme::light(),
            GridTheme::default(),
            "light() must alias the default palette"
        );
        assert_eq!(GridTheme::light(), GridTheme::neutral_light());
        assert_eq!(GridTheme::dark(), GridTheme::neutral_dark());
        for (name, t) in [
            ("neutral_dark", GridTheme::neutral_dark()),
            ("signature_dark", GridTheme::signature_dark()),
        ] {
            assert!(
                t.bg.l < t.text_fg.l,
                "{name} must be light text on a dark surface"
            );
        }
        for (name, t) in all_palettes() {
            assert_eq!(t.bg.a, 1.0, "{name}: grid background must be opaque");
            assert_eq!(t.selection_bg.a, 1.0, "{name}: selection must be opaque");
        }
    }

    /// Pivot surfaces must be mutually distinguishable and legible in every
    /// palette: totals must stand out from ordinary groups, drop-zone hover
    /// must differ from its resting state, and total text must contrast
    /// with the total background.
    #[test]
    fn pivot_surfaces_are_distinct_in_every_palette() {
        for (name, t) in all_palettes() {
            assert_ne!(t.pivot_grand_total_bg, t.pivot_group_bg, "{name}");
            assert_ne!(t.pivot_grand_total_bg, t.pivot_subtotal_bg, "{name}");
            assert_ne!(t.pivot_total_fg, t.pivot_grand_total_bg, "{name}");
            assert_ne!(t.pivot_drop_zone_active_bg, t.pivot_drop_zone_bg, "{name}");
            assert_ne!(t.pivot_chip_fg, t.pivot_chip_bg, "{name}");
        }
    }

    /// `for_appearance` must map the two dark variants to the dark palette
    /// and the two light variants to the light palette, on both the static
    /// Neutral helper and an arbitrary pair.
    #[test]
    fn for_appearance_maps_dark_and_light_variants() {
        assert_eq!(
            GridTheme::for_appearance(WindowAppearance::Dark).bg,
            GridTheme::dark().bg
        );
        assert_eq!(
            GridTheme::for_appearance(WindowAppearance::VibrantDark).bg,
            GridTheme::dark().bg
        );
        assert_eq!(
            GridTheme::for_appearance(WindowAppearance::Light).bg,
            GridTheme::light().bg
        );
        assert_eq!(
            GridTheme::for_appearance(WindowAppearance::VibrantLight).bg,
            GridTheme::light().bg
        );
        let sig = GridThemePair::signature();
        assert_eq!(
            sig.for_appearance(WindowAppearance::Dark).bg,
            GridTheme::signature_dark().bg
        );
        assert_eq!(
            sig.for_appearance(WindowAppearance::VibrantLight).bg,
            GridTheme::signature_light().bg
        );
    }
}

/// WCAG contrast verification for the shipped palettes. Every text role is
/// checked against every surface it is actually painted on in `paint.rs` /
/// `sidebar.rs` / `widget.rs`, at AA thresholds (4.5:1 for text, 3:1 for
/// UI indicators), plus perceivable-difference floors for state fills.
#[cfg(test)]
mod wcag {
    use super::*;

    /// Convert an `Hsla` (alpha ignored — all checked colors are opaque,
    /// guarded by `aliases_and_dark_variants_hold`) to linear-light sRGB
    /// relative luminance.
    fn relative_luminance(c: Hsla) -> f32 {
        // HSL -> sRGB
        let (h, s, l) = (c.h, c.s, c.l);
        let q = if l < 0.5 {
            l * (1.0 + s)
        } else {
            l + s - l * s
        };
        let p = 2.0 * l - q;
        let hue = |mut t: f32| -> f32 {
            if t < 0.0 {
                t += 1.0;
            }
            if t > 1.0 {
                t -= 1.0;
            }
            if t < 1.0 / 6.0 {
                p + (q - p) * 6.0 * t
            } else if t < 0.5 {
                q
            } else if t < 2.0 / 3.0 {
                p + (q - p) * (2.0 / 3.0 - t) * 6.0
            } else {
                p
            }
        };
        let (r, g, b) = (hue(h + 1.0 / 3.0), hue(h), hue(h - 1.0 / 3.0));
        // gamma -> linear
        let lin = |u: f32| -> f32 {
            if u <= 0.04045 {
                u / 12.92
            } else {
                ((u + 0.055) / 1.055).powf(2.4)
            }
        };
        0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
    }

    fn contrast(a: Hsla, b: Hsla) -> f32 {
        let (la, lb) = (relative_luminance(a), relative_luminance(b));
        let (hi, lo) = if la > lb { (la, lb) } else { (lb, la) };
        (hi + 0.05) / (lo + 0.05)
    }

    /// (foreground field, background field, minimum ratio, painted where)
    fn requirements(t: &GridTheme) -> Vec<(Hsla, Hsla, f32, &'static str)> {
        vec![
            (t.text_fg, t.bg, 7.0, "body text on bg"),
            (t.text_fg, t.alt_row_bg, 7.0, "body text on zebra row"),
            (t.text_fg, t.selection_bg, 4.5, "body text on selection"),
            (t.text_fg, t.row_header_bg, 4.5, "pivot leaf label"),
            (t.text_fg, t.header_bg, 4.5, "status bar text"),
            (t.text_fg, t.filter_active_bg, 4.5, "filter text"),
            (t.header_fg, t.header_bg, 4.5, "column labels"),
            (t.header_fg, t.row_header_bg, 4.5, "row numbers"),
            (t.header_fg, t.selection_bg, 4.5, "selected header label"),
            (
                t.header_fg,
                t.pivot_grand_total_bg,
                4.5,
                "pivot header on total bg",
            ),
            (t.muted_text, t.bg, 4.5, "placeholder text on bg"),
            (t.muted_text, t.menu_bg, 4.5, "menu secondary text"),
            (t.muted_text, t.header_bg, 4.5, "sidebar header hint"),
            (t.muted_text, t.pivot_drop_zone_bg, 4.5, "drop zone hint"),
            (t.negative_fg, t.bg, 4.5, "negative numbers on bg"),
            (
                t.negative_fg,
                t.alt_row_bg,
                4.5,
                "negative numbers on zebra",
            ),
            (
                t.negative_fg,
                t.selection_bg,
                3.0,
                "negative on selection (parentheses carry the channel too)",
            ),
            (t.negative_fg, t.pivot_grand_total_bg, 3.0, "negative total"),
            (t.menu_fg, t.menu_bg, 7.0, "menu labels"),
            (t.menu_fg, t.menu_hover_bg, 4.5, "hovered menu label"),
            (
                t.menu_fg,
                t.pivot_drop_zone_bg,
                4.5,
                "pivot menu on zone bg",
            ),
            (t.null_fg, t.bg, 4.5, "null placeholder on bg"),
            (t.null_fg, t.null_bg, 4.5, "null placeholder on null bg"),
            (t.null_fg, t.alt_row_bg, 4.5, "null placeholder on zebra"),
            (
                t.pivot_total_fg,
                t.pivot_group_bg,
                7.0,
                "group header label",
            ),
            (
                t.pivot_total_fg,
                t.pivot_subtotal_bg,
                4.5,
                "subtotal values",
            ),
            (
                t.pivot_total_fg,
                t.pivot_grand_total_bg,
                4.5,
                "grand total values",
            ),
            (t.pivot_chip_fg, t.pivot_chip_bg, 4.5, "chip labels"),
            (t.sort_indicator, t.header_bg, 3.0, "sort glyph"),
            (t.sort_indicator, t.menu_bg, 4.5, "sidebar sort glyph"),
            (t.sort_indicator, t.bg, 3.0, "grouped-column underline"),
            (t.filter_cursor, t.filter_active_bg, 4.5, "filter cursor"),
            (t.scrollbar_thumb, t.row_header_bg, 3.0, "thumb vs track"),
        ]
    }

    /// State fills must be perceivably different from what they replace.
    fn distinctness(t: &GridTheme) -> Vec<(Hsla, Hsla, f32, &'static str)> {
        vec![
            (t.selection_bg, t.bg, 1.1, "selection visible on bg"),
            (t.alt_row_bg, t.bg, 1.02, "zebra visible"),
            (t.menu_hover_bg, t.menu_bg, 1.1, "menu hover visible"),
            (
                t.pivot_drop_zone_active_bg,
                t.pivot_drop_zone_bg,
                1.1,
                "drop-zone hover visible",
            ),
            (t.grid_line, t.bg, 1.1, "grid lines visible"),
            (
                t.pivot_grand_total_bg,
                t.pivot_subtotal_bg,
                1.05,
                "totals hierarchy readable",
            ),
        ]
    }

    #[test]
    fn every_palette_meets_wcag_contrast() {
        for (name, theme) in [
            ("neutral_light", GridTheme::neutral_light()),
            ("neutral_dark", GridTheme::neutral_dark()),
            ("signature_light", GridTheme::signature_light()),
            ("signature_dark", GridTheme::signature_dark()),
        ] {
            for (fg, bg, min, what) in requirements(&theme).into_iter().chain(distinctness(&theme))
            {
                let ratio = contrast(fg, bg);
                assert!(
                    ratio >= min,
                    "{name}: {what} — contrast {ratio:.2} below required {min}"
                );
            }
        }
    }
}