vampir 0.4.1

Lit widget toolkit for GPUI: buttons, fields, pop-ups, menus and a text input, over a small OKLCH palette.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
//! The colours the controls draw with.
//!
//! [`Palette`] is deliberately small: roughly twenty colours, all of them
//! things a control actually paints. A host with its own richer theme fills
//! one in from that theme; a host without one calls
//! [`Palette::from_hue_and_saturation`] with the app's chosen colours.

use gpui::Rgba;

use crate::color::{TRANSPARENT, WHITE, argb, oklch_to_color};

/// The toolkit's original pastel chroma, unchanged by the saturation gain.
pub const DEFAULT_SATURATION: f64 = 1.0;
/// The upper theme intensity; surfaces and controls use different chroma gains.
pub const MAX_SATURATION: f64 = 3.0;

pub(crate) fn normalized_saturation(saturation: f64) -> f64 {
    if saturation.is_nan() {
        DEFAULT_SATURATION
    } else {
        saturation.clamp(0.0, MAX_SATURATION)
    }
}

/// Colours for one colour scheme at one hue.
///
/// `Copy`, and cheap enough to build per frame, so a host can hand controls
/// a freshly derived palette during a theme cross-fade without caching.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Palette {
    /// Drives shadow and highlight strength throughout [`crate::lighting`]:
    /// dark schemes are lit with white highlights, light ones with shadow.
    pub is_dark: bool,

    /// The one saturated colour: focus rings, the switch's on state, slider
    /// fills, an open pop-up's border.
    pub accent: Rgba,

    /// The window's own ground, behind every panel. Barely tinted toward the
    /// hue, so a panel reads as sitting on it rather than floating in grey.
    /// [`crate::lighting::ground`] lights it.
    pub backdrop: Rgba,

    /// Body text, and the text inside fields.
    pub text_primary: Rgba,
    /// Captions, step glyphs, scrollbar thumbs. Quieter than primary.
    pub text_secondary: Rgba,

    /// Inside of a single-line field, and the switch knob and slider handle.
    pub field_surface: Rgba,
    /// A field's resting border, and the slider's unfilled track.
    pub field_border: Rgba,
    /// Firmer border for the small round parts that need to read against a
    /// light surface: the switch knob, the slider handle.
    pub field_border_strong: Rgba,

    /// Inside of a multi-line text area. Often the same as `field_surface`;
    /// separate because areas sit on a different panel in some layouts.
    pub area_surface: Rgba,
    /// A text area's resting border.
    pub area_border: Rgba,

    /// Hover wash behind an unselected row in a pop-up list.
    pub row_hover: Rgba,

    /// The accent-tinted control fill: the pop-up's chevron chip, and the
    /// highlighted row in its list.
    pub control_fill: Rgba,
    /// Label and chevron colour on `control_fill`.
    pub control_label: Rgba,

    /// Secondary button: tinted, not flat grey.
    pub soft_fill: Rgba,
    pub soft_fill_hover: Rgba,
    pub soft_label: Rgba,

    /// The single call to action in a group.
    pub primary_fill: Rgba,
    pub primary_fill_hover: Rgba,
    pub primary_label: Rgba,

    /// Destructive action: tinted red, still a button rather than a warning.
    pub danger_fill: Rgba,
    pub danger_fill_hover: Rgba,
    pub danger_label: Rgba,
}

impl Palette {
    /// The whole palette from one hue in degrees and a light/dark flag.
    ///
    /// Chroma stays inside a soft range, so every hue lands as a pastel of
    /// the same intensity and a hue slider never sends the UI garish.
    pub fn from_hue(hue: f64, dark: bool) -> Self {
        Self::from_hue_and_saturation(hue, DEFAULT_SATURATION, dark)
    }

    /// The palette with a gain on the roles' OKLCH chroma, including
    /// destructive colors: `0` is grayscale, `1` the original pastels, and
    /// `3` the vividness limit. Above one, controls gain colour gently while
    /// background surfaces gain more, including a tint on light panels.
    /// Values outside `0..=3` are clamped; NaN uses [`DEFAULT_SATURATION`].
    pub fn from_hue_and_saturation(hue: f64, saturation: f64, dark: bool) -> Self {
        let saturation = normalized_saturation(saturation);
        // Here rather than only where a colour is made: the roles offset the
        // hue, and a hue that is not a number has to be one hue for all of them.
        let hue = if hue.is_finite() { hue } else { 0.0 };
        // Strong fills reach the sRGB boundary quickly; spend the extra
        // intensity on the quieter surfaces instead of clipping every button.
        let control_gain = saturation.min(1.0) + (saturation - 1.0).max(0.0) * 0.35;
        let surface_gain = saturation.min(1.0) + (saturation - 1.0).max(0.0) * 1.25;
        let color = |l: f64, c: f64, h: f64| oklch_to_color(l, c * control_gain, h);
        let surface = |l: f64, c: f64, h: f64| oklch_to_color(l, c * surface_gain, h);
        let light_surface = if saturation > 1.0 {
            oklch_to_color(
                1.0 - 0.012 * (saturation - 1.0),
                0.012 * (saturation - 1.0),
                hue - 2.0,
            )
        } else {
            WHITE
        };
        let pastel = |l: f64, c: f64, dh: f64| color(l, c.clamp(0.0, 0.16), hue + dh);
        let pick =
            |dark_color: Rgba, light_color: Rgba| if dark { dark_color } else { light_color };

        let accent = pick(pastel(0.78, 0.105, 0.0), pastel(0.62, 0.105, 0.0));
        let selection = pick(pastel(0.84, 0.125, 12.0), pastel(0.68, 0.125, 12.0));
        let control_fill = pick(color(0.36, 0.06, hue), accent);
        let control_fill_hover = pick(color(0.44, 0.08, hue + 4.0), selection);
        let control_label = pick(pastel(0.97, 0.006, 0.0), WHITE);
        let border = pick(pastel(0.33, 0.016, 0.0), pastel(0.86, 0.014, 0.0));
        let text_primary = pick(pastel(0.95, 0.010, 0.0), pastel(0.24, 0.018, 0.0));

        Self {
            is_dark: dark,
            accent,
            backdrop: pick(surface(0.285, 0.012, hue), surface(0.955, 0.012, hue)),

            text_primary,
            text_secondary: pick(pastel(0.86, 0.015, 0.0), pastel(0.36, 0.015, 0.0)),

            field_surface: pick(surface(0.20, 0.014, hue - 2.0), light_surface),
            field_border: pick(pastel(0.35, 0.016, 0.0), pastel(0.87, 0.014, 0.0)),
            field_border_strong: pick(color(0.48, 0.060, hue), pastel(0.72, 0.065, 0.0)),

            area_surface: pick(surface(0.26, 0.016, hue - 2.0), light_surface),
            area_border: pick(border, pastel(0.84, 0.018, 0.0)),

            row_hover: pick(pastel(0.28, 0.025, -2.0), pastel(0.87, 0.018, -2.0)),

            control_fill,
            control_label,

            soft_fill: pick(color(0.36, 0.06, hue), pastel(0.90, 0.048, 0.0)),
            soft_fill_hover: pick(color(0.44, 0.08, hue + 4.0), pastel(0.84, 0.058, 0.0)),
            soft_label: pick(control_label, pastel(0.26, 0.040, 0.0)),

            primary_fill: pick(control_fill, pastel(0.70, 0.095, 0.0)),
            primary_fill_hover: pick(control_fill_hover, pastel(0.64, 0.105, 0.0)),
            primary_label: pick(control_label, WHITE),

            danger_fill: pick(color(0.38, 0.07, 18.0), pastel(0.91, 0.042, 16.0)),
            danger_fill_hover: pick(color(0.44, 0.09, 18.0), pastel(0.86, 0.052, 16.0)),
            danger_label: pick(pastel(0.97, 0.006, 0.0), pastel(0.42, 0.085, 16.0)),
        }
    }

    /// Neutral grey palette for a host with no hue of its own.
    pub fn neutral(dark: bool) -> Self {
        Self::from_hue_and_saturation(0.0, 0.0, dark)
    }

