Skip to main content

rcus_core/
view.rs

1use std::sync::Arc;
2
3use crate::style::{Axis, Size, Style};
4
5pub type RowRenderer = Arc<dyn Fn(usize) -> ViewNode + Send + Sync>;
6
7/// The retained view description a host builds and the layout engine consumes.
8/// Script runtimes produce the same tree from JSON, so the renderer never needs
9/// to know which frontend authored a frame.
10#[derive(Clone)]
11pub enum ViewNode {
12    Element {
13        id: String,
14        style: Style,
15        axis: Axis,
16        children: Vec<ViewNode>,
17    },
18    Text {
19        id: String,
20        text: String,
21        style: Style,
22    },
23    VirtualRows {
24        id: String,
25        count: usize,
26        style: Style,
27        /// First visible source row, driven by host scroll state.
28        first: usize,
29        render: RowRenderer,
30    },
31}
32
33impl ViewNode {
34    pub fn element(id: impl Into<String>, style: Style, children: Vec<ViewNode>) -> Self {
35        Self::Element {
36            id: id.into(),
37            style,
38            axis: Axis::Column,
39            children,
40        }
41    }
42
43    pub fn row_element(id: impl Into<String>, style: Style, children: Vec<ViewNode>) -> Self {
44        Self::Element {
45            id: id.into(),
46            style,
47            axis: Axis::Row,
48            children,
49        }
50    }
51
52    pub fn column(children: Vec<ViewNode>) -> Self {
53        Self::Element {
54            id: "column".into(),
55            style: Style::default(),
56            axis: Axis::Column,
57            children,
58        }
59    }
60
61    pub fn row(children: Vec<ViewNode>) -> Self {
62        Self::Element {
63            id: "row".into(),
64            style: Style::default(),
65            axis: Axis::Row,
66            children,
67        }
68    }
69
70    pub fn text(text: impl Into<String>, style: Style) -> Self {
71        Self::Text {
72            id: "text".into(),
73            text: text.into(),
74            style,
75        }
76    }
77
78    /// A text node with a stable id, which is what hit testing and focus use.
79    pub fn text_node(id: impl Into<String>, text: impl Into<String>, style: Style) -> Self {
80        Self::Text {
81            id: id.into(),
82            text: text.into(),
83            style,
84        }
85    }
86
87    pub fn empty(style: Style) -> Self {
88        Self::Element {
89            id: "empty".into(),
90            style,
91            axis: Axis::Column,
92            children: Vec::new(),
93        }
94    }
95
96    pub fn virtual_rows(
97        count: usize,
98        style: Style,
99        render: impl Fn(usize) -> ViewNode + Send + Sync + 'static,
100    ) -> Self {
101        Self::virtual_rows_named("virtual-rows", 0, count, style, render)
102    }
103
104    /// A virtual list scrolled to a starting row.
105    pub fn virtual_rows_from(
106        first: usize,
107        count: usize,
108        style: Style,
109        render: impl Fn(usize) -> ViewNode + Send + Sync + 'static,
110    ) -> Self {
111        Self::virtual_rows_named("virtual-rows", first, count, style, render)
112    }
113
114    /// A virtual list with an addressable id, so a host can scroll it in place
115    /// with [`ViewNode::scroll_virtual_rows`] instead of rebuilding the tree.
116    ///
117    /// A virtual list always fills its parent on the main axis: it is a
118    /// scrollback panel, and the window is derived from the space it is given.
119    pub fn virtual_rows_named(
120        id: impl Into<String>,
121        first: usize,
122        count: usize,
123        mut style: Style,
124        render: impl Fn(usize) -> ViewNode + Send + Sync + 'static,
125    ) -> Self {
126        style.fill = true;
127        Self::VirtualRows {
128            id: id.into(),
129            count,
130            style,
131            first: first.min(count.saturating_sub(1)),
132            render: Arc::new(render),
133        }
134    }
135
136    /// Rewrites the window start of a virtual list, so scrolling only rebuilds
137    /// the rows the user can actually see.
138    pub fn scroll_virtual_rows(&mut self, id: &str, first: usize) -> bool {
139        match self {
140            Self::VirtualRows {
141                id: node_id,
142                count,
143                first: start,
144                ..
145            } if node_id == id => {
146                let clamped = first.min(count.saturating_sub(1));
147                if *start == clamped {
148                    return false;
149                }
150                *start = clamped;
151                true
152            }
153            Self::Element { children, .. } => children
154                .iter_mut()
155                .any(|child| child.scroll_virtual_rows(id, first)),
156            Self::Text { .. } | Self::VirtualRows { .. } => false,
157        }
158    }
159
160    /// Visits every node, parents before children, which is the paint order.
161    pub fn for_each(&self, visit: &mut dyn FnMut(&ViewNode)) {
162        visit(self);
163        match self {
164            Self::Element { children, .. } => {
165                for child in children {
166                    child.for_each(visit);
167                }
168            }
169            Self::Text { .. } => {}
170            Self::VirtualRows { .. } => {}
171        }
172    }
173
174    /// Total node count, including every materialized virtual row.
175    pub fn node_count(&self) -> usize {
176        let mut count = 0;
177        self.for_each(&mut |_| count += 1);
178        count
179    }
180}
181
182/// A paint-order node, produced by the layout engine and consumed by renderers.
183#[derive(Clone, Copy, Debug, PartialEq, Eq)]
184pub enum NodeKind {
185    Element,
186    Text,
187    VirtualRow,
188}
189
190/// JSON shape accepted from script runtimes. Kept separate from `ViewNode` so
191/// the host owns style defaults and script cannot smuggle in a closure.
192#[derive(Clone, Debug, serde::Deserialize)]
193#[serde(tag = "kind", rename_all = "lowercase")]
194pub enum ViewSpec {
195    Element {
196        id: Option<String>,
197        #[serde(default)]
198        style: Option<Style>,
199        #[serde(default)]
200        row: bool,
201        #[serde(default)]
202        children: Vec<ViewSpec>,
203    },
204    Text {
205        id: Option<String>,
206        #[serde(default)]
207        style: Option<Style>,
208        text: String,
209    },
210    Rows {
211        id: Option<String>,
212        #[serde(default)]
213        style: Option<Style>,
214        count: usize,
215        #[serde(default)]
216        first: usize,
217        /// Materialized rows, used when a host renders a bounded list eagerly.
218        #[serde(default)]
219        rows: Vec<ViewSpec>,
220    },
221}
222
223impl ViewSpec {
224    /// Converts a script-authored spec into a retained node. Virtual row bodies
225    /// beyond the supplied rows render as empty placeholders, so a list never
226    /// has to cross the language boundary in full.
227    pub fn into_node(self) -> ViewNode {
228        match self {
229            ViewSpec::Element {
230                id,
231                style,
232                row,
233                children,
234            } => {
235                let style = style.unwrap_or_default();
236                let axis = if row { Axis::Row } else { Axis::Column };
237                let children = children.into_iter().map(ViewSpec::into_node).collect();
238                ViewNode::Element {
239                    id: id.unwrap_or_else(|| "element".into()),
240                    style,
241                    axis,
242                    children,
243                }
244            }
245            ViewSpec::Text { id, style, text } => ViewNode::Text {
246                id: id.unwrap_or_else(|| "text".into()),
247                text,
248                style: style.unwrap_or_default(),
249            },
250            ViewSpec::Rows {
251                id,
252                style,
253                count,
254                first,
255                rows,
256            } => {
257                let mut style = style.unwrap_or_default();
258                // Same rule as `virtual_rows_named`: a list fills its parent.
259                style.fill = true;
260                let row_height = style.row_height;
261                let rows: Vec<ViewNode> = rows.into_iter().map(ViewSpec::into_node).collect();
262                ViewNode::VirtualRows {
263                    id: id.unwrap_or_else(|| "rows".into()),
264                    count,
265                    style,
266                    first: first.min(count.saturating_sub(1)),
267                    render: Arc::new(move |index| {
268                        rows.get(index).cloned().unwrap_or_else(|| {
269                            ViewNode::empty(Style {
270                                size: Some(Size::new(0.0, row_height)),
271                                ..Style::default()
272                            })
273                        })
274                    }),
275                }
276            }
277        }
278    }
279}