# `egui-macview`
**Deterministic macOS AppKit Layout Engines, Authentic Control Primitive Suite, and CoreAnimation Physics Runtime for `egui` on Windows, macOS, Linux, and Web.**
[](https://crates.io/crates/egui-macview)
[](https://docs.rs/egui-macview)
[](https://opensource.org/licenses/MIT)
[-brightgreen.svg)](https://github.com/oversluizen/egui-macview)
---
## 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.
```bash
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:
```text
┌─────────────────┬──────────────────────────────────────────┬──────────────────┐
│ 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
| [`MacSplitView`](file:///D:/Programmeren/egui-macview/src/layout/split_view.rs) | `NSSplitView` | Dual hairline draggable divider with min/max constraint protection and cursor styling. |
| [`MacFixedView`](file:///D:/Programmeren/egui-macview/src/layout/fixed_view.rs) | Retained NIB Frame | Exact coordinate subview placement guaranteeing zero margin bleed and exact pixel alignment. |
| [`MacRow`](file:///D:/Programmeren/egui-macview/src/layout/row.rs) | Flexible Cell Row | Auto-budgeting horizontal cell layout with analytical $O(n)$ space distribution. |
| [`MacScrollView`](file:///D:/Programmeren/egui-macview/src/layout/scroll_view.rs) | `NSScrollView` | Floating overlay scrollbars with zero gutter reservation and smooth auto-fade timers. |
| [`MacStackView`](file:///D:/Programmeren/egui-macview/src/layout/stack_view.rs) | `NSStackView` | Auto-layout linear stacking container with token-governed spacing and section separators. |
### 3.2 Authentic Control Primitives
| [`MacInputCell`](file:///D:/Programmeren/egui-macview/src/controls/text_field.rs) | `NSTextField` | Compact text input with external focus ring, cyclic Tab-chain FSM, and transactional buffer commit. |
| [`MacSegmentedControl`](file:///D:/Programmeren/egui-macview/src/controls/segmented.rs) | `NSSegmentedControl` | Apple segmented pill with smooth animated sliding selection indicator and dark-mode contrast. |
| [`MacOutlineView`](file:///D:/Programmeren/egui-macview/src/controls/outline_view.rs) | `NSOutlineView` | Hierarchical outline view with disclosure triangles, indentation steps, and custom accessory buttons. |
| [`MacToggle`](file:///D:/Programmeren/egui-macview/src/controls/toggle.rs) | `NSSwitch` | Native macOS toggle switch with system green active fill and smooth spring thumb transitions. |
| [`MacSlider`](file:///D:/Programmeren/egui-macview/src/controls/slider.rs) | `NSSlider` | Continuous tracking slider with tick marks, keyboard arrow nudging, and token-driven dimensions. |
| [`MacStepper`](file:///D:/Programmeren/egui-macview/src/controls/stepper.rs) | `NSStepper` | Discrete scalar increment/decrement buttons with float epsilon wrapping protection and unit suffix formatting. |
| [`MacPopUpButton`](file:///D:/Programmeren/egui-macview/src/controls/popup_button.rs) | `NSPopUpButton` | Trailing double chevrons with dropdown selection overlay and auto-clamping viewport positioning. |
| [`MacSearchField`](file:///D:/Programmeren/egui-macview/src/controls/search_field.rs) | `NSSearchField` | Magnifying glass glyph, instant clear (`×`) button, and keyboard escape handling. |
| [`MacColorWell`](file:///D:/Programmeren/egui-macview/src/controls/color_well.rs) | `NSColorWell` | Color swatch preview with translucent alpha checkerboard underlay and popover picker. |
| [`MacProgressIndicator`](file:///D:/Programmeren/egui-macview/src/controls/progress_indicator.rs) | `NSProgressIndicator` | Determinate/indeterminate horizontal progress bar (`6.0 pt` / `4.0 pt`) and 12-spoke stepped circular activity spinner (`Regular`, `Small`, `Mini`). |
| [`MacTableView`](file:///D:/Programmeren/egui-macview/src/controls/table_view/mod.rs) | `NSTableView` + `NSTableHeaderView` | Multi-column data table with `24.0 pt` sortable column headers, alternating row backgrounds, single/Shift/Cmd row selection, and keyboard navigation. |
| [`MacTokenField`](file:///D:/Programmeren/egui-macview/src/controls/token_field.rs) | `NSTokenField` | Interactive capsule tag/pill input with comma/Enter commit, per-pill `×` removal, Backspace pop, flow wrapping, and optional character counter. |
| [`MacLevelIndicator`](file:///D:/Programmeren/egui-macview/src/controls/level_indicator.rs) | `NSLevelIndicator` | Continuous and discrete segmented capacity/audio level meter (horizontal or vertical) with green/yellow/red thresholds and peak-hold marker. |
| [`MacTrimScrubber`](file:///D:/Programmeren/egui-macview/src/controls/trim_scrubber/mod.rs) | `AVPlayerView` Trim Bar | QuickTime / AVKit media timeline trim bar with waveform bars, named zones, yellow selection handles, dimmed outside regions, and draggable playhead with `MM:SS.d` badge. |
| [`MacPathControl`](file:///D:/Programmeren/egui-macview/src/controls/path_control.rs) | `NSPathControl` | Interactive file/folder breadcrumb bar with vector icons, chevron separators, clickable segments, and optional trailing `Choose...` button. |
| [`MacMenuBar`](file:///D:/Programmeren/egui-macview/src/navigation/menu.rs) | `NSMenu` / App Menu | Authentic menu bar with cascading submenus, global keyboard shortcuts, and dynamic width auto-calculation guaranteeing $\ge 24\,\text{pt}$ clearance between titles and accelerators. |
| [`MacCommandPalette`](file:///D:/Programmeren/egui-macview/src/navigation/command_palette.rs) | Spotlight / Quick Open | Floating modal command runner with fuzzy subsequence scoring, category badges, and keyboard navigation. |
### 3.3 CoreAnimation Physics (`CASpring`)
[`CASpring`](file:///D:/Programmeren/egui-macview/src/motion/spring.rs) 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`:
```toml
[dependencies]
egui = "0.37.0"
egui-macview = "0.5.2"
```
### Complete Code Example
```rust
use egui_macview::{
MacAppearance, MacInputCell, MacSegmentedControl, MacStepper, MacTheme, MacToggle,
};
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**: **142 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` (6 tests + 1 live SSH test)
- `menu_and_palette_tests` (20 tests)
- `micro_animations_and_hud_tests` (7 tests)
- `studio_controls_v05_tests` (6 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](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.