Public: anyone can read this; the crew can change it.

The signed-in home's first paint reserves space for everything that loads later, proven by a test on the rendered HTML #13503

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13489-the-signed-in-home-s-first-paint-reserve → main 4 commits fork 3 threads · 3 unresolved

  • Merged. scout/13489-the-signed-in-home-s-first-paint-reserve was merged into main as dfa578c.

Review

Sign in to review this change.
4 files changed +238 −7
docs/design/areas/home-flow.md +1
@@ -40,6 +40,7 @@ One section under the lanes or the table (`web/pages/home_figures.ts`), an admin
4040
4141 - `.fg`, `.fg-sum`, `.fg-title`, `.fg-hint` — the section, its summary row (a rotating chevron, the title, one line saying what it holds).
4242 - `.fg-grid` — the cards, as many 220px columns as fit.
43 - `.fg-body` — the figures' live region; holds one row of cards (172px, summed from the card's own rules) before they arrive, so nothing below moves.
4344 - `.fg-card`, `.fg-label`, `.fg-value`, `.fg-n`, `.fg-unit`, `.fg-note` — a card: a name, the value with its unit, a note on two reserved lines so a row of cards is as tall as its tallest and nothing shifts. A card with a tone `attn` is the figure that is near or past a limit.
4445 - `.fg-chart`, `.fg-svg`, `.fg-line`, `.fg-area`, `.fg-base`, `.fg-dot`, `.fg-axis` — the one chart: a line over a faint area in the accent, scaled from zero to the series' own peak, a day with no value breaking the line; its two ends named underneath (`14 days ago`, `today`); a card with no daily series keeps the same 32px, empty.
4546 - `.fg-reading` — the line a region shows before the first reading.
src/web/pages/home_flow.ts +19 −7
@@ -434,7 +434,7 @@ export function stripRegion(picture: LanePicture, viewer: StripViewer, dataDir:
434434 * A lane before the picture exists: its name, "reading…", and the address that fills it. The page's
435435 * script fetches that address at once.
436436 */
437 function readingLane(key: LaneKey, only: string | null): Html {
437 export function readingLane(key: LaneKey, only: string | null): Html {
438438 const scope = only === null ? null : html` data-live-repo="${only}"`;
439439 return html`<section class="lane" id="lane-${key}" data-lane="${key}" data-tone="quiet" data-count="" data-reading aria-busy="true"
440440 data-live="${LANE_LIVE[key]}" data-live-src="/live/lane?s=${key}${query(only)}"${scope}>
@@ -446,10 +446,22 @@ function readingLane(key: LaneKey, only: string | null): Html {
446446 </section>`;
447447 }
448448
449 const readingStrip = (): Html =>
450 html`<section class="hf-strip" id="hf-strip" data-reading aria-busy="true" aria-label="Today's figures" data-live="${STRIP_LIVE}" data-live-src="/live/strip"><p class="hf-calm"><span class="dot"></span>Reading today's figures…</p></section>`;
449 /**
450 * The strip before the picture exists. For the owner it draws the loaded strip's own figures
451 * (same labels, links and classes, "—" for the value), so the two are the same height; anyone else
452 * gets the one line alone, as the loaded strip does.
453 */
454 export const readingStrip = (wide: boolean): Html =>
455 html`<section class="hf-strip" id="hf-strip" data-reading aria-busy="true" aria-label="${wide ? "Today's figures" : "What needs you"}" data-live="${STRIP_LIVE}" data-live-src="/live/strip"><p class="hf-calm"><span class="dot"></span>Reading today's figures…</p>${wide ? html`<div class="hf-figs">${READING_FIGS.map(([label, href]) => fig(label, "—", "\u00a0", href))}</div>` : null}</section>`;
456 const READING_FIGS: readonly (readonly [string, string])[] = [
457 ["Shipped in 24 hours", "/board"],
458 ["Median open to landed", "/boards"],
459 ["Crew running", "/settings/crew"],
460 ["Week used", "/settings/crew"],
461 ["Live version", "/releases"],
462 ];
451463
452 const readingTable = (q: TableQuery): Html => {
464 export const readingTable = (q: TableQuery): Html => {
453465 const params = tableParams(q);
454466 return html`<section class="tb-region" id="hf-table" data-reading aria-busy="true" data-live="${TABLE_LIVE}" data-live-src="/live/table${params === "" ? "" : `?${params}`}"><p class="tb-empty">Reading what the forge is doing…</p></section>`;
455467 };
@@ -518,7 +530,7 @@ function forgesHtml(f: Forges): Html {
518530 return html`<p class="hf-forges" id="hf-forges" data-live="${FORGES_LIVE}" data-live-src="/live/forges" data-tone="${f.quiet.length === 0 ? "ok" : "attn"}"><span class="dot" ${f.quiet.length === 0 ? null : html`data-tone="attn"`}></span><a href="/forges">${words}</a></p>`;
519531 }
520532
521 const readingForges = (): Html =>
533 export const readingForges = (): Html =>
522534 html`<p class="hf-forges" id="hf-forges" data-reading data-live="${FORGES_LIVE}" data-live-src="/live/forges"><span class="dot"></span><span>Reading the hosted forges…</span></p>`;
523535
524536 /**
@@ -613,7 +625,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited
613625 // or lean.
614626 const spawned = known !== undefined ? known.spawned : await timePhaseAsync(ctx.request, "spawned", () => spawnedForge(ctx.app));
615627 const wide = user.isAdmin && spawned === undefined;
616 const strip = picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now);
628 const strip = picture === undefined ? readingStrip(wide) : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now);
617629 // What the old home also carried and is not a lane: the box that tells the crew (with Notes and
618630 // Talk), the welcome after an account is allowed, a
619631 // spawned forge's address, and a stranger's request for an account. The everyday-account ask is
@@ -747,7 +759,7 @@ export async function liveStripFragment(ctx: Ctx): Promise<Response> {
747759 const picture = await timePhaseAsync(ctx.request, "picture", () => lanePicture(ctx.app.db, optionsOf(ctx, user), "lane", now));
748760 const rendering = performance.now();
749761 const wide = user.isAdmin && (await spawnedForge(ctx.app)) === undefined;
750 const res = fragment(picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now), { request: ctx.request });
762 const res = fragment(picture === undefined ? readingStrip(wide) : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now), { request: ctx.request });
751763 notePhase(ctx.request, "render", performance.now() - rendering);
752764 return res;
753765 }
src/web/pages/home_flow_style.ts +18
@@ -235,6 +235,24 @@ a.fg-card:hover { border-color: var(--border-strong); color: var(--fg); }
235235 .fg-axis { display: flex; justify-content: space-between; gap: 8px; min-height: 16px; margin: 0; font-size: var(--fs-min); line-height: 16px; color: var(--muted-fg); }
236236 .fg-reading { margin: 0; color: var(--muted-fg); }
237237
238 /* ---- first paint reserves what fills in later (test/home-no-shift.test.ts) ----
239 A region in its reading state is the loaded region's own markup where the
240 loaded one is fixed (the strip draws its five figures with "—"), and holds
241 the loaded floor where the data decides the rest. The floors are summed
242 from the loaded rules above, not guessed: change a part, change its sum.
243 Not measured in a browser (none ran where this was written); the data
244 decides the rest, so a long note or a busy lane still grows past its floor. */
outdated

300px while reading against 44px once loaded: the page shrinks by about 256px on a phone when the strip fills. Reserve the loaded height in both states.

245 .hf-forges { min-height: 44px; }
outdated

Guessed heights (.lane 180px, .tb-region 320px, .fg-body 176px) shift in the other direction when the loaded content is shorter. Measure them from the loaded render and say so here.

246 /* A lane: its head and health line are in the reading markup already; the
247 floor adds, under its 8px padding, one tile row: a gap (8px) and the tile's
248 min-height (44px). */
249 .lane[data-reading] { padding-bottom: 64px; }
250 /* A table: its header row and one row, each 44px (.tb-pick), and the gap. */
251 .tb-region[data-reading] { min-height: calc(44px + 8px + 44px); }
252 /* A figures card: border 2 + padding 24 + label 18 + gap 4 + value 28 + gap 4
253 + note 32 + gap 4 + chart (4 + 32) + gap 4 + axis 16 = 172px, one row. */
254 .fg-body { min-height: 172px; }
255
238256 /* ---- the box that tells the crew, kept to one row on a desk ---- */
239257 .hf-tell { display: flex; flex-wrap: wrap; align-items: center; gap: 0 16px; }
240258 .hf-tell .tell-box { flex: 1 1 480px; min-width: 0; flex-wrap: nowrap; }
test/home-no-shift.test.ts added +200
@@ -0,0 +1,200 @@
1 /**
2 * The signed-in home's first paint reserves space for everything that loads
3 * later: no layout shift on the page the owner opens most. Read off the
4 * server's HTML and the stylesheet it links, so a region added without a
5 * reserved height, or an image without a size, fails here.
6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createSession } from "../src/core/sessions.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { LANES } from "../src/flow/lanes_read.ts";
15 import { readingForges, readingLane, readingStrip, readingTable } from "../src/web/pages/home_flow.ts";
16 import { parseTable } from "../src/flow/lanes_table.ts";
17 import { figuresSection } from "../src/web/pages/home_figures.ts";
18 import { seedHomeFlow } from "./helpers/home-flow-seed.ts";
19
20 const tags = (html: string): { name: string; attrs: string }[] =>
21 [...html.matchAll(/<([a-z][a-z0-9]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi)].map((m) => ({ name: m[1]!.toLowerCase(), attrs: m[2]! }));
22 const attr = (attrs: string, name: string): string | null =>
23 new RegExp(`(?:^|\\s)${name}(?:="([^"]*)")?(?=\\s|/|$)`).exec(attrs)?.[1] ?? (new RegExp(`(?:^|\\s)${name}(?=\\s|/|$)`).test(attrs) ? "" : null);
24
25 const noComments = (css: string): string => css.replace(/\/\*[\s\S]*?\*\//g, "");
26
27 interface Rule { readonly compound: string; readonly body: string }
28 /**
29 * Every rule's last compound selector and its declarations; media blocks flatten, which is enough
30 * to know a height is declared.
31 */
32 function rulesOf(raw: string): Rule[] {
33 const css = noComments(raw);
34 const out: Rule[] = [];
35 for (const m of css.matchAll(/([^{}]+)\{([^{}]*)\}/g))
36 for (const sel of m[1]!.split(",")) out.push({ compound: sel.trim().split(/[\s>+~]+/).pop()!, body: m[2]! });
37 return out;
38 }
39 const reserves = (body: string): boolean => /(?:^|[;\s])(?:(?:min-)?height|padding-bottom)\s*:\s*(?:calc\()?[1-9]\d*(?:\.\d+)?(?:px|rem|em|vh|lh)/.test(body);
40
41 /** Does the stylesheet give this element a height before its content arrives? */
42 function reserved(attrs: string, rules: Rule[]): boolean {
43 const id = attr(attrs, "id");
44 const classes = (attr(attrs, "class") ?? "").split(/\s+/).filter(Boolean);
45 const reading = attr(attrs, "data-reading") !== null;
46 return rules.some((r) => {
47 if (!reserves(r.body)) return false;
48 if (r.compound.includes("[data-reading]") && !reading) return false;
49 const base = r.compound.replace(/\[data-reading\]/g, "");
50 return (id !== null && base === `#${id}`) || classes.some((c) => base === `.${c}`);
51 });
52 }
53
54 /**
55 * Regions whose reading state is the loaded markup itself, proved by the strip test below, not by a
56 * height.
57 */
58 const STRUCTURAL = new Set(["hf-strip"]);
59
60 /**
61 * What a page's HTML promises: every image sized, every late-filled region given a height. A
62 * late-filled region is one in its reading state: it carries `data-reading`, which the page's
63 * script looks for and replaces (`home_flow_client.ts`). The reading renderers are also checked
64 * directly below, so a page that happens to be loaded cannot hide one.
65 */
66 function unreserved(html: string, rules: Rule[]): string[] {
67 const bad: string[] = [];
68 for (const t of tags(html)) {
69 if (t.name === "img" && (attr(t.attrs, "width") === null || attr(t.attrs, "height") === null || attr(t.attrs, "width") === "" || attr(t.attrs, "height") === ""))
70 bad.push(`img without width and height: ${t.attrs.trim().slice(0, 80)}`);
71 if (attr(t.attrs, "data-reading") !== null && !STRUCTURAL.has(attr(t.attrs, "id") ?? "") && !reserved(t.attrs, rules))
72 bad.push(`streamed region without a reserved height: ${t.attrs.trim().slice(0, 80)}`);
73 }
74 return bad;
75 }
76
77 describe("the detector", () => {
78 const rules = rulesOf(".a { min-height: 40px; } .b[data-reading] { height: 10px; } #c { color: red; } .d { min-height: 0; }");
79 test("fails an img without width and height", () => {
80 expect(unreserved('<img src="/x.png">', rules)).toHaveLength(1);
81 expect(unreserved('<img src="/x.png" width="10">', rules)).toHaveLength(1);
82 expect(unreserved('<img src="/x.png" width="10" height="10">', rules)).toHaveLength(0);
83 });
84 test("fails a late-filled region without a reserved height, and honours a reading-only rule only while reading", () => {
85 expect(unreserved('<div class="a" data-reading>', rules)).toHaveLength(0);
86 expect(unreserved('<div id="c" data-reading>', rules)).toHaveLength(1);
87 expect(unreserved('<div class="d" data-reading>', rules)).toHaveLength(1);
88 expect(unreserved('<div class="b" data-live-src="/live/x">', rules)).toHaveLength(0);
89 expect(unreserved('<div class="b" data-reading>', rules)).toHaveLength(0);
90 expect(unreserved('<div class="e" data-reading>', rules)).toHaveLength(1);
91 });
92 });
93
94 /**
95 * The px a declaration gives, summing calc(a + b) terms; null when the rule or property is absent.
96 */
97 function px(raw: string, selector: string, prop: string): number | null {
98 const css = noComments(raw);
99 for (const m of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
100 if (!m[1]!.split(",").some((x) => x.trim() === selector)) continue;
101 const d = new RegExp(`(?:^|[;\\s])${prop}\\s*:\\s*([^;]+)`).exec(m[2]!);
102 if (d === null) continue;
103 return [...d[1]!.matchAll(/(\d+(?:\.\d+)?)px/g)].reduce((n, t) => n + Number(t[1]), 0);
104 }
outdated

This loop over a one-element array does nothing. Call the check once. Also compare the reading state's reserved height with the loaded state's, not only that some height exists.

105 return null;
106 }
107 const need = (n: number | null): number => {
108 expect(n).not.toBeNull();
109 return n!;
110 };
111
112 describe("the signed-in home", () => {
113 let app: App;
114 let servers: Servers;
115 let dataDir: string;
116 let reading = "";
117 let loaded = "";
118 let css = "";
119 let rules: Rule[] = [];
120
121 beforeAll(async () => {
122 dataDir = await mkdtemp(join(tmpdir(), "forge-noshift-"));
123 app = createApp({ dataDir, port: 0 });
124 const seed = await seedHomeFlow(app);
125 servers = await serve(app);
126 const cookie = `forge_session=${createSession(app.db, seed.owner.id).token}`;
127 const get = async (path: string): Promise<string> => (await fetch(`${servers.url}${path}`, { headers: { cookie } })).text();
128 reading = await get("/");
129 const href = /<link rel="stylesheet" href="([^"]+)"/.exec(reading)![1]!;
130 css = await get(href);
131 rules = rulesOf(css);
132 // The live addresses warm the picture; the page after them is the loaded one.
133 for (const path of ["/live/strip", "/live/figures", "/live/table", "/live/lane?s=ready"]) await get(path);
134 loaded = await get("/");
135 });
136 afterAll(async () => {
137 await servers.stop();
138 await rm(dataDir, { recursive: true, force: true });
139 });
140
141 test("every streamed region and image in the render has its space reserved", () => {
142 expect(reading).toContain("data-live-src");
143 expect(unreserved(reading, rules)).toEqual([]);
144 });
145
146 test("each reading renderer, called directly, reserves", () => {
147 const q = parseTable(new URLSearchParams());
148 const states = [readingStrip(true), readingStrip(false), readingTable(q), readingForges(), ...LANES.map((k) => readingLane(k, null))];
149 for (const state of states) {
150 expect(String(state)).toContain("data-reading");
151 expect(unreserved(String(state), rules)).toEqual([]);
152 }
153 });
154
155 test("a reading page carries only the regions this file reserves for, and the loaded page none", () => {
156 const named = new Set(["hf-strip", "hf-forges", "hf-table", "hf-figures-body"]);
157 const left = tags(reading).filter((t) => attr(t.attrs, "data-reading") !== null).map((t) => attr(t.attrs, "id") ?? "");
158 for (const id of left) expect(named.has(id) || id.startsWith("lane-")).toBe(true);
159 expect(tags(loaded).filter((t) => attr(t.attrs, "data-reading") !== null)).toEqual([]);
160 });
161
162 test("the reading strip is the loaded strip's figures: same labels, links and count", () => {
163 const figs = (h: string): string[] => [...h.matchAll(/<a class="hf-fig" href="([^"]+)"[^>]*>\s*<span class="hf-fig-label">([^<]*)</g)].map((m) => `${m[2]} ${m[1]}`);
164 expect(figs(loaded)).toHaveLength(5);
165 expect(figs(reading)).toEqual(figs(loaded));
166 });
167
168 test("the reading lane holds the loaded lane's head and health line, and a tile row more", () => {
169 const parts = (h: string): string[] => [...h.matchAll(/<(header class="lane-head"|p class="lane-health")/g)].map((m) => m[1]!);
170 expect(parts(reading).length).toBeGreaterThan(0);
171 expect(parts(loaded)).toEqual(parts(reading));
172 // The lane's own bottom padding is the last of "12px 8px 8px"; then one tile row: the list's
173 // gap and the tile's own minimum.
174 const floor = need(px(css, ".lane[data-reading]", "padding-bottom"));
175 expect(floor).toBeGreaterThanOrEqual(8 + need(px(css, ".lane-list", "gap")) + need(px(css, ".tile-link", "min-height")));
176 });
177
178 test("the reading table holds its header row and one row", () => {
179 const row = need(px(css, ".tb-pick", "height"));
180 expect(need(px(css, ".tb-region[data-reading]", "min-height"))).toBeGreaterThanOrEqual(2 * row + need(px(css, ".tb-region", "gap")));
181 });
182
183 test("the figures' reading state reserves the loaded row of cards, summed from the card's own rules", () => {
184 const section = String(figuresSection(undefined, Date.now()));
185 expect(section).toContain("data-reading");
186 expect(unreserved(section, rules)).toEqual([]);
187 const card =
188 need(px(css, ".fg-card", "padding")) +
189 2 +
190 18 + // the label: 12px at the body's 1.5 line
191 need(px(css, ".fg-n", "line-height")) +
192 need(px(css, ".fg-note", "min-height")) +
193 need(px(css, ".fg-chart", "height")) +
194 need(px(css, ".fg-chart", "margin-top")) +
195 need(px(css, ".fg-axis", "min-height")) +
196 4 * need(px(css, ".fg-card", "gap"));
197 // The card's padding is "12px 16px": top and bottom make 24.
198 expect(need(px(css, ".fg-body", "min-height"))).toBeGreaterThanOrEqual(card - 16 * 2 + 12);
199 });
200 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs