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

small: the space view has a legend that says what a body's size, colour and distance mean #12782

Merged opened this

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

Merged

torque/forge:torque/12757-small-the-space-view-has-a-legend-that-s → main 7 commits fork 5 threads · 5 unresolved

  • Merged. torque/12757-small-the-space-view-has-a-legend-that-s was merged into main as 5e78705.

Review

Sign in to review this change.
7 files changed +129 −3
docs/design/areas/space.md +3
@@ -7,3 +7,6 @@ The repository space (`/:owner/:name/space`, `docs/features/space.md`): one full
77 - `.space-time` — the scrubber along the bottom; shown only when the script runs.
88 - `.space-panel` — what a tapped issue or crew member is on: a heading and rows, on the page background with one hairline.
99 - `.space-list` — the pillar list the server draws; hidden when the script runs.
10 - `.space-foot` — the bottom edge: the legend above the scrubber, one block so opening the legend lifts the scrubber with it.
11 - `.space-legend` — a `details` that says what size, ink and distance mean; closed in the server render, opened by the script on a first visit on a wide screen only. No border; the page background sets it off.
12 - `.space-legend i` — the swatch before a state's name, inked at the same strength the canvas uses (`ink-<state>`).
docs/features/space.md +1
@@ -10,6 +10,7 @@ is `/:owner/:name/space.json`, the same plane for an agent. In the terminal it i
1010 - **Semantic zoom.** Out: pillars are regions whose area follows open work, with a progress bar (landed ÷ open + landed over the week) and whether they moved. In: each region's issues sit in clusters by state (ready, building, in review, waiting, landed). Further in: an issue is a card with its title, then its pull, checks and the crew member on it. Words are set at a fixed pixel size at every level; detail is added, nothing shrinks.
1111 - **Time.** The scrubber replays the last 7 days: issues appear when opened, slide from "in review" to "landed" when they close, and crew members sit on what they were running then. **Play** runs the week in 20 seconds. At **Now** the view is live: any run, issue or pull event of the repository fetches the plane again.
1212 - **Crew.** Their avatars sit on the issue they are working; tap one (or its name in the bar) to see what they are on.
13 - **Legend.** **Legend**, above the scrubber, says what size, ink and distance mean and gives each state one line. It starts closed; on a wide screen it opens once, on a first visit, and stays closed after. It is real HTML from `space_model.ts`, so it reads without the script.
1314 - **Share.** The view is in the address hash: `#x=…&y=…&z=…` (centre in world units, zoom relative to Fit) and `&t=` (minutes since the epoch) when scrubbed back.
1415
1516 ## How it is built
src/web/pages/space.ts +15 −1
@@ -15,7 +15,7 @@ import { html } from "../html.ts";
1515 import { page } from "../layout.ts";
1616 import { btn } from "../ui.ts";
1717 import { spaceCss, spaceJs } from "../space_client.ts";
18 import type { Region } from "../space_model.ts";
18 import { COLOUR_SAYS, DISTANCE_SAYS, SIZE_SAYS, STATES, STATE_LEGEND, type Region } from "../space_model.ts";
1919 import { spaceOf } from "../space_read.ts";
2020
2121 /** The plane as JSON: for the canvas, and for an agent that wants the numbers. */
@@ -67,12 +67,26 @@ export function spacePage(ctx: Ctx): Response {
6767 <span id="space-crew"></span>
6868 </div>
6969 <aside class="space-panel" id="space-panel" hidden></aside>
70 <div class="space-foot">
71 <details class="space-legend" id="space-legend">
72 <summary>Legend</summary>
73 <p>${SIZE_SAYS}</p>
74 <p>${COLOUR_SAYS}</p>
75 <ul>
76 ${STATES.map(
77 (s) =>
78 html`<li><i class="ink-${s}" aria-hidden="true"></i><strong>${STATE_LEGEND[s].label}</strong>: ${STATE_LEGEND[s].says}</li>`,
79 )}
80 </ul>
81 <p>${DISTANCE_SAYS}</p>
82 </details>
7083 <div class="space-time">
7184 ${btn("Play", { type: "button", id: "space-play", variant: "outline", size: "sm" })}
7285 <input type="range" id="space-t" min="0" max="10080" step="1" value="10080" aria-label="Time, the last 7 days" />
7386 <output id="space-clock">Now</output>
outdated

Principle 1 (nothing explains itself twice): the page already labels each cluster, and the legend then restates each cluster name plus three paragraphs. Keep one short sentence per state. Principle 3: the swatch <i> hand-rolled with per-state classes is a new component class; per docs/DESIGN.md it belongs in docs/design/areas/space.md, or use a named component.

7487 ${btn("Now", { type: "button", id: "space-now", variant: "outline", size: "sm" })}
7588 </div>
89 </div>
7690 <div class="space-list">
7791 <h1>${repo.name}</h1>
7892 <p id="space-error" class="muted" hidden>The canvas could not load the space. The pillars are below.</p>
src/web/space_client.ts +32 −2
@@ -11,9 +11,28 @@
1111 * markup from data: text goes to the canvas or to `textContent`.
1212 */
1313
14 import { STATES, STATE_INK } from "./space_model.ts";
1415 import { viewJs } from "./space_view.ts";
1516
17 /**
18 * The legend arrives closed, so a returning visitor sees no jump. On the first
19 * visit, and only where there is room beside the plane, it opens. The legend
20 * sits in the bottom bar, which is out of the page's flow, so opening shifts no layout.
21 */
22 export const legendJs = /* js */ `
23 (function () {
24 var legend = document.getElementById('space-legend');
25 if (!legend) return;
26 try {
27 if (localStorage.getItem('space-legend-seen')) return;
28 localStorage.setItem('space-legend-seen', '1');
29 if (window.matchMedia('(min-width: 40rem)').matches) legend.open = true;
30 } catch (e) {}
31 })();
32 `;
33
1634 export const spaceCss = /* css */ `
35 ${STATES.map((s) => `.space-legend .ink-${s} { opacity: ${STATE_INK[s]}; }`).join("\n")}
1736 html.space-on, html.space-on body { height: 100%; overflow: hidden; overscroll-behavior: none; }
1837 .space { position: fixed; inset: 0; background: var(--bg); color: var(--fg); overflow: auto; }
outdated

The summary is .85rem text with no minimum tap height, well under 44px on a phone. Give it a 44px target and a visible focus ring.

1938 .space canvas, .space-bar, .space-time { display: none; }
@@ -23,7 +42,7 @@ html.space-on .space canvas:active { cursor: grabbing; }
2342 html.space-on .space-bar { display: flex; position: absolute; left: 0; right: 0; top: 0; gap: .5rem; align-items: center; flex-wrap: wrap; padding: .5rem .75rem; pointer-events: none; }
2443 .space-bar > *, .space-bar span > * { pointer-events: auto; }
2544 .space-bar span { display: contents; }
26 html.space-on .space-time { display: flex; position: absolute; left: 0; right: 0; bottom: 0; gap: .6rem; align-items: center; padding: .6rem .75rem calc(.6rem + env(safe-area-inset-bottom)); background: linear-gradient(transparent, var(--bg) 60%); }
45 html.space-on .space-time { display: flex; gap: .6rem; align-items: center; padding: .6rem .75rem calc(.6rem + env(safe-area-inset-bottom)); background: linear-gradient(transparent, var(--bg) 60%); }
2746 .space-time input[type=range] { flex: 1; min-width: 0; accent-color: var(--accent); }
2847 .space-time output { font-variant-numeric: tabular-nums; min-width: 9ch; text-align: right; }
2948 .space-panel { position: absolute; right: .75rem; top: 3.5rem; width: min(22rem, calc(100% - 1.5rem)); background: var(--bg); border-left: 1px solid var(--border); padding: .75rem 1rem; }
@@ -31,11 +50,22 @@ html.space-on .space-time { display: flex; position: absolute; left: 0; right: 0
3150 .space-panel h2 { font-size: 1rem; margin: 0 0 .35rem; }
3251 .space-panel .status-rows { margin-top: 0; border-top: 0; }
3352 html.space-on .space-list { display: none; }
53 .space-legend { padding: 0 1rem; font-size: .85rem; }
54 .space-legend summary { cursor: pointer; font-weight: 600; min-height: 44px; display: flex; align-items: center; }
55 .space-legend summary:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
56 .space-legend ul { list-style: none; padding: 0; margin: .4rem 0 0; }
outdated

The server always sends open, and this closes it after first paint: a visible open-to-closed jump and layout shift for every returning visitor. Set the state before first paint (a tiny inline-free approach: render closed and open it on first visit only), and say in a test that the second visit is closed.

57 .space-legend li { margin: .25rem 0; }
58 .space-legend i { display: inline-block; width: .7rem; height: .7rem; margin-right: .4rem; background: currentColor; vertical-align: -.05rem; }
59 .space-foot { background: linear-gradient(transparent, var(--bg) 40%); }
60 html.space-on .space-foot { position: absolute; left: 0; right: 0; bottom: 0; }
61 html.space-on .space-foot .space-legend { max-height: 40vh; overflow: auto; background: var(--bg); }
62 html.space-on .space-foot .space-time { position: static; }
3463 .space-list { padding: 4rem 1rem 2rem; max-width: 40rem; }
3564 .space-list ul { list-style: none; padding: 0; margin: 0; }
3665 `;
3766
3867 export const spaceJs = /* js */ `
68 ${legendJs}
3969 (function () {
4070 ${viewJs}
4171 var root = document.getElementById('space');
@@ -63,7 +93,7 @@ ${viewJs}
6393 var accentFg = token('--accent-fg', fg);
6494 var ground = token('--bg', 'Canvas');
6595 // One accent, for interaction (the crew). A state is told by its cluster's label and position; its weight is muted as it ages.
66 var WEIGHT = { ready: 1, building: 1, review: 0.7, waiting: 0.5, landed: 0.35 };
96 var WEIGHT = ${JSON.stringify(STATE_INK)};
6797 var sans = style.fontFamily || 'system-ui, sans-serif';
6898 var picked = null; // {kind:'issue'|'crew', ...}
6999
src/web/space_model.ts +22
@@ -34,6 +34,28 @@ export function stateOf(word: string): State {
3434 }
3535 }
3636
37 /**
38 * What a reader is told a cluster means, one plain sentence per state. A
39 * `Record<State, …>` so a state added to `STATES` without words fails the
40 * type check, and `test/space-legend.test.ts` fails it at run time.
41 */
42 export const STATE_LEGEND: Record<State, { label: string; says: string }> = {
43 ready: { label: "Ready", says: "Open and nothing stands in front of it, so the crew can pick it up now." },
44 building: { label: "Building", says: "An agent is working on it right now." },
45 review: { label: "In review", says: "A pull is open, or a person holds it, and it waits for a verdict." },
46 waiting: { label: "Waiting", says: "Blocked by another issue, deferred or parked until something else moves." },
47 landed: { label: "Landed", says: "Closed this week." },
48 };
49
50 /** How strongly each state is inked on the canvas, 1 full to 0 faint: the page's one "colour". */
51 export const STATE_INK: Record<State, number> = { ready: 1, building: 1, review: 0.7, waiting: 0.5, landed: 0.35 };
52
53 /** The sentences for size, colour and distance, beside the five for state.
54 * The order is `STATES`, not retyped. */
outdated

Box 1 says the sentences are derived from space_model, not retyped. SIZE_SAYS, DISTANCE_SAYS and COLOUR_SAYS are hand-written prose about the layout, so they will drift silently when the layout changes. Derive what you can (for example the order from STATES) or add a test that ties them to the layout constants. Principle 8: these sentences are long and use semicolons and 'inside it'; split them into plain short ones.

55 export const SIZE_SAYS = "Size: one square is one issue. A pillar's area follows its open work.";
56 export const COLOUR_SAYS = "Colour: one ink. The stronger it is, the nearer the work is to moving.";
57 export const DISTANCE_SAYS = `Distance: a pillar's issues sit together, in this order: ${STATES.map((s) => STATE_LEGEND[s].label).join(", ")}.`;
58
3759 export const DAY_MS = 86_400_000;
3860 /** How far back the scrubber goes. */
3961 export const WEEK_MS = 7 * DAY_MS;
test/space-legend.test.ts added +48
@@ -0,0 +1,48 @@
1 import { expect, test } from "bun:test";
2 import { DISTANCE_SAYS, STATES, STATE_INK, STATE_LEGEND } from "../src/web/space_model.ts";
3 import { legendJs, spaceCss, spaceJs } from "../src/web/space_client.ts";
4
5 test("every State has a legend row in words and an ink", () => {
6 for (const s of STATES) {
7 expect(STATE_LEGEND[s].label.length).toBeGreaterThan(0);
8 expect(STATE_LEGEND[s].says.endsWith(".")).toBe(true);
9 expect(STATE_INK[s]).toBeGreaterThan(0);
10 expect(spaceCss).toContain(`.ink-${s} { opacity: ${STATE_INK[s]}; }`);
11 }
12 expect(Object.keys(STATE_LEGEND).sort()).toEqual([...STATES].sort());
13 });
14
15 test("the canvas draws with the same inks the legend shows", () => {
16 expect(spaceJs).toContain(JSON.stringify(STATE_INK));
17 });
18
19 test("the distance sentence lists the states in the order of STATES", () => {
20 const labels = STATES.map((s) => STATE_LEGEND[s].label);
21 expect(DISTANCE_SAYS).toContain(labels.join(", "));
22 });
23
24 /** Runs the legend script against a stub page: the visit number and the width decide. */
25 function visit(store: Map<string, string>, wide: boolean) {
26 const legend = { open: false };
27 const doc = { getElementById: (id: string) => (id === "space-legend" ? legend : null) };
28 const ls = { getItem: (k: string) => store.get(k) ?? null, setItem: (k: string, v: string) => void store.set(k, v) };
29 const win = { matchMedia: () => ({ matches: wide }) };
30 new Function("document", "localStorage", "window", legendJs)(doc, ls, win);
31 return legend.open;
32 }
33
34 test("the legend opens on the first visit on a wide screen and is closed on the second", () => {
35 const store = new Map<string, string>();
36 expect(visit(store, true)).toBe(true);
37 expect(visit(store, true)).toBe(false);
38 });
39
40 test("on a phone the legend stays closed even on the first visit", () => {
41 expect(visit(new Map(), false)).toBe(false);
42 });
43
44 test("the legend has no border and a 44px tap target with a focus ring", () => {
45 expect(spaceCss).not.toMatch(/\.space-legend[^{]*\{[^}]*border/);
46 expect(spaceCss).toContain("min-height: 44px");
47 expect(spaceCss).toContain(".space-legend summary:focus-visible");
48 });
test/space-page.test.ts +8
@@ -111,3 +111,11 @@ test("the script starts its frame loop before the data arrives, and says when it
111111 test("the one accent is for interaction: the canvas paints no state hues", () => {
112112 for (const token of ["--series-1", "--attn", "--series-4", "--success"]) expect(spaceJs).not.toContain(token);
113113 });
114
115 test("the legend is real HTML in the server render, closed, with every state", async () => {
116 const body = await (await get("/keeper/forge/space")).text();
117 expect(body).toContain('<details class="space-legend" id="space-legend">');
118 for (const s of ["Ready", "Building", "In review", "Waiting", "Landed"]) expect(body).toContain(`<strong>${s}</strong>`);
119 expect(body).toContain("Size:");
120 expect(body).toContain("Distance:");
121 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs