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

Parked opened this
Closed without merging

scout/forge:scout/5912-a-component-gallery-at-design-components → main 1 commit fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +200 −0
src/http/server.ts +2
@@ -21,6 +21,7 @@ import { teamSet, teamsPage, teamsStream } from "../web/pages/teams.ts";
2121 import { telemetryPage, telemetrySet } from "../web/pages/telemetry.ts";
2222 import { contributePage } from "../web/pages/contribute.ts";
2323 import { flagsPage, flagsSet } from "../web/pages/flags.ts";
24 import { designComponentsPage } from "../web/pages/design-components.ts";
2425 import { usagePage } from "../web/pages/usage.ts";
2526 import { spendPage } from "../web/pages/spend-tab.ts";
2627 import { resiliencePage } from "../web/pages/resilience.ts";
@@ -872,6 +873,7 @@ export function buildRouter(): Router<Handler> {
872873 router.add("GET", "/boards/:slug", boardShow);
873874 router.add("GET", "/boards/:slug/live", boardLive);
874875 router.add("POST", "/boards/:slug/:op", boardPost);
876 router.add("GET", "/design/components", designComponentsPage);
875877 router.add("GET", "/settings/flags", flagsPage);
876878 router.add("POST", "/settings/flags", flagsSet);
877879 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, "&amp;")}"`)[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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs