gabriel / musehub public
docs.ts typescript
167 lines 6.4 KB
Raw
sha256:597ccb67ee85981be2facd62d44c72e3484f2323c8ca876ca388d498e0c2a5a9 Merge task/243-docs-concept-map (#243 V1 concept map) into dev Opus 5.5 patch 10 days ago
1 /**
2 * docs.ts — scroll-spy sidebar for all Muse developer docs pages.
3 *
4 * Observes .devdocs-section[id] elements and marks the matching
5 * .devdocs-nav-link--sub link active as sections scroll into view.
6 *
7 * Registered for every docs-* page key in app.ts.
8 */
9
10 function initScrollSpy(): void {
11 const links = document.querySelectorAll<Element>('.devdocs-nav-link--sub');
12 if (!links.length) return;
13 const observer = new IntersectionObserver(
14 (entries) => {
15 entries.forEach((e) => {
16 if (e.isIntersecting) {
17 links.forEach((l) => l.classList.remove('devdocs-nav-link--active'));
18 const target = document.querySelector(
19 `.devdocs-nav-link--sub[href="#${e.target.id}"]`
20 );
21 if (target) target.classList.add('devdocs-nav-link--active');
22 }
23 });
24 },
25 { rootMargin: '-20% 0px -70% 0px' }
26 );
27 document.querySelectorAll('.devdocs-section[id]').forEach((s) => observer.observe(s));
28 }
29
30 /**
31 * Concept map on /muse (musehub#243): trace a concept's relations on hover/focus.
32 *
33 * The server-rendered map is complete without this: every concept is a link and its
34 * relations are listed as text. This adds highlighting of the concept's neighbours
35 * and, when the map is laid out in columns, connector lines between them.
36 */
37 const SVG_NS = 'http://www.w3.org/2000/svg';
38
39 function initConceptMap(): void {
40 const map = document.querySelector<HTMLElement>('.cmap');
41 const board = map?.querySelector<HTMLElement>('.cmap-board');
42 const wires = map?.querySelector<SVGSVGElement>('.cmap-wires');
43 if (!map || !board || !wires) return;
44
45 const nodes = new Map<string, HTMLElement>();
46 map.querySelectorAll<HTMLElement>('.cmap-node[data-node]').forEach((n) => {
47 if (n.dataset.node) nodes.set(n.dataset.node, n);
48 });
49 const neighbours = new Map<string, Set<string>>();
50 const link = (a: string, b: string): void => {
51 if (!neighbours.has(a)) neighbours.set(a, new Set());
52 neighbours.get(a)?.add(b);
53 };
54 nodes.forEach((n, key) => {
55 (n.dataset.uses ?? '').split(' ').filter((t) => nodes.has(t)).forEach((t) => {
56 link(key, t);
57 link(t, key);
58 });
59 });
60
61 const columns = window.matchMedia('(min-width: 961px)');
62 let active: string | null = null;
63
64 const clear = (): void => {
65 active = null;
66 map.classList.remove('cmap--tracing');
67 map.querySelectorAll('.cmap-item--active, .cmap-item--related').forEach((el) =>
68 el.classList.remove('cmap-item--active', 'cmap-item--related'),
69 );
70 wires.replaceChildren();
71 };
72
73 // getBoundingClientRect() reports zoomed (on-screen) pixels, but the SVG's user units are
74 // the board's unzoomed CSS pixels: MuseHub sets `body { zoom: var(--zoom-factor) }` (1.25
75 // on desktop). Measure the ratio from the board itself, so this holds at any zoom, and
76 // convert every rect into board-local units before doing any geometry.
77 type Box = { left: number; right: number; cx: number; cy: number };
78 const ratio = (screen: number, layout: number): number => {
79 const r = screen / layout;
80 return Number.isFinite(r) && r > 0 ? r : 1;
81 };
82 const toBoard = (r: DOMRect, o: DOMRect, sx: number, sy: number): Box => {
83 const left = (r.left - o.left) / sx;
84 const right = (r.right - o.left) / sx;
85 return { left, right, cx: (left + right) / 2, cy: (r.top + r.height / 2 - o.top) / sy };
86 };
87
88 // Wires run between node edges (through the gutters), not centre to centre, so they
89 // never cross the active node's own text. Same-column neighbours get a bracket.
90 // All lengths below are board-local CSS pixels.
91 const SAME_COLUMN = 40;
92 const BRACKET = 28;
93 const MIN_BEND = 24;
94
95 const draw = (key: string, related: Set<string>): void => {
96 const from = nodes.get(key);
97 if (!from || !columns.matches || board.offsetWidth <= 0 || board.offsetHeight <= 0) return;
98 const origin = board.getBoundingClientRect();
99 const sx = ratio(origin.width, board.offsetWidth);
100 const sy = ratio(origin.height, board.offsetHeight);
101 const a = toBoard(from.getBoundingClientRect(), origin, sx, sy);
102 related.forEach((other) => {
103 const to = nodes.get(other);
104 if (!to) return;
105 const b = toBoard(to.getBoundingClientRect(), origin, sx, sy);
106 let d: string;
107 if (Math.abs(a.cx - b.cx) < SAME_COLUMN) {
108 d = `M${a.left},${a.cy} C${a.left - BRACKET},${a.cy} ${b.left - BRACKET},${b.cy} ${b.left},${b.cy}`;
109 } else {
110 const right = b.cx > a.cx;
111 const x1 = right ? a.right : a.left;
112 const x2 = right ? b.left : b.right;
113 const bend = (right ? 1 : -1) * Math.max(MIN_BEND, Math.abs(x2 - x1) / 2);
114 d = `M${x1},${a.cy} C${x1 + bend},${a.cy} ${x2 - bend},${b.cy} ${x2},${b.cy}`;
115 }
116 const path = document.createElementNS(SVG_NS, 'path');
117 path.setAttribute('class', 'cmap-wire');
118 path.setAttribute('d', d);
119 wires.appendChild(path);
120 });
121 };
122
123 const activate = (key: string | undefined): void => {
124 if (!key || key === active) return;
125 clear();
126 active = key;
127 const related = neighbours.get(key) ?? new Set<string>();
128 map.classList.add('cmap--tracing');
129 nodes.get(key)?.closest('.cmap-item')?.classList.add('cmap-item--active');
130 related.forEach((r) => nodes.get(r)?.closest('.cmap-item')?.classList.add('cmap-item--related'));
131 draw(key, related);
132 };
133
134 const nodeOf = (target: EventTarget | null): HTMLElement | null =>
135 target instanceof Element
136 ? target.closest<HTMLElement>('.cmap-item')?.querySelector<HTMLElement>('.cmap-node') ?? null
137 : null;
138
139 map.addEventListener('pointerover', (e) => activate(nodeOf(e.target)?.dataset.node));
140 map.addEventListener('pointerleave', () => {
141 if (!map.contains(document.activeElement)) clear();
142 });
143 map.addEventListener('focusin', (e) => activate(nodeOf(e.target)?.dataset.node));
144 map.addEventListener('focusout', (e) => {
145 if (!(e.relatedTarget instanceof Node && map.contains(e.relatedTarget))) clear();
146 });
147 map.addEventListener('keydown', (e) => {
148 if (e.key === 'Escape') clear();
149 });
150 columns.addEventListener('change', clear);
151 // Redraw after layout settles: geometry read inside the resize event can be transient.
152 let pending = 0;
153 window.addEventListener('resize', () => {
154 cancelAnimationFrame(pending);
155 pending = requestAnimationFrame(() => {
156 if (!active) return;
157 const key = active;
158 active = null;
159 activate(key);
160 });
161 });
162 }
163
164 export function initDocs(): void {
165 initScrollSpy();
166 initConceptMap();
167 }
File History 3 commits
sha256:597ccb67ee85981be2facd62d44c72e3484f2323c8ca876ca388d498e0c2a5a9 Merge task/243-docs-concept-map (#243 V1 concept map) into dev Opus 5.5 patch 10 days ago
sha256:13b886ba1f92343d568cf8cdf74846810609fc4c244e6edacee8451e1f15d22d docs(landing): interactive architecture concept map on /mus… Opus 5.5 patch 10 days ago
sha256:d8e22751d67fbf8fc2b7f457582e7447a54ea5732d91a52cb68e32779ef5becf feat(ui): icon standardisation, inline script removal, bran… Sonnet 4.6 minor ⚠ 194 days ago