    /// The palette part way between two others, for a scheme or a hue that
    /// is changing over rather than cutting. Every colour role is blended;
    /// the light-or-dark flag, which only picks shadow directions, flips
    /// half way.
    ///
    /// Blended in sRGB rather than in linear light. Linear is right for two
    /// colours that are really overlapping; for a cross-fade it is wrong,
    /// because half way between a dark palette and a light one in linear
    /// light is a washed-out grey brighter than either looks, and the whole
    /// window flashes on its way from one to the other.
    pub fn mix(from: Palette, to: Palette, t: f32) -> Palette {
        let m = |a, b| crate::color::lerp(a, b, t);
        Palette {
            is_dark: if t < 0.5 { from.is_dark } else { to.is_dark },
            accent: m(from.accent, to.accent),
            backdrop: m(from.backdrop, to.backdrop),
            text_primary: m(from.text_primary, to.text_primary),
            text_secondary: m(from.text_secondary, to.text_secondary),
            field_surface: m(from.field_surface, to.field_surface),
            field_border: m(from.field_border, to.field_border),
            field_border_strong: m(from.field_border_strong, to.field_border_strong),
            area_surface: m(from.area_surface, to.area_surface),
            area_border: m(from.area_border, to.area_border),
            row_hover: m(from.row_hover, to.row_hover),
            control_fill: m(from.control_fill, to.control_fill),
            control_label: m(from.control_label, to.control_label),
            soft_fill: m(from.soft_fill, to.soft_fill),
            soft_fill_hover: m(from.soft_fill_hover, to.soft_fill_hover),
            soft_label: m(from.soft_label, to.soft_label),
            primary_fill: m(from.primary_fill, to.primary_fill),
            primary_fill_hover: m(from.primary_fill_hover, to.primary_fill_hover),
            primary_label: m(from.primary_label, to.primary_label),
            danger_fill: m(from.danger_fill, to.danger_fill),
            danger_fill_hover: m(from.danger_fill_hover, to.danger_fill_hover),
            danger_label: m(from.danger_label, to.danger_label),
        }
    }

    /// A translucent black wash to lay over content behind a modal.
    pub fn scrim(&self) -> Rgba {
        if self.is_dark {
            argb(0x8000_0000)
        } else {
            argb(0x5500_0000)
        }
    }

    /// A fully transparent colour in this palette's space, for `when` arms
    /// that need to paint nothing.
    pub const fn transparent() -> Rgba {
        TRANSPARENT
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::color::{channels, relative_luminance};

    fn roles(palette: Palette) -> [Rgba; 21] {
        [
            palette.accent,
            palette.backdrop,
            palette.text_primary,
            palette.text_secondary,
            palette.field_surface,
            palette.field_border,
            palette.field_border_strong,
            palette.area_surface,
            palette.area_border,
            palette.row_hover,
            palette.control_fill,
            palette.control_label,
            palette.soft_fill,
            palette.soft_fill_hover,
            palette.soft_label,
            palette.primary_fill,
            palette.primary_fill_hover,
            palette.primary_label,
            palette.danger_fill,
            palette.danger_fill_hover,
            palette.danger_label,
        ]
    }

    #[test]
    fn schemes_run_in_opposite_directions() {
        let dark = Palette::from_hue(280.0, true);
        let light = Palette::from_hue(280.0, false);
        assert!(relative_luminance(dark.field_surface) < relative_luminance(dark.text_primary));
        assert!(relative_luminance(light.field_surface) > relative_luminance(light.text_primary));
        // The ground follows the scheme, and in the light one the panels
        // sit white on a ground a shade below them.
        assert!(relative_luminance(dark.backdrop) < relative_luminance(light.backdrop));
        assert!(relative_luminance(light.backdrop) < relative_luminance(light.area_surface));
    }

    #[test]
    fn every_hue_stays_in_gamut() {
        for hue in (0..360).step_by(15) {
            for dark in [true, false] {
                for saturation in [0.0, 0.5, DEFAULT_SATURATION, MAX_SATURATION] {
                    let palette = Palette::from_hue_and_saturation(hue as f64, saturation, dark);
                    for color in roles(palette) {
                        for channel in channels(color) {
                            assert!(
                                (0.0..=1.0).contains(&channel),
                                "hue {hue} saturation {saturation} dark {dark} produced {channel}"
                            );
                        }
                    }
                }
            }
        }
    }

    #[test]
    fn zero_saturation_makes_every_role_neutral_including_danger() {
        for dark in [false, true] {
            let neutral = Palette::neutral(dark);
            for hue in [0.0, 37.0, 180.0, 268.0, 359.9] {
                let palette = Palette::from_hue_and_saturation(hue, 0.0, dark);
                assert_eq!(palette, neutral);
                for color in roles(palette) {
                    let [r, g, b, a] = channels(color);
                    assert_eq!(r, g);
                    assert_eq!(g, b);
                    assert_eq!(a, 1.0);
                }
            }
        }
    }

    #[test]
    fn saturation_is_chroma_gain_and_one_keeps_the_original_palette() {
        for hue in [0.0, 87.0, 193.0, 268.0] {
            for dark in [false, true] {
                assert_eq!(
                    Palette::from_hue(hue, dark),
                    Palette::from_hue_and_saturation(hue, DEFAULT_SATURATION, dark)
                );
                for saturation in [0.5, 1.0, 2.0, MAX_SATURATION] {
                    let palette = Palette::from_hue_and_saturation(hue, saturation, dark);
                    let lightness = if dark { 0.78 } else { 0.62 };
                    assert_eq!(
                        palette.accent,
                        oklch_to_color(
                            lightness,
                            0.105 * (saturation.min(1.0) + (saturation - 1.0).max(0.0) * 0.35),
                            hue
                        )
                    );
                }
            }
        }
    }

    #[test]
    fn invalid_saturation_is_normalized_for_every_role() {
        for (input, expected) in [
            (f64::NAN, DEFAULT_SATURATION),
            (f64::NEG_INFINITY, 0.0),
            (-1.0, 0.0),
            (0.5, 0.5),
            (3.0, 3.0),
            (4.0, MAX_SATURATION),
            (5.0, MAX_SATURATION),
            (f64::INFINITY, MAX_SATURATION),
        ] {
            assert_eq!(normalized_saturation(input), expected);
            for dark in [false, true] {
                assert_eq!(
                    Palette::from_hue_and_saturation(268.0, input, dark),
                    Palette::from_hue_and_saturation(268.0, expected, dark)
                );
            }
        }
    }

    #[test]
    fn a_hue_that_is_not_a_number_falls_back_to_zero() {
        for dark in [false, true] {
            for hue in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
                assert_eq!(
                    Palette::from_hue_and_saturation(hue, MAX_SATURATION, dark),
                    Palette::from_hue_and_saturation(0.0, MAX_SATURATION, dark)
                );
            }
        }
    }

    #[test]
    fn surface_tint_arrives_continuously_above_standard_intensity() {
        for dark in [false, true] {
            let standard = Palette::from_hue(268.0, dark);
            let increased = Palette::from_hue_and_saturation(268.0, 1.000001, dark);
            for (before, after) in roles(standard).into_iter().zip(roles(increased)) {
                for (before, after) in channels(before).into_iter().zip(channels(after)) {
                    assert!((before - after).abs() < 0.0001);
                }
            }
        }
    }

    #[test]
    fn vivid_backgrounds_are_tinted_and_keep_body_text_readable() {
        for hue in (0..360).step_by(15) {
            for dark in [false, true] {
                let palette = Palette::from_hue_and_saturation(hue as f64, MAX_SATURATION, dark);
                for background in [
                    palette.backdrop,
                    palette.field_surface,
                    palette.area_surface,
                ] {
                    let [r, g, b, _] = channels(background);
                    assert!(r != g || g != b, "hue {hue} dark {dark}: neutral surface");
                    let background = relative_luminance(background);
                    for text in [palette.text_primary, palette.text_secondary] {
                        let foreground = relative_luminance(text);
                        let contrast = (foreground.max(background) + 0.05)
                            / (foreground.min(background) + 0.05);
                        assert!(contrast >= 4.5, "hue {hue} dark {dark}: {contrast}");
                    }
                }
            }
        }
    }

    #[test]
    fn vivid_secondary_surfaces_keep_readable_labels() {
        for hue in (0..360).step_by(15) {
            for dark in [false, true] {
                let palette = Palette::from_hue_and_saturation(hue as f64, MAX_SATURATION, dark);
                let foreground = relative_luminance(palette.soft_label);
                for background in [palette.soft_fill, palette.soft_fill_hover] {
                    let background = relative_luminance(background);
                    let contrast =
                        (foreground.max(background) + 0.05) / (foreground.min(background) + 0.05);
                    assert!(contrast >= 4.5, "hue {hue} dark {dark}: {contrast}");
                }
            }
        }
    }
}