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
//! List rows and the runs that fall back when they do not fit.

use crate::list::{self, cell_part_class, part_class};
use crate::reset::Reset;
use crate::{Emit, class};
use makeover_layout::{CellPart, Fallback, Flow, Prominence};

/// The container a vertical tab strip's arrangement names when it can fold the
/// strip over its pane.
pub const STRIP_CONTAINER: &str = "tab-strip";

/// The inline size of [`STRIP_CONTAINER`] under which a vertical strip runs
/// across its pane. An arrangement that folds the strip folds at this width,
/// or the tabs draw one way while laid out the other.
pub const STRIP_FOLD: &str = "36rem";

/// The parts of a list row.
///
/// Written out, since `Prominence` is `#[non_exhaustive]`: a member added
/// upstream emits no rule until it is named here. [`part_class`] carries the
/// same list.
pub(crate) fn row_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // The container the rows sit in, giving back what a `<ul>` brought. Not a
    // size: there is no magnitude in it, which is the line this crate holds.
    css.push_str(&Reset::BULLETS.rule(&format!(".{}", class("list", opts))));

    // A run of badges, controls or a meter takes its holding class in place of
    // one of these, so the intent never sits under a thing that carries its
    // own colour.
    for part in [Prominence::Lead, Prominence::Support, Prominence::Quiet] {
        let c = class(part_class(part), opts);
        putln!(css, ".{c} {{\n    color: var(--{});\n}}", part.intent());

        // A row's actions are shown at rest. A hover-reveal method said
        // otherwise and was not honoured here from 0.23.0; makeover-layout
        // 0.13.0 retired the method, so there is no longer a description saying
        // one thing and a renderer doing another.
        //
        // The rule was `opacity: 0` gated to pointer devices, revealed on
        // `:hover` and on `:focus-within`. Each escape it needed was a report
        // that hiding was wrong for somebody: `focus-within` because tabbing
        // could never reach an action; the gate because a fingertip had no way
        // to unhide, which both webview apps had already hand-written
        // `opacity: 1` to undo. What was left was a control hidden from
        // exactly one group: people using a pointer, who are also the group
        // scanning a list to find out what can be done to a row.
        //
        // A settings screen is where that reads worst: the whole reason to be
        // on it is to remove a key, and the button doing so was invisible
        // until pointed at. A table cell's actions were never hidden, so the
        // two arrangements now agree.
    }

    // A part that may take two lines. `Flow::Tight` gets no rule: one line is
    // what a run already does, and restating it here would put a declaration on
    // every part in every row to say nothing.
    //
    // This is the shape both webview apps had already written by hand and
    // commented, Balanced Breakfast on a feed row's title, goingson on a
    // problem's body, which is the whole argument for the description
    // carrying it. `-webkit-` prefixed and unprefixed together: the prefixed
    // trio is what every engine actually implements, and `line-clamp` is the
    // standard property landing behind it.
    putln!(
        css,
        ".{} {{\n    display: -webkit-box;\n    -webkit-box-orient: vertical;\n    -webkit-line-clamp: {lines};\n    line-clamp: {lines};\n    overflow: hidden;\n}}",
        class("row-relaxed", opts),
        lines = Flow::Relaxed.lines()
    );

    // A row inside a hierarchy: a tree, an outline, a threaded list.
    // makeover-layout names the concept `Nesting`, deliberately not `Depth`,
    // which is surface bevel in that crate, and this is the rule. Without it a
    // described outline in a browser is a flat list with chevrons in it: the
    // folding works and the indent does not exist.
    //
    // The magnitude is a custom property with a fallback, which is this crate's
    // own shape: `--awaiting-gap` above is the precedent, and an app overriding
    // `--row-indent` is how a level becomes worth more or less. What a level IS
    // stays the description's; what it is WORTH is a renderer's, and a terminal
    // spending columns for the same fact is not disagreeing.
    //
    // Here rather than in each app, and that was a live option rather than an
    // oversight. `row-select`, `row-current` and `row-chosen` are app-styled by
    // design; the indent is not decoration, it is what the description MEANS,
    // and three apps agreeing about it by accident is not agreement.
    //
    // `padding` and not `margin`: a row is a box that can be selected and
    // hovered, and indenting with margin would take the indent out of the
    // highlight, so the shading under a nested row would start where its text
    // does rather than where its row does.
    putln!(
        css,
        ".{} {{\n    padding-inline-start: calc(var(--row-depth, 0) * var(--row-indent, 1.5ch));\n}}",
        class("row-nested", opts)
    );

    // The two halves of a branch, emitted by quasi-webview and unstyled until
    // now for the same reason.
    //
    // A branch row is the one a reader can fold, and the chevron is its hit
    // target. The chevron is drawn by the app or the description, this says
    // where it sits and how big the target is, which is the accessibility fact
    // rather than the decorative one: a control smaller than this is one a
    // finger misses.
    putln!(
        css,
        ".{} {{\n    display: flex;\n    align-items: baseline;\n    gap: var(--row-disclose-gap, 0.5ch);\n}}",
        class("row-branch", opts)
    );
    putln!(
        css,
        ".{} {{\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}}",
        class("row-disclose", opts)
    );

    // How a part holds what is in it, for a row and for a table cell. Here
    // rather than in quasi-webview's arrangement sheet because these are names
    // this crate emits, so a row an app writes by hand gets them too. The row
    // itself stays quasi-webview's: where a part sits in the line is the screen
    // renderer's arrangement, and nothing here says it.
    //
    // A token or a control never breaks across two lines. What gives when the
    // line runs short is the row's text.
    let tokens = class(list::ROW_TOKENS, opts);
    let actions = class(list::ROW_ACTIONS, opts);
    let proportion = class(list::ROW_PROPORTION, opts);
    let fallback = class("row-part", opts);
    let cell_tokens = class(cell_part_class(CellPart::Tokens), opts);
    let cell_actions = class(cell_part_class(CellPart::Actions), opts);
    let cell_fallback = class("cell-part", opts);
    putln!(
        css,
        ".{fallback},\n.{cell_fallback} {{\n    min-width: 0;\n}}"
    );
    putln!(
        css,
        ".{tokens} {{\n    display: flex;\n    flex-wrap: wrap;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    putln!(
        css,
        ".{actions} {{\n    display: flex;\n    flex: none;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    // A cell's parts sit inside the cell's own box, so they are inline: the
    // cell's alignment, which the column kind sets, still places them.
    putln!(
        css,
        ".{cell_tokens},\n.{cell_actions} {{\n    display: inline-flex;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    // Wrapping, and no wider than the cell: a badge already ends in an
    // ellipsis at its container's width, and an inline run sized by its
    // contents gave it a container as wide as the badge, so a long token was
    // clipped at the cell edge instead.
    putln!(
        css,
        ".{cell_tokens} {{\n    flex-wrap: wrap;\n    max-inline-size: 100%;\n}}"
    );
    // A part that follows another keeps the same gap from it that its own
    // members keep from each other: a title ran into its New version badge, a
    // split into its Invited one, and a value into the value after it. Every
    // part after the first, not just tokens and actions. Not after the sizer,
    // which is a block of its own above the run.
    let sizer = class(list::CELL_SIZER, opts);
    let cell_in = class(list::CELL_IN, opts);
    putln!(
        css,
        ".{cell_in} > :not(.{sizer}) + * {{\n    \
         margin-inline-start: var(--gap-bound);\n}}"
    );
    putln!(
        css,
        ".{tokens} > *,\n.{actions} > *,\n.{cell_tokens} > *,\n.{cell_actions} > * {{\n    white-space: nowrap;\n}}"
    );
    // A proportion is a meter, and a meter is as wide as the row lets it be.
    putln!(css, ".{proportion} {{\n    flex: 1 1 auto;\n}}");

    css
}

/// A row of things that share their space, and what each fallback gets here.
///
/// Every described member stays in flow (wiki `layout-room-and-fallback`):
/// no rule here takes one out with `position: absolute`.
///
/// # The floor
///
/// `.run > *` gets `min-width: min-content`, so a member cannot be squeezed
/// narrower than what is in it and members in one flow push each other
/// instead of overlapping. It applies whichever fallback the group declared.
///
/// # A member that asks to fill
///
/// `.run > [data-width="fill"]` gets `flex: 1 1 0`, so several fills divide
/// the room equally, [`makeover_layout::Width::Fill`]'s stated rule. The floor
/// still applies. A member that says nothing gets nothing: with the floor and
/// no grow it is content-sized.
///
/// # What each fallback gets
///
/// [`Fallback::Wrap`] is `flex-wrap: wrap`, and a fill member's `flex-basis`
/// is `min(100%, var(--run-room, 20rem))` rather than `0`. A line breaks on
/// each member's hypothetical size, and a member holding a table (whose cells
/// are size containers) reports almost nothing, so the basis is the room the
/// app states in `--run-room`. `min(100%, ...)` keeps a lone member from
/// overflowing a narrower run. A fill member in a run that does not wrap
/// keeps `flex: 1 1 0`.
///
/// [`Fallback::Stack`] is wrap plus `flex: 1 1 max-content` on the members,
/// so a member that cannot sit beside its sibling takes a line of its own and
/// fills it.
///
/// [`Fallback::Shed`] and [`Fallback::Menu`] get wrap, which honours less than
/// the description says: every member stays reachable, but none is removed.
/// Shedding by [`Priority`](makeover_layout::Priority) needs to know the run is out of room, and
/// `@container` compares against a `<length>`, not `min-content`.
///
/// # Menu, once a script is measuring
///
/// `quasi-webview`'s `menu.js` marks a menu run it has taken over
/// `data-menu`, and a marked run goes back to `nowrap`, so the script can
/// measure the overflow. An unmarked run still wraps. `.run-overflow` is the
/// control the shed members move into and `.run-overflow-items` is where they
/// land; this crate styles both, and the script decides which members move.
pub(crate) fn run_rules(opts: &Emit) -> String {
    let run = class("run", opts);
    let mut css = String::new();

    // `flex-wrap: nowrap` is stated rather than left to the default, because
    // the fallbacks below are read as overrides of this line and a reader
    // should not have to know which way flexbox leans to see that.
    //
    // No gap. Spacing between members is the app's, the same way this crate
    // states no margins anywhere else; a gap here would be a size, and the one
    // hardcoded size in the mechanism is makeover-geometry's contact patch.
    putln!(
        css,
        ".{run} {{\n    display: flex;\n    flex-wrap: nowrap;\n    align-items: center;\n}}"
    );

    // The derived minimum, and the whole reason a member can no longer be
    // overlapped. `min-width: auto` is flexbox's default for a flex item and is
    // *not* the same thing: auto lets an item be compressed below its content
    // in a nowrap run, which is how a toolbar ends up drawn over a tab strip
    // even without anything leaving the flow.
    putln!(css, ".{run} > * {{\n    min-width: min-content;\n}}");

    // A member that absorbs what is left. `flex-basis: 0` rather than `auto` is
    // what makes several fills divide the room equally instead of dividing the
    // leftovers in proportion to what is already in them, which is
    // `Width::Fill`'s own rule and the one thing that type states about more
    // than one of them.
    //
    // The `min-width: min-content` floor above is deliberately not overridden.
    // A fill that could shrink below its contents would overlap its neighbour,
    // which is rule 1, and equal division under a floor is still equal division
    // everywhere the floor is not reached.
    //
    // Attribute rather than class, because the width is a fact the description
    // carried rather than a hook this crate invented: the same division
    // `data-tone` and `data-selector` are on the right side of. It beats the
    // `Stack` rule below on specificity whichever order they are written in,
    // which is what a member asking to fill should do to a blanket.
    putln!(
        css,
        ".{run} > [data-width=\"fill\"] {{\n    flex: 1 1 0;\n}}"
    );

    for fallback in [
        Fallback::Wrap,
        Fallback::Stack,
        Fallback::Shed,
        Fallback::Menu,
    ] {
        let name = fallback_class(fallback);
        let c = class(name, opts);
        putln!(css, ".{c} {{\n    flex-wrap: wrap;\n}}");
        if matches!(fallback, Fallback::Stack) {
            putln!(css, ".{c} > * {{\n    flex: 1 1 max-content;\n}}");
        }
        // The stated room, and only here. Written after the blanket fill rule
        // above so it overrides the basis it set; the grow and shrink that rule
        // states are deliberately left alone, so several fills still divide one
        // line equally and the min-content floor still stops any of them
        // shrinking under its contents.
        if matches!(fallback, Fallback::Wrap) {
            putln!(
                css,
                ".{c} > [data-width=\"fill\"] {{\n    \
                 flex-basis: min(100%, var(--run-room, 20rem));\n}}"
            );
        }
    }

    // A menu run a script has taken over. The mark is the script's and this is
    // the only rule that reads it: wrapping is what a run does when nothing is
    // measuring, and it is also what makes the overflow unmeasurable, since a
    // wrapped run always fits. The two cannot both be on.
    let menu = class(fallback_class(Fallback::Menu), opts);
    putln!(css, ".{menu}[data-menu] {{\n    flex-wrap: nowrap;\n}}");

    // The tab strip inside such a run, which is the member whose tabs fold.
    // The run going back to `nowrap` is not enough on its own: the strip is a
    // wrapping row in its own right, and the floor above holds it at its
    // min-content, so it either wrapped to more lines or pushed the run wider
    // than its pane. Neither overflows, and a strip that never overflows never
    // folds: eight tabs drew as three rows. So the strip takes the room the
    // run has and no more, holds one line, keeps each tab at its own width,
    // and clips across, which is the overflow the script measures. `clip` and
    // not `hidden`: `hidden` would make the block axis scroll too, and a
    // chosen tab's pull over its pane is drawn below the strip's box.
    //
    // The floor comes off this one member deliberately. It exists so members
    // push rather than overlap; a clipped strip overlaps nothing, and what it
    // clips is moved into the menu before anyone sees it.
    let strip =
        format!("{menu}[data-menu] > [role=\"tablist\"]:not([aria-orientation=\"vertical\"])");
    putln!(
        css,
        ".{strip} {{\n    flex: 1 1 auto;\n    flex-wrap: nowrap;\n    min-width: 0;\n    overflow-x: clip;\n}}"
    );
    putln!(css, ".{strip} > * {{\n    flex-shrink: 0;\n}}");

    // The overflow control, and it is a member of the run like any other: in
    // flow, at the end, taking the width of what is in it. `relative` is what
    // the items hang off.
    let overflow = class("run-overflow", opts);
    let items = class("run-overflow-items", opts);
    putln!(css, ".{overflow} {{\n    position: relative;\n}}");

    // Overlaid rather than in flow, for the reason every menu is: a control
    // that pushed the page down when it opened would change the layout it was
    // opened to escape. `inset-inline-end: 0` rather than a left, so the panel
    // stays on the page in both writing directions.
    //
    // No width, no padding and no border. All three are sizes and sizes are
    // makeover-geometry's; what is stated here is placement, the surface and
    // the shadow that separates it from the page, which is the same division
    // `figure_rules` and the timeline entry make. The elevation shadow is what
    // an overlaid surface takes instead of an edge, see `ELEVATION_PROPERTY`.
    putln!(
        css,
        ".{items} {{\n    \
         position: absolute;\n    \
         inset-block-start: 100%;\n    \
         inset-inline-end: 0;\n    \
         z-index: 1;\n    \
         display: flex;\n    \
         flex-direction: column;\n    \
         align-items: stretch;\n    \
         background: var(--surface-raised);\n    \
         box-shadow: var(--elevation-overlay);\n\
         }}"
    );

    // `hidden` is how the script closes it, and a flex display would otherwise
    // beat the attribute's own `display: none`.
    putln!(css, ".{items}[hidden] {{\n    display: none;\n}}");

    css
}

/// Every run class: `run`, every class [`fallback_class`] can return, and
/// `run-overflow` and `run-overflow-items`, the overflow control a measuring
/// script builds. A test holds the list to [`fallback_class`].
pub const RUN_CLASSES: &[&str] = &[
    "run",
    "run-wrap",
    "run-stack",
    "run-shed",
    "run-menu",
    // Not returned by `fallback_class`: these two are the overflow control a
    // measuring renderer builds, and they are in the list because the list is
    // what a host seals its vocabulary against. A class emitted by a script and
    // missing from here is a control with no surface and no edge.
    "run-overflow",
    "run-overflow-items",
];

/// The class a run carries for what it does when it is tight.
///
/// A run always carries `.run` as well, so an unrecognised fallback (the
/// enum is `#[non_exhaustive]`) lands as a plain nowrap row with the
/// min-content floor still under it.
#[must_use]
pub fn fallback_class(fallback: Fallback) -> &'static str {
    match fallback {
        Fallback::Wrap => "run-wrap",
        Fallback::Stack => "run-stack",
        Fallback::Shed => "run-shed",
        Fallback::Menu => "run-menu",
        _ => "run",
    }
}