Skip to main content

max / makenotwork

14.0 KB · 388 lines History Blame Raw
1 //! The project dashboard's Overview panel, described.
2 //!
3 //! Fourth of the tier-1 batch (wiki `mnw-server-conversion-plan`, "The S4 tab
4 //! inventory"): 93 lines, three `hx-` attributes, no `data-action`, and nothing
5 //! in `static/` or `frontend/src` reaches for any id it writes.
6 //!
7 //! A fill on `project_tabs::build_overview` rather than a mounted screen, for
8 //! the reason the batch before it established: `project_tab_overview` answers a
9 //! conditional GET through `resolve_project_etag`, and `super::mount` has no
10 //! way to say "304 if the project's cache generation has not moved". See
11 //! [`super::user_projects`] for the rule and why it is the ETag that decides.
12 //!
13 //! # The disclosure is sayable now, and this is the first screen to say it
14 //!
15 //! `super::buyer_contacts` gave up its `<details open>` in August and filed the
16 //! gap: 51 sites, and nothing named a disclosure. It is named now, as a
17 //! selective region -- `Slot::widget(id, "disclosure").showing_at_most_one(..)`
18 //! -- where `None` is the closed state and is a legal resting place. So the
19 //! tools panel keeps its collapse instead of becoming a heading and six
20 //! paragraphs, and `buyer_contacts` can take its own back whenever somebody is
21 //! in there.
22 //!
23 //! # The setup checklist is a list of three steps, not three copies of one row
24 //!
25 //! The template writes each step twice, once done and once not, and the two
26 //! branches differ in a tick, a label class, and whether a CTA is there at all.
27 //! Said once, a step is a row that carries a token when it is finished and an
28 //! act when there is something to do about it, and the six branches collapse to
29 //! three [`Step`]s built from three booleans.
30 //!
31 //! The whole block is conditional on at least one step being unfinished, which
32 //! is [`Step::all_done`] here rather than a three-way `||` in the caller.
33 //!
34 //! # Quick Actions loses its third spelling of Export
35 //!
36 //! `hx-post="/api/export/projects"` with `hx-target="body" hx-swap="beforeend"`
37 //! was a sixth hand-written export control. [`super::export_act`] is the one
38 //! that already exists, and it says what the answer *is* -- a file the reader
39 //! keeps -- rather than where to staple the response.
40 //!
41 //! **It renames the button, from "Export Data" to "Export CSV".** That is the
42 //! cost of taking the shared control rather than spelling a sixth one, and it
43 //! is the right way round: five other sites already say "Export CSV" and this
44 //! was the only one that did not. Noted rather than hidden, since a conversion
45 //! changing user-visible copy should say so.
46
47 use makeover_layout as layout;
48 use quasi_router::screen::{Act, Figure, Row, Tag};
49 use quasi_router::{Action, Node, RegionKind, Slot};
50 use quasi_webview::Webview;
51
52 use crate::types::StatCard;
53
54 /// The region the answer replaces, keeping the id the page already used.
55 pub const REGION: &str = "project-overview";
56
57 /// The disclosure holding the tour of the other tabs.
58 const TOOLS: &str = "project-overview-tools";
59
60 /// The one frame inside it, which is what carries the summary line.
61 const TOOLS_BODY: &str = "project-overview-tools-body";
62
63 /// One line of the setup checklist.
64 struct Step {
65 /// What the reader is being asked to do.
66 label: &'static str,
67 /// Whether they have done it.
68 done: bool,
69 /// Where to go and do it, when there is somewhere and it is not done.
70 act: Option<(&'static str, String)>,
71 }
72
73 impl Step {
74 /// The three steps, in the order the template drew them.
75 fn all(slug: &str, stripe_connected: bool, has_items: bool, has_published: bool) -> Vec<Self> {
76 vec![
77 Self {
78 label: "Add your first item: upload files, set a price",
79 done: has_items,
80 act: Some(("New Item", format!("/dashboard/project/{slug}/new-item"))),
81 },
82 Self {
83 label: "Connect Stripe: required to receive payments (3% processing only)",
84 done: stripe_connected,
85 act: Some(("Go to Payments", "/dashboard?tab=payments".to_owned())),
86 },
87 Self {
88 label: "Publish an item: make it visible on your public page",
89 done: has_published,
90 // The template offers this only once there is something to
91 // publish, which is a real condition and not an oversight:
92 // Content is an empty screen before the first item exists.
93 act: has_items.then(|| {
94 (
95 "Go to Content",
96 format!("/dashboard/project/{slug}?tab=content"),
97 )
98 }),
99 },
100 ]
101 }
102
103 /// Whether the checklist has anything left to say.
104 fn all_done(steps: &[Self]) -> bool {
105 steps.iter().all(|step| step.done)
106 }
107
108 /// One step as a row.
109 fn row(&self) -> Row {
110 let mut row = Row::new(self.label);
111
112 if self.done {
113 let mut tick = Tag::badge("Done");
114 tick.tone = layout::Tone::Success;
115 return row.token(tick);
116 }
117
118 if let Some((label, href)) = &self.act {
119 row = row.act(Act::new(*label, Action::external(href.clone())));
120 }
121 row
122 }
123 }
124
125 /// The panel as the route answers it: the region, carrying its own id.
126 #[must_use]
127 pub fn fragment(
128 slug: &str,
129 stats: &[StatCard],
130 stripe_connected: bool,
131 has_items: bool,
132 has_published: bool,
133 ) -> String {
134 use quasi_axum::Serves as _;
135
136 let mut slot = Slot::new(REGION, RegionKind::Pane);
137 for node in body(slug, stats, stripe_connected, has_items, has_published) {
138 slot = slot.with(node);
139 }
140 Webview::new().fragment(&Node::Region(slot))
141 }
142
143 /// The panel's contents as the page embeds them, without a region wrapper.
144 #[must_use]
145 pub fn fill(
146 slug: &str,
147 stats: &[StatCard],
148 stripe_connected: bool,
149 has_items: bool,
150 has_published: bool,
151 ) -> String {
152 use quasi_axum::Serves as _;
153
154 let mut out = String::new();
155 for node in body(slug, stats, stripe_connected, has_items, has_published) {
156 out.push_str(&Webview::new().fragment(&node));
157 }
158 out
159 }
160
161 /// The panel's contents, in order.
162 fn body(
163 slug: &str,
164 stats: &[StatCard],
165 stripe_connected: bool,
166 has_items: bool,
167 has_published: bool,
168 ) -> Vec<Node> {
169 let mut out = Vec::new();
170
171 let steps = Step::all(slug, stripe_connected, has_items, has_published);
172 if !Step::all_done(&steps) {
173 out.push(setup(&steps));
174 }
175
176 out.push(Node::Link {
177 text: "Docs: Projects".into(),
178 action: Action::get("/docs/projects").navigating(),
179 });
180 out.push(figures(stats));
181 out.push(Node::section("Quick Actions"));
182 out.extend(quick_actions(slug));
183 out.push(tools());
184 out
185 }
186
187 /// What is left to do before the project can sell anything.
188 fn setup(steps: &[Step]) -> Node {
189 Node::Region(
190 Slot::new("project-overview-setup", RegionKind::Pane)
191 .with(Node::Heading {
192 level: layout::Heading::Subsection,
193 text: "Project Setup".into(),
194 })
195 .with(Node::list(steps.iter().map(Step::row))),
196 )
197 }
198
199 /// The figures across the top.
200 ///
201 /// The same shape as `super::user_analytics::stats`, and toned the same way:
202 /// the tone rides on the delta, so a card with nothing to report stays neutral
203 /// rather than going green for having no news.
204 fn figures(stats: &[StatCard]) -> Node {
205 Node::Stats {
206 figures: stats
207 .iter()
208 .map(|stat| {
209 let mut figure = Figure::new(stat.value.clone(), stat.label.clone());
210 if let Some(change) = &stat.change {
211 figure = figure.change(change.clone()).tone(if stat.is_positive {
212 layout::Tone::Success
213 } else {
214 layout::Tone::Danger
215 });
216 }
217 (figure, None)
218 })
219 .collect(),
220 }
221 }
222
223 /// The three controls under Quick Actions.
224 fn quick_actions(slug: &str) -> Vec<Node> {
225 vec![
226 // Whole pages rather than fragments, so both leave. An internal
227 // `Action::get` would fetch them into this panel.
228 Node::act(
229 "New Item",
230 Action::external(format!("/dashboard/project/{slug}/new-item")),
231 ),
232 Node::act("View Public Page", Action::external(format!("/p/{slug}"))),
233 // Through `export_act`, which is the described control five other sites
234 // already use. See the module header.
235 super::export_act::act("/api/export/projects", "projects.csv"),
236 ]
237 }
238
239 /// The tour of the other tabs, behind a disclosure.
240 fn tools() -> Node {
241 const TOOLS_LIST: &[(&str, &str)] = &[
242 ("Content", "Upload items, manage versions, set prices."),
243 (
244 "Blog",
245 "Write posts that appear on your project page and RSS feed.",
246 ),
247 (
248 "Promo Codes",
249 "Create discounts, free access codes, or trial periods.",
250 ),
251 (
252 "Membership Tiers",
253 "Recurring subscriptions with gated content access.",
254 ),
255 ("Team", "Add collaborators and split revenue automatically."),
256 ("Analytics", "Track sales, revenue, and views over time."),
257 ];
258
259 // The shape is what makes this a disclosure, and it is exact: a region
260 // showing at most one frame, whose single frame is a LABELLED sub-region.
261 // The label is the summary line. Put it on the outer slot instead and the
262 // renderer finds no labels, falls through to the frame-stepper branch, and
263 // draws Prev/Next buttons and a "0 / 1" counter. Measured 2026-08-26 by
264 // doing exactly that.
265 Node::Region(
266 Slot::new(TOOLS, RegionKind::Group)
267 .with(Node::Region(
268 Slot::new(TOOLS_BODY, RegionKind::Pane)
269 .label("Explore Your Project Tools")
270 .with(Node::list(TOOLS_LIST.iter().map(|(name, description)| {
271 Row::new(*name).secondary(*description)
272 }))),
273 ))
274 // `None` is closed, which is where the template's `<details>` rests:
275 // it carries no `open`.
276 .showing_at_most_one(None),
277 )
278 }
279
280 #[cfg(test)]
281 mod tests {
282 use super::*;
283 use quasi_axum::Serves;
284
285 fn stat(label: &str, change: Option<&str>, positive: bool) -> StatCard {
286 StatCard {
287 label: label.into(),
288 value: "12".into(),
289 change: change.map(Into::into),
290 is_positive: positive,
291 }
292 }
293
294 fn render(slug: &str, stripe: bool, items: bool, published: bool) -> String {
295 let mut out = String::new();
296 for node in &body(slug, &[stat("Items", None, true)], stripe, items, published) {
297 out.push_str(&Webview::new().fragment(node));
298 }
299 out
300 }
301
302 #[test]
303 fn a_finished_project_is_not_shown_the_setup_checklist() {
304 let done = render("an-album", true, true, true);
305 assert!(!done.contains("Project Setup"), "{done}");
306
307 let unfinished = render("an-album", false, true, true);
308 assert!(unfinished.contains("Project Setup"), "{unfinished}");
309 }
310
311 #[test]
312 fn a_finished_step_says_done_and_offers_nothing() {
313 let html = render("an-album", false, true, false);
314
315 // Items is done, so its CTA is gone and the tick is there.
316 assert!(html.contains("Done"), "{html}");
317 assert!(
318 !html.contains("/dashboard/project/an-album/new-item\">New Item"),
319 "a finished step still offers its CTA: {html}"
320 );
321 // Stripe is not, so its CTA is there.
322 assert!(html.contains("/dashboard?tab=payments"), "{html}");
323 }
324
325 #[test]
326 fn publish_offers_content_only_once_there_is_something_to_publish() {
327 let empty = render("an-album", false, false, false);
328 let stocked = render("an-album", false, true, false);
329
330 assert!(!empty.contains("Go to Content"), "{empty}");
331 assert!(stocked.contains("Go to Content"), "{stocked}");
332 }
333
334 #[test]
335 fn the_tools_disclosure_is_closed_and_holds_all_six() {
336 let html = render("an-album", true, true, true);
337
338 assert!(html.contains("Explore Your Project Tools"), "{html}");
339 // It is a disclosure and not a frame-stepper. Both are legal renderings
340 // of a selective region and only one of them is this screen; getting
341 // the shape wrong draws Prev/Next and a counter, which is what happened
342 // on the first attempt.
343 assert!(html.contains("aria-expanded=\"false\""), "{html}");
344 assert!(!html.contains("data-shows=\"next\""), "{html}");
345 assert!(!html.contains("data-shows=\"previous\""), "{html}");
346 for tool in [
347 "Content",
348 "Blog",
349 "Promo Codes",
350 "Membership Tiers",
351 "Team",
352 "Analytics",
353 ] {
354 assert!(html.contains(tool), "missing {tool}: {html}");
355 }
356 }
357
358 #[test]
359 fn the_export_is_the_described_one_and_not_a_sixth_spelling() {
360 let html = render("an-album", true, true, true);
361
362 assert!(html.contains("data-saves=\"projects.csv\""), "{html}");
363 assert!(html.contains("hx-post=\"/api/export/projects\""), "{html}");
364 // What the template did instead: staple the answer onto the document.
365 assert!(!html.contains("hx-swap=\"beforeend\""), "{html}");
366 assert!(!html.contains("data-action"), "{html}");
367 }
368
369 #[test]
370 fn a_figure_without_a_delta_stays_neutral() {
371 let out = Webview::new().fragment(&figures(&[stat("Items", None, true)]));
372 assert!(!out.contains("data-tone=\"success\""), "{out}");
373 }
374
375 #[test]
376 fn the_slug_cannot_smuggle_markup() {
377 let html = render("<script>x()</script>", false, false, false);
378 assert!(!html.contains("<script>x()"), "{html}");
379 }
380
381 #[test]
382 fn the_inline_fill_carries_no_region_because_the_strip_draws_one() {
383 let inline = fill("an-album", &[], true, true, true);
384 assert!(!inline.contains(&format!("id=\"{REGION}\"")), "{inline}");
385 assert!(inline.contains("Quick Actions"), "{inline}");
386 }
387 }
388