makeover_webview/rows.rs
1//! List rows and the runs that fall back when they do not fit.
2
3use crate::list::{self, cell_part_class, part_class};
4use crate::reset::Reset;
5use crate::{Emit, class};
6use makeover_layout::{CellPart, Fallback, Flow, Prominence};
7
8/// The container a vertical tab strip's arrangement names when it can fold the
9/// strip over its pane.
10pub const STRIP_CONTAINER: &str = "tab-strip";
11
12/// The inline size of [`STRIP_CONTAINER`] under which a vertical strip runs
13/// across its pane. An arrangement that folds the strip folds at this width,
14/// or the tabs draw one way while laid out the other.
15pub const STRIP_FOLD: &str = "36rem";
16
17/// The parts of a list row.
18///
19/// Written out, since `Prominence` is `#[non_exhaustive]`: a member added
20/// upstream emits no rule until it is named here. [`part_class`] carries the
21/// same list.
22pub(crate) fn row_rules(opts: &Emit) -> String {
23 let mut css = String::new();
24
25 // The container the rows sit in, giving back what a `<ul>` brought. Not a
26 // size: there is no magnitude in it, which is the line this crate holds.
27 css.push_str(&Reset::BULLETS.rule(&format!(".{}", class("list", opts))));
28
29 // A run of badges, controls or a meter takes its holding class in place of
30 // one of these, so the intent never sits under a thing that carries its
31 // own colour.
32 for part in [Prominence::Lead, Prominence::Support, Prominence::Quiet] {
33 let c = class(part_class(part), opts);
34 putln!(css, ".{c} {{\n color: var(--{});\n}}", part.intent());
35
36 // A row's actions are shown at rest. A hover-reveal method said
37 // otherwise and was not honoured here from 0.23.0; makeover-layout
38 // 0.13.0 retired the method, so there is no longer a description saying
39 // one thing and a renderer doing another.
40 //
41 // The rule was `opacity: 0` gated to pointer devices, revealed on
42 // `:hover` and on `:focus-within`. Each escape it needed was a report
43 // that hiding was wrong for somebody: `focus-within` because tabbing
44 // could never reach an action; the gate because a fingertip had no way
45 // to unhide, which both webview apps had already hand-written
46 // `opacity: 1` to undo. What was left was a control hidden from
47 // exactly one group: people using a pointer, who are also the group
48 // scanning a list to find out what can be done to a row.
49 //
50 // A settings screen is where that reads worst: the whole reason to be
51 // on it is to remove a key, and the button doing so was invisible
52 // until pointed at. A table cell's actions were never hidden, so the
53 // two arrangements now agree.
54 }
55
56 // A part that may take two lines. `Flow::Tight` gets no rule: one line is
57 // what a run already does, and restating it here would put a declaration on
58 // every part in every row to say nothing.
59 //
60 // This is the shape both webview apps had already written by hand and
61 // commented, Balanced Breakfast on a feed row's title, goingson on a
62 // problem's body, which is the whole argument for the description
63 // carrying it. `-webkit-` prefixed and unprefixed together: the prefixed
64 // trio is what every engine actually implements, and `line-clamp` is the
65 // standard property landing behind it.
66 putln!(
67 css,
68 ".{} {{\n display: -webkit-box;\n -webkit-box-orient: vertical;\n -webkit-line-clamp: {lines};\n line-clamp: {lines};\n overflow: hidden;\n}}",
69 class("row-relaxed", opts),
70 lines = Flow::Relaxed.lines()
71 );
72
73 // A row inside a hierarchy: a tree, an outline, a threaded list.
74 // makeover-layout names the concept `Nesting`, deliberately not `Depth`,
75 // which is surface bevel in that crate, and this is the rule. Without it a
76 // described outline in a browser is a flat list with chevrons in it: the
77 // folding works and the indent does not exist.
78 //
79 // The magnitude is a custom property with a fallback, which is this crate's
80 // own shape: `--awaiting-gap` above is the precedent, and an app overriding
81 // `--row-indent` is how a level becomes worth more or less. What a level IS
82 // stays the description's; what it is WORTH is a renderer's, and a terminal
83 // spending columns for the same fact is not disagreeing.
84 //
85 // Here rather than in each app, and that was a live option rather than an
86 // oversight. `row-select`, `row-current` and `row-chosen` are app-styled by
87 // design; the indent is not decoration, it is what the description MEANS,
88 // and three apps agreeing about it by accident is not agreement.
89 //
90 // `padding` and not `margin`: a row is a box that can be selected and
91 // hovered, and indenting with margin would take the indent out of the
92 // highlight, so the shading under a nested row would start where its text
93 // does rather than where its row does.
94 putln!(
95 css,
96 ".{} {{\n padding-inline-start: calc(var(--row-depth, 0) * var(--row-indent, 1.5ch));\n}}",
97 class("row-nested", opts)
98 );
99
100 // The two halves of a branch, emitted by quasi-webview and unstyled until
101 // now for the same reason.
102 //
103 // A branch row is the one a reader can fold, and the chevron is its hit
104 // target. The chevron is drawn by the app or the description, this says
105 // where it sits and how big the target is, which is the accessibility fact
106 // rather than the decorative one: a control smaller than this is one a
107 // finger misses.
108 putln!(
109 css,
110 ".{} {{\n display: flex;\n align-items: baseline;\n gap: var(--row-disclose-gap, 0.5ch);\n}}",
111 class("row-branch", opts)
112 );
113 putln!(
114 css,
115 ".{} {{\n flex: none;\n min-inline-size: var(--tap-target, 2rem);\n min-block-size: var(--tap-target, 2rem);\n background: none;\n border: 0;\n color: inherit;\n cursor: pointer;\n}}",
116 class("row-disclose", opts)
117 );
118
119 // How a part holds what is in it, for a row and for a table cell. Here
120 // rather than in quasi-webview's arrangement sheet because these are names
121 // this crate emits, so a row an app writes by hand gets them too. The row
122 // itself stays quasi-webview's: where a part sits in the line is the screen
123 // renderer's arrangement, and nothing here says it.
124 //
125 // A token or a control never breaks across two lines. What gives when the
126 // line runs short is the row's text.
127 let tokens = class(list::ROW_TOKENS, opts);
128 let actions = class(list::ROW_ACTIONS, opts);
129 let proportion = class(list::ROW_PROPORTION, opts);
130 let fallback = class("row-part", opts);
131 let cell_tokens = class(cell_part_class(CellPart::Tokens), opts);
132 let cell_actions = class(cell_part_class(CellPart::Actions), opts);
133 let cell_fallback = class("cell-part", opts);
134 putln!(
135 css,
136 ".{fallback},\n.{cell_fallback} {{\n min-width: 0;\n}}"
137 );
138 putln!(
139 css,
140 ".{tokens} {{\n display: flex;\n flex-wrap: wrap;\n align-items: center;\n gap: var(--gap-bound);\n}}"
141 );
142 putln!(
143 css,
144 ".{actions} {{\n display: flex;\n flex: none;\n align-items: center;\n gap: var(--gap-bound);\n}}"
145 );
146 // A cell's parts sit inside the cell's own box, so they are inline: the
147 // cell's alignment, which the column kind sets, still places them.
148 putln!(
149 css,
150 ".{cell_tokens},\n.{cell_actions} {{\n display: inline-flex;\n align-items: center;\n gap: var(--gap-bound);\n}}"
151 );
152 // Wrapping, and no wider than the cell: a badge already ends in an
153 // ellipsis at its container's width, and an inline run sized by its
154 // contents gave it a container as wide as the badge, so a long token was
155 // clipped at the cell edge instead.
156 putln!(
157 css,
158 ".{cell_tokens} {{\n flex-wrap: wrap;\n max-inline-size: 100%;\n}}"
159 );
160 // A part that follows another keeps the same gap from it that its own
161 // members keep from each other: a title ran into its New version badge, a
162 // split into its Invited one, and a value into the value after it. Every
163 // part after the first, not just tokens and actions. Not after the sizer,
164 // which is a block of its own above the run.
165 let sizer = class(list::CELL_SIZER, opts);
166 let cell_in = class(list::CELL_IN, opts);
167 putln!(
168 css,
169 ".{cell_in} > :not(.{sizer}) + * {{\n \
170 margin-inline-start: var(--gap-bound);\n}}"
171 );
172 putln!(
173 css,
174 ".{tokens} > *,\n.{actions} > *,\n.{cell_tokens} > *,\n.{cell_actions} > * {{\n white-space: nowrap;\n}}"
175 );
176 // A proportion is a meter, and a meter is as wide as the row lets it be.
177 putln!(css, ".{proportion} {{\n flex: 1 1 auto;\n}}");
178
179 css
180}
181
182/// A row of things that share their space, and what each fallback gets here.
183///
184/// Every described member stays in flow (wiki `layout-room-and-fallback`):
185/// no rule here takes one out with `position: absolute`.
186///
187/// # The floor
188///
189/// `.run > *` gets `min-width: min-content`, so a member cannot be squeezed
190/// narrower than what is in it and members in one flow push each other
191/// instead of overlapping. It applies whichever fallback the group declared.
192///
193/// # A member that asks to fill
194///
195/// `.run > [data-width="fill"]` gets `flex: 1 1 0`, so several fills divide
196/// the room equally, [`makeover_layout::Width::Fill`]'s stated rule. The floor
197/// still applies. A member that says nothing gets nothing: with the floor and
198/// no grow it is content-sized.
199///
200/// # What each fallback gets
201///
202/// [`Fallback::Wrap`] is `flex-wrap: wrap`, and a fill member's `flex-basis`
203/// is `min(100%, var(--run-room, 20rem))` rather than `0`. A line breaks on
204/// each member's hypothetical size, and a member holding a table (whose cells
205/// are size containers) reports almost nothing, so the basis is the room the
206/// app states in `--run-room`. `min(100%, ...)` keeps a lone member from
207/// overflowing a narrower run. A fill member in a run that does not wrap
208/// keeps `flex: 1 1 0`.
209///
210/// [`Fallback::Stack`] is wrap plus `flex: 1 1 max-content` on the members,
211/// so a member that cannot sit beside its sibling takes a line of its own and
212/// fills it.
213///
214/// [`Fallback::Shed`] and [`Fallback::Menu`] get wrap, which honours less than
215/// the description says: every member stays reachable, but none is removed.
216/// Shedding by [`Priority`](makeover_layout::Priority) needs to know the run is out of room, and
217/// `@container` compares against a `<length>`, not `min-content`.
218///
219/// # Menu, once a script is measuring
220///
221/// `quasi-webview`'s `menu.js` marks a menu run it has taken over
222/// `data-menu`, and a marked run goes back to `nowrap`, so the script can
223/// measure the overflow. An unmarked run still wraps. `.run-overflow` is the
224/// control the shed members move into and `.run-overflow-items` is where they
225/// land; this crate styles both, and the script decides which members move.
226pub(crate) fn run_rules(opts: &Emit) -> String {
227 let run = class("run", opts);
228 let mut css = String::new();
229
230 // `flex-wrap: nowrap` is stated rather than left to the default, because
231 // the fallbacks below are read as overrides of this line and a reader
232 // should not have to know which way flexbox leans to see that.
233 //
234 // No gap. Spacing between members is the app's, the same way this crate
235 // states no margins anywhere else; a gap here would be a size, and the one
236 // hardcoded size in the mechanism is makeover-geometry's contact patch.
237 putln!(
238 css,
239 ".{run} {{\n display: flex;\n flex-wrap: nowrap;\n align-items: center;\n}}"
240 );
241
242 // The derived minimum, and the whole reason a member can no longer be
243 // overlapped. `min-width: auto` is flexbox's default for a flex item and is
244 // *not* the same thing: auto lets an item be compressed below its content
245 // in a nowrap run, which is how a toolbar ends up drawn over a tab strip
246 // even without anything leaving the flow.
247 putln!(css, ".{run} > * {{\n min-width: min-content;\n}}");
248
249 // A member that absorbs what is left. `flex-basis: 0` rather than `auto` is
250 // what makes several fills divide the room equally instead of dividing the
251 // leftovers in proportion to what is already in them, which is
252 // `Width::Fill`'s own rule and the one thing that type states about more
253 // than one of them.
254 //
255 // The `min-width: min-content` floor above is deliberately not overridden.
256 // A fill that could shrink below its contents would overlap its neighbour,
257 // which is rule 1, and equal division under a floor is still equal division
258 // everywhere the floor is not reached.
259 //
260 // Attribute rather than class, because the width is a fact the description
261 // carried rather than a hook this crate invented: the same division
262 // `data-tone` and `data-selector` are on the right side of. It beats the
263 // `Stack` rule below on specificity whichever order they are written in,
264 // which is what a member asking to fill should do to a blanket.
265 putln!(
266 css,
267 ".{run} > [data-width=\"fill\"] {{\n flex: 1 1 0;\n}}"
268 );
269
270 for fallback in [
271 Fallback::Wrap,
272 Fallback::Stack,
273 Fallback::Shed,
274 Fallback::Menu,
275 ] {
276 let name = fallback_class(fallback);
277 let c = class(name, opts);
278 putln!(css, ".{c} {{\n flex-wrap: wrap;\n}}");
279 if matches!(fallback, Fallback::Stack) {
280 putln!(css, ".{c} > * {{\n flex: 1 1 max-content;\n}}");
281 }
282 // The stated room, and only here. Written after the blanket fill rule
283 // above so it overrides the basis it set; the grow and shrink that rule
284 // states are deliberately left alone, so several fills still divide one
285 // line equally and the min-content floor still stops any of them
286 // shrinking under its contents.
287 if matches!(fallback, Fallback::Wrap) {
288 putln!(
289 css,
290 ".{c} > [data-width=\"fill\"] {{\n \
291 flex-basis: min(100%, var(--run-room, 20rem));\n}}"
292 );
293 }
294 }
295
296 // A menu run a script has taken over. The mark is the script's and this is
297 // the only rule that reads it: wrapping is what a run does when nothing is
298 // measuring, and it is also what makes the overflow unmeasurable, since a
299 // wrapped run always fits. The two cannot both be on.
300 let menu = class(fallback_class(Fallback::Menu), opts);
301 putln!(css, ".{menu}[data-menu] {{\n flex-wrap: nowrap;\n}}");
302
303 // The tab strip inside such a run, which is the member whose tabs fold.
304 // The run going back to `nowrap` is not enough on its own: the strip is a
305 // wrapping row in its own right, and the floor above holds it at its
306 // min-content, so it either wrapped to more lines or pushed the run wider
307 // than its pane. Neither overflows, and a strip that never overflows never
308 // folds: eight tabs drew as three rows. So the strip takes the room the
309 // run has and no more, holds one line, keeps each tab at its own width,
310 // and clips across, which is the overflow the script measures. `clip` and
311 // not `hidden`: `hidden` would make the block axis scroll too, and a
312 // chosen tab's pull over its pane is drawn below the strip's box.
313 //
314 // The floor comes off this one member deliberately. It exists so members
315 // push rather than overlap; a clipped strip overlaps nothing, and what it
316 // clips is moved into the menu before anyone sees it.
317 let strip =
318 format!("{menu}[data-menu] > [role=\"tablist\"]:not([aria-orientation=\"vertical\"])");
319 putln!(
320 css,
321 ".{strip} {{\n flex: 1 1 auto;\n flex-wrap: nowrap;\n min-width: 0;\n overflow-x: clip;\n}}"
322 );
323 putln!(css, ".{strip} > * {{\n flex-shrink: 0;\n}}");
324
325 // The overflow control, and it is a member of the run like any other: in
326 // flow, at the end, taking the width of what is in it. `relative` is what
327 // the items hang off.
328 let overflow = class("run-overflow", opts);
329 let items = class("run-overflow-items", opts);
330 putln!(css, ".{overflow} {{\n position: relative;\n}}");
331
332 // Overlaid rather than in flow, for the reason every menu is: a control
333 // that pushed the page down when it opened would change the layout it was
334 // opened to escape. `inset-inline-end: 0` rather than a left, so the panel
335 // stays on the page in both writing directions.
336 //
337 // No width, no padding and no border. All three are sizes and sizes are
338 // makeover-geometry's; what is stated here is placement, the surface and
339 // the shadow that separates it from the page, which is the same division
340 // `figure_rules` and the timeline entry make. The elevation shadow is what
341 // an overlaid surface takes instead of an edge, see `ELEVATION_PROPERTY`.
342 putln!(
343 css,
344 ".{items} {{\n \
345 position: absolute;\n \
346 inset-block-start: 100%;\n \
347 inset-inline-end: 0;\n \
348 z-index: 1;\n \
349 display: flex;\n \
350 flex-direction: column;\n \
351 align-items: stretch;\n \
352 background: var(--surface-raised);\n \
353 box-shadow: var(--elevation-overlay);\n\
354 }}"
355 );
356
357 // `hidden` is how the script closes it, and a flex display would otherwise
358 // beat the attribute's own `display: none`.
359 putln!(css, ".{items}[hidden] {{\n display: none;\n}}");
360
361 css
362}
363
364/// Every run class: `run`, every class [`fallback_class`] can return, and
365/// `run-overflow` and `run-overflow-items`, the overflow control a measuring
366/// script builds. A test holds the list to [`fallback_class`].
367pub const RUN_CLASSES: &[&str] = &[
368 "run",
369 "run-wrap",
370 "run-stack",
371 "run-shed",
372 "run-menu",
373 // Not returned by `fallback_class`: these two are the overflow control a
374 // measuring renderer builds, and they are in the list because the list is
375 // what a host seals its vocabulary against. A class emitted by a script and
376 // missing from here is a control with no surface and no edge.
377 "run-overflow",
378 "run-overflow-items",
379];
380
381/// The class a run carries for what it does when it is tight.
382///
383/// A run always carries `.run` as well, so an unrecognised fallback (the
384/// enum is `#[non_exhaustive]`) lands as a plain nowrap row with the
385/// min-content floor still under it.
386#[must_use]
387pub fn fallback_class(fallback: Fallback) -> &'static str {
388 match fallback {
389 Fallback::Wrap => "run-wrap",
390 Fallback::Stack => "run-stack",
391 Fallback::Shed => "run-shed",
392 Fallback::Menu => "run-menu",
393 _ => "run",
394 }
395}