docs.ts
typescript
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