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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13783-interactions-are-behaviors-a-small-set-o → main 6 commits fork 4 threads · 4 unresolved
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). | ||
| 40 | 40 | - [](feed-reply.md) |
| 41 | 41 | - [](packs.md) |
| 42 | 42 | - [](home-frame.md) |
| 43 | - [](behaviors.md) | |
| 43 | 44 | - [](v1-proven.md) |
| 44 | 45 | - [](home-looks.md) |
| 45 | 46 | - [](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 | /** | |
| 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"; | ||
| 45 | 45 | import { signInFirst } from "../chrome.ts"; |
| 46 | 46 | import { figure as fig } from "../figure.ts"; |
| 47 | 47 | import { homeFlowJs } from "./home_flow_client.ts"; |
| 48 | import { behaviorsJs } from "../behaviors.ts"; | |
| 48 | 49 | import { liveRegionsJs } from "../client.ts"; |
| 49 | 50 | import { html, type Html } from "../html.ts"; |
| 50 | 51 | import { fragment, page, redirect } from "../layout.ts"; |
| @@ -174,6 +175,7 @@ export function laneRegion( | ||
| 174 | 175 | class="lane" |
| 175 | 176 | id="lane-${key}" |
| 176 | 177 | data-lane="${key}" |
| 178 | data-disclose-scope | |
| 177 | 179 | data-tone="${health.tone}" |
| 178 | 180 | data-count="${String(view.total)}" |
| 179 | 181 | aria-label="${label}" |
| @@ -212,7 +214,7 @@ export function laneRegion( | ||
| 212 | 214 | ><span class="lane-more-md">${more(total - 4)}</span |
| 213 | 215 | ><span class="lane-more-sm">${more(total - 4)}</span></a |
| 214 | 216 | > |
| 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> | |
| 216 | 218 | ${total > shown ? html`<a class="lane-all" href="${href}">All ${String(total)} in the table</a>` : null} |
| 217 | 219 | </p>`} |
| 218 | 220 | </section>`; |
| @@ -543,7 +545,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited | ||
| 543 | 545 | <a href="/feed">The feed</a> |
| 544 | 546 | </p> |
| 545 | 547 | </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}` }); | |
| 547 | 549 | // The view asked for in the address is remembered for the next visit. |
| 548 | 550 | if (asked) { |
| 549 | 551 | 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 */ ` | ||
| 90 | 90 | var lane = e.target && e.target.closest ? e.target.closest('.lane') : null; |
| 91 | 91 | clocks(true); |
| 92 | 92 | if (lane) glide(lane); else remember(); |
| 93 | toggles(); | |
| 94 | 93 | afterSwap(); |
| 95 | 94 | }); |
| 96 | 95 | doc.addEventListener('forge:event', function () { clocks(false); }); |
| @@ -321,26 +320,8 @@ export const homeFlowJs = /* js */ ` | ||
| 321 | 320 | }); |
| 322 | 321 | } |
| 323 | 322 | |
| 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. | |
| 334 | 324 | 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 | ||
| 344 | 325 | remember(); |
| 345 | 326 | clocks(true); |
| 346 | 327 | })(); |
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 | }); |
new above
offline
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'skeyargument andend'suargument are unused.