makeover-layout 0.51.0

// Names this module's prose links to, resolved for rustdoc.
#[allow(unused_imports)]
use crate::{Field, FieldKind, Fill, Region, RowPart};

/// How much room a placement asks for.
///
/// A column says it, and so does a [`Field`]. An intent, so the actual floor
/// stays with `makeover-geometry`. goingson's task table spells these as
/// `minmax(200px, 1fr)`, `140px` and content-sized; only the first three words
/// of that survive deferral.
/// `#[non_exhaustive]`, for the reason [`Fill`] and [`FieldKind`] are: a
/// renderer matches on this and a vocabulary that grows must not break every
/// renderer when it does.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Width {
    /// Takes what it needs and no more.
    Content,
    /// A fixed share, the same at every width.
    Fixed,
    /// Absorbs whatever is left over.
    ///
    /// **Several fills divide what is left equally.** Stated because it would
    /// otherwise be undefined and each renderer would invent something, and
    /// stated this way because equal division is the only sharing rule that
    /// answers to "Any width, one answer" without a tiebreak: allocating in
    /// declaration order makes the result depend on the order the description
    /// was written in, which is a fact about the source file and not about the
    /// screen. It documents what both renderers already do (CSS grid gives
    /// `1fr 1fr`, ratatui gives each a `Constraint::Fill(1)`) rather than
    /// changing anything.
    ///
    /// So a row of fills is a legal thing to describe, and there is no rule
    /// against it.
    Fill,
}

/// What a member is worth when there is not room for all of them.
///
/// Written for table columns and no longer only theirs. Three shapes ask the
/// same question and this answers all three: a table too narrow for its
/// columns, a row too narrow for its parts (see [`RowPart::priority`]), and a
/// group of regions sharing one run of room, goingson's tab strip and the
/// [`Region::Band`] beside it, which is the case wiki `layout-room-and-fallback`
/// was ruled on. It is what any member of a group is worth, not a table
/// concept, and [`Fallback::Shed`] is what reads it.
///
/// The doc below is the column argument, which is where the type was measured;
/// the sentence that gave it away is [`Priority::Essential`]'s, which was
/// already written about a row.
///
/// Ordered: [`Priority::Optional`] drops first, [`Priority::Essential`] never
/// drops. This replaces addressing columns by position, which is what both
/// webview apps do today and is a live bug rather than only verbosity. goingson
/// hides mobile columns with `nth-child(n+5)` against a seven-column table, so
/// inserting a column silently hides the wrong one.
/// `#[non_exhaustive]`, same reasoning as [`Width`]. Note the ordering is the
/// whole point of the type, so a new tier has to be declared in its place in
/// the sequence rather than appended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum Priority {
    /// Dropped first.
    Optional,
    /// Dropped once the optional members are gone.
    Secondary,
    /// Never dropped. Without it the group does not identify itself.
    Essential,
}

impl Priority {
    /// Every cutoff, weakest first: the order a narrowing renderer raises
    /// through.
    ///
    /// The one list of tiers. A renderer walks this rather than writing its
    /// own, so a tier added here is one every renderer narrows to.
    pub const RAISING: &'static [Self] = &[Self::Optional, Self::Secondary, Self::Essential];
}

/// What the columns kept at a cutoff ask for.
///
/// Counted in `ch` and in columns, and never in a host's unit: each renderer
/// turns it into its own with [`Budget::width`], which is the one gap model
/// every native renderer budgets by.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub struct Budget {
    /// How many columns are kept.
    pub columns: u32,
    /// Their [`floor`](Column::floor)s, summed, in `ch`.
    pub floors: u32,
}

impl Budget {
    /// The width these columns need, at `ch` per `ch` and `gap` between
    /// adjacent columns and at each edge.
    ///
    /// `floors * ch + gap * (columns + 1)`. A terminal passes one cell per `ch`
    /// and its column spacing; an immediate-mode painter passes the width of a
    /// figure and its cell padding on both sides. One formula, so a table
    /// drops a column at the same declared width in both.
    #[must_use]
    pub fn width(self, ch: f32, gap: f32) -> f32 {
        self.floors as f32 * ch + gap * (self.columns + 1) as f32
    }
}

/// What the columns kept at `cutoff` ask for.
#[must_use]
pub fn budget(columns: &[Column<'_>], cutoff: Priority) -> Budget {
    columns.iter().filter(|column| column.kept_at(cutoff)).fold(
        Budget::default(),
        |budget, column| Budget {
            columns: budget.columns + 1,
            floors: budget.floors + u32::from(column.floor()),
        },
    )
}

/// The weakest cutoff whose kept columns `fits` accepts.
///
/// Raised through [`Priority::RAISING`] until the columns fit, and never past
/// [`Priority::Essential`]: the essential columns are what makes a row identify
/// itself, so a window too narrow for them gets them squeezed rather than
/// dropped. Nothing here counts positions, so which column drops is a property
/// of the column.
#[must_use]
pub fn cutoff_for(columns: &[Column<'_>], fits: impl Fn(Budget) -> bool) -> Priority {
    Priority::RAISING
        .iter()
        .copied()
        .find(|&cutoff| fits(budget(columns, cutoff)))
        .unwrap_or(Priority::Essential)
}

/// The lengths a description deferred, in a renderer's own unit.
///
/// [`Width`] says `Content`, `Fixed` or `Fill` and carries no magnitude,
/// because a magnitude is an answer for one renderer. Each renderer holds this
/// over its own unit (cells, points, CSS lengths) and looks a column up by
/// name, because an app's columns are not all one size.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
#[non_exhaustive]
pub struct Sizing<'a, L> {
    /// `(column name, length)`: the track for a [`Width::Fixed`] column and the
    /// floor for a [`Width::Fill`] one.
    pub lengths: &'a [(&'a str, L)],
    /// Used for a column with no entry above.
    pub fallback: L,
}

impl<'a, L: Copy> Sizing<'a, L> {
    /// These lengths, and `fallback` for a column not among them.
    #[must_use]
    pub const fn new(lengths: &'a [(&'a str, L)], fallback: L) -> Self {
        Self { lengths, fallback }
    }

    /// The length for a named column.
    #[must_use]
    pub fn length_for(&self, name: &str) -> L {
        self.lengths
            .iter()
            .find(|(column, _)| *column == name)
            .map_or(self.fallback, |(_, length)| *length)
    }
}

/// What a group does when it runs out of room.
///
/// Authored, and required: the field carrying this has no `Default` and a group
/// cannot be described without saying what it does when it runs out of room.
/// More intentionality from layout designers is acceptable so long as the constraints are solvable, because the goal is
/// enabling good layouts rather than rescuing bad ones. A default here would be
/// the crate guessing, and the guess would be silently wrong on the screens
/// that matter.
///
/// Relief resolves inside-out. A group asks its children to fall back before
/// falling back itself, or an outer group collapses while an inner one still
/// had slack.
///
/// # No `Swap`
///
/// An authored alternate group for the tight case is deliberately out of the
/// first cut. It doubles the description for that group and the two halves can
/// drift, which is the failure this vocabulary exists to end. Add it when a
/// site proves it needs one.
///
/// `#[non_exhaustive]`, [`Width`]'s reasoning. Unlike [`Priority`] there is no
/// order to preserve, so a member can be appended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Fallback {
    /// One row becomes two. Every member stays, in the order described.
    Wrap,
    /// A row becomes a column. Every member stays, full width.
    Stack,
    /// Members drop by [`Priority`], down to [`Priority::Essential`].
    ///
    /// What a narrow table already does with its columns, applied to a group.
    /// What drops is gone from the screen, so this is right when the dropped
    /// members are facts the reader can do without and wrong when they are the
    /// only way to act.
    Shed,
    /// The members [`Shed`](Self::Shed) would drop move into one overflow
    /// control instead.
    ///
    /// The answer when a group holds actions. A control is not a fact: dropping
    /// it does not cost the reader a detail, it costs them the only way to act,
    /// which is [`RowPart::priority`]'s argument one level up.
    Menu,
}

/// The widest a column's [`floor`](Column::floor) may be, in `ch`.
///
/// A bound so a webview can name every floor as a class from a fixed ladder:
/// a container condition cannot read a custom property, so the length a
/// column hides its contents under has to be written into the stylesheet.
/// Wider than any column the tree declares, and a column wanting more is a
/// [`Width::Fill`] with this as its floor.
pub const MIN_CEILING: u16 = 64;

/// The floor an undeclared [`Width::Fill`] column takes, in `ch`.
const FILL_FLOOR: u16 = 16;

