@intentius/behold 0.29.40 → 0.29.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +180 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +16121 -13141
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +294 -0
  10. package/web/carve-narration.test.js +48 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/event-help-modal.js +1 -1
  34. package/web/index.html +215 -121
  35. package/web/kiosk-carve.js +225 -0
  36. package/web/kiosk-carve.test.js +26 -0
  37. package/web/kiosk-event-help-ui.js +7 -1
  38. package/web/kiosk-link.js +68 -0
  39. package/web/kiosk-link.test.js +69 -0
  40. package/web/kiosk-metrics.js +2 -2
  41. package/web/kiosk-trace.js +1 -1
  42. package/web/kiosk.html +186 -135
  43. package/web/kiosk.js +65 -7
  44. package/web/motion.js +42 -0
  45. package/web/motion.test.js +64 -0
  46. package/web/operator.js +1 -1
  47. package/web/run-playhead.js +102 -19
  48. package/web/run-playhead.test.js +81 -11
  49. package/web/terralith.html +2 -2
  50. package/web/theme.js +99 -26
  51. package/web/theme.test.js +70 -6
  52. package/web/tooltip.js +212 -0
  53. package/web/tooltip.test.js +193 -0
  54. package/web/tour-player.js +204 -0
  55. package/web/tour-player.test.js +115 -0
  56. package/web/tours/behold.tour.v1.schema.json +182 -0
  57. package/web/tours/terralith.json +330 -0
  58. package/web/trunk-lane.js +406 -0
  59. package/web/trunk-lane.test.js +224 -0
  60. package/web/workspace-gates.js +29 -4
  61. package/web/workspace-gates.test.js +23 -2
