egui_macview/theme/
mod.rs

1//! macOS AppKit Dynamic Theming System.
2//!
3//! Grounded in Apple AppKit `NSAppearance` semantics and W3C DTCG design tokens.
4//! Guarantees zero hardcoded constants by deriving all geometry metrics,
5//! typography bounds, and semantic colors dynamically from [`MacDesignTokens`].
6
7use crate::tokens::{MacAppearanceColors, MacDesignTokens};
8use egui::{Color32, Id};
9use std::sync::{Arc, OnceLock};
10
11pub mod accessors;
12pub mod contrast;
13pub use contrast::{
14    contrast_ratio, relative_luminance, srgb_channel_to_linear, MacBackgroundStyle,
15};
16
17static DEFAULT_TOKENS: OnceLock<Arc<MacDesignTokens>> = OnceLock::new();
18
19fn default_cached_tokens() -> Arc<MacDesignTokens> {
20    DEFAULT_TOKENS
21        .get_or_init(|| Arc::new(MacDesignTokens::load_default()))
22        .clone()
23}
24
25/// macOS system appearance mode.
26#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
27pub enum MacAppearance {
28    /// Authentic Apple macOS light appearance (`NSAppearanceNameAqua`).
29    #[default]
30    Aqua,
31    /// Anthracite calm intermediate studio appearance mode.
32    Anthracite,
33    /// Authentic Apple macOS dark appearance (`NSAppearanceNameDarkAqua`).
34    DarkAqua,
35}
36
37/// Window caption controls presentation style (Strategy 2: Token-Driven / Configurable Presentation).
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
39pub enum WindowControlsStyle {
40    /// Authentic Apple macOS traffic lights on the leading (left) edge.
41    #[default]
42    AppleTrafficLights,
43    /// Authentic Microsoft Windows 11 caption buttons on the trailing (right) edge.
44    WindowsCaptionButtons,
45    /// Native host OS window manager decorations (decorations provided by OS).
46    NativeHost,
47}
48
49/// Dynamic theme resolving AppKit semantic styling from [`MacDesignTokens`].
50///
51/// # Example
52///
53/// ```rust
54/// use egui_macview::{MacAppearance, MacTheme, WindowControlsStyle};
55///
56/// let theme = MacTheme::new(MacAppearance::DarkAqua)
57///     .with_window_controls_style(WindowControlsStyle::AppleTrafficLights);
58///
59/// let bg = theme.window_background();
60/// let text_color = theme.label();
61/// let corner_radius = theme.button().regular.corner_radius.points();
62/// assert_eq!(corner_radius, 6.0);
63/// ```
64#[derive(Debug, Clone)]
65pub struct MacTheme {
66    /// Active macOS appearance mode ([`MacAppearance::Aqua`] or [`MacAppearance::DarkAqua`]).
67    pub appearance: MacAppearance,
68    /// Window caption controls presentation style.
69    pub window_controls_style: WindowControlsStyle,
70    tokens: Arc<MacDesignTokens>,
71    custom_accent: Option<Color32>,
72}
73
74impl Default for MacTheme {
75    fn default() -> Self {
76        Self::new(MacAppearance::Aqua)
77    }
78}
79
80impl MacTheme {
81    /// Creates a new `MacTheme` for the given appearance using the embedded default token catalog.
82    pub fn new(appearance: MacAppearance) -> Self {
83        Self {
84            appearance,
85            window_controls_style: WindowControlsStyle::AppleTrafficLights,
86            tokens: default_cached_tokens(),
87            custom_accent: None,
88        }
89    }
90
91    /// Retrieves the active `MacTheme` stored in `egui::Context` by [`MacTheme::apply_to_egui`],
92    /// falling back to [`MacTheme::default`] (`Aqua`) if none was registered.
93    pub fn from_ctx(ctx: &egui::Context) -> Self {
94        ctx.data(|d| d.get_temp::<MacTheme>(Id::NULL))
95            .unwrap_or_default()
96    }
97
98    /// Resolves an optional borrowed [`MacTheme`], falling back to [`MacTheme::from_ctx`].
99    pub fn resolve<'a>(theme: Option<&'a Self>, ctx: &egui::Context) -> std::borrow::Cow<'a, Self> {
100        match theme {
101            Some(t) => std::borrow::Cow::Borrowed(t),
102            None => std::borrow::Cow::Owned(Self::from_ctx(ctx)),
103        }
104    }
105
106    /// Resolves an optional borrowed [`MacTheme`], falling back to the cached [`MacTheme::default`]
107    /// without allocating an [`egui::Context`].
108    pub fn resolve_or_default<'a>(theme: Option<&'a Self>) -> std::borrow::Cow<'a, Self> {
109        match theme {
110            Some(t) => std::borrow::Cow::Borrowed(t),
111            None => std::borrow::Cow::Owned(Self::default()),
112        }
113    }
114
115    /// Sets the window controls presentation style (Strategy 2).
116    pub fn with_window_controls_style(mut self, style: WindowControlsStyle) -> Self {
117        self.window_controls_style = style;
118        self
119    }
120
121    /// Returns the active window controls presentation style.
122    pub fn window_controls_style(&self) -> WindowControlsStyle {
123        self.window_controls_style
124    }
125
126    /// Sets a dynamic system accent color override (matching macOS System Settings Appearance Accent).
127    pub fn with_accent(mut self, accent: Color32) -> Self {
128        self.custom_accent = Some(accent);
129        self
130    }
131
132    /// Creates a `MacTheme` with custom loaded tokens.
133    pub fn with_tokens(appearance: MacAppearance, tokens: MacDesignTokens) -> Self {
134        Self {
135            appearance,
136            window_controls_style: WindowControlsStyle::AppleTrafficLights,
137            tokens: Arc::new(tokens),
138            custom_accent: None,
139        }
140    }
141
142    /// Creates a `MacTheme` with custom loaded tokens wrapped in an `Arc`.
143    pub fn with_arc_tokens(appearance: MacAppearance, tokens: Arc<MacDesignTokens>) -> Self {
144        Self {
145            appearance,
146            window_controls_style: WindowControlsStyle::AppleTrafficLights,
147            tokens,
148            custom_accent: None,
149        }
150    }
151
152    /// Returns the underlying design token catalog.
153    pub fn tokens(&self) -> &MacDesignTokens {
154        &self.tokens
155    }
156
157    /// Active appearance color palette.
158    pub fn colors(&self) -> &MacAppearanceColors {
159        match self.appearance {
160            MacAppearance::Aqua => &self.tokens.colors().aqua,
161            MacAppearance::Anthracite => &self.tokens.colors().anthracite,
162            MacAppearance::DarkAqua => &self.tokens.colors().dark_aqua,
163        }
164    }
165
166    /// Resolves `windowBackgroundColor` (NSColor) for the active appearance.
167    pub fn window_background(&self) -> Color32 {
168        self.colors().window_background.to_color32()
169    }
170
171    /// Resolves `controlBackgroundColor` (NSColor) for the active appearance.
172    pub fn control_background(&self) -> Color32 {
173        self.colors().control_background.to_color32()
174    }
175
176    /// Resolves `controlColor` (NSColor) for the active appearance.
177    pub fn control(&self) -> Color32 {
178        self.colors().control.to_color32()
179    }
180
181    /// Resolves `controlAccentColor` (NSColor) or custom accent override.
182    pub fn control_accent(&self) -> Color32 {
183        self.custom_accent
184            .unwrap_or_else(|| self.colors().control_accent.to_color32())
185    }
186
187    /// Resolves `selectedControlColor` (NSColor) or custom accent override.
188    pub fn selected_control(&self) -> Color32 {
189        self.custom_accent
190            .unwrap_or_else(|| self.colors().selected_control.to_color32())
191    }
192
193    /// Resolves `selectedControlColor` (NSColor) when the window or control is inactive/unfocused.
194    pub fn selected_control_inactive(&self) -> Color32 {
195        self.colors().selected_control_inactive.to_color32()
196    }
197
198    /// Resolves `separatorColor` (NSColor) for hairlines and borders.
199    pub fn separator(&self) -> Color32 {
200        self.colors().separator.to_color32()
201    }
202
203    /// Resolves `placeholderTextColor` (NSColor) for empty text fields and search inputs.
204    pub fn placeholder_text(&self) -> Color32 {
205        self.colors().placeholder_text.to_color32()
206    }
207
208    /// Resolves `keyboardFocusIndicatorColor` (NSColor) for focus rings.
209    pub fn keyboard_focus_indicator(&self) -> Color32 {
210        self.colors().keyboard_focus_indicator.to_color32()
211    }
212
213    /// Resolves primary `labelColor` (NSColor).
214    pub fn label(&self) -> Color32 {
215        self.colors().label.to_color32()
216    }
217
218    /// Resolves `secondaryLabelColor` (NSColor) for captions, subtitles, and section headers.
219    pub fn secondary_label(&self) -> Color32 {
220        self.colors().secondary_label.to_color32()
221    }
222
223    /// Resolves Apple system green semantic color (`systemGreenColor`).
224    pub fn system_green(&self) -> Color32 {
225        self.colors().system_green.to_color32()
226    }
227
228    /// Resolves Apple system yellow/amber semantic color (`systemYellowColor`).
229    pub fn system_yellow(&self) -> Color32 {
230        self.colors().system_yellow.to_color32()
231    }
232
233    /// Resolves Apple system orange semantic color (`systemOrangeColor`).
234    pub fn system_orange(&self) -> Color32 {
235        self.colors().system_orange.to_color32()
236    }
237
238    /// Resolves Apple system red semantic color (`systemRedColor`).
239    pub fn system_red(&self) -> Color32 {
240        self.colors().system_red.to_color32()
241    }
242
243    /// Resolves even table row background color (`alternatingContentBackgroundColors[0]`).
244    pub fn alternating_row_even(&self) -> Color32 {
245        self.colors().alternating_row_even.to_color32()
246    }
247
248    /// Resolves odd table row background color (`alternatingContentBackgroundColors[1]`).
249    pub fn alternating_row_odd(&self) -> Color32 {
250        self.colors().alternating_row_odd.to_color32()
251    }
252
253    /// Resolves alternating content background color for the given row index (`row_index % 2`).
254    pub fn alternating_content_background(&self, row_index: usize) -> Color32 {
255        if row_index.is_multiple_of(2) {
256            self.alternating_row_even()
257        } else {
258            self.alternating_row_odd()
259        }
260    }
261
262    /// Resolves QuickTime / AVKit trim selection border and handle color.
263    pub fn scrubber_selection_border(&self) -> Color32 {
264        self.colors().scrubber_selection_border.to_color32()
265    }
266
267    /// Resolves dimming overlay color for timeline regions outside active trim bounds.
268    pub fn scrubber_outside_dim(&self) -> Color32 {
269        self.colors().scrubber_outside_dim.to_color32()
270    }
271
272    /// Resolves waveform amplitude bar color inside trim scrubber track.
273    pub fn scrubber_waveform(&self) -> Color32 {
274        self.colors().scrubber_waveform.to_color32()
275    }
276
277    /// Resolves playhead cursor line and timecode badge accent color.
278    pub fn scrubber_playhead(&self) -> Color32 {
279        self.colors().scrubber_playhead.to_color32()
280    }
281
282    /// Resolves high-contrast white text color used on accent fills.
283    pub fn on_accent_text(&self) -> Color32 {
284        self.colors().on_accent_text.to_color32()
285    }
286
287    /// Resolves white thumb knob fill color for switches and sliders.
288    pub fn knob_fill(&self) -> Color32 {
289        self.colors().knob_fill.to_color32()
290    }
291
292    /// Resolves subtle ambient drop shadow color for controls and floating surfaces.
293    pub fn drop_shadow(&self) -> Color32 {
294        self.colors().drop_shadow.to_color32()
295    }
296
297    /// Resolves modal backdrop dimming overlay color.
298    pub fn backdrop_dim(&self) -> Color32 {
299        self.colors().backdrop_dim.to_color32()
300    }
301
302    /// Resolves translucent dark HUD palette background color (`SPEC-006 §2.2`).
303    pub fn hud_background(&self) -> Color32 {
304        self.colors().hud_background.to_color32()
305    }
306
307    /// Resolves dark HUD palette hairline border color.
308    pub fn hud_border(&self) -> Color32 {
309        self.colors().hud_border.to_color32()
310    }
311
312    /// Resolves dark HUD palette primary text color.
313    pub fn hud_text(&self) -> Color32 {
314        self.colors().hud_text.to_color32()
315    }
316
317    /// Resolves dark HUD palette secondary label color.
318    pub fn hud_secondary_text(&self) -> Color32 {
319        self.colors().hud_secondary_text.to_color32()
320    }
321
322    /// Resolves macOS window close traffic light fill and border colors `(fill, border)`.
323    pub fn traffic_light_close(&self) -> (Color32, Color32) {
324        (
325            self.colors().traffic_light_close.to_color32(),
326            self.colors().traffic_light_close_border.to_color32(),
327        )
328    }
329
330    /// Resolves macOS window minimize traffic light fill and border colors `(fill, border)`.
331    pub fn traffic_light_minimize(&self) -> (Color32, Color32) {
332        (
333            self.colors().traffic_light_minimize.to_color32(),
334            self.colors().traffic_light_minimize_border.to_color32(),
335        )
336    }
337
338    /// Resolves macOS window zoom/fullscreen traffic light fill and border colors `(fill, border)`.
339    pub fn traffic_light_zoom(&self) -> (Color32, Color32) {
340        (
341            self.colors().traffic_light_zoom.to_color32(),
342            self.colors().traffic_light_zoom_border.to_color32(),
343        )
344    }
345
346    /// Interior glyph color for hovered macOS traffic light buttons.
347    pub fn traffic_light_glyph(&self) -> Color32 {
348        self.colors().traffic_light_glyph.to_color32()
349    }
350
351    /// Background color for Windows 11 close caption button on hover (`#E81123`).
352    pub fn windows_caption_close_hover_bg(&self) -> Color32 {
353        self.colors().caption_close_hover.to_color32()
354    }
355
356    /// Background color for Windows 11 close caption button when pressed (`#C42B1C`).
357    pub fn windows_caption_close_pressed_bg(&self) -> Color32 {
358        self.colors().caption_close_pressed.to_color32()
359    }
360
361    /// Background color for Windows 11 minimize/maximize caption buttons on hover.
362    pub fn windows_caption_hover_bg(&self) -> Color32 {
363        self.colors().caption_hover.to_color32()
364    }
365
366    /// Background color for Windows 11 minimize/maximize caption buttons when pressed.
367    pub fn windows_caption_pressed_bg(&self) -> Color32 {
368        self.colors().caption_pressed.to_color32()
369    }
370
371    /// Overlay scrollbar thumb color scaled by fade `alpha_factor` in `[0.0, 1.0]`.
372    pub fn scrollbar_thumb_color(&self, active: bool, alpha_factor: f32) -> Color32 {
373        let base = if active {
374            self.colors().scrollbar_thumb_active.to_color32()
375        } else {
376            self.colors().scrollbar_thumb.to_color32()
377        };
378        base.gamma_multiply(alpha_factor.clamp(0.0, 1.0))
379    }
380
381    /// Synchronizes `egui::Context` theme, visuals, and stored `MacTheme` with the macOS appearance.
382    ///
383    /// Performs an $O(1)$ short-circuit when the active `MacTheme` stored in `ctx` already matches
384    /// the current appearance, window controls style, accent override, and token catalog pointer.
385    pub fn apply_to_egui(&self, ctx: &egui::Context) {
386        let unchanged = ctx.data(|d| {
387            d.get_temp::<MacTheme>(Id::NULL).is_some_and(|prev| {
388                prev.appearance == self.appearance
389                    && prev.window_controls_style == self.window_controls_style
390                    && prev.custom_accent == self.custom_accent
391                    && Arc::ptr_eq(&prev.tokens, &self.tokens)
392            })
393        });
394        if unchanged {
395            return;
396        }
397        ctx.data_mut(|d| d.insert_temp(Id::NULL, self.clone()));
398
399        let egui_theme = match self.appearance {
400            MacAppearance::Aqua => egui::Theme::Light,
401            MacAppearance::Anthracite | MacAppearance::DarkAqua => egui::Theme::Dark,
402        };
403        ctx.set_theme(egui_theme);
404
405        let mut visuals = match self.appearance {
406            MacAppearance::Aqua => egui::Visuals::light(),
407            MacAppearance::Anthracite | MacAppearance::DarkAqua => egui::Visuals::dark(),
408        };
409
410        let border_w = self.button().regular.border_width.points();
411        let label_color = self.label();
412        visuals.override_text_color = Some(label_color);
413        visuals.widgets.noninteractive.fg_stroke.color = label_color;
414        visuals.widgets.noninteractive.bg_stroke = egui::Stroke::new(border_w, self.separator());
415        visuals.widgets.inactive.fg_stroke.color = label_color;
416        visuals.widgets.inactive.bg_stroke = egui::Stroke::new(border_w, self.separator());
417        visuals.panel_fill = self.window_background();
418        visuals.window_fill = self.window_background();
419        visuals.window_stroke = egui::Stroke::new(border_w, self.separator());
420
421        let small_pt = self.text_field().small.font_size.points();
422        let body_pt = self.outline_view().font_size.points();
423        let heading_pt = self.text_field().regular.font_size.points();
424
425        ctx.all_styles_mut(|style| {
426            use egui::{FontFamily, FontId, TextStyle};
427            style.text_styles = [
428                (
429                    TextStyle::Small,
430                    FontId::new(small_pt, FontFamily::Proportional),
431                ),
432                (
433                    TextStyle::Body,
434                    FontId::new(body_pt, FontFamily::Proportional),
435                ),
436                (
437                    TextStyle::Button,
438                    FontId::new(body_pt, FontFamily::Proportional),
439                ),
440                (
441                    TextStyle::Heading,
442                    FontId::new(heading_pt, FontFamily::Proportional),
443                ),
444                (
445                    TextStyle::Monospace,
446                    FontId::new(body_pt, FontFamily::Monospace),
447                ),
448            ]
449            .into();
450        });
451
452        ctx.set_visuals_of(egui_theme, visuals.clone());
453        ctx.set_visuals(visuals);
454    }
455}
egui_macview/theme/mod.rs

egui_macview/theme/
mod.rs