/// One column of a table.
///
/// Described once. The grid track, the cell order and the drop behaviour are
/// all derived from this, rather than being three hand-written encodings that
/// must agree and are never checked against each other.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct Column<'a> {
    /// The heading, and the name the cell is addressed by.
    pub name: &'a str,
    /// How much room it asks for.
    pub width: Width,
    /// What it is worth when room runs out.
    pub priority: Priority,
    /// What the column holds, which is what carries its look.
    pub kind: ColumnKind,
    /// The narrowest the column may be before it drops, in `ch`.
    ///
    /// wiki `frontend-unification`: collapse points derive from declared
    /// minimums only, so every host narrows at the same declared width rather
    /// than at its own breakpoints. `ch` because every host has a direct
    /// answer for it: a terminal cell is one, an immediate-mode painter
    /// measures one off its face, and a webview draws one as nine sixteenths
    /// of the base, a figure at a table's text size with room to spare. Not
    /// the CSS `ch`
    /// itself, because a container condition resolves font-relative units
    /// against a different font than the cell's, and the column would hide at
    /// one width and be sized at another.
    ///
    /// `None` derives it from the kind and the heading, which is what most
    /// columns want. Read it through [`floor`](Self::floor), never directly:
    /// that is where the derivation, the rounding and the ceiling live, and a
    /// host reading this field would narrow somewhere the other two do not.
    pub min: Option<u16>,
    /// Whether the user can reorder the table by this column.
    ///
    /// What reordering *calls* is not here (that is an address, and this
    /// crate names none) so a host pairs this with the route the way it pairs
    /// a row's parts with the row's activation. This says the affordance
    /// exists, which is what a renderer needs to draw a header a user can
    /// press rather than a heading they cannot.
    pub sortable: bool,
    /// Which way the table is ordered by this column, if it is.
    ///
    /// `None` on every column but the one in force. A renderer draws the caret
    /// from this and a webview sets `aria-sort`, which is why it is per column
    /// rather than a single fact on the table: the host idiom is a property of
    /// the header cell.
    ///
    /// Independent of [`sortable`](Self::sortable) rather than implied by it,
    /// because both combinations mean something. A column sorted and not
    /// sortable is a list ordered by a key the user cannot change, which is a
    /// real thing to describe and a caret worth drawing.
    pub sorted: Option<Sort>,
}

/// What a column holds.
///
/// wiki `table-model`: the kind is what carries a column's look, and four of
/// the reference table's six rules were per kind rather than per table. A
/// description states what the column is; each renderer decides what that
/// looks like in its host, from the facts below rather than from the name.
///
/// `#[non_exhaustive]`, [`Width`]'s reasoning.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum ColumnKind {
    /// Prose. Wraps. What a column is when it says nothing else.
    #[default]
    Text,
    /// A name a machine made: a fingerprint, a hash, a slug. Monospace, and
    /// breaks mid-string rather than widening the table.
    Identifier,
    /// A point in time. Never wraps, so a date cannot print over its
    /// neighbour, and its figures line up down the column.
    Date,
    /// A quantity. Figures line up and the column aligns to its end, so
    /// magnitudes compare by length.
    Number,
    /// Source text, one row per line. Monospace and never wrapped. A table
    /// holding one is read as code, so its rows are not striped or spaced as
    /// records.
    Code,
    /// A state the row is in, drawn as a chip rather than as coloured text.
    Status,
    /// The row's controls. Aligns to its end and shrinks to what it holds.
    Actions,
}

impl ColumnKind {
    /// The narrowest a column of this kind reads at, in `ch`, when it declares
    /// nothing narrower.
    ///
    /// A date is ten characters in the form every host writes, and a number
    /// cut short is a different number, so the kinds that cannot truncate
    /// floor at what they hold. Prose and identifiers wrap or break, so theirs
    /// is only enough to be recognisable.
    #[must_use]
    pub const fn floor(self) -> u16 {
        match self {
            Self::Text | Self::Code | Self::Status | Self::Actions => 8,
            Self::Identifier => 12,
            Self::Date => 10,
            Self::Number => 6,
        }
    }

    /// Whether the column aligns to its end rather than its start.
    #[must_use]
    pub const fn aligns_end(self) -> bool {
        matches!(self, Self::Number | Self::Actions)
    }

    /// Whether the column's text may wrap onto a second line.
    ///
    /// An identifier wraps by breaking mid-string, which is still a wrap: the
    /// alternative is a fingerprint forcing the table wider than its pane.
    #[must_use]
    pub const fn wraps(self) -> bool {
        matches!(self, Self::Text | Self::Identifier)
    }

