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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/12757-small-the-space-view-has-a-legend-that-s → main 7 commits fork 5 threads · 5 unresolved
docs/design/areas/space.md +3
| @@ -7,3 +7,6 @@ The repository space (`/:owner/:name/space`, `docs/features/space.md`): one full | ||
| 7 | 7 | - `.space-time` — the scrubber along the bottom; shown only when the script runs. |
| 8 | 8 | - `.space-panel` — what a tapped issue or crew member is on: a heading and rows, on the page background with one hairline. |
| 9 | 9 | - `.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 | ||
| 10 | 10 | - **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. |
| 11 | 11 | - **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. |
| 12 | 12 | - **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. | |
| 13 | 14 | - **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. |
| 14 | 15 | |
| 15 | 16 | ## How it is built |
src/web/pages/space.ts +15 −1
| @@ -15,7 +15,7 @@ import { html } from "../html.ts"; | ||
| 15 | 15 | import { page } from "../layout.ts"; |
| 16 | 16 | import { btn } from "../ui.ts"; |
| 17 | 17 | 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"; | |
| 19 | 19 | import { spaceOf } from "../space_read.ts"; |
| 20 | 20 | |
| 21 | 21 | /** 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 { | ||
| 67 | 67 | <span id="space-crew"></span> |
| 68 | 68 | </div> |
| 69 | 69 | <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> | |
| 70 | 83 | <div class="space-time"> |
| 71 | 84 | ${btn("Play", { type: "button", id: "space-play", variant: "outline", size: "sm" })} |
| 72 | 85 | <input type="range" id="space-t" min="0" max="10080" step="1" value="10080" aria-label="Time, the last 7 days" /> |
| 73 | 86 | <output id="space-clock">Now</output> |
| 74 | 87 | ${btn("Now", { type: "button", id: "space-now", variant: "outline", size: "sm" })} |
| 75 | 88 | </div> |
| 89 | </div> | |
| 76 | 90 | <div class="space-list"> |
| 77 | 91 | <h1>${repo.name}</h1> |
| 78 | 92 | <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 @@ | ||
| 11 | 11 | * markup from data: text goes to the canvas or to `textContent`. |
| 12 | 12 | */ |
| 13 | 13 | |
| 14 | import { STATES, STATE_INK } from "./space_model.ts"; | |
| 14 | 15 | import { viewJs } from "./space_view.ts"; |
| 15 | 16 | |
| 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 | ||
| 16 | 34 | export const spaceCss = /* css */ ` |
| 35 | ${STATES.map((s) => `.space-legend .ink-${s} { opacity: ${STATE_INK[s]}; }`).join("\n")} | |
| 17 | 36 | html.space-on, html.space-on body { height: 100%; overflow: hidden; overscroll-behavior: none; } |
| 18 | 37 | .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. |
||
| 19 | 38 | .space canvas, .space-bar, .space-time { display: none; } |
| @@ -23,7 +42,7 @@ html.space-on .space canvas:active { cursor: grabbing; } | ||
| 23 | 42 | 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; } |
| 24 | 43 | .space-bar > *, .space-bar span > * { pointer-events: auto; } |
| 25 | 44 | .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%); } | |
| 27 | 46 | .space-time input[type=range] { flex: 1; min-width: 0; accent-color: var(--accent); } |
| 28 | 47 | .space-time output { font-variant-numeric: tabular-nums; min-width: 9ch; text-align: right; } |
| 29 | 48 | .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 | ||
| 31 | 50 | .space-panel h2 { font-size: 1rem; margin: 0 0 .35rem; } |
| 32 | 51 | .space-panel .status-rows { margin-top: 0; border-top: 0; } |
| 33 | 52 | 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 |
||
| 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; } | |
| 34 | 63 | .space-list { padding: 4rem 1rem 2rem; max-width: 40rem; } |
| 35 | 64 | .space-list ul { list-style: none; padding: 0; margin: 0; } |
| 36 | 65 | `; |
| 37 | 66 | |
| 38 | 67 | export const spaceJs = /* js */ ` |
| 68 | ${legendJs} | |
| 39 | 69 | (function () { |
| 40 | 70 | ${viewJs} |
| 41 | 71 | var root = document.getElementById('space'); |
| @@ -63,7 +93,7 @@ ${viewJs} | ||
| 63 | 93 | var accentFg = token('--accent-fg', fg); |
| 64 | 94 | var ground = token('--bg', 'Canvas'); |
| 65 | 95 | // 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)}; | |
| 67 | 97 | var sans = style.fontFamily || 'system-ui, sans-serif'; |
| 68 | 98 | var picked = null; // {kind:'issue'|'crew', ...} |
| 69 | 99 |
src/web/space_model.ts +22
| @@ -34,6 +34,28 @@ export function stateOf(word: string): State { | ||
| 34 | 34 | } |
| 35 | 35 | } |
| 36 | 36 | |
| 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 | ||
| 37 | 59 | export const DAY_MS = 86_400_000; |
| 38 | 60 | /** How far back the scrubber goes. */ |
| 39 | 61 | 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 | ||
| 111 | 111 | test("the one accent is for interaction: the canvas paints no state hues", () => { |
| 112 | 112 | for (const token of ["--series-1", "--attn", "--series-4", "--success"]) expect(spaceJs).not.toContain(token); |
| 113 | 113 | }); |
| 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 | }); |
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.