package/web/theme.js CHANGED
@@ -148,10 +148,23 @@ function pushForContrast(hex, against, floor, dark) {
148
148
  // actual message, so everything around them gives up chroma to let them land.
149
149
  // Every one of them is still DERIVED: no chrome constant is a fixed colour, and
150
150
  // all 552 palettes have to come out of here legible.
151
+ /** behold#725: the least contrast --muted and --muted-ink keep on the grounds they sit on (WCAG AA). */
152
+ export const MUTED_FLOOR = 4.5;
153
+ /** behold#725: the least contrast --ink2, the secondary prose ink, keeps on every ground (WCAG AAA). */
154
+ export const INK2_FLOOR = 7;
155
+ /** behold#725: how far --ink2 starts from --fg toward --bg before the floor holds it. */
156
+ export const INK2_EASE = 0.22;
157
+
151
158
  export function tokensFor(th) {
152
159
  const fgMix = (t) => mix(th.bg, th.fg, t);
153
160
  const P = th.palette;
154
161
  const panel = fgMix(0.09);
162
+ const kiosk = kioskSurfaces(th);
163
+ // The recessed ground (see `well` below), computed first so --ink2 can be held on it.
164
+ const well = (() => {
165
+ const b = hexToOklch(th.bg);
166
+ return oklchToHex({ ...b, L: clamp(b.L + (b.L < 0.16 ? 0.06 : -0.06), 0, 1) });
167
+ })();
155
168
  // The active-control fill (tab strip, the picked option) — the panel pulled
156
169
  // toward the accent, then pushed AWAY from the panel's own lightness so the
157
170
  // fill is visible even on a palette whose blue slot happens to sit exactly at
@@ -173,8 +186,9 @@ export function tokensFor(th) {
173
186
  // #240: secondary text needs an actual floor, not just "quieter than
174
187
  // fg" — a handful of low-range palettes (Darkermatrix and friends) mix
175
188
  // fg/panel close enough that the quieted 0.5 mix reads at ~1.25:1.
176
- // Push its OKLCH L away from --panel's until it clears 3:1.
177
- muted: pushForContrast(desaturate(fgMix(0.5), 0.75), panel, 3, th.dark),
189
+ // Push its OKLCH L away from --panel's until it clears MUTED_FLOOR
190
+ // (behold#725: 4.5:1, WCAG AA for body text; it was 3:1).
191
+ muted: pushForContrast(desaturate(fgMix(0.5), 0.75), panel, MUTED_FLOOR, th.dark),
178
192
  edge: fgMix(0.32),
179
193
  // The structural border — the panel shell, the pane edge, the footer rule.
180
194
  // Tinted by the palette's OWN bright-black slot instead of being one more
@@ -190,10 +204,7 @@ export function tokensFor(th) {
190
204
  // off the background (down, or UP on the near-black palettes where there is
191
205
  // no "darker" left), keeping the bg's own hue so it never reads as a patch
192
206
  // of a different theme.
193
- well: (() => {
194
- const b = hexToOklch(th.bg);
195
- return oklchToHex({ ...b, L: clamp(b.L + (b.L < 0.16 ? 0.06 : -0.06), 0, 1) });
196
- })(),
207
+ well,
197
208
  // Shadow/scrim base, used through color-mix() at the call site — a light
198
209
  // theme's drop shadow must not be the same slab of black a dark one wants.
199
210
  shadow: mix(th.bg, "#000000", th.dark ? 0.85 : 0.6),
@@ -211,10 +222,37 @@ export function tokensFor(th) {
211
222
  // pending change).
212
223
  runtime: th.palette[6], // cyan — runtime child (expected, not drift)
213
224
  cat: [1, 2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14].map((i) => th.palette[i]),
214
- ...kioskSurfaces(th),
225
+ ...kiosk,
226
+ ink2: ink2For(th, ink2Grounds(th, { panel, well, kiosk })),
215
227
  };
216
228
  }
217
229
 
230
+ /**
231
+ * behold#725: every ground --ink2 is read on: the page, the app's panel and
232
+ * well, the kiosk's surfaces, and each of those under the zebra tint.
233
+ */
234
+ export function ink2Grounds(th, { panel, well, kiosk }) {
235
+ const plain = [th.bg, panel, well, kiosk.surfaceBox, kiosk.surfacePaneA, kiosk.surfacePaneB];
236
+ return [...plain, ...plain.map((g) => mix(g, th.fg, ZEBRA))];
237
+ }
238
+
239
+ /**
240
+ * behold#725: the secondary prose ink. Sentences that sit under a heading or
241
+ * beside a value read in it, where --muted stays for keys and captions. It is
242
+ * --fg eased INK2_EASE of the way toward --bg, then pushed back until it
243
+ * clears INK2_FLOOR on every ground. Where --fg itself sits under the floor
244
+ * (a low-contrast palette), the push goes past --fg, as far as the gamut
245
+ * allows.
246
+ */
247
+ function ink2For(th, grounds) {
248
+ const up = hexToOklch(th.fg).L >= hexToOklch(th.bg).L;
249
+ const pushed = pushAll(mix(th.fg, th.bg, INK2_EASE), grounds, INK2_FLOOR, up);
250
+ if (worstOn(pushed, grounds) >= INK2_FLOOR) return pushed;
251
+ // A mid-tone palette (Grass, Hot Dog Stand and nine others) where not even
252
+ // white or black reaches the floor on every ground: the best of the three.
253
+ return [pushed, "#ffffff", "#000000"].reduce((a, b) => (worstOn(b, grounds) > worstOn(a, grounds) + 0.01 ? b : a));
254
+ }
255
+
218
256
  // --- the kiosk's surfaces (behold#571) -------------------------------------
219
257
  // The kiosk lays several panes side by side; on one flat near-black they run
220
258
  // together. Each region gets its own calm level instead: the page, a step up
@@ -230,6 +268,12 @@ export const SURFACE_STEPS = { box: 0.03, paneA: 0.055, paneB: 0.08 };
230
268
  export const SOFT_CEILING = 13;
231
269
  /** The least OKLCH lightness between two neighbouring levels, so each reads as its own box. */
232
270
  export const MIN_STEP = 0.02;
271
+ /**
272
+ * behold#725: the share of --bg's OKLCH chroma the derived surfaces keep. A
273
+ * saturated ground (a deep blue or red) stacked three steps high reads loud;
274
+ * the surfaces keep its hue at under half its colour. --bg itself is left alone.
275
+ */
276
+ export const SURFACE_CHROMA = 0.4;
233
277
 
234
278
  /** The root dots' hues, by theme (behold#571): violet, orange, orchid, silver, tan. Never a state's. */
235
279
  export const ROOT_HUES = {
@@ -255,7 +299,8 @@ function pushAll(hex, against, floor, dark) {
255
299
  * on a light one; the other way where the palette leaves no room), `zebra`
256
300
  * (the tint list rows alternate with), `soft` (body ink: --fg, eased toward
257
301
  * --bg where it would glare, and never under 4.5:1 on any surface or zebra
258
- * row), `mutedInk` (secondary ink, 3:1 on all of them), each state colour's
302
+ * row), `mutedInk` (keys and captions, MUTED_FLOOR on all of them; behold#725
303
+ * raised it from 3:1), each state colour's
259
304
  * `*Ink` (3:1 on all of them) and `roots` (the root dots, 3:1 on all of them).
260
305
  */
261
306
  export function kioskSurfaces(th) {
@@ -275,13 +320,14 @@ export function kioskSurfaces(th) {
275
320
  // Each level at least MIN_STEP of OKLCH lightness past the one before, as the
276
321
  // colour rounds to 8 bits (near black, small steps all round to #000000).
277
322
  const levels = [];
323
+ const ground = { ...b, C: b.C * SURFACE_CHROMA };
278
324
  let prev = b.L;
279
325
  for (const dl of [SURFACE_STEPS.box, SURFACE_STEPS.paneA - SURFACE_STEPS.box, SURFACE_STEPS.paneB - SURFACE_STEPS.paneA]) {
280
326
  let want = prev + dir * dl;
281
- let hex = oklchToHex({ ...b, L: clamp(want, 0, 1) });
327
+ let hex = oklchToHex({ ...ground, L: clamp(want, 0, 1) });
282
328
  for (let i = 0; i < 40 && Math.abs(hexToOklch(hex).L - prev) < MIN_STEP; i++) {
283
329
  want += dir * 0.005;
284
- hex = oklchToHex({ ...b, L: clamp(want, 0, 1) });
330
+ hex = oklchToHex({ ...ground, L: clamp(want, 0, 1) });
285
331
  }
286
332
  levels.push(hex);
287
333
  prev = hexToOklch(hex).L;
@@ -302,7 +348,7 @@ export function kioskSurfaces(th) {
302
348
  soft = mix(th.fg, th.bg, lo);
303
349
  }
304
350
  soft = pushAll(soft, grounds, 4.5, lightInk);
305
- const muted = pushAll(desaturate(mix(th.bg, th.fg, 0.5), 0.75), grounds, 3, lightInk);
351
+ const muted = pushAll(desaturate(mix(th.bg, th.fg, 0.5), 0.75), grounds, MUTED_FLOOR, lightInk);
306
352
  const P = th.palette;
307
353
  const ink = (c) => pushAll(c, grounds, 3, lightInk);
308
354
  const hues = th.dark ? ROOT_HUES.dark : ROOT_HUES.light;
@@ -325,7 +371,7 @@ export function kioskSurfaces(th) {
325
371
  // CSS custom properties behold's chrome (:root) reads. The pre-paint fallback
326
372
  // block in index.html mirrors these for the DEFAULT theme — smoke/ui-smoke.mjs
327
373
  // recomputes it from here and fails if the two ever drift apart.
328
- const CSS_VARS = ["bg", "panel", "line", "fg", "muted", "edge", "managed", "foreign", "pending", "degraded", "neutral", "runtime", "rule", "focus", "active", "well", "shadow"];
374
+ const CSS_VARS = ["bg", "panel", "line", "fg", "muted", "ink2", "edge", "managed", "foreign", "pending", "degraded", "neutral", "runtime", "rule", "focus", "active", "well", "shadow"];
329
375
  // behold#571: the kiosk's surfaces and ink, as --surface-box, --soft, --managed-ink and the like; the root dots as --root-0 … --root-4.
330
376
  const KIOSK_VARS = { surfaceBox: "surface-box", surfacePaneA: "surface-pane-a", surfacePaneB: "surface-pane-b", zebra: "zebra", soft: "soft", mutedInk: "muted-ink", managedInk: "managed-ink", foreignInk: "foreign-ink", pendingInk: "pending-ink", degradedInk: "degraded-ink", runtimeInk: "runtime-ink" };
331
377
 
@@ -497,24 +543,51 @@ export function getTokens() { return _tokens; }
497
543
  export function getThemeName() { return _active && _active.name; }
498
544
  export function onThemeChange(cb) { _subs.add(cb); return () => _subs.delete(cb); }
499
545
 
500
- export function applyTheme(tokens = _tokens) {
501
- if (!tokens || typeof document === "undefined") return;
502
- const root = document.documentElement;
503
- for (const k of CSS_VARS) root.style.setProperty("--" + k, tokens[k]);
504
- for (const [k, v] of Object.entries(KIOSK_VARS)) if (tokens[k]) root.style.setProperty("--" + v, tokens[k]);
505
- (tokens.roots || []).forEach((c, i) => root.style.setProperty(`--root-${i}`, c));
506
- if (_active) { const pin = pinTokensFor(_active); for (const k of PIN_VARS) root.style.setProperty("--pin-" + k, pin[k]); }
507
- // behold#571: the state colours the graph frame draws as text and lines, legible on every ground (frameInks).
508
- if (_active) {
509
- const inks = frameInks(_active);
546
+ /**
547
+ * behold#725: every custom property applyTheme sets for `tokens`, as
548
+ * { "--name": value }. One list, so the page and the pre-paint copy
549
+ * (paintFor) can't drift apart.
550
+ */
551
+ export function themeVars(tokens, th = _active) {
552
+ const vars = {};
553
+ for (const k of CSS_VARS) vars["--" + k] = tokens[k];
554
+ for (const [k, v] of Object.entries(KIOSK_VARS)) if (tokens[k]) vars["--" + v] = tokens[k];
555
+ (tokens.roots || []).forEach((c, i) => { vars[`--root-${i}`] = c; });
556
+ if (th) {
557
+ const pin = pinTokensFor(th);
558
+ for (const k of PIN_VARS) vars["--pin-" + k] = pin[k];
559
+ // behold#571: the state colours the graph frame draws as text and lines, legible on every ground (frameInks).
560
+ const inks = frameInks(th);
510
561
  for (const k of FRAME_STATES) {
511
- root.style.setProperty("--frame-" + k, inks.box[k]);
512
- root.style.setProperty("--frame-card-" + k, inks.card[k]);
562
+ vars["--frame-" + k] = inks.box[k];
563
+ vars["--frame-card-" + k] = inks.card[k];
513
564
  }
514
565
  // behold#571: the left bars' colours, shared by the app, the kiosk and the lanes strip (barInks).
515
- for (const [k, v] of Object.entries(barVars(_active))) root.style.setProperty("--" + k, v);
566
+ for (const [k, v] of Object.entries(barVars(th))) vars["--" + k] = v;
516
567
  }
517
- root.style.setProperty("color-scheme", tokens.dark ? "dark" : "light");
568
+ return vars;
569
+ }
570
+
571
+ /**
572
+ * behold#725: where applyTheme keeps the last theme it painted, for the
573
+ * inline script at the top of index.html and kiosk.html. theme.js is a module
574
+ * and runs after the first frame, so a viewer's own theme would open on the
575
+ * page's default for a moment. That script reads this record first and
576
+ * applies it when it belongs to the stored theme.
577
+ */
578
+ export const PAINT_KEY = "behold.theme.paint";
579
+ /** The record applyTheme keeps under PAINT_KEY. */
580
+ export function paintFor(tokens, th = _active) {
581
+ return { name: th ? th.name : null, scheme: tokens.dark ? "dark" : "light", vars: themeVars(tokens, th) };
582
+ }
583
+
584
+ export function applyTheme(tokens = _tokens) {
585
+ if (!tokens || typeof document === "undefined") return;
586
+ const root = document.documentElement;
587
+ const paint = paintFor(tokens, _active);
588
+ for (const [k, v] of Object.entries(paint.vars)) root.style.setProperty(k, v);
589
+ root.style.setProperty("color-scheme", paint.scheme);
590
+ try { localStorage.setItem(PAINT_KEY, JSON.stringify(paint)); } catch { /* private mode or a full store: the next load opens on the default first */ }
518
591
  }
519
592
 
520
593
  export function setTheme(nameOrObj, { persist = true } = {}) {
package/web/theme.test.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // sweeps all 552 palettes for the same assertion; this pins the exact
7
7
  // palette the issue was filed against, with no browser involved.
8
8
  import { describe, it, expect } from "vitest";
9
- import { BAR_FLOOR, BAR_STATES, FRAME_STATES, MIN_STEP, barGrounds, barInks, barVars, SOFT_CEILING, ZEBRA, contrast, desaturate, frameGrounds, frameInks, hexToOklch, mix, pinTokensFor, tokensFor } from "./theme.js";
9
+ import { BAR_FLOOR, BAR_STATES, FRAME_STATES, INK2_FLOOR, MIN_STEP, MUTED_FLOOR, SURFACE_CHROMA, barGrounds, barInks, barVars, SOFT_CEILING, ZEBRA, contrast, desaturate, frameGrounds, frameInks, hexToOklch, ink2Grounds, mix, PAINT_KEY, paintFor, pinTokensFor, tokensFor } from "./theme.js";
10
10
  import { THEMES } from "./themes.js";
11
11
 
12
12
  describe("tokensFor — the --muted contrast floor (#240)", () => {
@@ -21,16 +21,48 @@ describe("tokensFor — the --muted contrast floor (#240)", () => {
21
21
  expect(ratio).toBeLessThan(1.3);
22
22
  });
23
23
 
24
- it("clears the 3:1 floor on Darkermatrix after the push", () => {
24
+ // behold#725 raised the floor from 3:1 to 4.5:1.
25
+ it("clears the 4.5:1 floor on Darkermatrix after the push", () => {
26
+ expect(MUTED_FLOOR).toBe(4.5);
25
27
  const t = tokensFor(THEMES["Darkermatrix"]);
26
- expect(contrast(t.muted, t.panel)).toBeGreaterThanOrEqual(3);
28
+ expect(contrast(t.muted, t.panel)).toBeGreaterThanOrEqual(4.5);
27
29
  });
28
30
 
29
31
  it("holds the floor across every shipped palette, not just the one reported", () => {
32
+ const short = Object.values(THEMES).map((th) => [th.name, tokensFor(th)]).filter(([, t]) => contrast(t.muted, t.panel) < 4.5).map(([n, t]) => `${n} ${contrast(t.muted, t.panel).toFixed(2)}`);
33
+ expect(short).toEqual([]);
34
+ });
35
+ });
36
+
37
+ // behold#725: --ink2, the secondary prose ink, between --fg and --muted.
38
+ describe("tokensFor — the --ink2 level (behold#725)", () => {
39
+ const worst = (c, gs) => Math.min(...gs.map((g) => contrast(c, g)));
40
+
41
+ it("reads at 7:1 or better on every ground, or, where neither white nor black can, as well as the better of them", () => {
42
+ expect(INK2_FLOOR).toBe(7);
43
+ const bad = [];
30
44
  for (const th of Object.values(THEMES)) {
31
45
  const t = tokensFor(th);
32
- expect(contrast(t.muted, t.panel)).toBeGreaterThanOrEqual(3);
46
+ const gs = ink2Grounds(th, { panel: t.panel, well: t.well, kiosk: t });
47
+ const w = worst(t.ink2, gs);
48
+ const reach = Math.max(worst("#ffffff", gs), worst("#000000", gs));
49
+ if (w < 7 && w < reach - 0.05) bad.push(`${th.name} ${t.ink2} ${w.toFixed(2)} (white or black reach ${reach.toFixed(2)})`);
33
50
  }
51
+ expect(bad).toEqual([]);
52
+ });
53
+
54
+ it("sits between --muted and --fg on Catppuccin Mocha, quieter than --fg and louder than --muted", () => {
55
+ const t = tokensFor(THEMES["Catppuccin Mocha"]);
56
+ expect(t.ink2).not.toBe(t.fg);
57
+ expect(contrast(t.ink2, t.panel)).toBeLessThan(contrast(t.fg, t.panel));
58
+ expect(contrast(t.ink2, t.panel)).toBeGreaterThan(contrast(t.muted, t.panel));
59
+ });
60
+
61
+ it("is held on the page, the app's panel and well, the kiosk's surfaces and their zebra rows", () => {
62
+ const th = THEMES["Sea Shells"];
63
+ const t = tokensFor(th);
64
+ const gs = ink2Grounds(th, { panel: t.panel, well: t.well, kiosk: t });
65
+ for (const g of [th.bg, t.panel, t.well, t.surfaceBox, t.surfacePaneA, t.surfacePaneB, mix(t.surfacePaneB, th.fg, ZEBRA)]) expect(gs).toContain(g);
34
66
  });
35
67
  });
36
68
 
@@ -55,8 +87,21 @@ describe("tokensFor — the kiosk's surfaces (behold#571)", () => {
55
87
  expect(each((t, _th, { grounds }) => grounds.filter((g) => contrast(t.soft, g) < 4.5).map((g) => `${t.soft} on ${g} is ${contrast(t.soft, g).toFixed(2)}`)[0])).toEqual([]);
56
88
  });
57
89
 
58
- it("keeps secondary ink at 3:1 or better on every surface and zebra row", () => {
59
- expect(each((t, _th, { grounds }) => grounds.filter((g) => contrast(t.mutedInk, g) < 3).map((g) => `${t.mutedInk} on ${g} is ${contrast(t.mutedInk, g).toFixed(2)}`)[0])).toEqual([]);
90
+ // behold#725 raised the floor from 3:1 to 4.5:1.
91
+ it("keeps secondary ink at 4.5:1 or better on every surface and zebra row", () => {
92
+ expect(each((t, _th, { grounds }) => grounds.filter((g) => contrast(t.mutedInk, g) < 4.5).map((g) => `${t.mutedInk} on ${g} is ${contrast(t.mutedInk, g).toFixed(2)}`)[0])).toEqual([]);
93
+ });
94
+
95
+ // behold#725: a saturated ground stacked three levels high reads loud, so the surfaces keep under half its colour.
96
+ it("keeps at most SURFACE_CHROMA of --bg's chroma on each derived surface, and leaves --bg alone", () => {
97
+ expect(SURFACE_CHROMA).toBe(0.4);
98
+ expect(each((t, th) => {
99
+ expect(t.bg).toBe(th.bg);
100
+ const c = hexToOklch(th.bg).C;
101
+ // 8-bit rounding moves chroma a little, most of all near black.
102
+ const over = [t.surfaceBox, t.surfacePaneA, t.surfacePaneB].find((s) => hexToOklch(s).C > c * SURFACE_CHROMA + 0.012);
103
+ return over ? `${over} keeps ${hexToOklch(over).C.toFixed(3)} of ${c.toFixed(3)}` : null;
104
+ })).toEqual([]);
60
105
  });
61
106
 
62
107
  it("keeps the state colours and the root colours at 3:1 or better on every surface and zebra row", () => {
@@ -193,3 +238,22 @@ describe("the left bars (behold#571)", () => {
193
238
  expect(contrast(barInks(th).neutral, t.surfacePaneB)).toBeGreaterThanOrEqual(3);
194
239
  });
195
240
  });
241
+
242
+ // behold#725: the record the pre-paint script in index.html and kiosk.html applies before theme.js runs.
243
+ describe("paintFor — the theme before first paint (behold#725)", () => {
244
+ it("names the theme, its colour scheme and every custom property applyTheme sets, --ink2 and the bars among them", () => {
245
+ const th = THEMES["Sea Shells"];
246
+ const t = tokensFor(th);
247
+ const p = paintFor(t, th);
248
+ expect(PAINT_KEY).toBe("behold.theme.paint");
249
+ expect(p.name).toBe("Sea Shells");
250
+ expect(p.scheme).toBe(th.dark ? "dark" : "light");
251
+ expect(p.vars["--ink2"]).toBe(t.ink2);
252
+ expect(p.vars["--muted"]).toBe(t.muted);
253
+ expect(p.vars["--surface-pane-a"]).toBe(t.surfacePaneA);
254
+ expect(p.vars["--bar-neutral"]).toBe(barInks(th).neutral);
255
+ expect(p.vars["--frame-focus"]).toBe(frameInks(th).box.focus);
256
+ expect(Object.keys(p.vars).every((k) => k.startsWith("--"))).toBe(true);
257
+ expect(JSON.parse(JSON.stringify(p))).toEqual(p);
258
+ });
259
+ });
package/web/tooltip.js ADDED
@@ -0,0 +1,212 @@
1
+ // behold#725: one small tooltip for the page, in place of the browser's own
2
+ // for an SVG <title>. The browser's shows only under a resting mouse; this one
3
+ // also opens when a badge takes keyboard focus, closes on Escape, and is
4
+ // position: fixed, so a scrolling pane can't clip it. Screen readers get it
5
+ // through aria-describedby on the element it describes.
6
+ //
7
+ // The graph's marks keep their <title> elements as app.js draws them, so an
8
+ // exported SVG still carries every tooltip's words. While a mark is hovered or
9
+ // focused, its <title> is emptied (the browser then has nothing to show) and
10
+ // its words go into the shared tooltip; they go back when the pointer or the
11
+ // focus leaves. An HTML element can ask for the tooltip with data-tip.
12
+
13
+ export const TIP_ID = "b-tip";
14
+ /** The room between the tooltip and what it describes, and between it and the window's edge, in px. */
15
+ export const TIP_GAP = 8;
16
+ export const TIP_MARGIN = 8;
17
+ /** How long a pointer rests before the tooltip opens; focus opens it at once. */
18
+ export const HOVER_MS = 250;
19
+
20
+ /**
21
+ * Where the tooltip goes: centred under its target, above it when there is no
22
+ * room below, and kept inside the window's sides.
23
+ * `target` is a client rect, `size` the tooltip's, `view` the window's.
24
+ */
25
+ export function placeTip(target, size, view, { gap = TIP_GAP, margin = TIP_MARGIN } = {}) {
26
+ const below = target.bottom + gap;
27
+ const above = target.top - gap - size.height;
28
+ const fitsBelow = below + size.height <= view.height - margin;
29
+ const side = fitsBelow || above < margin ? "below" : "above";
30
+ const top = side === "below" ? below : above;
31
+ const centred = (target.left + target.right) / 2 - size.width / 2;
32
+ const left = Math.max(margin, Math.min(centred, view.width - margin - size.width));
33
+ return { left: Math.round(left), top: Math.round(Math.max(margin, top)), side };
34
+ }
35
+
36
+ /** An id list (aria-describedby) with `id` in it once. */
37
+ export function addId(list, id) {
38
+ const ids = String(list || "").split(/\s+/).filter(Boolean);
39
+ return ids.includes(id) ? ids.join(" ") : [...ids, id].join(" ");
40
+ }
41
+ /** An id list without `id`. */
42
+ export function dropId(list, id) {
43
+ return String(list || "").split(/\s+/).filter((x) => x && x !== id).join(" ");
44
+ }
45
+
46
+ const tagOf = (node) => String((node && (node.localName || node.tagName || node.nodeName)) || "").toLowerCase();
47
+
48
+ /** The <title> an SVG element carries as its own child, or null. */
49
+ export function ownTitle(node) {
50
+ for (const c of (node && node.children) || []) if (tagOf(c) === "title") return c;
51
+ return null;
52
+ }
53
+
54
+ /**
55
+ * Whether an SVG element with a <title> is a badge, a mark drawn on a card or
56
+ * a box, which the keyboard should reach. The card itself, an edge and the
57
+ * drawing as a whole are not: the card has its own click, and a tab stop on
58
+ * every edge would bury the badges.
59
+ */
60
+ export function isBadge(node) {
61
+ if (!node || !node.getAttribute) return false;
62
+ if (tagOf(node) === "svg") return false;
63
+ return !node.hasAttribute("data-node-id") && !node.hasAttribute("data-edge-from") && !node.hasAttribute("data-edge-via");
64
+ }
65
+
66
+ /**
67
+ * The element under `node` (or `node` itself) whose words a tooltip shows: the
68
+ * nearest with data-tip, or with a <title> child that has words. `current` is
69
+ * the element whose <title> is emptied while it is shown, so it still counts.
70
+ */
71
+ export function tipHost(node, current = null) {
72
+ for (let n = node; n && n.nodeType === 1; n = n.parentNode) {
73
+ if (n === current) return n;
74
+ if (n.hasAttribute && n.hasAttribute("data-tip") && n.getAttribute("data-tip")) return n;
75
+ const t = ownTitle(n);
76
+ if (t && (t.textContent || "").trim()) return n;
77
+ if (tagOf(n) === "body") break;
78
+ }
79
+ return null;
80
+ }
81
+
82
+ /** Give every badge under `root` that has a <title> a tab stop. Returns how many it gave one. */
83
+ export function reachBadges(root) {
84
+ let n = 0;
85
+ if (!root || !root.querySelectorAll) return 0;
86
+ for (const t of root.querySelectorAll("svg title")) {
87
+ const host = t.parentNode;
88
+ if (!isBadge(host) || host.hasAttribute("tabindex") || !(t.textContent || "").trim()) continue;
89
+ host.setAttribute("tabindex", "0");
90
+ n++;
91
+ }
92
+ return n;
93
+ }
94
+
95
+ /**
96
+ * Wire the tooltip into `doc`. `scope` names the part of the page whose SVG
97
+ * badges get tab stops as they are drawn. A kiosk frame (the root's .bare) has
98
+ * its own popover and nothing to focus, so it gets neither.
99
+ */
100
+ export function installTooltips(doc = typeof document !== "undefined" ? document : null, { scope = "#graph", setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
101
+ if (!doc || !doc.documentElement || !doc.body) return () => {};
102
+ const off = () => doc.documentElement.classList && doc.documentElement.classList.contains("bare");
103
+ const win = doc.defaultView || (typeof window !== "undefined" ? window : null);
104
+ let tip = null;
105
+ let current = null; // { host, title, text, timer }
106
+
107
+ const ensureTip = () => {
108
+ if (tip) return tip;
109
+ tip = doc.getElementById(TIP_ID) || doc.createElement("div");
110
+ tip.id = TIP_ID;
111
+ tip.setAttribute("role", "tooltip");
112
+ tip.hidden = true;
113
+ if (!tip.parentNode) doc.body.appendChild(tip);
114
+ return tip;
115
+ };
116
+ const show = () => {
117
+ if (!current) return;
118
+ const t = ensureTip();
119
+ t.textContent = current.text;
120
+ t.hidden = false;
121
+ const r = current.host.getBoundingClientRect();
122
+ const s = t.getBoundingClientRect();
123
+ const view = { width: (win && win.innerWidth) || doc.documentElement.clientWidth, height: (win && win.innerHeight) || doc.documentElement.clientHeight };
124
+ const at = placeTip(r, { width: s.width, height: s.height }, view);
125
+ t.style.left = `${at.left}px`;
126
+ t.style.top = `${at.top}px`;
127
+ t.setAttribute("data-side", at.side);
128
+ current.host.setAttribute("aria-describedby", addId(current.host.getAttribute("aria-describedby"), TIP_ID));
129
+ };
130
+ const hideBubble = () => {
131
+ if (current && current.timer) { clearTimer(current.timer); current.timer = null; }
132
+ if (tip) tip.hidden = true;
133
+ };
134
+ const leave = () => {
135
+ if (!current) return;
136
+ hideBubble();
137
+ const { host, title, text } = current;
138
+ // Put the words back, unless app.js wrote new ones while they were out.
139
+ if (title && !(title.textContent || "").trim()) title.textContent = text;
140
+ const ids = dropId(host.getAttribute("aria-describedby"), TIP_ID);
141
+ if (ids) host.setAttribute("aria-describedby", ids);
142
+ else host.removeAttribute("aria-describedby");
143
+ current = null;
144
+ };
145
+ const enter = (host, delay) => {
146
+ if (current && current.host === host) return;
147
+ leave();
148
+ const title = host.hasAttribute("data-tip") ? null : ownTitle(host);
149
+ const text = title ? (title.textContent || "").trim() : host.getAttribute("data-tip");
150
+ if (!text) return;
151
+ // Emptied now, before the browser's own tooltip can rise.
152
+ if (title) title.textContent = "";
153
+ current = { host, title, text, timer: null };
154
+ if (delay > 0) current.timer = setTimer(show, delay);
155
+ else show();
156
+ };
157
+ const inside = (outer, node) => { for (let n = node; n; n = n.parentNode) if (n === outer) return true; return false; };
158
+
159
+ const onOver = (e) => {
160
+ if (off()) return;
161
+ const host = tipHost(e.target, current && current.host);
162
+ if (host) enter(host, HOVER_MS);
163
+ else if (current && !inside(current.host, e.target)) leave();
164
+ };
165
+ const onOut = (e) => { if (current && !inside(current.host, e.relatedTarget)) leave(); };
166
+ const onFocusIn = (e) => {
167
+ if (off()) return;
168
+ const host = tipHost(e.target, current && current.host);
169
+ if (host !== e.target) return;
170
+ // A click focuses a badge too; only the keyboard's focus opens the tooltip.
171
+ try { if (host.matches && !host.matches(":focus-visible")) return; } catch { /* an engine without :focus-visible opens it */ }
172
+ enter(host, 0);
173
+ };
174
+ const onFocusOut = () => leave();
175
+ const onKey = (e) => { if (e.key === "Escape" && current) hideBubble(); };
176
+ // A pan, a zoom or a scroll moves the target out from under a fixed tooltip.
177
+ const onMove = () => hideBubble();
178
+
179
+ doc.addEventListener("pointerover", onOver);
180
+ doc.addEventListener("pointerout", onOut);
181
+ doc.addEventListener("focusin", onFocusIn);
182
+ doc.addEventListener("focusout", onFocusOut);
183
+ doc.addEventListener("keydown", onKey);
184
+ doc.addEventListener("pointerdown", onMove, true);
185
+ doc.addEventListener("wheel", onMove, { capture: true, passive: true });
186
+ doc.addEventListener("scroll", onMove, true);
187
+
188
+ // Tab stops for the badges, as each frame is drawn.
189
+ let observer = null;
190
+ const area = doc.querySelector(scope);
191
+ const MO = win && win.MutationObserver;
192
+ if (area && MO) {
193
+ let queued = false;
194
+ const pass = () => { queued = false; if (!off()) reachBadges(area); };
195
+ observer = new MO(() => { if (!queued) { queued = true; Promise.resolve().then(pass); } });
196
+ observer.observe(area, { childList: true, subtree: true });
197
+ pass();
198
+ }
199
+
200
+ return () => {
201
+ leave();
202
+ if (observer) observer.disconnect();
203
+ doc.removeEventListener("pointerover", onOver);
204
+ doc.removeEventListener("pointerout", onOut);
205
+ doc.removeEventListener("focusin", onFocusIn);
206
+ doc.removeEventListener("focusout", onFocusOut);
207
+ doc.removeEventListener("keydown", onKey);
208
+ doc.removeEventListener("pointerdown", onMove, true);
209
+ doc.removeEventListener("wheel", onMove, { capture: true });
210
+ doc.removeEventListener("scroll", onMove, true);
211
+ };
212
+ }