    /// Whether the column is set in the monospace face.
    #[must_use]
    pub const fn monospace(self) -> bool {
        matches!(self, Self::Identifier | Self::Code)
    }

    /// Whether figures in the column take equal widths.
    #[must_use]
    pub const fn tabular(self) -> bool {
        matches!(self, Self::Date | Self::Number)
    }
}

/// Which way a column is ordered.
///
/// Two, because there is no third. "Unsorted" is [`Column::sorted`] being
/// `None`, and folding it in here would be the same absence said twice.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Sort {
    /// Smallest, earliest or first alphabetically at the top.
    Ascending,
    /// The other way.
    Descending,
}

impl Sort {
    /// The other direction, for a header that flips when pressed.
    #[must_use]
    pub const fn reversed(self) -> Self {
        match self {
            Self::Ascending => Self::Descending,
            Self::Descending => Self::Ascending,
        }
    }

    /// What a webview writes into `aria-sort`.
    ///
    /// Named here rather than in the webview renderer because a terminal and an
    /// immediate-mode painter both want the same two words for a caret's label,
    /// and three renderers picking their own is the drift this crate ends.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Ascending => "ascending",
            Self::Descending => "descending",
        }
    }

    /// The caret a renderer draws for this direction.
    ///
    /// Here for [`as_str`](Self::as_str)'s reason, said about a glyph rather
    /// than a word: three renderers picking their own is the drift this crate
    /// ends. They had picked their own (two on the solid triangles and
    /// `makeover-webview` on the arrows U+2191/U+2193) and agreeing by
    /// coincidence in three files is not agreement.
    ///
    /// The reason generalizes past this pair and is the house rule now,
    /// prefer the bolder, simpler glyph over the thinner or more complicated
    /// one. A third spelling is not open for re-argument.
    ///
    /// **Bare, with no spacing.** Where the gap goes is each renderer's
    /// business: `makeover-tui` and `makeover-immediate` carry a leading space
    /// inside their `TableStyle` string and a webview emits its own in
    /// `content`, so folding a space in here would make one of the two wrong.
    ///
    /// Neither face the web apps self-host carries these (IBM Plex Mono has one
    /// glyph in the whole geometric-shapes block and Lato has none) so a
    /// browser falls back per glyph until the in-house face ships with them
    /// drawn in (wiki `typography-standard`). Cosmetic
    /// drift in one renderer, not a reason to spell it three ways.
    #[must_use]
    pub const fn glyph(self) -> &'static str {
        match self {
            Self::Ascending => "\u{25B2}",
            Self::Descending => "\u{25BC}",
        }
    }
}

impl<'a> Column<'a> {
    /// A column that absorbs slack and never drops.
    ///
    /// [`Priority::Essential`], and the default is the whole of the argument.
    /// A table that states no priorities used to empty itself wherever a
    /// renderer narrows (head and cells together, every column having
    /// inherited a droppable rank) which is what goingson's task table did.
    /// Undeclared now means kept, so a column goes only when someone demotes
    /// it, and the remaining failure is a cramped table rather than a blank
    /// one. That is the same judgment [`kept_at`](Self::kept_at)'s renderers
    /// make about a rank they have not learned: of the two ways to be wrong,
    /// showing a column that should have gone is the one a reader can see and
    /// work around.
    #[must_use]
    pub const fn new(name: &'a str) -> Self {
        Self {
            name,
            width: Width::Fill,
            priority: Priority::Essential,
            kind: ColumnKind::Text,
            min: None,
            sortable: false,
            sorted: None,
        }
    }

    /// The same column, declaring the narrowest it may be before it drops.
    #[must_use]
    pub const fn min(mut self, ch: u16) -> Self {
        self.min = Some(ch);
        self
    }

    /// The same column, asking for this much room.
    #[must_use]
    pub const fn width(mut self, width: Width) -> Self {
        self.width = width;
        self
    }

    /// The same column, worth this much when room runs out.
    #[must_use]
    pub const fn priority(mut self, priority: Priority) -> Self {
        self.priority = priority;
        self
    }

    /// The same column, holding this kind of value.
    #[must_use]
    pub const fn kind(mut self, kind: ColumnKind) -> Self {
        self.kind = kind;
        self
    }

