squiffy-runtime 6.0.1 → 7.0.0-beta.11

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 (117) hide show
  1. package/dist/assets.d.ts +3 -0
  2. package/dist/assets.test.d.ts +1 -0
  3. package/dist/classes.test.d.ts +1 -0
  4. package/dist/confirmDialog.d.ts +8 -0
  5. package/dist/events.d.ts +16 -0
  6. package/dist/every.d.ts +12 -0
  7. package/dist/every.test.d.ts +1 -0
  8. package/dist/helpers.test.d.ts +1 -0
  9. package/dist/numbers.d.ts +3 -0
  10. package/dist/panels.d.ts +14 -0
  11. package/dist/panels.test.d.ts +1 -0
  12. package/dist/paths.d.ts +15 -0
  13. package/dist/paths.test.d.ts +1 -0
  14. package/dist/persistent.test.d.ts +1 -0
  15. package/dist/playerSettings.d.ts +17 -0
  16. package/dist/pluginManager.d.ts +2 -1
  17. package/dist/preview-host.d.ts +33 -0
  18. package/dist/preview-host.js +125 -0
  19. package/dist/preview-host.js.map +7 -0
  20. package/dist/preview-host.test.d.ts +1 -0
  21. package/dist/preview-html.d.ts +2 -0
  22. package/dist/preview-html.js +2 -0
  23. package/dist/preview-protocol.d.ts +69 -0
  24. package/dist/preview.d.ts +15 -0
  25. package/dist/preview.main.d.ts +1 -0
  26. package/dist/preview.test.d.ts +1 -0
  27. package/dist/saveSlots.d.ts +16 -0
  28. package/dist/saves.test.d.ts +1 -0
  29. package/dist/savesDialog.d.ts +43 -0
  30. package/dist/savesDialog.test.d.ts +1 -0
  31. package/dist/scripts.test.d.ts +1 -0
  32. package/dist/settings.test.d.ts +1 -0
  33. package/dist/settingsDialog.d.ts +17 -0
  34. package/dist/skill.test.d.ts +1 -0
  35. package/dist/sound.d.ts +35 -0
  36. package/dist/sound.test.d.ts +1 -0
  37. package/dist/squiffy.page.css +155 -0
  38. package/dist/squiffy.preview.html +1631 -0
  39. package/dist/squiffy.runtime.css +1123 -20
  40. package/dist/squiffy.runtime.d.ts +13 -1
  41. package/dist/squiffy.runtime.global.js +146 -76
  42. package/dist/squiffy.runtime.global.js.map +1 -1
  43. package/dist/squiffy.runtime.js +7105 -4681
  44. package/dist/squiffy.runtime.js.map +1 -1
  45. package/dist/state.d.ts +17 -0
  46. package/dist/storyLists.d.ts +4 -0
  47. package/dist/storyLists.test.d.ts +1 -0
  48. package/dist/style.test.d.ts +1 -0
  49. package/dist/textProcessor.d.ts +27 -0
  50. package/dist/transitions.test.d.ts +1 -0
  51. package/dist/types.d.ts +137 -1
  52. package/dist/types.plugins.d.ts +2 -0
  53. package/dist/uiLinks.test.d.ts +1 -0
  54. package/dist/utils.d.ts +2 -1
  55. package/dist/utils.test.d.ts +1 -0
  56. package/package.json +25 -11
  57. package/src/__snapshots__/squiffy.runtime.test.ts.snap +22 -22
  58. package/src/animation.test.ts +44 -0
  59. package/src/animation.ts +9 -5
  60. package/src/assets.test.ts +225 -0
  61. package/src/assets.ts +92 -0
  62. package/src/classes.test.ts +201 -0
  63. package/src/confirmDialog.ts +66 -0
  64. package/src/events.ts +20 -0
  65. package/src/every.test.ts +25 -0
  66. package/src/every.ts +94 -0
  67. package/src/helpers.test.ts +34 -0
  68. package/src/numbers.ts +21 -0
  69. package/src/panels.test.ts +225 -0
  70. package/src/panels.ts +187 -0
  71. package/src/paths.test.ts +66 -0
  72. package/src/paths.ts +155 -0
  73. package/src/persistent.test.ts +155 -0
  74. package/src/playerSettings.ts +128 -0
  75. package/src/pluginManager.ts +6 -1
  76. package/src/plugins/animate.ts +34 -9
  77. package/src/plugins/live.ts +18 -5
  78. package/src/plugins/plugins.test.ts +93 -6
  79. package/src/plugins/replaceLabel.ts +7 -3
  80. package/src/preview-host.test.ts +171 -0
  81. package/src/preview-host.ts +190 -0
  82. package/src/preview-protocol.ts +79 -0
  83. package/src/preview.main.ts +34 -0
  84. package/src/preview.test.ts +367 -0
  85. package/src/preview.ts +331 -0
  86. package/src/saveSlots.ts +159 -0
  87. package/src/saves.test.ts +199 -0
  88. package/src/savesDialog.test.ts +290 -0
  89. package/src/savesDialog.ts +499 -0
  90. package/src/scripts.test.ts +130 -0
  91. package/src/settings.test.ts +233 -0
  92. package/src/settingsDialog.ts +160 -0
  93. package/src/skill.test.ts +67 -0
  94. package/src/sound.test.ts +273 -0
  95. package/src/sound.ts +207 -0
  96. package/src/squiffy.page.css +155 -0
  97. package/src/squiffy.runtime.css +1123 -20
  98. package/src/squiffy.runtime.test.ts +2806 -44
  99. package/src/squiffy.runtime.ts +1130 -64
  100. package/src/state.ts +172 -11
  101. package/src/storyLists.test.ts +134 -0
  102. package/src/storyLists.ts +57 -0
  103. package/src/style.test.ts +89 -0
  104. package/src/textProcessor.ts +739 -58
  105. package/src/transitions.test.ts +343 -0
  106. package/src/types.plugins.ts +7 -0
  107. package/src/types.ts +226 -2
  108. package/src/uiLinks.test.ts +156 -0
  109. package/src/updater.ts +26 -8
  110. package/src/utils.test.ts +60 -0
  111. package/src/utils.ts +46 -14
  112. package/vite.config.ts +3 -4
  113. package/vite.preview.config.ts +83 -0
  114. package/dist/infixExpressions.d.ts +0 -2
  115. package/src/infixExpressions.test.ts +0 -187
  116. package/src/infixExpressions.ts +0 -323
  117. /package/dist/{infixExpressions.test.d.ts → animation.test.d.ts} +0 -0
@@ -0,0 +1,233 @@
1
+ import { expect, test, beforeEach, afterEach } from "vitest";
2
+ import globalJsdom from "global-jsdom";
3
+ import { init } from "./squiffy.runtime.js";
4
+ import { compile as squiffyCompile } from "squiffy-compiler";
5
+ import { createSettingsDialog } from "./settingsDialog.js";
6
+ import type { PlayerSetting, SquiffyInitOptions } from "./types.js";
7
+
8
+ // Player settings (#452): squiffy.json's "settings", which the story reads as settings.name
9
+
10
+ let cleanup: () => void;
11
+
12
+ beforeEach(() => {
13
+ cleanup = globalJsdom("<!DOCTYPE html><html><body><div id=\"squiffy\"></div></body></html>");
14
+ // jsdom has no showModal()
15
+ window.HTMLDialogElement.prototype.showModal = function () { this.setAttribute("open", ""); };
16
+ window.HTMLDialogElement.prototype.close = function () {
17
+ this.removeAttribute("open");
18
+ this.dispatchEvent(new window.Event("close"));
19
+ };
20
+ });
21
+
22
+ afterEach(() => {
23
+ localStorage.clear();
24
+ cleanup();
25
+ });
26
+
27
+ const SETTINGS: PlayerSetting[] = [
28
+ { name: "warnings", label: "Content warnings", type: "toggle", default: true, description: "Before scenes some may find upsetting" },
29
+ { name: "textSize", label: "Text size", type: "list", options: [
30
+ { value: "small", label: "Small" }, { value: "medium", label: "Medium" }, { value: "large", label: "Large" },
31
+ ], default: "medium" },
32
+ { name: "speed", label: "Speed", type: "range", min: 1, max: 5, step: 1, default: 3 },
33
+ ];
34
+
35
+ const script = `[[start]]:
36
+ @set score = 1
37
+ {{#if settings.warnings}}Warning!{{/if}} Size {{settings.textSize}}, speed {{settings.speed}}.
38
+ {{#if settings.textSize == "large"}}Big.{{/if}}
39
+ Live: {{live "settings.speed"}}
40
+ {{settings}} {{settings text="Options"}} [[Next]](end)
41
+
42
+ [[end]]:
43
+ @set score = 2
44
+ The end.`;
45
+
46
+ const start = async (options: Partial<SquiffyInitOptions> = {}, settings: PlayerSetting[] | undefined = SETTINGS) => {
47
+ const element = document.getElementById("squiffy")!;
48
+ const result = await squiffyCompile({ script, settings });
49
+ if (!result.success) throw new Error("Compile failed");
50
+ const js = result.output.js.map(lines => new Function("squiffy", "get", "set", lines.join("\n")));
51
+ const api = await init({ element, story: { js: js as any, ...result.output.story }, persist: false, scroll: "none", ...options });
52
+ await api.begin();
53
+ return { api, element };
54
+ };
55
+
56
+ const link = (element: HTMLElement, text: string) =>
57
+ [...element.querySelectorAll<HTMLElement>("a.squiffy-link")].filter(l => l.textContent === text).pop()!;
58
+
59
+ const settle = () => new Promise(resolve => setTimeout(resolve, 0));
60
+
61
+ const text = (element: HTMLElement) => element.textContent!.replace(/\s+/g, " ");
62
+
63
+ test("The story reads its settings' defaults as settings.name", async () => {
64
+ const { api, element } = await start();
65
+ expect(text(element)).toContain("Warning! Size medium, speed 3.");
66
+ expect(text(element)).not.toContain("Big.");
67
+ expect(api.get("settings")).toEqual({ warnings: true, textSize: "medium", speed: 3 });
68
+ expect(api.get("settings.textSize")).toBe("medium");
69
+ expect(api.getSettings().map(s => s.name)).toEqual(["warnings", "textSize", "speed"]);
70
+ });
71
+
72
+ test("Changed settings are read as the player left them, and only values a setting can have are taken", async () => {
73
+ const { api, element } = await start();
74
+ api.setSetting("warnings", false);
75
+ api.setSetting("textSize", "large");
76
+ api.setSetting("speed", 4.6);
77
+ expect(api.get("settings")).toEqual({ warnings: false, textSize: "large", speed: 5 });
78
+
79
+ api.setSetting("textSize", "enormous");
80
+ api.setSetting("speed", "fast" as any);
81
+ api.setSetting("nonsense", true);
82
+ expect(api.get("settings")).toEqual({ warnings: false, textSize: "large", speed: 5 });
83
+
84
+ // Text shown after the change uses it
85
+ api.restart();
86
+ await settle();
87
+ expect(text(element)).toContain("Size large, speed 5.");
88
+ expect(text(element)).toContain("Big.");
89
+ });
90
+
91
+ test("Settings put classes on the story's element, for its CSS", async () => {
92
+ const { api, element } = await start();
93
+ expect([...element.classList]).toEqual(expect.arrayContaining(["setting-warnings", "setting-textSize-medium", "setting-speed-3"]));
94
+ api.setSetting("warnings", false);
95
+ api.setSetting("textSize", "large");
96
+ expect(element.classList.contains("setting-warnings")).toBe(false);
97
+ expect(element.classList.contains("setting-textSize-medium")).toBe(false);
98
+ expect(element.classList.contains("setting-textSize-large")).toBe(true);
99
+ });
100
+
101
+ test("The story can't change a setting", async () => {
102
+ const { api } = await start();
103
+ api.set("settings.warnings", false);
104
+ api.set("settings", { warnings: false });
105
+ expect(api.getSetting("warnings")).toBe(true);
106
+ });
107
+
108
+ test("Back, Restart and saved games leave settings alone, and saved games don't include them", async () => {
109
+ const { api, element } = await start();
110
+ const save = api.getSave();
111
+ expect(save.state).not.toHaveProperty("settings");
112
+
113
+ await api.clickLink(link(element, "Next"));
114
+ api.setSetting("textSize", "small");
115
+ api.goBack();
116
+ expect(api.get("score")).toBe(1);
117
+ expect(api.getSetting("textSize")).toBe("small");
118
+
119
+ await api.loadSave(save);
120
+ expect(api.getSetting("textSize")).toBe("small");
121
+
122
+ api.restart();
123
+ await settle();
124
+ expect(api.getSetting("textSize")).toBe("small");
125
+ expect(text(element)).toContain("Size small");
126
+ });
127
+
128
+ test("Settings are kept for the story when persist is on, and Reset to defaults puts them back", async () => {
129
+ const first = await start({ persist: true, storyId: "mystory" });
130
+ first.api.setSetting("speed", 2);
131
+ first.api.dispose();
132
+ document.getElementById("squiffy")!.innerHTML = "";
133
+
134
+ const { api, element } = await start({ persist: true, storyId: "mystory" });
135
+ expect(api.getSetting("speed")).toBe(2);
136
+ expect(element.classList.contains("setting-speed-2")).toBe(true);
137
+
138
+ const changes: unknown[] = [];
139
+ api.on("settingChanged", e => changes.push(e));
140
+ api.resetSettings();
141
+ expect(api.getSetting("speed")).toBe(3);
142
+ expect(changes).toEqual([{ name: "speed", value: 3 }]);
143
+ expect(localStorage.getItem("squiffy-settings:mystory")).toBeNull();
144
+ });
145
+
146
+ test("A story without settings can have an attribute called settings", async () => {
147
+ const { api } = await start({}, []);
148
+ api.set("settings", { a: 1 });
149
+ expect(api.get("settings.a")).toBe(1);
150
+ expect(api.getSettings()).toEqual([]);
151
+ });
152
+
153
+ test("Changing a setting updates {{live}} text and raises settingChanged", async () => {
154
+ const { api } = await start();
155
+ const events: unknown[] = [];
156
+ api.on("settingChanged", e => events.push(e));
157
+ api.on("set", e => events.push(e.attribute));
158
+ api.setSetting("warnings", false);
159
+ api.setSetting("warnings", false);
160
+ expect(events).toEqual([{ name: "warnings", value: false }, "settings"]);
161
+ });
162
+
163
+ test("{{live}} shows a setting as it changes, and only fades when its own value changes", async () => {
164
+ const { api, element } = await start();
165
+ const live = element.querySelector<HTMLElement>(".squiffy-live")!;
166
+ expect(live.textContent).toBe("3");
167
+ api.setSetting("warnings", false);
168
+ expect(live.classList.contains("fade-out")).toBe(false);
169
+ api.setSetting("speed", 4);
170
+ expect(live.classList.contains("fade-out")).toBe(true);
171
+ });
172
+
173
+ const settingsDialog = () => document.querySelector<HTMLDialogElement>("dialog.squiffy-settings");
174
+
175
+ test("{{settings}} is a link that opens the runtime's own Settings dialog, if the page doesn't handle it", async () => {
176
+ const { api, element } = await start({ strings: { settings: "Réglages" } });
177
+ expect(link(element, "Réglages").classList.contains("link-settings")).toBe(true);
178
+ expect(await api.clickLink(link(element, "Options"))).toBe(true);
179
+ const dialog = settingsDialog()!;
180
+ expect(dialog.open).toBe(true);
181
+ expect(dialog.querySelector("h2")!.textContent).toBe("Réglages");
182
+ // The link can be clicked again
183
+ expect(link(element, "Options").classList.contains("disabled")).toBe(false);
184
+ });
185
+
186
+ test("{{settings}} raises settingsRequested if the page handles it", async () => {
187
+ const { api, element } = await start();
188
+ let requested = 0;
189
+ api.on("settingsRequested", () => requested++);
190
+ await api.clickLink(link(element, "Options"));
191
+ expect(requested).toBe(1);
192
+ expect(settingsDialog()).toBeNull();
193
+ });
194
+
195
+ const dialogFor = async () => {
196
+ const { api, element } = await start();
197
+ const dialog = createSettingsDialog(api);
198
+ dialog.open();
199
+ return { api, element, dialog: dialog.element };
200
+ };
201
+
202
+ test("The Settings dialog shows each setting with its value", async () => {
203
+ const { dialog } = await dialogFor();
204
+ const rows = [...dialog.querySelectorAll(".squiffy-setting")];
205
+ expect(rows.map(r => r.querySelector("label")!.textContent)).toEqual(["Content warnings", "Text size", "Speed"]);
206
+ expect(rows[0].querySelector("p")!.textContent).toBe("Before scenes some may find upsetting");
207
+ expect(rows[0].querySelector<HTMLInputElement>("input[type=checkbox]")!.checked).toBe(true);
208
+ const select = rows[1].querySelector<HTMLSelectElement>("select")!;
209
+ expect([...select.options].map(o => o.textContent)).toEqual(["Small", "Medium", "Large"]);
210
+ expect(select.value).toBe("medium");
211
+ expect(rows[2].querySelector<HTMLInputElement>("input[type=range]")!.value).toBe("3");
212
+ expect(rows[2].querySelector("output")!.textContent).toBe("3");
213
+ });
214
+
215
+ test("Changing a control in the Settings dialog changes the setting straight away", async () => {
216
+ const { api, element, dialog } = await dialogFor();
217
+ const toggle = dialog.querySelector<HTMLInputElement>("input[type=checkbox]")!;
218
+ toggle.checked = false;
219
+ toggle.dispatchEvent(new window.Event("change"));
220
+ const select = dialog.querySelector<HTMLSelectElement>("select")!;
221
+ select.value = "large";
222
+ select.dispatchEvent(new window.Event("change"));
223
+ const range = dialog.querySelector<HTMLInputElement>("input[type=range]")!;
224
+ range.value = "5";
225
+ range.dispatchEvent(new window.Event("input"));
226
+ expect(api.get("settings")).toEqual({ warnings: false, textSize: "large", speed: 5 });
227
+ expect(dialog.querySelector("output")!.textContent).toBe("5");
228
+ expect(element.classList.contains("setting-textSize-large")).toBe(true);
229
+
230
+ dialog.querySelector<HTMLButtonElement>("[data-reset]")!.click();
231
+ expect(api.get("settings")).toEqual({ warnings: true, textSize: "medium", speed: 3 });
232
+ expect(dialog.querySelector<HTMLSelectElement>("select")!.value).toBe("medium");
233
+ });
@@ -0,0 +1,160 @@
1
+ // The Settings dialog (#452): the story's player settings, from squiffy.json's "settings", which
2
+ // the player can change at any time. A toggle is a switch, a list a drop-down and a range a
3
+ // slider. Changes take effect straight away, and Reset to defaults puts them all back.
4
+
5
+ import type { PlayerSetting, SquiffyApi } from "./types.js";
6
+
7
+ // The dialog's text in English. The published page passes in squiffy.json's "strings", which
8
+ // use the same names (see PAGE_STRINGS in the compiler).
9
+ export const SETTINGS_STRINGS = {
10
+ settings: "Settings",
11
+ resetSettings: "Reset to defaults",
12
+ close: "Close",
13
+ };
14
+
15
+ type SettingsStringName = keyof typeof SETTINGS_STRINGS;
16
+
17
+ export interface SettingsDialogOptions {
18
+ // The dialog's text, for a story in another language. Anything left out is in English.
19
+ strings?: Partial<Record<string, string>>;
20
+ // Where the dialog goes in the page: the end of the body by default
21
+ container?: HTMLElement;
22
+ }
23
+
24
+ export interface SettingsDialog {
25
+ element: HTMLDialogElement;
26
+ open: () => void;
27
+ close: () => void;
28
+ }
29
+
30
+ // Lucide's settings icon (ISC licence), as on the published page's Settings button
31
+ export const SETTINGS_ICON = "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/></svg>";
32
+
33
+ const ICON_CLOSE = "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M18 6 6 18M6 6l12 12\"/></svg>";
34
+
35
+ let dialogCount = 0;
36
+
37
+ export function createSettingsDialog(api: SquiffyApi, options: SettingsDialogOptions = {}): SettingsDialog {
38
+ const strings: Record<SettingsStringName, string> = { ...SETTINGS_STRINGS };
39
+ for (const name of Object.keys(SETTINGS_STRINGS) as SettingsStringName[]) {
40
+ const value = options.strings?.[name];
41
+ if (typeof value == "string") strings[name] = value;
42
+ }
43
+ const id = `squiffy-settings-${++dialogCount}`;
44
+
45
+ const dialog = document.createElement("dialog");
46
+ dialog.className = "squiffy-settings";
47
+ dialog.setAttribute("aria-labelledby", `${id}-heading`);
48
+ dialog.innerHTML = `
49
+ <div class="squiffy-settings-header">
50
+ <h2 id="${id}-heading"></h2>
51
+ <button type="button" class="squiffy-settings-close" data-close>${ICON_CLOSE}</button>
52
+ </div>
53
+ <div class="squiffy-settings-list"></div>
54
+ <div class="squiffy-settings-footer">
55
+ <button type="button" class="squiffy-settings-reset" data-reset></button>
56
+ </div>`;
57
+ const $ = <T extends Element>(selector: string) => dialog.querySelector<T>(selector)!;
58
+ $("h2").textContent = strings.settings;
59
+ const closeButton = $<HTMLButtonElement>("[data-close]");
60
+ closeButton.title = strings.close;
61
+ closeButton.setAttribute("aria-label", strings.close);
62
+ closeButton.addEventListener("click", () => dialog.close());
63
+ const list = $<HTMLDivElement>(".squiffy-settings-list");
64
+ const reset = $<HTMLButtonElement>("[data-reset]");
65
+ reset.textContent = strings.resetSettings;
66
+ reset.addEventListener("click", () => {
67
+ api.resetSettings();
68
+ render();
69
+ });
70
+ // Clicking the backdrop closes it too
71
+ dialog.addEventListener("click", event => {
72
+ if (event.target === dialog) dialog.close();
73
+ });
74
+ (options.container ?? document.body).appendChild(dialog);
75
+
76
+ // A row for each setting, with the control showing its value now
77
+ function render() {
78
+ list.replaceChildren(...api.getSettings().map((setting, i) => row(setting, `${id}-${i}`)));
79
+ }
80
+
81
+ function row(setting: PlayerSetting, controlId: string): HTMLElement {
82
+ const div = document.createElement("div");
83
+ div.className = `squiffy-setting squiffy-setting-${setting.type}`;
84
+ const text = document.createElement("div");
85
+ text.className = "squiffy-setting-text";
86
+ const label = document.createElement("label");
87
+ label.htmlFor = controlId;
88
+ label.textContent = setting.label || setting.name;
89
+ text.appendChild(label);
90
+ if (setting.description) {
91
+ const description = document.createElement("p");
92
+ description.id = `${controlId}-description`;
93
+ description.textContent = setting.description;
94
+ text.appendChild(description);
95
+ }
96
+ div.appendChild(text);
97
+
98
+ const value = api.getSetting(setting.name);
99
+ let control: HTMLInputElement | HTMLSelectElement;
100
+ if (setting.type == "toggle") {
101
+ const input = document.createElement("input");
102
+ input.type = "checkbox";
103
+ input.setAttribute("role", "switch");
104
+ input.checked = value === true;
105
+ input.addEventListener("change", () => api.setSetting(setting.name, input.checked));
106
+ control = input;
107
+ }
108
+ else if (setting.type == "list") {
109
+ const select = document.createElement("select");
110
+ for (const option of setting.options) {
111
+ const element = document.createElement("option");
112
+ element.value = option.value;
113
+ element.textContent = option.label;
114
+ select.appendChild(element);
115
+ }
116
+ select.value = String(value);
117
+ select.addEventListener("change", () => api.setSetting(setting.name, select.value));
118
+ control = select;
119
+ }
120
+ else {
121
+ const input = document.createElement("input");
122
+ input.type = "range";
123
+ input.min = String(setting.min);
124
+ input.max = String(setting.max);
125
+ input.step = setting.step ? String(setting.step) : "any";
126
+ input.value = String(value);
127
+ const output = document.createElement("output");
128
+ output.htmlFor.add(controlId);
129
+ output.textContent = String(value);
130
+ input.addEventListener("input", () => {
131
+ api.setSetting(setting.name, Number(input.value));
132
+ output.textContent = String(api.getSetting(setting.name));
133
+ });
134
+ const wrapper = document.createElement("div");
135
+ wrapper.className = "squiffy-setting-slider";
136
+ wrapper.append(input, output);
137
+ control = input;
138
+ control.id = controlId;
139
+ if (setting.description) control.setAttribute("aria-describedby", `${controlId}-description`);
140
+ div.appendChild(wrapper);
141
+ return div;
142
+ }
143
+ control.id = controlId;
144
+ if (setting.description) control.setAttribute("aria-describedby", `${controlId}-description`);
145
+ div.appendChild(control);
146
+ return div;
147
+ }
148
+
149
+ return {
150
+ element: dialog,
151
+ open() {
152
+ render();
153
+ if (!dialog.open) dialog.showModal();
154
+ list.querySelector<HTMLElement>("input, select")?.focus();
155
+ },
156
+ close() {
157
+ dialog.close();
158
+ },
159
+ };
160
+ }
@@ -0,0 +1,67 @@
1
+ // Keeps the docs and the Claude Code plugin's Squiffy skill (plugins/squiffy) from going stale:
2
+ // every helper the runtime registers must be in the helpers reference on the docs site, and in
3
+ // the skill's own helpers reference, which an author's AI agent reads instead of the docs.
4
+ import { expect, test, vi, beforeEach, afterEach } from "vitest";
5
+ import globalJsdom from "global-jsdom";
6
+ import Handlebars from "handlebars";
7
+ import fs from "fs";
8
+ import path from "path";
9
+ import { fileURLToPath } from "url";
10
+ import { init } from "./squiffy.runtime.js";
11
+ import { compile } from "squiffy-compiler";
12
+
13
+ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
14
+ const skillHelpers = path.join(root, "plugins/squiffy/skills/squiffy/references/helpers.md");
15
+ const docsHelpers = path.join(root, "site/src/content/docs/helpers-reference.mdx");
16
+
17
+ // Handlebars' own helpers, documented as part of Handlebars, and the runtime's internal ones
18
+ const builtIn = new Set(["helperMissing", "blockHelperMissing", "each", "if", "unless", "with", "log", "lookup"]);
19
+
20
+ let cleanup: () => void;
21
+
22
+ beforeEach(() => {
23
+ cleanup = globalJsdom("<!DOCTYPE html><html><body><div id=\"squiffy\"></div></body></html>");
24
+ });
25
+
26
+ afterEach(() => {
27
+ vi.restoreAllMocks();
28
+ cleanup();
29
+ });
30
+
31
+ const registeredHelpers = async () => {
32
+ const create = vi.spyOn(Handlebars, "create");
33
+ const result = await compile({ script: "Hello" });
34
+ if (!result.success) throw new Error("Compile failed");
35
+ const story = { ...result.output.story, js: [] } as any;
36
+ await init({ element: document.getElementById("squiffy")!, story, persist: false, storyId: "test", scroll: "none" });
37
+ const names = new Set<string>();
38
+ for (const created of create.mock.results) {
39
+ for (const name of Object.keys((created.value as typeof Handlebars).helpers)) {
40
+ if (!builtIn.has(name) && !name.startsWith("__")) names.add(name);
41
+ }
42
+ }
43
+ return [...names].sort();
44
+ };
45
+
46
+ // A helper counts as mentioned when its name is in code, as `name`, `#name`, {{name, {{#name or (name
47
+ const mentioned = (text: string, name: string) =>
48
+ new RegExp("(`#?|\\{\\{#?|\\()" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\b").test(text);
49
+
50
+ test("finds the runtime's helpers", async () => {
51
+ const helpers = await registeredHelpers();
52
+ expect(helpers).toContain("seen");
53
+ expect(helpers).toContain("rotate");
54
+ expect(helpers.length).toBeGreaterThan(40);
55
+ });
56
+
57
+ test("every helper is in the docs' helpers reference", async () => {
58
+ const text = fs.readFileSync(docsHelpers, "utf8");
59
+ const missing = (await registeredHelpers()).filter(name => !mentioned(text, name));
60
+ expect(missing, `Add these to ${path.relative(root, docsHelpers)}`).toEqual([]);
61
+ });
62
+
63
+ test("every helper is in the Squiffy skill's helpers reference", async () => {
64
+ const text = fs.readFileSync(skillHelpers, "utf8");
65
+ const missing = (await registeredHelpers()).filter(name => !mentioned(text, name));
66
+ expect(missing, `Add these to ${path.relative(root, skillHelpers)}`).toEqual([]);
67
+ });