@projektemacher/storymapjs 0.10.7 → 0.10.8

package/src/core/Util.ts

@@ -1,104 +1,79 @@
 // const debug = true;
 
-export function extend<T extends Record<string, unknown>>(
-    dest: T,
-    ...sources: (Record<string, unknown> | null | undefined)[]
-): T {
-    // merge src properties into dest
-    sources = sources.filter(Boolean);
-    for (let j = 0, len = sources.length, src; j < len; j++) {
-        src = sources[j] || {};
-        for (const i in src) {
-            if (Object.hasOwn(src, i)) {
-                (dest as Record<string, unknown>)[i] = src[i];
-            }
-        }
-    }
-    return dest;
-}
-
-export function convertUnixTime(str: string): string {
-    // created for Instagram. It's ISO8601-ish
-    // 2013-12-09 01:56:28
-    const pattern = /^(\d{4})-(\d{2})-(\d{2})[T\s](\d{2}):(\d{2}):(\d{2})/;
-    const date_parts = str.match(pattern)?.slice(1);
-    if (!date_parts) {
+/**
+ * Format an ISO-8601-ish timestamp (as found in `date.created_time`, originally
+ * from Instagram) as a short, locale-aware date, e.g. "Mar 3, 2013".
+ *
+ * Falls back to the raw input when it does not parse, so an unusual value
+ * shows as-is rather than "Invalid Date".
+ */
+export function convertUnixTime(str: string, locale?: string): string {
+    if (!str) {
         return str;
     }
-    const date_array = [];
-    for (let i = 0; i < date_parts.length; i++) {
-        let val = parseInt(date_parts[i]);
-        if (i === 1) {
-            val = val - 1;
-        } // stupid javascript months
-        date_array.push(val);
+    // "2013-12-09 01:56:28" is not valid ISO-8601 (space instead of "T"), so
+    // normalise it before parsing.
+    const parsed = new Date(/^\d{4}-\d{2}-\d{2} /.test(str) ? str.replace(" ", "T") : str);
+    if (Number.isNaN(parsed.getTime())) {
+        return str;
     }
-    const date = new Date(
-        date_array[0],
-        date_array[1],
-        date_array[2],
-        date_array[3],
-        date_array[4],
-        date_array[5],
-    );
-    const months = [
-        "Jan",
-        "Feb",
-        "Mar",
-        "Apr",
-        "May",
-        "Jun",
-        "Jul",
-        "Aug",
-        "Sep",
-        "Oct",
-        "Nov",
-        "Dec",
-    ];
-    const year = date.getFullYear();
-    const month = months[date.getMonth()];
-    const day = date.getDate();
-    const time = month + ", " + day + " " + year;
-    return time;
+    return parsed.toLocaleDateString(locale ?? "en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
 }
 
-export function setData(obj: { data?: unknown }, data: unknown): void {
-    obj.data = extend(
-        {} as Record<string, unknown>,
-        obj.data as Record<string, unknown> | undefined,
-        data as Record<string, unknown> | undefined,
-    );
-    const stored = obj.data as Record<string, unknown>;
-    if (stored.uniqueid === "") {
-        stored.uniqueid = unique_ID(6);
+/**
+ * Copy the own enumerable properties of `source` onto `target`, limited to
+ * `keys` (or all of the source's keys when omitted). Shared body for the two
+ * public merge helpers below.
+ */
+function copyOwn(
+    target: Record<string, unknown>,
+    source: Record<string, unknown> | null | undefined,
+    keys?: Iterable<string>,
+): void {
+    // `for...in` over a null/undefined source was a silent no-op, and several
+    // call sites pass optional values straight through — keep that behaviour.
+    if (source == null) {
+        return;
     }
-}
-
-export function mergeData<T extends object>(data_main: T, data_to_merge: object): T {
-    const target = data_main as Record<string, unknown>;
-    const source = data_to_merge as Record<string, unknown>;
-    let x;
-    for (x in source) {
-        if (Object.prototype.hasOwnProperty.call(source, x)) {
-            target[x] = source[x];
+    const names = keys ?? Object.keys(source);
+    for (const name of names) {
+        if (Object.prototype.hasOwnProperty.call(source, name)) {
+            target[name] = source[name];
         }
     }
+}
+
+/**
+ * Shallow-assign every own property of `data_to_merge` onto `data_main`.
+ *
+ * Despite the name this is *not* a deep merge, and it must not become one:
+ * every call site merges a partial options object over a defaults object, and
+ * a recursive merge would silently change how nested `map_options` and
+ * `overlays` values are combined.
+ */
+export function mergeData<T extends object>(data_main: T, data_to_merge?: object | null): T {
+    copyOwn(
+        data_main as Record<string, unknown>,
+        data_to_merge as Record<string, unknown> | null | undefined,
+    );
     return data_main;
 }
 
 /**
- *  Like mergeData, except will only try to copy data that already exists
- *  in data_main
+ * Like `mergeData`, but only copies keys that already exist in `data_main`.
+ * This is what lets storymap *data* override a known option without being able
+ * to introduce new ones.
  */
-export function updateData<T extends object>(data_main: T, data_to_merge: object): T {
-    const target = data_main as Record<string, unknown>;
-    const source = data_to_merge as Record<string, unknown>;
-    let x;
-    for (x in data_main) {
-        if (Object.prototype.hasOwnProperty.call(source, x)) {
-            target[x] = source[x];
-        }
-    }
+export function updateData<T extends object>(data_main: T, data_to_merge?: object | null): T {
+    copyOwn(
+        data_main as Record<string, unknown>,
+        data_to_merge as Record<string, unknown> | null | undefined,
+        Object.keys(data_main),
+    );
     return data_main;
 }
 
@@ -112,18 +87,36 @@ export function stamp(obj: object): number {
     return target[_stampKey] as number;
 }
 
+/**
+ * Index of the entry whose `data[prop]` equals `id`, or -1 when there is no
+ * match. Returning -1 matters: a "not found" result of 0 is indistinguishable
+ * from "the first slide", so a bad id silently jumped the story to the start
+ * (contrast StoryMap.goTo, which range-checks).
+ */
 export function findArrayNumberByUniqueID(
     id: unknown,
     array: { data: Record<string, unknown> }[],
     prop: string,
 ): number {
-    let _n = 0;
     for (let i = 0; i < array.length; i++) {
         if (array[i].data[prop] === id) {
-            _n = i;
+            return i;
         }
     }
-    return _n;
+    return -1;
+}
+
+/**
+ * Clear a timer that may be null/undefined and reset the variable.
+ *
+ * `clearTimeout(null)` is a harmless no-op at runtime but not assignable to
+ * the overloads, and forgetting to null the handle afterwards is what lets a
+ * cancelled timer be cleared twice (or, worse, not cleared at all).
+ */
+export function clearTimer(timer: ReturnType<typeof setTimeout> | null | undefined): void {
+    if (timer !== null && timer !== undefined) {
+        clearTimeout(timer);
+    }
 }
 
 export function unique_ID(size: number, prefix?: string): string {
@@ -167,55 +160,153 @@ export function hexToRgb(hex: string): { r: number; g: number; b: number } | nul
 
 // CSS named colors (Colors Level 4) for parseCssColor below.
 const NAMED_COLORS: Record<string, [number, number, number]> = {
-    aliceblue: [240, 248, 255], antiquewhite: [250, 235, 215], aqua: [0, 255, 255],
-    aquamarine: [127, 255, 212], azure: [240, 255, 255], beige: [245, 245, 220],
-    bisque: [255, 228, 196], black: [0, 0, 0], blanchedalmond: [255, 235, 205],
-    blue: [0, 0, 255], blueviolet: [138, 43, 226], brown: [165, 42, 42],
-    burlywood: [222, 184, 135], cadetblue: [95, 158, 160], chartreuse: [127, 255, 0],
-    chocolate: [210, 105, 30], coral: [255, 127, 80], cornflowerblue: [100, 149, 237],
-    cornsilk: [255, 248, 220], crimson: [220, 20, 60], cyan: [0, 255, 255],
-    darkblue: [0, 0, 139], darkcyan: [0, 139, 139], darkgoldenrod: [184, 134, 11],
-    darkgray: [169, 169, 169], darkgreen: [0, 100, 0], darkgrey: [169, 169, 169],
-    darkkhaki: [189, 183, 107], darkmagenta: [139, 0, 139], darkolivegreen: [85, 107, 47],
-    darkorange: [255, 140, 0], darkorchid: [153, 50, 204], darkred: [139, 0, 0],
-    darksalmon: [233, 150, 122], darkseagreen: [143, 188, 143], darkslateblue: [72, 61, 139],
-    darkslategray: [47, 79, 79], darkslategrey: [47, 79, 79], darkturquoise: [0, 206, 209],
-    darkviolet: [148, 0, 211], deeppink: [255, 20, 147], deepskyblue: [0, 191, 255],
-    dimgray: [105, 105, 105], dimgrey: [105, 105, 105], dodgerblue: [30, 144, 255],
-    firebrick: [178, 34, 34], floralwhite: [255, 250, 240], forestgreen: [34, 139, 34],
-    fuchsia: [255, 0, 255], gainsboro: [220, 220, 220], ghostwhite: [248, 248, 255],
-    gold: [255, 215, 0], goldenrod: [218, 165, 32], gray: [128, 128, 128],
-    green: [0, 128, 0], greenyellow: [173, 255, 47], grey: [128, 128, 128],
-    honeydew: [240, 255, 240], hotpink: [255, 105, 180], indianred: [205, 92, 92],
-    indigo: [75, 0, 130], ivory: [255, 255, 240], khaki: [240, 230, 140],
-    lavender: [230, 230, 250], lavenderblush: [255, 240, 245], lawngreen: [124, 252, 0],
-    lemonchiffon: [255, 250, 205], lightblue: [173, 216, 230], lightcoral: [240, 128, 128],
-    lightcyan: [224, 255, 255], lightgoldenrodyellow: [250, 250, 210], lightgray: [211, 211, 211],
-    lightgreen: [144, 238, 144], lightgrey: [211, 211, 211], lightpink: [255, 182, 193],
-    lightsalmon: [255, 160, 122], lightseagreen: [32, 178, 170], lightskyblue: [135, 206, 250],
-    lightslategray: [119, 136, 153], lightslategrey: [119, 136, 153], lightsteelblue: [176, 196, 222],
-    lightyellow: [255, 255, 224], lime: [0, 255, 0], limegreen: [50, 205, 50],
-    linen: [250, 240, 230], magenta: [255, 0, 255], maroon: [128, 0, 0],
-    mediumaquamarine: [102, 205, 170], mediumblue: [0, 0, 205], mediumorchid: [186, 85, 211],
-    mediumpurple: [147, 112, 219], mediumseagreen: [60, 179, 113], mediumslateblue: [123, 104, 238],
-    mediumspringgreen: [0, 250, 154], mediumturquoise: [72, 209, 204], mediumvioletred: [199, 21, 133],
-    midnightblue: [25, 25, 112], mintcream: [245, 255, 250], mistyrose: [255, 228, 225],
-    moccasin: [255, 228, 181], navajowhite: [255, 222, 173], navy: [0, 0, 128],
-    oldlace: [253, 245, 230], olive: [128, 128, 0], olivedrab: [107, 142, 35],
-    orange: [255, 165, 0], orangered: [255, 69, 0], orchid: [218, 112, 214],
-    palegoldenrod: [238, 232, 170], palegreen: [152, 251, 152], paleturquoise: [175, 238, 238],
-    palevioletred: [219, 112, 147], papayawhip: [255, 239, 213], peachpuff: [255, 218, 185],
-    peru: [205, 133, 63], pink: [255, 192, 203], plum: [221, 160, 221],
-    powderblue: [176, 224, 230], purple: [128, 0, 128], rebeccapurple: [102, 51, 153],
-    red: [255, 0, 0], rosybrown: [188, 143, 143], royalblue: [65, 105, 225],
-    saddlebrown: [139, 69, 19], salmon: [250, 128, 114], sandybrown: [244, 164, 96],
-    seagreen: [46, 139, 87], seashell: [255, 245, 238], sienna: [160, 82, 45],
-    silver: [192, 192, 192], skyblue: [135, 206, 235], slateblue: [106, 90, 205],
-    slategray: [112, 128, 144], slategrey: [112, 128, 144], snow: [255, 250, 250],
-    springgreen: [0, 255, 127], steelblue: [70, 130, 180], tan: [210, 180, 140],
-    teal: [0, 128, 128], thistle: [216, 191, 216], tomato: [255, 99, 71],
-    turquoise: [64, 224, 208], violet: [238, 130, 238], wheat: [245, 222, 179],
-    white: [255, 255, 255], whitesmoke: [245, 245, 245], yellow: [255, 255, 0],
+    aliceblue: [240, 248, 255],
+    antiquewhite: [250, 235, 215],
+    aqua: [0, 255, 255],
+    aquamarine: [127, 255, 212],
+    azure: [240, 255, 255],
+    beige: [245, 245, 220],
+    bisque: [255, 228, 196],
+    black: [0, 0, 0],
+    blanchedalmond: [255, 235, 205],
+    blue: [0, 0, 255],
+    blueviolet: [138, 43, 226],
+    brown: [165, 42, 42],
+    burlywood: [222, 184, 135],
+    cadetblue: [95, 158, 160],
+    chartreuse: [127, 255, 0],
+    chocolate: [210, 105, 30],
+    coral: [255, 127, 80],
+    cornflowerblue: [100, 149, 237],
+    cornsilk: [255, 248, 220],
+    crimson: [220, 20, 60],
+    cyan: [0, 255, 255],
+    darkblue: [0, 0, 139],
+    darkcyan: [0, 139, 139],
+    darkgoldenrod: [184, 134, 11],
+    darkgray: [169, 169, 169],
+    darkgreen: [0, 100, 0],
+    darkgrey: [169, 169, 169],
+    darkkhaki: [189, 183, 107],
+    darkmagenta: [139, 0, 139],
+    darkolivegreen: [85, 107, 47],
+    darkorange: [255, 140, 0],
+    darkorchid: [153, 50, 204],
+    darkred: [139, 0, 0],
+    darksalmon: [233, 150, 122],
+    darkseagreen: [143, 188, 143],
+    darkslateblue: [72, 61, 139],
+    darkslategray: [47, 79, 79],
+    darkslategrey: [47, 79, 79],
+    darkturquoise: [0, 206, 209],
+    darkviolet: [148, 0, 211],
+    deeppink: [255, 20, 147],
+    deepskyblue: [0, 191, 255],
+    dimgray: [105, 105, 105],
+    dimgrey: [105, 105, 105],
+    dodgerblue: [30, 144, 255],
+    firebrick: [178, 34, 34],
+    floralwhite: [255, 250, 240],
+    forestgreen: [34, 139, 34],
+    fuchsia: [255, 0, 255],
+    gainsboro: [220, 220, 220],
+    ghostwhite: [248, 248, 255],
+    gold: [255, 215, 0],
+    goldenrod: [218, 165, 32],
+    gray: [128, 128, 128],
+    green: [0, 128, 0],
+    greenyellow: [173, 255, 47],
+    grey: [128, 128, 128],
+    honeydew: [240, 255, 240],
+    hotpink: [255, 105, 180],
+    indianred: [205, 92, 92],
+    indigo: [75, 0, 130],
+    ivory: [255, 255, 240],
+    khaki: [240, 230, 140],
+    lavender: [230, 230, 250],
+    lavenderblush: [255, 240, 245],
+    lawngreen: [124, 252, 0],
+    lemonchiffon: [255, 250, 205],
+    lightblue: [173, 216, 230],
+    lightcoral: [240, 128, 128],
+    lightcyan: [224, 255, 255],
+    lightgoldenrodyellow: [250, 250, 210],
+    lightgray: [211, 211, 211],
+    lightgreen: [144, 238, 144],
+    lightgrey: [211, 211, 211],
+    lightpink: [255, 182, 193],
+    lightsalmon: [255, 160, 122],
+    lightseagreen: [32, 178, 170],
+    lightskyblue: [135, 206, 250],
+    lightslategray: [119, 136, 153],
+    lightslategrey: [119, 136, 153],
+    lightsteelblue: [176, 196, 222],
+    lightyellow: [255, 255, 224],
+    lime: [0, 255, 0],
+    limegreen: [50, 205, 50],
+    linen: [250, 240, 230],
+    magenta: [255, 0, 255],
+    maroon: [128, 0, 0],
+    mediumaquamarine: [102, 205, 170],
+    mediumblue: [0, 0, 205],
+    mediumorchid: [186, 85, 211],
+    mediumpurple: [147, 112, 219],
+    mediumseagreen: [60, 179, 113],
+    mediumslateblue: [123, 104, 238],
+    mediumspringgreen: [0, 250, 154],
+    mediumturquoise: [72, 209, 204],
+    mediumvioletred: [199, 21, 133],
+    midnightblue: [25, 25, 112],
+    mintcream: [245, 255, 250],
+    mistyrose: [255, 228, 225],
+    moccasin: [255, 228, 181],
+    navajowhite: [255, 222, 173],
+    navy: [0, 0, 128],
+    oldlace: [253, 245, 230],
+    olive: [128, 128, 0],
+    olivedrab: [107, 142, 35],
+    orange: [255, 165, 0],
+    orangered: [255, 69, 0],
+    orchid: [218, 112, 214],
+    palegoldenrod: [238, 232, 170],
+    palegreen: [152, 251, 152],
+    paleturquoise: [175, 238, 238],
+    palevioletred: [219, 112, 147],
+    papayawhip: [255, 239, 213],
+    peachpuff: [255, 218, 185],
+    peru: [205, 133, 63],
+    pink: [255, 192, 203],
+    plum: [221, 160, 221],
+    powderblue: [176, 224, 230],
+    purple: [128, 0, 128],
+    rebeccapurple: [102, 51, 153],
+    red: [255, 0, 0],
+    rosybrown: [188, 143, 143],
+    royalblue: [65, 105, 225],
+    saddlebrown: [139, 69, 19],
+    salmon: [250, 128, 114],
+    sandybrown: [244, 164, 96],
+    seagreen: [46, 139, 87],
+    seashell: [255, 245, 238],
+    sienna: [160, 82, 45],
+    silver: [192, 192, 192],
+    skyblue: [135, 206, 235],
+    slateblue: [106, 90, 205],
+    slategray: [112, 128, 144],
+    slategrey: [112, 128, 144],
+    snow: [255, 250, 250],
+    springgreen: [0, 255, 127],
+    steelblue: [70, 130, 180],
+    tan: [210, 180, 140],
+    teal: [0, 128, 128],
+    thistle: [216, 191, 216],
+    tomato: [255, 99, 71],
+    turquoise: [64, 224, 208],
+    violet: [238, 130, 238],
+    wheat: [245, 222, 179],
+    white: [255, 255, 255],
+    whitesmoke: [245, 245, 245],
+    yellow: [255, 255, 0],
     yellowgreen: [154, 205, 50],
 };
 
@@ -263,6 +354,19 @@ export function slideTransitionDuration(from: number, to: number): number {
     return Math.max(600, Math.min(1000 + steps * 120, 2000));
 }
 
+/**
+ * True when the user prefers reduced motion
+ * (`prefers-reduced-motion: reduce`) — slide/map glides collapse to
+ * instant changes and autoplay stays off.
+ */
+export function prefersReducedMotion(): boolean {
+    return (
+        typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    );
+}
+
 export function htmlify(str: string): string {
     //if (str.match(/<\s*p[^>]*>([^<]*)<\s*\/\s*p\s*>/)) {
     if (str.match(/<p>[\s\S]*?<\/p>/)) {
@@ -272,69 +376,27 @@ export function htmlify(str: string): string {
     }
 }
 
-export function getUrlVars(string: string): string[] & Record<string, string> {
-    let str: string, hash: string[];
-    const vars: string[] = [];
-    str = string.toString();
-    if (str.match("&#038;")) {
-        str = str.replace("&#038;", "&");
-    } else if (str.match("&#38;")) {
-        str = str.replace("&#38;", "&");
-    } else if (str.match("&amp;")) {
-        str = str.replace("&amp;", "&");
-    }
-    const hashes = str.slice(str.indexOf("?") + 1).split("&");
-    for (let i = 0; i < hashes.length; i++) {
-        hash = hashes[i].split("=");
-        vars.push(hash[0]);
-        (vars as unknown as Record<string, string>)[hash[0]] = hash[1];
-    }
-    return vars as string[] & Record<string, string>;
-}
-
 export const ratio = {
+    /**
+     * The 16:9 height for a given width, or the 16:9 width for a given
+     * height. Returns 0 when neither is a usable number.
+     *
+     * The old guards were `!== null && !== ""`, which an `undefined` passes
+     * through — so a caller that omitted `w` computed `Math.round(NaN)` and
+     * wrote `height: "NaNpx"`. A `typeof === "number"` check is what the
+     * arithmetic actually needs.
+     */
     r16_9: function (size: { w?: number; h?: number }): number {
-        if (size.w !== null && (size.w as unknown as string) !== "") {
+        if (typeof size.w === "number" && isFinite(size.w)) {
             return Math.round((size.w / 16) * 9);
-        } else if (size.h !== null && (size.h as unknown as string) !== "") {
+        }
+        if (typeof size.h === "number" && isFinite(size.h)) {
             return Math.round((size.h / 9) * 16);
-        } else {
-            return 0;
         }
+        return 0;
     },
 };
 
-export function urljoin(base_url: string, path: string): string {
-    if (base_url.length && base_url.at(-1) === "/") {
-        base_url = base_url.substring(0, base_url.length - 1);
-    }
-    if (path.length && path[0] === "/") {
-        path = path.substring(1);
-    }
-    const url1 = base_url.split("/");
-    const url2 = path.split("/");
-    const url3 = [];
-    for (let i = 0, l = url1.length; i < l; i++) {
-        if (url1[i] === "..") {
-            url3.pop();
-        } else if (url1[i] === ".") {
-            continue;
-        } else {
-            url3.push(url1[i]);
-        }
-    }
-    for (let i = 0, l = url2.length; i < l; i++) {
-        if (url2[i] === "..") {
-            url3.pop();
-        } else if (url2[i] === ".") {
-            continue;
-        } else {
-            url3.push(url2[i]);
-        }
-    }
-    return url3.join("/");
-}
-
 export function getObjectAttributeByIndex(
     obj: Record<string, unknown> | undefined,
     index: number,

package/src/core/mixins.ts

@@ -16,9 +16,17 @@ export interface EventedInstance {
     hasEventListeners: (type: string) => boolean;
 }
 
-/** Instance contract for DomMixed consumers. */
+/**
+ * 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 extends EventedInstance {
-    _el: Record<string, HTMLElement>;
+    _el: Record<string, unknown>;
     data?: unknown;
 }
 
@@ -115,27 +123,36 @@ export function Evented<T extends Constructor>(Base: T) {
  *  and the onAdd/onRemove/onLoaded lifecycle events) to a class. */
 export function DomMixed<T extends Constructor<DomMixedInstance>>(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 +160,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";
             }

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];
+}