max / makeover-immediate

44.1 KB · 1064 lines History Blame Raw

1	//! The immediate-mode renderer for [`makeover_layout`].
2	//!
3	//! <!-- wiki: makeover-immediate -->
4	//!
5	//! Named for the mode, not the library, the way `makeover-tui` is named for
6	//! the target and not for ratatui. Immediate mode is the constraint that
7	//! actually separates this renderer from the other two, and egui is the
8	//! backend it is written against.
9	//!
10	//! It is the harshest renderer the description has to survive: no
11	//! `box-shadow`, no `inset`, no cascade, no retained tree to mutate, and
12	//! `Visuals.widgets.*.bg_stroke` is a single stroke with no per-side control.
13	//! A two-tone lit edge is not something egui can be configured into producing,
14	//! so it gets painted by hand here, once, instead of in every consuming app.
15	//!
16	//! # What this crate does and does not own
17	//!
18	//! It owns the expression: two mitred polylines for a bevel and a `Frame`
19	//! for a filled region. It owns no colours and no sizes, and no longer owns a
20	//! substitution: it briefly supplied the page for a well, which was a stand-in
21	//! for `surface-well` before makeover derived it, and every consumer reads the
22	//! real token now. [`Palette`] is supplied by the caller,
23	//! already resolved, and every radius, margin and stroke width arrives in
24	//! [`FrameStyle`].
25	//!
26	//! That split is why the crate has no dependency on `makeover` itself: the app
27	//! already resolves a theme, and coupling a renderer to a colour crate's
28	//! version would buy nothing.
29	//!
30	//! # The cascade is the real difference
31	//!
32	//! A stylesheet can say "a pressed button inverts its bevel" once and let the
33	//! cascade carry it. An immediate-mode renderer has nowhere to put that, so
34	//! every call site decides. [`makeover_layout::Depth::pressed`] is what keeps
35	//! the decision from being re-derived per widget.
36	//!
37	//! # 0.11.0: the overlay becomes reachable
38	//!
39	//! 0.10.0 answered what overlaying means in immediate mode with
40	//! [`Palette::cast`], and nothing could ask: the description had no
41	//! `Depth::Overlay` until `makeover-layout` 0.14.0, so the answer sat beside a
42	//! question that could not be posed. [`frame`] now hands the cast shadow to the
43	//! `egui::Frame` for any depth whose fill is [`Fill::Overlay`], keyed off the
44	//! fill rather than the variant.
45	//!
46	//! The same release brings `makeover_layout::CellPart`, which 0.11.0 carried
47	//! and did not draw. [`table`] draws it, below.
48	//!
49	//! # 0.12.0: the table
50	//!
51	//! [`table`] is the vocabulary 0.11.0 took without using. The consumer is
52	//! audiofiles, whose file list is the only table in the tree exercising all four
53	//! of what the description says about one at once: sortable headings with
54	//! carets, fixed and remainder tracks, and buttons inside cells.
55	//!
56	//! Two things it forces, both named where they land:
57	//!
58	//! - `egui_extras`, this crate's first dependency past egui. egui has no
59	//! table, and `Grid` gives no per-column sizing, no sticky header and no
60	//! scroll sync, which is why audiofiles reached for `egui_extras` rather than
61	//! building on `Grid`. A third answer here would reimplement that crate worse.
62	//! - [`Palette::action`], on the footing [`Palette::content`] arrived on: a
63	//! link in a cell is the first thing here needing the action intent.
64	//!
65	//! Narrowing works differently from the terminal's and the module header says
66	//! why: a content column cannot be measured before the app's closure has drawn
67	//! it, so `egui_extras` sizes it and the declared floor budgets it.
68	//!
69	//! # 0.13.0: what the adoption found missing
70	//!
71	//! 0.12.0 shipped [`table`] before audiofiles had taken it, and taking it found
72	//! three things the file list already did that the function could not say. All
73	//! three are host idiom rather than description, which is why they land here and
74	//! not in `makeover-layout`, and all three are answered on a handle the app
75	//! never sees: the `egui_extras` row and builder this crate owns. That is
76	//! [`table::cell`]'s reasoning again: what the app cannot reach, the renderer
77	//! owes it.
78	//!
79	//! - A selected row. [`table::Body::selected`], a predicate asked per row,
80	//! because `set_selected` is a method on the row. Without it a file list has
81	//! no way to show what is selected, which is most of what a file list does.
82	//! - Scrolling a row into view. [`table::Body::scroll_to`], because
83	//! `scroll_to_row` is a method on the builder. A keyboard cursor that moves
84	//! off-screen and stays there is the bug this prevents.
85	//! - Dragging a divider. [`table::TableStyle::resizable`], which passes the
86	//! test `sticky_header` failed in 0.12.0: egui_extras offers two settings here
87	//! and a renderer can honestly make either choice.
88	//!
89	//! A fourth was found and is not a knob. Cells are centred on the row's centre
90	//! line, always, because there is no second honest answer and egui's own default
91	//! (top-aligned) is the one thing it cannot be.
92	//!
93	//! [`table::Body`] is also what splits a table's per-frame facts from its
94	//! description and from its style. A row count, a selection and a scroll request
95	//! are none of them style, and none of them survive the frame.
96	//!
97	//! # 0.18.0: the nodes that were not fields, tables or frames
98	//!
99	//! [`widget`] draws a meter, a token, a control and a figure. `makeover-tui` has
100	//! had all four for releases and this crate had none of them, which stayed
101	//! invisible while the only consumer was an app calling [`field`] and [`table`]
102	//! directly. It stopped being invisible the moment anything tried to draw a
103	//! whole `quasi_router::Screen` in egui: the four are ordinary nodes, so a
104	//! screen walk would have had to draw them itself, one copy per consumer.
105	//!
106	//! [`Palette`] grows the three status intents with it. They arrive together
107	//! rather than one per widget for the reason [`Palette::fill`] is an `Option`:
108	//! `Tone` is five members wide, and a resolver missing one has to invent a
109	//! colour, which is the substitution 0.2.0 spent a release removing.
110	//!
111	//! # Forms
112	//!
113	//! 0.5.0 adds the field vocabulary on top of the depth vocabulary:
114	//! [`makeover_layout::Field`] rendered to egui widgets, in [`field`], and a set
115	//! of them laid down a column in [`group`]. Before it, a description saying
116	//! "text field, labelled, required, with this hint" had no way to become a
117	//! widget here, and audiofiles' forms stayed hand-rolled.
118	//!
119	//! `makeover-webview` got there first and its form emitter is the precedent
120	//! followed rather than re-derived, including the parts that are bug fixes: a
121	//! select handed a value none of its options carries keeps that value visible
122	//! instead of silently reading as the first option, which is a save-the-wrong-
123	//! thing bug goingson hit for real.
124	//!
125	//! What differs is forced by the mode and not chosen:
126	//!
127	//! - The value arrives as a `&mut`. [`Filling`] borrows the app's own field
128	//! and the widget writes through it. There is no DOM to read back out of,
129	//! which is also why the description deliberately does not carry the value.
130	//! - A text control is drawn as a well and a select is not. The description
131	//! holds that a well is for anything the user looks into, and a text field
132	//! is its own example; a select and a checkbox are pressed rather than looked
133	//! into, so they keep egui's own control painting.
134	//! - Focus is not describable, and egui owns all of it here. Reach,
135	//! focus and the focus ring are this renderer's three answers and
136	//! egui already has all three: its own id stack decides what is reachable,
137	//! its own state decides what holds the keyboard, and it paints exactly one
138	//! ring. A description states none of them — `makeover_layout` removed the
139	//! member that used to try in 0.19.0 — and drawing a second ring on top of
140	//! egui's would break the one-ring rule it would have come from. The terms
141	//! are defined once in `makeover_layout`'s crate header, "Reach, focus and
142	//! the focus ring". [`makeover_layout::State::Disabled`] is drawn, because
143	//! egui has no opinion about it until told.
144	//! - **App-level chrome is not drawn here, and it is not this crate's to
145	//! draw.** `quasi-router` names the affordances that outlive one screen: a
146	//! `Chrome` of key bindings, and an `Outcome::Over` for a screen drawn over
147	//! another. Both are answered by `quasi-webview` and `quasi-tui`, and neither
148	//! is answerable here, because this crate depends on `makeover-layout` and
149	//! not on `quasi-router` — it is the peer of `makeover-webview` and
150	//! `makeover-tui`, one layer below the renderers that consume a `Screen`.
151	//! What is missing is the egui crate at that layer, which does not exist:
152	//! nothing renders a quasi `Screen` in egui at all, and chrome is one item on
153	//! the list such a crate would owe. Said here because this is where a reader
154	//! looks for it, and because the silent version reads as "egui does not need
155	//! a palette" rather than "nobody has built the renderer yet".
156
157	#![forbid(unsafe_code)]
158
159	use egui::{
160	Color32, ComboBox, CornerRadius, Margin, Painter, Rect, Response, RichText, Shape, Stroke,
161	TextEdit, Ui,
162	};
163	use makeover_layout::{Bevel, Choice, Depth, Edge, Field, FieldKind, Fill, State, Tone};
164
165	/// Columns, narrowing, cell parts and the sort caret, over `egui_extras`.
166	pub mod table;
167	pub mod widget;
168
169	/// The resolved colours this renderer needs, as flat values.
170	///
171	/// Built by the app from whatever it already uses to resolve a theme, then
172	/// held and reused. Deliberately not a trait and not string-keyed: a bevel is
173	/// painted per widget per frame, and a map lookup per edge is a cost with
174	/// nothing to show for it.
175	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
176	pub struct Palette {
177	/// `surface-page`.
178	pub page: Color32,
179	/// `surface-raised`.
180	pub raised: Color32,
181	/// `surface-overlay`.
182	pub overlay: Color32,
183	/// `surface-well`.
184	///
185	/// Required, not optional. makeover derives it for every theme from 2.3.0,
186	/// so a resolved palette without a well is not a thing that exists here.
187	/// It was an `Option` while that was untrue, and this renderer substituted
188	/// the page; `makeover-tui` keeps its own `Option` for a different reason,
189	/// since a terminal can have the colour and still be unable to show it.
190	pub well: Color32,
191	/// `surface-sunken`.
192	///
193	/// A surface set back from the one it sits on, by colour and nothing else.
194	/// Not a well: a well is a hole with an edge, and this has no edge. An
195	/// immediate-mode renderer paints an arbitrary rect, so unlike
196	/// `makeover-tui` it has no excuse for declining this one.
197	///
198	/// Required rather than optional, on the same footing as `well`: all 31
199	/// themes makeover embeds author it.
200	pub sunken: Color32,
201	/// `bevel-light`.
202	pub bevel_light: Color32,
203	/// `bevel-dark`.
204	pub bevel_dark: Color32,
205	/// `elevation`.
206	///
207	/// What a surface that floats OVER the page is cast onto it with. The one
208	/// intent here that is about a surface's relationship to the page rather
209	/// than about the surface, which is why it is a translucent near-black on
210	/// every theme rather than something read off the palette's own ramp.
211	///
212	/// Only for a surface that overlays. A menu, a tooltip, a modal. A
213	/// surface in the layout takes a bevel, and reaching for this on a panel
214	/// or a card is how a pre-Platinum look survives a conversion under a new
215	/// name.
216	///
217	/// egui has a real answer for this where a terminal does not: see
218	/// [`Palette::cast`], which is the shadow to hand an
219	/// [`egui::Frame`](egui::Frame).
220	pub elevation: Color32,
221	/// `content`.
222	///
223	/// Ordinary text. Added 0.5.0 with the field renderer, which is the first
224	/// thing here that draws any: until then this crate painted surfaces and
225	/// edges and let the caller's own egui visuals answer for text.
226	pub content: Color32,
227	/// `content-muted`.
228	///
229	/// A field's hint, and what
230	/// [`makeover_layout::State::Disabled`](makeover_layout::State::Disabled)
231	/// resolves to. Both readings come from the description rather than from
232	/// here: `State::Disabled` names this intent by token.
233	pub content_muted: Color32,
234	/// `action-primary`.
235	///
236	/// What a control is drawn in. Added 0.12.0 with the table renderer, for the
237	/// reason `content` was added 0.5.0 with the field renderer: a link in a
238	/// cell is the first thing here that needs the action intent, and a palette
239	/// should carry what is used.
240	///
241	/// This is the intent [`CellPart`](makeover_layout::CellPart) exists to
242	/// separate. A cell holding a control took the cell's text colour until the
243	/// description could say otherwise, which is the drift `makeover-layout`
244	/// 0.14.0 named and `makeover-webview` 0.25.0 fixed on its own side.
245	pub action: Color32,
246	/// `danger`.
247	///
248	/// A field's error message, a destructive control, a bar that has run over.
249	pub danger: Color32,
250	/// `success`.
251	///
252	/// Added 0.18.0 with [`widget`], which is the first thing here that draws a
253	/// [`Tone`]. The three status intents arrive together and not one at a
254	/// time: [`Tone`] is five members wide and a resolver missing one has to
255	/// invent a colour for it, which is the substitution this crate spent
256	/// 0.2.0 removing from [`Palette::fill`].
257	pub success: Color32,
258	/// `warning`.
259	pub warning: Color32,
260	/// `info`.
261	pub info: Color32,
262	}
263
264	impl Palette {
265	/// Resolve a surface intent, or `None` for one this renderer does not know.
266	///
267	/// A plain lookup. There is still no substitution: the old one existed only
268	/// while `surface-well` was underived, and every consumer reads the real
269	/// token now.
270	///
271	/// `Option` since 0.3.0, because [`Fill`] became `#[non_exhaustive]` in
272	/// `makeover-layout` 0.4.0 and a total function over an open enum can only
273	/// stay total by inventing a colour for a member it has never heard of.
274	/// That is the substitution this crate spent 0.2.0 removing, so the return
275	/// type moved instead. Every member the description has today is answered
276	/// with `Some`.
277	#[must_use]
278	pub const fn fill(&self, fill: Fill) -> Option<Color32> {
279	match fill {
280	Fill::Page => Some(self.page),
281	Fill::Raised => Some(self.raised),
282	Fill::Overlay => Some(self.overlay),
283	Fill::Well => Some(self.well),
284	Fill::Sunken => Some(self.sunken),
285	_ => None,
286	}
287	}
288
289	/// The colour a [`Tone`] reads as.
290	///
291	/// Total, unlike [`fill`](Self::fill), and the difference is not an
292	/// inconsistency. `Fill` is `#[non_exhaustive]` and `Tone` is not: the
293	/// description layer settled tone at five members and grows surfaces, so a
294	/// total function here cannot be made to invent a colour by an upstream
295	/// release the way a total `fill` could.
296	///
297	/// [`Tone::Neutral`] is [`content`](Self::content) rather than a colour of
298	/// its own, which is what "an ordinary fact" means: a neutral badge is text
299	/// in a box, not a fifth status.
300	#[must_use]
301	pub const fn tone(&self, tone: Tone) -> Color32 {
302	match tone {
303	Tone::Neutral => self.content,
304	Tone::Info => self.info,
305	Tone::Success => self.success,
306	Tone::Warning => self.warning,
307	Tone::Danger => self.danger,
308	}
309	}
310
311	/// The cast shadow for a surface that overlays the page.
312	///
313	/// What "overlaying" means in immediate mode, answered rather than skipped.
314	/// egui already paints shadows for its menus and windows through
315	/// [`egui::Frame::shadow`], so the honest port is to hand that machinery the
316	/// theme's tone instead of egui's own default, not to invent a painter here
317	/// the way [`paint_bevel`] had to.
318	///
319	/// The geometry matches what `makeover-webview` composes, in points rather
320	/// than pixels: a small downward offset and a wide soft blur. A Platinum-era
321	/// menu sits just off the page rather than hovering above it.
322	///
323	/// ```no_run
324	/// # let palette: makeover_immediate::Palette = unimplemented!();
325	/// # let ui: &mut egui::Ui = unimplemented!();
326	/// egui::Frame::popup(ui.style())
327	/// .shadow(palette.cast())
328	/// .show(ui, \|ui\| { ui.label("over the page"); });
329	/// ```
330	#[must_use]
331	pub const fn cast(&self) -> egui::Shadow {
332	egui::Shadow {
333	offset: [0, 2],
334	blur: 24,
335	spread: 0,
336	color: self.elevation,
337	}
338	}
339
340	/// Resolve a bevel edge intent.
341	#[must_use]
342	pub const fn edge(&self, edge: Edge) -> Color32 {
343	match edge {
344	Edge::Light => self.bevel_light,
345	Edge::Dark => self.bevel_dark,
346	}
347	}
348	}
349
350	/// The geometry a framed region is drawn with.
351	///
352	/// Every field is a value, which is why they all arrive from the caller:
353	/// radius and border width belong to `makeover-geometry`, and margins come
354	/// from its relational gaps.
355	#[derive(Debug, Clone, Copy, PartialEq)]
356	pub struct FrameStyle {
357	/// Corner radius. Square under the Platinum default.
358	pub radius: CornerRadius,
359	/// Inner margin between the frame and its contents.
360	pub margin: Margin,
361	/// Bevel stroke width, in points.
362	pub stroke: f32,
363	}
364
365	impl Default for FrameStyle {
366	/// A one-point square frame with no inner margin.
367	fn default() -> Self {
368	Self {
369	radius: CornerRadius::ZERO,
370	margin: Margin::ZERO,
371	stroke: 1.0,
372	}
373	}
374	}
375
376	/// Paint a two-tone edge just inside `rect`.
377	///
378	/// Fill first, bevel after: this adds two polylines and nothing else, so it
379	/// composes over whatever is already there. That is what lets it go over an
380	/// [`egui::TextEdit`] after `ui.add`, where the widget's own fill has landed.
381	///
382	/// Two three-point polylines meeting at opposite corners, rather than four
383	/// segments, so egui mitres the corner joins instead of leaving a notch.
384	///
385	/// The dark polyline is drawn second, so the two corners where the runs meet
386	/// take its tone. That is the right answer here rather than a concession.
387	/// [`makeover_layout::Bevel`] holds those corners to belong to both edges, and
388	/// a renderer with room to divide one should; at the default one-point stroke
389	/// the corner is a one-point square, so the division is sub-pixel and
390	/// antialiasing resolves it to the same blend the mitre already gives. Splitting
391	/// it would add a seam and no information. `makeover-tui` does split, because a
392	/// terminal cell is large enough that not splitting costs a visible cell of edge
393	/// weight — the same rule, at a resolution where it has something to say.
394	pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
395	let (top_left, bottom_right) = bevel.edges();
396
397	// Inset by half a stroke so the line lands inside `rect` rather than
398	// straddling its edge, which on a fractional-scale display is the
399	// difference between one crisp pixel and two dim ones.
400	let r = rect.shrink(stroke / 2.0);
401
402	painter.add(Shape::line(
403	vec![r.left_bottom(), r.left_top(), r.right_top()],
404	Stroke::new(stroke, palette.edge(top_left)),
405	));
406	painter.add(Shape::line(
407	vec![r.right_top(), r.right_bottom(), r.left_bottom()],
408	Stroke::new(stroke, palette.edge(bottom_right)),
409	));
410	}
411
412	/// Draw a region at a given [`Depth`]: its fill and its edge, together.
413	///
414	/// [`Depth::Flat`] gets neither, and inherits whatever it sits on. That is the
415	/// difference between level-with and painted-the-same-colour, and it is the
416	/// reason `Depth::fill` returns an [`Option`] rather than defaulting to the
417	/// page.
418	pub fn frame<R>(
419	ui: &mut Ui,
420	depth: Depth,
421	palette: &Palette,
422	style: FrameStyle,
423	add_contents: impl FnOnce(&mut Ui) -> R,
424	) -> R {
425	let mut f = egui::Frame::new()
426	.corner_radius(style.radius)
427	.inner_margin(style.margin);
428	// Two ways there is no fill to paint, and they collapse to the same
429	// outcome: the depth names none (Depth::Flat), or it names one this
430	// renderer cannot resolve. Either way the frame goes unfilled and the
431	// bevel below carries the depth on its own, which is the rule this
432	// module already documents for Flat.
433	if let Some(fill) = depth.fill().and_then(\|f\| palette.fill(f)) {
434	f = f.fill(fill);
435	}
436	// A surface that overlays the page is cast onto it. [`Palette::cast`] has
437	// answered what that means here since 0.10.0 and nothing could reach it: a
438	// description had no way to say Overlay until makeover-layout 0.14.0, so
439	// the answer sat beside the question. Keyed off the fill rather than the
440	// variant, so it stays right for whatever else the description calls an
441	// overlay later.
442	if depth.fill() == Some(Fill::Overlay) {
443	f = f.shadow(palette.cast());
444	}
445	let framed = f.show(ui, add_contents);
446	if let Some(bevel) = depth.bevel() {
447	paint_bevel(
448	ui.painter(),
449	framed.response.rect,
450	bevel,
451	palette,
452	style.stroke,
453	);
454	}
455	framed.inner
456	}
457
458	/// The geometry a field group is drawn with.
459	///
460	/// Values again, for the reason [`FrameStyle`] is: every number here belongs to
461	/// `makeover-geometry` and arrives already resolved.
462	#[derive(Debug, Clone, Copy, PartialEq)]
463	pub struct FieldStyle {
464	/// The well a text control sits in.
465	pub frame: FrameStyle,
466	/// Between a field's own parts: its label, its control, its hint and its
467	/// error.
468	pub gap: f32,
469	/// Between one field and the next.
470	pub group_gap: f32,
471	/// What marks a required field, appended to its label.
472	///
473	/// A knob rather than a constant, because it is the one piece of copy in
474	/// this crate and copy is not a renderer's call. A webview does not need it
475	/// at all — it emits the `required` attribute and the browser answers — so
476	/// this renderer is the first place where a compulsory field either shows
477	/// that it is or silently does not.
478	pub required_marker: &'static str,
479	}
480
481	impl Default for FieldStyle {
482	/// The default frame, no gaps, and an asterisk.
483	fn default() -> Self {
484	Self {
485	frame: FrameStyle::default(),
486	gap: 0.0,
487	group_gap: 0.0,
488	required_marker: "*",
489	}
490	}
491	}
492
493	/// What the field currently holds, borrowed from wherever the app keeps it.
494	///
495	/// The immediate-mode counterpart of `makeover_webview::form::Value`, and the
496	/// place the two renderers are forced apart: there the value is read back out
497	/// of the DOM after the fact, and here the widget writes through this borrow as
498	/// it is edited. Same reason the description carries neither.
499	///
500	/// An enum rather than a bag of options, on the reasoning
501	/// `makeover_webview::form::Value` records: a checkbox holding a string is
502	/// unsayable here, where a struct would let it be said and then have to cope.
503	#[derive(Debug, Default)]
504	pub enum Filling<'a> {
505	/// Nothing to edit. The control is drawn and does not answer.
506	#[default]
507	Absent,
508	/// The buffer behind anything that takes typed text, a select included:
509	/// what a select holds is the `value` of one of its [`Choice`]s.
510	///
511	/// [`Choice`]: makeover_layout::Choice
512	Text(&'a mut String),
513	/// A checkbox, on or off.
514	On(&'a mut bool),
515	}
516
517	/// The label, marked if the field is compulsory.
518	fn label_text(field: &Field<'_>, style: &FieldStyle) -> String {
519	if field.required {
520	format!("{} {}", field.label, style.required_marker)
521	} else {
522	field.label.to_owned()
523	}
524	}
525
526	/// The four shapes a control comes in here, which is fewer than there are
527	/// kinds.
528	///
529	/// [`FieldKind`] is `#[non_exhaustive]` and grows; this does not, because the
530	/// ways egui has of asking for a value do not. Reducing the open set to this
531	/// closed one in one total function is what keeps a new kind from needing a new
532	/// arm at every match below.
533	#[derive(Debug, Clone, Copy, PartialEq, Eq)]
534	enum Control {
535	/// Typed into, so it is drawn as a well: the user looks into it.
536	Typed,
537	/// Picked from a control that shows one option at a time. Pressed rather
538	/// than looked into, so egui's own control painting stands.
539	Chosen,
540	/// Picked from options that are all on screen at once.
541	///
542	/// Apart from [`Chosen`](Self::Chosen) because the description holds them
543	/// apart, and holding them apart is the whole content of
544	/// [`FieldKind::Radio`]: same question, and an answer the user can read
545	/// without opening anything.
546	Listed,
547	/// Held on or off.
548	Toggled,
549	}
550
551	/// Which shape a kind takes.
552	///
553	/// The wildcard falls to [`Control::Typed`] on purpose: a kind added to the
554	/// description since this renderer was built degrades to a text box, which
555	/// accepts any value the others would, rather than to nothing drawn at all.
556	///
557	/// `FieldKind::File` lands there as of makeover-layout 0.11.0, and it is left
558	/// there rather than grown a shape of its own. egui's honest answer is a button
559	/// that opens a native picker, which is a fifth control and a file-dialog
560	/// dependency; no consumer of this crate asks for a file field yet. Same
561	/// position this crate took on `Meter` at 0.10.0: the membership test is that
562	/// every renderer could answer honestly, not that each one does on the day.
563	/// A path in a text box is not nothing, and it is what an app that needs this
564	/// tomorrow gets today.
565	///
566	/// `FieldKind::Date` and `FieldKind::DateTime` land there too, as of
567	/// makeover-layout 0.15.0, on the same footing and with one thing owed. A
568	/// calendar is a sixth control and bare `egui` has none, so a typed value is
569	/// the honest answer here; what the app gets is the format the description
570	/// names, `makeover_layout::DATE_FORMAT` and `DATETIME_FORMAT`, which is why
571	/// those are constants rather than a sentence. audiofiles is the only consumer
572	/// of this crate and asks for neither today. A calendar popup is the upgrade
573	/// whenever one does.
574	const fn control_shape(kind: FieldKind) -> Control {
575	match kind {
576	FieldKind::Select => Control::Chosen,
577	FieldKind::Radio => Control::Listed,
578	FieldKind::Checkbox => Control::Toggled,
579	_ => Control::Typed,
580	}
581	}
582
583	/// What a select shows for the value it currently holds.
584	///
585	/// A value no option carries stays on screen as itself rather than reading as
586	/// whichever option happens to be first. goingson saved a backup retention of
587	/// 10 against a 1/3/7/14/0 list and the browser silently showed it as 1, so the
588	/// next save wrote a value nobody chose; `makeover-webview` grew the fix as a
589	/// stray `<option>` and this is the same fix in the shape egui allows.
590	fn shown_label<'a>(options: &'a [Choice<'a>], value: &'a str) -> &'a str {
591	options
592	.iter()
593	.find(\|opt\| opt.value == value)
594	.map_or(value, \|opt\| opt.label)
595	}
596
597	/// The control alone, without its label, hint or error.
598	fn control(
599	ui: &mut Ui,
600	field: &Field<'_>,
601	filling: Filling<'_>,
602	palette: &Palette,
603	style: &FieldStyle,
604	) -> Response {
605	// The mismatch path: described as one thing and filled as another. Nothing
606	// here can fix it, so it is drawn as the empty, inert version of what was
607	// described — visible on screen, in the way an empty select is at the
608	// webview renderer, rather than reported in a log nobody reads.
609	let mut discard = String::new();
610	let mut off = false;
611
612	match control_shape(field.kind) {
613	Control::Typed => {
614	let text = match filling {
615	Filling::Text(text) => text,
616	_ => &mut discard,
617	};
618	// An empty frame and no margin: the well is this crate's, and egui's
619	// own control background and padding would sit underneath it saying
620	// something different about both.
621	let mut edit = if matches!(field.kind, FieldKind::Textarea) {
622	TextEdit::multiline(text)
623	} else {
624	TextEdit::singleline(text)
625	}
626	.frame(egui::Frame::NONE)
627	.margin(Margin::ZERO)
628	.text_color(palette.content)
629	.password(field.kind.confidential());
630	if let Some(ghost) = field.placeholder {
631	edit = edit.hint_text(RichText::new(ghost).color(palette.content_muted));
632	}
633	frame(ui, Depth::Well, palette, style.frame, \|ui\| ui.add(edit))
634	}
635	Control::Toggled => {
636	let on = match filling {
637	Filling::On(on) => on,
638	_ => &mut off,
639	};
640	ui.checkbox(on, RichText::new(field.label).color(palette.content))
641	}
642	Control::Listed => {
643	let value = match filling {
644	Filling::Text(text) => text,
645	_ => &mut discard,
646	};
647	// No `shown_label` counterpart, and none is needed: a value no
648	// option carries leaves every button unfilled, which is already
649	// the honest report on screen. The select needs the fix because it
650	// has one slot and must put something in it.
651	let group = ui.vertical(\|ui\| {
652	let mut answered: Option<Response> = None;
653	for opt in field.options {
654	let picked = ui.radio_value(
655	value,
656	opt.value.to_owned(),
657	RichText::new(opt.label).color(palette.content),
658	);
659	answered = Some(match answered {
660	Some(prev) => prev.union(picked),
661	None => picked,
662	});
663	}
664	answered
665	});
666	// A group described with no options answers as its own empty area
667	// rather than as no response at all, which keeps the caller's
668	// `.changed()` chain working on a field whose option list has not
669	// loaded yet.
670	group.inner.unwrap_or(group.response)
671	}
672	Control::Chosen => {
673	let value = match filling {
674	Filling::Text(text) => text,
675	_ => &mut discard,
676	};
677	let shown = shown_label(field.options, value);
678	ComboBox::from_id_salt(field.name)
679	.selected_text(RichText::new(shown).color(palette.content))
680	.show_ui(ui, \|ui\| {
681	for opt in field.options {
682	ui.selectable_value(
683	value,
684	opt.value.to_owned(),
685	RichText::new(opt.label).color(palette.content),
686	);
687	}
688	})
689	.response
690	}
691	}
692	}
693
694	/// One field, as the column the app drops into its form.
695	///
696	/// The anatomy is `makeover-webview`'s, so the two renderers put a form
697	/// together the same way: label, control, hint, error, top to bottom, with a
698	/// checkbox labelling itself instead of taking a label above.
699	///
700	/// Returns [`None`] for a [`FieldKind::Hidden`] field, which is what
701	/// [`FieldKind::visible`] means and is the honest answer here: a webview still
702	/// emits an input for it because the form submits, and an immediate-mode
703	/// renderer has no form and no submission, so a hidden field is a value the app
704	/// already holds and there is nothing to draw or to respond to.
705	///
706	/// `state` is the description's interaction axis.
707	/// [`State::Disabled`] greys the field and stops it answering, through
708	/// [`State::suppresses_interaction`] rather than through a second reading of
709	/// what disabled means. Focus is not on that axis and never reaches here: egui
710	/// owns reach, focus and the ring for this renderer, and one ring means not a
711	/// second one per renderer that happens to have opinions.
712	pub fn field(
713	ui: &mut Ui,
714	field: &Field<'_>,
715	filling: Filling<'_>,
716	state: Option<State>,
717	palette: &Palette,
718	style: &FieldStyle,
719	) -> Option<Response> {
720	if !field.kind.visible() {
721	return None;
722	}
723	let enabled = !state.is_some_and(State::suppresses_interaction);
724	let text = if enabled {
725	palette.content
726	} else {
727	palette.content_muted
728	};
729
730	let response = ui
731	.vertical(\|ui\| {
732	ui.spacing_mut().item_spacing.y = style.gap;
733
734	// A checkbox labels itself, on the right of the box.
735	// `FieldKind::labels_itself` is the description saying so, and both
736	// webview apps special-cased it inline before it did.
737	if !field.kind.labels_itself() {
738	ui.label(RichText::new(label_text(field, style)).color(text));
739	}
740
741	let response = ui
742	.add_enabled_ui(enabled, \|ui\| control(ui, field, filling, palette, style))
743	.inner;
744
745	// Standing help first, then what is wrong now. Both, in that order,
746	// for the reason the webview renderer names both in
747	// `aria-describedby`: an error appearing must not take the hint
748	// away with it.
749	if let Some(hint) = field.hint {
750	ui.label(RichText::new(hint).color(palette.content_muted));
751	}
752	if let Some(error) = field.error {
753	ui.label(RichText::new(error).color(palette.danger));
754	}
755	response
756	})
757	.inner;
758
759	Some(response)
760	}
761
762	/// A set of fields, laid down a column.
763	///
764	/// `show_extended` is the disclosure, and it is a parameter rather than state
765	/// held here because the disclosure belongs to the form and not to any field:
766	/// [`Field::extended`] marks which fields are behind one, and the app owns
767	/// whether it is open. That is the same division `makeover-webview` draws when
768	/// it marks the group `data-extended` and emits no control to toggle it.
769	///
770	/// `draw` is called once per field that should be visible, in order. Taking a
771	/// callback rather than a slice of [`Filling`]s is what keeps the app's own
772	/// values borrowed one at a time: a form's fields usually live in different
773	/// structs, and a parallel array would have to be built each frame and kept in
774	/// step with the description by hand.
775	pub fn group<'a>(
776	ui: &mut Ui,
777	fields: &'a [Field<'a>],
778	show_extended: bool,
779	style: &FieldStyle,
780	mut draw: impl FnMut(&mut Ui, &'a Field<'a>),
781	) {
782	ui.vertical(\|ui\| {
783	ui.spacing_mut().item_spacing.y = style.group_gap;
784	for f in fields {
785	if f.extended && !show_extended {
786	continue;
787	}
788	draw(ui, f);
789	}
790	});
791	}
792
793	#[cfg(test)]
794	mod tests {
795	use super::*;
796
797	fn palette(well: Color32) -> Palette {
798	Palette {
799	page: Color32::from_rgb(1, 1, 1),
800	raised: Color32::from_rgb(2, 2, 2),
801	overlay: Color32::from_rgb(3, 3, 3),
802	well,
803	sunken: Color32::from_rgb(4, 4, 4),
804	bevel_light: Color32::WHITE,
805	bevel_dark: Color32::BLACK,
806	elevation: Color32::from_black_alpha(46),
807	content: Color32::from_rgb(5, 5, 5),
808	content_muted: Color32::from_rgb(6, 6, 6),
809	action: Color32::from_rgb(7, 7, 7),
810	danger: Color32::from_rgb(8, 8, 8),
811	success: Color32::from_rgb(9, 9, 9),
812	warning: Color32::from_rgb(10, 10, 10),
813	info: Color32::from_rgb(11, 11, 11),
814	}
815	}
816
817	/// The cast is egui's own shadow type carrying the theme's tone, which is
818	/// the whole of what this crate had to decide for it: unlike a bevel, egui
819	/// already knows how to paint one.
820	#[test]
821	fn the_cast_hands_egui_the_themes_tone() {
822	let p = palette(Color32::from_rgb(9, 9, 9));
823	let cast = p.cast();
824	assert_eq!(cast.color, p.elevation);
825	assert!(cast.blur > 0, "a cast shadow is soft");
826	assert_eq!(cast.offset, [0, 2], "it falls downward and only a little");
827	}
828
829	#[test]
830	fn a_well_resolves_to_its_own_token() {
831	// No substitution left. The page-filled well was a stand-in for a
832	// token that did not exist yet; it exists now.
833	let w = Color32::from_rgb(9, 9, 9);
834	let p = palette(w);
835	assert_eq!(p.fill(Fill::Well), Some(w));
836	assert_ne!(p.fill(Fill::Well), Some(p.page));
837	}
838
839	#[test]
840	fn every_intent_is_a_plain_lookup() {
841	let p = palette(Color32::from_rgb(9, 9, 9));
842	assert_eq!(p.fill(Fill::Page), Some(p.page));
843	assert_eq!(p.fill(Fill::Raised), Some(p.raised));
844	assert_eq!(p.fill(Fill::Overlay), Some(p.overlay));
845	}
846
847	/// Sunken is its own colour, not the well's and not the page's. The two
848	/// are authored in opposite directions and an earlier cut of the
849	/// description conflated them.
850	#[test]
851	fn sunken_is_neither_the_well_nor_the_page() {
852	let p = palette(Color32::from_rgb(9, 9, 9));
853	assert_eq!(p.fill(Fill::Sunken), Some(p.sunken));
854	assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Well));
855	assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Page));
856	}
857
858	#[test]
859	fn a_raised_region_never_resolves_to_the_well_fill() {
860	// The cross-app bug, asserted at the renderer boundary this time.
861	let p = palette(Color32::from_rgb(9, 9, 9));
862	let raised = Depth::Raised.fill().and_then(\|f\| p.fill(f));
863	let well = Depth::Well.fill().and_then(\|f\| p.fill(f));
864	assert_eq!(raised, Some(p.raised));
865	assert_ne!(raised, well);
866	}
867
868	#[test]
869	fn an_overlay_is_cast_onto_the_page_and_takes_no_edge() {
870	// makeover-layout 0.14.0 is what made this reachable. The answer was
871	// already here at 0.10.0 and the question could not be asked.
872	let p = palette(Color32::from_rgb(9, 9, 9));
873	assert_eq!(
874	Depth::Overlay.fill().and_then(\|f\| p.fill(f)),
875	Some(p.overlay)
876	);
877	assert_eq!(Depth::Overlay.bevel(), None);
878	// The shadow `frame` reaches for is the theme's tone rather than
879	// egui's default, which is the whole reason `cast` exists.
880	assert_eq!(p.cast().color, p.elevation);
881	}
882
883	#[test]
884	fn the_lit_edge_swaps_when_a_card_is_pressed() {
885	let p = palette(Color32::from_rgb(9, 9, 9));
886	let (tl, _) = Depth::Raised.bevel().unwrap().edges();
887	let (ptl, _) = Depth::Raised.pressed().bevel().unwrap().edges();
888	assert_eq!(p.edge(tl), p.bevel_light);
889	assert_eq!(p.edge(ptl), p.bevel_dark);
890	}
891
892	#[test]
893	fn flat_asks_for_neither_fill_nor_edge() {
894	assert!(Depth::Flat.fill().is_none());
895	assert!(Depth::Flat.bevel().is_none());
896	}
897
898	#[test]
899	fn a_select_keeps_a_value_none_of_its_options_carries() {
900	// The save-the-wrong-thing bug, asserted at the second renderer so it
901	// is not re-found there. goingson's own numbers.
902	let options = [
903	Choice::plain("1"),
904	Choice::plain("3"),
905	Choice::plain("7"),
906	Choice::plain("14"),
907	];
908	assert_eq!(shown_label(&options, "10"), "10");
909	// And a value that does match reads as its label, not as itself.
910	let spelled = [Choice {
911	value: "7",
912	label: "One week",
913	}];
914	assert_eq!(shown_label(&spelled, "7"), "One week");
915	}
916
917	#[test]
918	fn only_a_required_field_is_marked() {
919	let style = FieldStyle::default();
920	let plain = Field::new(FieldKind::Text, "title", "Title");
921	assert_eq!(label_text(&plain, &style), "Title");
922
923	let required = Field {
924	required: true,
925	..plain
926	};
927	assert_eq!(label_text(&required, &style), "Title *");
928
929	// The marker is copy and the app owns it, which is why it is a knob.
930	let house = FieldStyle {
931	required_marker: "(required)",
932	..style
933	};
934	assert_eq!(label_text(&required, &house), "Title (required)");
935	}
936
937	#[test]
938	fn a_select_and_a_checkbox_are_pressed_and_everything_else_is_typed_into() {
939	// What decides whether the control gets a well. A well is for what the
940	// user looks into, and only one of these is.
941	assert_eq!(control_shape(FieldKind::Select), Control::Chosen);
942	assert_eq!(control_shape(FieldKind::Radio), Control::Listed);
943	assert_eq!(control_shape(FieldKind::Checkbox), Control::Toggled);
944	for k in [
945	FieldKind::Text,
946	FieldKind::Secret,
947	FieldKind::Number,
948	FieldKind::Email,
949	FieldKind::Url,
950	FieldKind::Tel,
951	FieldKind::Textarea,
952	] {
953	assert_eq!(control_shape(k), Control::Typed, "{k:?} is typed into");
954	}
955	}
956
957	#[test]
958	fn the_two_option_taking_kinds_are_drawn_differently_on_purpose() {
959	// The description holds Select and Radio apart, and a renderer that
960	// collapsed them would silently answer a question the app did not ask:
961	// audiofiles' storage style is irreversible and its alternatives have
962	// to be readable without opening anything. Asserting the two shapes
963	// differ is asserting that distinction survives the trip.
964	assert!(FieldKind::Select.offers_options());
965	assert!(FieldKind::Radio.offers_options());
966	assert_ne!(
967	control_shape(FieldKind::Select),
968	control_shape(FieldKind::Radio)
969	);
970	}
971
972	#[test]
973	fn a_hidden_field_draws_nothing_and_answers_nothing() {
974	// Where the two renderers legitimately part: a webview still emits an
975	// input because the form submits, and there is no form here.
976	let f = Field::new(FieldKind::Hidden, "id", "Id");
977	let p = palette(Color32::from_rgb(9, 9, 9));
978	egui::__run_test_ui(\|ui\| {
979	let drawn = field(ui, &f, Filling::Absent, None, &p, &FieldStyle::default());
980	assert!(drawn.is_none());
981	});
982	}
983
984	#[test]
985	fn a_disabled_field_stops_answering_and_an_unstated_one_does_not() {
986	let f = Field::new(FieldKind::Text, "title", "Title");
987	let p = palette(Color32::from_rgb(9, 9, 9));
988	let style = FieldStyle::default();
989	egui::__run_test_ui(\|ui\| {
990	let mut text = String::from("x");
991	let disabled = field(
992	ui,
993	&f,
994	Filling::Text(&mut text),
995	Some(State::Disabled),
996	&p,
997	&style,
998	)
999	.unwrap();
1000	assert!(!disabled.enabled());
1001
1002	// Stating no state is the ordinary case and answers. Focus used to
1003	// be the counter-example here; it is egui's now and a description
1004	// cannot state it at all.
1005	let mut text = String::from("x");
1006	let plain = field(ui, &f, Filling::Text(&mut text), None, &p, &style).unwrap();
1007	assert!(plain.enabled(), "an unstated field still answers");
1008	});
1009	}
1010
1011	#[test]
1012	fn a_field_described_one_way_and_filled_another_is_drawn_inert() {
1013	// No panic and no write-through. A checkbox handed a string cannot be
1014	// filled, so it is drawn off and left alone.
1015	let f = Field::new(FieldKind::Checkbox, "done", "Done");
1016	let p = palette(Color32::from_rgb(9, 9, 9));
1017	let mut text = String::from("untouched");
1018	egui::__run_test_ui(\|ui\| {
1019	let drawn = field(
1020	ui,
1021	&f,
1022	Filling::Text(&mut text),
1023	None,
1024	&p,
1025	&FieldStyle::default(),
1026	);
1027	assert!(drawn.is_some());
1028	});
1029	assert_eq!(text, "untouched");
1030	}
1031
1032	#[test]
1033	fn the_disclosure_belongs_to_the_form_and_not_to_the_field() {
1034	let fields = [
1035	Field::new(FieldKind::Text, "title", "Title"),
1036	Field {
1037	extended: true,
1038	..Field::new(FieldKind::Text, "notes", "Notes")
1039	},
1040	];
1041	let style = FieldStyle::default();
1042
1043	let mut closed = Vec::new();
1044	egui::__run_test_ui(\|ui\| {
1045	group(ui, &fields, false, &style, \|_, f\| closed.push(f.name));
1046	});
1047	assert_eq!(closed, ["title"]);
1048
1049	let mut open = Vec::new();
1050	egui::__run_test_ui(\|ui\| {
1051	group(ui, &fields, true, &style, \|_, f\| open.push(f.name));
1052	});
1053	assert_eq!(open, ["title", "notes"]);
1054	}
1055
1056	#[test]
1057	fn the_default_frame_is_square_and_one_point() {
1058	let d = FrameStyle::default();
1059	assert_eq!(d.radius, CornerRadius::ZERO);
1060	assert_eq!(d.margin, Margin::ZERO);
1061	assert!((d.stroke - 1.0).abs() < f32::EPSILON);
1062	}
1063	}
1064