    /// The same column, reorderable by the user or not.
    #[must_use]
    pub const fn sortable(mut self, sortable: bool) -> Self {
        self.sortable = sortable;
        self
    }

    /// The same column, the one the table is ordered by, in this direction.
    #[must_use]
    pub const fn sorted(mut self, sort: Sort) -> Self {
        self.sorted = Some(sort);
        self
    }

    /// The narrowest this column may be before it drops, in `ch`.
    ///
    /// What every host narrows by: a column is kept at a cutoff only while the
    /// floors of every column kept there fit. The declared [`min`](Self::min),
    /// or else the widest of the kind's [`floor`](ColumnKind::floor), the
    /// heading with two for its capitals and two more for a caret, and sixteen
    /// for a [`Width::Fill`] column. Rounded up to an even count and held under
    /// [`MIN_CEILING`], so a webview can carry the whole range as a fixed ladder
    /// of classes and the other two hosts round the same way.
    #[must_use]
    pub const fn floor(&self) -> u16 {
        let raw = match self.min {
            Some(ch) => ch,
            None => {
                let caret = if self.sortable || self.sorted.is_some() {
                    2
                } else {
                    0
                };
                // Bytes, not characters: const, and a heading is a short word
                // in every table in the tree. A multi-byte heading reads a
                // little wide, which errs toward keeping it legible. Two more
                // for the heading's capitals and tracking, which run wider than
                // the figures a `ch` is measured off: `AMOUNT` at six ch is cut.
                let heading = if self.name.len() > MIN_CEILING as usize {
                    MIN_CEILING
                } else {
                    self.name.len() as u16 + 2 + caret
                };
                let kind = self.kind.floor();
                // A column that takes the slack is the one holding prose, and
                // floored at its kind it wraps a title onto three lines while
                // the columns worth less still stand at full width.
                let fill = if matches!(self.width, Width::Fill) {
                    FILL_FLOOR
                } else {
                    0
                };
                let wider = if heading > kind { heading } else { kind };
                if fill > wider { fill } else { wider }
            }
        };
        // Clamped before rounding, so a declared `min(u16::MAX)` cannot
        // overflow on its way to being held under the ceiling.
        let raw = if raw > MIN_CEILING { MIN_CEILING } else { raw };
        let even = raw + raw % 2;
        if even < 2 {
            2
        } else if even > MIN_CEILING {
            MIN_CEILING
        } else {
            even
        }
    }

    /// Whether this column survives at the given cutoff.
    ///
    /// A renderer narrows by raising the cutoff, and never by counting
    /// positions.
    #[must_use]
    pub const fn kept_at(&self, cutoff: Priority) -> bool {
        (self.priority as u8) >= (cutoff as u8)
    }
}

/// What a table cell holds.
///
/// [`RowPart`] for tables, and it exists for the same reason: a part that
/// carries a control is not text, and a renderer with one class for the whole
/// cell paints it as though it were: a button in a cell inherits the cell's
/// content colour, which is the drift [`RowPart::intent`] prevents for rows.
///
/// Four members, and the count is what quasi's `Cell` was measured to carry: a
/// value, tokens, actions and a link. Nothing was added past what something
/// holds.
///
/// `#[non_exhaustive]` for [`RowPart`]'s reason: growth here must not be a
/// lockstep event across three renderers.
///
/// # No hover-reveal
///
/// This enum never gets one. A cell's actions are shown at rest in every
/// consumer measured, and a member nothing uses is one three renderers owe an
/// answer for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum CellPart {
    /// The cell's own text.
    Value,
    /// Small labelled things in the cell: a status badge, a chip.
    Tokens,
    /// Controls that act on what the row is about.
    Actions,
    /// The cell's value, where the value is itself a link.
    Link,
}

impl CellPart {
    /// The content intent the part takes.
    ///
    /// One part is text and three are not, so three answer with the intent
    /// inheriting already gives. That is [`RowPart::intent`]'s shape with the
    /// text side narrower: a cell's secondary and muted readings are the
    /// column's business, not the cell's.
    #[must_use]
    pub const fn intent(self) -> &'static str {
        match self {
            Self::Value => "content",
            // A token carries its own tone, and a part-level intent underneath
            // it would fight the token sitting on it.
            Self::Tokens => "content",
            // Actions carry controls rather than text.
            Self::Actions => "content",
            // A link in a cell is its row's title, so it reads in the ink the
            // values beside it do.
            Self::Link => "content",
        }
    }
}