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

A fork-tree branch with more than five forks collapses behind a plain details element that says how many it holds #13566

Merged opened this

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

Merged

torque/forge:torque/13541-a-fork-tree-branch-with-more-than-five-f → main 5 commits fork 2 threads · 2 unresolved

  • Merged. torque/13541-a-fork-tree-branch-with-more-than-five-f was merged into main as e9fc96b.

Review

Sign in to review this change.
8 files changed +147 −11
docs/features/README.md +1
@@ -47,6 +47,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
4747 - [The explorer's sorts](explore.md)
4848 - [The feed pages by cursor](feed-cursor.md)
4949 - [The fork tree](fork-tree.md)
50 - [A busy branch of the forge family folds](family-collapse.md)
5051 - [The home](living-home.md)
5152 - [The quiet feed names its one next thing](quiet-feed.md)
5253 - [The roadmap](roadmap.md)
docs/features/family-collapse.md added +8
@@ -0,0 +1,8 @@
1 # A busy branch of the forge family folds
2
3 On `/family`, a forge with more than five children shows them behind a plain `<details>` whose summary says
4 `N forks`. It needs no script and shifts no layout when opened; the links are in the page while it is closed, so
5 crawlers still follow them. The branch that holds the forge you are viewing opens by default.
6
7 In the terminal, open the palette and choose the family card: when there are more than five children it carries the
8 same `N forks` line before the children (`withForkCount` in `src/tui/screens/family.ts`).
src/tui/forge.ts +2 −2
@@ -57,7 +57,7 @@ import { canSeeMemory } from "../boards/memory.ts";
5757 import { askedScreen } from "./screens/asked.ts";
5858 import { notesScreen } from "./screens/thoughtnotes.ts";
5959 import { deciderScreen } from "./screens/decider.ts";
60 import { familyScreen } from "./screens/family.ts";
60 import { familyScreen, withForkCount } from "./screens/family.ts";
6161 import { securityScreen } from "./screens/security_public.ts";
6262 import { familyLines, familyView } from "../spawn/family.ts";
6363 import { issueScreen } from "./screens/issue.ts";
@@ -704,7 +704,7 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
704704 run: () =>
705705 runAsync(ctx, async () => {
706706 const view = await familyView(session.app, session.user?.isAdmin === true);
707 ctx.push(familyScreen(ctx, familyLines(view)));
707 ctx.push(familyScreen(ctx, withForkCount(familyLines(view), view.children.length)));
708708 }),
709709 });
710710 commands.push({
src/tui/screens/family.ts +8
@@ -27,3 +27,11 @@ export function familyScreen(ctx: Ctx, rows: readonly (readonly [string, string]
2727 },
2828 };
2929 }
30
31 /** The page folds a branch of more than five behind "N forks"; the terminal says the same count. */
32 export function withForkCount(rows: readonly [string, string][], children: number): [string, string][] {
33 if (children <= 5) return [...rows];
34 const at = rows.findIndex(([k]) => k.startsWith("child "));
35 const line: [string, string] = ["forks", `${children} forks`];
36 return at < 0 ? [...rows, line] : [...rows.slice(0, at), line, ...rows.slice(at)];
37 }
src/web/pages/family.ts +27 −5
@@ -14,7 +14,7 @@ import { familyView, followLine, type FamilyChild } from "../../spawn/family.ts"
1414 import { hostedChildApps } from "../../spawn/host.ts";
1515 import { MAX_DEPTH } from "../../spawn/heartbeat.ts";
1616 import { pageHead } from "../chrome.ts";
17 import { html, type Html } from "../html.ts";
17 import { html, raw, type Html } from "../html.ts";
1818 import { page } from "../layout.ts";
1919 import { badge, row } from "../ui.ts";
2020 import { FOLLOW_WORD } from "../../actions/follow_words.ts";
@@ -62,11 +62,33 @@ export function standingNode(c: FamilyChild): Node {
6262 };
6363 }
6464
65 /** More children than this fold behind a plain `<details>` (no script, no layout shift). */
66 export const FOLD_OVER = 5;
67
68 const holdsHere = (n: Node): boolean => n.here === true || n.children.some(holdsHere);
69
70 /**
71 * Over five children collapse behind `<details><summary>N forks</summary>`. The
72 * links stay in the markup, so a crawler reads them closed. The branch holding
73 * the viewed fork is open.
outdated

This sits between treeRow's doc comment and treeRow. Move it above the comment, and update the comment: it still says every branch is open.

74 */
75 function foldedKids(n: Node, kids: readonly Node[], depth: number): Html[] {
76 const rows = kids.map((c) => treeRow(c, depth + 1));
77 if (kids.length <= FOLD_OVER) return rows;
78 const open = kids.some(holdsHere);
79 return [
80 html`<li role="none" data-fold><details${open ? raw(" open") : null}><summary role="treeitem" aria-level="${depth + 2}" aria-expanded="${open ? "true" : "false"}">${plural(kids.length, "fork")}</summary><ul role="group" class="row-children">${rows}</ul></details></li>`,
81 ];
82 }
83
6584 /**
6685 * One node as a `row()` that is a `treeitem`: the row is what takes focus, so
67 * it carries the level and `aria-expanded` itself. Every branch is open in the
68 * markup, so without script the page is plain nested lists; `familyTreeJs`
69 * adds the keys and the folding. Depth shows as indentation and, quietly, as
86 * it carries the level and `aria-expanded` itself. A branch is open in the
87 * markup unless it has more than `FOLD_OVER` children and holds nobody being
88 * viewed: that one folds behind a `<details>`, whose summary is itself a
outdated

A summary inside role=group is not a treeitem, and the arrow-key script will focus hidden rows in a closed details (family_tree_js.ts all()). Fix both and test it.

89 * `treeitem` (so it is legal inside `role=group` and the arrow keys reach it).
90 * Without script the page is plain nested lists and a plain details; `familyTreeJs`
91 * adds the keys. Depth shows as indentation and, quietly, as
7092 * "level N" text for sighted readers (hidden from screen readers, which hear
7193 * `aria-level`).
7294 */
@@ -87,7 +109,7 @@ export function treeRow(n: Node, depth: number): Html {
87109 ...(trail.length === 0 ? {} : { trail: html`${trail}` }),
88110 ...(n.here ? { current: true } : {}),
89111 tree: { level: depth + 1, open: true },
90 children: kids.map((c) => treeRow(c, depth + 1)),
112 children: foldedKids(n, kids, depth),
91113 });
92114 }
93115
src/web/pages/family_tree_js.ts +20 −4
@@ -2,7 +2,8 @@
22 * The keys of the family tree (#12415). The markup is already a complete,
33 * open tree; this only adds a roving focus on the treeitem rows: Up/Down walk
44 * the visible rows, Right opens a branch (or steps into it), Left closes it
5 * (or steps out), Home/End jump. A closed branch hides its group with `hidden`.
5 * (or steps out), Home/End jump. A closed branch hides its group with `hidden`; a folded one is a
6 * `<details>` whose summary is a treeitem, and rows inside it count only while it is open.
67 *
78 * The navigation is one pure function, `treeStep`, over the visible rows as
89 * plain data; the script embeds that very function's source, and the test
@@ -44,18 +45,30 @@ export const familyTreeJs = /* js */ `
4445 if (!tree) return;
4546 ${treeStep.toString().replace(/<\/script/gi, "<\\/script")}
4647 var all = function () { return Array.prototype.slice.call(tree.querySelectorAll('[role=treeitem]')); };
47 var visible = function () { return all().filter(function (n) { return !n.closest('[hidden]'); }); };
48 // A row is not rendered inside a closed <details> or a hidden group; the fold's own
49 // summary (a treeitem) is judged from outside its details, so it stays reachable.
50 var unseen = function (n) {
51 var p = n.tagName === 'SUMMARY' ? n.parentElement.parentElement : n.parentElement;
52 return !!(p && p.closest('[hidden], details:not([open])'));
53 };
54 var visible = function () { return all().filter(function (n) { return !unseen(n); }); };
4855 var data = function (n) {
4956 var e = n.getAttribute('aria-expanded');
5057 return { level: Number(n.getAttribute('aria-level')), open: e === null ? null : e === 'true' };
5158 };
5259 function focusNode(n) {
5360 all().forEach(function (x) { x.tabIndex = -1; });
61 if (n.tagName === 'SUMMARY') n.setAttribute('tabindex', '0');
5462 n.tabIndex = 0;
5563 n.focus();
5664 }
5765 var first = all()[0];
5866 if (first) first.tabIndex = 0;
67 // Opening the fold by mouse, Enter or Space keeps aria-expanded true to what is drawn.
68 tree.addEventListener('toggle', function (e) {
69 var d = e.target, s = d && d.querySelector && d.querySelector(':scope > summary[role=treeitem]');
70 if (s) s.setAttribute('aria-expanded', d.open ? 'true' : 'false');
71 }, true);
5972 tree.addEventListener('keydown', function (e) {
6073 var cur = e.target.closest && e.target.closest('[role=treeitem]');
6174 if (!cur || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -65,9 +78,12 @@ export const familyTreeJs = /* js */ `
6578 if ('focus' in move) focusNode(list[move.focus]);
6679 else {
6780 var n = list[move.toggle];
68 var g = n.parentElement.querySelector(':scope > [role=group]');
6981 n.setAttribute('aria-expanded', move.open ? 'true' : 'false');
70 if (g) g.hidden = !move.open;
82 if (n.tagName === 'SUMMARY') n.parentElement.open = move.open;
83 else {
84 var g = n.parentElement.querySelector(':scope > [role=group]');
85 if (g) g.hidden = !move.open;
86 }
7187 }
7288 e.preventDefault();
7389 });
src/web/style/components.ts +3
@@ -486,6 +486,9 @@ a.row:hover, .row[data-nav]:hover { background: var(--muted); color: inherit; }
486486 .list li[aria-current="true"] > .row { background: var(--muted); }
487487 /* A tree: the rows under a row hang from a rule, a step in. */
488488 .row-children { list-style: none; margin: 0 0 0 22px; padding: 0; border-left: 1px solid var(--border); }
489 .row-children > li[data-fold] > details > summary { display: flex; align-items: center; min-height: 44px; padding: 0 12px; cursor: pointer; color: var(--muted-fg, inherit); }
490 .row-children > li[data-fold] > details > summary:hover { background: var(--muted); }
491 .row-children > li[data-fold] > details > summary:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
489492 .row-children > li { border-top: 1px solid var(--border); }
490493 @media (max-width: 719px) { .row-children { margin-left: 12px; } }
491494 /* A bare tree (/family, docs/design/areas/family.md): names and a line each; indentation is the only structure. */
test/family-collapse.test.ts added +78
@@ -0,0 +1,78 @@
1 /** A fork-tree branch with more than five children folds behind a plain details (#13541). */
2 import { describe, expect, test } from "bun:test";
3 import { Window, type HTMLDetailsElement, type HTMLElement } from "happy-dom";
4 import { familyTreeJs } from "../src/web/pages/family_tree_js.ts";
5 import { treeRow, type Node } from "../src/web/pages/family.ts";
6
7 const kid = (i: number, here = false): Node => ({
8 label: `kid${i}`, href: `https://k${i}.example.test`, meta: [], badge: null, here, children: [],
9 });
10 const parent = (kids: Node[]): Node => ({ label: "p", href: null, meta: [], badge: null, children: kids });
11 const out = (n: Node) => String(treeRow(n, 0));
12
13 describe("fork collapse", () => {
14 test("six children fold behind a summary saying how many", () => {
15 const h = out(parent([1, 2, 3, 4, 5, 6].map((i) => kid(i))));
16 expect(h).toContain(">6 forks</summary>");
17 expect(h).toContain('<summary role="treeitem" aria-level="2" aria-expanded="false">');
18 expect(h).toMatch(/<details>/);
19 expect(h).not.toMatch(/<details open/);
20 });
21 test("links stay in the markup, and no script is added", () => {
22 const h = out(parent([1, 2, 3, 4, 5, 6].map((i) => kid(i))));
23 for (let i = 1; i <= 6; i++) expect(h).toContain(`href="https://k${i}.example.test"`);
24 expect(h).not.toContain("<script");
25 });
26 test("five children do not fold", () => {
27 expect(out(parent([1, 2, 3, 4, 5].map((i) => kid(i))))).not.toContain("<details");
28 });
29 test("the branch holding the viewed fork opens", () => {
30 const h = out(parent([1, 2, 3, 4, 5].map((i) => kid(i)).concat(kid(6, true))));
31 expect(h).toMatch(/<details open>/);
32 });
33 });
34
35 describe("terminal door", () => {
36 test("the terminal states the same count over five", async () => {
37 const { withForkCount } = await import("../src/tui/screens/family.ts");
38 const rows: [string, string][] = [["parent", "none"], ["child a", "x"]];
39 expect(withForkCount(rows, 6)).toEqual([["parent", "none"], ["forks", "6 forks"], ["child a", "x"]]);
40 expect(withForkCount(rows, 5)).toEqual(rows);
41 });
42 });
43
44 describe("the keys with a fold", () => {
45 const boot = (n: Node) => {
46 const w = new Window();
47 w.document.body.innerHTML = `<ul data-tree role="tree"><li role="none">${out(n)}</li></ul>`;
48 (w as unknown as { eval(s: string): void }).eval(familyTreeJs);
49 const tree = w.document.querySelector("[data-tree]")!;
50 const press = (el: HTMLElement, key: string) => el.dispatchEvent(new w.KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
51 return { w, tree, press, items: () => [...tree.querySelectorAll("[role=treeitem]")] as HTMLElement[] };
52 };
53 const six = parent([1, 2, 3, 4, 5, 6].map((i) => kid(i)));
54
55 test("Down from the branch lands on the fold's summary, never on a row inside the closed fold", () => {
56 const { w, press, items } = boot(six);
57 const [root, summary, k1] = items() as [HTMLElement, HTMLElement, HTMLElement];
58 root.focus();
59 press(root, "ArrowDown");
60 expect(w.document.activeElement).toBe(summary);
61 press(summary, "ArrowDown");
62 expect(w.document.activeElement).not.toBe(k1);
63 expect(w.document.activeElement).toBe(summary);
64 });
65 test("Right opens the fold and keeps aria-expanded true to it; Down then enters; Left closes", () => {
66 const { w, press, items } = boot(six);
67 const [, summary, k1] = items() as [HTMLElement, HTMLElement, HTMLElement];
68 summary.focus();
69 press(summary, "ArrowRight");
70 expect((summary.parentElement as HTMLDetailsElement).open).toBe(true);
71 expect(summary.getAttribute("aria-expanded")).toBe("true");
72 press(summary, "ArrowDown");
73 expect(w.document.activeElement).toBe(k1);
74 press(summary, "ArrowLeft");
75 expect((summary.parentElement as HTMLDetailsElement).open).toBe(false);
76 expect(summary.getAttribute("aria-expanded")).toBe("false");
77 });
78 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs