max / makeover-layout

54.2 KB · 1382 lines History Blame Raw

1	//! The renderer-agnostic half of the make-family design system.
2	//!
3	//! <!-- wiki: makeover-layout -->
4	//!
5	//! `makeover` answers what colour, and varies by theme. `makeover-geometry`
6	//! answers how much space, and varies by density and surface. This crate
7	//! answers what the thing is, and varies by nothing.
8	//!
9	//! # The deferral rule
10	//!
11	//! A description names intents and relationships, never values. Say
12	//! [`Fill::Raised`], never `#D9DDF4`. Say `Gap::Peer`, never `6px`. What is
13	//! left once colour and spacing are deferred is composition: which edges
14	//! are lit, what inverts on press, what nests in what.
15	//!
16	//! The constraint that shapes all of it: a renderer that can only paint
17	//! rectangles has to be able to express the result. egui has no
18	//! `box-shadow: inset` and one stroke per widget with no per-side control; a
19	//! terminal has box-drawing characters and one cell of resolution, and cannot
20	//! draw a two-tone lit edge at all. A description that assumes per-side edges
21	//! is a CSS description wearing a neutral name. So this crate names the
22	//! intent — this region is a well — and each renderer chooses an expression
23	//! it can actually produce, including dropping half of one.
24	//!
25	//! # Scope
26	//!
27	//! Depth came first: the bevel and the surfaces it shapes. That much was
28	//! settled the hard way — the vocabulary here was read off audiofiles'
29	//! `ui::theme` and `ui::widgets`, which are the only implementation written
30	//! by a consumer with no CSS, then checked against both webview apps. All
31	//! three agreed once Balanced Breakfast's fills were corrected.
32	//!
33	//! 0.2.0 adds the rest of the description, each member drawn the same way,
34	//! from what the three apps already hand-write rather than from a taxonomy:
35	//!
36	//! - Components. [`Token`] (badge against chip), [`Notice`] (toast against
37	//! banner), [`RowPart`], [`Heading`], [`Selector`], [`Readiness`], and
38	//! [`Tone`], which is the one intent family they share.
39	//! - Schemas. [`Field`] for forms and [`Column`] for lists and tables.
40	//! - Structure. [`Region`] for the parts of a screen, [`Arrangement`] for how
41	//! a screen is put together.
42	//!
43	//! Validation is absent on purpose rather than pending: neither app has a
44	//! shared story, and a schema describing fields but not constraints acquires a
45	//! constraint layer per app, which is how the divergence this crate exists to
46	//! end got started.
47	//!
48	//! 0.3.0 closes a gap the first real adoption found, which is what adopting
49	//! against goingson first was for. [`Selector`] described only the chosen
50	//! option, so an unchosen one fell through to [`Depth::Flat`] and no renderer
51	//! drew it; goingson's tab strip recesses its unchosen tabs by hand and could
52	//! not delete the line, because being recessed is why the chosen tab reads as
53	//! coming forward. So [`Selector::unchosen`] joins `chosen`, and saying it
54	//! needed [`Fill::Sunken`] and [`Depth::Sunken`]: a surface set back by colour
55	//! with no edge, which is neither a well nor level-with.
56	//!
57	//! 0.7.0 adds [`State`], the interaction axis, closing the gap that adopting
58	//! against three apps rather than one made visible. The description named
59	//! rest and, through [`Depth::pressed`], pressed. It named neither focus nor
60	//! disabled, so `makeover-webview` emitted a hover rule and stopped, and each
61	//! consumer completed the primitive from outside by out-specifying a rule it
62	//! did not own: 19 such rules in goingson, 21 in the MNW server, a further set
63	//! in Balanced Breakfast, and three focus rings that do not match. The axis is
64	//! deliberately two members wide, because hover and pressed belong where they
65	//! already are. [`State`]'s own docs carry that argument.
66	//!
67	//! # Where the description stops
68	//!
69	//! The bespoke widgets, a day-plan timeline and a kanban board and a calendar,
70	//! are not describable here and will not become describable. A description
71	//! expressive enough to produce a timeline is a widget library wearing a
72	//! description's name. Generate the boring 80% so the bespoke 20% gets the
73	//! attention.
74	//!
75	//! [`Region::Bespoke`] is how that limit is stated rather than hidden. The
76	//! description names the place and the app owns the contents, so a screen
77	//! containing a timeline is still a whole screen and still routable. Without
78	//! it, the four goingson screens that make the app worth using would need a
79	//! second, undescribed path beside the router, and two paths is how a
80	//! vocabulary starts drifting from its app again.
81
82	#![forbid(unsafe_code)]
83
84	/// A colour intent this crate refers to but never resolves.
85	///
86	/// The string is the token name `makeover` publishes, so a renderer can look
87	/// it up without this crate knowing what colour came back.
88	pub trait Intent {
89	/// The `makeover` intent token this resolves against.
90	fn token(self) -> &'static str;
91	}
92
93	/// Which way the light falls across a two-tone edge.
94	///
95	/// The whole content of a bevel, once colour and thickness are deferred. The
96	/// light is always assumed to come from the top left: every consumer measured
97	/// agreed on that and none of them ever varied it, so it is an invariant here
98	/// rather than a parameter.
99	///
100	/// # The two corners that belong to both edges
101	///
102	/// Top-right and bottom-left are where the lit run meets the shaded one, and
103	/// the description's claim is that they belong to both. How a renderer says
104	/// that is its own business, because the answer is bounded by resolution and
105	/// not by taste:
106	///
107	/// - A terminal cell is roughly 8x17 device pixels, so giving the whole corner
108	/// to one tone thickens that edge by a cell and reads as one run overrunning
109	/// the other. A half-cell glyph divides the cell already, so `makeover-tui`
110	/// splits it and recovers real information. Its box-drawing fallback cannot:
111	/// a single stroke has no half to give, so there both corners go to dark.
112	/// - A pixel bevel is a one-point stroke by default, which makes the corner a
113	/// one-point square. There is nothing to divide — a diagonal seam across one
114	/// point is sub-pixel, and antialiasing renders it as the blend a mitred join
115	/// already produces. So `makeover-immediate` mitres and is not diverging;
116	/// it is the same rule at a resolution where the split degenerates.
117	///
118	/// Stated here so the difference reads as a decision rather than as drift. A
119	/// renderer with room to divide the corner should; one without should mitre or
120	/// pick the shaded tone, and neither is a bug.
121	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
122	pub enum Bevel {
123	/// Lit from the top left: light on top and left, dark on bottom and right.
124	Raised,
125	/// The same edge inverted, which is also the pressed state of anything
126	/// that draws itself [`Bevel::Raised`].
127	Inset,
128	}
129
130	impl Bevel {
131	/// The edge intents, as `(top_left, bottom_right)`.
132	///
133	/// Split out from any painting because the inversion is the idea, and
134	/// it is the one part every renderer implements identically.
135	#[must_use]
136	pub const fn edges(self) -> (Edge, Edge) {
137	match self {
138	Self::Raised => (Edge::Light, Edge::Dark),
139	Self::Inset => (Edge::Dark, Edge::Light),
140	}
141	}
142
143	/// Pressing inverts. A raised control reads as inset while held.
144	///
145	/// Stated here rather than left to each consumer because a cascade can
146	/// carry a pressed state and an immediate-mode renderer cannot: audiofiles
147	/// resolves this per call site, eighteen times.
148	#[must_use]
149	pub const fn pressed(self) -> Self {
150	match self {
151	Self::Raised => Self::Inset,
152	Self::Inset => Self::Raised,
153	}
154	}
155	}
156
157	/// One side of a bevel, named by the intent it takes.
158	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
159	pub enum Edge {
160	/// The lit side.
161	Light,
162	/// The shadowed side.
163	Dark,
164	}
165
166	impl Intent for Edge {
167	fn token(self) -> &'static str {
168	match self {
169	Self::Light => "bevel-light",
170	Self::Dark => "bevel-dark",
171	}
172	}
173	}
174
175	/// A surface intent a region is filled with.
176	///
177	/// `#[non_exhaustive]`, so a renderer must carry a wildcard arm and a new
178	/// member is additive rather than breaking. Added 0.4.0, after [`Sunken`]
179	/// (an additive member, 0.3.0) hard-broke `makeover-tui` and
180	/// `makeover-immediate` at compile time and left neither able to move until
181	/// both published. The vocabulary exists to grow and the renderers exist to
182	/// disagree about how much of it they answer, so growth must not be a
183	/// lockstep event. The renderer's wildcard is not a hole: [`Fill`] is
184	/// resolved through a fallible lookup, and a missing intent is answered with
185	/// structure rather than with a substituted colour.
186	///
187	/// [`Sunken`]: Fill::Sunken
188	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
189	#[non_exhaustive]
190	pub enum Fill {
191	/// The page behind everything.
192	Page,
193	/// A surface lifted off the page: cards, controls, menus, toasts.
194	Raised,
195	/// A surface floating above the page rather than resting on it.
196	Overlay,
197	/// The inside of a well.
198	Well,
199	/// A surface set back from the one it sits on, by colour and nothing else.
200	///
201	/// Not a well. A well is a hole with an edge, and the two are authored in
202	/// opposite directions: `makeover` derives `surface-well` by inverting
203	/// against the theme's own content colour, while `surface-sunken` is
204	/// authored and free to sit darker than raised (goingson's does). Naming
205	/// only the well left the recessed-with-no-edge surface unsayable, which is
206	/// what an unchosen tab is: it recedes so the chosen one can come forward,
207	/// and it carries no bevel of its own.
208	///
209	/// Added 0.3.0, from goingson's tab strip, which hand-writes exactly this
210	/// and could not delete the line because no member described it.
211	Sunken,
212	}
213
214	// No `fallback` here, deliberately. An earlier cut had `Fill::Well` fall back
215	// to `Fill::Page` so a consumer on makeover 2.2.0, which has no `surface-well`,
216	// had something to paint. makeover-tui found that wrong within a day: page is
217	// the surface a well is usually cut into, so on a terminal that substitution
218	// produces exactly the invisibility it was meant to prevent, and the right
219	// answer there is a drawn edge rather than a different colour.
220	//
221	// Substituting one intent for another is renderer policy. The description says
222	// what the region is and stops.
223
224	impl Intent for Fill {
225	fn token(self) -> &'static str {
226	match self {
227	Self::Page => "surface-page",
228	Self::Raised => "surface-raised",
229	Self::Overlay => "surface-overlay",
230	Self::Well => "surface-well",
231	Self::Sunken => "surface-sunken",
232	}
233	}
234	}
235
236	/// How a region sits relative to the surface behind it.
237	///
238	/// Fill and bevel are named together because naming them apart is what let
239	/// them disagree. Every consumer measured had at least one region carrying a
240	/// raised bevel over a recessed fill: audiofiles fixed it in `raised_frame`
241	/// and recorded the bug in its doc comment, and Balanced Breakfast still had
242	/// twelve of them a year later. A single name for the pair makes that
243	/// unrepresentable.
244	/// `#[non_exhaustive]` for the same reason as [`Fill`], and in the same
245	/// release: a depth this renderer has no drawing for should cost it a
246	/// wildcard arm, not a compile error and a wait on someone else's publish.
247	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
248	#[non_exhaustive]
249	pub enum Depth {
250	/// Level with its surroundings. No edge.
251	Flat,
252	/// A card laid on the panel it sits in.
253	Raised,
254	/// A hole in the panel, with content down inside it. For anything the
255	/// user looks into: a table body, a tag tree, a text field.
256	Well,
257	/// Set back from what it sits on, by colour alone. No edge.
258	///
259	/// The one member carrying a fill without a bevel, so a renderer cannot
260	/// assume the two arrive together. That is deliberate and it is still the
261	/// pairing rule: both halves come off the same `Depth`, so they cannot
262	/// disagree, and here one half is legitimately absent.
263	///
264	/// Distinct from [`Depth::Flat`], which has no fill either and inherits.
265	/// Recessed and level-with are different claims, and only one of them
266	/// needs a colour.
267	Sunken,
268	}
269
270	impl Depth {
271	/// The edge this depth is drawn with, if it has one.
272	#[must_use]
273	pub const fn bevel(self) -> Option<Bevel> {
274	match self {
275	// Sunken joins Flat here, for the opposite reason: Flat has no edge
276	// because nothing separates it from its surroundings, and Sunken has
277	// none because its colour is already doing the separating.
278	Self::Flat \| Self::Sunken => None,
279	Self::Raised => Some(Bevel::Raised),
280	Self::Well => Some(Bevel::Inset),
281	}
282	}
283
284	/// The surface this depth is filled with.
285	///
286	/// [`Depth::Flat`] has no fill of its own: it inherits whatever it sits on,
287	/// which is the difference between level-with and painted-the-same-colour.
288	#[must_use]
289	pub const fn fill(self) -> Option<Fill> {
290	match self {
291	Self::Flat => None,
292	Self::Raised => Some(Fill::Raised),
293	Self::Well => Some(Fill::Well),
294	Self::Sunken => Some(Fill::Sunken),
295	}
296	}
297
298	/// Pressing a raised region reads as a well, and nothing else moves.
299	#[must_use]
300	pub const fn pressed(self) -> Self {
301	match self {
302	Self::Raised => Self::Well,
303	other => other,
304	}
305	}
306	}
307
308	/// An interaction state a region can be in, beside whatever [`Depth`] it is.
309	///
310	/// Orthogonal to depth on purpose. A disabled button is still [`Depth::Raised`]
311	/// and a disabled field is still a [`Depth::Well`], so folding either member
312	/// into `Depth` would make [`Depth::bevel`] and [`Depth::fill`] answer for
313	/// something that is not a depth, and would leave disabled-button and
314	/// disabled-field sharing one variant that cannot tell them apart.
315	///
316	/// # Why hover and pressed are not members
317	///
318	/// The line is whether every renderer has the state to express, not whether CSS
319	/// does. Hover is renderer policy and `makeover-webview` says so in its own
320	/// header: a terminal and an immediate-mode painter have no pointer hovering
321	/// over anything, and pressed already arrives through [`Bevel::pressed`] and
322	/// [`Depth::pressed`], where it belongs, because pressing is a depth inversion
323	/// rather than a separate condition.
324	///
325	/// Focus and disabled are different in kind. A TUI has a focused widget and a
326	/// greyed-out one; so does egui. Both were unsayable here, so all three webview
327	/// consumers supplied them from outside the primitive by out-specifying rules
328	/// they did not own: goingson alone carries 19 of them, and the MNW server
329	/// another 21. That is the divergence this crate exists to end, arriving one
330	/// layer down.
331	///
332	/// # The principle this encodes
333	///
334	/// A primitive owns every state it implies. A renderer that emits a hover rule
335	/// for a thing owes disabled, focus and the capability answer for that same
336	/// thing, because anything less exports the completion work to N consumers who
337	/// will each do it differently.
338	///
339	/// `#[non_exhaustive]` for the reason [`Fill`] and [`Depth`] carry it: growth
340	/// must not be a lockstep event across the three renderers.
341	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
342	#[non_exhaustive]
343	pub enum State {
344	/// Keyboard focus, as distinct from the pointer having landed on something.
345	///
346	/// One ring, not one per primitive. Where the ring sits is [`Depth`]'s
347	/// question and not a per-component choice: a well takes it inside its own
348	/// edge and a raised surface takes it outside. That is one decision with
349	/// two renderings rather than one decision per component, which is how the
350	/// three apps ended up with three rings.
351	Focus,
352	/// Present, visible, and not answering.
353	///
354	/// Not the same as absent, and deliberately not a [`Fill`]: a disabled
355	/// control keeps the surface it always had and stops responding, so what
356	/// changes is its content and its interactivity rather than what it is.
357	Disabled,
358	}
359
360	impl State {
361	/// Whether a region in this state stops answering the pointer.
362	///
363	/// Stated in the description rather than left to each renderer, on the same
364	/// reasoning as [`Bevel::pressed`]: a cascade carries it for free and an
365	/// immediate-mode renderer resolves it per call site, so leaving it unsaid
366	/// means resolving it once per consumer and disagreeing.
367	#[must_use]
368	pub const fn suppresses_interaction(self) -> bool {
369	match self {
370	Self::Disabled => true,
371	Self::Focus => false,
372	}
373	}
374	}
375
376	impl Intent for State {
377	fn token(self) -> &'static str {
378	match self {
379	// Already derived by `makeover` from `action.primary`, and unused
380	// until now for the same reason `hover-surface` was: nothing
381	// emitted the rule that would consume it.
382	Self::Focus => "focus-ring",
383	// Reusing the muted content intent rather than minting a
384	// `disabled` colour. Disabled is a reduction and not a status, and
385	// `makeover-webview`'s progress rules already record the reading
386	// that `content-muted` is what disabled looks like.
387	Self::Disabled => "content-muted",
388	}
389	}
390	}
391
392	/// What a region is saying, when it is saying something.
393	///
394	/// The one intent family shared by badges, notices and nothing else. Kept
395	/// separate from [`Fill`] because a surface is where a thing sits and a tone is
396	/// what it means, and the three apps agree on the four statuses:
397	/// `info_banner` / `warning_banner` in audiofiles, `.toast-info` /
398	/// `.toast-success` / `.toast-error` in goingson, `.toast.success` /
399	/// `.toast.error` in Balanced Breakfast.
400	///
401	/// The per-tag palette (`category-one` through `category-six`) is deliberately
402	/// not here. Which colour a particular tag takes is app domain, and both
403	/// webview apps already carry it as a `data-color` attribute.
404	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
405	pub enum Tone {
406	/// No status. Reads as ordinary de-emphasised content.
407	Neutral,
408	/// Something worth knowing and nothing to do about it.
409	Info,
410	/// Something finished and it worked.
411	Success,
412	/// Something the user should look at before continuing.
413	Warning,
414	/// Something broken, or something about to be destroyed.
415	Danger,
416	}
417
418	impl Intent for Tone {
419	fn token(self) -> &'static str {
420	match self {
421	// Neutral has no status token of its own. It takes the muted
422	// content intent, which is what both webview apps already spell as
423	// `data-color="muted"`.
424	Self::Neutral => "content-muted",
425	Self::Info => "info",
426	Self::Success => "success",
427	Self::Warning => "warning",
428	Self::Danger => "danger",
429	}
430	}
431	}
432
433	/// A small labelled thing that sits inside something else.
434	///
435	/// Two members, because the three apps drew three taxonomies and only one line
436	/// runs through all of them: does it answer a click. audiofiles has
437	/// `classification_badge` (a label) against `tag_chip`, `tag_chip_removable`
438	/// and `selectable_tag` (all of which do). Balanced Breakfast has `.tag` and
439	/// `.badge` against `.tag-chip`. goingson is the one that has to move: its
440	/// `.tag` and `.badge` are a single CSS rule, so every call site has to be read
441	/// to decide which of the two it always was.
442	///
443	/// The evidence that a chip is a real concept rather than a badge with a
444	/// cursor: audiofiles inverts its bevel on press and Balanced Breakfast latches
445	/// `.tag-chip.active` with the inset bevel. Two independent arrivals at "a chip
446	/// holds itself down", which is exactly what [`Depth::pressed`] already says.
447	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
448	pub enum Token {
449	/// Non-interactive status or count. Answers no click.
450	Badge,
451	/// An interactive or removable token. Answers a click, and latches if it
452	/// stands for a filter that is either on or off.
453	Chip {
454	/// Whether it carries its own remove affordance.
455	removable: bool,
456	},
457	}
458
459	impl Token {
460	/// Whether this answers a click.
461	///
462	/// The whole difference between the two members, and the reason a renderer
463	/// with no hover (a touch surface, a terminal) can still tell them apart.
464	#[must_use]
465	pub const fn interactive(self) -> bool {
466	matches!(self, Self::Chip { .. })
467	}
468
469	/// How it sits, given whether it is currently latched down.
470	///
471	/// A badge is flat: it is a label, and giving it an edge would say it can
472	/// be pressed. A chip is raised, and inset while latched.
473	#[must_use]
474	pub const fn depth(self, latched: bool) -> Depth {
475	match self {
476	Self::Badge => Depth::Flat,
477	Self::Chip { .. } if latched => Depth::Well,
478	Self::Chip { .. } => Depth::Raised,
479	}
480	}
481	}
482
483	/// Something the app is telling the user, unprompted.
484	///
485	/// Two concepts, not one with a placement. They differ in more than where they
486	/// sit: a toast is transient, stacked and self-dismissing, and a banner is
487	/// persistent, in flow, one per region, and dismissed by fixing the condition
488	/// it reports. Folding them into one member with a placement parameter would
489	/// make lifetime, stacking and dismissal all placement-dependent, which is the
490	/// description leaking renderer policy.
491	///
492	/// All three apps have banners: `info_banner` and `warning_banner` in
493	/// audiofiles, five of them in goingson (sync, sync-result, vacation-day,
494	/// timer-active, past-review), `.update-banner` in Balanced Breakfast. The two
495	/// webview apps also have toasts. So neither member is speculative, and no app
496	/// gains a concept it lacks except audiofiles, whose renderer may legitimately
497	/// decline to draw a toast at all.
498	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
499	pub enum Notice {
500	/// Transient, stacked, dismisses itself.
501	Toast,
502	/// Persistent, in flow, one per region, dismissed by fixing the cause.
503	Banner,
504	}
505
506	impl Notice {
507	/// Whether it goes away on its own.
508	#[must_use]
509	pub const fn transient(self) -> bool {
510	matches!(self, Self::Toast)
511	}
512
513	/// How it sits.
514	///
515	/// A toast floats above the page rather than resting on it, which is
516	/// [`Fill::Overlay`]'s whole reason to exist. A banner is a card in the
517	/// flow. Both are raised, and they are raised off different things.
518	#[must_use]
519	pub const fn fill(self) -> Fill {
520	match self {
521	Self::Toast => Fill::Overlay,
522	Self::Banner => Fill::Raised,
523	}
524	}
525	}
526
527	/// The parts of a list row.
528	///
529	/// Four, taken from Balanced Breakfast, which is the only consumer that had all
530	/// of them (`row-primary`, `row-secondary`, `row-meta`, `row-actions`).
531	/// audiofiles has two and no slot structure at all, so it gains meta and
532	/// actions as real work rather than a rename; goingson moves off
533	/// `task-row` / `task-cell`.
534	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
535	pub enum RowPart {
536	/// The thing itself. What the row is called.
537	Primary,
538	/// Supporting text under the primary.
539	Secondary,
540	/// A short trailing fact: a count, a size, a date.
541	Meta,
542	/// Controls that act on this row.
543	Actions,
544	}
545
546	impl RowPart {
547	/// Whether the part stays hidden until the row is hovered or focused.
548	///
549	/// Behaviour of the part, not app policy: Balanced Breakfast and goingson
550	/// grew the same hover-reveal on their actions independently and neither
551	/// applies it to anything else.
552	///
553	/// A renderer with no hover shows it always. That is a renderer decision
554	/// and this returning `true` does not forbid it.
555	#[must_use]
556	pub const fn revealed_on_hover(self) -> bool {
557	matches!(self, Self::Actions)
558	}
559
560	/// The content intent the part takes.
561	#[must_use]
562	pub const fn intent(self) -> &'static str {
563	match self {
564	Self::Primary => "content",
565	Self::Secondary => "content-secondary",
566	Self::Meta => "content-muted",
567	// Actions carry controls rather than text, so they inherit.
568	Self::Actions => "content",
569	}
570	}
571	}
572
573	/// How far down the heading tree a title sits.
574	///
575	/// Three, and only the three that are actually headings. The bands those used
576	/// to be filed with (goingson's `.page-header`, Balanced Breakfast's `.header`
577	/// and `.detail-header`) are arrangement, not type, and live at
578	/// [`Region::Band`]. One of them contains no text at all.
579	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
580	pub enum Heading {
581	/// Names the whole screen. One per screen.
582	Page,
583	/// Names a block within the screen.
584	Section,
585	/// Names a sub-block inside an already-named section.
586	Subsection,
587	}
588
589	impl Heading {
590	/// Whether a rule follows the heading.
591	///
592	/// audiofiles' `section_header` draws a separator and its
593	/// `subsection_label` deliberately does not, which is the only thing
594	/// distinguishing the two once weight and colour are deferred.
595	#[must_use]
596	pub const fn separated(self) -> bool {
597	matches!(self, Self::Section)
598	}
599	}
600
601	/// A control that picks between things.
602	///
603	/// Three, because three distinct behaviours are in play and collapsing any two
604	/// loses something. A segmented control picks a value; a tab picks a pane; a
605	/// toggle picks nothing and simply holds itself on or off.
606	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
607	pub enum Selector {
608	/// Exactly one of N, and the options abut.
609	Segmented,
610	/// Independent on or off, on its own.
611	Toggle,
612	/// Navigation between panes. The folder semantic.
613	Tabs,
614	}
615
616	impl Selector {
617	/// How the chosen option sits.
618	///
619	/// Held in for a segmented control and a toggle, which is the same shape
620	/// pressing produces and the whole economy of the idiom: one appearance,
621	/// two reasons to wear it. A tab is the exception, because the selected
622	/// folder tab comes forward to join the pane it opens.
623	#[must_use]
624	pub const fn chosen(self) -> Depth {
625	match self {
626	Self::Segmented \| Self::Toggle => Depth::Well,
627	Self::Tabs => Depth::Raised,
628	}
629	}
630
631	/// How the options that were not picked sit.
632	///
633	/// Added 0.3.0. Describing only [`Selector::chosen`] left the unchosen
634	/// option falling through to [`Depth::Flat`], which says it is level with
635	/// the strip it sits in, and no renderer emitted anything for it. That is
636	/// wrong in both directions and goingson proved it: its unchosen tabs are
637	/// recessed by hand, and being recessed is why the chosen one reads as
638	/// coming forward. Against a flat strip, a raised chosen tab is a bevel
639	/// drawn on the strip's own colour, which is a much weaker folder effect
640	/// than the contrast the idiom is named after.
641	///
642	/// Each member is the inverse of its chosen state, which is the whole
643	/// content of "picked" once colour is deferred:
644	///
645	/// - Tabs recede, so the chosen one comes forward.
646	/// - A segment and a toggle stand up, so the chosen one is held in.
647	#[must_use]
648	pub const fn unchosen(self) -> Depth {
649	match self {
650	Self::Tabs => Depth::Sunken,
651	Self::Segmented \| Self::Toggle => Depth::Raised,
652	}
653	}
654
655	/// Whether the options touch.
656	///
657	/// The gap is the entire difference between a segmented control and a row
658	/// of buttons that happen to sit near each other, which is what audiofiles'
659	/// `segmented_control` says in its own comment and why it zeroes the
660	/// spacing by hand.
661	#[must_use]
662	pub const fn abutting(self) -> bool {
663	matches!(self, Self::Segmented \| Self::Tabs)
664	}
665	}
666
667	/// Whether the content of a region has arrived.
668	///
669	/// The state, not the shimmer. Whether pending paints a skeleton, a spinner or
670	/// nothing at all is renderer policy, the same class of decision that got
671	/// `Fill::fallback` deleted from this crate. goingson and Balanced Breakfast
672	/// each grew a skeleton with differently-named parts; both keep them, as the
673	/// webview renderer's expression of [`Readiness::Pending`]. audiofiles has none
674	/// and needs none, because an immediate-mode renderer simply repaints.
675	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
676	pub enum Readiness {
677	/// The content is here.
678	Ready,
679	/// The content is on its way.
680	Pending,
681	}
682
683	/// A named part of a screen.
684	///
685	/// The thing `makeover-geometry` deliberately does not name: it names the space
686	/// between things by relationship, and nothing named the things. Six named
687	/// members, taken from what the two webview apps actually use, plus
688	/// [`Region::Bespoke`] for the parts no description should reach. Both apps'
689	/// `layout.css` currently names exactly two things, `.raised` and `.well`, so
690	/// this layer is absent rather than divergent, which makes it the cheapest of
691	/// the schemas to add and the easiest to over-build.
692	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
693	pub enum Region<'a> {
694	/// A full-width strip with a title slot and an actions cluster, either of
695	/// which may be empty. goingson's `.page-header`, Balanced Breakfast's
696	/// `.header` and `.detail-header` are all this, differing only in which
697	/// slots they fill.
698	Band,
699	/// A persistent column beside the content, holding navigation.
700	Sidebar,
701	/// A region of content with its own scroll.
702	Pane,
703	/// Two panes side by side, where the left chooses what the right shows.
704	Split,
705	/// A set of panes, one visible at a time, with a [`Selector::Tabs`] above.
706	TabGroup,
707	/// Content over a scrim, taking input until dismissed.
708	Modal,
709	/// A region this crate names the place of and nothing else. The app owns
710	/// what goes in it.
711	///
712	/// The escape hatch, and the thing that keeps the description honest about
713	/// its own limits. A day-plan timeline, a kanban board, a calendar and the
714	/// paint interaction over the timeline are not describable here and are not
715	/// going to become describable: a description expressive enough to produce
716	/// a timeline is a widget library wearing a description's name.
717	///
718	/// But a screen containing one still has to be a screen. Without this
719	/// member the description covers only the boring screens, and the four that
720	/// make goingson worth using would need a second, undescribed path beside
721	/// the router. Two paths is how the vocabulary starts drifting from the app
722	/// again, which is the exact failure this crate exists to end.
723	///
724	/// So the description says "a thing called `day-plan` goes here" and stops.
725	/// The name is opaque: this crate never interprets it, and no renderer is
726	/// expected to know what it means beyond handing the space over.
727	Bespoke {
728	/// What the app calls it. Never interpreted here.
729	name: &'a str,
730	},
731	}
732
733	impl Region<'_> {
734	/// How the region sits on what is behind it.
735	#[must_use]
736	pub const fn depth(self) -> Depth {
737	match self {
738	Self::Band \| Self::Sidebar \| Self::Split \| Self::TabGroup => Depth::Flat,
739	// A pane is looked into, the same as a table body or a tag tree.
740	Self::Pane => Depth::Well,
741	Self::Modal => Depth::Raised,
742	// Flat because it inherits: a bespoke region takes the depth of
743	// whatever frames it. An app that wants its timeline in a well puts
744	// it in a `Pane`, which composes rather than adding a knob here.
745	Self::Bespoke { .. } => Depth::Flat,
746	}
747	}
748
749	/// Whether this crate can say anything about the region's contents.
750	///
751	/// A renderer walks the description and hands every region it understands
752	/// to the right drawing code. This is how it tells the two apart, and the
753	/// reason it is a method rather than a `matches!` at each renderer: there
754	/// is exactly one opaque member and there should stay exactly one.
755	#[must_use]
756	pub const fn described(self) -> bool {
757	!matches!(self, Self::Bespoke { .. })
758	}
759	}
760
761	/// How a screen is laid out.
762	///
763	/// Two, and the second is not a variant of the first. goingson is list-detail,
764	/// Balanced Breakfast is sidebar plus content, and neither app has a third.
765	/// The tab group is a modifier rather than a member, because goingson uses it
766	/// inside the same content region rather than instead of one.
767	///
768	/// This exists at all because the router has to be able to express a screen
769	/// rather than only a control. Discovering the arrangement layer missing after
770	/// the renderers exist is a redesign; naming two now is a morning.
771	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
772	pub enum Arrangement {
773	/// A list that chooses what the detail beside it shows.
774	ListDetail {
775	/// Whether the detail side is a [`Region::TabGroup`].
776	tabbed: bool,
777	},
778	/// Navigation down the side, content filling the rest.
779	SidebarContent,
780	}
781
782	/// What kind of value a form field takes.
783	///
784	/// The union of the two vocabularies that diverged, which is what triggered
785	/// this crate. They have since converged on their own: both apps now have a
786	/// `renderFormField` emitting the same anatomy, and what is left differing is
787	/// the kind set, the error shape, and whether the return is a string or a node.
788	///
789	/// Validation is deliberately absent. Neither app has a shared story (goingson
790	/// validates after collecting the form data, with per-field transform hooks;
791	/// Balanced Breakfast has `required` and nothing else), and a schema that
792	/// describes fields but not constraints acquires a constraint layer per app,
793	/// which is exactly how the current divergence started. Naming it absent is a
794	/// decision; leaving it unmentioned would not be.
795	/// `#[non_exhaustive]` for the reason [`Fill`] is: renderers match on this and
796	/// the set keeps growing, so growth must not be a lockstep event. Email, Url
797	/// and Tel arriving in 0.5.0 is the second growth in two releases.
798	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
799	#[non_exhaustive]
800	pub enum FieldKind {
801	/// A single line of text.
802	Text,
803	/// A single line of text that must never be echoed, logged or round-tripped
804	/// through anything that might persist it.
805	Secret,
806	/// A number.
807	Number,
808	/// An email address.
809	///
810	/// Distinct from [`Text`](Self::Text) because the distinction is not
811	/// decoration: a webview renderer emits `type="email"`, which on a touch
812	/// device changes the keyboard that appears and turns on the platform's own
813	/// validation. goingson ships to iOS, so collapsing this into text costs a
814	/// keyboard with no `@` on it.
815	///
816	/// Added 0.5.0, from goingson's contact form.
817	Email,
818	/// A URL. Same reasoning as [`Email`](Self::Email).
819	///
820	/// Added 0.5.0, from goingson's contact-social and contact-feed forms.
821	Url,
822	/// A telephone number. Same reasoning as [`Email`](Self::Email), and the
823	/// clearest case of it: the keyboard is a numeric pad rather than letters.
824	///
825	/// Added 0.5.0, from goingson's contact-phone form.
826	Tel,
827	/// Several lines of text.
828	Textarea,
829	/// One of a fixed set.
830	Select,
831	/// On or off.
832	Checkbox,
833	/// Carried through the form and never shown.
834	Hidden,
835	}
836
837	impl FieldKind {
838	/// Whether the field is drawn at all.
839	#[must_use]
840	pub const fn visible(self) -> bool {
841	!matches!(self, Self::Hidden)
842	}
843
844	/// Whether the value must be kept out of logs and diagnostics.
845	#[must_use]
846	pub const fn confidential(self) -> bool {
847	matches!(self, Self::Secret)
848	}
849
850	/// Where the field's own label sits.
851	///
852	/// A checkbox labels itself on the right of the box; everything else takes
853	/// a label above. Both webview apps already do this and both special-case
854	/// it inline, which is the tell that it belongs in the description.
855	#[must_use]
856	pub const fn labels_itself(self) -> bool {
857	matches!(self, Self::Checkbox)
858	}
859	}
860
861	/// One field of a form.
862	///
863	/// Borrowed rather than owned: a description is built, read once by a renderer,
864	/// and dropped. Nothing here outlives the screen it describes.
865	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
866	pub struct Field<'a> {
867	/// What kind of value it takes.
868	pub kind: FieldKind,
869	/// The name the value is submitted under.
870	pub name: &'a str,
871	/// What the user is asked for.
872	pub label: &'a str,
873	/// Standing help, shown whether or not anything is wrong.
874	pub hint: Option<&'a str>,
875	/// What is currently wrong with the value.
876	pub error: Option<&'a str>,
877	/// Whether the form refuses to submit without it.
878	pub required: bool,
879	/// Whether the field lives behind a "more options" disclosure.
880	pub extended: bool,
881	}
882
883	impl<'a> Field<'a> {
884	/// A plain required-nothing field of the given kind.
885	#[must_use]
886	pub const fn new(kind: FieldKind, name: &'a str, label: &'a str) -> Self {
887	Self {
888	kind,
889	name,
890	label,
891	hint: None,
892	error: None,
893	required: false,
894	extended: false,
895	}
896	}
897
898	/// Whether the field is currently reporting a problem.
899	///
900	/// Read this rather than testing `error.is_some()` at each renderer: the
901	/// error state has to mark the field's whole group and not only the
902	/// message, because a renderer with no descendant selectors (egui, a
903	/// terminal) cannot find the group from the message. goingson already marks
904	/// the group and Balanced Breakfast does not, so goingson's shape is the
905	/// one taken here.
906	#[must_use]
907	pub const fn invalid(&self) -> bool {
908	self.error.is_some()
909	}
910	}
911
912	/// How much room a column asks for.
913	///
914	/// An intent, so the actual floor stays with `makeover-geometry`. goingson's
915	/// task table spells these as `minmax(200px, 1fr)`, `140px` and content-sized;
916	/// only the first three words of that survive deferral.
917	/// `#[non_exhaustive]`, for the reason [`Fill`] and [`FieldKind`] are: a
918	/// renderer matches on this and a vocabulary that grows must not break every
919	/// renderer when it does.
920	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
921	#[non_exhaustive]
922	pub enum Width {
923	/// Takes what it needs and no more.
924	Content,
925	/// A fixed share, the same at every width.
926	Fixed,
927	/// Absorbs whatever is left over.
928	Fill,
929	}
930
931	/// What a column is worth when there is not room for all of them.
932	///
933	/// Ordered: [`Priority::Optional`] drops first, [`Priority::Essential`] never
934	/// drops. This replaces addressing columns by position, which is what both
935	/// webview apps do today and is a live bug rather than only verbosity. goingson
936	/// hides mobile columns with `nth-child(n+5)` against a seven-column table, so
937	/// inserting a column silently hides the wrong one.
938	/// `#[non_exhaustive]`, same reasoning as [`Width`]. Note the ordering is the
939	/// whole point of the type, so a new tier has to be declared in its place in
940	/// the sequence rather than appended.
941	#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
942	#[non_exhaustive]
943	pub enum Priority {
944	/// Dropped first.
945	Optional,
946	/// Dropped once the optional columns are gone.
947	Secondary,
948	/// Never dropped. Without it the row does not identify itself.
949	Essential,
950	}
951
952	/// One column of a table.
953	///
954	/// Described once. The grid track, the cell order and the drop behaviour are
955	/// all derived from this, rather than being three hand-written encodings that
956	/// must agree and are never checked against each other.
957	#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
958	pub struct Column<'a> {
959	/// The heading, and the name the cell is addressed by.
960	pub name: &'a str,
961	/// How much room it asks for.
962	pub width: Width,
963	/// What it is worth when room runs out.
964	pub priority: Priority,
965	}
966
967	impl<'a> Column<'a> {
968	/// A column that absorbs slack and drops after the optional ones.
969	#[must_use]
970	pub const fn new(name: &'a str) -> Self {
971	Self {
972	name,
973	width: Width::Fill,
974	priority: Priority::Secondary,
975	}
976	}
977
978	/// Whether this column survives at the given cutoff.
979	///
980	/// A renderer narrows by raising the cutoff, and never by counting
981	/// positions.
982	#[must_use]
983	pub const fn kept_at(&self, cutoff: Priority) -> bool {
984	(self.priority as u8) >= (cutoff as u8)
985	}
986	}
987
988	#[cfg(test)]
989	mod tests {
990	use super::*;
991
992	#[test]
993	fn inset_is_raised_with_the_light_moved() {
994	let (rl, rd) = Bevel::Raised.edges();
995	let (il, id) = Bevel::Inset.edges();
996	assert_eq!((rl, rd), (Edge::Light, Edge::Dark));
997	assert_eq!((il, id), (rd, rl));
998	}
999
1000	#[test]
1001	fn pressing_twice_is_a_no_op() {
1002	for b in [Bevel::Raised, Bevel::Inset] {
1003	assert_eq!(b.pressed().pressed(), b);
1004	}
1005	}
1006
1007	#[test]
1008	fn a_raised_region_is_never_filled_with_a_recessed_surface() {
1009	// The bug this vocabulary exists to make unrepresentable.
1010	assert_eq!(Depth::Raised.fill(), Some(Fill::Raised));
1011	assert_eq!(Depth::Raised.bevel(), Some(Bevel::Raised));
1012	assert_eq!(Depth::Well.bevel(), Some(Bevel::Inset));
1013	assert_ne!(Depth::Well.fill(), Depth::Raised.fill());
1014	}
1015
1016	#[test]
1017	fn state_is_orthogonal_to_depth() {
1018	// The reason State is its own axis and not a Depth member: a disabled
1019	// button and a disabled field are both disabled and are not the same
1020	// shape, which one shared variant could not have said.
1021	assert_eq!(Depth::Raised.fill(), Some(Fill::Raised));
1022	assert_eq!(Depth::Well.fill(), Some(Fill::Well));
1023	assert!(State::Disabled.suppresses_interaction());
1024	}
1025
1026	#[test]
1027	fn only_disabled_stops_answering() {
1028	// Focus is a thing you can still click. Getting this backwards is how
1029	// a focus ring ends up on something inert.
1030	assert!(!State::Focus.suppresses_interaction());
1031	assert!(State::Disabled.suppresses_interaction());
1032	}
1033
1034	#[test]
1035	fn both_states_resolve_against_intents_makeover_already_derives() {
1036	// Neither needs a new token, so this costs no `makeover` release.
1037	assert_eq!(State::Focus.token(), "focus-ring");
1038	assert_eq!(State::Disabled.token(), "content-muted");
1039	}
1040
1041	#[test]
1042	fn flat_has_neither_edge_nor_fill() {
1043	assert_eq!(Depth::Flat.bevel(), None);
1044	assert_eq!(Depth::Flat.fill(), None);
1045	}
1046
1047	#[test]
1048	fn sunken_is_recessed_by_colour_with_no_edge() {
1049	// The one member carrying a fill without a bevel. A renderer that
1050	// assumes the two arrive together drops the fill silently, which is
1051	// exactly what makeover-webview did before 0.3.0.
1052	assert_eq!(Depth::Sunken.fill(), Some(Fill::Sunken));
1053	assert_eq!(Depth::Sunken.bevel(), None);
1054	}
1055
1056	#[test]
1057	fn sunken_and_flat_are_different_claims() {
1058	// Both edgeless, and only one of them needs a colour. Collapsing them
1059	// is what left an unchosen tab unsayable.
1060	assert_eq!(Depth::Flat.bevel(), Depth::Sunken.bevel());
1061	assert_ne!(Depth::Flat.fill(), Depth::Sunken.fill());
1062	}
1063
1064	#[test]
1065	fn a_sunken_surface_is_not_a_well() {
1066	// Authored in opposite directions: makeover derives surface-well by
1067	// inverting against the theme's content colour, while surface-sunken is
1068	// authored and may sit darker than raised.
1069	assert_ne!(Fill::Sunken, Fill::Well);
1070	assert_eq!(Fill::Sunken.token(), "surface-sunken");
1071	assert_eq!(Fill::Well.token(), "surface-well");
1072	}
1073
1074	#[test]
1075	fn every_selector_describes_both_of_its_states() {
1076	// The gap 0.3.0 closed. Before it, only `chosen` existed and the
1077	// unchosen option fell through to Flat at every renderer.
1078	for s in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
1079	assert_ne!(
1080	s.chosen(),
1081	s.unchosen(),
1082	"{s:?} cannot tell picked from unpicked"
1083	);
1084	}
1085	}
1086
1087	#[test]
1088	fn only_a_tab_inverts_the_other_way() {
1089	// Tabs recede so the chosen one comes forward; a segment and a toggle
1090	// stand up so the chosen one is held in. That inversion is the whole
1091	// content of "picked" once colour is deferred, and it is why the three
1092	// are not one member with a flag.
1093	assert_eq!(Selector::Tabs.unchosen(), Depth::Sunken);
1094	assert_eq!(Selector::Tabs.chosen(), Depth::Raised);
1095
1096	for s in [Selector::Segmented, Selector::Toggle] {
1097	assert_eq!(s.unchosen(), Depth::Raised);
1098	assert_eq!(s.chosen(), Depth::Well);
1099	// Held in is what pressing produces: one appearance, two reasons.
1100	assert_eq!(s.unchosen().pressed(), s.chosen());
1101	}
1102	}
1103
1104	#[test]
1105	fn pressing_a_card_makes_a_well() {
1106	assert_eq!(Depth::Raised.pressed(), Depth::Well);
1107	assert_eq!(
1108	Depth::Raised.pressed().bevel(),
1109	Depth::Raised.bevel().map(Bevel::pressed)
1110	);
1111	// Only raised regions respond to being pressed.
1112	assert_eq!(Depth::Flat.pressed(), Depth::Flat);
1113	assert_eq!(Depth::Well.pressed(), Depth::Well);
1114	}
1115
1116	#[test]
1117	fn intents_name_makeover_tokens_and_nothing_else() {
1118	assert_eq!(Edge::Light.token(), "bevel-light");
1119	assert_eq!(Edge::Dark.token(), "bevel-dark");
1120	assert_eq!(Fill::Raised.token(), "surface-raised");
1121	assert_eq!(Fill::Well.token(), "surface-well");
1122	// No value ever leaves this crate.
1123	for t in [
1124	Edge::Light.token(),
1125	Edge::Dark.token(),
1126	Tone::Danger.token(),
1127	Tone::Neutral.token(),
1128	State::Focus.token(),
1129	State::Disabled.token(),
1130	] {
1131	assert!(!t.starts_with('#'), "{t} looks like a value");
1132	assert!(
1133	!t.chars().next().unwrap().is_ascii_digit(),
1134	"{t} is a value"
1135	);
1136	}
1137	}
1138
1139	#[test]
1140	fn a_badge_cannot_be_pressed_and_a_chip_latches() {
1141	// The one line that runs through all three apps' taxonomies.
1142	assert!(!Token::Badge.interactive());
1143	assert!(Token::Chip { removable: false }.interactive());
1144	assert!(Token::Chip { removable: true }.interactive());
1145
1146	// A badge is a label, so giving it an edge would lie about it.
1147	assert_eq!(Token::Badge.depth(false), Depth::Flat);
1148	assert_eq!(Token::Badge.depth(true), Depth::Flat);
1149
1150	// A latched chip wears the same shape a pressed one does.
1151	let chip = Token::Chip { removable: false };
1152	assert_eq!(chip.depth(false), Depth::Raised);
1153	assert_eq!(chip.depth(true), Depth::Raised.pressed());
1154	}
1155
1156	#[test]
1157	fn a_toast_and_a_banner_differ_in_more_than_placement() {
1158	assert!(Notice::Toast.transient());
1159	assert!(!Notice::Banner.transient());
1160	// A toast floats above the page; a banner rests in the flow.
1161	assert_eq!(Notice::Toast.fill(), Fill::Overlay);
1162	assert_eq!(Notice::Banner.fill(), Fill::Raised);
1163	}
1164
1165	#[test]
1166	fn only_the_actions_part_hides_until_hovered() {
1167	for p in [RowPart::Primary, RowPart::Secondary, RowPart::Meta] {
1168	assert!(!p.revealed_on_hover(), "{p:?} should always be visible");
1169	}
1170	assert!(RowPart::Actions.revealed_on_hover());
1171	// Emphasis falls off down the row, and never rises again.
1172	assert_eq!(RowPart::Primary.intent(), "content");
1173	assert_eq!(RowPart::Secondary.intent(), "content-secondary");
1174	assert_eq!(RowPart::Meta.intent(), "content-muted");
1175	}
1176
1177	#[test]
1178	fn a_separator_is_what_tells_a_section_from_a_subsection() {
1179	assert!(Heading::Section.separated());
1180	assert!(!Heading::Subsection.separated());
1181	assert!(!Heading::Page.separated());
1182	}
1183
1184	#[test]
1185	fn a_chosen_segment_is_held_in_and_a_chosen_tab_comes_forward() {
1186	assert_eq!(Selector::Segmented.chosen(), Depth::Well);
1187	assert_eq!(Selector::Toggle.chosen(), Depth::Well);
1188	// The exception, and the whole folder semantic: the open tab joins its
1189	// pane rather than sinking away from it.
1190	assert_eq!(Selector::Tabs.chosen(), Depth::Raised);
1191
1192	// A held-in segment is indistinguishable from a pressed raised one,
1193	// which is the economy the light model buys over a colour swap.
1194	assert_eq!(Selector::Segmented.chosen(), Depth::Raised.pressed());
1195
1196	// A toggle stands alone; the other two are built out of parts that
1197	// touch.
1198	assert!(Selector::Segmented.abutting());
1199	assert!(Selector::Tabs.abutting());
1200	assert!(!Selector::Toggle.abutting());
1201	}
1202
1203	#[test]
1204	fn a_pane_is_looked_into_and_a_band_is_not() {
1205	assert_eq!(Region::Pane.depth(), Depth::Well);
1206	assert_eq!(Region::Modal.depth(), Depth::Raised);
1207	for r in [
1208	Region::Band,
1209	Region::Sidebar,
1210	Region::Split,
1211	Region::TabGroup,
1212	] {
1213	assert_eq!(r.depth(), Depth::Flat, "{r:?} should carry no edge");
1214	}
1215	}
1216
1217	#[test]
1218	fn exactly_one_region_is_opaque() {
1219	// The escape hatch is one member and stays one member. If a second
1220	// undescribed region ever appears, the description has started
1221	// conceding rather than deferring.
1222	for r in [
1223	Region::Band,
1224	Region::Sidebar,
1225	Region::Pane,
1226	Region::Split,
1227	Region::TabGroup,
1228	Region::Modal,
1229	] {
1230	assert!(r.described(), "{r:?} should be describable");
1231	}
1232	assert!(!Region::Bespoke { name: "day-plan" }.described());
1233	}
1234
1235	#[test]
1236	fn a_bespoke_region_inherits_its_depth_rather_than_choosing_one() {
1237	// The app owns the contents, not the placement. An app that wants its
1238	// timeline in a well frames it in a Pane.
1239	assert_eq!(Region::Bespoke { name: "day-plan" }.depth(), Depth::Flat);
1240	assert_eq!(Region::Bespoke { name: "kanban" }.depth(), Depth::Flat);
1241	}
1242
1243	#[test]
1244	fn a_screen_with_a_bespoke_region_is_still_a_whole_screen() {
1245	// The argument the member exists for: goingson's day-plan has to be
1246	// routable, or the description covers only the boring screens and the
1247	// interesting four need a second path beside the router.
1248	let day_plan = [
1249	Region::Band,
1250	Region::Bespoke { name: "day-plan" },
1251	Region::Sidebar,
1252	];
1253	assert_eq!(day_plan.iter().filter(\|r\| r.described()).count(), 2);
1254	assert_eq!(day_plan.iter().filter(\|r\| !r.described()).count(), 1);
1255	}
1256
1257	#[test]
1258	fn a_secret_field_is_marked_as_one_and_a_hidden_field_is_not_drawn() {
1259	let secret = Field::new(FieldKind::Secret, "password", "Password");
1260	assert!(secret.kind.confidential());
1261	assert!(secret.kind.visible());
1262
1263	assert!(!FieldKind::Hidden.visible());
1264	// Nothing else is confidential, or the marker means nothing.
1265	for k in [
1266	FieldKind::Text,
1267	FieldKind::Number,
1268	FieldKind::Textarea,
1269	FieldKind::Select,
1270	FieldKind::Checkbox,
1271	FieldKind::Hidden,
1272	] {
1273	assert!(!k.confidential(), "{k:?} should not be confidential");
1274	}
1275
1276	// Only a checkbox carries its own label.
1277	assert!(FieldKind::Checkbox.labels_itself());
1278	assert!(!FieldKind::Text.labels_itself());
1279	}
1280
1281	#[test]
1282	fn a_field_reports_its_own_error_state() {
1283	let mut f = Field::new(FieldKind::Text, "title", "Title");
1284	assert!(!f.invalid());
1285	f.error = Some("Required");
1286	assert!(f.invalid());
1287	}
1288
1289	#[test]
1290	fn columns_drop_by_priority_and_never_by_position() {
1291	let cols = [
1292	Column {
1293	name: "Title",
1294	width: Width::Fill,
1295	priority: Priority::Essential,
1296	},
1297	Column {
1298	name: "Due",
1299	width: Width::Fixed,
1300	priority: Priority::Secondary,
1301	},
1302	Column {
1303	name: "Estimate",
1304	width: Width::Fixed,
1305	priority: Priority::Optional,
1306	},
1307	];
1308
1309	// Widest: everything survives.
1310	assert_eq!(
1311	cols.iter()
1312	.filter(\|c\| c.kept_at(Priority::Optional))
1313	.count(),
1314	3
1315	);
1316	// Narrower: the optional column goes first.
1317	let kept: Vec<_> = cols
1318	.iter()
1319	.filter(\|c\| c.kept_at(Priority::Secondary))
1320	.map(\|c\| c.name)
1321	.collect();
1322	assert_eq!(kept, ["Title", "Due"]);
1323	// Narrowest: only what identifies the row.
1324	let kept: Vec<_> = cols
1325	.iter()
1326	.filter(\|c\| c.kept_at(Priority::Essential))
1327	.map(\|c\| c.name)
1328	.collect();
1329	assert_eq!(kept, ["Title"]);
1330	}
1331
1332	#[test]
1333	fn inserting_a_column_does_not_move_what_gets_dropped() {
1334	// The bug the ordinal form has and this form cannot: goingson hides
1335	// `nth-child(n+5)` against a seven-column table, so a column inserted
1336	// anywhere to the left silently hides a different one.
1337	let before = [
1338	Column::new("Title"),
1339	Column {
1340	name: "Estimate",
1341	width: Width::Fixed,
1342	priority: Priority::Optional,
1343	},
1344	];
1345	let after = [
1346	Column::new("Title"),
1347	Column::new("Project"), // inserted
1348	Column {
1349	name: "Estimate",
1350	width: Width::Fixed,
1351	priority: Priority::Optional,
1352	},
1353	];
1354
1355	fn dropped<'a>(cols: &[Column<'a>]) -> Vec<&'a str> {
1356	cols.iter()
1357	.filter(\|c\| !c.kept_at(Priority::Secondary))
1358	.map(\|c\| c.name)
1359	.collect()
1360	}
1361	assert_eq!(dropped(&before), ["Estimate"]);
1362	assert_eq!(dropped(&after), ["Estimate"]);
1363	}
1364
1365	#[test]
1366	fn an_arrangement_carries_the_tab_group_as_a_modifier() {
1367	// goingson uses the tab group inside the content region rather than
1368	// instead of one, so it is not a third arrangement.
1369	let go = Arrangement::ListDetail { tabbed: true };
1370	let plain = Arrangement::ListDetail { tabbed: false };
1371	assert_ne!(go, plain);
1372	assert_ne!(go, Arrangement::SidebarContent);
1373	}
1374
1375	#[test]
1376	fn readiness_names_the_state_and_not_the_shimmer() {
1377	// Two members and no third. If a skeleton ever appears in this enum,
1378	// the deferral rule has been broken.
1379	assert_ne!(Readiness::Ready, Readiness::Pending);
1380	}
1381	}
1382