Skip to main content

makeover_immediate/
lib.rs

1//! The immediate-mode renderer for [`makeover_layout`], written against egui.
2//!
3//! <!-- wiki: makeover-immediate -->
4//!
5//! egui's `Visuals.widgets.*.bg_stroke` is one stroke with no per-side
6//! control, so the two-tone lit edge is painted here by hand
7//! ([`paint_bevel`]).
8//!
9//! # What this crate draws
10//!
11//! The parts of the description that carry no vocabulary member: depth
12//! ([`frame`], [`paint_bevel`]), the resolved colours ([`Palette`]), a table's
13//! per-frame facts and cell tones ([`table`]), the token and the waiting
14//! marks ([`piece`]), and the egui visuals and metrics a host starts from
15//! ([`host`]).
16//!
17//! The vocabulary members (fields, columns, meters, controls, facts, figures
18//! and charts) are drawn by `quasi-immediate`, which owns those types through
19//! `quasi-router` and calls into this crate for everything above. The style
20//! types it draws them with stay here: [`FieldStyle`], [`Editing`],
21//! [`piece::PieceStyle`] and [`table::TableStyle`].
22//!
23//! # What this crate does and does not own
24//!
25//! It owns the expression: two mitred polylines for a bevel and a `Frame` for
26//! a filled region. It owns no colours and makes no substitutions: the caller
27//! supplies [`Palette`] already resolved.
28//!
29//! Every radius, margin, stroke width and floor arrives in a style type
30//! ([`FrameStyle`], [`FieldStyle`], [`piece::PieceStyle`],
31//! [`table::TableStyle`], [`host::Metrics`]). The focus ring and target floor
32//! in [`host::Metrics`] default to what `makeover-webview` emits.
33//!
34//! `makeover` itself is linked only by the `theme` feature, for
35//! `Palette::from_theme`; it embeds every shipped theme file.
36//!
37//! # Pressed state
38//!
39//! There is no cascade to carry a pressed state, so each call site asks
40//! [`makeover_layout::Depth::pressed`] for the depth a pressed region takes.
41//!
42//! # Overlays
43//!
44//! [`frame`] hands [`Palette::cast`] to the `egui::Frame` for any depth whose
45//! fill is [`Fill::Overlay`], keyed off the fill rather than the variant.
46//!
47//! # Focus and chrome
48//!
49//! egui decides what is reachable and what holds the keyboard, and paints the
50//! one focus ring; this crate draws no ring of its own. The terms are defined
51//! in `makeover_layout`'s crate header, "Reach, focus and the focus ring".
52//!
53//! App-level chrome is not drawn here. `quasi-router` names the affordances
54//! that outlive one screen and `quasi-immediate` answers them; this crate
55//! depends on `makeover-layout` and not on `quasi-router`.
56
57#![forbid(unsafe_code)]
58
59use egui::{Color32, CornerRadius, Margin, Painter, Rect, Shape, Stroke, Ui};
60use makeover_layout::{Bevel, Depth, Edge, Fill, HEAT_BANDS, Heat, Tone};
61
62pub mod host;
63pub mod piece;
64pub mod table;
65
66/// The resolved colours this renderer needs, as flat values.
67///
68/// Built by the app from whatever it already uses to resolve a theme, then
69/// held and reused.
70///
71/// `#[non_exhaustive]`, so a colour added here is not a breaking change: build
72/// one with `Palette::from_theme` (the `theme` feature), or start from
73/// [`Palette::two_tone`] and set every colour the app resolves.
74#[derive(Debug, Clone, Copy, PartialEq, Eq)]
75#[non_exhaustive]
76pub struct Palette {
77    /// `surface-page`.
78    pub page: Color32,
79    /// `surface-raised`.
80    pub raised: Color32,
81    /// `surface-overlay`.
82    pub overlay: Color32,
83    /// `surface-well`. Required: makeover derives it for every theme.
84    pub well: Color32,
85    /// `surface-sunken`.
86    ///
87    /// A surface set back from the one it sits on, by colour and with no edge;
88    /// a well has an edge. Required: every theme makeover embeds authors it.
89    pub sunken: Color32,
90    /// `bevel-light`.
91    pub bevel_light: Color32,
92    /// `bevel-dark`.
93    pub bevel_dark: Color32,
94    /// `elevation`.
95    ///
96    /// The colour a surface that floats over the page (a menu, a tooltip, a
97    /// modal) is cast onto it with: a translucent near-black on every theme.
98    /// A surface in the layout takes a bevel instead. [`Palette::cast`] is the
99    /// shadow to hand an [`egui::Frame`].
100    pub elevation: Color32,
101    /// `content`.
102    ///
103    /// Ordinary text.
104    pub content: Color32,
105    /// `content-secondary`.
106    ///
107    /// Inactive but usable: it still answers a press. The middle tone of the
108    /// three (wiki `three-tone-convention`), and the one an unchosen option in
109    /// a choice field takes. Distinct from
110    /// [`content_disabled`](Self::content_disabled), which
111    /// `State::Disabled` resolves to.
112    ///
113    /// A step of `content` toward the page, derived at load by `makeover` and
114    /// read off the resolved theme like any other token.
115    pub content_secondary: Color32,
116    /// `content-muted`.
117    ///
118    /// A field's hint, a caption, a reading: text that was never a control.
119    /// Held to body text's floor.
120    pub content_muted: Color32,
121    /// `content-disabled`.
122    ///
123    /// What [`makeover_layout::State::Disabled`] resolves to, by token: the
124    /// label of a control that will not answer, fainter than any hint.
125    pub content_disabled: Color32,
126    /// `action-primary`.
127    ///
128    /// What a control is drawn in, and the intent
129    /// [`CellPart`](makeover_layout::CellPart) separates from a cell's text.
130    pub action: Color32,
131    /// `content-on-action`: ink that stays readable on [`action`](Self::action).
132    ///
133    /// Resolved by makeover: the theme's page or content where one reads at
134    /// 4.5:1 on the accent, black or white otherwise. The label of the leading
135    /// control, the one control filled with `action`.
136    pub content_on_action: Color32,
137    /// `danger`.
138    ///
139    /// A field's error message, a destructive control, a bar that has run over.
140    pub danger: Color32,
141    /// `success`.
142    pub success: Color32,
143    /// `warning`.
144    pub warning: Color32,
145    /// `info`.
146    pub info: Color32,
147    /// `border`, the authored line colour.
148    ///
149    /// A neutral badge's edge.
150    pub border: Color32,
151    /// `info-surface`: raised with 12 percent of `info`. A badge's fill.
152    pub info_surface: Color32,
153    /// `success-surface`.
154    pub success_surface: Color32,
155    /// `warning-surface`.
156    pub warning_surface: Color32,
157    /// `danger-surface`.
158    pub danger_surface: Color32,
159    /// `row-hover`: the row under the pointer, at 9 percent.
160    pub row_hover: Color32,
161    /// `row-rule`: the hairline between rows and around a table, at 26
162    /// percent.
163    pub row_rule: Color32,
164    /// `row-selected`: a selected row, raised with 18 percent of the content
165    /// ink (a neutral-ramp step). A fill and never a foreground.
166    pub row_selected: Color32,
167    /// `heat-0` to `heat-4`: the measure ramp, quietest first, from the
168    /// raised ground to the cursor row's mix. Read through
169    /// [`heat`](Self::heat).
170    pub heats: [Color32; HEAT_BANDS as usize],
171}
172
173impl Palette {
174    /// Every surface `page` and every ink `ink`, with no cast shadow.
175    ///
176    /// A starting point for the setters: an app that resolves its own colours
177    /// starts here and sets each one. A colour added to this type later
178    /// starts at one of these two.
179    #[must_use]
180    pub const fn two_tone(page: Color32, ink: Color32) -> Self {
181        Self {
182            page,
183            raised: page,
184            overlay: page,
185            well: page,
186            sunken: page,
187            bevel_light: page,
188            bevel_dark: ink,
189            elevation: Color32::TRANSPARENT,
190            content: ink,
191            content_secondary: ink,
192            content_muted: ink,
193            content_disabled: ink,
194            action: ink,
195            content_on_action: page,
196            danger: ink,
197            success: ink,
198            warning: ink,
199            info: ink,
200            border: ink,
201            info_surface: page,
202            success_surface: page,
203            warning_surface: page,
204            danger_surface: page,
205            row_hover: page,
206            row_rule: ink,
207            row_selected: page,
208            heats: [page; HEAT_BANDS as usize],
209        }
210    }
211
212    /// Set [`page`](Self::page).
213    #[must_use]
214    pub const fn page(mut self, colour: Color32) -> Self {
215        self.page = colour;
216        self
217    }
218
219    /// Set [`raised`](Self::raised).
220    #[must_use]
221    pub const fn raised(mut self, colour: Color32) -> Self {
222        self.raised = colour;
223        self
224    }
225
226    /// Set [`overlay`](Self::overlay).
227    #[must_use]
228    pub const fn overlay(mut self, colour: Color32) -> Self {
229        self.overlay = colour;
230        self
231    }
232
233    /// Set [`well`](Self::well).
234    #[must_use]
235    pub const fn well(mut self, colour: Color32) -> Self {
236        self.well = colour;
237        self
238    }
239
240    /// Set [`sunken`](Self::sunken).
241    #[must_use]
242    pub const fn sunken(mut self, colour: Color32) -> Self {
243        self.sunken = colour;
244        self
245    }
246
247    /// Set [`bevel_light`](Self::bevel_light).
248    #[must_use]
249    pub const fn bevel_light(mut self, colour: Color32) -> Self {
250        self.bevel_light = colour;
251        self
252    }
253
254    /// Set [`bevel_dark`](Self::bevel_dark).
255    #[must_use]
256    pub const fn bevel_dark(mut self, colour: Color32) -> Self {
257        self.bevel_dark = colour;
258        self
259    }
260
261    /// Set [`elevation`](Self::elevation).
262    #[must_use]
263    pub const fn elevation(mut self, colour: Color32) -> Self {
264        self.elevation = colour;
265        self
266    }
267
268    /// Set [`content`](Self::content).
269    #[must_use]
270    pub const fn content(mut self, colour: Color32) -> Self {
271        self.content = colour;
272        self
273    }
274
275    /// Set [`content_secondary`](Self::content_secondary).
276    #[must_use]
277    pub const fn content_secondary(mut self, colour: Color32) -> Self {
278        self.content_secondary = colour;
279        self
280    }
281
282    /// Set [`content_muted`](Self::content_muted).
283    #[must_use]
284    pub const fn content_muted(mut self, colour: Color32) -> Self {
285        self.content_muted = colour;
286        self
287    }
288
289    /// Set [`content_disabled`](Self::content_disabled).
290    #[must_use]
291    pub const fn content_disabled(mut self, colour: Color32) -> Self {
292        self.content_disabled = colour;
293        self
294    }
295
296    /// Set [`action`](Self::action).
297    #[must_use]
298    pub const fn action(mut self, colour: Color32) -> Self {
299        self.action = colour;
300        self
301    }
302
303    /// Set [`content_on_action`](Self::content_on_action).
304    #[must_use]
305    pub const fn content_on_action(mut self, colour: Color32) -> Self {
306        self.content_on_action = colour;
307        self
308    }
309
310    /// Set [`danger`](Self::danger).
311    #[must_use]
312    pub const fn danger(mut self, colour: Color32) -> Self {
313        self.danger = colour;
314        self
315    }
316
317    /// Set [`success`](Self::success).
318    #[must_use]
319    pub const fn success(mut self, colour: Color32) -> Self {
320        self.success = colour;
321        self
322    }
323
324    /// Set [`warning`](Self::warning).
325    #[must_use]
326    pub const fn warning(mut self, colour: Color32) -> Self {
327        self.warning = colour;
328        self
329    }
330
331    /// Set [`info`](Self::info).
332    #[must_use]
333    pub const fn info(mut self, colour: Color32) -> Self {
334        self.info = colour;
335        self
336    }
337
338    /// Set [`border`](Self::border).
339    #[must_use]
340    pub const fn border(mut self, colour: Color32) -> Self {
341        self.border = colour;
342        self
343    }
344
345    /// Set [`info_surface`](Self::info_surface).
346    #[must_use]
347    pub const fn info_surface(mut self, colour: Color32) -> Self {
348        self.info_surface = colour;
349        self
350    }
351
352    /// Set [`success_surface`](Self::success_surface).
353    #[must_use]
354    pub const fn success_surface(mut self, colour: Color32) -> Self {
355        self.success_surface = colour;
356        self
357    }
358
359    /// Set [`warning_surface`](Self::warning_surface).
360    #[must_use]
361    pub const fn warning_surface(mut self, colour: Color32) -> Self {
362        self.warning_surface = colour;
363        self
364    }
365
366    /// Set [`danger_surface`](Self::danger_surface).
367    #[must_use]
368    pub const fn danger_surface(mut self, colour: Color32) -> Self {
369        self.danger_surface = colour;
370        self
371    }
372
373    /// Set [`row_hover`](Self::row_hover).
374    #[must_use]
375    pub const fn row_hover(mut self, colour: Color32) -> Self {
376        self.row_hover = colour;
377        self
378    }
379
380    /// Set [`row_rule`](Self::row_rule).
381    #[must_use]
382    pub const fn row_rule(mut self, colour: Color32) -> Self {
383        self.row_rule = colour;
384        self
385    }
386
387    /// Set [`row_selected`](Self::row_selected).
388    #[must_use]
389    pub const fn row_selected(mut self, colour: Color32) -> Self {
390        self.row_selected = colour;
391        self
392    }
393
394    /// Set [`heats`](Self::heats).
395    #[must_use]
396    pub const fn heats(mut self, ramp: [Color32; HEAT_BANDS as usize]) -> Self {
397        self.heats = ramp;
398        self
399    }
400
401    /// Every colour, read from a resolved makeover theme.
402    ///
403    /// # Errors
404    ///
405    /// [`MissingToken`] naming the first token the theme does not resolve.
406    /// makeover derives every one of these for every shipped theme, so this
407    /// fails only on a theme file missing a base intent.
408    #[cfg(feature = "theme")]
409    pub fn from_theme(tokens: &makeover::SemanticTokens) -> Result<Self, MissingToken> {
410        use makeover::Token;
411        let colour = |token: Token| {
412            tokens
413                .rgba(token)
414                .map(|(r, g, b, a)| Color32::from_rgba_unmultiplied(r, g, b, a))
415                .ok_or(MissingToken(token))
416        };
417        Ok(Self {
418            page: colour(Token::SurfacePage)?,
419            raised: colour(Token::SurfaceRaised)?,
420            overlay: colour(Token::SurfaceOverlay)?,
421            well: colour(Token::SurfaceWell)?,
422            sunken: colour(Token::SurfaceSunken)?,
423            bevel_light: colour(Token::BevelLight)?,
424            bevel_dark: colour(Token::BevelDark)?,
425            elevation: colour(Token::Elevation)?,
426            content: colour(Token::Content)?,
427            content_secondary: colour(Token::ContentSecondary)?,
428            content_muted: colour(Token::ContentMuted)?,
429            content_disabled: colour(Token::ContentDisabled)?,
430            action: colour(Token::Action)?,
431            content_on_action: colour(Token::ContentOnAction)?,
432            danger: colour(Token::Danger)?,
433            success: colour(Token::Success)?,
434            warning: colour(Token::Warning)?,
435            info: colour(Token::Info)?,
436            border: colour(Token::Border)?,
437            info_surface: colour(Token::InfoSurface)?,
438            success_surface: colour(Token::SuccessSurface)?,
439            warning_surface: colour(Token::WarningSurface)?,
440            danger_surface: colour(Token::DangerSurface)?,
441            row_hover: colour(Token::RowHover)?,
442            row_rule: colour(Token::RowRule)?,
443            row_selected: colour(Token::RowSelected)?,
444            heats: [
445                colour(Token::Heat0)?,
446                colour(Token::Heat1)?,
447                colour(Token::Heat2)?,
448                colour(Token::Heat3)?,
449                colour(Token::Heat4)?,
450            ],
451        })
452    }
453}
454
455/// A token `Palette::from_theme` needed and the theme did not resolve.
456#[cfg(feature = "theme")]
457#[derive(Debug, Clone, Copy, PartialEq, Eq)]
458pub struct MissingToken(pub makeover::Token);
459
460#[cfg(feature = "theme")]
461impl std::fmt::Display for MissingToken {
462    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
463        write!(f, "the theme resolves no `{}`", self.0.as_str())
464    }
465}
466
467#[cfg(feature = "theme")]
468impl std::error::Error for MissingToken {}
469
470impl Palette {
471    /// Resolve a surface intent, or `None` for one this renderer does not know.
472    ///
473    /// A plain lookup with no substitution. Every [`Fill`] this renderer
474    /// knows, `Fill::Sunken` included, is answered with `Some`.
475    #[must_use]
476    pub const fn fill(&self, fill: Fill) -> Option<Color32> {
477        match fill {
478            Fill::Page => Some(self.page),
479            Fill::Raised => Some(self.raised),
480            Fill::Overlay => Some(self.overlay),
481            Fill::Well => Some(self.well),
482            Fill::Sunken => Some(self.sunken),
483            _ => None,
484        }
485    }
486
487    /// The colour a [`Tone`] reads as.
488    ///
489    /// [`Tone::Neutral`] and a tone this renderer has not learnt (`Tone` is
490    /// `#[non_exhaustive]`) read as [`content`](Self::content).
491    #[must_use]
492    pub const fn tone(&self, tone: Tone) -> Color32 {
493        match tone {
494            Tone::Neutral => self.content,
495            Tone::Info => self.info,
496            Tone::Success => self.success,
497            Tone::Warning => self.warning,
498            Tone::Danger => self.danger,
499            // A tone this renderer has not learnt yet reads as an ordinary
500            // fact rather than as a status it might misstate.
501            _ => self.content,
502        }
503    }
504
505    /// The fill a measure band sits on, or `None` at band 0, which is the
506    /// ground and draws nothing. A band past the last reads as the last.
507    #[must_use]
508    pub const fn heat(&self, heat: Heat) -> Option<Color32> {
509        let band = heat.0 as usize;
510        if band == 0 {
511            None
512        } else if band < self.heats.len() {
513            Some(self.heats[band])
514        } else {
515            Some(self.heats[self.heats.len() - 1])
516        }
517    }
518
519    /// What a badge of this tone is filled with: its tone surface, or the
520    /// raised surface for [`Tone::Neutral`], as `makeover-webview` fills one.
521    #[must_use]
522    pub const fn tone_surface(&self, tone: Tone) -> Color32 {
523        match tone {
524            Tone::Neutral => self.raised,
525            Tone::Info => self.info_surface,
526            Tone::Success => self.success_surface,
527            Tone::Warning => self.warning_surface,
528            Tone::Danger => self.danger_surface,
529            _ => self.raised,
530        }
531    }
532
533    /// What a badge of this tone is edged with: its tone, or
534    /// [`border`](Self::border) for [`Tone::Neutral`], whose tone is the ink.
535    #[must_use]
536    pub const fn tone_edge(&self, tone: Tone) -> Color32 {
537        match tone {
538            Tone::Neutral => self.border,
539            other => self.tone(other),
540        }
541    }
542
543    /// The cast shadow for a surface that overlays the page.
544    ///
545    /// An [`egui::Shadow`] in [`elevation`](Self::elevation), for
546    /// [`egui::Frame::shadow`]: `makeover-webview`'s overlay cast, a hard
547    /// offset of `[3, 3]` down and right with no blur and no spread.
548    /// [`host::visuals`] gives egui's own windows and popups the same shadow.
549    ///
550    /// ```no_run
551    /// # let palette: makeover_immediate::Palette = unimplemented!();
552    /// # let ui: &mut egui::Ui = unimplemented!();
553    /// egui::Frame::popup(ui.style())
554    ///     .shadow(palette.cast())
555    ///     .show(ui, |ui| { ui.label("over the page"); });
556    /// ```
557    #[must_use]
558    pub const fn cast(&self) -> egui::Shadow {
559        egui::Shadow {
560            offset: [3, 3],
561            blur: 0,
562            spread: 0,
563            color: self.elevation,
564        }
565    }
566
567    /// Resolve a bevel edge intent.
568    #[must_use]
569    pub const fn edge(&self, edge: Edge) -> Color32 {
570        match edge {
571            Edge::Light => self.bevel_light,
572            Edge::Dark => self.bevel_dark,
573            // An edge this renderer has not learnt is drawn as the border, the
574            // one line every surface already has.
575            _ => self.border,
576        }
577    }
578}
579
580/// The geometry a framed region is drawn with.
581///
582/// Every field is a value the caller resolves: radius and border width from
583/// `makeover-geometry`, margins from its relational gaps.
584#[derive(Debug, Clone, Copy, PartialEq)]
585pub struct FrameStyle {
586    /// Corner radius. Square under the Platinum default.
587    pub radius: CornerRadius,
588    /// Inner margin between the frame and its contents.
589    pub margin: Margin,
590    /// Bevel stroke width, in points.
591    pub stroke: f32,
592}
593
594impl Default for FrameStyle {
595    /// A one-point square frame with no inner margin.
596    fn default() -> Self {
597        Self {
598            radius: CornerRadius::ZERO,
599            margin: Margin::ZERO,
600            stroke: f32::from(makeover_geometry::Stroke::Hairline.px()),
601        }
602    }
603}
604
605/// Paint a two-tone edge just inside `rect`.
606///
607/// Adds two polylines and nothing else, so it composes over what is already
608/// painted: over an [`egui::TextEdit`] after `ui.add`, for one.
609///
610/// The polylines are inset by half a stroke. The first, in the tone
611/// [`Bevel::edges`] gives the top and left, runs bottom-left, top-left,
612/// top-right; the second, in the other tone, runs top-right, bottom-right,
613/// bottom-left, and stops at bottom-right for a bevel that does not draw its
614/// bottom. Each is one three-point line, so egui mitres its corner. The second
615/// is drawn over the first, so the two corners where they meet take its tone.
616pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
617    let (top_left, bottom_right) = bevel.edges();
618
619    // Inset by half a stroke so the line lands inside `rect` rather than
620    // straddling its edge, which on a fractional-scale display is the
621    // difference between one crisp pixel and two dim ones.
622    let r = rect.shrink(stroke / 2.0);
623
624    painter.add(Shape::line(
625        vec![r.left_bottom(), r.left_top(), r.right_top()],
626        Stroke::new(stroke, palette.edge(top_left)),
627    ));
628    // Three points close the box, two leave the bottom open: the shaded run
629    // comes down the right side and stops. That is the folder tab, and it is
630    // the same edge the browser draws by dropping the shadow's vertical
631    // offset. The lit polyline is untouched either way, so the join is the
632    // only thing that changes.
633    let shaded = if bevel.draws_bottom() {
634        vec![r.right_top(), r.right_bottom(), r.left_bottom()]
635    } else {
636        vec![r.right_top(), r.right_bottom()]
637    };
638    painter.add(Shape::line(
639        shaded,
640        Stroke::new(stroke, palette.edge(bottom_right)),
641    ));
642}
643
644/// Draw a region at a given [`Depth`]: its fill and its edge, together.
645///
646/// [`Depth::Flat`] gets neither and shows whatever it sits on. A depth whose
647/// fill this palette does not resolve goes unfilled and keeps its bevel. An
648/// overlay fill also takes [`Palette::cast`].
649pub fn frame<R>(
650    ui: &mut Ui,
651    depth: Depth,
652    palette: &Palette,
653    style: FrameStyle,
654    add_contents: impl FnOnce(&mut Ui) -> R,
655) -> R {
656    let mut f = egui::Frame::new()
657        .corner_radius(style.radius)
658        .inner_margin(style.margin);
659    // Two ways there is no fill to paint, and they collapse to the same
660    // outcome: the depth names none (Depth::Flat), or it names one this
661    // renderer cannot resolve. Either way the frame goes unfilled and the
662    // bevel below carries the depth on its own, which is the rule this
663    // module already documents for Flat.
664    if let Some(fill) = depth.fill().and_then(|f| palette.fill(f)) {
665        f = f.fill(fill);
666    }
667    // A surface that overlays the page is cast onto it, with
668    // [`Palette::cast`]. Keyed off the fill rather than the variant, so it stays right for whatever else the description calls an
669    // overlay later.
670    if depth.fill() == Some(Fill::Overlay) {
671        f = f.shadow(palette.cast());
672    }
673    let framed = f.show(ui, add_contents);
674    if let Some(bevel) = depth.bevel() {
675        paint_bevel(
676            ui.painter(),
677            framed.response.rect,
678            bevel,
679            palette,
680            style.stroke,
681        );
682    }
683    framed.inner
684}
685
686/// The geometry a field group is drawn with.
687///
688/// The fields themselves are drawn by `quasi-immediate`. Every number here is
689/// a `makeover-geometry` value the caller resolves, as in [`FrameStyle`],
690/// which it embeds.
691#[derive(Debug, Clone, Copy, PartialEq)]
692pub struct FieldStyle {
693    /// The well a text control sits in.
694    pub frame: FrameStyle,
695    /// Between a field's own parts: its label, its control, its hint and its
696    /// error.
697    pub gap: f32,
698    /// Between one field and the next.
699    pub group_gap: f32,
700    /// What marks a required field, appended to its label. `"*"` by default.
701    pub required_marker: &'static str,
702}
703
704impl Default for FieldStyle {
705    /// The default frame, no gaps, and an asterisk.
706    fn default() -> Self {
707        Self {
708            frame: FrameStyle::default(),
709            gap: 0.0,
710            group_gap: 0.0,
711            required_marker: "*",
712        }
713    }
714}
715
716/// What the field currently holds, borrowed from wherever the app keeps it.
717///
718/// Handed to `quasi-immediate`'s field, which writes through it as the user
719/// edits.
720///
721/// The editable counterpart of [`makeover_layout::Value`], which the other
722/// renderers read back after the fact. The description carries neither.
723///
724/// `#[non_exhaustive]`: a host builds these and does not match on them.
725#[derive(Debug, Default)]
726#[non_exhaustive]
727pub enum Editing<'a> {
728    /// Nothing to edit. The control is drawn and does not answer.
729    #[default]
730    Absent,
731    /// The buffer behind anything that takes typed text, a select included:
732    /// what a select holds is the `value` of one of its options.
733    Text(&'a mut String),
734    /// A checkbox, on or off.
735    On(&'a mut bool),
736    /// The values of a [`FieldKind::Checklist`](makeover_layout::FieldKind::Checklist)'s ticked options.
737    ///
738    /// Ticking pushes the option's value and unticking removes it, so the
739    /// order is the order things were ticked in.
740    Ticked(&'a mut Vec<String>),
741    /// The two buffers behind a [`FieldKind::Interval`](makeover_layout::FieldKind::Interval), lower first.
742    ///
743    /// Either end may be empty while the other stands: an open end
744    /// ("over 120 BPM").
745    Between {
746        /// The lower end's buffer.
747        lower: &'a mut String,
748        /// The upper end's buffer.
749        upper: &'a mut String,
750    },
751}
752
753#[cfg(test)]
754mod tests;