squiffy-runtime 6.0.0-alpha.10 → 6.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squiffy-runtime",
-  "version": "6.0.0-alpha.10",
+  "version": "6.0.0-alpha.11",
   "type": "module",
   "main": "dist/squiffy.runtime.js",
   "types": "dist/squiffy.runtime.d.ts",
@@ -22,7 +22,7 @@
     "@types/jsdom": "^21.1.7",
     "global-jsdom": "^25.0.0",
     "jsdom": "^25.0.0",
-    "squiffy-compiler": "^6.0.0-alpha.2",
+    "squiffy-compiler": "^6.0.0-alpha.3",
     "typescript": "^5.6.2",
     "vitest": "^2.1.1"
   }

package/src/__snapshots__/squiffy.runtime.test.ts.snap

@@ -102,13 +102,3 @@ exports[`Update passage output - passage name "a'1" 2`] = `
 "
     <div class="squiffy-output-section" id="squiffy-section-1" data-section="_default"><div class="squiffy-output-block"><div data-source="[[_default]]"><p>Click this: <a class="squiffy-link link-passage disabled" data-passage="a'1" role="link" tabindex="-1">a'1</a></p></div></div><div class="squiffy-output-block"><div data-source="[[_default]][a'1]"><p>Updated passage content</p></div></div></div>"
 `;
-
-exports[`Update passage output 1`] = `
-"
-    <div class="squiffy-output-section" id="squiffy-section-1" data-section="_default"><div class="squiffy-output-block"><div data-source="[[_default]]"><p>Click this: <a class="squiffy-link link-passage disabled" data-passage="a" role="link" tabindex="-1">a</a></p></div></div><div class="squiffy-output-block"><div data-source="[[_default]][a]"><p>Passage a content</p></div></div></div>"
-`;
-
-exports[`Update passage output 2`] = `
-"
-    <div class="squiffy-output-section" id="squiffy-section-1" data-section="_default"><div class="squiffy-output-block"><div data-source="[[_default]]"><p>Click this: <a class="squiffy-link link-passage disabled" data-passage="a" role="link" tabindex="-1">a</a></p></div></div><div class="squiffy-output-block"><div data-source="[[_default]][a]"><p>Updated passage content</p></div></div></div>"
-`;

package/src/events.ts

@@ -0,0 +1,42 @@
+type LinkType = 'section' | 'passage' | 'rotate' | 'sequence';
+
+export type SquiffyEventMap = {
+    linkClick: { linkType: LinkType }; // a story link was clicked
+};
+
+export type SquiffyEventHandler<E extends keyof SquiffyEventMap> =
+    (payload: SquiffyEventMap[E]) => void;
+
+export class Emitter<Events extends Record<string, any>> {
+    private listeners = new Map<keyof Events, Set<Function>>();
+
+    on<E extends keyof Events>(event: E, handler: (p: Events[E]) => void) {
+        if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+        this.listeners.get(event)!.add(handler);
+        return () => this.off(event, handler);
+    }
+
+    off<E extends keyof Events>(event: E, handler: (p: Events[E]) => void) {
+        this.listeners.get(event)?.delete(handler);
+    }
+
+    once<E extends keyof Events>(event: E, handler: (p: Events[E]) => void) {
+        const off = this.on(event, (payload) => {
+            off();
+            handler(payload);
+        });
+        return off;
+    }
+
+    emit<E extends keyof Events>(event: E, payload: Events[E]) {
+        // Fire handlers asynchronously so the runtime isn't blocked by user code.
+        queueMicrotask(() => {
+            this.listeners.get(event)?.forEach(h => {
+                try { (h as any)(payload); } catch (err) {
+                    // Swallow so a bad handler doesn't break the game; optionally log.
+                    console.error(`[Squiffy] handler for "${String(event)}" failed`, err);
+                }
+            });
+        });
+    }
+}

package/src/squiffy.runtime.test.ts

@@ -1,4 +1,4 @@
-import { expect, test, beforeEach, afterEach } from 'vitest';
+import { expect, test, beforeEach, afterEach, vi } from 'vitest';
 import fs from 'fs/promises';
 import globalJsdom from 'global-jsdom';
 import { init } from './squiffy.runtime.js';
@@ -20,7 +20,6 @@ const html = `
 
 const compile = async (script: string) => {
     const compileResult = await squiffyCompile({
-        scriptBaseFilename: "filename.squiffy", // TODO: This shouldn't be required
         script: script,
     });
 
@@ -40,7 +39,6 @@ const compile = async (script: string) => {
 }
 
 const initScript = async (script: string) => {
-    globalJsdom(html);
     const element = document.getElementById('squiffy');
 
     if (!element) {
@@ -78,7 +76,7 @@ const getTestOutput = () => {
 let cleanup: { (): void };
 
 beforeEach(() => {
-    cleanup = globalJsdom();
+    cleanup = globalJsdom(html);
 });
 
 afterEach(() => {
@@ -103,6 +101,9 @@ test('Click a section link', async () => {
     expect(section3Link).not.toBeNull();
     expect(linkToPassage.classList).not.toContain('disabled');
 
+    const handler = vi.fn();
+    const off = squiffyApi.on('linkClick', handler);
+
     const handled = squiffyApi.clickLink(section3Link);
     expect(handled).toBe(true);
 
@@ -110,6 +111,15 @@ test('Click a section link', async () => {
 
     // passage link is from the previous section, so should be unclickable
     expect(squiffyApi.clickLink(linkToPassage)).toBe(false);
+
+    // await for the event to be processed
+    await Promise.resolve();
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({ linkType: 'section' })
+    );
+    off();
 });
 
 test('Click a passage link', async () => {
@@ -125,6 +135,9 @@ test('Click a passage link', async () => {
     expect(section3Link).not.toBeNull();
     expect(linkToPassage.classList).not.toContain('disabled');
 
+    const handler = vi.fn();
+    const off = squiffyApi.on('linkClick', handler);
+
     const handled = squiffyApi.clickLink(linkToPassage);
     expect(handled).toBe(true);
 
@@ -133,6 +146,15 @@ test('Click a passage link', async () => {
 
     // shouldn't be able to click it again
     expect(squiffyApi.clickLink(linkToPassage)).toBe(false);
+
+    // await for the event to be processed
+    await Promise.resolve();
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({ linkType: 'passage' })
+    );
+    off();
 });
 
 test('Run JavaScript functions', async () => {

package/src/squiffy.runtime.ts

@@ -1,64 +1,7 @@
-export interface SquiffyInitOptions {
-    element: HTMLElement;
-    story: Story;
-    scroll?: string,
-    persist?: boolean,
-    onSet?: (attribute: string, value: any) => void,
-}
-
-export interface SquiffySettings {
-    scroll: string,
-    persist: boolean,
-    onSet: (attribute: string, value: any) => void,
-}
-
-export interface SquiffyApi {
-    restart: () => void;
-    get: (attribute: string) => any;
-    set: (attribute: string, value: any) => void;
-    clickLink: (link: HTMLElement) => boolean;
-    update: (story: Story) => void;
-}
-
-// Previous versions of Squiffy had "squiffy", "get" and "set" as globals - we now pass these directly into JS functions.
-// We may tidy up this API at some point, though that would be a breaking change.
-interface SquiffyJsFunctionApi {
-    get: (attribute: string) => any;
-    set: (attribute: string, value: any) => void;
-    ui: {
-        transition: (f: any) => void;
-    };
-    story: {
-        go: (section: string) => void;
-    };
-}
-
-export interface Story {
-    js: ((
-            squiffy: SquiffyJsFunctionApi,
-            get: (attribute: string) => any,
-            set: (attribute: string, value: any) => void
-        ) => void)[];
-    start: string;
-    id?: string | null;
-    sections: Record<string, Section>;
-}
-
-export interface Section {
-    text?: string;
-    clear?: boolean;
-    attributes?: string[],
-    jsIndex?: number;
-    passages?: Record<string, Passage>;
-    passageCount?: number;
-}
-
-export interface Passage {
-    text?: string;
-    clear?: boolean;
-    attributes?: string[];
-    jsIndex?: number;
-}
+import { SquiffyApi, SquiffyInitOptions, SquiffySettings, Story, Section } from './types.js';
+import { startsWith, rotate } from "./utils.js";
+import { TextProcessor } from './textProcessor.js';
+import { Emitter, SquiffyEventMap } from './events.js';
 
 export const init = (options: SquiffyInitOptions): SquiffyApi => {
     let story: Story;
@@ -69,6 +12,8 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
     let outputElement: HTMLElement;
     let settings: SquiffySettings;
     let storageFallback: Record<string, string> = {};
+    let textProcessor: TextProcessor;
+    const emitter = new Emitter<SquiffyEventMap>();
     
     function set(attribute: string, value: any) {
         if (typeof value === 'undefined') value = true;
@@ -122,6 +67,7 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
                 }
             }
 
+            emitter.emit('linkClick', { linkType: 'passage' });
             return true;
         }
         
@@ -131,6 +77,7 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
                 go(section);
             }
 
+            emitter.emit('linkClick', { linkType: 'section' });
             return true;
         }
         
@@ -147,7 +94,8 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
                 set(attribute, result[0]);
             }
             save();
-            
+
+            emitter.emit('linkClick', { linkType: rotateAttr ? 'rotate' : 'sequence' });
             return true;
         }
 
@@ -493,197 +441,16 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
             }
         },
         processText: (text: string) => {
-            function process(text: string, data: any) {
-                let containsUnprocessedSection = false;
-                const open = text.indexOf('{');
-                let close;
-    
-                if (open > -1) {
-                    let nestCount = 1;
-                    let searchStart = open + 1;
-                    let finished = false;
-    
-                    while (!finished) {
-                        const nextOpen = text.indexOf('{', searchStart);
-                        const nextClose = text.indexOf('}', searchStart);
-    
-                        if (nextClose > -1) {
-                            if (nextOpen > -1 && nextOpen < nextClose) {
-                                nestCount++;
-                                searchStart = nextOpen + 1;
-                            }
-                            else {
-                                nestCount--;
-                                searchStart = nextClose + 1;
-                                if (nestCount === 0) {
-                                    close = nextClose;
-                                    containsUnprocessedSection = true;
-                                    finished = true;
-                                }
-                            }
-                        }
-                        else {
-                            finished = true;
-                        }
-                    }
-                }
-    
-                if (containsUnprocessedSection) {
-                    const section = text.substring(open + 1, close);
-                    const value = processTextCommand(section, data);
-                    text = text.substring(0, open) + value + process(text.substring(close! + 1), data);
-                }
-    
-                return (text);
-            }
-    
-            function processTextCommand(text: string, data: any) {
-                if (startsWith(text, 'if ')) {
-                    return processTextCommand_If(text, data);
-                }
-                else if (startsWith(text, 'else:')) {
-                    return processTextCommand_Else(text, data);
-                }
-                else if (startsWith(text, 'label:')) {
-                    return processTextCommand_Label(text, data);
-                }
-                else if (/^rotate[: ]/.test(text)) {
-                    return processTextCommand_Rotate('rotate', text);
-                }
-                else if (/^sequence[: ]/.test(text)) {
-                    return processTextCommand_Rotate('sequence', text);
-                }
-                else if (currentSection.passages && text in currentSection.passages) {
-                    return process(currentSection.passages[text].text || '', data);
-                }
-                else if (text in story.sections) {
-                    return process(story.sections[text].text || '', data);
-                }
-                else if (startsWith(text, '@') && !startsWith(text, '@replace')) {
-                    processAttributes(text.substring(1).split(","));
-                    return "";
-                }
-                return get(text);
-            }
-    
-            function processTextCommand_If(section: string, data: any) {
-                const command = section.substring(3);
-                const colon = command.indexOf(':');
-                if (colon == -1) {
-                    return ('{if ' + command + '}');
-                }
-    
-                const text = command.substring(colon + 1);
-                let condition = command.substring(0, colon);
-                condition = condition.replace("<", "&lt;");
-                const operatorRegex = /([\w ]*)(=|&lt;=|&gt;=|&lt;&gt;|&lt;|&gt;)(.*)/;
-                const match = operatorRegex.exec(condition);
-    
-                let result = false;
-    
-                if (match) {
-                    const lhs = get(match[1]);
-                    const op = match[2];
-                    let rhs = match[3];
-    
-                    if (startsWith(rhs, '@')) rhs = get(rhs.substring(1));
-    
-                    if (op == '=' && lhs == rhs) result = true;
-                    if (op == '&lt;&gt;' && lhs != rhs) result = true;
-                    if (op == '&gt;' && lhs > rhs) result = true;
-                    if (op == '&lt;' && lhs < rhs) result = true;
-                    if (op == '&gt;=' && lhs >= rhs) result = true;
-                    if (op == '&lt;=' && lhs <= rhs) result = true;
-                }
-                else {
-                    let checkValue = true;
-                    if (startsWith(condition, 'not ')) {
-                        condition = condition.substring(4);
-                        checkValue = false;
-                    }
-    
-                    if (startsWith(condition, 'seen ')) {
-                        result = (seen(condition.substring(5)) == checkValue);
-                    }
-                    else {
-                        let value = get(condition);
-                        if (value === null) value = false;
-                        result = (value == checkValue);
-                    }
-                }
-    
-                const textResult = result ? process(text, data) : '';
-    
-                data.lastIf = result;
-                return textResult;
-            }
-    
-            function processTextCommand_Else(section: string, data: any) {
-                if (!('lastIf' in data) || data.lastIf) return '';
-                const text = section.substring(5);
-                return process(text, data);
-            }
-    
-            function processTextCommand_Label(section: string, data: any) {
-                const command = section.substring(6);
-                const eq = command.indexOf('=');
-                if (eq == -1) {
-                    return ('{label:' + command + '}');
-                }
-    
-                const text = command.substring(eq + 1);
-                const label = command.substring(0, eq);
-    
-                return '<span class="squiffy-label-' + label + '">' + process(text, data) + '</span>';
-            }
-    
-            function processTextCommand_Rotate(type: string, section: string) {
-                let options;
-                let attribute = '';
-                if (section.substring(type.length, type.length + 1) == ' ') {
-                    const colon = section.indexOf(':');
-                    if (colon == -1) {
-                        return '{' + section + '}';
-                    }
-                    options = section.substring(colon + 1);
-                    attribute = section.substring(type.length + 1, colon);
-                }
-                else {
-                    options = section.substring(type.length + 1);
-                }
-                // TODO: Check - previously there was no second parameter here
-                const rotation = rotate(options.replace(/"/g, '&quot;').replace(/'/g, '&#39;'), null);
-                if (attribute) {
-                    set(attribute, rotation[0]);
-                }
-                return '<a class="squiffy-link" data-' + type + '="' + rotation[1] + '" data-attribute="' + attribute + '" role="link">' + rotation[0] + '</a>';
-            }
-    
             const data = {
                 fulltext: text
             };
-            return process(text, data);
+            return textProcessor.process(text, data);
         },
         transition: function (f: any) {
             set('_transition', f.toString());
             f();
         },
     };
-    
-    function startsWith(string: string, prefix: string) {
-        return string.substring(0, prefix.length) === prefix;
-    }
-    
-    function rotate(options: string, current: string | null) {
-        const colon = options.indexOf(':');
-        if (colon == -1) {
-            return [options, current];
-        }
-        const next = options.substring(0, colon);
-        let remaining = options.substring(colon + 1);
-        if (current) remaining += ':' + current;
-        return [next, remaining];
-    }
 
     function safeQuerySelector(name: string) {
         return name.replace(/'/g, "\\'");
@@ -784,6 +551,8 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
         if (event.key !== "Enter") return;
         handleClick(event);
     });
+
+    textProcessor = new TextProcessor(get, set, story, ui, seen, processAttributes);
     
     begin();
 
@@ -793,5 +562,8 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
         set: set,
         clickLink: handleLink,
         update: update,
+        on: (e, h) => emitter.on(e, h),
+        off: (e, h) => emitter.off(e, h),
+        once: (e, h) => emitter.once(e, h),
     };
 };

package/src/textProcessor.ts

@@ -0,0 +1,177 @@
+import { startsWith, rotate } from "./utils.js";
+
+export class TextProcessor {
+    get: (attribute: string) => any;
+    set: (attribute: string, value: any) => void;
+    story: any;
+    currentSection: any;
+    seen: (section: string) => boolean;
+    processAttributes: (attributes: string[]) => void;
+
+    constructor (get: (attribute: string) => any,
+                 set: (attribute: string, value: any) => void,
+                 story: any, currentSection: any,
+                 seen: (section: string) => boolean,
+                 processAttributes: (attributes: string[]) => void) {
+        this.get = get;
+        this.set = set;
+        this.story = story;
+        this.currentSection = currentSection;
+        this.seen = seen;
+        this.processAttributes = processAttributes;
+    }
+
+    process(text: string, data: any) {
+        let containsUnprocessedSection = false;
+        const open = text.indexOf('{');
+        let close;
+
+        if (open > -1) {
+            let nestCount = 1;
+            let searchStart = open + 1;
+            let finished = false;
+
+            while (!finished) {
+                const nextOpen = text.indexOf('{', searchStart);
+                const nextClose = text.indexOf('}', searchStart);
+
+                if (nextClose > -1) {
+                    if (nextOpen > -1 && nextOpen < nextClose) {
+                        nestCount++;
+                        searchStart = nextOpen + 1;
+                    } else {
+                        nestCount--;
+                        searchStart = nextClose + 1;
+                        if (nestCount === 0) {
+                            close = nextClose;
+                            containsUnprocessedSection = true;
+                            finished = true;
+                        }
+                    }
+                } else {
+                    finished = true;
+                }
+            }
+        }
+
+        if (containsUnprocessedSection) {
+            const section = text.substring(open + 1, close);
+            const value = this.processTextCommand(section, data);
+            text = text.substring(0, open) + value + this.process(text.substring(close! + 1), data);
+        }
+
+        return (text);
+    }
+
+    processTextCommand(text: string, data: any) {
+        if (startsWith(text, 'if ')) {
+            return this.processTextCommand_If(text, data);
+        } else if (startsWith(text, 'else:')) {
+            return this.processTextCommand_Else(text, data);
+        } else if (startsWith(text, 'label:')) {
+            return this.processTextCommand_Label(text, data);
+        } else if (/^rotate[: ]/.test(text)) {
+            return this.processTextCommand_Rotate('rotate', text);
+        } else if (/^sequence[: ]/.test(text)) {
+            return this.processTextCommand_Rotate('sequence', text);
+        } else if (this.currentSection.passages && text in this.currentSection.passages) {
+            return this.process(this.currentSection.passages[text].text || '', data);
+        } else if (text in this.story.sections) {
+            return this.process(this.story.sections[text].text || '', data);
+        } else if (startsWith(text, '@') && !startsWith(text, '@replace')) {
+            this.processAttributes(text.substring(1).split(","));
+            return "";
+        }
+        return this.get(text);
+    }
+
+    processTextCommand_If(section: string, data: any) {
+        const command = section.substring(3);
+        const colon = command.indexOf(':');
+        if (colon == -1) {
+            return ('{if ' + command + '}');
+        }
+
+        const text = command.substring(colon + 1);
+        let condition = command.substring(0, colon);
+        condition = condition.replace("<", "&lt;");
+        const operatorRegex = /([\w ]*)(=|&lt;=|&gt;=|&lt;&gt;|&lt;|&gt;)(.*)/;
+        const match = operatorRegex.exec(condition);
+
+        let result = false;
+
+        if (match) {
+            const lhs = this.get(match[1]);
+            const op = match[2];
+            let rhs = match[3];
+
+            if (startsWith(rhs, '@')) rhs = this.get(rhs.substring(1));
+
+            if (op == '=' && lhs == rhs) result = true;
+            if (op == '&lt;&gt;' && lhs != rhs) result = true;
+            if (op == '&gt;' && lhs > rhs) result = true;
+            if (op == '&lt;' && lhs < rhs) result = true;
+            if (op == '&gt;=' && lhs >= rhs) result = true;
+            if (op == '&lt;=' && lhs <= rhs) result = true;
+        } else {
+            let checkValue = true;
+            if (startsWith(condition, 'not ')) {
+                condition = condition.substring(4);
+                checkValue = false;
+            }
+
+            if (startsWith(condition, 'seen ')) {
+                result = (this.seen(condition.substring(5)) == checkValue);
+            } else {
+                let value = this.get(condition);
+                if (value === null) value = false;
+                result = (value == checkValue);
+            }
+        }
+
+        const textResult = result ? this.process(text, data) : '';
+
+        data.lastIf = result;
+        return textResult;
+    }
+
+    processTextCommand_Else(section: string, data: any) {
+        if (!('lastIf' in data) || data.lastIf) return '';
+        const text = section.substring(5);
+        return this.process(text, data);
+    }
+
+    processTextCommand_Label(section: string, data: any) {
+        const command = section.substring(6);
+        const eq = command.indexOf('=');
+        if (eq == -1) {
+            return ('{label:' + command + '}');
+        }
+
+        const text = command.substring(eq + 1);
+        const label = command.substring(0, eq);
+
+        return '<span class="squiffy-label-' + label + '">' + this.process(text, data) + '</span>';
+    }
+
+    processTextCommand_Rotate(type: string, section: string) {
+        let options;
+        let attribute = '';
+        if (section.substring(type.length, type.length + 1) == ' ') {
+            const colon = section.indexOf(':');
+            if (colon == -1) {
+                return '{' + section + '}';
+            }
+            options = section.substring(colon + 1);
+            attribute = section.substring(type.length + 1, colon);
+        } else {
+            options = section.substring(type.length + 1);
+        }
+        // TODO: Check - previously there was no second parameter here
+        const rotation = rotate(options.replace(/"/g, '&quot;').replace(/'/g, '&#39;'), null);
+        if (attribute) {
+            this.set(attribute, rotation[0]);
+        }
+        return '<a class="squiffy-link" data-' + type + '="' + rotation[1] + '" data-attribute="' + attribute + '" role="link">' + rotation[0] + '</a>';
+    }
+}