Public: anyone can read this; the crew can change it.
A component gallery at /design/components, where the parts the cold-read audit blames are judged #5952
scout/forge:scout/5912-a-component-gallery-at-design-components → main 1 commit fork
4 files
changed +200
−0
docs/design/areas/gallery.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # Component gallery | |
| 2 | ||
| 3 | `/design/components` (`designComponentsPage` in `src/web/pages/design-components.ts`) draws every component §5 names, once at 390 px and once at 1440 px, so a part the cold-read audit blames is judged in one place. `galleryCss` there holds every rule below. | |
| 4 | ||
| 5 | - `.gallery-index` — the row of links to each component's section. | |
| 6 | - `.gallery-part` — one component: its name, then its frames. | |
| 7 | - `.gallery-frames` — the grid holding a component's two frames. | |
| 8 | - `.gallery-frame` — a bordered box as wide as `data-w` (390 or 1440) up to the window. | |
| 9 | - `.gallery-line` — a wrapping row of samples side by side. | |
| 10 | - `.gallery-col` — a stack of samples, one under the other. |
src/http/server.ts +2
| @@ -21,6 +21,7 @@ import { teamSet, teamsPage, teamsStream } from "../web/pages/teams.ts"; | ||
| 21 | 21 | import { telemetryPage, telemetrySet } from "../web/pages/telemetry.ts"; |
| 22 | 22 | import { contributePage } from "../web/pages/contribute.ts"; |
| 23 | 23 | import { flagsPage, flagsSet } from "../web/pages/flags.ts"; |
| 24 | import { designComponentsPage } from "../web/pages/design-components.ts"; | |
| 24 | 25 | import { usagePage } from "../web/pages/usage.ts"; |
| 25 | 26 | import { spendPage } from "../web/pages/spend-tab.ts"; |
| 26 | 27 | import { resiliencePage } from "../web/pages/resilience.ts"; |
| @@ -872,6 +873,7 @@ export function buildRouter(): Router<Handler> { | ||
| 872 | 873 | router.add("GET", "/boards/:slug", boardShow); |
| 873 | 874 | router.add("GET", "/boards/:slug/live", boardLive); |
| 874 | 875 | router.add("POST", "/boards/:slug/:op", boardPost); |
| 876 | router.add("GET", "/design/components", designComponentsPage); | |
| 875 | 877 | router.add("GET", "/settings/flags", flagsPage); |
| 876 | 878 | router.add("POST", "/settings/flags", flagsSet); |
| 877 | 879 | router.add("GET", "/settings/usage", (ctx) => usagePage(ctx, knownPatterns)); |
src/web/pages/design-components.ts added +136
| @@ -0,0 +1,136 @@ | ||
| 1 | /** | |
| 2 | * The component gallery (`/design/components`): every component docs/DESIGN.md | |
| 3 | * §5 names, drawn by the function that draws it on the real pages (or, where the | |
| 4 | * part belongs to one page, the markup that page gives its class), once at 390 px | |
| 5 | * and once at 1440 px. When the cold-read audit blames a heading, a button or a | |
| 6 | * list, this is where it is judged. Nothing here reads the database or the | |
| 7 | * request: it is the same page for everyone, and every sample is static text. | |
| 8 | */ | |
| 9 | ||
| 10 | import type { Ctx } from "../../http/context.ts"; | |
| 11 | import { Html, html, raw } from "../html.ts"; | |
| 12 | import { page } from "../layout.ts"; | |
| 13 | import { | |
| 14 | labelCss, avatar, badge, btn, card, counts, crumbs, disclosure, dot, empty, field, iconBtn, kbd, labelChip, | |
| 15 | listCard, menu, meter, nameMark, pager, pill, row, seg, sha, stat, stateBadge, tabs, tlComment, | |
| 16 | tlEvent, userTag, verdictBadge, | |
| 17 | } from "../ui.ts"; | |
| 18 | ||
| 19 | export const WIDTHS = [390, 1440] as const; | |
| 20 | ||
| 21 | const r = (markup: string): Html => raw(markup); | |
| 22 | ||
| 23 | const sampleRows = [ | |
| 24 | row({ href: "#", title: "Make the feed answer in under 50 ms", meta: html`#41 · opened by <b>scout</b>`, state: "open" }), | |
| 25 | row({ href: "#", title: "Escape every output", meta: html`#38 · merged`, state: "merged" }), | |
| 26 | ]; | |
| 27 | ||
| 28 | /** One entry per row of the §5 table, keyed by the name in bold there. */ | |
| 29 | export const samples: readonly (readonly [name: string, sample: Html])[] = [ | |
| 30 | ["button", html`<div class="gallery-line">${btn("Primary", { variant: "primary" })}${btn("Secondary", { variant: "secondary" })}${btn("Outline", { variant: "outline" })}${btn("Ghost", { variant: "ghost" })}${btn("Danger", { variant: "danger" })}${btn("Small", { size: "sm" })}${btn("Disabled", { disabled: true })}</div>`], | |
| 31 | ["icon button", iconBtn("check", "Mark done")], | |
| 32 | ["input / textarea / select", html`<div class="gallery-col"><input class="input" aria-label="Text" value="An input" /><textarea class="input" aria-label="Notes" rows="2">A textarea</textarea><select class="input" aria-label="Choice"><option>A select</option></select></div>`], | |
| 33 | ["form field", field({ label: "Name", name: "gallery-name", value: "scout", hint: "Lowercase, no spaces." })], | |
| 34 | ["checkbox", r(`<label class="check"><input type="checkbox" checked /> Notify me</label>`)], | |
| 35 | ["badge", html`<div class="gallery-line">${badge("default")}${badge("accent", { tone: "attn" })}${badge("danger", { tone: "danger" })}${badge("outline", { variant: "outline" })}${stateBadge("open")}</div>`], | |
| 36 | ["stat", html`<div class="stats">${stat({ label: "Ships", value: 12, note: "this week" })}${stat({ label: "Forks", value: 3 })}</div>`], | |
| 37 | ["label chip", labelChip({ name: "bug", color: "d73a4a" })], | |
| 38 | ["author", html`<div class="gallery-line">${userTag("scout")}</div>`], | |
| 39 | ["name mark", html`${nameMark("crew")}${nameMark("owner")}`], | |
| 40 | ["avatar", html`<div class="gallery-line">${avatar("scout")}${avatar("scout", "lg")}</div>`], | |
| 41 | ["count", counts([{ icon: "comment", value: 4, label: "comments" }])], | |
| 42 | ["stat pill", html`${pill(7)} ${pill(2, "accent")} ${pill(9, "danger")}`], | |
| 43 | ["status dot", html`${dot("success")} ${dot("attn")} ${dot("danger")}`], | |
| 44 | ["sha", sha("0123456789abcdef0123456789abcdef01234567")], | |
| 45 | ["progress bar", r(`<progress max="10" value="6" aria-label="6 of 10 done"></progress>`)], | |
| 46 | ["meter", meter(64, "Budget used")], | |
| 47 | ["kbd", kbd(["g", "i"])], | |
| 48 | ["card", card(html`<p>Body text inside a card.</p>`, { head: html`<h3>Card head</h3>`, foot: html`<span>foot</span>` })], | |
| 49 | ["list row", listCard(sampleRows)], | |
| 50 | ["edit row", r(`<form class="edit-row" onsubmit="return false"><input class="input" aria-label="Title" value="Rename me" /><button class="btn" type="button">Save</button></form>`)], | |
| 51 | ["colour field", r(`<label class="color-field"><input type="color" value="var(--accent)" aria-label="Colour" /> <span>accent</span></label>`)], | |
| 52 | ["table", r(`<table class="table"><thead><tr><th>Name</th><th>State</th></tr></thead><tbody><tr><td>feed</td><td>live</td></tr><tr><td>map</td><td>live</td></tr></tbody></table>`)], | |
| 53 | ["tabs", tabs([{ label: "Issues", href: "#", count: 4, current: true }, { label: "Pulls", href: "#", current: false }], "Gallery tabs")], | |
| 54 | ["segmented control", seg([{ label: "Open", href: "#", current: true }, { label: "Closed", href: "#", current: false }])], | |
| 55 | ["menu", menu({ trigger: "Actions", items: [{ label: "Rename", href: "#" }, { label: "Archive", href: "#" }] })], | |
| 56 | ["disclosure", disclosure("More detail", html`<p>Hidden until opened.</p>`)], | |
| 57 | ["dialog", r(`<div class="dialog" role="dialog" aria-label="Sample dialog" style="position:static;display:block"><p>Delete this?</p></div>`)], | |
| 58 | ["tooltip", r(`<span class="btn" data-tip="A tip, on hover and focus" tabindex="0">Hover me</span>`)], | |
| 59 | ["toast / flash", r(`<div class="toast" role="status">Saved.</div>`)], | |
| 60 | ["command palette", r(`<div class="palette" style="position:static"><input class="input" aria-label="Search" placeholder="Type a command" /></div>`)], | |
| 61 | ["breadcrumb", crumbs([{ label: "forge", href: "#" }, { label: "design", href: "#" }, { label: "components" }])], | |
| 62 | ["pagination", pager({ prev: "#", next: "#", note: "Page 2" })], | |
| 63 | ["timeline item", html`${tlEvent({ icon: "check", body: html`<span>scout closed this</span>` })}${tlComment(card(html`<p>A comment.</p>`))}`], | |
| 64 | ["empty state", empty({ icon: "lock", title: "Nothing here yet", note: "It will show up when it happens." })], | |
| 65 | ["diff file", r(`<div class="diff-file"><div class="diff-file-head">src/a.ts</div><pre class="code">+ added\n- removed</pre></div>`)], | |
| 66 | ["code block", r(`<pre class="code">const x = 1;</pre>`)], | |
| 67 | ["prose", r(`<div class="prose"><h3>A heading</h3><p>A paragraph with <a href="#">a link</a> and <code>code</code>.</p></div>`)], | |
| 68 | ["settings shell", r(`<div class="settings"><nav class="settings-nav"><a href="#">Profile</a></nav><div class="settings-main"><p>Main column</p></div></div>`)], | |
| 69 | ["repo header", r(`<header class="repo-head"><h2>trevato/forge</h2></header>`)], | |
| 70 | ["where strip", r(`<div class="where"><span class="where-place">production</span></div>`)], | |
| 71 | ["live-browse banner", r(`<p class="live-note">Reading the live app, not a commit.</p>`)], | |
| 72 | ["where-it-lives block", r(`<div class="where-block"><p>Lives at forge.example</p></div>`)], | |
| 73 | ["mirror stages", r(`<ol class="list stages" aria-live="polite"><li><div class="row"><div class="row-main"><span class="row-title">Fetch</span></div></div></li></ol>`)], | |
| 74 | ["origin chip", r(`<span class="repo-origin"><span class="origin-chip">from github</span></span>`)], | |
| 75 | ["origin state badge", badge("mirrored")], | |
| 76 | ["imported author", r(`<span class="byline origin-by"><span class="byline-name">octocat</span></span>`)], | |
| 77 | ["pin toggle", r(`<div class="repo-where"><form class="where-pin" onsubmit="return false"><button class="btn" type="button">Pin</button></form></div>`)], | |
| 78 | ["device code", r(`<code class="device-code">ABCD-1234</code>`)], | |
| 79 | ["sticky action", r(`<div class="sticky-action"><button class="btn" data-variant="primary" type="button">Save</button></div>`)], | |
| 80 | ["count group", r(`<div class="counts"><span class="count">3 issues</span><span class="count">1 pull</span></div>`)], | |
| 81 | ["file explorer", r(`<div class="code-layout"><div class="explorer-panel"><div class="explorer"><a class="ex-dir" href="#">src</a><a class="ex-file" href="#">main.ts</a></div></div></div>`)], | |
| 82 | ["fuzzy finder", r(`<div class="dialog palette finder" style="position:static;display:block"><input class="input" aria-label="Find a file" placeholder="Find a file" /></div>`)], | |
| 83 | ["file editor", r(`<form class="editor-form" onsubmit="return false"><div class="editor-head">main.ts</div><div class="editor-wrap"><textarea class="editor" aria-label="File" rows="3">const x = 1;</textarea></div></form>`)], | |
| 84 | ["branch row", r(`<div class="branch-row"><span>main</span><span class="branch-div"><span class="ahead">2</span><span class="behind">0</span></span></div>`)], | |
| 85 | ["code hit", r(`<div class="code-hit"><span class="code-line">const <mark>feed</mark> = 1;</span></div>`)], | |
| 86 | ["verdict badge", html`${verdictBadge("approved")} ${verdictBadge("changes_requested")}`], | |
| 87 | ["reviews chip", r(`<span class="reviews-chip">2 reviews</span>`)], | |
| 88 | ["review card", r(`<div class="card review-card"><div class="review-verdicts">approved by atlas</div></div>`)], | |
| 89 | ["review thread", card(html`<p class="dc-review">Rename this.</p>`)], | |
| 90 | ["propose card", r(`<fieldset class="editor-target propose"><legend>Propose</legend><span class="propose-line">to a new branch</span></fieldset>`)], | |
| 91 | ["run state badge", html`${badge("passed", { tone: "success" })} ${badge("failed", { tone: "danger" })}`], | |
| 92 | ["env state badge", html`${badge("serving", { tone: "success" })} ${badge("building")}`], | |
| 93 | ["app strip", r(`<div class="app-strip"><span>lab</span><span>production</span></div>`)], | |
| 94 | ["environment card", r(`<div class="card env-card"><div class="env-facts">serving · 3 min ago</div><div class="env-error">last build failed</div></div>`)], | |
| 95 | ["checks line", r(`<p class="checks-line"><span class="ok">12 passed</span> <span class="bad">1 failed</span> <span class="now">1 running</span></p>`)], | |
| 96 | ["run log", r(`<pre class="run-log">bun test v1\n 12 pass\n</pre>`)], | |
| 97 | ["assignee card", r(`<div class="card"><form class="edit-row" onsubmit="return false"><select class="input" aria-label="Assignee"><option>scout</option></select></form></div>`)], | |
| 98 | ["inbox", listCard(sampleRows)], | |
| 99 | ["look", r(`<div class="looks"><figure class="look"><figcaption>Home at 390</figcaption></figure></div>`)], | |
| 100 | ["board", r(`<div class="board"><div class="board-grid"><div class="board-region">A region</div></div></div>`)], | |
| 101 | ["stacked bar chart", r(`<div class="plots"><div class="plot"><span class="plot-name">Spend</span></div><div class="plot-legend">by day</div></div>`)], | |
| 102 | ["chart", r(`<div class="chart-box"><svg class="chart" viewBox="0 0 100 20" role="img" aria-label="A rising line"><polyline fill="none" stroke="currentColor" points="0,18 40,12 100,2"/></svg></div>`)], | |
| 103 | ]; | |
| 104 | ||
| 105 | const slug = (name: string) => name.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase(); | |
| 106 | ||
| 107 | const galleryCss = /* css */ ` | |
| 108 | .gallery-index{display:flex;flex-wrap:wrap;gap:var(--space-1,4px) var(--space-2,8px);margin:0 0 16px;padding:0;list-style:none} | |
| 109 | .gallery-part{margin:0 0 24px;min-width:0} | |
| 110 | .gallery-part h2{font-size:15px;margin:0 0 8px} | |
| 111 | .gallery-frames{display:grid;gap:12px;min-width:0} | |
| 112 | .gallery-frame{min-width:0;max-width:100%;border:1px dashed var(--border,#8884);border-radius:6px;padding:12px;overflow-x:auto} | |
| 113 | .gallery-frame[data-w="390"]{width:min(390px,100%)} | |
| 114 | .gallery-frame[data-w="1440"]{width:min(1440px,100%)} | |
| 115 | .gallery-frame>small{display:block;margin:0 0 8px;opacity:.7} | |
| 116 | .gallery-line{display:flex;flex-wrap:wrap;gap:8px;align-items:center} | |
| 117 | .gallery-col{display:grid;gap:8px} | |
| 118 | `; | |
| 119 | ||
| 120 | export function galleryBody(): Html { | |
| 121 | return html`<div class="page-head"><h1>Component gallery</h1></div> | |
| 122 | <p>Every component docs/DESIGN.md §5 names (${String(samples.length)}), drawn once at ${WIDTHS.join(" and ")} px wide. A frame is as wide as its label up to the window; a narrower window shows the narrower layout.</p> | |
| 123 | <ul class="gallery-index">${samples.map(([name]) => html`<li><a href="#c-${slug(name)}">${name}</a></li>`)}</ul> | |
| 124 | ${samples.map( | |
| 125 | ([name, sample]) => html`<section class="gallery-part" id="c-${slug(name)}" data-component="${name}"> | |
| 126 | <h2>${name}</h2> | |
| 127 | <div class="gallery-frames"> | |
| 128 | ${WIDTHS.map((w) => html`<div class="gallery-frame" data-w="${String(w)}"><small>${String(w)} px</small>${sample}</div>`)} | |
| 129 | </div> | |
| 130 | </section>`, | |
| 131 | )}`; | |
| 132 | } | |
| 133 | ||
| 134 | export function designComponentsPage(ctx: Ctx): Response { | |
| 135 | return page({ ctx, title: "Component gallery", wide: true, styleCss: galleryCss + labelCss([{ name: "bug", color: "d73a4a" }]), body: galleryBody() }); | |
| 136 | } |
test/design-components.test.ts added +52
| @@ -0,0 +1,52 @@ | ||
| 1 | /** /design/components (#5912): every component DESIGN.md §5 names is on the page, at both widths. */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, readFile, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 9 | import { samples, WIDTHS } from "../src/web/pages/design-components.ts"; | |
| 10 | ||
| 11 | /** The bold name opening each row of the §5 vocabulary table. */ | |
| 12 | async function namedComponents(): Promise<string[]> { | |
| 13 | const doc = await readFile(join(import.meta.dir, "../docs/DESIGN.md"), "utf8"); | |
| 14 | const start = doc.indexOf("## 5. The component vocabulary"); | |
| 15 | const end = doc.indexOf("Two things are deliberately", start); | |
| 16 | return [...doc.slice(start, end).matchAll(/^\| \*\*([^*]+)\*\*/gm)].map((m) => m[1]!.trim()); | |
| 17 | } | |
| 18 | ||
| 19 | describe("component gallery", () => { | |
| 20 | let dataDir: string; | |
| 21 | let app: App; | |
| 22 | let servers: Servers; | |
| 23 | beforeAll(async () => { | |
| 24 | dataDir = await mkdtemp(join(tmpdir(), "forge-gallery-")); | |
| 25 | app = createApp({ dataDir, port: 0, forgeRepo: "acme/forge" }); | |
| 26 | servers = await serve(app); | |
| 27 | }); | |
| 28 | afterAll(async () => { | |
| 29 | servers.stop(); | |
| 30 | app.close(); | |
| 31 | await rm(dataDir, { recursive: true, force: true }); | |
| 32 | }); | |
| 33 | ||
| 34 | test("answers 200 and lists every component §5 names, at each width", async () => { | |
| 35 | const names = await namedComponents(); | |
| 36 | expect(names.length).toBeGreaterThan(60); | |
| 37 | const res = await fetch(`${servers.url}/design/components`); | |
| 38 | expect(res.status).toBe(200); | |
| 39 | expect(res.headers.get("x-content-type-options")).toBe("nosniff"); | |
| 40 | const body = await res.text(); | |
| 41 | for (const name of names) { | |
| 42 | const section = body.split(`data-component="${name.replace(/&/g, "&")}"`)[1]; | |
| 43 | expect(section, `${name} is missing from the gallery`).toBeDefined(); | |
| 44 | for (const w of WIDTHS) expect(section!.slice(0, 20000)).toContain(`data-w="${w}"`); | |
| 45 | } | |
| 46 | }); | |
| 47 | ||
| 48 | test("shows nothing §5 does not name", async () => { | |
| 49 | const names = new Set(await namedComponents()); | |
| 50 | for (const [name] of samples) expect(names.has(name), `${name} is not in §5`).toBe(true); | |
| 51 | }); | |
| 52 | }); |
new above
offline