egui-macview

Deterministic macOS AppKit Layout Engines, Authentic Control Primitive Suite, and CoreAnimation Physics Runtime for egui on Windows, macOS, Linux, and Web.

1. Architectural Overview

Standard egui relies on content-driven streaming flow: widgets dynamically compute their own margins and sequentially advance the cursor. While convenient for rapid prototyping, streaming flow poses challenges when building pixel-exact desktop application suites (like Xcode, Final Cut Pro, or macOS System Settings) that require:

1. Mathematical Layout Determinism: Subpixel-snapped boundaries, zero-margin outer containers, and formal layout contracts that mathematically prevent clipping and content overlap.
2. AppKit Control Parity: Authentic macOS design language—including focused control rings, segmented pill buttons with animated selection thumbs, cyclic Tab-chain FSMs, and discrete stepper steppers with unit suffixes.
3. CoreAnimation Physics: Frame-rate independent damped harmonic oscillator spring motion (CASpring), producing exact Apple perceptual micro-interactions across 60Hz, 120Hz ProMotion, and 144Hz displays.

egui-macview solves this by introducing retained NIB-style layout framing, an authentic AppKit control suite, and a high-assurance physics engine built directly on top of egui 0.37.0.

2. Interactive Showcase Gallery (macview_gallery)

The crate includes an interactive capability showcase demonstrating all primitives working together in a production-grade multi-window environment.

cargo run --example macview_gallery

The 4 Master-Detail Capability Screens

Clicking the Screens group in the left sidebar switches the central work area across 4 specialized AppKit capability screens:

┌─────────────────┬──────────────────────────────────────────┬──────────────────┐
│ Left Sidebar    │ Center Work Area (Master-Detail)         │ Right Inspector  │
│                 │                                          │                  │
│ • Screens       │ 1. Interactive Canvas & Physics          │ • Presets        │
│   ├─ 1. Canvas  │    - 2D Affine Matrix live transforms    │   ├─ Default NIB │
│   ├─ 2. Vectors │    - Damped CASpring pulse on clicks     │   ├─ Compact HUD │
│   ├─ 3. Tokens  │ 2. Vector Assets Gallery                 │   └─ Expanded    │
│   └─ 4. Layouts │    - 14 Cupertino true-vector glyphs     │ • Dimensions     │
│                 │    - Live search filter (⌘K / Ctrl+K)    │ • Layout & Mask  │
│ • Presets       │ 3. W3C Design Tokens & WCAG Engine       │   [L][ C ][R][F] │
│   ├─ Default    │    - Token catalogue (colors/metrics)    │ • 2x2 Matrix     │
│   ├─ Compact    │    - Real-time WCAG AA contrast tester   │ • Live Swatches  │
│   └─ Expanded   │ 4. Layout Engines Playground             │                  │
│                 │    - MacFixedView & live Raster Mask     │                  │
│                 │    - MacRow container width budgeting    │                  │
└─────────────────┴──────────────────────────────────────────┴──────────────────┘

1. Screen 1: Interactive Canvas & Physics
   • 2D Affine Matrix Manipulation: Live rotation ($\theta$), scaling ($25%\dots200%$), skew, and translation.
   • CASpring Harmonic Oscillator: Analytical spring pulse triggered by canvas clicks or inspector actions.
   • Layout & Alignment Mask Integration: Segmented [Left] [Center] [Right] [Fill] control in the inspector dynamically updates the card's anchor position or expands it to full container width with zero clipping.
2. Screen 2: Vector Assets Gallery
   • 14 Authentic Cupertino Symbols: 100% vector TrueType glyphs (MacSymbol::Search, ChevronDown, Gear, Checkmark, etc.) with zero emoji-bleed on Windows or Linux.
   • Instant Search Filtering: Host-adaptive search shortcut ([🔍 ⌘K] on macOS, [🔍 Ctrl+K] on Windows/Linux) with live fuzzy substring matching and metadata inspection cards.
3. Screen 3: W3C Design Tokens & WCAG Contrast Engine
   • DTCG Token Catalogue: Direct visualization of tokenized colors, elevations, corner radii, and optical typography.
   • Dynamic Contrast Engine: Real-time evaluation of relative luminance ($L \le 0.179$) and contrast ratios against WCAG AA standards with pass/fail badges.
4. Screen 4: Layout Engines Playground
   • MacFixedView: Retained exact-point subview layout with hardware raster mask clipping (zero border bleed) and Core Animation cascading spring effects.
   • MacRow Auto-Budgeting: Interactive container width slider demonstrating how compartments automatically allocate and budget available horizontal space.

3. Core Component Suite & API Reference

3.1 Layout Engines

3.2 Authentic Control Primitives

3.3 CoreAnimation Physics (CASpring)

CASpring provides the closed-form analytical solution to the damped harmonic oscillator:

$$m \ddot{x} + c \dot{x} + k x = 0$$

• Response ($T_0$) & Damping Ratio ($\zeta$): Configured via Apple design tokens (macview.motion.spring.default).
• Analytically Exact: Evaluates position and velocity at any arbitrary time $t$ in microseconds with zero numerical drift or Euler integration lag.
• Display Agnostic: Delivers mathematically identical motion at 60 FPS, 120 FPS ProMotion, or 240 FPS.

4. Developer Quick Start

Add Dependency

Add egui-macview to your Cargo.toml:

[dependencies]
egui = "0.37.0"
egui-macview = "0.3.1"

Complete Code Example

use egui::{pos2, vec2, Rect};
use egui_macview::{
    theme::{MacAppearance, MacTheme},
    controls::{
        segmented::MacSegmentedControl,
        text_field::MacInputCell,
        toggle::MacToggle,
        stepper::MacStepper,
    },
    layout::{fixed_view::MacFixedView, row::MacRow},
};

pub struct MySettingsView {
    theme: MacTheme,
    selected_tab: usize,
    username: String,
    notifications_enabled: bool,
    zoom_level: f64,
}

impl MySettingsView {
    pub fn new() -> Self {
        Self {
            theme: MacTheme::new(MacAppearance::DarkAqua),
            selected_tab: 0,
            username: "developer@apple.internal".to_string(),
            notifications_enabled: true,
            zoom_level: 100.0,
        }
    }

    pub fn ui(&mut self, ui: &mut egui::Ui) {
        // 1. Apple Segmented Tab Selector
        MacSegmentedControl::new(&["General", "Appearance", "Advanced"], self.selected_tab)
            .theme(&self.theme)
            .show(ui, |new_idx| {
                self.selected_tab = new_idx;
            });

        ui.add_space(12.0);

        // 2. Compact Input with Cyclic Tab Chain
        MacInputCell::new("input_user", &mut self.username)
            .theme(&self.theme)
            .width(220.0)
            .show(ui);

        ui.add_space(8.0);

        // 3. Native Switch Toggle
        ui.horizontal(|h_ui| {
            h_ui.label("Enable Push Notifications:");
            h_ui.add(MacToggle::new(&mut self.notifications_enabled).theme(&self.theme));
        });

        ui.add_space(8.0);

        // 4. Stepper with Unit Formatting
        ui.horizontal(|h_ui| {
            h_ui.label("Display Scale:");
            MacStepper::new(&mut self.zoom_level, 25.0, 200.0, 5.0)
                .theme(&self.theme)
                .show(h_ui);
            h_ui.label(format!("{:.0} %", self.zoom_level));
        });
    }
}

5. Quality Assurance & Standards (GL-1015 Compliance)

All code adheres strictly to GL-1015 (De Verankeringswet & Software Engineering Standards):

• 100% Red-Green Test Anchoring: Every requirement, glitch fix, and layout invariant is anchored by failing red COTS tests prior to implementation.
• Zero Host OS Emoji Bleed: Guaranteed 100% monochrome vector rendering via MacSymbol TrueType glyphs.
• Zero Dead Controls: Every UI control bidirectionally mutates state and updates visual geometry in real time.
• Test Suite Pass Rate: 135 passed, 0 failed, 1 ignored (physical Mac SSH differential test runner).
  • appkit_primitives_tests (35 tests)
  • architecture_guard_tests (7 tests)
  • cots_red_baseline_tests (7 tests)
  • high_assurance_invariants_tests (4 tests)
  • macbook_parity_differential_tests (5 tests)
  • menu_and_palette_tests (20 tests)
  • micro_animations_and_hud_tests (7 tests)
  • symbol_tests (6 tests)
  • undo_and_feedback_tests (10 tests)
  • wcag_contrast_and_visuals_tests (8 tests)
  • zero_hardcoding_and_primitive_tests (4 tests)
  • Documentation tests (20+ tests)

6. License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.