makeover-webview 0.130.0

The webview renderer for makeover-layout. Emits CSS, and is the one renderer that needs no palette: var() is the late binding, so resolution stays with the browser. With the build feature, writes a consumer's generated frontend files and checks the hand-written ones against them.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
//! What a view says while it waits, its facts, pictures, showings, tracks
//! and sortable states.

use crate::{Emit, class, css_escape, status_edge, tone_rules};
use makeover_layout::{Fill, Intent as _, Sort, Tone};

/// What a wait looks like.
///
/// `data-awaiting` is emitted as `data-awaiting="determinate"` with a
/// `data-awaiting-amount` beside it, or `data-awaiting="indeterminate"` alone
/// (wiki `loading-and-progress-standard`). These rules style the two.
///
/// # Keyed on `aria-busy`
///
/// `data-awaiting` says the control waits when pressed. The rules draw only
/// while the element also carries `aria-busy="true"`, which the binder sets
/// while a wait is running: `quasi-webview` sets it from htmx's request
/// events, and any other host sets the same attribute.
///
/// # The two drawings
///
/// One pseudo-element either way, so no renderer emits an extra node.
///
/// Indeterminate is the activity mark of rule 2: a small square that blinks.
/// Determinate is a trough with a fill, drawn as a single gradient whose stop is
/// `--awaiting-share`, a plain number from 0 to 1 that the binder sets from
/// bytes it has actually watched land, marking the control
/// `data-awaiting-watched` while it does.
///
/// A determinate control nobody is watching draws the mark with the total
/// beside it in the reading's ink, `content: attr(data-awaiting-amount)`: the
/// size is known and the delivery is not, which is what the tui and egui
/// renderers draw for the same wait. A watched control whose share is still
/// unset draws an empty trough, never a full one.
///
/// The only input is a share of a measured payload: nothing here draws a
/// remaining time, an arrival time or a rate.
///
/// # Sizes
///
/// Both sizes are custom properties with defaults, `--awaiting-mark` and
/// `--awaiting-bar`, which an app may set once.
///
/// # The cadence
///
/// `--cadence-activity` comes from `makeover-timing` through
/// [`build`](mod@crate::build), and is a half-period, so a full cycle is twice
/// it. It is used bare, with no fallback.
///
/// The base style is a lit, still mark and the keyframes do the dimming. A
/// sheet assembled without the time axis leaves `animation-duration` invalid,
/// which resolves to `0s` and runs no animation; the reduced-motion block sets
/// the cadence to `0ms`, with the same result.
pub(crate) fn awaiting_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // Dimming rather than lighting, so a zero-length animation leaves a lit
    // mark rather than a blank one. See `makeover_timing::reduced_motion_css`.
    css.push_str(
        "@keyframes makeover-activity {\n    \
         0%, 49.99% {\n        background: var(--action);\n    }\n    \
         50%, 100% {\n        background: var(--surface-sunken);\n    }\n\
         }\n",
    );
    // The same blink for a mark drawn as an image beside text, where the
    // background colour is the text's ground and must not change.
    css.push_str(
        "@keyframes makeover-activity-beside {\n    \
         0%, 49.99% {\n        background-image: linear-gradient(var(--action), var(--action));\n    }\n    \
         50%, 100% {\n        background-image: linear-gradient(var(--surface-sunken), var(--surface-sunken));\n    }\n\
         }\n",
    );

    // Nothing is drawn until something is waiting. `content` on the base rule
    // rather than on the busy one keeps the box the same box across the
    // transition, so a mark appearing does not reflow the line it is in.
    putln!(
        css,
        "[data-awaiting]::after {{\n    \
         content: \"\";\n    \
         display: none;\n    \
         margin-inline-start: var(--awaiting-gap, 0.5ch);\n    \
         vertical-align: baseline;\n\
         }}"
    );

    putln!(
        css,
        "[data-awaiting][aria-busy=\"true\"]::after {{\n    \
         display: inline-block;\n    \
         inline-size: var(--awaiting-mark, 0.5em);\n    \
         block-size: var(--awaiting-mark, 0.5em);\n    \
         background: var(--action);\n    \
         opacity: 1;\n    \
         animation: makeover-activity calc(var(--cadence-activity) * 2) \
         step-end infinite;\n\
         }}"
    );

    // The measured half. A wider box, no blink, and a gradient whose stop is
    // the share: the fill and the trough in one paint, so the markup stays one
    // pseudo-element on both branches.
    //
    // `--awaiting-share` unset is an empty trough, not a full one. A bar that
    // read full because nobody was counting would be the confidently-wrong
    // drawing rule 1 exists to forbid.
    //
    // `to right` and a right-to-left override rather than `to inline-end`:
    // no browser takes a logical direction in a gradient, and the declaration
    // that names one is dropped whole, leaving no fill at all.
    //
    // The trough takes an edge for the reason a well does: a bar at zero share
    // is otherwise a rectangle of the surface it sits on, which is nothing at
    // all. `border_width` rather than a literal, the way `depth_rule` and
    // `track_rules` write theirs.
    putln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"]::after {{\n    \
         inline-size: var(--awaiting-bar, 6em);\n    \
         animation: none;\n    \
         outline: {} solid var(--border);\n    \
         outline-offset: -{};\n    \
         background: linear-gradient(\n        \
         to right,\n        \
         var(--action) 0 calc(var(--awaiting-share, 0) * 100%),\n        \
         var(--surface-sunken) 0\n    \
         );\n\
         }}",
        opts.border_width,
        opts.border_width
    );

    // Measured and unwatched: the mark, then the total. One pseudo-element
    // still, so the mark is an image painted at the inline start and the
    // total is the content beside it. More specific than the bar by the
    // `:not`, so it wins whatever the order.
    putln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"]:not([data-awaiting-watched])::after {{\n    \
         content: attr(data-awaiting-amount);\n    \
         inline-size: auto;\n    \
         block-size: auto;\n    \
         outline: none;\n    \
         color: var(--content-muted);\n    \
         padding-inline-start: calc(var(--awaiting-mark, 0.5em) + var(--awaiting-gap, 0.5ch));\n    \
         background: linear-gradient(var(--action), var(--action)) no-repeat \
         left center / var(--awaiting-mark, 0.5em) var(--awaiting-mark, 0.5em);\n    \
         animation: makeover-activity-beside calc(var(--cadence-activity) * 2) \
         step-end infinite;\n\
         }}"
    );

    // Right to left, the fill grows from the right and the mark sits there.
    putln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"][data-awaiting-watched]:dir(rtl)::after {{\n    \
         background: linear-gradient(\n        \
         to left,\n        \
         var(--action) 0 calc(var(--awaiting-share, 0) * 100%),\n        \
         var(--surface-sunken) 0\n    \
         );\n\
         }}\n\
         [data-awaiting=\"determinate\"][aria-busy=\"true\"]:not([data-awaiting-watched]):dir(rtl)::after {{\n    \
         background-position: right center;\n\
         }}"
    );

    css
}

/// A definition list, and the two tracks that make its values line up.
///
/// A grid with one label track sized to the longest label lines the values
/// up across the set. The first track is `max-content`: as wide as the
/// longest label and no wider. The value takes `--content` and the label
/// `--content-secondary`.
///
/// The value takes `content` and the label reads back: the same rule
/// `figure_rules` states for a value against its caption, and `row` for
/// primary against meta.
pub(crate) fn facts_rules(opts: &Emit) -> String {
    let facts = class("facts", opts);
    let label = class("facts-label", opts);
    let value = class("facts-value", opts);
    let mut css = String::new();

    putln!(
        css,
        ".{facts} {{\n    display: grid;\n    grid-template-columns: max-content 1fr;\n    \
         column-gap: var(--gap-section);\n    row-gap: var(--gap-peer);\n    margin: 0;\n}}"
    );
    // `dt` and `dd` both carry a browser margin that would break the tracks.
    putln!(
        css,
        ".{facts} > .{label} {{\n    margin: 0;\n    color: var(--content-secondary);\n}}"
    );
    putln!(
        css,
        ".{facts} > .{value} {{\n    margin: 0;\n    color: var(--content);\n}}"
    );
    css
}

/// A picture, its frame and its caption.
///
/// # The frame is a border, not a bevel
///
/// No [`Depth`] rule: a bevel is an inset shadow drawn inside the element's
/// box, which on a picture lands on the image's own pixels. The frame is a
/// [`Emit::border_width`] border in `--border`, outside the content.
///
/// The fill stays: it shows through a transparent PNG and stands in the
/// frame's place while the image is loading.
///
/// # No size
///
/// `width: 100%`, `height: auto`, and no other size: how large a picture is
/// depends on the box it was put in.
pub(crate) fn picture_rules(opts: &Emit) -> String {
    let picture = class("picture", opts);
    let img = class("picture-img", opts);
    let caption = class("picture-caption", opts);
    let mut css = String::new();

    // Block, or an inline image sits on the text baseline and carries a
    // descender's worth of space under it that no app ever wants and every app
    // deletes by hand. The border is the frame; see the type docs for why it is
    // not the bevel every other surface here gets.
    putln!(
        css,
        ".{img} {{\n    display: block;\n    width: 100%;\n    height: auto;\n    \
         background: var(--{});\n    border: {} solid var(--border);\n}}",
        Fill::Raised.token(),
        opts.border_width
    );

    // The two fits that need a rule. `Fit::Natural` emits no attribute at all,
    // so it is the bare rule above and needs nothing here.
    putln!(
        css,
        ".{img}[data-fit=\"cover\"] {{\n    height: 100%;\n    object-fit: cover;\n}}"
    );
    putln!(
        css,
        ".{img}[data-fit=\"contain\"] {{\n    height: 100%;\n    object-fit: contain;\n}}"
    );

    // A caption reads back one step, which is `figure-caption`'s answer and the
    // same claim: it says what the thing above it is, and it is not the thing.
    putln!(
        css,
        ".{picture} > .{caption} {{\n    color: var(--content-muted);\n}}"
    );

    css
}

/// A region showing one child at a time, and the chrome that moves between them.
///
/// [`makeover_layout::Showing`] lets a description say that a region holds
/// several children and shows some of them. A renderer derives its chrome from
/// that; these are the rules the derived chrome needs.
///
/// # Every child until bound
///
/// Without `data-ready` on the region, every child shows in order and the
/// controls are hidden. Whatever binds the region sets `data-ready`, which
/// collapses the stack to the `.current` child and reveals the row that moves
/// it.
///
/// # Not spacing
///
/// No gaps: the rules set `display` and the muted readout only.
pub(crate) fn showing_rules(opts: &Emit) -> String {
    let controls = class("showing", opts);
    let position = class("showing-position", opts);
    let frame = class("showing-frame", opts);
    let mut css = String::new();

    // Hidden until something binds it, which is the whole argument above.
    putln!(css, ".{controls} {{\n    display: none;\n}}");
    // Block, and nothing about how the three sit in it. A button and a span are
    // inline already, so they make a row without this crate saying so, and
    // saying so is where `align-items` and a gap would follow, both spacing,
    // both `makeover-geometry`'s, and `row_rules` refuses them for the same
    // reason.
    putln!(
        css,
        "[data-ready] > .{controls} {{\n    display: block;\n}}"
    );

    // A child is in flow until the region is bound, and then only the current
    // one is. `.current` is a modifier for the reason `.chosen` and `.latched`
    // are: one name for the state, set by whoever knows it.
    putln!(
        css,
        "[data-ready] > .{frame}:not(.current) {{\n    display: none;\n}}"
    );

    // Reads back one step. `picture-caption`'s rule and its reason.
    putln!(css, ".{position} {{\n    color: var(--content-muted);\n}}");

    css
}

/// A time axis: the container, its gridlines and ruler, and the placed things.
///
/// [`Track`](makeover_layout::Track) places things by position on a span.
///
/// # Where the numbers come from
///
/// Every value that varies per item is a custom property the caller sets in
/// [`VARS_ATTR`], and every rule here reads one. `--track-at` and
/// `--track-for` are percentages of the span, which
/// [`Track::fraction`](makeover_layout::Track::fraction) computes: an entry
/// carries `--track-at: 37.5%; --track-for: 4.166%` and the rule turns it into
/// a box. Nothing here knows a pixel.
///
/// **The height of the track is the app's.** `.track` gets
/// `position: relative` and nothing else, and the percentages resolve against
/// whatever height the app gives it.
///
/// # Overlap
///
/// `Placement::overlaps` derives overlap from the times, so what arrives here
/// is a lane index and a lane count, and the rule divides the width. Without
/// either property the defaults give one full-width lane.
pub(crate) fn track_rules(opts: &Emit) -> String {
    let track = class("track", opts);
    let slot = class("track-slot", opts);
    let tick = class("track-tick", opts);
    let entry = class("track-entry", opts);
    let mut css = String::new();

    // The positioning context every entry resolves against, and the whole of
    // what this crate says about the container. No height: see the doc above.
    putln!(css, ".{track} {{\n    position: relative;\n}}");

    // Gridlines and the ruler are the axis reading itself back, which is
    // `picture-caption` and `showing-position`'s claim: about the thing rather
    // than one of the things.
    //
    // `border_width` rather than a literal, the way `depth_rule` writes its
    // edge. A gridline is the one place a timeline would most naturally reach
    // for a hardcoded 1px, and a hardcoded 1px is this crate naming a size.
    putln!(
        css,
        ".{slot} {{\n    border-top: {} solid var(--border);\n}}",
        opts.border_width
    );
    putln!(css, ".{tick} {{\n    color: var(--content-muted);\n}}");

    // The one rule that does real work. Top and height are the placement;
    // left and width are the lane. Both lane properties default so an entry
    // that names neither is full width, which is the common case and the one a
    // renderer gets for free.
    putln!(
        css,
        ".{entry} {{\n    \
         position: absolute;\n    \
         top: var(--track-at, 0%);\n    \
         height: var(--track-for, 100%);\n    \
         left: calc(var(--track-lane, 0) / var(--track-lanes, 1) * 100%);\n    \
         width: calc(100% / var(--track-lanes, 1));\n\
         }}"
    );

    css
}

/// A region's stand-in, and the header of a table that can be reordered.
///
/// Colour, affordance and `makeover-geometry`'s gap steps; no type scale and
/// no literal size.
///
/// The sort caret is drawn from `aria-sort` on the header, so the order the
/// table states to a screen reader is also visible.
pub(crate) fn state_rules(opts: &Emit) -> String {
    let placeholder = class("placeholder", opts);
    let text = class("placeholder-text", opts);
    let heading = class("table-heading", opts);
    let mut css = String::new();

    // An empty stand-in is a slot with nothing in it yet, and it draws as one:
    // a box on the page's own ground with a dashed edge from the neutral ramp.
    // A muted sentence loose on the page read as a stray line, and the way
    // out beneath it as an unrelated control; inside the box they read as one
    // thing that says what will be here and how to put it there. A waiting
    // stand-in keeps its sunken ground (below), so the two states stay apart.
    putln!(
        css,
        ".{placeholder}:not([data-state=\"pending\"]) {{\n    \
         border: 1px dashed var(--border);\n    border-radius: var(--radius-fine);\n    \
         padding: var(--gap-section);\n}}"
    );
    // A stand-in's sentence wraps at the reading measure rather than running
    // the pane's width: goingson's Problems empty state was 172 characters on
    // one line at 1440. The token is quasi-webview's, the one a screen's
    // `Measure::Reading` already answers to, and the fallback is the value it
    // falls back to, so a page that sets neither still gets a line that reads.
    putln!(
        css,
        ".{placeholder} > .{text} {{\n    max-inline-size: var(--measure-reading, 42rem);\n    \
         color: var(--content-muted);\n}}"
    );
    // Only the failure is toned. An empty list is the normal state of a new
    // install, and `Readiness::tone` is what says so. The tone is an edge and
    // the sentence takes content ink, a step up from the muted one an empty
    // stand-in reads in: a failure is read, and a status colour is never the
    // colour of words (wiki `quasi-vocabulary-findings`).
    putln!(
        css,
        ".{placeholder}[data-tone=\"{0}\"] > .{text} {{\n    color: var(--content);\n{1}}}",
        Tone::Danger.token(),
        status_edge(opts.focus_width, Tone::Danger.token())
    );
    // A stand-in that is waiting draws on a sunken ground, so it does not
    // read as one that is empty: both say a sentence where content will be,
    // and only the ground says whether anything is coming. A step of the
    // neutral ramp rather than a tone, since waiting is not a status. The
    // sentence carries the same news to a screen reader through the region's
    // own `aria-busy`. The inset is a gap step, so the ground reads as a
    // ground rather than a highlight under the words.
    putln!(
        css,
        ".{placeholder}[data-state=\"pending\"] {{\n    background: var(--surface-sunken);\n    \
         padding: var(--gap-bound) var(--gap-peer);\n    \
         border-radius: var(--radius-fine);\n}}"
    );
    // A sentence that carries a status draws an edge in that status, the way
    // a figure does, and keeps its ink. A bare sentence was the one member
    // that accepted a tone and drew none of it; drawing the words in the tone
    // is what a figure's numbers measured at 1.24:1 to 2.27:1, and a
    // sentence is read the same way. Same edge and inset as the figure's.
    let sentence = class("text", opts);
    tone_rules(&mut css, &format!(".{sentence}"), |tone| {
        status_edge(opts.focus_width, tone)
    });
    // A sentence at a measure band sits on that band's step of the neutral
    // ramp, sized to its words so the band reads as the value's and not the
    // line's. Band 0 is the ground and draws nothing.
    for band in 1..makeover_layout::HEAT_BANDS {
        let heat = makeover_layout::Heat(band).token();
        putln!(
            css,
            ".{sentence}[data-heat=\"{heat}\"] {{\n    background: var(--{heat});\n    \
             inline-size: fit-content;\n    \
             padding-inline: var(--step-snug);\n    \
             border-radius: var(--radius-fine);\n}}"
        );
    }
    // The way out stands a group apart from the sentence it answers. A gap
    // step rather than a size: how much room the stand-in gets is still the
    // app's.
    putln!(
        css,
        ".{placeholder} > .{} {{\n    margin-block-start: var(--gap-group);\n}}",
        class("placeholder-action", opts)
    );

    // A header that reorders the table is a control, and the pointer is the
    // only part of saying so that is not the app's own type and spacing.
    putln!(
        css,
        ".{heading}[data-sortable] {{\n    cursor: pointer;\n}}"
    );
    // The caret carries its own leading space, the way `makeover-tui` and
    // `makeover-immediate` both write `" \u{25B2}"`. An app adding the gap
    // itself would do it the obvious way, as `content`, and app CSS outranks
    // this crate's cascade layer, so it would win over the glyph and leave the
    // heading with no caret at all. With the space emitted here there is
    // nothing left for one to add.
    //
    // Three states, three tones, on the convention in wiki
    // `three-tone-convention`. A column in force is `content`; a column offering
    // to reorder and not doing it now is `content-secondary`, because it still
    // answers a press; a column that is not sortable emits no caret at all and
    // takes nothing. The idle arm draws its glyph rather than hiding it and
    // reserving the box, so there is no reservation to get right.
    //
    // The glyph is `Sort::glyph`, escaped rather than written: a CSS `content`
    // string cannot carry the character literally through this file's own
    // escaping, and spelling it here as well would put the third copy back that
    // `makeover-layout` 0.27.5 exists to remove.
    //
    // On the heading's `.cell-in`, so the caret sits beside the label inside
    // its padding rather than at the far edge of a column that grew.
    let cell_in = class("cell-in", opts);
    putln!(
        css,
        ".{heading}[data-sortable] > .{cell_in}::after \
         {{\n    content: \" {}\";\n    color: var(--content-secondary);\n}}",
        css_escape(Sort::Ascending.glyph())
    );
    for direction in [Sort::Ascending, Sort::Descending] {
        putln!(
            css,
            ".{heading}[aria-sort=\"{}\"] > .{cell_in}::after \
             {{\n    content: \" {}\";\n    color: var(--content);\n}}",
            direction.as_str(),
            css_escape(direction.glyph())
        );
    }
    css
}