//! The renderer-agnostic half of the make-family design system. //! //! //! //! `makeover` answers *what colour*, and varies by theme. `makeover-geometry` //! answers *how much space*, and varies by density and surface. This crate //! answers *what the thing is*, and varies by nothing. //! //! # The deferral rule //! //! A description names intents and relationships, never values. Say //! [`Fill::Raised`], never `#D9DDF4`. Say `Gap::Peer`, never `6px`. What is //! left once colour and spacing are deferred is **composition**: which edges //! are lit, what inverts on press, what nests in what. //! //! The constraint that shapes all of it: a renderer that can only paint //! rectangles has to be able to express the result. egui has no //! `box-shadow: inset` and one stroke per widget with no per-side control; a //! terminal has box-drawing characters and one cell of resolution, and cannot //! draw a two-tone lit edge at all. A description that assumes per-side edges //! is a CSS description wearing a neutral name. So this crate names the //! *intent* — this region is a well — and each renderer chooses an expression //! it can actually produce, including dropping half of one. //! //! # Scope //! //! - **Depth.** [`Bevel`], [`Edge`], [`Fill`], [`Depth`]: the bevel and the //! surfaces it shapes. Fill and bevel are named together, so a raised bevel //! over a recessed fill is unrepresentable. //! - **Components.** [`Token`] (badge against chip), [`Notice`] (toast against //! banner), [`RowPart`], [`CellPart`], [`Heading`], [`Selector`], //! [`Readiness`], [`Awaiting`], [`Meter`], [`Figure`], [`Track`], //! and [`Tone`], the one intent family they share. //! - **Schemas.** [`Field`] for forms, [`Column`] for lists and tables, //! [`Facet`] for the dimensions a set is narrowed by. //! - **Structure.** [`Region`] for the parts of a screen, [`Arrangement`] for //! how a screen is put together, [`Showing`] for how many of a region's //! children are visible at once. //! //! # What a member is admitted on //! //! A member is added when an app needs a fact the vocabulary cannot state, and //! refused when what it wants is presentation it should be asking a renderer //! for. Three tests, all of which have to pass: //! //! - **Generic against bespoke.** Is this furniture any app would have, or is //! it this app's own? A rule that withholds a word until a second app has //! duplicated the code guarantees the duplication. What the app owns //! keeps [`Region::Handover`] and [`Region::Ceded`]. //! - **Every host has an honest answer.** A member no renderer can express //! without borrowing one host's idiom is not a description. //! - **It can be laid out before it is filled.** See *First paint is final //! paint* below. //! //! Count the members a thing needs before refusing it. A refusal is only worth //! as much as the measurement under it. //! //! # What this crate cannot say //! //! - **An address.** What a control calls, and where a button goes. [`Act`] //! names the act and holds no destination. //! - **A current value.** A webview reads it out of the DOM and an //! immediate-mode renderer holds a `&mut` to the app's own field. A //! description carrying it would be a form model. //! - **What has focus.** See below. //! - **A duration or a clock.** No estimate of time remaining, no autosave //! interval, no animation length. //! - **A colour, a size or a position.** The deferral rule. //! //! # Reach, focus and the focus ring //! //! Three terms, and no others, for what sits outside the description. //! **Reach** is which things can take focus and in what order; a browser reads //! it off the document, a TUI derives it from draw order, egui from its own id //! stack. **Focus** is which reached thing has the keyboard right now: the //! renderer's, live, never described and never round-tripped through a //! description. The **focus ring** is the visible cue; the token (`focus-ring`, //! derived by `makeover` from the action colour) is the one shared artifact and //! the drawing is the renderer's. Retired as names for any of this: "focus //! stroke", "focus cue", "wants focus". "Caret" is a different thing — the text //! cursor inside a field — and keeps its name. //! //! # The three tones, and what a colour claims //! //! One rule for how colour says whether a thing can be //! used. Every renderer answers to it, and it is stated here because the //! description is what names the intents. //! //! | the thing | intent | //! |-----------|--------| //! | active, emphasised, the thing itself | `content` | //! | inactive but usable: it still answers a press | `content-secondary` | //! | inert: disabled, or not a control at all | `content-muted` | //! //! `content-muted` is the one with a claim in it. [`State::Disabled`] resolves //! to it, so a live control wearing it is telling the user it will not answer, //! and being wrong about that is worse than being quiet, because the user's //! response is to stop trying. A sortable column heading that was never sorted, //! and every unchosen option in a radio group, read as dead lists if they wear //! it. What is legitimately muted is a caption, a hint, a placeholder, a meter's reading, an axis label: text that //! was never going to answer anything. //! //! The three are one ramp and not three colours. `makeover`'s `Emphasis` derives //! the quieter two from the ink, so "one step back" means the same distance in //! every theme and a renderer cannot land between them by picking its own. //! //! # First paint is final paint //! //! Nothing may change size or position after it is //! first drawn, and nothing may stand in for content that has not arrived yet. //! Both halves are absolute. //! //! It is stated here, rather than left to each renderer, because a renderer can //! only reserve space the description gave it enough to size. A member whose //! size depends on its content therefore owes whatever makes it sizeable while //! the content is still absent, and that is the second admission test for a new //! member: not only does it compose something this crate already names, it can //! be laid out before it is filled. //! //! The mechanism is a reservation, and [`Sort`]'s caret is the worked example. //! The caret is drawn into a box its own width whether or not the column is //! sorted, so pressing a heading cannot reflow the row it sits in. The box names //! no magnitude, which is what keeps it out of `makeover-geometry`'s territory. //! Reserve from what is known; never discover geometry from what has not //! arrived. //! //! The trap is an `Option` that means "not yet". [`Readiness::Pending`] is the //! honest way to say a region is still waiting. An optional *measurement* is //! not: a count that shows up later widens the text that prints it and moves //! everything beside it, which is the reflow this rule exists to forbid. So an //! `Option` on a measurement means the host will never know it — a property of //! the query, fixed for the life of the screen — and a renderer sizes for the //! answer it was handed rather than for the one it hopes is coming. //! //! # Any width, one answer //! //! The sibling of the rule above. That one is //! independence from *when*; this one is independence from *how you got here*. //! //! A rendering is a pure function of the description and the viewport. The same //! description at the same width is the same output, whatever widths came //! before it. No renderer may carry geometry across frames, and none may narrow //! by counting. //! //! The failure this forbids is ordinary enough to be the default everywhere //! else: a page that hides its sidebar below some width, remembers that it hid //! it, and does not bring it back the same way. Layout there is a function of //! `(width, history)`, so dragging a window to 900 wide is a different screen //! depending on whether you came from 1400 or from 600. Nobody chose that; it //! is what measuring and remembering produce. //! //! The mechanism is [`Width`] for what grows and [`Priority`] for what drops. //! Both are declared, both are read off the description, and neither needs a //! measurement. A renderer narrows by raising a cutoff over a total order, //! never by counting what fits and stopping — `makeover-tui`'s table states //! that as its own rule and tests it, and `makeover-webview` reaches the same //! place with `@media` and `display: none`, which is path-independent by //! construction because CSS has nowhere to keep the previous width. //! //! Two things follow for anything new. A member that would need last frame's //! size to lay out this frame is refused, the same way a member that cannot be //! sized before it is filled is refused. And a fact about what disappears //! belongs in the description, because a host that has to infer it can only //! infer it from a measurement. //! //! # Where the description stops //! //! A member is added when an app needs a fact the vocabulary cannot state, and //! refused when what it wants is presentation it should be asking a renderer //! for. It is not a quota, and the goal is every screen described. //! //! A timeline is describable. What it needs and could not previously get is two //! integers, where a thing starts and how long it lasts, which is [`Track`]. //! Slot heights, gridline colour, how overlapping things stack and which hour //! scrolls into view stay the renderer's, and `Track` carries none of them. //! //! A kanban board is describable, and the member is [`Region::Columns`]. Every //! card fact is already sayable through `Row`'s parts; what nothing else could //! say is that the columns are *peers*, since [`Arrangement`] offers only //! list-detail and sidebar-content and a board described as either is a lie //! about the screen. Dragging a card between columns does not enter into it: a //! drop's effect is "set status", a discrete action `Row`'s menu already //! carries, and the drag itself is affordance. //! //! A calendar takes no members. The month grid's primacy in calendar apps is an //! artifact of paper: paper cannot be queried, so it has to show every day at //! once as a fallback index, and routes, search and ranking do that job better. //! Three jobs survive that reasoning, and only one of them needs a grid: //! //! 1. **Spans across days**, a stretch of leave, a trip, a sprint. You cannot //! see "away the 3rd to the 17th" in a list without diffing dates. This is //! [`Track`] with [`Unit::Days`], and [`Track::days`] is it. //! 2. **Density at a glance**, which weeks were heavy. That is a heatmap, and a //! heatmap describes as a list. //! 3. **Weekday periodicity**, "every other Tuesday", "the 15th is a Saturday". //! This is the only job that needs the seven-column wrap, because alignment //! is the whole of what makes it visible. //! //! Job 3 is the only open question, and nothing in the tree asks for it. A //! month grid otherwise renders as a [`Table`](crate::Column): seven weekday //! columns, weeks as rows, blanks for the offset. If a screen wants one, //! measure the members it needs before adding any. //! //! [`Region::Handover`] and [`Region::Ceded`] remain for the genuinely //! app-owned. The description //! names the *place* and the app owns the contents, so a screen containing a //! timeline is still a whole screen and still routable. Without it, the screens //! that make an app worth using would need a second, undescribed path beside //! the router, and two paths is how a vocabulary drifts from its app. //! //! [`Region::Widget`] sits between that limit and the primitives, and it does //! not move the limit. A widget is an assembly of members this crate *already* //! has, under a name a renderer may or may not recognise. Anything that needs a //! member the vocabulary does not have is still a finding about the vocabulary //! or still bespoke; naming an assembly buys no new expressive power, which is //! why it is safe to let the set grow outside this crate. #![forbid(unsafe_code)] /// A colour intent this crate refers to but never resolves. /// /// The string is the token name `makeover` publishes, so a renderer can look /// it up without this crate knowing what colour came back. pub trait Intent { /// The `makeover` intent token this resolves against. fn token(self) -> &'static str; } /// Which way the light falls across a two-tone edge. /// /// The whole content of a bevel, once colour and thickness are deferred. The /// light is always assumed to come from the top left: every consumer measured /// agreed on that and none of them ever varied it, so it is an invariant here /// rather than a parameter. /// /// # The two corners that belong to both edges /// /// Top-right and bottom-left are where the lit run meets the shaded one, and /// the description's claim is that they belong to *both*. How a renderer says /// that is its own business, because the answer is bounded by resolution and /// not by taste: /// /// - A terminal cell is roughly 8x17 device pixels, so giving the whole corner /// to one tone thickens that edge by a cell and reads as one run overrunning /// the other. A half-cell glyph divides the cell already, so `makeover-tui` /// splits it and recovers real information. Its box-drawing fallback cannot: /// a single stroke has no half to give, so there both corners go to dark. /// - A pixel bevel is a one-point stroke by default, which makes the corner a /// one-point square. There is nothing to divide — a diagonal seam across one /// point is sub-pixel, and antialiasing renders it as the blend a mitred join /// already produces. So `makeover-immediate` mitres and is *not* diverging; /// it is the same rule at a resolution where the split degenerates. /// /// Stated here so the difference reads as a decision rather than as drift. A /// renderer with room to divide the corner should; one without should mitre or /// pick the shaded tone, and neither is a bug. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Bevel { /// Lit from the top left: light on top and left, dark on bottom and right. Raised, /// The same edge inverted, which is also the pressed state of anything /// that draws itself [`Bevel::Raised`]. Inset, } impl Bevel { /// The edge intents, as `(top_left, bottom_right)`. /// /// Split out from any painting because the inversion *is* the idea, and /// it is the one part every renderer implements identically. #[must_use] pub const fn edges(self) -> (Edge, Edge) { match self { Self::Raised => (Edge::Light, Edge::Dark), Self::Inset => (Edge::Dark, Edge::Light), } } /// Pressing inverts. A raised control reads as inset while held. /// /// Stated here rather than left to each consumer because a cascade can /// carry a pressed state and an immediate-mode renderer cannot: audiofiles /// resolves this per call site, eighteen times. #[must_use] pub const fn pressed(self) -> Self { match self { Self::Raised => Self::Inset, Self::Inset => Self::Raised, } } } /// One side of a bevel, named by the intent it takes. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Edge { /// The lit side. Light, /// The shadowed side. Dark, } impl Intent for Edge { fn token(self) -> &'static str { match self { Self::Light => "bevel-light", Self::Dark => "bevel-dark", } } } /// A surface intent a region is filled with. /// /// `#[non_exhaustive]`, so a renderer must carry a wildcard arm and a new /// member is additive rather than breaking. The vocabulary exists to grow and /// the renderers exist to disagree about how much of it they answer, so growth /// must not be a lockstep event. The renderer's wildcard is not a hole: /// [`Fill`] is resolved through a fallible lookup, and a missing intent is /// answered with structure rather than with a substituted colour. /// /// [`Sunken`]: Fill::Sunken #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum Fill { /// The page behind everything. Page, /// A surface lifted off the page: cards, controls, menus, toasts. Raised, /// A surface floating above the page rather than resting on it. Overlay, /// The inside of a well. Well, /// A surface set back from the one it sits on, by colour and nothing else. /// /// Not a well. A well is a hole with an edge, and the two are authored in /// opposite directions: `makeover` derives `surface-well` by inverting /// against the theme's own content colour, while `surface-sunken` is /// authored and free to sit darker than raised (goingson's does). Naming /// only the well left the recessed-with-no-edge surface unsayable, which is /// what an unchosen tab is: it recedes so the chosen one can come forward, /// and it carries no bevel of its own. Sunken, } // No `fallback` here, deliberately. An earlier cut had `Fill::Well` fall back // to `Fill::Page` so a consumer on makeover 2.2.0, which has no `surface-well`, // had something to paint. makeover-tui found that wrong within a day: page is // the surface a well is usually cut into, so on a terminal that substitution // produces exactly the invisibility it was meant to prevent, and the right // answer there is a drawn edge rather than a different colour. // // Substituting one intent for another is renderer policy. The description says // what the region is and stops. impl Intent for Fill { fn token(self) -> &'static str { match self { Self::Page => "surface-page", Self::Raised => "surface-raised", Self::Overlay => "surface-overlay", Self::Well => "surface-well", Self::Sunken => "surface-sunken", } } } /// How a region sits relative to the surface behind it. /// /// Fill and bevel are named together because naming them apart is what let /// them disagree. Every consumer measured had at least one region carrying a /// raised bevel over a recessed fill: audiofiles fixed it in `raised_frame` /// and recorded the bug in its doc comment, and Balanced Breakfast still had /// twelve of them a year later. A single name for the pair makes that /// unrepresentable. /// `#[non_exhaustive]` for the same reason as [`Fill`], and in the same /// release: a depth this renderer has no drawing for should cost it a /// wildcard arm, not a compile error and a wait on someone else's publish. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum Depth { /// Level with its surroundings. No edge. Flat, /// A card laid on the panel it sits in. Raised, /// A hole in the panel, with content down inside it. For anything the /// user looks *into*: a table body, a tag tree, a text field. Well, /// Set back from what it sits on, by colour alone. No edge. /// /// The one member carrying a fill without a bevel, so a renderer cannot /// assume the two arrive together. That is deliberate and it is still the /// pairing rule: both halves come off the same `Depth`, so they cannot /// disagree, and here one half is legitimately absent. /// /// Distinct from [`Depth::Flat`], which has no fill either and inherits. /// Recessed and level-with are different claims, and only one of them /// needs a colour. Sunken, /// A surface sitting *over* the page rather than in it. A modal, a popover, /// a menu. /// /// Takes elevation and no bevel: a surface overlaying the page is lifted /// off it, and a surface in the page is cut into it. That is the same /// pairing rule the rest of the enum holds, applied to the one case where /// the separation is not an edge at all — the lift and the scrim behind it /// are already saying where the surface is. /// /// Every renderer already has the surface: `makeover-tui` carries /// `Palette::overlay`, `makeover-immediate` `Palette::elevation`, and /// `makeover-webview` emits `--elevation-overlay`. This variant is the /// route from a description to any of them, which is why it is one variant /// rather than a feature. Overlay, } impl Depth { /// The edge this depth is drawn with, if it has one. #[must_use] pub const fn bevel(self) -> Option { match self { // Sunken joins Flat here, for the opposite reason: Flat has no edge // because nothing separates it from its surroundings, and Sunken has // none because its colour is already doing the separating. Self::Flat | Self::Sunken => None, // A third reason to have no edge, which is why it gets its own arm // rather than joining the two above: an overlay is separated by the // lift and by the scrim behind it, so an edge would be a second // answer to a question already answered. Self::Overlay => None, Self::Raised => Some(Bevel::Raised), Self::Well => Some(Bevel::Inset), } } /// The surface this depth is filled with. /// /// [`Depth::Flat`] has no fill of its own: it inherits whatever it sits on, /// which is the difference between level-with and painted-the-same-colour. #[must_use] pub const fn fill(self) -> Option { match self { Self::Flat => None, Self::Raised => Some(Fill::Raised), Self::Well => Some(Fill::Well), Self::Sunken => Some(Fill::Sunken), Self::Overlay => Some(Fill::Overlay), } } /// Pressing a raised region reads as a well, and nothing else moves. /// /// [`Depth::Overlay`] is untouched along with the rest: an overlay is a /// surface, not a control, so there is nothing there to press. #[must_use] pub const fn pressed(self) -> Self { match self { Self::Raised => Self::Well, other => other, } } } /// An interaction state a region can be in, beside whatever [`Depth`] it is. /// /// Orthogonal to depth on purpose. A disabled button is still [`Depth::Raised`] /// and a disabled field is still a [`Depth::Well`], so folding either member /// into `Depth` would make [`Depth::bevel`] and [`Depth::fill`] answer for /// something that is not a depth, and would leave disabled-button and /// disabled-field sharing one variant that cannot tell them apart. /// /// # Why hover and pressed are not members /// /// The line is whether every renderer has the state to express, not whether CSS /// does. Hover is renderer policy and `makeover-webview` says so in its own /// header: a terminal and an immediate-mode painter have no pointer hovering /// over anything, and pressed already arrives through [`Bevel::pressed`] and /// [`Depth::pressed`], where it belongs, because pressing is a depth inversion /// rather than a separate condition. /// /// Focus and disabled are different in kind. A TUI has a focused widget and a /// greyed-out one; so does egui. Both were unsayable here, so all three webview /// consumers supplied them from outside the primitive by out-specifying rules /// they did not own: goingson alone carries 19 of them, and the MNW server /// another 21. That is the divergence this crate exists to end, arriving one /// layer down. /// /// # The principle this encodes /// /// A primitive owns every state it implies. A renderer that emits a hover rule /// for a thing owes disabled and the capability answer for that same thing, /// because anything less exports the completion work to N consumers who will /// each do it differently. /// /// Focus is not on that list and is not on this axis. It is the renderer's, /// decided after the description; see the crate header, "Reach, /// focus and the focus ring", for the three terms and who owns each. /// /// `#[non_exhaustive]` for the reason [`Fill`] and [`Depth`] carry it: growth /// must not be a lockstep event across the three renderers. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum State { /// Present, visible, and not answering. /// /// Not the same as absent, and deliberately not a [`Fill`]: a disabled /// control keeps the surface it always had and stops responding, so what /// changes is its content and its interactivity rather than what it is. Disabled, } impl State { /// Whether a region in this state stops answering the pointer. /// /// Stated in the description rather than left to each renderer, on the same /// reasoning as [`Bevel::pressed`]: a cascade carries it for free and an /// immediate-mode renderer resolves it per call site, so leaving it unsaid /// means resolving it once per consumer and disagreeing. #[must_use] pub const fn suppresses_interaction(self) -> bool { // A match rather than a bare `true`, so a member added to this // `#[non_exhaustive]` axis has to answer the question rather than // inheriting an answer. match self { Self::Disabled => true, } } } impl Intent for State { fn token(self) -> &'static str { match self { // Reusing the muted content intent rather than minting a // `disabled` colour. Disabled is a reduction and not a status, and // `makeover-webview`'s progress rules already record the reading // that `content-muted` is what disabled looks like. Self::Disabled => "content-muted", } } } /// What a region is saying, when it is saying something. /// /// The one intent family shared by badges, notices and nothing else. Kept /// separate from [`Fill`] because a surface is where a thing sits and a tone is /// what it means, and the three apps agree on the four statuses: /// `info_banner` / `warning_banner` in audiofiles, `.toast-info` / /// `.toast-success` / `.toast-error` in goingson, `.toast.success` / /// `.toast.error` in Balanced Breakfast. /// /// The per-tag palette (`category-one` through `category-six`) is deliberately /// not here. Which colour a *particular* tag takes is app domain, and both /// webview apps already carry it as a `data-color` attribute. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Tone { /// No status. /// /// Ordinary content, at full weight. It does not also mean muted: a /// badge reads quiet because [`Token::Badge`] answers no click, which is /// the renderer's knowledge and not this axis's. A renderer wanting a /// muted badge reaches for [`Token::interactive`] itself rather than /// expecting `Neutral` to have muted it. Neutral, /// Something worth knowing and nothing to do about it. Info, /// Something finished and it worked. Success, /// Something the user should look at before continuing. Warning, /// Something broken, or something about to be destroyed. Danger, } impl Intent for Tone { fn token(self) -> &'static str { match self { // Neutral has no status token of its own, so it takes the plain // content intent. It used to answer `content-muted`, which read // "no status" as "de-emphasised" and muted every figure value in // the webview. Muting is a renderer's call about a particular // token, not something the status axis knows. Self::Neutral => "content", Self::Info => "info", Self::Success => "success", Self::Warning => "warning", Self::Danger => "danger", } } } /// A small labelled thing that sits inside something else. /// /// Two members, because the three apps drew three taxonomies and only one line /// runs through all of them: does it answer a click. audiofiles has /// `classification_badge` (a label) against `tag_chip`, `tag_chip_removable` /// and `selectable_tag` (all of which do). Balanced Breakfast has `.tag` and /// `.badge` against `.tag-chip`. goingson is the one that has to move: its /// `.tag` and `.badge` are a single CSS rule, so every call site has to be read /// to decide which of the two it always was. /// /// The evidence that a chip is a real concept rather than a badge with a /// cursor: audiofiles inverts its bevel on press and Balanced Breakfast latches /// `.tag-chip.active` with the inset bevel. Two independent arrivals at "a chip /// holds itself down", which is exactly what [`Depth::pressed`] already says. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Token { /// Non-interactive status or count. Answers no click. Badge, /// An interactive or removable token. Answers a click, and latches if it /// stands for a filter that is either on or off. Chip { /// Whether it carries its own remove affordance. removable: bool, }, } impl Token { /// Whether this answers a click. /// /// The whole difference between the two members, and the reason a renderer /// with no hover (a touch surface, a terminal) can still tell them apart. #[must_use] pub const fn interactive(self) -> bool { matches!(self, Self::Chip { .. }) } /// How it sits, given whether it is currently latched down. /// /// A badge is flat: it is a label, and giving it an edge would say it can /// be pressed. A chip is raised, and inset while latched. #[must_use] pub const fn depth(self, latched: bool) -> Depth { match self { Self::Badge => Depth::Flat, Self::Chip { .. } if latched => Depth::Well, Self::Chip { .. } => Depth::Raised, } } } /// Something the app is telling the user, unprompted. /// /// Two concepts, not one with a placement. They differ in more than where they /// sit: a toast is transient, stacked and self-dismissing, and a banner is /// persistent, in flow, one per region, and dismissed by fixing the condition /// it reports. Folding them into one member with a placement parameter would /// make lifetime, stacking and dismissal all placement-dependent, which is the /// description leaking renderer policy. /// /// All three apps have banners: `info_banner` and `warning_banner` in /// audiofiles, five of them in goingson (sync, sync-result, vacation-day, /// timer-active, past-review), `.update-banner` in Balanced Breakfast. The two /// webview apps also have toasts. So neither member is speculative, and no app /// gains a concept it lacks except audiofiles, whose renderer may legitimately /// decline to draw a toast at all. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Notice { /// Transient, stacked, dismisses itself. Toast, /// Persistent, in flow, one per region, dismissed by fixing the cause. Banner, } impl Notice { /// Whether it goes away on its own. #[must_use] pub const fn transient(self) -> bool { matches!(self, Self::Toast) } /// How it sits. /// /// A toast floats above the page rather than resting on it, which is /// [`Fill::Overlay`]'s whole reason to exist. A banner is a card in the /// flow. Both are raised, and they are raised off different things. #[must_use] pub const fn fill(self) -> Fill { match self { Self::Toast => Fill::Overlay, Self::Banner => Fill::Raised, } } } /// The parts of a list row. /// /// `#[non_exhaustive]`: a renderer carries a wildcard arm, so a new part is not /// a lockstep event across three renderers. /// /// # Meta against Tokens /// /// The line is whether the thing has its own standing. `Meta` is one short /// trailing fact about the row, written as text: a count, a size, a date. /// `Tokens` is a set of small labelled things, each of which can be toned and /// can answer a click. "3 files" is meta. A status badge that is amber, and a /// tag you can click to filter by, are tokens. /// /// Keeping them apart is what a single widened slot would have foreclosed. A /// renderer can right-align one string and cannot usefully do the same to a /// strip of chips, and a fact that is not clickable should not be drawn as /// though it were. /// How much vertical room a part's text may take. /// /// A row is an inline run and every part in it is a leaf, so a part's text has /// always been drawn on one line and no description could say otherwise. Two /// apps say otherwise in their own stylesheets, both to the same number and /// both with a comment explaining it: Balanced Breakfast clamps a feed row's /// title to two lines (`.row--article .row-primary`, whose comment reads /// "overrides .row-primary's single flex line"), and goingson clamps a /// problem's body to two ("two lines is enough to recognize one, and the full /// text is in the task once promoted"). /// /// Two named tiers rather than a line count, and the count is what the measured /// demand argues against. Both sites want exactly one tier past the default, /// and a number invites a row whose primary is a paragraph, which is a block /// and has no business in a run. A third tier is a decision, made here, rather /// than something a call site can reach for. /// /// What a renderer owes it: `Tight` is what a run already does and needs no /// answer. `Relaxed` is at most two lines and then truncation, however that /// renderer truncates -- a webview clamps, a terminal wraps into two rows of /// cells, an immediate-mode renderer caps the galley. A renderer that cannot /// give two lines may draw one; what it may not do is grow without bound, /// because the run is a line and the row's neighbours are relying on that. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Flow { /// One line. What every part did before this type existed. #[default] Tight, /// Up to two lines, then truncated. Relaxed, } impl Flow { /// How many lines the part may take. /// /// A number here rather than in the enum, because a renderer needs one and /// a call site does not. That asymmetry is the whole argument for the /// tiers: the description says how much room the thing deserves and this /// says what that costs, so a third tier changes one line rather than every /// consumer's arithmetic. #[must_use] pub const fn lines(self) -> u8 { match self { Self::Relaxed => 2, // Including any tier added later: one line is the safe reading of // an unknown flow, since it is what the run guaranteed before flows // existed. _ => 1, } } } /// How deep a row sits inside a set: a tree, an outline, a threaded list. /// /// [`RowPart`] below already names what is *in* a row; nothing named where a /// row sits relative to its siblings, so every consumer that had a hierarchy /// carried a bare number and every renderer decided for itself what one was /// worth. /// /// # Not `Depth`, and the collision is the reason /// /// [`Depth`] is taken and means something else entirely: surface bevel -- /// `Flat`, `Raised`, `Well`, `Sunken`, `Overlay` -- a fact about a surface /// rather than a position in a hierarchy. Two meanings under one word in one /// crate is the collision that costs a reader an hour, and the word this /// concept wants is the one that would cause it. /// /// # The magnitude is the renderer's, and that is the precedent /// /// [`Awaiting`] is the shape: this crate names the fact and declines to name /// what it is worth. makeover-webview writes the rule as a custom property with /// a fallback -- the way it writes `margin-inline-start: var(--awaiting-gap, /// 0.5ch)` -- so a level has one answer per renderer and an app can override /// it. A terminal spends columns, a browser spends inline space, and neither /// number belongs in a description. /// /// # Zero is a real answer /// /// [`top`](Self::top) is the default and is what a flat list says: every row is /// at the top level, which is true and is the reading a renderer needs. An /// `Option` here would make "not nested" and "nested at zero" two spellings of /// one thing, the same argument `Discovery`'s `indexable` makes about defaults /// that are meaningful. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, PartialOrd, Ord)] #[non_exhaustive] pub struct Nesting { /// How many levels in, counting from zero. /// /// `u8` because a hierarchy a reader can follow is not 256 deep, and a /// renderer indenting by a level has to multiply it by something -- a wider /// integer here is a wider integer in every renderer's arithmetic for a /// range nothing will use. pub level: u8, } impl Nesting { /// The top level: not nested. The default, and what a flat list says. #[must_use] pub const fn top() -> Self { Self { level: 0 } } /// A row this many levels in. #[must_use] pub const fn at(level: u8) -> Self { Self { level } } /// Whether this row sits under another. /// /// The question every renderer asks before it spends anything on indenting, /// answered once here rather than by a `> 0` in each -- which is /// [`Awaiting::is_determinate`]'s reason too. #[must_use] pub const fn is_nested(self) -> bool { self.level > 0 } } #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum RowPart { /// The thing itself. What the row is called. Primary, /// Supporting text under the primary. Secondary, /// A short trailing fact: a count, a size, a date. Meta, /// Controls that act on this row. Actions, /// Small labelled things belonging to the row: badges, chips, tags. /// /// Each carries its own [`Token`] kind and [`Tone`], so a renderer with no /// colour still has the kind to work with, and one with no chips still has /// the label. That is the constrained-consumer test this vocabulary exists /// to pass, and it is why the tone lives on the token rather than on the /// part. Tokens, /// How much of a set the row's thing has done: a [`Meter`] in the row. /// /// A row holds no nodes, by the rule that a row part may not carry an /// arbitrary node, which is the door through which a description becomes a /// templating language. So the part carries the *description of a bar* rather than a node, exactly as /// `Tokens` carries tags rather than nodes. /// /// Without it a row flattens the proportion into [`Meta`](Self::Meta) as /// "3/7 subtasks", which keeps both numbers and loses the reading, the same /// way a toned status badge read as prose before `Tokens`. Proportion, } impl RowPart { /// What the part is worth when the run does not fit. /// /// The default only. A part may say otherwise, and a renderer reads the /// part rather than the role; this is what a description that has never /// heard of [`Priority`] means, which is every description written before /// the field existed. /// /// Deriving it from the role is the thing this vocabulary has otherwise /// been moving away from, and it is right here for one reason: the roles /// already encode this ranking and every consumer already assumes it. /// [`Primary`](Self::Primary) is what the row is called, and /// [`Priority::Essential`]'s own doc was written about exactly that -- /// "without it the row does not identify itself". /// /// [`Actions`](Self::Actions) is `Essential` and it is the interesting one. /// A control is not a fact, so dropping it does not cost the reader a /// detail; it costs them the only way to act on the row, and in a terminal /// it silently removes something focus had already been claimed for. A /// renderer that needs room takes it from what the row *says*, never from /// what it *offers*. /// /// An unknown member reads as [`Priority::Secondary`]: droppable, but not /// first, since guessing `Optional` for something this crate has not been /// taught would make a new member the first thing to vanish. #[must_use] pub const fn priority(self) -> Priority { match self { Self::Primary | Self::Actions => Priority::Essential, Self::Meta | Self::Proportion => Priority::Optional, _ => Priority::Secondary, } } /// The content intent the part takes. #[must_use] pub const fn intent(self) -> &'static str { match self { Self::Primary => "content", Self::Secondary => "content-secondary", Self::Meta => "content-muted", // Actions carry controls rather than text, so they inherit. Self::Actions => "content", // So do tokens: each one carries its own tone, and a part-level // intent underneath it would fight the token that sits on it. Self::Tokens => "content", // And so does a proportion, for the same reason: the meter carries // the tone, and it is about the ratio rather than about the row. Self::Proportion => "content", } } } /// How far down the heading tree a title sits. /// /// Three, and only the three that are actually headings. The bands those used /// to be filed with (goingson's `.page-header`, Balanced Breakfast's `.header` /// and `.detail-header`) are arrangement, not type, and live at /// [`Region::Band`]. One of them contains no text at all. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Heading { /// Names the whole screen. One per screen. Page, /// Names a block within the screen. Section, /// Names a sub-block inside an already-named section. Subsection, } impl Heading { /// Whether a rule follows the heading. /// /// audiofiles' `section_header` draws a separator and its /// `subsection_label` deliberately does not, which is the only thing /// distinguishing the two once weight and colour are deferred. #[must_use] pub const fn separated(self) -> bool { matches!(self, Self::Section) } } /// A control that picks between things. /// /// Three, because three distinct behaviours are in play and collapsing any two /// loses something. A segmented control picks a value; a tab picks a pane; a /// toggle picks nothing and simply holds itself on or off. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Selector { /// Exactly one of N, and the options abut. Segmented, /// Independent on or off, on its own. Toggle, /// Navigation between panes. The folder semantic. Tabs, } impl Selector { /// How the chosen option sits. /// /// Held in for a segmented control and a toggle, which is the same shape /// pressing produces and the whole economy of the idiom: one appearance, /// two reasons to wear it. A tab is the exception, because the selected /// folder tab comes *forward* to join the pane it opens. #[must_use] pub const fn chosen(self) -> Depth { match self { Self::Segmented | Self::Toggle => Depth::Well, Self::Tabs => Depth::Raised, } } /// How the options that were *not* picked sit. /// /// Describing only [`Selector::chosen`] left the unchosen option falling /// through to [`Depth::Flat`], which says it is level with the strip it /// sits in, and no renderer emitted anything for it. That is wrong in both /// directions and goingson proved it: its unchosen tabs are recessed by /// hand, and being recessed is *why* the chosen one reads as coming /// forward. Against a flat strip, a raised chosen tab is a bevel drawn on /// the strip's own colour, which is a much weaker folder effect than the /// contrast the idiom is named after. /// /// Each member is the inverse of its chosen state, which is the whole /// content of "picked" once colour is deferred: /// /// - Tabs recede, so the chosen one comes forward. /// - A segment and a toggle stand up, so the chosen one is held in. #[must_use] pub const fn unchosen(self) -> Depth { match self { Self::Tabs => Depth::Sunken, Self::Segmented | Self::Toggle => Depth::Raised, } } /// Whether the options touch. /// /// The gap is the entire difference between a segmented control and a row /// of buttons that happen to sit near each other, which is what audiofiles' /// `segmented_control` says in its own comment and why it zeroes the /// spacing by hand. #[must_use] pub const fn abutting(self) -> bool { matches!(self, Self::Segmented | Self::Tabs) } } /// What is in a region right now. /// /// The state, not the shimmer. Whether pending paints a skeleton, a spinner or /// nothing at all is renderer policy, the same class of decision that got /// `Fill::fallback` deleted from this crate. goingson and Balanced Breakfast /// each grew a skeleton with differently-named parts; both keep them, as the /// webview renderer's expression of [`Readiness::Pending`]. audiofiles has none /// and needs none, because an immediate-mode renderer simply repaints. /// /// # Four states and not two /// /// Naming only `Ready` and `Pending` leaves a screen whose list came back empty /// with nothing to say about it, so it renders an empty region or invents its /// own placeholder text and neither says what it is. Left to the apps, the /// class family drifts: `empty-state`, `empty-state--error`, `error-state` and /// six more. /// /// The four are one axis because they are mutually exclusive: a region shows its /// content, or a sign that it is coming, or a sign that there is none, or a sign /// that it broke. Never two. That is the test for one enum against several /// fields, and it is why this grew rather than a new member arriving beside it. /// /// # What is not here /// /// **The message.** "No projects yet" is content, and this names a state. It /// lives with whatever holds the region — in quasi's case a `Slot` — alongside /// the action that leads out of the emptiness, since an address is the one thing /// this crate never names. /// /// **How much room it gets.** goingson's `--compact`, `--dashboard` and /// `--padded` are the same state at three sizes, and a size is /// `makeover-geometry`'s question. Naming them here would be this crate stating /// values again. /// /// **The icon.** Presentation, and each host has its own answer or none. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum Readiness { /// The content is here. Ready, /// The content is on its way. /// /// For a region that changes *after* the first paint, and never for the /// first paint itself: see "First paint is final paint" in the crate header. /// A host that renders once, with its data already in hand, has nothing to /// say this about, and a screen arriving in this state is describing a /// moment its host should not have been in. /// /// What stands in occupies the geometry the content will occupy. A stand-in /// sized to itself rather than to what replaces it is the reflow the rule /// forbids, arriving one repaint later. Pending, /// The content arrived and there is none of it. /// /// Not a failure. An empty list is the normal state of a new install, and a /// renderer that drew it in a danger tone would be reporting a fault where /// there is none. Empty, /// The content did not arrive. Failed, } impl Readiness { /// Whether the region draws its own content, or something standing in for /// it. /// /// The question every renderer asks first, so it is answered once here /// rather than by a `matches!` in each. A state added later is a stand-in /// until proven otherwise: falling back to drawing content that may not be /// there is the worse of the two mistakes. #[must_use] pub const fn shows_content(self) -> bool { matches!(self, Self::Ready) } /// What the state means, for a renderer choosing a colour. /// /// Derived rather than carried, which is the opposite of [`Meter`] and /// [`Figure`], and the difference is worth stating: a proportion's meaning /// depends on what is being counted and only the app knows it, while /// "nothing here yet" and "this broke" mean the same thing in every app that /// will ever have them. #[must_use] pub const fn tone(self) -> Tone { match self { Self::Failed => Tone::Danger, _ => Tone::Neutral, } } } /// An action is waiting on something that resolves once, in expected finite /// time. /// /// The control-side sibling of [`Readiness`]. That enum names four states for a /// region and named nothing at all for the button that is currently doing what /// it was clicked for, so the in-flight treatment is hand-written wherever it /// exists: the MNW server carries 57 in-flight indicators against 2 guards /// against a second press, which is the spinner mostly present and the guard /// mostly absent, on a codebase whose money path is a purchase button. /// /// # What is described here, and what is not /// /// The fact is that there is an outstanding thing which will complete. Not that /// the address is remote: a heavy local query waits too, and a server calling a /// payment provider is not the browser leaving the app. Not that the call is /// slow either, which is a judgement about a call rather than a property of one. /// /// Resolving **once** is the boundary, and it is what separates this from a /// screen that keeps changing. A live screen never resolves and has no name in /// this crate yet. /// /// # One mark, two renderings /// /// | what reads it | what it does | /// |---|---| /// | a control that was pressed | goes busy and refuses a second press until it resolves | /// | a region fed by it | stands in as [`Readiness::Pending`], then fills | /// /// The two were on the table separately and both were taken. Controls alone /// leaves a slow region hand-split into its own route, which is what MNW's user /// dashboard does with its payout summary; regions alone leaves the purchase /// button unguarded. /// /// # A quantity when it is measured, never a duration /// /// [`amount`](Self::amount) is stated only when it is a measured fact about the /// payload. An upload's file length, yes; a round trip to a payment provider, /// [`None`]. A duration is described nowhere, and a renderer may not manufacture /// one from the amount either: a determinate bar shows what is done over what /// there is, plus the time it has taken so far, and never a remaining time, an /// arrival time or a rate extrapolated forwards. A prediction is wrong the /// moment the transfer stalls, and being confidently wrong is worse than being /// honestly indeterminate. /// /// This is why the crate refuses to say how long an undo stays offered and /// accepts a byte count here. The refusal is about naming a decision that /// belongs to the renderer; a file's length is not a decision, nobody chose it. /// /// # Not [`Meter`] /// /// [`Meter`] is how much of a set is done, and its own docs refuse the progress /// of an operation on the grounds that a description is built once and dropped /// while an operation runs between renders. That refusal stands. This names the /// operation and its size, which is all that is known before it starts; how much /// of it has gone through is the renderer's to observe live, and nothing round /// trips through a description to say so. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub struct Awaiting { /// Total work to get through, when it is a measured fact about the payload. /// /// `None` when the wait has no countable size, which is the common case and /// the default. /// /// Unit-agnostic on purpose. Bytes for an upload, rows for an import; what /// is being counted is the app's business and a renderer draws a proportion /// either way. pub amount: Option, } impl Awaiting { /// A wait with no countable size. #[must_use] pub const fn unmeasured() -> Self { Self { amount: None } } /// A wait whose size is known. /// /// Reach for it only with a measured figure. An estimate written in here is /// a prediction wearing a fact's clothes, and the renderer has no way to /// tell the two apart. #[must_use] pub const fn of(amount: u64) -> Self { Self { amount: Some(amount), } } /// Whether there is a proportion to draw. /// /// The question every renderer asks first, answered once here rather than by /// a `matches!` in each. False means indeterminate, which is the honest /// drawing when nothing countable was measured. #[must_use] pub const fn is_determinate(self) -> bool { self.amount.is_some() } } /// How much of a set is done. /// /// Nine sites across the two webview apps drew a bar and nothing here named /// one, so every described screen concatenated the two numbers into its /// heading text instead: "Subtasks 3/7", "Time Tracking 45m tracked / 30m est, /// over". Every fact survives that and the reading does not, which is the same /// loss `RowPart::Tokens` closed when a toned status badge became prose. /// /// # Why a pair and not a percentage /// /// Both numbers, not the percentage the apps compute from them. The percentage /// was the obvious shape and it had already been tried: goingson's /// `Task::time_progress` divides, rounds, and then clamps to 100, which throws /// away the one case the bar exists to show — 45 minutes tracked against a /// 30-minute estimate. It carries a separate `is_over_estimate` boolean beside /// it to recover the fact the clamp dropped. A pair keeps the over-run without a /// companion flag, and [`percent`](Meter::percent) is still one call away for a /// renderer that wants it. /// /// The pair is also what the apps already have at every site. All seven /// determinate bars write the ratio into the accessible layer and never the /// percentage: `title="3/7 subtasks"`, `aria-label="3 of 7 subtasks completed"`, /// a milestone's own `3/7` span. Given 43 nothing can recover "3 of 7", so a /// percentage member would have made [`label`](Meter::label) mandatory at every /// call site, which is the concatenated text this member removes, moved one /// layer down. /// /// # What this is not /// /// The progress of an *operation*. Two of the nine sites are that — goingson's /// focus timer, Balanced Breakfast's feed fetch — and they get nothing here, on /// purpose. Both are imperative controllers over a live handle, driven by a tick /// or an event stream, and a description is built once and dropped. Holding one /// would mean growing a way to update a description between renders, which is a /// different feature. [`Readiness::Pending`] and a [`Notice::Toast`] carry the /// honest part. /// /// The two cases are distinguishable in the markup rather than by taste: every /// determinate bar in both apps carries a tone, and neither operation bar /// carries one. Two codebases drew that line the same way without coordinating. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Meter<'a> { /// How much is done. May exceed [`total`](Self::total), and that is the /// case worth drawing. pub done: u32, /// How much there is to do. Zero means there is no set, not that the set is /// complete. pub total: u32, /// What the proportion means right now. /// /// Carried rather than derived, because no renderer can work it out. The /// same 90% is [`Tone::Success`] on a subtask rollup and [`Tone::Danger`] on /// a time estimate, and goingson picks between them from `is_over_estimate`, /// a fact about the data and not about the number. pub tone: Tone, /// What is being counted, if the bar says so: "subtasks", "tasks". /// /// The noun, not the ratio. A renderer builds "3 of 7 subtasks" from this /// and the two numbers; handing it the assembled string would put the /// sentence order in the description, where a terminal at one line and a /// tooltip want different ones. pub label: Option<&'a str>, } impl<'a> Meter<'a> { /// A proportion with no tone and no label. #[must_use] pub const fn new(done: u32, total: u32) -> Self { Self { done, total, tone: Tone::Neutral, label: None, } } /// What the proportion means. #[must_use] pub const fn tone(mut self, tone: Tone) -> Self { self.tone = tone; self } /// What is being counted. #[must_use] pub const fn label(mut self, label: &'a str) -> Self { self.label = Some(label); self } /// How full the bar is, 0 to 100, clamped. /// /// For drawing, which is the only thing a clamped number is good for. Ask /// [`overflowing`](Self::overflowing) before reporting it as a fact, or this /// is `time_progress`'s bug again with the clamp moved. /// /// An empty set reads as 0. Nothing is done, because there is nothing to do /// and no bar to fill; the apps guard on the count before drawing at all. #[must_use] pub const fn percent(&self) -> u8 { if self.total == 0 { return 0; } let scaled = (self.done as u64 * 100) / self.total as u64; if scaled > 100 { 100 } else { scaled as u8 } } /// Whether more is done than there was to do. /// /// The fact [`percent`](Self::percent) destroys, kept reachable so a /// renderer can mark the over-run rather than drawing a full bar and /// implying it landed exactly. #[must_use] pub const fn overflowing(&self) -> bool { self.done > self.total } /// Whether there is a set at all. /// /// A meter over nothing is sayable on purpose, for the same reason a field /// with no options is: it is what an app with an unloaded count actually /// has, and a renderer that shows an empty bar says so on screen rather than /// dividing by zero. #[must_use] pub const fn is_empty(&self) -> bool { self.total == 0 } } /// One figure with a caption: a number and what it counts. /// /// The dashboard shape. A large value over a small caption, several of them in /// a strip: a current streak, a completion rate, a total. Four put the value /// above the caption and one inverts it, which is drift inside the shape /// rather than a second shape. /// /// # Why the value is text /// /// "17", "84%", "12/30", "3d". A figure is whatever the app computed, already /// formatted, and the formatting is the app's because only it knows whether the /// number is a percentage, a duration or a ratio. This carries none of the /// arithmetic [`Meter`] carries, and that is the difference between them: a /// meter is a proportion a renderer draws, and a figure is a fact a renderer /// sets in type. /// /// # Tone is carried, for [`Meter`]'s reason /// /// Three of the five sites tone the figure by their own means — `red`/`blue` on /// the weekly review, a `${type}` class on the monthly one, `sync-stat-warn` on /// sync. So tone is carried at every site that needs it and derived at none, and /// no renderer can work out that a streak of zero is worth colouring. /// /// # What is not here /// /// Whether the figure answers a click. One of the five is a control — sync's /// "Not Applied: 3" opens the list — and an action is not something this crate /// can name: nothing here knows what a route is. That belongs beside the figure /// in whatever layer holds the actions, the same way a row's activation sits /// beside its parts rather than inside them. /// /// The arrangement is not here either. Several figures in a strip is a set, and /// a renderer given them one at a time cannot tell it is looking at one; the /// layer that holds the tree is where the set gets said. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Figure<'a> { /// The number, formatted the way the app means it to read. pub value: &'a str, /// What it counts. The caption under the value. pub caption: &'a str, /// How the value has moved, if the app is tracking that. /// /// Text, for [`value`](Self::value)'s reason: only the app knows whether a /// move reads as `+12.5%`, `+3` or `2x`, and a renderer handed a number /// would have to guess. /// /// This is what [`tone`](Self::tone) was for and had no consumer of. The MNW /// server has four screens whose stat card is a label, a value and a delta, /// and the delta is the toned part: the figure itself is an ordinary fact /// and it is the movement that reads as good or bad. Without this the delta /// has to be folded into the caption, which loses the tone and reads as a /// longer caption rather than as a second, smaller line. pub change: Option<&'a str>, /// What the figure means right now. [`Tone::Neutral`] is an ordinary fact. /// /// Applies to [`change`](Self::change) where there is one, since that is the /// part that carries the judgement, and to the value where there is not. pub tone: Tone, } impl<'a> Figure<'a> { /// A figure that is an ordinary fact. #[must_use] pub const fn new(value: &'a str, caption: &'a str) -> Self { Self { value, caption, change: None, tone: Tone::Neutral, } } /// How the value has moved. #[must_use] pub const fn change(mut self, change: &'a str) -> Self { self.change = Some(change); self } /// What the figure means. #[must_use] pub const fn tone(mut self, tone: Tone) -> Self { self.tone = tone; self } } /// Something the user can do, and what it costs to say so. /// /// Beside [`Meter`] and [`Figure`] for the reason those are here: a renderer /// that is handed the parts has to decide how to say them, and a renderer that /// is handed a finished string has already had the decision made for it. /// /// No address. Where a control goes is the app's business and every host /// follows it differently — an `hx-get`, a protocol URL, a function call — so /// the description says what the control *is* and the caller keeps what it /// does. That is the same split [`Choice`] makes. /// /// No confirmation flag either, and that one is a finding rather than an /// omission: a question asked *after* a control is pressed belongs to whatever /// is holding the interaction, and a renderer that drew it would be asking /// before there was anything to answer. /// How a picture sits in the box it is given. /// /// An intent rather than a value, so a renderer picks the expression it has: /// `object-fit` in a webview, a texture's UV rect in egui, and in a terminal a /// choice about how many cells the blit gets. Named because MNW already makes /// the distinction deliberately at 17 sites and makes it three different ways, /// which is a policy the app decided rather than one a shared crate would be /// picking by accident. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Fit { /// The picture's own proportions, and the box takes the height they imply. /// /// The default because it is the only one that shows the whole picture at /// its own shape, so a renderer that ignores this enum entirely is still /// right about the common case. A screenshot wants this; the shipped MNW /// carousel sets no `object-fit` at all, which is this. #[default] Natural, /// Fill the box and crop whatever does not fit. /// /// For a picture in a slot whose shape the layout fixed: a thumbnail, an /// avatar, cover art. 15 of MNW's 17 sites. Cover, /// Fit inside the box whole, leaving space on two sides. /// /// The letterbox. For when the whole picture matters more than filling the /// space, and the space is not the picture's shape. Contain, } /// A picture's own pixel dimensions. /// /// Deliberately not [`makeover_geometry`]'s business. Geometry answers *how /// much space a thing should get*, which is a scale question with the same /// answer on every screen. This is the intrinsic size of one asset, which is a /// fact about that asset and varies per picture. /// /// [`makeover_geometry`]: https://docs.rs/makeover-geometry #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Extent { /// Width in the picture's own pixels. pub width: u32, /// Height in the picture's own pixels. pub height: u32, } impl Extent { /// A picture's dimensions. #[must_use] pub const fn new(width: u32, height: u32) -> Self { Self { width, height } } /// Width over height, or `None` if either side is zero. /// /// The form a renderer actually reserves space with: a box that knows its /// proportion holds the right height at any width, which is what a /// responsive picture needs and what a fixed pixel height cannot give. #[must_use] pub fn ratio(self) -> Option { (self.width > 0 && self.height > 0).then(|| self.width as f32 / self.height as f32) } } /// When a picture is needed. /// /// A claim about *importance and position* rather than a fetch mechanism, which /// is why it is the description's to make: only the app knows whether a picture /// is the first thing on the screen or the fortieth thing down a list. /// /// # Eager is the default, and that is a correctness choice /// /// Emitting the webview's `loading="lazy"` for every picture reads one /// consumer's habit as a rule. Deferring a picture that is on screen at first paint does not /// save anything -- it is needed immediately either way -- and it delays the /// arrival, so the space it eventually takes is claimed later and the shift is /// more visible, not less. /// /// So the safe answer is the default and the optimisation is opted into. A /// carousel is the case that proves the two cannot be one setting for the /// renderer to choose: its first frame is on screen and its other frames are /// not, in the same widget, at the same moment. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Loading { /// Needed with the screen. Fetch it now. #[default] Eager, /// Not on screen yet. It can wait until it is near. Lazy, } /// What a [`Track`]'s integers count. /// /// `Track::fraction` never needed this -- the arithmetic is the same whatever /// the numbers mean -- which is exactly how the ruler came to assume minutes /// and print `00:00` over a month. A renderer drawing an axis has to write a /// label, and it cannot derive the unit from the numbers. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Unit { /// Minutes from the start of a day. A day view. #[default] Minutes, /// Whole days. A month strip, a sprint, a stretch of leave. /// /// A day-granularity axis is a *strip*, not a calendar: one line with /// spans laid along it. What it deliberately does not do is wrap into /// weeks, which is the shape that makes weekday periodicity visible and /// the one job of a month grid that a strip cannot take over. See the /// crate header. Days, } /// A window on an axis, in whatever [`Unit`] its [`Track`] counts. /// /// The axis a [`Track`] draws. Offsets rather than instants, because a /// description carrying a `DateTime` would carry a timezone with it and the /// vocabulary has no business holding one. The app knows which day or month /// this is; the description says how far along it a thing sits. /// /// `to` is exclusive and may exceed the natural period, which is how a span /// running past the end is said without a second date: under /// [`Unit::Minutes`], `Span::new(1320, 1560)` is 22:00 to 02:00. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Span { from: u16, to: u16, } impl Span { /// Midnight to midnight, the ordinary day. pub const DAY: Self = Self { from: 0, to: 1440 }; /// A span, clamped to a sane one. /// /// An empty or backwards span is a caller bug that should not cost a /// renderer a division by zero, so `to` is forced at least one minute past /// `from` rather than returning an error nobody can act on. Same reasoning /// as [`Share::percent`], which clamps rather than refuses. #[must_use] pub const fn new(from: u16, to: u16) -> Self { Self { from, to: if to > from { to } else { from + 1 }, } } /// The first minute on the axis. #[must_use] pub const fn from(self) -> u16 { self.from } /// One past the last minute on the axis. #[must_use] pub const fn to(self) -> u16 { self.to } /// How much the axis covers, in its track's unit. Never zero. #[must_use] pub const fn length(self) -> u16 { self.to - self.from } /// Whether an offset falls on this axis. #[must_use] pub const fn holds(self, minute: u16) -> bool { minute >= self.from && minute < self.to } } impl Default for Span { fn default() -> Self { Self::DAY } } /// Where a thing sits on a [`Track`], and for how long. /// /// The one fact a list cannot carry and the whole reason this primitive exists. /// A list says what order things come in; a track says a thing starts 135 /// minutes along and lasts 45, which is a different claim and not derivable /// from the first. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Placement { at: u16, length: u16, } impl Placement { /// A placement, clamped to a drawable one. /// /// Zero length becomes one for the same reason [`Span::new`] clamps: a /// zero-height thing is invisible rather than expressive, and every /// renderer would need its own guard. #[must_use] pub const fn new(at: u16, length: u16) -> Self { Self { at, length: if length == 0 { 1 } else { length }, } } /// Offset from the axis origin, matching [`Span`]'s. #[must_use] pub const fn at(self) -> u16 { self.at } /// How long it lasts, in its track's unit. Never zero. #[must_use] pub const fn length(self) -> u16 { self.length } /// One past its last minute. #[must_use] pub const fn end(self) -> u16 { self.at + self.length } /// Whether two placements cover any of the same time. /// /// Geometry, and deliberately not a described field. Whether an overlap is /// a *conflict* is the app's judgment -- a meeting inside a block of free /// time overlaps and is fine -- and that judgment travels the way every /// other judgment does, as a [`Tone`] on the thing itself. What a renderer /// needs in order to lay two things side by side instead of on top of each /// other is this, and it can compute it. /// /// The alternative was a `conflicts: bool` on each entry, which is state /// that can disagree with the times beside it. Two sources for one fact is /// how a screen starts rendering a conflict badge on a thing that no longer /// conflicts. #[must_use] pub const fn overlaps(self, other: Self) -> bool { self.at < other.end() && other.at < self.end() } } /// A time axis: things placed by when they happen, rather than flowed. /// /// # Why this is a primitive /// /// The argument against naming a timeline is that a description expressive /// enough to draw one is a component library wearing a description's name. It /// does not hold here, and being precise about why matters, because the /// reasoning applies to real cases. /// /// What a timeline needs that a [`List`](Region::Pane) does not is **one** /// thing: placement. Where a thing sits is a fact about the thing, the way a /// row's primary text is, and it is not derivable from order. Everything else a /// day view draws -- the labels, the gridlines, the item bodies, the tones -- /// is furniture this vocabulary already names. Measured against goingson's /// `day-planning-render.js`, the only members it needed and could not get were /// `at` and `minutes`. /// /// So the timeline was never a component library's worth of vocabulary. It was /// two integers, and the refusal was priced as though it were the whole widget. /// The test that matters is not "does this shape look complicated" but "how /// many members does it actually add, and are they facts or presentation". /// Slot heights, gridline colour, how overlaps stack and which hour scrolls /// into view on open are all presentation and all stay the renderer's, which is /// why they are absent here. /// /// # What it does not carry /// /// No pixel measure, no scroll offset, no drag affordance. A renderer draws the /// span at whatever density its host uses; `makeover-geometry` owns that the /// way it owns everything else measured in pixels. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Track { /// The window the axis covers. pub span: Span, /// The granularity a thing can be placed on, in minutes. /// /// goingson's day view is 15, giving 96 slots across a day. A renderer uses /// it to decide where gridlines fall and what a drop lands on; it does not /// constrain [`Placement`], because data arriving from a calendar does not /// respect anyone's grid. pub slot: u16, /// How often the axis labels itself, in its own unit. /// /// 60 gives an hourly ruler over a 15-minute grid, which is the common /// shape and the reason this is separate from `slot`. Zero means an /// unlabelled axis. pub tick: u16, /// What `span`, `slot`, `tick` and every [`Placement`] on it count. /// /// The one field here a renderer cannot derive, and the reason it exists: /// [`fraction`](Self::fraction) is unit-agnostic, so a day-granularity /// track produced correct geometry under an hours-and-minutes ruler until /// this was added. Geometry never needed it; a label always did. pub unit: Unit, } impl Track { /// An ordinary day: midnight to midnight, quarter-hour slots, hourly ticks. pub const DAY: Self = Self { span: Span::DAY, slot: 15, tick: 60, unit: Unit::Minutes, }; /// A track over `span`, with the day's usual granularity. #[must_use] pub const fn over(span: Span) -> Self { Self { span, slot: 15, tick: 60, unit: Unit::Minutes, } } /// A strip of whole days: one slot a day, a label a week. /// /// The shape a stretch of leave or a sprint is drawn on. Not a calendar -- /// it does not wrap into weeks, and the crate header says why that /// distinction is the whole of what a month grid still has over this. #[must_use] pub const fn days(span: Span) -> Self { Self { span, slot: 1, tick: 7, unit: Unit::Days, } } /// How many slots the axis holds. /// /// Rounded up, so a span that does not divide evenly by `slot` still has a /// slot covering its tail rather than dropping it. Never zero: `slot` of 0 /// reads as one slot spanning the whole axis rather than a division by /// zero, since a renderer asking this question has already committed to /// drawing something. #[must_use] pub const fn slots(self) -> u16 { if self.slot == 0 { 1 } else { self.span.length().div_ceil(self.slot) } } /// Where a placement sits on the axis, as a fraction from 0.0 to 1.0. /// /// The one calculation every renderer would otherwise write itself, and the /// place the three would drift apart. Clamped, so a placement outside the /// span draws at the edge rather than off it -- an event running past /// midnight is a real thing and truncating it is better than either /// panicking or drawing it somewhere impossible. #[must_use] pub fn fraction(self, minute: u16) -> f32 { let span = f32::from(self.span.length()); let offset = f32::from(minute.saturating_sub(self.span.from())); (offset / span).clamp(0.0, 1.0) } } impl Default for Track { fn default() -> Self { Self::DAY } } #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Act<'a> { /// What the control says. pub label: &'a str, /// The key that reaches it where a host has keys. /// /// The one member written for a terminal before there was one. A webview /// hangs it off `accesskey` or ignores it; a terminal has nothing else to /// offer, so this is the whole of how a control is reached there. pub key: Option<&'a str>, /// What pressing it means. [`Tone::Danger`] is the destructive one. pub tone: Tone, /// Disabled, or nothing said. /// /// [`State::Disabled`] is what changes what a renderer may do: see /// [`State::suppresses_interaction`], which is what says a disabled control /// is drawn and not reachable. A control's focus is not sayable here at /// all: see the crate header, "Reach, focus and the focus ring". pub state: Option, /// A sentence that is always true of this control, shown rather than hunted /// for. /// /// Standing help, not a message and not a tooltip. Half the hosts that read /// this have no pointer: a hover is one spelling of it, and the shipped /// apps reached for that spelling only because egui and a browser both had /// one. What is being said is that the sentence is true, never that it is /// hidden until a pointer arrives. /// /// # Why it is here rather than a layer up /// /// A hint left to `quasi_router::Act` alone means each renderer draws it /// for itself: `makeover_tui` had no hint to read, so quasi-tui built /// the muted line, and quasi-immediate called `on_hover_text` outside /// [`crate::Act`] rather than inside it. `Field::hint` was here the whole /// time, so the same idea sat at two layers depending on which thing /// carried it, and a host that was not quasi could say it of a field and /// not of a control. /// /// What kept it out was price rather than doubt: this crate declares /// `links`, so a member here moves 25 manifests across 12 repos. That is a /// release's forward-fix pass, which is a cost and was being read as a /// barrier. /// /// # What a renderer owes it /// /// Somewhere to put it, or nothing. Dropping it is legitimate; drawing it /// *instead of* the label is not, and neither is drawing it in a way that /// takes it out of the accessible tree, which is the failure `title` alone /// has on a browser. Nothing may live only in a hint. /// /// `None` is a control whose label is the whole of it, which is nearly all /// of them. pub hint: Option<&'a str>, } impl<'a> Act<'a> { /// An ordinary control, reachable, with no key. #[must_use] pub const fn new(label: &'a str) -> Self { Self { label, key: None, tone: Tone::Neutral, state: None, hint: None, } } /// The sentence that is always true of it; see [`hint`](Self::hint). /// /// A renderer with nowhere to put it drops it, so this must never be the /// only place a fact appears. #[must_use] pub const fn hinted(mut self, hint: &'a str) -> Self { self.hint = Some(hint); self } /// The key that reaches it. #[must_use] pub const fn key(mut self, key: &'a str) -> Self { self.key = Some(key); self } /// What pressing it means. #[must_use] pub const fn tone(mut self, tone: Tone) -> Self { self.tone = tone; self } /// Focus, or disabled. #[must_use] pub const fn state(mut self, state: State) -> Self { self.state = Some(state); self } /// Whether the control is drawn and does not answer. #[must_use] pub fn disabled(&self) -> bool { self.state.is_some_and(State::suppresses_interaction) } } /// A named part of a screen. /// /// The thing `makeover-geometry` deliberately does not name: it names the space /// *between* things by relationship, and nothing named the things. Six named /// members, taken from what the two webview apps actually use, plus /// [`Region::Handover`] and [`Region::Ceded`] for the parts no description /// should reach. Both apps' /// `layout.css` currently names exactly two things, `.raised` and `.well`, so /// this layer is absent rather than divergent, which makes it the cheapest of /// the schemas to add and the easiest to over-build. /// /// `#[non_exhaustive]`, for [`RowPart`]'s and [`Readiness`]' reason: the member /// after this one should not be a lockstep event across three renderers. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum Region<'a> { /// A full-width strip with a title slot and an actions cluster, either of /// which may be empty. goingson's `.page-header`, Balanced Breakfast's /// `.header` and `.detail-header` are all this, differing only in which /// slots they fill. Band, /// A persistent column beside the content, holding navigation. Sidebar, /// A region of content with its own scroll. Pane, /// Things that belong together, and nothing else. /// /// The block [`Heading::Section`] names, which the vocabulary otherwise /// cannot contain. A section heading is a leaf sitting /// *beside* the things it names, so nothing said where a section started or /// ended and a renderer learned one had ended only because the next heading /// arrived. /// /// # The measurement /// /// 41 [`Heading::Section`] sites across the ten screens described through /// the router, not one of them contained. audiofiles' settings screen is the /// clearest: one pane holding a heading, a field, a heading, two toggles, a /// heading, a toggle and a heading, which is four sections and no /// containers. Under the hand-written CSS the ports are replacing the same /// block is spelled `.settings-section` in goingson, `.form-section` and /// `.content-section` in the MNW server, `.help-section` in Balanced /// Breakfast: three apps, four names, one shape. /// /// # Why the existing members were the wrong answer /// /// [`Pane`](Self::Pane) is what apps reached for, and it is 28 of the 45 /// regions in the described screens. It claims a scroll of its own and /// [`Depth::Well`], so four settings groups inside a pane are four wells /// inside a well and four scroll contexts. Neither claim is true of a group. /// /// [`Widget`](Self::Widget) is wrong from the other side. Its own docs say a /// widget is never how a primitive gets added by the back door, and a run of /// related controls under a heading is furniture any app would have, which /// is the generic-against-bespoke bar a primitive has to clear. /// /// # What it does not carry /// /// **A heading.** A group usually has one and it is an ordinary node in the /// body, the way it already was. A group of related toggles with no heading /// is a real thing and a mandatory slot would forbid it. /// /// **A depth.** [`Depth::Flat`], on [`Handover`](Self::Handover)'s reasoning: /// it inherits, and an app that wants its group in a well puts it in a /// [`Pane`](Self::Pane), which composes rather than adding a knob here. /// /// **A colour.** Distinguishing sibling groups by colour is the thing this /// member was asked for and it is deliberately not stated here. The /// description says these things belong together; which of the theme's /// categorical colours a renderer reaches for, and whether it reaches for /// one at all, is derived from sibling order at the renderer. A terminal /// that tints nothing and separates with a rule is honouring this. Group, /// Two panes side by side, where the left chooses what the right shows. Split, /// Peer regions across, all of them equals. /// /// A kanban board's columns, and the shape [`Split`](Self::Split) is not: /// a split's two panes stand in a master-detail relationship, where the /// left chooses what the right shows. These choose nothing about each /// other. Each is a whole region and the set is the arrangement. /// /// # What it does not carry /// /// **How many.** The children say, and a count here would be a second /// source for something the description already states by containing them. /// /// **How wide.** Peers are equal by definition, so there is no [`Share`] to /// state. A board whose columns wanted different widths would be a /// different member, and no app has one. /// /// **What happens when there is no room.** Scroll across, wrap, or collapse /// to one column at a time: all three are right on some host, none is /// derivable from the description, and every one of them is presentation. /// A terminal that stacks them vertically is honouring this, not degrading /// it. /// /// # Why it is not an `Arrangement` /// /// [`Arrangement`] is the page's shape, and a board is usually a region /// *inside* a page that also has a band over it. Naming it here composes; /// naming it there would make a screen either a board or a list-detail and /// never a band above a board. It also keeps [`Arrangement::share`] /// meaningful, which a peer arrangement has no answer for. Columns, /// A set of panes, one visible at a time, and a [`Selector::Tabs`] that /// chooses between them. /// /// Says nothing about where the strip sits. A row over the panes, a column /// beside them, a wrapped run of links under them: all three are the same /// member drawn by a renderer that knows its host, the way the strip's /// overflow is. TabGroup, /// Content over a scrim, taking input until dismissed. Modal, /// A region this crate names the *place* of, whose contents the app still /// owes every host. /// /// The escape hatch, and the thing that keeps the description honest about /// its own limits. A day-plan timeline, a kanban board, a calendar and the /// paint interaction over the timeline are not describable here and are not /// going to become describable: a description expressive enough to produce /// a timeline is a widget library wearing a description's name. /// /// But a screen containing one still has to be a screen. Without this /// member the description covers only the boring screens, and the four that /// make goingson worth using would need a second, undescribed path beside /// the router. Two paths is how the vocabulary starts drifting from the app /// again, which is the exact failure this crate exists to end. /// /// So the description says "a thing called `day-plan` goes here" and stops. /// The name is opaque: this crate never interprets it, and no renderer is /// expected to know what it means beyond handing the space over. /// /// # What separates it from [`Ceded`](Self::Ceded) /// /// **A fill is owed here in every host's currency.** A renderer handed one /// of these and given nothing to put in it is looking at a hole the app /// meant to fill, and saying so is the honest drawing. [`owed`](Self::owed) /// is how it asks. /// /// That is the whole of the split. Before it there was one opaque member, /// so a region the description had given up on and a region nobody had /// converted yet were the same value, and both drew as a silently empty /// box on the two renderers that answer no fill. Handover { /// What the app calls it. Never interpreted here. name: &'a str, }, /// A region this crate names the place of, whose contents no host is owed. /// /// The other half of the old single opaque member. The app has decided this /// space is not the description's to fill and is not going to become so: /// a chart, a waveform, a rendered picture of domain data with marks /// painted over it at positions no description knows. /// /// **Silence is the correct drawing.** A renderer with no fill for this /// draws nothing and is right to; unlike [`Handover`](Self::Handover) there /// is nothing missing. That is what makes the pair worth two members rather /// than a flag: the two want opposite behaviour from a renderer that cannot /// fill them, and one name cannot carry both. /// /// The measured sites are MNW's analytics charts, which already carry the /// ruling that a bar chart is not describable and should not be, and /// audiofiles' waveform, whose exclusion had no vocabulary to live in and /// was recorded in a doc comment instead. Ceded { /// What the app calls it. Never interpreted here. name: &'a str, }, /// A named assembly of things the vocabulary already says. /// /// The third tier, between a primitive and the two opaque members. /// /// # What separates it from the two members either side /// /// A primitive is a thing every renderer draws from scratch, and the test /// it has to pass is that every host has an honest answer. A carousel fails /// that test — a terminal has no carousel — which is the same refusal /// `Node::Html` got and is why the carousel sat unsayable for months. /// /// [`Handover`](Self::Handover) fails it from the other side. It is for /// what one app owns and nobody will build twice, and it carries *no* /// contents: the description names the place and stops. A carousel is /// furniture any app would have, and every part of it — an ordered set of /// frames, a position, prev and next, a strip of position indicators — is /// already sayable. Only the assembly had no name. /// /// So this member is the pair the other two are not: a name **and** /// contents. The contents are the assembly, in the region's own body, said /// in members that already exist. /// /// # Why the name does not have to be understood /// /// A renderer that recognises the name draws it the way its host does it: a /// carousel in a webview, a pager with a count in a terminal, a selector in /// egui. A renderer that does not recognise it walks the body, which is /// primitives all the way down and which it can already draw. /// /// That is what lets the widget set be **open** without every renderer /// knowing every widget. An unrecognised widget degrades to its assembly /// instead of failing, so a second or third party can name one without /// three renderers releasing in lockstep to accept it. Contrast /// [`Handover`](Self::Handover), which no renderer can degrade: there is /// nothing under it to fall back to. /// /// # What it does not do /// /// A widget is an assembly of things the vocabulary *already* says, so it /// buys no expressive power. Anything needing a member the vocabulary does /// not have is a finding about the vocabulary, and the answer to a finding /// is to add the member. A widget is never the way a primitive gets added /// by the back door. A timeline is describable because [`Track`] was added /// to say it, not because a screen was dressed up as an assembly. Widget { /// What the assembly is called. This crate never interprets it, and a /// renderer is free not to know it. name: &'a str, }, } impl<'a> Region<'a> { /// How the region sits on what is behind it. #[must_use] pub const fn depth(self) -> Depth { match self { Self::Band | Self::Sidebar | Self::Split | Self::TabGroup => Depth::Flat, // Flat, and it inherits. A group says its contents belong together // and says nothing about the surface they sit on, so a group in a // pane is in a well and a group on the page is on the page. An app // wanting one lifted puts it in a `Pane`. Self::Group => Depth::Flat, // Flat, and it is the container rather than the columns. Each // column is its own region and brings its own depth; a well here // would put a second edge around a row of wells. Self::Columns => Depth::Flat, // A pane is looked into, the same as a table body or a tag tree. Self::Pane => Depth::Well, Self::Modal => Depth::Raised, // Flat because it inherits: a bespoke region takes the depth of // whatever frames it. An app that wants its timeline in a well puts // it in a `Pane`, which composes rather than adding a knob here. // // A widget inherits for the same reason and it matters more here, // because a widget is drawn by whichever renderer recognises it. A // depth set here would be this crate deciding that a carousel is // raised on every host, which is the kind of value the deferral // rule exists to refuse. Self::Handover { .. } | Self::Ceded { .. } | Self::Widget { .. } => Depth::Flat, } } /// Whether this crate can say anything about the region's contents. /// /// A renderer walks the description and hands every region it understands /// to the right drawing code. This is how it tells the two apart, and the /// reason it is a method rather than a `matches!` at each renderer: there /// is exactly one opaque member and there should stay exactly one. /// /// [`Widget`](Self::Widget) is described, and that is the whole of what /// separates it from the two opaque members here. All three carry a name /// this crate never interprets; only the widget carries contents under it. /// A renderer that does not recognise a widget's name still walks its body, /// so there is nothing for it to hand over and nothing it cannot draw. #[must_use] pub const fn described(self) -> bool { !matches!(self, Self::Handover { .. } | Self::Ceded { .. }) } /// Whether a fill is owed here, for a renderer that has none. /// /// The question the single opaque member could not answer. True for /// [`Handover`](Self::Handover): the app meant to fill this and a renderer /// with nothing to put in it should say so. False for everything else, /// [`Ceded`](Self::Ceded) included, where silence is the correct drawing /// because nothing is missing. /// /// A method rather than a `matches!` at each renderer, for /// [`described`](Self::described)'s reason: three renderers writing the /// same match is three chances to disagree about what an empty region /// means. #[must_use] pub const fn owed(self) -> bool { matches!(self, Self::Handover { .. }) } /// The name an app gave this region, if it gave one. /// /// [`Handover`](Self::Handover), [`Ceded`](Self::Ceded) and /// [`Widget`](Self::Widget) are the members that carry a name, for two /// different purposes: the first two say what the app puts in the space, /// the third says what the assembly under it is called. A renderer dispatching on either wants the string without /// caring which member it came from, and writing that `matches!` at each /// renderer is how the two drift apart. #[must_use] pub const fn name(self) -> Option<&'a str> { match self { Self::Handover { name } | Self::Ceded { name } | Self::Widget { name } => Some(name), // Spelled out rather than a wildcard, so a member added later has // to answer whether it carries a name instead of inheriting `None` // by sitting under a `_`. Self::Band | Self::Sidebar | Self::Pane | Self::Group | Self::Split | Self::Columns | Self::TabGroup | Self::Modal => None, } } } /// How many of a region's children are visible at once. /// /// One sentence covering three shapes: *this region holds several children and /// shows some of them, and the reader can change which.* A tab group, a /// carousel and a disclosure all need it, and without it a renderer has two /// moves: hardcode a widget name, or draw every child. That is what puts /// per-widget code in renderers. /// /// # What is here and what is not /// /// The *kind*, and only the kind. Which child is currently up is the current /// answer, and a layer that defers every address does not hold the current /// answer either — the split [`Selector`] already makes, where this crate says /// what kind of chooser a thing is and the router says which option is picked. /// So a holder of regions carries the index and the per-child label beside this. /// /// # What a renderer does with it /// /// Derives its chrome, once, for every widget rather than per name: /// /// - Children carrying labels get a strip of the labels, the current one marked. /// - Children carrying none get previous, position, next. /// - [`AtMostOne`](Self::AtMostOne) over one child gets a summary line that /// opens. /// /// The name on [`Region::Widget`] survives as app vocabulary, for a renderer /// that wants to do something *special* with one, which is what it should have /// been from the start. /// /// Degradation runs the way it already did: a renderer ignoring this draws every /// child, which is more content rather than less. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Showing { /// Every child, in order. What every region did before this existed. #[default] All, /// Exactly one. A carousel, a tab group. One, /// One, or none. A disclosure, which is closed until it is opened. AtMostOne, } impl Showing { /// Whether the reader can change which child is up. /// /// The question every renderer's region arm asks before deriving any /// chrome, and a method rather than a `matches!` at each renderer for /// [`Region::name`]'s reason: three renderers writing the same comparison is /// how they come to disagree about a member added later. #[must_use] pub const fn selective(self) -> bool { !matches!(self, Self::All) } /// Whether showing nothing is a legal state. /// /// True only for [`AtMostOne`](Self::AtMostOne). A renderer needs this to /// know whether its control closes as well as moves: a carousel's row moves /// between frames and never reaches empty, and a disclosure's summary line /// is the same control wearing its closed state. #[must_use] pub const fn dismissible(self) -> bool { matches!(self, Self::AtMostOne) } } /// A window onto a sequence: where it starts, how much it covers, and how long /// the sequence is when that is known. /// /// The mechanism under two things the vocabulary deliberately keeps apart. A /// carousel is a window of one frame over children that are all present; a /// paged list is a window of a page over rows most of which were never fetched. /// Those are different facts and they stay different types — [`Showing`] says /// which child is up, [`Paging`] says where a reader is in a query — but the /// arithmetic underneath is one piece of code, so a terminal and a browser /// cannot come to disagree about which frame is last. /// /// # Why `of` is optional and `count` is not /// /// `count` is what is on screen and is therefore always known. `of` is the /// length of the thing being windowed, and a host that cannot count says so by /// leaving it empty **for the life of the screen**. It is never "not counted /// yet": see "First paint is final paint" in the crate header. A total that /// turns up on a later pass widens the text that prints it. /// /// # Clamping /// /// Every derivation clamps rather than refusing, and a zero `count` answers /// `None` rather than dividing. A window past the end is a bug in the host, and /// a renderer that answered it by drawing nothing would report a region that /// vanished, which is the hardest kind of bug to find from what is on screen. /// [`Share::percent`] clamps for the same reason. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] pub struct Window { /// The index into the sequence where the window starts. pub from: usize, /// How many the window covers. One, for a carousel. pub count: usize, /// How long the sequence is, when the host can say. pub of: Option, } impl Window { /// A window of `count`, starting at `from`, over a sequence of unknown /// length. #[must_use] pub const fn new(from: usize, count: usize) -> Self { Self { from, count, of: None, } } /// How long the sequence is. #[must_use] pub const fn of(mut self, of: usize) -> Self { self.of = Some(of); self } /// One item of a sequence whose length is known. A carousel frame. #[must_use] pub const fn frame(at: usize, of: usize) -> Self { Self { from: at, count: 1, of: Some(of), } } /// Which window this is, counting from zero. /// /// `None` when `count` is zero, which is the only input with no answer /// rather than a clamped one. #[must_use] pub const fn index(self) -> Option { if self.count == 0 { return None; } Some(self.from / self.count) } /// How many windows the sequence holds. /// /// `None` unless both the length and a non-zero `count` are known. A /// partial answer here would be a renderer drawing "of 0". #[must_use] pub const fn windows(self) -> Option { match self.of { Some(of) if self.count > 0 => Some(of.div_ceil(self.count)), _ => None, } } /// Whether anything sits before this window. #[must_use] pub const fn has_before(self) -> bool { self.from > 0 } /// How many sit after this window, when the length is known. /// /// Here rather than in each renderer for [`Showing::selective`]'s reason: /// three of them writing the same subtraction is how they come to disagree, /// and this one has an underflow in it for whoever writes it fourth. #[must_use] pub const fn after(self) -> Option { match self.of { Some(of) => Some(of.saturating_sub(self.from.saturating_add(self.count))), None => None, } } /// Whether anything sits after it. /// /// `true` when the length is unknown: a host that cannot count cannot rule /// out more, and offering a way forward that turns out to be empty is the /// cheaper of the two mistakes. #[must_use] pub const fn has_after(self) -> bool { match self.of { Some(of) => self.from.saturating_add(self.count) < of, None => true, } } /// The window with `from` brought inside the sequence. /// /// A no-op when the length is unknown, since there is nothing to clamp /// against. #[must_use] pub const fn clamped(mut self) -> Self { if let Some(of) = self.of && self.from >= of { // `max(1)` by hand: `Ord::max` is not const yet, and a zero-count // window would otherwise clamp onto the end rather than inside it. let step = if self.count == 0 { 1 } else { self.count }; self.from = of.saturating_sub(step); } self } } /// Where a reader is in a set that arrived in parts. /// /// A [`Window`] wearing the paged reading of itself. Distinct from a carousel's /// window at the top level on purpose, because the intent differs and a call /// site should say which one it means, while the arithmetic below is shared so /// the two cannot drift apart. /// /// # The two idioms, and which one a renderer may draw /// /// Load-more and numbered pages are both this type. Which is honest is /// [`paged`](Self::paged): a set whose page size is known can be drawn as /// "Page 3 of 8", and one without can only be drawn as "150 of 400" and a way /// forward. Saying it here rather than letting each renderer guess is the point /// — three renderers inferring it from the numbers is how they come to disagree. /// /// # What it does not carry /// /// No addresses. `makeover-layout` cannot name an action, and the way to ask for /// the next part is the host's: `quasi_router` pairs this with the addresses the /// same way `Row` pairs its parts with `Row::activate`. That split is the reason /// this type is reusable by a carousel, which has nothing to ask. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] pub struct Paging { /// The window onto the set. pub window: Window, /// Whether the parts are a fixed size, and so whether pages are countable. /// /// `false` for load-more, where the window simply grew and "page 2" would /// name nothing. pub paged: bool, } impl Paging { /// A page of `per`, starting at `from`. #[must_use] pub const fn pages(from: usize, per: usize) -> Self { Self { window: Window::new(from, per), paged: true, } } /// The first `shown`, with more behind them. /// /// The load-more shape: the window starts at the beginning and grows, so /// there is no page to number. #[must_use] pub const fn more(shown: usize) -> Self { Self { window: Window::new(0, shown), paged: false, } } /// How many there are altogether. /// /// Left unsaid by a host that cannot count, and left unsaid **for good**: /// a total arriving later widens whatever prints it. See "First paint is /// final paint" in the crate header. #[must_use] pub const fn of(mut self, of: usize) -> Self { self.window = self.window.of(of); self } /// Which page this is, counting from one, when pages are countable. /// /// One-based because it is read aloud. [`Window::index`] is the zero-based /// form for anyone indexing with it. #[must_use] pub const fn page(self) -> Option { if !self.paged { return None; } match self.window.index() { Some(index) => Some(index + 1), None => None, } } /// How many pages there are, when that is countable. #[must_use] pub const fn pages_total(self) -> Option { if !self.paged { return None; } self.window.windows() } /// How many are on screen. #[must_use] pub const fn shown(self) -> usize { self.window.count } /// How many there are, when the host counted. #[must_use] pub const fn total(self) -> Option { self.window.of } /// How many are not shown yet, when the host counted. /// /// The figure a load-more control puts in its label. `None` is the honest /// and common case: a set that cannot say how many more there are still has /// a way to ask for them. #[must_use] pub const fn remaining(self) -> Option { self.window.after() } /// Whether there is anything further on. #[must_use] pub const fn has_more(self) -> bool { self.window.has_after() } /// Whether there is anything back the other way. #[must_use] pub const fn has_previous(self) -> bool { self.window.has_before() } } /// How much of the width an arrangement's first region takes. /// /// Nothing said how much room a region got, so every renderer invented its own /// number and two hosts showing one screen disagreed about its proportions. A /// webview never noticed, because the stylesheet answered once for every /// consumer; a terminal has no stylesheet to inherit from, so `quasi-tui` /// picked 24 columns for a sidebar and 40% for a list pane and neither had /// anything behind it. /// /// # A proportion, never a unit /// /// Held as a percentage, and that is the only form it comes in. A description /// carrying columns would be describing a terminal and one carrying pixels a /// webview, and the whole point is that both honour the same fact: a terminal /// resolves it against a column count, a webview writes it into a grid, and /// neither has to know what the other did. /// /// It is not [`makeover_geometry::Ratio`]'s job either, which was the first /// guess. Geometry is scales that answer the same for every screen and takes /// no input that would let a sidebar screen differ from a list-detail one. /// /// [`makeover_geometry::Ratio`]: https://docs.rs/makeover-geometry #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] pub struct Share(u8); impl Share { /// What a sidebar takes, when nobody says otherwise. /// /// A quarter. `quasi-tui` drew 24 columns, which is a quarter of a /// 96-column terminal and about a fifth of a wide one; a quarter is that /// number said in the form a webview can honour too. pub const SIDEBAR: Self = Self(25); /// What the list side of a list-detail takes, when nobody says otherwise. /// /// `quasi-tui`'s 40%, which was already a proportion and is the one number /// this member did not have to invent. pub const LIST: Self = Self(40); /// A share of the width, as a percentage. /// /// Clamped to 5..=95 rather than refused. A description that asked for a /// region of nothing is a bug in the app, and a renderer drawing a region /// zero cells wide reports it as a region that vanished, which is the /// hardest kind of bug to find from what is on the screen. #[must_use] pub const fn percent(percent: u8) -> Self { Self(if percent < 5 { 5 } else if percent > 95 { 95 } else { percent }) } /// The share as a percentage. #[must_use] pub const fn as_percent(self) -> u8 { self.0 } /// This share of a width, rounded to the nearest whole unit. /// /// What a terminal calls to turn the proportion into columns. At least one, /// because a region the description named should be visible: a screen /// 3 columns wide is unusable either way, and a sidebar that is there is a /// truer picture of the description than a sidebar that is not. #[must_use] pub const fn of(self, whole: u16) -> u16 { let taken = (whole as u32 * self.0 as u32).div_ceil(100); if taken == 0 { 1 } else { taken as u16 } } } /// How a screen is laid out. /// /// Three, and no one of them is a variant of another. goingson is list-detail, /// Balanced Breakfast is sidebar plus content, and MNW's embeds are one region /// filling the document. The tab group is a modifier rather than a member, /// because goingson uses it *inside* the same content region rather than /// instead of one. /// /// This exists at all because the router has to be able to express a screen /// rather than only a control. Discovering the arrangement layer missing after /// the renderers exist is a redesign; naming two now is a morning. /// /// # Why the share rides here /// /// A share is per-arrangement: how much a sidebar takes and how much a list /// side takes are different questions, and this enum is the only thing that /// knows which one is being asked. Geometry would have had to invent a channel /// to be told. /// /// [`list_detail`](Self::list_detail) and /// [`sidebar_content`](Self::sidebar_content) build these with the default /// shares, so a screen that has no opinion does not have to have one. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Arrangement { /// A list that chooses what the detail beside it shows. ListDetail { /// Whether the detail side is a [`Region::TabGroup`]. tabbed: bool, /// How much of the width the list side takes. share: Share, }, /// Navigation down the side, content filling the rest. SidebarContent { /// How much of the width the sidebar takes. share: Share, }, /// One region, filling the document. /// /// The other two are both about dividing a width between two regions, so a /// screen that is one region had to borrow one of them and then undo it: /// MNW's five embeds said `list_detail(title, false)` and the host spent a /// `display: block` cancelling the grid that produced. A host writing CSS /// to contradict the description rather than to add to it is the thing /// this member ends. /// /// Carries no [`Share`], because there is no division to describe. That is /// why [`share`](Self::share) answers `None` here. Single, } impl Arrangement { /// A list and a detail beside it, at the default share. #[must_use] pub const fn list_detail(tabbed: bool) -> Self { Self::ListDetail { tabbed, share: Share::LIST, } } /// A sidebar and content beside it, at the default share. #[must_use] pub const fn sidebar_content() -> Self { Self::SidebarContent { share: Share::SIDEBAR, } } /// How much of the width the first region takes, when two regions divide it. /// /// `None` for [`Single`](Self::Single): one region takes the width, and a /// renderer that asked how to divide it was asking the wrong question. It /// answers `Option` rather than a full-width `Share` so that a host cannot /// quietly draw a one-region screen as a grid with an empty second column. #[must_use] pub const fn share(self) -> Option { match self { Self::ListDetail { share, .. } | Self::SidebarContent { share } => Some(share), Self::Single => None, } } /// The same arrangement, at this share. /// /// [`Single`](Self::Single) is returned unchanged: it has no division to /// set, so a share named for it is a statement about nothing rather than an /// error worth refusing a screen over. #[must_use] pub const fn with_share(self, share: Share) -> Self { match self { Self::ListDetail { tabbed, .. } => Self::ListDetail { tabbed, share }, Self::SidebarContent { .. } => Self::SidebarContent { share }, Self::Single => Self::Single, } } } /// How wide the content of a whole screen runs. /// /// Both are the description's, which is what answering the two together /// settled. /// /// Measured in the MNW server, where 69 of 72 templates carry exactly one of /// three mutually exclusive classes and the choice is per screen. GoingsOn /// reaches for `max-width` 56 times and Balanced Breakfast 12, neither with a /// token for it, so three apps were solving one thing by hand. /// /// # Named for the measure, not for MNW's classes /// /// A renderer that is not a browser has to answer this too, and `padded-page` /// tells a terminal nothing. The three say how wide the text runs, which is a /// question every renderer can answer: a webview with a `max-width`, a terminal /// with gutters, an immediate-mode frame with its own width. /// /// `#[non_exhaustive]` for [`Fill`]'s reason. The set is closed today because /// the measurement found three, and a fourth arriving should not be a lockstep /// release across nine repos. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)] #[non_exhaustive] pub enum Measure { /// The whole width, with gutters. The default, and 53 of the 69. /// /// What a dashboard, a table and a settings screen want: the content is /// wide because the content *is* wide, and constraining it would waste the /// window. #[default] Wide, /// Capped at a comfortable page width, centred. 13 of the 69. /// /// A form, a sign-in, a purchase. Content that does not get better by /// getting wider, but is not prose either. Contained, /// Capped at a line length that reads well. 3 of the 69. /// /// Prose. The narrowest of the three, and the one with a reason outside /// taste: a line of text past roughly 75 characters costs the reader the /// return sweep. Reading, } impl Measure { /// A stable name, for a renderer that needs to spell it. /// /// Here rather than in each renderer for [`Sort::as_str`]'s reason: three /// renderers spelling one enum is three chances to spell it differently. #[must_use] pub const fn as_str(self) -> &'static str { match self { Self::Wide => "wide", Self::Contained => "contained", Self::Reading => "reading", } } } /// What kind of value a form field takes. /// /// The union of the two vocabularies that diverged, which is what triggered /// this crate. They have since converged on their own: both apps now have a /// `renderFormField` emitting the same anatomy, and what is left differing is /// the kind set, the error shape, and whether the return is a string or a node. /// /// Validation is deliberately absent. Neither app has a shared story (goingson /// validates after collecting the form data, with per-field transform hooks; /// Balanced Breakfast has `required` and nothing else), and a schema that /// describes fields but not constraints acquires a constraint layer per app, /// which is exactly how the current divergence started. Naming it absent is a /// decision; leaving it unmentioned would not be. /// `#[non_exhaustive]` for the reason [`Fill`] is: renderers match on this and /// the set keeps growing, so growth must not be a lockstep event. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum FieldKind { /// A single line of text. Text, /// A single line of text that must never be echoed, logged or round-tripped /// through anything that might persist it. Secret, /// A number. Number, /// A number inside bounds the user drags across, where the range being /// visible is the point. /// /// Not [`Number`](Self::Number) with [`min`](Field::min) and /// [`max`](Field::max), which is the reading to resist and is the same /// resistance [`Radio`](Self::Radio) needed against `Select`. A bounded /// number and a validated number are different *questions*. A validated /// number is typed and can be wrong: the bounds are a rule the answer is /// checked against, and being told "must be at least 1" afterwards is the /// normal course of it. A range cannot be out of range at all, because the /// bounds are the control's extent rather than a rule, and the two ends are /// what the question means — audiofiles asks for a classifier threshold /// between 0 and 1, where 0 is never and 1 is only-on-certainty, and a typed /// 0.72 says nothing without both ends on screen beside it. /// /// A renderer cannot infer which one is meant from `min`/`max` alone, which /// is why this is a kind and not an inference: goingson's `min="1"` duration /// is a validated number and would become a slider. /// /// The membership test passes without stretching: a webview emits /// ``, egui has `Slider`, a terminal draws a bar and /// takes arrow keys, a CLI takes a bounded argument. /// /// # It owes its bounds /// /// [`min`](Field::min) and [`max`](Field::max) are `Option` for every other /// kind and are **required** here, in the sense the description can require /// anything: [`Field::bounded`] is the check, and a range missing one has no /// extent for a renderer to draw. What a renderer does with an unbounded /// range is its own call and both answers are honest — fall back to a typed /// number, or pick a host default — so this is stated rather than enforced, /// the way every other constraint here is. /// /// [`Field::step`] is the third fact and is genuinely optional: absent, the /// host's own granularity stands. Range, /// One question with two ends: a lower value and an upper one, submitted /// under two names. /// /// "Show me samples between 90 and 130 BPM" has a single answer with two /// ends, and the ends constrain each other: a minimum above the maximum is /// not a wrong value, it is an empty result nobody asked for. Described as /// two [`Number`](Self::Number) fields that is unsayable — nothing says they /// are one question, so a renderer draws two controls with two labels and no /// relationship, and [`Field::error`] can only be attached to one side of a /// fault that belongs to both. /// /// Not [`Range`](Self::Range), which was the reading to resist and the /// resistance is the same one `Range` itself needed against `Number`. A /// range describes *one* value inside an extent; this describes two, and the /// extent is a bound on each rather than the question's meaning. The two /// come apart in the answer: a range has a value, an interval has a pair, /// and either end may be absent while the other stands. /// /// # It states both names /// /// [`Field::name`] is the lower end and [`Field::upper_name`] is the upper /// one, stated rather than derived. One member instead of a naming /// convention this crate would then own forever. /// /// Direction is carried by which member the name sits in, so nothing /// separate says which end is which. /// /// # What it does not enforce /// /// The crossing rule. A lower end above the upper one is describable here /// and always was, exactly as an out-of-[`min`](Field::min) number is: this /// crate carries constraints and never checks them, and deciding a value is /// wrong stays with whoever validated. What the description buys is that the /// fault now has one place to be reported rather than two. /// /// # Both ends take the same facts /// /// [`min`](Field::min), [`max`](Field::max), [`step`](Field::step) and /// [`unit`](Field::unit) describe the axis rather than one end of it, so /// they are read once and applied to both. Six of audiofiles' filter axes /// are exactly this: one extent, one unit, one granularity, two ends. /// /// The bounds are optional here, unlike `Range`. They are a rule the answer /// is checked against rather than the control's extent, which is /// [`Number`](Self::Number)'s arrangement and not a slider's. Interval, /// An email address. /// /// Distinct from [`Text`](Self::Text) because the distinction is not /// decoration: a webview renderer emits `type="email"`, which on a touch /// device changes the keyboard that appears and turns on the platform's own /// validation. goingson ships to iOS, so collapsing this into text costs a /// keyboard with no `@` on it. Email, /// A URL. Same reasoning as [`Email`](Self::Email). Url, /// A telephone number. Same reasoning as [`Email`](Self::Email), and the /// clearest case of it: the keyboard is a numeric pad rather than letters. Tel, /// A calendar day, with no time of day in it. /// /// [`Email`](Self::Email)'s argument, and it carries further: a webview /// emits `type="date"`, which is a native picker, the platform's own /// validation, and on a touch device the date keyboard. Described as /// [`Text`](Self::Text) with a hint reading "YYYY-MM-DD", all three are /// lost and the hint is doing the platform's job in prose. /// /// The membership test passes on every host without stretching: a webview /// and a Tauri app emit the input, egui has a date picker, a terminal /// prompts for a day and can validate it, a CLI takes an argument. /// /// # The value is ISO 8601, `YYYY-MM-DD` /// /// Named here rather than left to each host, because a host that picks /// differently sends a server something it parses differently, and the /// failure is silent and per-host. It is ``'s own wire /// format, so the webview renderer owes nothing to honour it and the other /// hosts have one spelling to meet. [`DATE_FORMAT`] is the constant, and a /// test asserts this doc and that constant agree. Date, /// A calendar day and a time of day together. /// /// Apart from [`Date`](Self::Date) because the question is different rather /// than more precise: "which day does this expire" and "at what moment does /// this publish" are asked by different screens and answered by different /// controls. A webview emits `type="datetime-local"` for one and /// `type="date"` for the other, and a host that collapsed them would ask /// half the tree for a precision it does not want. /// /// Both arrived together on measurement rather than on symmetry: 13 sites /// of each across the MNW server and goingson, and **zero** of `time`, /// `month` or `week`, which is why those are not here. A member added for a /// case nobody has is a member designed against nothing, which is /// [`File`](Self::File)'s reasoning about `accept` applied to a whole /// member. /// /// # The value is `YYYY-MM-DDTHH:MM`, local, with no zone /// /// ``'s own format, and the "local" is the /// load-bearing half: the value carries no offset and no `Z`, so the moment /// it names is only fixed once something supplies a zone. That is the app's /// business and not the description's. Seconds are absent, which is the /// browser's own default and is left as the rule rather than restated as a /// constraint. [`DATETIME_FORMAT`] is the constant. /// /// [`Field::min`] and [`Field::max`] already take "the host's own spelling /// of a bound", so a floor of *not in the past* needs nothing new here: it /// is a string in this same format. DateTime, /// Several lines of text. Textarea, /// Several lines of text the user writes markdown in. /// /// The editing counterpart of prose a description carries as markdown /// source, and the reason it can exist at all is the same one that lets the /// source be carried: editing markdown is editing text, so a terminal, an /// immediate-mode host and a webview all have an honest answer, and none of /// them has to refuse. A kind that meant "rich text" in the WYSIWYG sense /// would have been a document model, and two of the three hosts would have /// had to draw something they cannot. /// /// What the mark buys over [`Textarea`](Self::Textarea) is that a renderer /// may offer the affordances markdown has and plain text does not — a /// preview, a syntax pass, a monospaced face for the source — and that a /// host reading the value back knows what it is holding. A renderer with /// none of that draws a textarea, which is why this is additive rather than /// a second control. /// /// It says nothing about **when** the value is saved. Autosave is a clock, /// clocks are not described here, and the four MNW editors this was measured /// against each keep their own. /// /// Sanitising stays where it already is for markdown that is only displayed: /// with the renderer, at the point markup is produced. Being described is /// not a safety property, and a host with its own sanitiser and its own /// content-security posture still owns both. Rich, /// One of a fixed set, offered behind a control that shows one at a time. Select, /// One of a fixed set, with every option on screen at once. /// /// Not a presentation of [`Select`](Self::Select), which is the reading to /// resist: what differs is a property of the *question*. A choice that is /// consequential or irreversible has to be readable without opening /// anything, because a closed control shows one option and hides the rest, /// and the one it shows is whichever was current before the user had read /// the alternatives. audiofiles asks whether a library copies samples into /// its store or references them where they lie — which cannot be changed /// afterwards — and had already promoted that out of a checkbox by hand, /// with a comment giving this reason, before the description could say it. /// /// Everything here is an ``, a `