egui_macview/layout/
stack_view.rs

1//! Authentic macOS AppKit Stack View (NSStackView equivalent).
2//!
3//! Grounded in macOS HIG and W3C DTCG tokens via `MacTheme`.
4//! Fully data-driven: zero hardcoded dimensions or colors.
5//! Features automatic horizontal/vertical component stacking,
6//! configurable token-driven spacing and padding, section grouping,
7//! and optional hairline divider lines.
8
9use crate::layout::subpixel_snap;
10use crate::theme::MacTheme;
11use egui::{FontId, Pos2, Rect, Stroke, Ui, UiBuilder, Vec2};
12
13/// Orientation of a [`MacStackView`].
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
15pub enum MacStackOrientation {
16    /// Vertical auto-stacking (column layout, default).
17    #[default]
18    Vertical,
19    /// Horizontal auto-stacking (row layout).
20    Horizontal,
21}
22
23/// Alignment along the cross-axis.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
25pub enum MacStackAlignment {
26    /// Align items to the leading edge (left for vertical, top for horizontal).
27    #[default]
28    Leading,
29    /// Center items along the cross-axis.
30    Center,
31    /// Align items to the trailing edge.
32    Trailing,
33}
34
35/// Authentic macOS AppKit linear stacking container (`NSStackView` equivalent).
36///
37/// Supports automatic horizontal or vertical component stacking,
38/// configurable token-driven spacing and padding, grouped sections with header labels,
39/// and optional hairline divider lines between items.
40///
41/// # Example
42///
43/// ```rust
44/// use egui_macview::{MacStackView, MacTheme};
45///
46/// # let ctx = egui::Context::default();
47/// # let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
48/// let theme = MacTheme::default();
49///
50/// MacStackView::vertical()
51///     .theme(&theme)
52///     .spacing(12.0)
53///     .show_separators(true)
54///     .show(ui, |stack| {
55///         stack.add(|ui| {
56///             ui.label("First item");
57///         });
58///         stack.add_section(Some("Section 2"), |ui| {
59///             ui.label("Section content");
60///         });
61///     });
62/// # });
63/// # output.textures_delta.clear();
64/// ```
65pub struct MacStackView<'a> {
66    orientation: MacStackOrientation,
67    alignment: MacStackAlignment,
68    theme: Option<&'a MacTheme>,
69    spacing: Option<f32>,
70    padding: Option<f32>,
71    show_separators: bool,
72    width: Option<f32>,
73    height: Option<f32>,
74}
75
76/// Interactive stacking context passed to closures in [`MacStackView::show`].
77pub struct MacStackUi<'a> {
78    /// Underlying egui `Ui` instance for embedding widgets inside the stack.
79    pub ui: &'a mut Ui,
80
81    theme: &'a MacTheme,
82    orientation: MacStackOrientation,
83    spacing: f32,
84    separator_thickness: f32,
85    show_separators: bool,
86    container_height: Option<f32>,
87    padding: f32,
88    item_count: usize,
89    section_count: usize,
90}
91
92/// Output returned by [`MacStackView::show`].
93#[derive(Debug, Clone)]
94pub struct MacStackViewOutput<R> {
95    /// Return value of the inner closure.
96    pub inner: R,
97    /// Bounding rectangle enclosing the stacked items and padding.
98    pub rect: Rect,
99    /// Total count of items added to the stack.
100    pub item_count: usize,
101    /// Total count of sections added to the stack.
102    pub section_count: usize,
103}
104
105impl<'a> MacStackUi<'a> {
106    /// Adds an item closure to the stack with automatic spacing and separators.
107    pub fn add<R>(&mut self, item: impl FnOnce(&mut Ui) -> R) -> R {
108        if self.item_count > 0 {
109            if self.show_separators {
110                self.draw_separator();
111            } else {
112                self.advance_spacing();
113            }
114        }
115        self.item_count += 1;
116        item(self.ui)
117    }
118
119    /// Adds a grouped section with an optional section header label.
120    pub fn add_section<R>(
121        &mut self,
122        header: Option<&str>,
123        content: impl FnOnce(&mut Ui) -> R,
124    ) -> R {
125        if self.item_count > 0 || self.section_count > 0 {
126            self.draw_separator();
127        }
128        self.section_count += 1;
129
130        if let Some(title) = header {
131            let label_color = self.theme.secondary_label();
132            let font_size = self.theme.stack_view().section_header_font_size.points();
133            let font_id = FontId::proportional(font_size);
134            self.ui.add(
135                egui::Label::new(
136                    egui::RichText::new(title).font(font_id).color(label_color),
137                )
138                .wrap_mode(egui::TextWrapMode::Extend),
139            );
140            self.advance_spacing();
141        }
142
143        self.item_count += 1;
144        content(self.ui)
145    }
146
147    /// Explicitly inserts a hairline divider line spanning the cross-axis.
148    pub fn separator(&mut self) {
149        self.draw_separator();
150    }
151
152    /// Explicitly inserts custom spacing in points.
153    pub fn spacing(&mut self, pts: f32) {
154        self.ui.add_space(pts);
155    }
156
157    fn advance_spacing(&mut self) {
158        self.ui.add_space(self.spacing);
159    }
160
161    fn draw_separator(&mut self) {
162        self.ui.add_space(self.spacing * 0.5);
163        let scale = self.ui.pixels_per_point();
164        let th = self.separator_thickness;
165        let color = self.theme.separator();
166
167        match self.orientation {
168            MacStackOrientation::Vertical => {
169                let avail_w = self.ui.available_width();
170                let (rect, _) = self
171                    .ui
172                    .allocate_exact_size(Vec2::new(avail_w, th), egui::Sense::hover());
173                let y = subpixel_snap(rect.center().y, scale);
174                self.ui.painter().line_segment(
175                    [Pos2::new(rect.left(), y), Pos2::new(rect.right(), y)],
176                    Stroke::new(th, color),
177                );
178            }
179            MacStackOrientation::Horizontal => {
180                let avail_h = if let Some(ch) = self.container_height {
181                    (ch - 2.0 * self.padding).max(1.0)
182                } else {
183                    let current_h = self.ui.min_rect().height();
184                    if current_h > 0.0 {
185                        current_h
186                    } else {
187                        self.theme.stack_view().default_item_height.points()
188                    }
189                };
190                let (rect, _) = self
191                    .ui
192                    .allocate_exact_size(Vec2::new(th, avail_h), egui::Sense::hover());
193                let x = subpixel_snap(rect.center().x, scale);
194                self.ui.painter().line_segment(
195                    [Pos2::new(x, rect.top()), Pos2::new(x, rect.bottom())],
196                    Stroke::new(th, color),
197                );
198            }
199        }
200        self.ui.add_space(self.spacing * 0.5);
201    }
202}
203
204impl<'a> MacStackView<'a> {
205    /// Creates a new stack view with the specified orientation.
206    pub fn new(orientation: MacStackOrientation) -> Self {
207        Self {
208            orientation,
209            alignment: MacStackAlignment::Leading,
210            theme: None,
211            spacing: None,
212            padding: None,
213            show_separators: false,
214            width: None,
215            height: None,
216        }
217    }
218
219    /// Creates a vertical column stack view (default).
220    pub fn vertical() -> Self {
221        Self::new(MacStackOrientation::Vertical)
222    }
223
224    /// Creates a horizontal row stack view.
225    pub fn horizontal() -> Self {
226        Self::new(MacStackOrientation::Horizontal)
227    }
228
229    /// Injects dynamic theme to eliminate hardcoded metrics and colors.
230    pub fn theme(mut self, theme: &'a MacTheme) -> Self {
231        self.theme = Some(theme);
232        self
233    }
234
235    /// Sets cross-axis alignment.
236    pub fn alignment(mut self, alignment: MacStackAlignment) -> Self {
237        self.alignment = alignment;
238        self
239    }
240
241    /// Customizes spacing between adjacent elements in points.
242    pub fn spacing(mut self, spacing: f32) -> Self {
243        self.spacing = Some(spacing);
244        self
245    }
246
247    /// Customizes outer edge padding around all stacked elements in points.
248    pub fn padding(mut self, padding: f32) -> Self {
249        self.padding = Some(padding);
250        self
251    }
252
253    /// Enables automatic hairline separators between adjacent items and sections.
254    pub fn show_separators(mut self, show: bool) -> Self {
255        self.show_separators = show;
256        self
257    }
258
259    /// Sets container width constraint in points.
260    pub fn width(mut self, width: f32) -> Self {
261        self.width = Some(width);
262        self
263    }
264
265    /// Sets container height constraint in points.
266    pub fn height(mut self, height: f32) -> Self {
267        self.height = Some(height);
268        self
269    }
270
271    /// Renders the linear stack and executes the items closure.
272    pub fn show<R>(
273        self,
274        ui: &mut Ui,
275        add_contents: impl FnOnce(&mut MacStackUi<'_>) -> R,
276    ) -> MacStackViewOutput<R> {
277        let fallback_theme;
278        let theme = match self.theme {
279            Some(t) => t,
280            None => {
281                fallback_theme = MacTheme::default();
282                &fallback_theme
283            }
284        };
285
286        let metrics = theme.stack_view();
287        let spacing = self
288            .spacing
289            .unwrap_or_else(|| metrics.default_spacing.points());
290        let padding = self
291            .padding
292            .unwrap_or_else(|| metrics.edge_padding.points());
293        let separator_thickness = metrics.separator_thickness.points();
294
295        let available = ui.available_rect_before_wrap();
296        let target_w = self.width.unwrap_or(available.width());
297        let target_h = self.height.unwrap_or(available.height());
298        let container_rect = Rect::from_min_size(available.min, Vec2::new(target_w, target_h));
299
300        let inner_rect = container_rect.shrink(padding);
301
302        let mut child_ui = match self.orientation {
303            MacStackOrientation::Vertical => {
304                let layout = egui::Layout::top_down(match self.alignment {
305                    MacStackAlignment::Leading => egui::Align::Min,
306                    MacStackAlignment::Center => egui::Align::Center,
307                    MacStackAlignment::Trailing => egui::Align::Max,
308                });
309                ui.new_child(UiBuilder::new().max_rect(inner_rect).layout(layout))
310            }
311            MacStackOrientation::Horizontal => {
312                let layout = egui::Layout::left_to_right(match self.alignment {
313                    MacStackAlignment::Leading => egui::Align::Min,
314                    MacStackAlignment::Center => egui::Align::Center,
315                    MacStackAlignment::Trailing => egui::Align::Max,
316                });
317                ui.new_child(UiBuilder::new().max_rect(inner_rect).layout(layout))
318            }
319        };
320
321        let mut stack_ui = MacStackUi {
322            ui: &mut child_ui,
323            theme,
324            orientation: self.orientation,
325            spacing,
326            separator_thickness,
327            show_separators: self.show_separators,
328            container_height: self.height,
329            padding,
330            item_count: 0,
331            section_count: 0,
332        };
333
334        let inner = add_contents(&mut stack_ui);
335        let items_rect = stack_ui.ui.min_rect();
336        let content_w = if items_rect.is_positive() {
337            items_rect.width() + padding * 2.0
338        } else {
339            padding * 2.0
340        };
341        let content_h = if items_rect.is_positive() {
342            items_rect.height() + padding * 2.0
343        } else {
344            padding * 2.0
345        };
346        let final_w = self.width.unwrap_or(content_w).max(content_w);
347        let final_h = self.height.unwrap_or(content_h).max(content_h);
348        let final_rect = Rect::from_min_size(container_rect.min, Vec2::new(final_w, final_h));
349
350        ui.allocate_rect(final_rect, egui::Sense::hover());
351
352        MacStackViewOutput {
353            inner,
354            rect: final_rect,
355            item_count: stack_ui.item_count,
356            section_count: stack_ui.section_count,
357        }
358    }
359}
egui_macview/layout/stack_view.rs

egui_macview/layout/
stack_view.rs
