@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/core/mixins.ts

@@ -8,17 +8,42 @@
 /** Constructor shape accepted by the mixin functions. */
 export type Constructor<T = object> = new (...args: any[]) => T;
 
+/** What a listener receives: the payload, plus the framework's own fields.
+ *
+ * Kept as an intersection because `fire` merges them into one object — that
+ * is what a handler gets. As a side effect it also fixes the `type`
+ * clobbering at the type level: intersecting `type: "loaded"` with
+ * `type?: string` yields `"loaded"`.
+ */
+export type FiredEvent<M, K extends keyof M & string> = M[K] & { type: K; target: unknown };
+
 /** Eventing members provided by the Evented mixin. */
-export interface EventedInstance {
-    on: (type: string, fn: unknown, context?: unknown) => unknown;
-    off: (type: string, fn: unknown, context?: unknown) => unknown;
-    fire: (type: string, data?: unknown, target?: unknown) => unknown;
-    hasEventListeners: (type: string) => boolean;
+export interface EventedInstance<M = Record<string, unknown>> {
+    on<K extends keyof M & string>(
+        type: K,
+        fn: (e: FiredEvent<M, K>) => void,
+        context?: unknown,
+    ): this;
+    off<K extends keyof M & string>(
+        type: K,
+        fn: (e: FiredEvent<M, K>) => void,
+        context?: unknown,
+    ): this;
+    fire<K extends keyof M & string>(type: K, data?: M[K]): this;
+    hasEventListeners<K extends keyof M & string>(type: K): boolean;
 }
 
-/** Instance contract for DomMixed consumers. */
-export interface DomMixedInstance extends EventedInstance {
-    _el: Record<string, HTMLElement>;
+/**
+ * Instance contract for DomMixed consumers.
+ *
+ * `_el` is deliberately `Record<string, unknown>`: each class declares its
+ * own element shape, and several of them hold members that are legitimately
+ * null before the component builds them (a slide's call-to-action, a
+ * slider's live region). Requiring `Record<string, HTMLElement>` here would
+ * force every one of those back into an `{} as HTMLElement` placeholder.
+ */
+export interface DomMixedInstance<M = Record<string, unknown>> extends EventedInstance<M> {
+    _el: Record<string, unknown>;
     data?: unknown;
 }
 
@@ -28,7 +53,7 @@ export interface DomMixedInstance extends EventedInstance {
 ================================================== */
 
 /** Adds eventing (on/off/fire/hasEventListeners) to a class. */
-export function Evented<T extends Constructor>(Base: T) {
+export function Evented<M, T extends Constructor>(Base: T) {
     return class extends Base {
         declare "_vco_events"?: Record<string, { action: unknown; context: unknown }[]>;
 
@@ -62,31 +87,25 @@ export function Evented<T extends Constructor>(Base: T) {
                 string,
                 { action: unknown; context: unknown }[]
             >;
-            for (let i = 0, len = events[type].length; i < len; i++) {
-                if (
-                    events[type][i].action === fn &&
-                    (!context || events[type][i].context === context)
-                ) {
-                    events[type].splice(i, 1);
-                    return this;
-                }
+            events[type] = events[type].filter(
+                (listener) =>
+                    !(listener.action === fn && (!context || listener.context === context)),
+            );
+            if (events[type].length === 0) {
+                delete events[type];
             }
             return this;
         }
 
-        fire(
-            /*String*/ type: string,
-            /*(optional) Object*/ data?: unknown,
-            target?: unknown,
-        ): this {
+        fire(/*String*/ type: string, /*(optional) Object*/ data?: unknown): this {
             if (!this.hasEventListeners(type)) {
                 return this;
             }
 
             const event = {
-                type: type,
-                target: target || this,
                 ...(data as Record<string, unknown> | undefined),
+                type,
+                target: this,
             };
 
             const listeners = (
@@ -103,7 +122,7 @@ export function Evented<T extends Constructor>(Base: T) {
         constructor(...args: any[]) {
             super(...args);
         }
-    };
+    } as Constructor<EventedInstance<M>> & T;
 }
 
 /*	DomMixed
@@ -113,29 +132,41 @@ export function Evented<T extends Constructor>(Base: T) {
 
 /** Adds DOM container conveniences (addTo/removeFrom/setPosition/show/hide
  *  and the onAdd/onRemove/onLoaded lifecycle events) to a class. */
-export function DomMixed<T extends Constructor<DomMixedInstance>>(Base: T) {
+export function DomMixed<
+    M extends { loaded: unknown; added: unknown; removed: unknown },
+    T extends Constructor<DomMixedInstance<M>>,
+>(Base: T) {
     return class extends Base {
+        /**
+         * The host element. Every DomMixed consumer keeps its root element
+         * here, so this narrows the `Record<string, unknown>` element map to
+         * something with a style and children.
+         */
+        container(): HTMLElement {
+            return this._el.container as HTMLElement;
+        }
+
         /*	Adding, Hiding, Showing etc
         ================================================== */
         show(animate?: unknown): void {
             if (!animate) {
-                this._el.container.style.display = "block";
+                this.container().style.display = "block";
             }
             // animated show is not implemented
         }
 
         hide(): void {
-            this._el.container.style.display = "none";
+            this.container().style.display = "none";
         }
 
         addTo(container: HTMLElement): this {
-            container.appendChild(this._el.container);
+            container.appendChild(this.container());
             this.onAdd();
             return this;
         }
 
         removeFrom(container: HTMLElement): this {
-            container.removeChild(this._el.container);
+            container.removeChild(this.container());
             this.onRemove();
             return this;
         }
@@ -143,7 +174,7 @@ export function DomMixed<T extends Constructor<DomMixedInstance>>(Base: T) {
         /*	Set the Position
         ================================================== */
         setPosition(pos: Record<string, number>, el?: HTMLElement): this {
-            const target = el || this._el.container;
+            const target = el || this.container();
             for (const name of Object.keys(pos)) {
                 (target.style as unknown as Record<string, string>)[name] = pos[name] + "px";
             }
@@ -151,17 +182,17 @@ export function DomMixed<T extends Constructor<DomMixedInstance>>(Base: T) {
         }
 
         /*	Lifecycle events
-        ================================================== */
+	================================================== */
         onLoaded(): void {
-            this.fire("loaded", this.data);
+            this.fire("loaded", this.data as M["loaded"]);
         }
 
         onAdd(): void {
-            this.fire("added", this.data);
+            this.fire("added", this.data as M["added"]);
         }
 
         onRemove(): void {
-            this.fire("removed", this.data);
+            this.fire("removed", this.data as M["removed"]);
         }
 
         constructor(...args: any[]) {

package/src/core/viewers.ts

@@ -0,0 +1,94 @@
+/**
+ * A minimal registry of the viewers alive on this page.
+ *
+ * This is deliberately *not* a viewer singleton: nothing here owns or replaces
+ * a viewer, and the viewer itself holds all of its own state. It exists only
+ * so a viewer can answer the one question it cannot answer alone — "given a
+ * keypress or a focus change on the document, is this viewer the one that
+ * should react?" Two page-wide inputs (the arrow keys and `document.activeElement`)
+ * can only be attributed to a single viewer by comparing against the others.
+ *
+ * Entries are removed in `dispose()`, which is what keeps the registry from
+ * outliving the page content it describes.
+ */
+
+/** What a viewer has to expose to take part in page-wide arbitration. */
+export interface Participant {
+    /** The viewer's root element, or null before layout. */
+    readonly element: HTMLElement | null;
+    /** Higher means more recently interacted. */
+    readonly interaction: number;
+}
+
+/** Monotonic interaction clock. Shared, but it carries no state of its own. */
+let interactionClock = 0;
+
+const participants = new Set<Participant>();
+
+/** Stamp an interaction. Returns the new value, for the caller to store. */
+export function markInteraction(): number {
+    interactionClock += 1;
+    return interactionClock;
+}
+
+/** The interaction value currently held by the most recent participant. */
+function latestInteraction(): number {
+    let latest = -1;
+    for (const participant of participants) {
+        if (participant.interaction > latest) {
+            latest = participant.interaction;
+        }
+    }
+    return latest;
+}
+
+/** Add a viewer. Call from the same place that registers its listeners. */
+export function registerParticipant(participant: Participant): void {
+    participants.add(participant);
+}
+
+/** Remove a viewer. Call from `dispose()`. */
+export function unregisterParticipant(participant: Participant): void {
+    participants.delete(participant);
+}
+
+/** The registered viewer whose element contains `node`, if any. */
+export function participantFor(node: Node | null): Participant | null {
+    if (!node) {
+        return null;
+    }
+    for (const participant of participants) {
+        if (participant.element && participant.element.contains(node)) {
+            return participant;
+        }
+    }
+    return null;
+}
+
+/**
+ * The viewer that should react to a page-wide event.
+ *
+ * Focus wins over recency: if the visitor has focused one viewer, arrow keys
+ * belong to it even if they last clicked a different one. With nothing focused
+ * — the common case, since clicking a `<div>` does not move focus — the most
+ * recently interacted viewer takes it, so the viewer the visitor just used is
+ * the one that responds.
+ *
+ * @param viewer - The viewer asking whether it should react.
+ * @returns True if this viewer owns the event.
+ */
+export function ownsPageEvent(viewer: Participant): boolean {
+    const active = typeof document === "undefined" ? null : document.activeElement;
+    // body (or null) means the visitor has focused nothing viewer-specific
+    const focused = participantFor(active);
+    if (focused) {
+        return focused === viewer;
+    }
+    // no viewer holds focus, so the most recently interacted one responds
+    return viewer.interaction === latestInteraction();
+}
+
+/** The viewers currently registered. Test helper. */
+export function registeredParticipants(): readonly Participant[] {
+    return [...participants];
+}

package/src/dom/DomEvent.ts

@@ -16,6 +16,21 @@ export type LegacyEvent = Event & {
     pageY?: number;
 };
 
+/**
+ * The wrapper is remembered on the target so `removeListener` can find it
+ * again. Keyed by a per-registration counter rather than only by the stamped
+ * function: registering the same function twice for the same event used to
+ * overwrite the key, leaving the first listener permanently unremovable.
+ */
+const registrationCounts = new WeakMap<object, number>();
+
+function handlerKey(obj: DomEventTarget, type: string, fn: (e: Event) => void): string {
+    const target = obj as object;
+    const next = (registrationCounts.get(target) ?? 0) + 1;
+    registrationCounts.set(target, next);
+    return "_vco_" + type + stamp(fn) + "_" + next;
+}
+
 const DomEvent = {
     addListener: function (
         obj: DomEventTarget,
@@ -28,7 +43,7 @@ const DomEvent = {
         };
 
         obj.addEventListener(type, handler, false);
-        (obj as unknown as Record<string, unknown>)["_vco_" + type + stamp(fn)] = handler;
+        (obj as unknown as Record<string, unknown>)[handlerKey(obj, type, fn)] = handler;
     },
 
     removeListener: function (
@@ -37,15 +52,19 @@ const DomEvent = {
         fn: (e: Event) => void,
         context?: unknown,
     ): void {
-        const key = "_vco_" + type + stamp(fn);
-        const handler = (obj as unknown as Record<string, unknown>)[key];
-
-        if (!handler) {
+        // The most recent registration for this (type, fn) pair is the one the
+        // caller means; walk the counter back to find it.
+        const target = obj as unknown as Record<string, unknown>;
+        for (let n = registrationCounts.get(obj as object) ?? 0; n > 0; n--) {
+            const key = "_vco_" + type + stamp(fn) + "_" + n;
+            const handler = target[key];
+            if (!handler) {
+                continue;
+            }
+            obj.removeEventListener(type, handler as EventListener, false);
+            target[key] = null;
             return;
         }
-
-        obj.removeEventListener(type, handler as EventListener, false);
-        (obj as unknown as Record<string, unknown>)[key] = null;
     },
 
     preventDefault: function (e: Event): void {

package/src/globals.d.ts

@@ -11,6 +11,14 @@ declare global {
     const SC: {
         Widget: (el: HTMLElement) => { pause(): void };
     };
+
+    /**
+     * The library version, substituted from package.json by the Vite lib build
+     * (see the `define` in vite.config.ts). Hard-coded here only so the
+     * source type-checks; a dev-server run without the define falls back to
+     * "unknown" at runtime via the typeof guard in StoryMap.
+     */
+    const __STORYMAP_VERSION__: string;
 }
 
 export {};

package/src/language/Language.ts

@@ -1,3 +1,40 @@
+/**
+ * UI strings for the active locale.
+ *
+ * English is the fallback for every missing key (see `getLanguage`), so
+ * `messages` and `buttons` are guaranteed to be fully populated once a
+ * language has been set — they are typed as required here rather than as
+ * `Record<string, string> | undefined` so call sites do not need a null
+ * check on every one of the ~30 `Language.messages.*` reads.
+ *
+ * The locale JSON files themselves are *not* complete: only `en.json` defines
+ * every key, and 28 of the 29 bundled locales are missing 8-10 of them
+ * (the per-service consent strings and the fullscreen button labels). The
+ * runtime falls back to English per key, so this is a translation gap rather
+ * than a defect — `npm run check:locales` reports it.
+ */
+export interface LanguageEntry {
+    /** Display name of the language, e.g. "Deutsch". */
+    name?: string;
+    /** BCP 47 code, e.g. "de". */
+    lang?: string;
+    /** Writing direction; drives the `vco-rtl` layout. */
+    direction?: "ltr" | "rtl";
+    messages: Record<string, string>;
+    buttons: Record<string, string>;
+    [key: string]: unknown;
+}
+
+// The locales are imported statically rather than through `import.meta.glob`
+// on purpose. The viewer reads `Language.messages.*` while it is being
+// constructed — the consent dialog, the RTL class, the swipe hint icon and
+// every button label are all decided synchronously inside `new StoryMap()` —
+// so a locale that has not finished fetching yet would silently render in
+// English. The saving from splitting them is ~6 kB gzip, which is not worth
+// making the language load order-dependent.
+//
+// English remains the fallback for every key a translation is missing (see
+// `getLanguage`), and `npm run check:locales` reports those gaps.
 import be from "./locale/be.json";
 import bg from "./locale/bg.json";
 import cs from "./locale/cs.json";
@@ -28,14 +65,6 @@ import ur from "./locale/ur.json";
 import zhCn from "./locale/zh-cn.json";
 import zhTw from "./locale/zh-tw.json";
 
-interface LanguageEntry {
-    buttons?: Record<string, string>;
-    messages?: Record<string, string>;
-    [key: string]: unknown;
-}
-
-// Static locale map: the bundler-agnostic form of what `import.meta.glob`
-// with `{ eager: true }` desugars to (works in vite dev and rollup builds).
 const localeModules: Record<string, { default?: unknown }> = {
     "./locale/be.json": { default: be },
     "./locale/bg.json": { default: bg },
@@ -68,40 +97,192 @@ const localeModules: Record<string, { default?: unknown }> = {
     "./locale/zh-tw.json": { default: zhTw },
 };
 
+/** The locale every other language falls back to, per key. */
 const EN: Record<string, unknown> =
     (localeModules["./locale/en.json"]?.default as Record<string, unknown> | undefined) || {};
 
-let Language: LanguageEntry = {};
+/** The strings the viewer reads before (or without) a `setLanguage` call. */
+const FALLBACK: LanguageEntry = {
+    name: "English",
+    lang: "en",
+    direction: "ltr",
+    messages: (EN.messages as Record<string, string>) ?? {},
+    buttons: (EN.buttons as Record<string, string>) ?? {},
+};
 
-function getLanguage(code: string): Record<string, unknown> {
-    const lang = structuredClone(
-        (localeModules[`./locale/${code}.json`]?.default as Record<string, unknown> | undefined) ||
-            {},
+let Language: LanguageEntry = FALLBACK;
+
+/**
+ * The locale code last passed to `setLanguage`, defaulting to the fallback.
+ *
+ * Deliberately not derived from `Language.lang`: every bundled locale's `lang`
+ * happens to equal its file name today, but a locale like `pt-BR` would make
+ * the claim comparison below judge two different identifiers for one locale.
+ * Tracking what the caller passed keeps every comparison on one vocabulary.
+ */
+let activeLanguageCode = "en";
+
+/**
+ * Which live viewer owns the page-wide locale.
+ *
+ * `Language` above is a single module-level binding, and every label read in
+ * the viewer goes through it (MenuBar, Message, StorySlider, Consent, Media,
+ * ...). That is deliberate — the strings are read synchronously while a viewer
+ * is constructed — but it means two viewers on one page cannot show different
+ * languages: whichever called `setLanguage` last would win, and the other
+ * would silently keep repainting its chrome in the wrong language.
+ *
+ * Rather than thread a resolved entry down the options chain, the viewer
+ * claims the locale it needs and we fail loudly on a conflict. The claim is
+ * refcounted, so tearing down one of two viewers set in the same language
+ * does not release the page.
+ */
+const languageHolders = new Map<symbol, string>();
+
+/** Why a claim was rejected, for the thrown error. */
+function languageConflict(claimed: string, requested: string): Error {
+    const err = new Error(
+        `StoryMapJS: two viewers on this page asked for different languages ` +
+            `("${claimed}" and "${requested}"), but the UI strings are a single ` +
+            `page-wide setting — the last one set would win and the other viewer ` +
+            `would keep rendering its chrome in the wrong language. Pass the same ` +
+            `language to every viewer on the page, or call refreshLanguage() on ` +
+            `the surviving viewer. See docs/DEVELOPMENT.md, ` +
+            `"Multiple instances on one page".`,
     );
+    // the data may carry its own `language`, and a URL-loaded document claims
+    // asynchronously, where the constructor cannot throw — the name lets the
+    // async load path report the real cause instead of "could not load data"
+    err.name = "StoryMapLanguageConflict";
+    return err;
+}
+
+/** True for the error {@link claimLanguage} throws on a conflicting locale. */
+function isLanguageConflict(err: unknown): boolean {
+    return err instanceof Error && err.name === "StoryMapLanguageConflict";
+}
+
+/**
+ * Claim the page-wide locale for a viewer.
+ *
+ * @param code - The locale code the viewer is about to render.
+ * @param holder - Per-viewer identity; pass the same one to `releaseLanguage`.
+ * @throws If a live holder already claimed a different locale.
+ */
+function claimLanguage(code: string, holder: symbol): void {
+    for (const [existingHolder, existingCode] of languageHolders) {
+        if (existingHolder !== holder && existingCode !== code) {
+            throw languageConflict(existingCode, code);
+        }
+    }
+    languageHolders.set(holder, code);
+}
+
+/**
+ * Release a viewer's claim. The page-wide locale is only released once the
+ * last holder is gone, so a disposed viewer does not free the locale a
+ * sibling is still rendering in.
+ *
+ * @param holder - The identity passed to `claimLanguage`.
+ */
+function releaseLanguage(holder: symbol): void {
+    languageHolders.delete(holder);
+}
+
+/** The locale currently claimed by a live viewer, or null if there is none. */
+function claimedLanguage(): string | null {
+    const codes = new Set(languageHolders.values());
+    return codes.size > 0 ? [...codes][0] : null;
+}
+
+function getLanguage(code: string): Record<string, unknown> {
+    const lang: Record<string, unknown> = {};
+    // start from a deep copy of the English defaults, then layer this locale
+    // on top: a key the translation is missing keeps its English value
     for (const k in EN) {
-        if (lang[k]) {
-            if (typeof EN[k] == "object" && EN[k] !== null && typeof lang[k] == "object") {
-                // fresh object: never mutate the shared English default,
-                // otherwise one setLanguage() call would poison every later
-                // lookup (and every other language falling back to English)
-                lang[k] = Object.assign({}, EN[k] as object, lang[k]);
-            }
+        lang[k] = structuredClone(EN[k]);
+    }
+    const entry = (localeModules[`./locale/${code}.json`]?.default ?? {}) as Record<
+        string,
+        unknown
+    >;
+    applyLanguage(lang, entry);
+    return lang;
+}
+
+/** Merge `entry` over `target`, per key, never mutating the English defaults. */
+function applyLanguage(target: Record<string, unknown>, entry: Record<string, unknown>): void {
+    for (const k in entry) {
+        if (!entry[k]) {
+            continue;
+        }
+        if (typeof EN[k] === "object" && EN[k] !== null && typeof entry[k] === "object") {
+            // fresh object: never mutate the shared English default,
+            // otherwise one setLanguage() call would poison every later
+            // lookup (and every other language falling back to English)
+            target[k] = Object.assign({}, EN[k] as object, entry[k] as object);
         } else {
-            lang[k] = structuredClone(EN[k]);
+            target[k] = structuredClone(entry[k]);
         }
     }
-    return lang;
 }
 
 /**
- * Switch the active UI language.
+ * Switch the active UI language. Synchronous: the viewer resolves its labels
+ * while it is being constructed.
  *
  * @param code - A locale code for which a locale file exists (e.g. `"en"`).
  * @returns The language entry that is now active.
  */
 function setLanguage(code: string): LanguageEntry {
-    Language = getLanguage(code);
+    // recorded before the merge, and unconditionally: a rejected *claim* never
+    // reaches here, so a throw cannot leave the page locale half-switched
+    activeLanguageCode = code;
+    const merged = getLanguage(code);
+    Language = {
+        ...(merged as Omit<LanguageEntry, "messages" | "buttons">),
+        messages: (merged.messages as Record<string, string>) ?? FALLBACK.messages,
+        buttons: (merged.buttons as Record<string, string>) ?? FALLBACK.buttons,
+    };
+    // The page declares the language the viewer actually renders, so
+    // assistive tech pronounces chrome correctly. One effective locale per
+    // page (a second viewer claiming another throws), so this cannot fight
+    // a sibling viewer.
+    if (typeof document !== "undefined") {
+        document.documentElement.setAttribute("lang", code);
+    }
     return Language;
 }
 
-export { setLanguage, Language };
+/**
+ * The locale code the page is currently set to.
+ *
+ * A viewer that was not given a `language` adopts this instead of claiming the
+ * hardcoded `"en"` default, so a host that called `setLanguage("de")` and then
+ * constructed a viewer gets German rather than a conflict with a sibling.
+ */
+function currentLanguageCode(): string {
+    return activeLanguageCode;
+}
+
+/** The active locale's BCP 47 code, for `Intl` formatting. */
+function currentLocale(): string {
+    return typeof Language.lang === "string" && Language.lang !== "" ? Language.lang : "en";
+}
+
+/** True when the active language is written right-to-left. */
+function isRtl(): boolean {
+    return Language.direction === "rtl";
+}
+
+export {
+    setLanguage,
+    Language,
+    currentLocale,
+    isRtl,
+    currentLanguageCode,
+    claimLanguage,
+    releaseLanguage,
+    claimedLanguage,
+    isLanguageConflict,
+};