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

Interactions are behaviors: a small set of attachable, keyboard-complete enhancements over the forge's server-rendered HTML, and each page tells an agent what it can do #13785

Merged opened this in answer to

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

Merged

mason/forge:mason/13783-interactions-are-behaviors-a-small-set-o → main 6 commits fork 4 threads · 4 unresolved

  • Merged. mason/13783-interactions-are-behaviors-a-small-set-o was merged into main as 4332836.

Review

Sign in to review this change.
7 files changed +238 −22
docs/features/README.md +1
@@ -40,6 +40,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
4040 - [Reply to an issue post in the feed](feed-reply.md)
4141 - [Forge packs: a premade forge to deploy (`/packs`)](packs.md)
4242 - [Home paints its frame first](home-frame.md)
43 - [Behaviors: shared interactions, attached by attribute](behaviors.md)
4344 - [Is v1.0.0 proven?](v1-proven.md)
4445 - [Looks of `/` signed out](home-looks.md)
4546 - [Milestones at the front door](front-milestones.md)
docs/features/behaviors.md added +11
@@ -0,0 +1,11 @@
1 # Behaviors: shared interactions, attached by attribute
2
3 One module, `src/web/behaviors.ts` (one string, no dependency, under 2 KB: `test/behaviors.test.ts`), holds the interactions pages share. Each is attached by an attribute on HTML that already works without script. Only what a page uses is in it; a new behavior arrives with the page that needs it, keyboard path and terminal door included. The model is Vercel's UI SDK; none of its code or weight is used.
4
5 | Attribute | What it does |
6 | --- | --- |
7 | `data-disclose="attr"` on a button inside `[data-disclose-scope]` | sets or clears `attr` on the scope; `data-label-on`/`data-label-off` say the button; `aria-expanded` is kept (the home lane's "Show all N", which replaced that page's own toggle script) |
8
9 `test/behaviors-rule.test.ts` freezes the pages that still ship their own script and the files that still read a width in script, and lets both lists only shrink. Layout answers to CSS media and container queries, never to a width read in script.
10
11 Terminal door: a lane's "Show all N" is a phone layout choice with no terminal counterpart; the terminal lists every lane in full (`src/tui/screens/flow.ts`).
src/web/behaviors.ts added +39
@@ -0,0 +1,39 @@
1 /**

Dead code: tabs, menu, dialog, tooltip, roving and resize have no caller. Remove them until a page needs one. The ~350 lines ship to every home visit. Also lift's key argument and end's u argument are unused.

2 * Behaviors: the forge's shared interactions, each attached by an attribute on HTML that already
3 * works without it (the model of Vercel's UI SDK, none of its weight: one string, no dependency,
4 * under BEHAVIORS_BUDGET bytes, test/behaviors.test.ts). Only what a page uses is here; a new
5 * behavior arrives with the page that needs it. Layout is never decided here: widths answer to CSS
6 * media and container queries (test/behaviors-rule.test.ts).
7 *
8 * data-disclose="attr" a button that sets or clears `attr` on its closest [data-disclose-scope]
9 * (labels in data-label-on / data-label-off; aria-expanded is kept)
10 */
11 export const BEHAVIORS_BUDGET = 2 * 1024;
12
13 export const behaviorsJs = /* js */ `
14 (function () {
15 if (window.forgeBehaviors) return;
16 window.forgeBehaviors = true;
17 var d = document;
18 function disclose() {
19 Array.prototype.forEach.call(d.querySelectorAll('[data-disclose]'), function (b) {
20 var scope = b.closest('[data-disclose-scope]');
21 if (!scope) return;
22 var on = scope.hasAttribute(b.getAttribute('data-disclose'));
23 b.setAttribute('aria-expanded', on ? 'true' : 'false');
24 var label = b.getAttribute(on ? 'data-label-on' : 'data-label-off');
25 if (label && b.textContent !== label) b.textContent = label;
26 });
27 }
28 d.addEventListener('click', function (e) {
29 var b = e.target && e.target.closest ? e.target.closest('[data-disclose]') : null;
30 var scope = b && b.closest('[data-disclose-scope]');
31 if (!scope) return;
32 var attr = b.getAttribute('data-disclose');
33 if (scope.hasAttribute(attr)) scope.removeAttribute(attr); else scope.setAttribute(attr, '');
34 disclose();
35 });
36 d.addEventListener('forge:swapped', disclose);
37 disclose();
38 })();
39 `;
src/web/pages/home_flow.ts +4 −2
@@ -45,6 +45,7 @@ import type { Ctx } from "../../http/context.ts";
4545 import { signInFirst } from "../chrome.ts";
4646 import { figure as fig } from "../figure.ts";
4747 import { homeFlowJs } from "./home_flow_client.ts";
48 import { behaviorsJs } from "../behaviors.ts";
4849 import { liveRegionsJs } from "../client.ts";
4950 import { html, type Html } from "../html.ts";
5051 import { fragment, page, redirect } from "../layout.ts";
@@ -174,6 +175,7 @@ export function laneRegion(
174175 class="lane"
175176 id="lane-${key}"
176177 data-lane="${key}"
178 data-disclose-scope
177179 data-tone="${health.tone}"
178180 data-count="${String(view.total)}"
179181 aria-label="${label}"
@@ -212,7 +214,7 @@ export function laneRegion(
212214 ><span class="lane-more-md">${more(total - 4)}</span
213215 ><span class="lane-more-sm">${more(total - 4)}</span></a
214216 >
215 <button type="button" class="lane-toggle" aria-expanded="false" data-all="${String(total)}">Show all ${String(total)}</button>
217 <button type="button" class="lane-toggle" aria-expanded="false" data-disclose="data-open" data-label-off="Show all ${String(total)}" data-label-on="Show fewer">Show all ${String(total)}</button>
216218 ${total > shown ? html`<a class="lane-all" href="${href}">All ${String(total)} in the table</a>` : null}
217219 </p>`}
218220 </section>`;
@@ -543,7 +545,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited
543545 <a href="/feed">The feed</a>
544546 </p>
545547 </div>`;
546 const res = page({ ctx, title: "Home", body, wide: true, scriptJs: `${liveRegionsJs}\n${homeFlowJs}` });
548 const res = page({ ctx, title: "Home", body, wide: true, scriptJs: `${liveRegionsJs}\n${homeFlowJs}\n${behaviorsJs}` });
547549 // The view asked for in the address is remembered for the next visit.
548550 if (asked) {
549551 res.headers.append("set-cookie", setCookie(VIEW_COOKIE, view, { maxAge: 31536000, secure: secureFor(ctx.url, ctx.app.config.url) }));
src/web/pages/home_flow_client.ts +1 −20
@@ -90,7 +90,6 @@ export const homeFlowJs = /* js */ `
9090 var lane = e.target && e.target.closest ? e.target.closest('.lane') : null;
9191 clocks(true);
9292 if (lane) glide(lane); else remember();
93 toggles();
9493 afterSwap();
9594 });
9695 doc.addEventListener('forge:event', function () { clocks(false); });
@@ -321,26 +320,8 @@ export const homeFlowJs = /* js */ `
321320 });
322321 }
323322
324 // ---- a lane on a phone: Show all N opens it in place; the lane keeps data-open through every redraw ----
325 var toggles = function () {
326 Array.prototype.forEach.call(root.querySelectorAll('.lane'), function (lane) {
327 var button = lane.querySelector('.lane-toggle');
328 if (!button) return;
329 var open = lane.hasAttribute('data-open');
330 button.setAttribute('aria-expanded', open ? 'true' : 'false');
331 button.textContent = open ? 'Show fewer' : 'Show all ' + button.getAttribute('data-all');
332 });
333 };
323 // A lane's "Show all N" is the disclose behavior (behaviors.ts); the lane keeps data-open through every redraw.
334324 root.setAttribute('data-js', '');
335 doc.addEventListener('click', function (e) {
336 var button = e.target && e.target.closest ? e.target.closest('.lane-toggle') : null;
337 if (!button) return;
338 var lane = button.closest('.lane');
339 if (lane.hasAttribute('data-open')) lane.removeAttribute('data-open'); else lane.setAttribute('data-open', '');
340 toggles();
341 });
342 toggles();
343
344325 remember();
345326 clocks(true);
346327 })();
test/behaviors-rule.test.ts added +137
@@ -0,0 +1,137 @@
1 /**
2 * The rule (#13783): a page uses a behavior (`src/web/behaviors.ts`) or plain HTML for an
3 * interaction, and layout answers to CSS alone. Both are ratchets: the pages that already carry
4 * their own script, and the files that already read a width in script, are named here and may only
5 * leave this list. A page that is new, or a read that is new, fails until it uses a behavior or
6 * CSS.
7 */
8 import { expect, test } from "bun:test";
9 import { readFileSync, readdirSync, statSync } from "node:fs";
10 import { join } from "node:path";
11
12 const SRC = join(import.meta.dir, "..", "src");
13 const SKIP = /\/(vendor|render|og)(\/|$)/;
14
15 function walk(dir: string): string[] {
16 return readdirSync(dir).flatMap((n) => {
17 const p = join(dir, n);
18 if (SKIP.test(p)) return [];
19 return statSync(p).isDirectory() ? walk(p) : p.endsWith(".ts") ? [p] : [];
20 });
21 }
22 const files = walk(SRC).map((p) => ({ path: p.slice(SRC.length - 3), text: readFileSync(p, "utf8") }));
23
24 /**
25 * Pages that ship their own script today (each is replaced by a behavior, page by page, then
26 * leaves).
27 */
28 const OWN_SCRIPT = new Set([
29 "src/web/pages/api.ts",
30 "src/web/pages/apps.ts",
31 "src/web/pages/backups.ts",
32 "src/web/pages/bets.ts",
33 "src/web/pages/board.ts",
34 "src/web/pages/boards-view.ts",
35 "src/web/pages/boards.ts",
36 "src/web/pages/branches.ts",
37 "src/web/pages/bring.ts",
38 "src/web/pages/browse.ts",
39 "src/web/pages/builds.ts",
40 "src/web/pages/changelog.ts",
41 "src/web/pages/claim.ts",
42 "src/web/pages/commits.ts",
43 "src/web/pages/display.ts",
44 "src/web/pages/edit.ts",
45 "src/web/pages/everyday.ts",
46 "src/web/pages/family.ts",
47 "src/web/pages/first-admin.ts",
48 "src/web/pages/fleet-graph.ts",
49 "src/web/pages/flow.ts",
50 "src/web/pages/global-map.ts",
51 "src/web/pages/home_flow.ts",
52 "src/web/pages/iterations.ts",
53 "src/web/pages/map.ts",
54 "src/web/pages/migrate.ts",
55 "src/web/pages/milestones.ts",
56 "src/web/pages/new-forge.ts",
57 "src/web/pages/next.ts",
58 "src/web/pages/notes.ts",
59 "src/web/pages/origin-flow.ts",
60 "src/web/pages/passkeys.ts",
61 "src/web/pages/pricing.ts",
62 "src/web/pages/pull.ts",
63 "src/web/pages/repo.ts",
64 "src/web/pages/settings.ts",
65 "src/web/pages/site.ts",
66 "src/web/pages/space.ts",
67 "src/web/pages/start-forge.ts",
68 "src/web/pages/subscriptions.ts",
69 "src/web/pages/system.ts",
70 "src/web/pages/talk.ts",
71 "src/web/pages/teams.ts",
72 "src/web/pages/usage-tabs.ts",
73 "src/web/pages/variants.ts",
74 "src/web/studio/app.ts",
75 "src/web/studio/asks_page.ts",
76 "src/web/studio/change.ts",
77 "src/web/studio/drop.ts",
78 "src/web/studio/home.ts",
79 "src/web/studio/lists.ts",
80 "src/web/studio/review_page.ts",
81 "src/web/studio/run.ts",
82 "src/web/studio/share_tell.ts",
83 "src/web/studio/tell.ts",
84 "src/web/studio/tell_refused.ts",
85 "src/web/studio/toolbar.ts"
86 ]);
87
88 /**
89 * Files that read a width in script today, with how many reads: layout must answer to CSS instead.
90 */
91 const WIDTH_READS: Record<string, number> = {
92 "src/looks/capture.ts": 6,
93 "src/looks/readable.ts": 4,
94 "src/actions/runs.ts": 1,
95 "src/checks/looks.ts": 3,
96 "src/checks/summary.ts": 1,
97 "src/apps/toolbar.ts": 5,
98 "src/web/space_client.ts": 2,
99 "src/web/forge_made.ts": 1,
100 "src/web/client.ts": 2,
101 "src/web/pages/iterations.ts": 7,
102 "src/web/pages/map.ts": 2,
103 "src/web/studio/cards.ts": 1,
104 "src/keeper/covered.ts": 1,
105 "src/core/looks.ts": 3
106 };
107
108 const WIDTH = /innerWidth|clientWidth|offsetWidth|matchMedia\(['"]\((min|max)-/g;
109
110 test("a page that sets its own script is on the list or composes the behaviors", () => {
111 const strangers = files
112 .filter((f) => /\bscriptJs:/.test(f.text) && !OWN_SCRIPT.has(f.path) && !f.text.includes("behaviorsJs"))
113 .map((f) => f.path);
114 expect(strangers).toEqual([]);
115 });
116
117 test("the list only names pages that still set a script", () => {
118 const live = new Set(files.filter((f) => /\bscriptJs:/.test(f.text)).map((f) => f.path));
119 expect([...OWN_SCRIPT].filter((p) => !live.has(p))).toEqual([]);
120 });
121
122 test("no file reads a width in script beyond what the list allows", () => {
123 const over = files
124 .filter((f) => f.path !== "src/web/behaviors.ts")
125 .map((f) => ({ path: f.path, n: (f.text.match(WIDTH) ?? []).length }))
126 .filter((f) => f.n > (WIDTH_READS[f.path] ?? 0))
127 .map((f) => `${f.path}: ${f.n} reads of a width in script; use a media or container query`);
128 expect(over).toEqual([]);
129 });
130
131 test("the behaviors themselves read no width and the home lanes use them", () => {
132 const behaviors = files.find((f) => f.path === "src/web/behaviors.ts")?.text ?? "";
133 expect(behaviors.match(WIDTH) ?? []).toEqual([]);
134 const home = files.find((f) => f.path === "src/web/pages/home_flow.ts")?.text ?? "";
135 expect(home).toContain("data-disclose");
136 expect(home).toContain("behaviorsJs");
137 });
test/behaviors.test.ts added +45
@@ -0,0 +1,45 @@
1 /**
2 * Behaviors (`src/web/behaviors.ts`): one file under its budget, each interaction attached by an
3 * attribute on HTML that works without it.
4 */
5 import { expect, test } from "bun:test";
6 import { Window, type HTMLElement } from "happy-dom";
7 import { BEHAVIORS_BUDGET, behaviorsJs } from "../src/web/behaviors.ts";
8
9 function open(body: string) {
10 const window = new Window({ url: "https://forge.test/" });
11 window.document.body.innerHTML = body;
12 window.eval(behaviorsJs);
13 return window;
14 }
15
16 test("the module is one string under its budget", () => {
17 expect(Buffer.byteLength(behaviorsJs)).toBeLessThan(BEHAVIORS_BUDGET);
18 });
19
20 test("a disclosure button flips its scope's attribute, its label and aria-expanded", () => {
21 const window = open(`<section data-disclose-scope><button data-disclose="data-open" data-label-off="Show all 9" data-label-on="Show fewer">Show all 9</button></section>`);
22 const b = window.document.querySelector("button") as unknown as HTMLElement;
23 expect(b.getAttribute("aria-expanded")).toBe("false");
24 b.click();
25 expect(window.document.querySelector("section")?.hasAttribute("data-open")).toBe(true);
26 expect(b.textContent).toBe("Show fewer");
27 expect(b.getAttribute("aria-expanded")).toBe("true");
28 b.click();
29 expect(b.textContent).toBe("Show all 9");
30 expect(b.getAttribute("aria-expanded")).toBe("false");
31 });
32
33 test("a redrawn region (forge:swapped) keeps its disclosure state and labels", () => {
34 const window = open(`<section data-disclose-scope data-open><button data-disclose="data-open" data-label-off="Show all 9" data-label-on="Show fewer">Show all 9</button></section>`);
35 window.document.dispatchEvent(new window.CustomEvent("forge:swapped"));
36 const b = window.document.querySelector("button") as unknown as HTMLElement;
37 expect(b.textContent).toBe("Show fewer");
38 expect(b.getAttribute("aria-expanded")).toBe("true");
39 });
40
41 test("a button with no scope does nothing", () => {
42 const window = open(`<button data-disclose="data-open">x</button>`);
43 (window.document.querySelector("button") as unknown as HTMLElement).click();
44 expect(window.document.body.hasAttribute("data-open")).toBe(false);
45 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs