Skip to main content

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}