Skip to main content

gpui_base/
progress.rs

1use gpui::{
2    AnyElement, App, Div, ElementId, InteractiveElement, Interactivity, IntoElement, ParentElement,
3    RenderOnce, Role, SharedString, StatefulInteractiveElement, StyleRefinement, Styled, Window,
4    div, prelude::FluentBuilder as _,
5};
6use smallvec::SmallVec;
7
8/// An unstyled linear progress root with controlled value accessibility.
9#[derive(IntoElement)]
10pub struct Progress {
11    base: gpui::Stateful<Div>,
12    style: StyleRefinement,
13    value: f32,
14    indeterminate: bool,
15    accessibility_label: Option<SharedString>,
16    children: SmallVec<[AnyElement; 2]>,
17}
18
19impl Progress {
20    pub fn new(id: impl Into<ElementId>) -> Self {
21        Self {
22            base: div().id(id),
23            style: StyleRefinement::default(),
24            value: 0.,
25            indeterminate: false,
26            accessibility_label: None,
27            children: SmallVec::new(),
28        }
29    }
30
31    /// Sets the controlled percentage value, clamped to `0..=100`.
32    pub fn value(mut self, value: f32) -> Self {
33        self.value = value.clamp(0., 100.);
34        self
35    }
36
37    pub fn indeterminate(mut self, indeterminate: bool) -> Self {
38        self.indeterminate = indeterminate;
39        self
40    }
41
42    pub fn accessibility_label(mut self, label: impl Into<SharedString>) -> Self {
43        self.accessibility_label = Some(label.into());
44        self
45    }
46}
47
48impl Styled for Progress {
49    fn style(&mut self) -> &mut StyleRefinement {
50        &mut self.style
51    }
52}
53
54impl ParentElement for Progress {
55    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
56        self.children.extend(elements);
57    }
58}
59
60impl InteractiveElement for Progress {
61    fn interactivity(&mut self) -> &mut Interactivity {
62        self.base.interactivity()
63    }
64}
65
66impl StatefulInteractiveElement for Progress {}
67
68impl RenderOnce for Progress {
69    fn render(self, _: &mut Window, _: &mut App) -> impl IntoElement {
70        self.base
71            .role(Role::ProgressIndicator)
72            .when_some(self.accessibility_label, |this, label| {
73                this.aria_label(label)
74            })
75            .aria_min_numeric_value(0.)
76            .aria_max_numeric_value(100.)
77            .when(!self.indeterminate, |this| {
78                this.aria_numeric_value(self.value as f64)
79            })
80            .children(self.children)
81            .refine_style(&self.style)
82    }
83}
84
85macro_rules! progress_part {
86    ($name:ident, $docs:literal) => {
87        #[doc = $docs]
88        #[derive(IntoElement)]
89        pub struct $name {
90            base: Div,
91            style: StyleRefinement,
92            children: SmallVec<[AnyElement; 1]>,
93        }
94
95        impl $name {
96            pub fn new() -> Self {
97                Self {
98                    base: div(),
99                    style: StyleRefinement::default(),
100                    children: SmallVec::new(),
101                }
102            }
103        }
104
105        impl Styled for $name {
106            fn style(&mut self) -> &mut StyleRefinement {
107                &mut self.style
108            }
109        }
110
111        impl ParentElement for $name {
112            fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
113                self.children.extend(elements);
114            }
115        }
116
117        impl RenderOnce for $name {
118            fn render(self, _: &mut Window, _: &mut App) -> impl IntoElement {
119                self.base.children(self.children).refine_style(&self.style)
120            }
121        }
122    };
123}
124
125progress_part!(ProgressTrack, "An unstyled progress track.");
126progress_part!(ProgressIndicator, "An unstyled progress indicator.");
127
128#[cfg(test)]
129mod tests {
130    use super::*;
131    use gpui::{Element as _, accesskit};
132
133    #[gpui::test]
134    fn clamps_and_projects_numeric_accessibility(cx: &mut gpui::TestAppContext) {
135        let window = cx.add_empty_window();
136        window.update(|window, cx| {
137            let mut node = accesskit::Node::new(Role::ProgressIndicator);
138            Progress::new("progress")
139                .value(120.)
140                .render(window, cx)
141                .into_element()
142                .write_a11y_info(&mut node);
143
144            assert_eq!(node.numeric_value(), Some(100.));
145            assert_eq!(node.min_numeric_value(), Some(0.));
146            assert_eq!(node.max_numeric_value(), Some(100.));
147        });
148    }
149
150    #[gpui::test]
151    fn indeterminate_progress_omits_numeric_value(cx: &mut gpui::TestAppContext) {
152        let window = cx.add_empty_window();
153        window.update(|window, cx| {
154            let mut node = accesskit::Node::new(Role::ProgressIndicator);
155            Progress::new("loading")
156                .value(40.)
157                .indeterminate(true)
158                .render(window, cx)
159                .into_element()
160                .write_a11y_info(&mut node);
161
162            assert_eq!(node.numeric_value(), None);
163        });
164    }
165
166    #[gpui::test]
167    fn progress_projects_its_accessible_name(cx: &mut gpui::TestAppContext) {
168        let window = cx.add_empty_window();
169        window.update(|window, cx| {
170            let mut node = accesskit::Node::new(Role::ProgressIndicator);
171            Progress::new("download")
172                .accessibility_label("Downloading release")
173                .render(window, cx)
174                .into_element()
175                .write_a11y_info(&mut node);
176
177            assert_eq!(node.label(), Some("Downloading release"));
178        });
179    }
180}