squiffy-runtime 7.0.0-beta.4 → 7.0.0-beta.6

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 (47) hide show
  1. package/dist/events.d.ts +1 -0
  2. package/dist/panels.d.ts +14 -0
  3. package/dist/panels.test.d.ts +1 -0
  4. package/dist/preview-host.d.ts +2 -1
  5. package/dist/preview-host.js +4 -1
  6. package/dist/preview-host.js.map +2 -2
  7. package/dist/preview-html.js +1 -1
  8. package/dist/preview-protocol.d.ts +4 -0
  9. package/dist/saveSlots.d.ts +16 -0
  10. package/dist/saves.test.d.ts +1 -0
  11. package/dist/savesDialog.d.ts +43 -0
  12. package/dist/savesDialog.test.d.ts +1 -0
  13. package/dist/squiffy.page.css +46 -22
  14. package/dist/squiffy.preview.html +612 -109
  15. package/dist/squiffy.runtime.css +476 -9
  16. package/dist/squiffy.runtime.d.ts +9 -1
  17. package/dist/squiffy.runtime.global.js +113 -72
  18. package/dist/squiffy.runtime.global.js.map +1 -1
  19. package/dist/squiffy.runtime.js +4146 -3460
  20. package/dist/squiffy.runtime.js.map +1 -1
  21. package/dist/state.d.ts +4 -0
  22. package/dist/textProcessor.d.ts +5 -0
  23. package/dist/types.d.ts +32 -0
  24. package/package.json +3 -3
  25. package/src/__snapshots__/squiffy.runtime.test.ts.snap +21 -21
  26. package/src/events.ts +1 -0
  27. package/src/panels.test.ts +201 -0
  28. package/src/panels.ts +187 -0
  29. package/src/plugins/plugins.test.ts +42 -0
  30. package/src/plugins/replaceLabel.ts +6 -2
  31. package/src/preview-host.test.ts +5 -1
  32. package/src/preview-host.ts +9 -3
  33. package/src/preview-protocol.ts +6 -2
  34. package/src/preview.test.ts +71 -3
  35. package/src/preview.ts +74 -13
  36. package/src/saveSlots.ts +159 -0
  37. package/src/saves.test.ts +199 -0
  38. package/src/savesDialog.test.ts +290 -0
  39. package/src/savesDialog.ts +499 -0
  40. package/src/squiffy.page.css +46 -22
  41. package/src/squiffy.runtime.css +476 -9
  42. package/src/squiffy.runtime.test.ts +890 -4
  43. package/src/squiffy.runtime.ts +322 -17
  44. package/src/state.ts +34 -4
  45. package/src/textProcessor.ts +76 -9
  46. package/src/types.ts +57 -1
  47. package/vite.preview.config.ts +7 -0
@@ -31,6 +31,7 @@ export class TextProcessor {
31
31
  });
32
32
 
33
33
  this.handlebars.registerHelper("seen", (name: string) => this.state.getSeen(name));
34
+ this.handlebars.registerHelper("visits", (name: string) => this.state.getVisits(name));
34
35
  this.handlebars.registerHelper("get", (attribute: string) => this.state.get(attribute));
35
36
  this.handlebars.registerHelper("at", (section: string | string[]) => {
36
37
  const currentSection = this.state.get("_section");
@@ -48,6 +49,48 @@ export class TextProcessor {
48
49
  return value;
49
50
  };
50
51
 
52
+ // {{goto "section"}} and {{goto "section" after=3000}} (#375): the runtime goes there once
53
+ // the section or passage being shown has been written. Only the first one counts.
54
+ this.handlebars.registerHelper("goto", (...args: any[]) => {
55
+ const options = args.pop();
56
+ const section = args.length ? unwrapValue(args[0]) : undefined;
57
+ if (typeof section != "string" || !section || !(section in this.getStory().sections)) {
58
+ return new Handlebars.SafeString(errorHtml("Error in {{goto}}:",
59
+ section === undefined ? "expected a section name, e.g. {{goto \"cave\"}}" : `there is no section called "${section}"`));
60
+ }
61
+ let after = 0;
62
+ if (options.hash.after !== undefined) {
63
+ after = Number(unwrapValue(options.hash.after));
64
+ if (!Number.isFinite(after) || after < 0) {
65
+ return new Handlebars.SafeString(errorHtml("Error in {{goto}}:",
66
+ `after= should be a number of milliseconds, e.g. after=3000, not "${options.hash.after}"`));
67
+ }
68
+ }
69
+ this.goto ??= { section, after };
70
+ return "";
71
+ });
72
+
73
+ // {{deactivate "name"}} (#13): the runtime disables the links to that passage on the screen
74
+ // once the section or passage being shown has been written. With no name, it's the passage
75
+ // being shown, e.g. one with @repeat that the player is done with (#104).
76
+ this.handlebars.registerHelper("deactivate", (...args: any[]) => {
77
+ args.pop();
78
+ const names = args.length ? args.map(unwrapValue) : [this.state.get("_passage")];
79
+ for (const name of names) {
80
+ if (typeof name != "string" || !name) {
81
+ return new Handlebars.SafeString(errorHtml("Error in {{deactivate}}:",
82
+ args.length ? "expected a passage name, e.g. {{deactivate \"door\"}}" : "{{deactivate}} with no passage name only works in a passage"));
83
+ }
84
+ const sectionPassages = this.getCurrentSection()?.passages;
85
+ const masterPassages = this.getStory().sections[""]?.passages;
86
+ if (!(sectionPassages && name in sectionPassages) && !(masterPassages && name in masterPassages)) {
87
+ return new Handlebars.SafeString(errorHtml("Error in {{deactivate}}:", `there is no passage called "${name}" in this section`));
88
+ }
89
+ this.deactivate.add(name);
90
+ }
91
+ return "";
92
+ });
93
+
51
94
  // State modification helpers (side effects, no output)
52
95
  // These execute at render time, so they respect {{#if}} conditions
53
96
  this.handlebars.registerHelper("set", (attribute: string, value: any) => {
@@ -218,9 +261,24 @@ export class TextProcessor {
218
261
 
219
262
  const escapeAttr = (s: unknown) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
220
263
 
221
- const addAdditionalParameters = (options: any) => {
264
+ // A link's text and setters can have {{...}} in them, such as [[Drop the {{this}}]](drop,
265
+ // item = "{{this}}") inside an {{#each}}. They're filled in where the link is, so they see
266
+ // the loop's item. Setters aren't HTML, so their values aren't escaped.
267
+ const linkTemplates = new Map<string, HandlebarsTemplateDelegate>();
268
+ const fillIn = (text: unknown, context: unknown, options: any, escape: boolean) => {
269
+ if (typeof text != "string" || !text.includes("{{")) return text;
270
+ const key = (escape ? "h:" : "t:") + text;
271
+ let template = linkTemplates.get(key);
272
+ if (!template) {
273
+ template = this.handlebars.compile(rewriteInfixExpressions(text), { compat: true, noEscape: !escape });
274
+ linkTemplates.set(key, template);
275
+ }
276
+ return template(context, { data: options.data });
277
+ };
278
+
279
+ const addAdditionalParameters = (context: unknown, options: any) => {
222
280
  let result = "";
223
- const setters = options.hash.set as string || "";
281
+ const setters = fillIn(options.hash.set as string || "", context, options, false) as string;
224
282
  if (setters) {
225
283
  // With expressions, a setter can have commas inside quotes, e.g. greeting = "Hi, there"
226
284
  const list = this.getStory().expressions ? splitSetters(setters) : setters.split(",").map(s => s.trim());
@@ -229,14 +287,15 @@ export class TextProcessor {
229
287
  return result;
230
288
  };
231
289
 
232
- this.handlebars.registerHelper("section", (section: string, options) => {
233
- const text = options.hash.text as string || section;
234
- return new Handlebars.SafeString(`<a class="squiffy-link link-section" data-section="${escapeAttr(section)}"${addAdditionalParameters(options)} role="link" tabindex="0">${text}</a>`);
290
+ // Handlebars passes the context a helper is used in (inside an {{#each}}, the item) as this
291
+ this.handlebars.registerHelper("section", function (this: unknown, section: string, options) {
292
+ const text = fillIn(options.hash.text as string || section, this, options, true);
293
+ return new Handlebars.SafeString(`<a class="squiffy-link link-section" data-section="${escapeAttr(section)}"${addAdditionalParameters(this, options)} role="link" tabindex="0">${text}</a>`);
235
294
  });
236
295
 
237
- this.handlebars.registerHelper("passage", (passage: string, options) => {
238
- const text = options.hash.text as string || passage;
239
- return new Handlebars.SafeString(`<a class="squiffy-link link-passage" data-passage="${escapeAttr(passage)}"${addAdditionalParameters(options)} role="link" tabindex="0">${text}</a>`);
296
+ this.handlebars.registerHelper("passage", function (this: unknown, passage: string, options) {
297
+ const text = fillIn(options.hash.text as string || passage, this, options, true);
298
+ return new Handlebars.SafeString(`<a class="squiffy-link link-passage" data-passage="${escapeAttr(passage)}"${addAdditionalParameters(this, options)} role="link" tabindex="0">${text}</a>`);
240
299
  });
241
300
  }
242
301
 
@@ -253,13 +312,21 @@ export class TextProcessor {
253
312
  return this.evaluated;
254
313
  }
255
314
 
315
+ // Where a {{goto}} asked to go. The runtime clears it before showing a section or passage, and
316
+ // follows it afterwards.
317
+ goto: { section: string; after: number } | null = null;
318
+ // The passages whose links a {{deactivate}} asked to disable. Like goto, the runtime clears it
319
+ // before showing a section or passage, and acts on it afterwards.
320
+ deactivate = new Set<string>();
321
+
256
322
  private expressionCache = new Map<string, HandlebarsTemplateDelegate>();
257
323
  // Where the __value helper puts the value of the expression being evaluated
258
324
  private evaluated: unknown;
259
325
 
260
326
  process(text: string, inline: boolean) {
261
327
  try {
262
- const template = this.handlebars.compile(rewriteInfixExpressions(text));
328
+ // compat: inside an {{#each}}, a name that isn't one of the item's looks for an attribute
329
+ const template = this.handlebars.compile(rewriteInfixExpressions(text), { compat: true });
263
330
  text = template(this.state.getStore());
264
331
 
265
332
  if (inline) {
package/src/types.ts CHANGED
@@ -39,6 +39,17 @@ export interface SquiffyApi {
39
39
  clickLink: (link: HTMLElement) => Promise<boolean>;
40
40
  update: (story: Story) => void;
41
41
  goBack: () => void;
42
+ // Whether goBack() would go anywhere, e.g. to enable a Back button. canGoBackChanged says when it changes.
43
+ canGoBack: () => boolean;
44
+ // The game as it is now, to keep and load again later with loadSave()
45
+ getSave: () => SavedGame;
46
+ // Carries on from a saved game, in place of the game as it is now. A save from a different
47
+ // story (by its squiffy.json "id") isn't loaded.
48
+ loadSave: (save: SavedGame) => Promise<LoadSaveResult>;
49
+ // A passage in the master section [[]], rendered as HTML with the attributes as they are now,
50
+ // for a panel beside the story or a dialog (#14, #443). It changes nothing: {{set}} and the
51
+ // like are ignored, its @set and JavaScript don't run, and its links are disabled.
52
+ renderPassage: (name: string) => string;
42
53
 
43
54
  on<E extends keyof SquiffyEventMap>(
44
55
  event: E,
@@ -67,6 +78,7 @@ interface SquiffyJsFunctionApi {
67
78
  story: {
68
79
  go: (section: string) => void;
69
80
  seen: (sectionOrPassage: string) => boolean;
81
+ visits: (sectionOrPassage: string) => number;
70
82
  };
71
83
  }
72
84
 
@@ -78,13 +90,33 @@ export interface Story {
78
90
  ) => void)[];
79
91
  start: string;
80
92
  id?: string | null;
93
+ // squiffy.json's "id", which a saved game is checked against
94
+ projectId?: string;
81
95
  uiJsIndex?: number;
82
96
  // Whether @set and link setters take expressions, with the same rules as {{#if}}: attributes
83
97
  // by name, and text in quotes. True for a story with a squiffy.json (#373).
84
98
  expressions?: boolean;
99
+ // squiffy.json's "panels": passages shown beside the story, or in a dialog from a button
100
+ panels?: Panel[];
85
101
  sections: Record<string, Section>;
86
102
  }
87
103
 
104
+ // The icons a panel's button can have, in place of its label
105
+ export const PANEL_ICONS = ["bag", "person", "map", "help", "info", "list", "book", "star", "heart"] as const;
106
+ export type PanelIcon = typeof PANEL_ICONS[number];
107
+
108
+ // A passage in the master section that's always on screen, rendered again as the story goes on:
109
+ // beside the story ("side"), or in a dialog that a button in the header opens ("button").
110
+ export interface Panel {
111
+ passage: string;
112
+ // The button's text, or its tooltip if it has an icon. A side panel's button only shows on
113
+ // screens too narrow for the panel.
114
+ label: string;
115
+ // "button" if it's left out
116
+ position?: "side" | "button";
117
+ icon?: PanelIcon;
118
+ }
119
+
88
120
  export interface Section {
89
121
  text?: string;
90
122
  clear?: boolean;
@@ -97,6 +129,30 @@ export interface Section {
97
129
  export interface Passage {
98
130
  text?: string;
99
131
  clear?: boolean;
132
+ // @repeat: its links stay clickable, and clicking one doesn't count towards @1, @2... and @last (#104)
133
+ repeat?: boolean;
100
134
  attributes?: string[];
101
135
  jsIndex?: number;
102
- }
136
+ }
137
+ // A saved game, from SquiffyApi.getSave(). It's JSON, so it can be kept as text or in a file.
138
+ export interface SavedGame {
139
+ format: "squiffy-save";
140
+ version: 1;
141
+ // The story's squiffy.json "id", if it has one
142
+ storyId: string | null;
143
+ // Where the player was
144
+ section: string | null;
145
+ passage: string | null;
146
+ // The start of the text the player was reading, to tell saves apart by
147
+ summary: string;
148
+ // When it was saved, as an ISO date
149
+ savedAt: string;
150
+ // Every attribute, including the text on screen (_output)
151
+ state: Record<string, unknown>;
152
+ }
153
+
154
+ export type LoadSaveResult =
155
+ | { success: true }
156
+ // notASave: it isn't a saved game, or it's from a newer version of Squiffy.
157
+ // wrongStory: it's from a different story.
158
+ | { success: false; error: "notASave" | "wrongStory" };
@@ -22,6 +22,13 @@ html, body { height: 100%; }
22
22
  div#squiffy-container { max-width: none; height: 100%; padding: 0; }
23
23
  #squiffy, .squiffy-preview-story, .squiffy-preview-story > div { height: 100%; box-sizing: border-box; }
24
24
  .squiffy-preview-story > div { padding: 1em max(1.25rem, calc((100% - var(--squiffy-max-width)) / 2)); }
25
+ /* The story's panels: their buttons above the story, and side panels to its right */
26
+ #squiffy { display: flex; flex-direction: column; }
27
+ .squiffy-preview-header { flex: none; padding: 0.5rem 0.75rem 0; font-family: system-ui, sans-serif; font-size: 0.875rem; text-align: right; }
28
+ .squiffy-preview-header:empty { display: none; }
29
+ .squiffy-preview-body { flex: 1; min-height: 0; display: flex; }
30
+ #squiffy .squiffy-preview-body > .squiffy-preview-story { flex: 1; min-width: 0; height: 100%; }
31
+ .squiffy-preview-body > aside.squiffy-panels-side { flex: none; width: var(--squiffy-side-width); box-sizing: border-box; overflow-y: auto; padding: 1em 1.25rem 1em 0; }
25
32
  </style>
26
33
  </head>
27
34
  <body>