squiffy-runtime 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/state.ts

@@ -0,0 +1,106 @@
+import { Emitter, SquiffyEventMap } from "./events.js";
+
+export class State {
+    persist: boolean;
+    storyId: string;
+    onSet: (attribute: string, value: any) => void;
+    onSetInternal?: (attribute: string, oldValue: any, newValue: any) => void;
+    store: Record<string, any> = {};
+    emitter: Emitter<SquiffyEventMap>;
+
+    constructor(persist: boolean,
+                storyId: string,
+                onSet: (attribute: string, value: any) => void,
+                emitter: Emitter<SquiffyEventMap>,
+                onSetInternal?: (attribute: string, oldValue: any, newValue: any) => void) {
+        this.persist = persist;
+        this.storyId = storyId;
+        this.onSet = onSet;
+        this.emitter = emitter;
+        this.onSetInternal = onSetInternal;
+    }
+
+    private usePersistentStorage() {
+        return this.persist && window.localStorage && this.storyId;
+    }
+
+    set(attribute: string, value: any) {
+        this.setInternal(attribute, value, true);
+    }
+
+    setInternal(attribute: string, value: any, raiseEvents: boolean) {
+        if (typeof value === "undefined") value = true;
+
+        if (raiseEvents && this.onSetInternal) {
+            this.onSetInternal(attribute, this.get(attribute), structuredClone(value));
+        }
+
+        this.store[attribute] = structuredClone(value);
+
+        if (this.usePersistentStorage()) {
+            localStorage[this.storyId + "-" + attribute] = JSON.stringify(value);
+        }
+
+        if (raiseEvents) {
+            this.emitter.emit("set", { attribute, value });
+        }
+
+        this.onSet(attribute, value);
+    }
+
+    get(attribute: string): any {
+        if (attribute in this.store) {
+            return structuredClone(this.store[attribute]);
+        }
+
+        return null;
+    }
+
+    getStore() {
+        return structuredClone(this.store);
+    }
+
+    load() {
+        if (!this.usePersistentStorage()) {
+            return;
+        }
+
+        const keys = Object.keys(localStorage);
+        for (const key of keys) {
+            if (key.startsWith(this.storyId + "-")) {
+                const attribute = key.substring(this.storyId.length + 1);
+                this.store[attribute] = JSON.parse(localStorage[key]);
+            }
+        }
+    }
+
+    reset() {
+        this.store = {};
+
+        if (!this.usePersistentStorage()) {
+            return;
+        }
+
+        const keys = Object.keys(localStorage);
+        for (const key of keys) {
+            if (key.startsWith(this.storyId)) {
+                localStorage.removeItem(key);
+            }
+        }
+    }
+
+    setSeen(sectionName: string) {
+        let seenSections = this.get("_seen_sections");
+        if (!seenSections) seenSections = [];
+        if (seenSections.indexOf(sectionName) == -1) {
+            seenSections.push(sectionName);
+            this.set("_seen_sections", seenSections);
+        }
+    }
+
+    getSeen(sectionName: string) {
+        const seenSections = this.get("_seen_sections");
+        if (!seenSections) return false;
+        return (seenSections.indexOf(sectionName) > -1);
+    }
+}

package/src/textProcessor.ts

@@ -0,0 +1,76 @@
+import * as marked from "marked";
+import Handlebars from "handlebars";
+import { Section, Story } from "./types.js";
+import { State } from "./state.js";
+
+export class TextProcessor {
+    story: Story;
+    state: State;
+    getCurrentSection: () => Section;
+    handlebars: typeof Handlebars;
+
+    constructor (story: Story,
+                 state: State,
+                 currentSection: () => Section) {
+        this.story = story;
+        this.state = state;
+        this.getCurrentSection = currentSection;
+        this.handlebars = Handlebars.create();
+
+        this.handlebars.registerHelper("embed", (name: string) => {
+            const currentSection = this.getCurrentSection();
+            if (currentSection.passages && name in currentSection.passages) {
+                return this.process(currentSection.passages[name].text || "", true);
+            } else if (name in this.story.sections) {
+                return this.process(this.story.sections[name].text || "", true);
+            }
+        });
+
+        this.handlebars.registerHelper("seen", (name: string) => this.state.getSeen(name));
+        this.handlebars.registerHelper("get", (attribute: string) => this.state.get(attribute));
+        this.handlebars.registerHelper("and", (...args) => args.slice(0,-1).every(Boolean));
+        this.handlebars.registerHelper("or",  (...args) => args.slice(0,-1).some(Boolean));
+        this.handlebars.registerHelper("not", (v) => !v);
+        this.handlebars.registerHelper("eq",  (a,b) => a == b);
+        this.handlebars.registerHelper("ne",  (a,b) => a != b);
+        this.handlebars.registerHelper("gt",  (a,b) => a >  b);
+        this.handlebars.registerHelper("lt",  (a,b) => a <  b);
+        this.handlebars.registerHelper("gte", (a,b) => a >= b);
+        this.handlebars.registerHelper("lte", (a,b) => a <= b);
+        this.handlebars.registerHelper("array", function (...args) {
+            args.pop(); // remove last argument - options
+            return args;
+        });
+
+        const addAdditionalParameters = (options: any) => {
+            let result = "";
+            const setters = options.hash.set as string || "";
+            if (setters) {
+                result += ` data-set='${JSON.stringify(setters.split(",").map(s => s.trim()))}'`;
+            }
+            return result;
+        };
+
+        this.handlebars.registerHelper("section", (section: string, options) => {
+            const text = options.hash.text as string || section;
+            return new Handlebars.SafeString(`<a class="squiffy-link link-section" data-section="${section}"${addAdditionalParameters(options)} role="link" tabindex="0">${text}</a>`);
+        });
+
+        this.handlebars.registerHelper("passage", (passage: string, options) => {
+            const text = options.hash.text as string || passage;
+            return new Handlebars.SafeString(`<a class="squiffy-link link-passage" data-passage="${passage}"${addAdditionalParameters(options)} role="link" tabindex="0">${text}</a>`);
+        });
+    }
+
+    process(text: string, inline: boolean) {
+        const template = this.handlebars.compile(text);
+        text = template(this.state.getStore());
+
+        if (inline) {
+            return marked.parseInline(text, { async: false }).trim();
+        }
+        else {
+            return marked.parse(text, { async: false }).trim();
+        }
+    }
+}

package/src/types.plugins.ts

@@ -0,0 +1,41 @@
+import type { HelperDelegate } from "handlebars";
+import { SquiffyEventHandler, SquiffyEventMap } from "./events.js";
+import { Animation } from "./animation.js";
+
+export interface SquiffyPlugin {
+    name: string;
+    init(host: PluginHost): void | Promise<void>;
+    onWrite?(el: HTMLElement): void;
+    onLoad?(): void;
+}
+
+export interface HandleLinkResult {
+    disableLink?: boolean;
+}
+
+export interface PluginHost {
+    outputElement: HTMLElement;
+    registerHelper(name: string, helper: HelperDelegate): void;
+    registerLinkHandler(type: string, handler: (el: HTMLElement) => HandleLinkResult): void;
+    get(attribute: string): any;
+    set(attribute: string, value: any): void;
+    getSectionText(name: string): string | null;
+    getPassageText(name: string): string | null;
+    processText: (text: string, inline: boolean) => string;
+    addTransition: (fn: () => Promise<void>) => void;
+    animation: Animation;
+    on<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): () => void; // returns unsubscribe
+
+    off<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): void;
+
+    once<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): () => void;
+}

package/src/types.ts

@@ -0,0 +1,81 @@
+import { SquiffyEventHandler, SquiffyEventMap } from "./events.js";
+
+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 {
+    begin: () => Promise<void>;
+    restart: () => void;
+    get: (attribute: string) => any;
+    set: (attribute: string, value: any) => void;
+    clickLink: (link: HTMLElement) => Promise<boolean>;
+    update: (story: Story) => void;
+    goBack: () => void;
+
+    on<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): () => void; // returns unsubscribe
+
+    off<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): void;
+
+    once<E extends keyof SquiffyEventMap>(
+        event: E,
+        handler: SquiffyEventHandler<E>
+    ): () => 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;
+    uiJsIndex?: number;
+    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;
+}

package/src/updater.ts

@@ -0,0 +1,77 @@
+import { Story } from "./types.js";
+
+export function updateStory(oldStory: Story,
+                            newStory: Story,
+                            outputElement: HTMLElement,
+                            ui: any,
+                            disableLink: (link: Element) => void) {
+
+    function safeQuerySelector(name: string) {
+        return name.replace(/'/g, "\\'");
+    }
+
+    function getSectionContent(section: string) {
+        return outputElement.querySelectorAll(`[data-source='[[${safeQuerySelector(section)}]]']`);
+    }
+
+    function getPassageContent(section: string, passage: string) {
+        return outputElement.querySelectorAll(`[data-source='[[${safeQuerySelector(section)}]][${safeQuerySelector(passage)}]']`);
+    }
+
+    function updateElementTextPreservingDisabledPassageLinks(element: Element, text: string) {
+        // Record which passage links are disabled
+        const disabledPassages = Array.from(element
+            .querySelectorAll("a.link-passage.disabled"))
+            .map((el: HTMLElement) => el.getAttribute("data-passage"));
+
+        element.innerHTML = text;
+
+        // Re-disable links that were disabled before the update
+        for (const passage of disabledPassages) {
+            const link = element.querySelector(`a.link-passage[data-passage="${passage}"]`);
+            if (link) disableLink(link);
+        }
+    }
+
+    for (const existingSection of Object.keys(oldStory.sections)) {
+        const elements = getSectionContent(existingSection);
+        if (elements.length) {
+            const newSection = newStory.sections[existingSection];
+            if (!newSection) {
+                // section has been deleted
+                for (const element of elements) {
+                    const parentOutputSection = element.closest(".squiffy-output-section");
+                    parentOutputSection.remove();
+                }
+            }
+            else if (newSection.text != oldStory.sections[existingSection].text) {
+                // section has been updated
+                for (const element of elements) {
+                    updateElementTextPreservingDisabledPassageLinks(element, ui.processText(newSection.text, false));
+                }
+            }
+        }
+
+        if (!oldStory.sections[existingSection].passages) continue;
+
+        for (const existingPassage of Object.keys(oldStory.sections[existingSection].passages)) {
+            const elements = getPassageContent(existingSection, existingPassage);
+            if (!elements.length) continue;
+
+            const newPassage = newStory.sections[existingSection]?.passages && newStory.sections[existingSection]?.passages[existingPassage];
+            if (!newPassage) {
+                // passage has been deleted
+                for (const element of elements) {
+                    const parentOutputPassage = element.closest(".squiffy-output-passage");
+                    parentOutputPassage.remove();
+                }
+            }
+            else if (newPassage.text && newPassage.text != oldStory.sections[existingSection].passages[existingPassage].text) {
+                // passage has been updated
+                for (const element of elements) {
+                    updateElementTextPreservingDisabledPassageLinks(element, ui.processText(newPassage.text, false));
+                }
+            }
+        }
+    }
+}

package/src/utils.ts

@@ -0,0 +1,17 @@
+export function fadeReplace(element: HTMLElement, text: string): Promise<void> {
+    return new Promise((resolve) => {
+        element.addEventListener("transitionend", function () {
+            element.innerHTML = text;
+
+            element.addEventListener("transitionend", function () {
+                element.classList.remove("fade-in");
+                resolve();
+            }, { once: true });
+
+            element.classList.remove("fade-out");
+            element.classList.add("fade-in");
+        }, { once: true });
+
+        element.classList.add("fade-out");
+    });
+}

package/tsconfig.json

@@ -8,7 +8,10 @@
       "skipLibCheck": true,
       "outDir": "dist",
       "declaration": true,
+      "module": "NodeNext",
+      "moduleResolution": "nodenext",
+      "allowSyntheticDefaultImports": true
     },
-    "include": ["src/squiffy.runtime.ts"]
+    "include": ["src/*.ts"]
 }
   

package/vite.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+    build: {
+        target: "es2020",
+        sourcemap: true,
+        minify: "esbuild",
+
+        lib: {
+            entry: "src/squiffy.runtime.ts",
+            name: "squiffyRuntime"
+        },
+
+        rollupOptions: {
+            output: [
+                {
+                    format: "es",
+                    entryFileNames: "squiffy.runtime.js"
+                },
+                {
+                    format: "iife",
+                    name: "squiffyRuntime",
+                    entryFileNames: "squiffy.runtime.global.js"
+                }
+            ]
+        }
+    },
+
+    plugins: [
+        dts({
+            entryRoot: "src",
+            outDir: "dist"
+        })
+    ]
+});

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "jsdom",
+        setupFiles: "./vitest.setup.ts",
+    },
+});

package/vitest.setup.ts

@@ -0,0 +1,16 @@
+import cssEscape from "css.escape";
+
+declare global {
+    interface CSS {
+        escape(value: string): string;
+    }
+}
+
+const g = globalThis as any;
+
+if (!g.CSS) g.CSS = {};
+if (typeof g.CSS.escape !== "function") {
+    g.CSS.escape = cssEscape;
+}
+
+export {};