Skip to main content

fc_ui/capabilities/layout/
mod.rs

1//! Reusable layout containers and composition primitives.
2
3use gpui::*;
4
5#[derive(Debug, Clone, Copy, PartialEq, Eq)]
6pub enum Align {
7    Start,
8    Center,
9    End,
10    Stretch,
11}
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum Justify {
15    Start,
16    Center,
17    End,
18    Between,
19    Around,
20    Evenly,
21}
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub enum FlowDirection {
25    Horizontal,
26    Vertical,
27}
28
29pub struct VStack {
30    base: Div,
31    spacing: Option<Pixels>,
32    align: Option<Align>,
33}
34
35impl Default for VStack {
36    fn default() -> Self {
37        Self::new()
38    }
39}
40
41impl VStack {
42    pub fn new() -> Self {
43        Self {
44            base: div().flex().flex_col(),
45            spacing: None,
46            align: None,
47        }
48    }
49
50    pub fn spacing(mut self, spacing: impl Into<Pixels>) -> Self {
51        self.spacing = Some(spacing.into());
52        self
53    }
54
55    pub fn gap(self, gap: impl Into<Pixels>) -> Self {
56        self.spacing(gap)
57    }
58
59    pub fn align(mut self, align: Align) -> Self {
60        self.align = Some(align);
61        self
62    }
63
64    pub fn fill(mut self) -> Self {
65        self.base = self.base.size_full();
66        self
67    }
68
69    pub fn fill_width(mut self) -> Self {
70        self.base = self.base.w_full();
71        self
72    }
73
74    pub fn fill_height(mut self) -> Self {
75        self.base = self.base.h_full();
76        self
77    }
78
79    pub fn grow(mut self) -> Self {
80        self.base = self.base.flex_1();
81        self
82    }
83
84    pub fn padding(mut self, padding: impl Into<Pixels>) -> Self {
85        self.base = self.base.p(padding.into());
86        self
87    }
88
89    pub fn items_center(mut self) -> Self {
90        self.align = Some(Align::Center);
91        self
92    }
93}
94
95impl ParentElement for VStack {
96    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
97        self.base.extend(elements);
98    }
99}
100
101impl Styled for VStack {
102    fn style(&mut self) -> &mut StyleRefinement {
103        self.base.style()
104    }
105}
106
107impl InteractiveElement for VStack {
108    fn interactivity(&mut self) -> &mut Interactivity {
109        self.base.interactivity()
110    }
111}
112
113impl StatefulInteractiveElement for VStack {}
114
115impl IntoElement for VStack {
116    type Element = Div;
117
118    fn into_element(mut self) -> Self::Element {
119        if let Some(spacing) = self.spacing {
120            self.base = self.base.gap(spacing);
121        }
122
123        if let Some(align) = self.align {
124            self.base = match align {
125                Align::Start => self.base.items_start(),
126                Align::Center => self.base.items_center(),
127                Align::End => self.base.items_end(),
128                Align::Stretch => self.base,
129            };
130        }
131
132        self.base
133    }
134}
135
136pub struct HStack {
137    base: Div,
138    spacing: Option<Pixels>,
139    align: Option<Align>,
140    justify: Option<Justify>,
141}
142
143impl Default for HStack {
144    fn default() -> Self {
145        Self::new()
146    }
147}
148
149impl HStack {
150    pub fn new() -> Self {
151        Self {
152            base: div().flex().flex_row(),
153            spacing: None,
154            align: None,
155            justify: None,
156        }
157    }
158
159    pub fn spacing(mut self, spacing: impl Into<Pixels>) -> Self {
160        self.spacing = Some(spacing.into());
161        self
162    }
163
164    pub fn gap(self, gap: impl Into<Pixels>) -> Self {
165        self.spacing(gap)
166    }
167
168    pub fn align(mut self, align: Align) -> Self {
169        self.align = Some(align);
170        self
171    }
172
173    pub fn justify(mut self, justify: Justify) -> Self {
174        self.justify = Some(justify);
175        self
176    }
177
178    pub fn fill(mut self) -> Self {
179        self.base = self.base.size_full();
180        self
181    }
182
183    pub fn fill_width(mut self) -> Self {
184        self.base = self.base.w_full();
185        self
186    }
187
188    pub fn fill_height(mut self) -> Self {
189        self.base = self.base.h_full();
190        self
191    }
192
193    pub fn grow(mut self) -> Self {
194        self.base = self.base.flex_1();
195        self
196    }
197
198    pub fn padding(mut self, padding: impl Into<Pixels>) -> Self {
199        self.base = self.base.p(padding.into());
200        self
201    }
202
203    pub fn items_center(mut self) -> Self {
204        self.align = Some(Align::Center);
205        self
206    }
207
208    pub fn space_between(mut self) -> Self {
209        self.justify = Some(Justify::Between);
210        self
211    }
212}
213
214impl ParentElement for HStack {
215    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
216        self.base.extend(elements);
217    }
218}
219
220impl Styled for HStack {
221    fn style(&mut self) -> &mut StyleRefinement {
222        self.base.style()
223    }
224}
225
226impl InteractiveElement for HStack {
227    fn interactivity(&mut self) -> &mut Interactivity {
228        self.base.interactivity()
229    }
230}
231
232impl StatefulInteractiveElement for HStack {}
233
234impl IntoElement for HStack {
235    type Element = Div;
236
237    fn into_element(mut self) -> Self::Element {
238        if let Some(spacing) = self.spacing {
239            self.base = self.base.gap(spacing);
240        }
241
242        if let Some(align) = self.align {
243            self.base = match align {
244                Align::Start => self.base.items_start(),
245                Align::Center => self.base.items_center(),
246                Align::End => self.base.items_end(),
247                Align::Stretch => self.base,
248            };
249        }
250
251        if let Some(justify) = self.justify {
252            self.base = match justify {
253                Justify::Start => self.base.justify_start(),
254                Justify::Center => self.base.justify_center(),
255                Justify::End => self.base.justify_end(),
256                Justify::Between => self.base.justify_between(),
257                Justify::Around => self.base.justify_around(),
258                Justify::Evenly => {
259                    // Styled has no justify_evenly() helper, but taffy supports it
260                    let mut base = self.base;
261                    base.style().justify_content = Some(JustifyContent::SpaceEvenly);
262                    base
263                }
264            };
265        }
266
267        self.base
268    }
269}
270
271pub struct Flow {
272    base: Div,
273    direction: FlowDirection,
274    spacing: Option<Pixels>,
275    align: Option<Align>,
276}
277
278impl Default for Flow {
279    fn default() -> Self {
280        Self::new()
281    }
282}
283
284impl Flow {
285    pub fn new() -> Self {
286        Self {
287            base: div().flex().flex_wrap(),
288            direction: FlowDirection::Horizontal,
289            spacing: None,
290            align: None,
291        }
292    }
293
294    pub fn direction(mut self, direction: FlowDirection) -> Self {
295        self.direction = direction;
296        self
297    }
298
299    pub fn spacing(mut self, spacing: impl Into<Pixels>) -> Self {
300        self.spacing = Some(spacing.into());
301        self
302    }
303
304    pub fn align(mut self, align: Align) -> Self {
305        self.align = Some(align);
306        self
307    }
308}
309
310impl ParentElement for Flow {
311    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
312        self.base.extend(elements);
313    }
314}
315
316impl Styled for Flow {
317    fn style(&mut self) -> &mut StyleRefinement {
318        self.base.style()
319    }
320}
321
322impl InteractiveElement for Flow {
323    fn interactivity(&mut self) -> &mut Interactivity {
324        self.base.interactivity()
325    }
326}
327
328impl StatefulInteractiveElement for Flow {}
329
330impl IntoElement for Flow {
331    type Element = Div;
332
333    fn into_element(mut self) -> Self::Element {
334        self.base = match self.direction {
335            FlowDirection::Horizontal => self.base.flex_row(),
336            FlowDirection::Vertical => self.base.flex_col(),
337        };
338
339        if let Some(spacing) = self.spacing {
340            self.base = self.base.gap(spacing);
341        }
342
343        if let Some(align) = self.align {
344            self.base = match align {
345                Align::Start => self.base.items_start(),
346                Align::Center => self.base.items_center(),
347                Align::End => self.base.items_end(),
348                Align::Stretch => self.base,
349            };
350        }
351
352        self.base
353    }
354}
355
356pub struct Grid {
357    base: Div,
358    columns: usize,
359    gap: Option<Pixels>,
360    grid_children: Vec<AnyElement>,
361}
362
363impl Default for Grid {
364    fn default() -> Self {
365        Self::new()
366    }
367}
368
369impl Grid {
370    pub fn new() -> Self {
371        Self {
372            base: div().flex().flex_col(),
373            columns: 1,
374            gap: None,
375            grid_children: vec![],
376        }
377    }
378
379    pub fn columns(mut self, columns: usize) -> Self {
380        self.columns = columns.max(1);
381        self
382    }
383
384    pub fn gap(mut self, gap: impl Into<Pixels>) -> Self {
385        self.gap = Some(gap.into());
386        self
387    }
388}
389
390impl ParentElement for Grid {
391    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
392        self.grid_children.extend(elements);
393    }
394}
395
396impl Styled for Grid {
397    fn style(&mut self) -> &mut StyleRefinement {
398        self.base.style()
399    }
400}
401
402impl InteractiveElement for Grid {
403    fn interactivity(&mut self) -> &mut Interactivity {
404        self.base.interactivity()
405    }
406}
407
408impl StatefulInteractiveElement for Grid {}
409
410impl IntoElement for Grid {
411    type Element = Div;
412
413    fn into_element(mut self) -> Self::Element {
414        if let Some(gap) = self.gap {
415            self.base = self.base.gap(gap);
416        }
417
418        let total_children = self.grid_children.len();
419        let mut rows = vec![];
420        let mut current_row = vec![];
421
422        for (i, child) in self.grid_children.into_iter().enumerate() {
423            current_row.push(child);
424            if (i + 1) % self.columns == 0 || i == total_children - 1 {
425                rows.push(current_row);
426                current_row = vec![];
427            }
428        }
429
430        for row_children in rows {
431            let mut row = div().flex().flex_row().w_full();
432
433            if let Some(gap) = self.gap {
434                row = row.gap(gap);
435            }
436
437            let cell_count = row_children.len();
438            for child in row_children {
439                row = row.child(div().flex_1().child(child));
440            }
441            // Pad the final row so its cells keep the same width as full rows
442            for _ in cell_count..self.columns {
443                row = row.child(div().flex_1());
444            }
445
446            self.base = self.base.child(row);
447        }
448
449        self.base
450    }
451}
452
453pub struct Cluster {
454    base: Div,
455    spacing: Option<Pixels>,
456    align: Option<Align>,
457}
458
459impl Default for Cluster {
460    fn default() -> Self {
461        Self::new()
462    }
463}
464
465impl Cluster {
466    pub fn new() -> Self {
467        Self {
468            base: div().flex().flex_row(),
469            spacing: None,
470            align: None,
471        }
472    }
473
474    pub fn spacing(mut self, spacing: impl Into<Pixels>) -> Self {
475        self.spacing = Some(spacing.into());
476        self
477    }
478
479    pub fn align(mut self, align: Align) -> Self {
480        self.align = Some(align);
481        self
482    }
483}
484
485impl ParentElement for Cluster {
486    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
487        self.base.extend(elements);
488    }
489}
490
491impl Styled for Cluster {
492    fn style(&mut self) -> &mut StyleRefinement {
493        self.base.style()
494    }
495}
496
497impl InteractiveElement for Cluster {
498    fn interactivity(&mut self) -> &mut Interactivity {
499        self.base.interactivity()
500    }
501}
502
503impl StatefulInteractiveElement for Cluster {}
504
505impl IntoElement for Cluster {
506    type Element = Div;
507
508    fn into_element(mut self) -> Self::Element {
509        if let Some(spacing) = self.spacing {
510            self.base = self.base.gap(spacing);
511        }
512
513        if let Some(align) = self.align {
514            self.base = match align {
515                Align::Start => self.base.items_start(),
516                Align::Center => self.base.items_center(),
517                Align::End => self.base.items_end(),
518                Align::Stretch => self.base,
519            };
520        }
521
522        self.base
523    }
524}
525
526pub struct Spacer {
527    size: Option<Pixels>,
528}
529
530impl Default for Spacer {
531    fn default() -> Self {
532        Self::new()
533    }
534}
535
536impl Spacer {
537    pub fn new() -> Self {
538        Self { size: None }
539    }
540
541    pub fn fixed(size: impl Into<Pixels>) -> Self {
542        Self {
543            size: Some(size.into()),
544        }
545    }
546}
547
548impl IntoElement for Spacer {
549    type Element = Div;
550
551    fn into_element(self) -> Self::Element {
552        if let Some(size) = self.size {
553            div().size(size)
554        } else {
555            div().flex_1()
556        }
557    }
558}
559
560pub struct Panel {
561    base: Div,
562}
563
564impl Default for Panel {
565    fn default() -> Self {
566        Self::new()
567    }
568}
569
570impl Panel {
571    pub fn new() -> Self {
572        Self { base: div() }
573    }
574
575    pub fn card(mut self) -> Self {
576        self.base = self.base.border_1().rounded(px(8.0)).p(px(16.0));
577        self
578    }
579
580    pub fn elevated(mut self) -> Self {
581        self.base = self.base.border_1().rounded(px(8.0));
582        self
583    }
584
585    pub fn section(mut self) -> Self {
586        self.base = self.base.border_b_1().p(px(12.0));
587        self
588    }
589
590    pub fn border(mut self) -> Self {
591        self.base = self.base.border_1();
592        self
593    }
594
595    pub fn rounded(mut self) -> Self {
596        self.base = self.base.rounded(px(8.0));
597        self
598    }
599
600    pub fn padded(mut self) -> Self {
601        self.base = self.base.p(px(16.0));
602        self
603    }
604}
605
606impl ParentElement for Panel {
607    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
608        self.base.extend(elements);
609    }
610}
611
612impl Styled for Panel {
613    fn style(&mut self) -> &mut StyleRefinement {
614        self.base.style()
615    }
616}
617
618impl InteractiveElement for Panel {
619    fn interactivity(&mut self) -> &mut Interactivity {
620        self.base.interactivity()
621    }
622}
623
624impl StatefulInteractiveElement for Panel {}
625
626impl IntoElement for Panel {
627    type Element = Div;
628
629    fn into_element(self) -> Self::Element {
630        self.base
631    }
632}
633
634pub struct Container {
635    base: Div,
636    max_width: Option<Pixels>,
637    centered: bool,
638}
639
640impl Default for Container {
641    fn default() -> Self {
642        Self::new()
643    }
644}
645
646impl Container {
647    pub fn new() -> Self {
648        Self {
649            base: div().w_full(),
650            max_width: None,
651            centered: false,
652        }
653    }
654
655    pub fn max_w(mut self, width: impl Into<Pixels>) -> Self {
656        self.max_width = Some(width.into());
657        self
658    }
659
660    pub fn centered(mut self) -> Self {
661        self.centered = true;
662        self
663    }
664
665    pub fn sm() -> Self {
666        Self::new().max_w(px(640.0)).centered()
667    }
668
669    pub fn md() -> Self {
670        Self::new().max_w(px(768.0)).centered()
671    }
672
673    pub fn lg() -> Self {
674        Self::new().max_w(px(1024.0)).centered()
675    }
676
677    pub fn xl() -> Self {
678        Self::new().max_w(px(1280.0)).centered()
679    }
680
681    pub fn xxl() -> Self {
682        Self::new().max_w(px(1536.0)).centered()
683    }
684}
685
686impl ParentElement for Container {
687    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
688        self.base.extend(elements);
689    }
690}
691
692impl Styled for Container {
693    fn style(&mut self) -> &mut StyleRefinement {
694        self.base.style()
695    }
696}
697
698impl InteractiveElement for Container {
699    fn interactivity(&mut self) -> &mut Interactivity {
700        self.base.interactivity()
701    }
702}
703
704impl StatefulInteractiveElement for Container {}
705
706impl IntoElement for Container {
707    type Element = Div;
708
709    fn into_element(mut self) -> Self::Element {
710        if let Some(max_width) = self.max_width {
711            self.base = self.base.max_w(max_width);
712        }
713
714        if self.centered {
715            self.base = self.base.mx_auto();
716        }
717
718        self.base
719    }
720}
721
722pub struct MasonryItem {
723    element: AnyElement,
724    estimated_height: f32,
725}
726
727impl MasonryItem {
728    pub fn new(element: impl IntoElement, estimated_height: f32) -> Self {
729        Self {
730            element: element.into_any_element(),
731            estimated_height,
732        }
733    }
734}
735
736pub struct MasonryGrid {
737    base: Div,
738    columns: usize,
739    gap: Option<Pixels>,
740    default_estimated_height: f32,
741    items: Vec<MasonryItem>,
742}
743
744impl Default for MasonryGrid {
745    fn default() -> Self {
746        Self::new()
747    }
748}
749
750impl MasonryGrid {
751    pub fn new() -> Self {
752        Self {
753            base: div().flex().flex_row(),
754            columns: 3,
755            gap: None,
756            default_estimated_height: 100.0,
757            items: vec![],
758        }
759    }
760
761    pub fn columns(mut self, columns: usize) -> Self {
762        self.columns = columns.max(1);
763        self
764    }
765
766    pub fn gap(mut self, gap: impl Into<Pixels>) -> Self {
767        self.gap = Some(gap.into());
768        self
769    }
770
771    /// Estimated height used to place items added without an explicit height
772    /// (via `child()`/`extend()`). Defaults to 100px.
773    pub fn default_estimated_height(mut self, height: f32) -> Self {
774        self.default_estimated_height = height;
775        self
776    }
777
778    pub fn fill(mut self) -> Self {
779        self.base = self.base.size_full();
780        self
781    }
782
783    pub fn fill_width(mut self) -> Self {
784        self.base = self.base.w_full();
785        self
786    }
787
788    pub fn item(mut self, element: impl IntoElement, estimated_height: f32) -> Self {
789        self.items.push(MasonryItem::new(element, estimated_height));
790        self
791    }
792
793    pub fn items<I, E>(mut self, items: I) -> Self
794    where
795        I: IntoIterator<Item = (E, f32)>,
796        E: IntoElement,
797    {
798        for (element, height) in items {
799            self.items.push(MasonryItem::new(element, height));
800        }
801        self
802    }
803}
804
805impl ParentElement for MasonryGrid {
806    /// Items added through `child()`/`extend()` carry no explicit height and are
807    /// placed using `default_estimated_height` (100px unless configured).
808    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
809        let estimated_height = self.default_estimated_height;
810        for element in elements {
811            self.items.push(MasonryItem {
812                element,
813                estimated_height,
814            });
815        }
816    }
817}
818
819impl Styled for MasonryGrid {
820    fn style(&mut self) -> &mut StyleRefinement {
821        self.base.style()
822    }
823}
824
825impl InteractiveElement for MasonryGrid {
826    fn interactivity(&mut self) -> &mut Interactivity {
827        self.base.interactivity()
828    }
829}
830
831impl StatefulInteractiveElement for MasonryGrid {}
832
833impl IntoElement for MasonryGrid {
834    type Element = Div;
835
836    fn into_element(mut self) -> Self::Element {
837        if let Some(gap) = self.gap {
838            self.base = self.base.gap(gap);
839        }
840
841        let mut column_heights: Vec<f32> = vec![0.0; self.columns];
842        let mut column_items: Vec<Vec<AnyElement>> =
843            (0..self.columns).map(|_| Vec::new()).collect();
844
845        let gap_value: f32 = self.gap.map(f32::from).unwrap_or(0.0);
846
847        for item in self.items {
848            let min_column = column_heights
849                .iter()
850                .enumerate()
851                .min_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
852                .map(|(idx, _)| idx)
853                .unwrap_or(0);
854
855            if !column_items[min_column].is_empty() {
856                column_heights[min_column] += gap_value;
857            }
858            column_heights[min_column] += item.estimated_height;
859            column_items[min_column].push(item.element);
860        }
861
862        for column_children in column_items {
863            let mut column = div().flex().flex_col().flex_1();
864
865            if let Some(gap) = self.gap {
866                column = column.gap(gap);
867            }
868
869            for child in column_children {
870                column = column.child(child);
871            }
872
873            self.base = self.base.child(column);
874        }
875
876        self.base
877    }
878}
879
880#[cfg(test)]
881mod tests {
882    use super::{HStack, VStack};
883    use gpui::{div, prelude::*, px, size, Context, Render, TestAppContext, Window};
884
885    #[derive(Clone, Copy)]
886    enum RootDirection {
887        Vertical,
888        Horizontal,
889    }
890
891    struct AutoSizedRootView {
892        direction: RootDirection,
893    }
894
895    impl Render for AutoSizedRootView {
896        fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
897            match self.direction {
898                RootDirection::Vertical => VStack::new()
899                    .debug_selector(|| "auto-sized-stack-root".into())
900                    .child(div().size_full())
901                    .into_any_element(),
902                RootDirection::Horizontal => HStack::new()
903                    .debug_selector(|| "auto-sized-stack-root".into())
904                    .child(div().size_full())
905                    .into_any_element(),
906            }
907        }
908    }
909
910    fn assert_auto_sized_root_fills_viewport(direction: RootDirection, cx: &mut TestAppContext) {
911        let (_, cx) = cx.add_window_view(move |_, _| AutoSizedRootView { direction });
912
913        cx.update(|window, cx| window.draw(cx).clear());
914        let initial_viewport = cx.update(|window, _| window.viewport_size());
915        let initial_root = cx
916            .debug_bounds("auto-sized-stack-root")
917            .expect("the stack root should expose its bounds");
918        assert_eq!(initial_root.size, initial_viewport);
919
920        let resized_viewport = size(px(640.0), px(360.0));
921        cx.simulate_resize(resized_viewport);
922        cx.update(|window, cx| window.draw(cx).clear());
923        let resized_root = cx
924            .debug_bounds("auto-sized-stack-root")
925            .expect("the resized stack root should expose its bounds");
926        assert_eq!(resized_root.size, resized_viewport);
927    }
928
929    #[gpui::test]
930    fn vstack_direct_window_root_fills_the_viewport(cx: &mut TestAppContext) {
931        assert_auto_sized_root_fills_viewport(RootDirection::Vertical, cx);
932    }
933
934    #[gpui::test]
935    fn hstack_direct_window_root_fills_the_viewport(cx: &mut TestAppContext) {
936        assert_auto_sized_root_fills_viewport(RootDirection::Horizontal, cx);
937    }
938}