makeover_webview/list.rs
1//! The classes a list's or a table's columns, rows and cells carry.
2//!
3//! The row and cell markup is drawn by the quasi hosts (`quasi-webview` for
4//! this renderer), which own the column and cell members of the vocabulary.
5//! What stays here is the naming those hosts write into markup and the
6//! generated stylesheet rules: a column's name as a class
7//! ([`push_column_name`]), the kind, part and flow classes, the cell wrapper
8//! ([`CELL_IN`]) and sizer ([`push_sizer`]), the `short-N` ladder
9//! ([`SHORT_RUNGS`]), and the class lists the vocabulary is checked against.
10//!
11//! # Why positions are the bug
12//!
13//! goingson hid its mobile columns with `nth-child(n+5)` against a
14//! seven-column table, plus a separate `nth-child(3)`, plus two class-based
15//! rules, the same fact said three ways, two of them positional. Insert a
16//! column anywhere left of the cut and the wrong one disappears, silently,
17//! because nothing in the stylesheet knows what column five *is*.
18//! [`Priority`](makeover_layout::Priority) is the fix: a renderer narrows by what a column is worth, as a
19//! shrink factor on the column's own class (one of [`CELL_DROP_CLASSES`]), and
20//! never by counting.
21
22use crate::form::Markup;
23use crate::{Emit, push_class};
24use makeover_layout::{CellPart, ColumnKind, Flow, RowPart};
25
26/// A column's name as the identifier half of its class.
27///
28/// # Why this is not escaping
29///
30/// The name is the one app-supplied string this crate puts in a class attribute
31/// rather than in text or an `aria-label`, so it may never go in raw. A column
32/// named `a" onclick="steal()` emitted
33///
34/// ```html
35/// <div class="cell col-a" onclick="steal() cell-fill cell-keeps">
36/// ```
37///
38/// which is a live event handler on every cell of that column. HTML escaping is
39/// the reflex and it is the wrong tool here, because a class is read twice: once
40/// by the HTML parser, which would decode `"` back to a quote, and once by
41/// the CSS selector an app writes against it. An escaped name is safe in the
42/// attribute and unmatchable from the stylesheet, so the two halves would stop
43/// meeting, silently, the way every other defect this module's comments
44/// record did.
45///
46/// Reducing the name to identifier characters answers both. What comes out is a
47/// valid CSS identifier, so the selector matches, and it holds none of the five
48/// characters an attribute value can be ended with, so there is nothing to
49/// escape.
50///
51/// # What it changes for a name that was already fine
52///
53/// Nothing. Alphanumerics, `_` and `-` pass through, and every column name in
54/// the tree is made of those. A name that is *not* was already broken rather
55/// than merely unsafe: `Due date` emitted `col-Due date`, which the HTML parser
56/// reads as the two classes `col-Due` and `date`, and which a selector wrote as
57/// a descendant selector that matched neither. Both now agree on
58/// `col-Due-date`.
59///
60/// Alphanumeric in the Unicode sense, not the ASCII one. CSS identifiers admit
61/// everything from U+00A0 up, so a column named `Größe` keeps its name; folding
62/// it to `Gr--e` would collide with a neighbouring column for nothing.
63pub fn push_column_name(out: &mut String, name: &str) {
64 for ch in name.chars() {
65 // Substituted rather than dropped. Two columns called `a b` and `ab`
66 // are different columns, and dropping would give them one class and one
67 // set of narrowing rules between them.
68 if ch.is_alphanumeric() || ch == '_' || ch == '-' {
69 out.push(ch);
70 } else {
71 out.push('-');
72 }
73 }
74}
75
76/// The class saying what a column holds, or `None` for prose.
77///
78/// wiki `table-model`: the kind carries the look, so the class goes on every
79/// cell and on the heading, and the sheet rules each kind once. Text is the
80/// absence of a kind, as `cell-keeps` would be if a keep needed saying, so it
81/// writes nothing. A kind added upstream reads as text: plain, never missing.
82#[must_use]
83pub fn kind_class(kind: ColumnKind) -> Option<&'static str> {
84 match kind {
85 ColumnKind::Identifier => Some("kind-identifier"),
86 ColumnKind::Date => Some("kind-date"),
87 ColumnKind::Number => Some("kind-number"),
88 ColumnKind::Code => Some("kind-code"),
89 ColumnKind::Status => Some("kind-status"),
90 ColumnKind::Actions => Some("kind-actions"),
91 _ => None,
92 }
93}
94
95/// Every class [`kind_class`] can return.
96pub const KIND_CLASSES: &[&str] = &[
97 "kind-identifier",
98 "kind-date",
99 "kind-number",
100 "kind-code",
101 "kind-status",
102 "kind-actions",
103];
104
105/// The wrapper every cell and heading holds its contents in.
106///
107/// The column is a flex item that may close to nothing, and padding cannot
108/// shrink, so the padding lives on this and the column clips it. It is also
109/// what a droppable column hides when it is under its floor, and where the
110/// type goes, so a heading and the cells under it are the same box whatever
111/// each holds.
112pub const CELL_IN: &str = "cell-in";
113
114/// What a kept column is as wide as, when its floor cannot say.
115///
116/// A floor is a count of `ch`, and a column of controls is not drawn in `ch`.
117/// Measured on MNW's tables at 1440 and 420: a label's letters run 6 to 8px
118/// against the 9px rung while a button's padding and edge take 26px against the
119/// 18 that `quasi_router::screen::ACT_ROOM` allows, so "Add to cart" held 150px
120/// to draw 118 and "Remove" held 96 to draw 99. The first starved the name
121/// beside it to 32px at 420; the second clipped at every width. No constant
122/// fixes both, because the error is the face's and not the count's.
123///
124/// So the host that knows what a column holds writes a copy of it here, once
125/// per distinct run of controls, drawn in the row's own type and taking no
126/// height and no ink. A kept column holding one is as wide as its widest copy,
127/// which the browser measures in the face it draws, and every cell and the
128/// heading hold the same copies, so the column is one width down the table.
129/// Hidden rather than absent: a hidden box still has a width.
130///
131/// Write it with [`push_sizer`] and never by hand, so the wrapper the sheet
132/// rules and the one a host emits cannot be spelled apart.
133pub const CELL_SIZER: &str = "cell-sizer";
134
135/// A [`CELL_SIZER`] around `copies`, which go inside a cell's or a heading's
136/// [`CELL_IN`] after what it holds.
137///
138/// `copies` is the host's: one block per distinct run, each drawn with the
139/// classes and the element the real controls take, since an element rule an
140/// app writes for `button` reaches a copy only if it is one. Nothing in it may
141/// be a control anyone can reach: `aria-hidden` here and `visibility: hidden`
142/// in the sheet take it out of the accessibility tree and the tab order, and a
143/// copy carries no address. Empty writes nothing.
144///
145/// [`Markup`], because the copies are the host's markup and are written as-is.
146pub fn push_sizer(out: &mut String, copies: Markup<'_>, opts: &Emit) {
147 let Markup(copies) = copies;
148 if copies.is_empty() {
149 return;
150 }
151 out.push_str("<span class=\"");
152 push_class(out, CELL_SIZER, opts);
153 out.push_str("\" aria-hidden=\"true\">");
154 out.push_str(copies);
155 out.push_str("</span>");
156}
157
158/// Every class [`part_class`] can return, including the fallback.
159///
160/// Beside the match rather than derived from it, because a `match` over a
161/// `#[non_exhaustive]` enum cannot be enumerated from outside. It carries the
162/// same obligation the match does and a test below holds the two together, so
163/// a new arm added without a new entry fails rather than silently narrowing
164/// what a checker believes this crate can emit.
165pub const ROW_PART_CLASSES: &[&str] = &[
166 "row-primary",
167 "row-secondary",
168 "row-meta",
169 "row-actions",
170 "row-tokens",
171 "row-proportion",
172 "row-part",
173];
174
175/// Every class [`flow_class`] can return.
176///
177/// `Flow::Tight` has no class: one line is what a run already does, so a rule
178/// for it would restate the default on every part in every row. Only the tier
179/// that departs from it is named, which is also why a renderer emitting nothing
180/// for an unknown flow is correct rather than lossy.
181pub const FLOW_CLASSES: &[&str] = &["row-relaxed"];
182
183/// The classes a row inside a hierarchy carries.
184///
185/// Declared here because the generated sheet defines rules for them: the
186/// vocabulary has to say so, or the check that every emitted name has a rule
187/// cannot see them.
188pub const NESTING_CLASSES: &[&str] = &["row-nested", "row-branch", "row-disclose"];
189
190/// The class for a part's flow, if it needs one.
191///
192/// `None` for [`Flow::Tight`] and for any tier added upstream that this crate
193/// has not been taught, which lands as one line: the same trade
194/// [`part_class`]'s fallback makes, and the safe direction, since a part that
195/// grows without bound breaks the rows around it while a part that stays on one
196/// line only looks like the old rendering. Grep this when adopting a new
197/// makeover-layout.
198#[must_use]
199pub fn flow_class(flow: Flow) -> Option<&'static str> {
200 match flow {
201 Flow::Relaxed => Some("row-relaxed"),
202 _ => None,
203 }
204}
205
206/// Every class saying how wide a cell of a column asks to be, including the
207/// fill a column that makes no claim lands on.
208///
209/// See [`ROW_PART_CLASSES`] for why it is written out. Only two of the three
210/// carry a rule, a fill is what a cell does when the sheet says nothing,
211/// which is exactly why the list is here rather than being read off the
212/// generated CSS: `cell-fill` reached every table in the tree and the
213/// vocabulary named it nowhere.
214pub const CELL_WIDTH_CLASSES: &[&str] = &["cell-content", "cell-fixed", "cell-fill"];
215
216/// Every class saying when a cell of a column drops, including the tier that
217/// never does.
218///
219/// The class is a shrink factor: a table short of room takes the shortfall
220/// from the columns worth least, and nothing counts positions or names a
221/// breakpoint.
222///
223/// [`CELL_WIDTH_CLASSES`]' argument, one column property over: `cell-keeps` is
224/// the tier the narrowing never hides, so the sheet writes no rule for it and
225/// a scraped set cannot see it.
226pub const CELL_DROP_CLASSES: &[&str] = &["cell-drops-first", "cell-drops-next", "cell-keeps"];
227
228/// The rungs of the `short-N` ladder, in `rem`: the narrowest and widest table
229/// width it can say, and the step between two.
230///
231/// Two `rem` a step, so a table is marked short at most 32px before its
232/// essentials actually stop fitting, which is well inside the one gap of slack
233/// every floor already carries. A table needing more than the ceiling is wider
234/// than any pane the apps draw, and gets no class.
235pub const SHORT_RUNGS: (u16, u16, u16) = (8, 160, 2);
236
237/// Every class [`cell_part_class`] can return, including the fallback.
238///
239/// See [`ROW_PART_CLASSES`] for why it is written out.
240pub const CELL_PART_CLASSES: &[&str] = &[
241 "cell-value",
242 "cell-tokens",
243 "cell-actions",
244 "cell-link",
245 "cell-part",
246];
247
248/// The class for a row part.
249///
250/// [`RowPart`] is `#[non_exhaustive]`, so a member added upstream does not stop
251/// this compiling.
252///
253/// The fallback is what that costs. A member added upstream lands here as a
254/// bare `row-part`, which the sheet lets shrink like its siblings and otherwise
255/// leaves plain: a thing rendering plainly rather than a build that stops. Grep
256/// this function when adopting a new makeover-layout.
257///
258/// Public, because a row's parts are emitted by whoever builds the row element
259/// and that is not always the same host: a table's cells are one emitter, but a
260/// list row carries the app's identity and hooks, so a screen renderer writes
261/// it. A renderer that reimplements this list rather than calling it takes on
262/// the obligation above without knowing it.
263#[must_use]
264pub fn part_class(part: RowPart) -> &'static str {
265 match part {
266 RowPart::Primary => "row-primary",
267 RowPart::Secondary => "row-secondary",
268 RowPart::Meta => "row-meta",
269 RowPart::Actions => "row-actions",
270 RowPart::Tokens => "row-tokens",
271 RowPart::Proportion => "row-proportion",
272 _ => "row-part",
273 }
274}
275
276/// The class for a cell part.
277///
278/// [`part_class`]'s table half, for [`CellPart`]. The fallback is there for the
279/// same reason and costs the same thing: a member added upstream lands as a
280/// bare `cell-part` with no rule of its own, rather than as a build that stops.
281/// Grep this function too when adopting a new makeover-layout. Public for the
282/// reason [`part_class`] is.
283#[must_use]
284pub fn cell_part_class(part: CellPart) -> &'static str {
285 match part {
286 CellPart::Value => "cell-value",
287 CellPart::Tokens => "cell-tokens",
288 CellPart::Actions => "cell-actions",
289 CellPart::Link => "cell-link",
290 _ => "cell-part",
291 }
292}
293
294#[cfg(test)]
295mod tests {
296 use super::*;
297
298 /// A sizer is one hidden wrapper around the host's copies, and no copies
299 /// writes nothing.
300 #[test]
301 fn a_sizer_wraps_its_copies_and_an_empty_one_writes_nothing() {
302 let opts = Emit::default();
303 let mut out = String::new();
304 push_sizer(&mut out, Markup(""), &opts);
305 assert_eq!(out, "");
306
307 push_sizer(&mut out, Markup("<button>Remove</button>"), &opts);
308 assert_eq!(
309 out,
310 "<span class=\"cell-sizer\" aria-hidden=\"true\"><button>Remove</button></span>"
311 );
312 }
313
314 #[test]
315 fn a_column_name_cannot_break_out_of_the_class_attribute() {
316 // A name written raw would emit
317 // `class="cell col-a" onclick="steal() cell-fill ...">`, a live
318 // handler on every cell of the column.
319 let mut out = String::new();
320 push_column_name(&mut out, "a\" onclick=\"steal()");
321 assert_eq!(out, "a--onclick--steal--");
322 assert!(!out.contains('"'), "{out}");
323 }
324
325 #[test]
326 fn the_class_and_the_selector_that_names_it_agree_on_the_name() {
327 // The reason the fix is a filter and not an escape: one class, not the
328 // two `col-Due date` parses as, and no entity a selector cannot match.
329 let mut out = String::new();
330 push_column_name(&mut out, "Due date");
331 assert_eq!(out, "Due-date");
332 }
333
334 #[test]
335 fn a_name_already_made_of_identifier_characters_is_untouched() {
336 for name in ["description", "due", "progress", "Name", "col_2", "a-b"] {
337 let mut out = String::new();
338 push_column_name(&mut out, name);
339 assert_eq!(out, name);
340 }
341 }
342
343 #[test]
344 fn a_name_outside_ascii_keeps_itself() {
345 // CSS identifiers admit everything from U+00A0 up, so folding these to
346 // dashes would collide two columns for nothing.
347 let mut out = String::new();
348 push_column_name(&mut out, "Größe");
349 assert_eq!(out, "Größe");
350 }
351}