@projektemacher/storymapjs 0.10.8 → 0.11.0

package/schema/storymap.schema.json

@@ -138,6 +138,18 @@
                             "attribution": {
                                 "type": "string"
                             },
+                            "label": {
+                                "type": "string",
+                                "description": "Layer switcher row label (defaults to map_type)"
+                            },
+                            "locked": {
+                                "type": "boolean",
+                                "description": "Render the switcher row checked and disabled"
+                            },
+                            "control": {
+                                "type": "boolean",
+                                "description": "False hides the row from the switcher without removing the overlay"
+                            },
                             "className": {
                                 "type": "string",
                                 "description": "CSS class of the layer container, isolating it from the shared ol-layer canvas (e.g. for blend modes)"
@@ -262,11 +274,83 @@
                         },
                         "attribution": {
                             "type": "string"
+                        },
+                        "width": {
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                            "description": "Canvas width in pixels, enabling region clamping and the static fallback without another fetch"
+                        },
+                        "height": {
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                            "description": "Canvas height in pixels, enabling region clamping and the static fallback without another fetch"
+                        },
+                        "fallbackUrl": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "Full-size image used when info.json cannot be loaded (slideshow image_static)"
                         }
                     }
                 },
+                "tilejson": {
+                    "type": "object",
+                    "description": "TileJSON source for the base layer: tiles becomes the map_type template, the rest constrains the source/view where the map can act on it",
+                    "required": ["tiles"],
+                    "properties": {
+                        "tiles": {
+                            "anyOf": [
+                                { "type": "string" },
+                                { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+                            ]
+                        },
+                        "minzoom": { "type": "number" },
+                        "maxzoom": { "type": "number" },
+                        "bounds": {
+                            "type": "array",
+                            "items": { "type": "number" },
+                            "minItems": 4,
+                            "maxItems": 4
+                        },
+                        "scheme": { "type": "string", "enum": ["xyz", "tms"] },
+                        "center": {
+                            "type": "array",
+                            "items": { "type": "number" },
+                            "minItems": 3,
+                            "maxItems": 3
+                        }
+                    }
+                },
+                "see_also": {
+                    "type": "array",
+                    "description": "seeAlso targets recorded from a IIIF manifest (annotation collections/pages); recorded but not fetched on load",
+                    "items": {
+                        "type": "object",
+                        "required": ["id", "type"],
+                        "properties": {
+                            "id": { "type": "string" },
+                            "type": { "type": "string" }
+                        }
+                    }
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Story title carried by IIIF manifests (label) and slideshow tours; extra on legacy documents"
+                },
+                "metadata": {
+                    "type": "array",
+                    "description": "Label/value pairs carried from a IIIF manifest or slideshow tour; data-only, handed on as data.metadata[]"
+                },
+                "logo": {
+                    "description": "Publisher logo carried from a IIIF manifest; data-only, offered as data.logo"
+                },
                 "font_css": {
-                    "type": "string"
+                    "anyOf": [{ "type": "string" }, { "const": false }],
+                    "description": "Font theme stylesheet (stock:<name> or URL); false disables the injected stylesheet because the host bundles the theme itself"
+                },
+                "theme": {
+                    "type": "string",
+                    "enum": ["dark", "light"],
+                    "description": "Colour theme: dark forces the dark palette, light pins the light one; unset follows prefers-color-scheme"
                 },
                 "call_to_action": {
                     "type": "boolean"
@@ -286,6 +370,38 @@
                 "show_progress": {
                     "type": "boolean"
                 },
+                "progressbar": {
+                    "anyOf": [
+                        { "type": "boolean" },
+                        {
+                            "type": "string",
+                            "enum": ["bar", "dots", "squares", "block", "thinblock", "off"]
+                        }
+                    ],
+                    "description": "Progress indicator style (slideshow progressbar): false/off hides it, true/bar is the classic fill bar, dots/squares render one step per slide, block/thinblock are fill-bar height variants. Absent means show_progress decides with the bar style. Honored only with slideshow_source."
+                },
+                "show_layers_control": {
+                    "type": "boolean",
+                    "description": "Show the basemap/overlay switcher in the menubar"
+                },
+                "basemaps": {
+                    "type": "array",
+                    "description": "Selectable base maps for the layer switcher; entry 0 is the initial basemap unless map_type says otherwise",
+                    "items": {
+                        "type": "object",
+                        "required": ["map_type"],
+                        "properties": {
+                            "map_type": {
+                                "type": "string",
+                                "description": "Any map_type value"
+                            },
+                            "label": {
+                                "type": "string",
+                                "description": "Control row label (defaults to map_type)"
+                            }
+                        }
+                    }
+                },
                 "show_distance": {
                     "type": "boolean"
                 },
@@ -297,6 +413,62 @@
                     "enum": ["left", "center", "right"],
                     "description": "Default horizontal alignment for slide text"
                 },
+                "textmode": {
+                    "type": "string",
+                    "enum": ["left", "right", "bottom"],
+                    "description": "Slide panel dock (slideshow textmode) in landscape: right (default) is the current layout, left mirrors it, bottom docks the panel below the map. Portrait layouts always behave like bottom. Honored only with slideshow_source."
+                },
+                "textsize": {
+                    "type": "number",
+                    "minimum": 10,
+                    "maximum": 80,
+                    "description": "Slide panel size as a percentage (slideshow textsize): percent of the width for side docks, of the height for the bottom dock. Absent keeps the built-in 50/50 split. Honored only with slideshow_source."
+                },
+                "fxmode": {
+                    "type": "string",
+                    "enum": ["slide", "fade", "none"],
+                    "description": "Slide transition effect (slideshow fxmode): slide (default) is the current glide, fade cross-fades slides, none jumps without animation. prefers-reduced-motion still forces none. Honored only with slideshow_source."
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": ["standard", "static"],
+                    "description": "Reading mode (slideshow mode): standard (default) is the slider; static stacks all slides in a scrollable list and follows the map to the slide in view. Honored only with slideshow_source."
+                },
+                "hudcolor": {
+                    "type": "string",
+                    "description": "HUD foreground color override (slideshow hudcolor). Honored only with slideshow_source."
+                },
+                "hudbgcolor": {
+                    "type": "string",
+                    "description": "HUD background color override (slideshow hudbgcolor). Honored only with slideshow_source."
+                },
+                "hudopacity": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100,
+                    "description": "HUD opacity percent 0..100 (slideshow hudopacity), applied to the HUD background. Honored only with slideshow_source."
+                },
+                "shownav": {
+                    "type": "boolean",
+                    "description": "Show the previous/next slide navigation (slideshow shownav). Default true. Honored only with slideshow_source."
+                },
+                "show_headings": {
+                    "type": "boolean",
+                    "description": "Render slide headlines (slideshow showheadings). Default true; false hides headline elements. Honored only with slideshow_source."
+                },
+                "show_scrollbars": {
+                    "type": "boolean",
+                    "description": "Show scrollbars in the slide panel (slideshow showscrollbars). Default true; false hides them (content still scrolls). Honored only with slideshow_source."
+                },
+                "viewerheight": {
+                    "type": "string",
+                    "pattern": "^[0-9]+(\\.[0-9]+)?(px|%|vh)$",
+                    "description": "Fixed viewer height (slideshow viewerheight), e.g. 400px: applied as a container height override when set. Honored only with slideshow_source."
+                },
+                "show_info": {
+                    "type": "boolean",
+                    "description": "Show media captions and credits (slideshow showinfo). Default true; false hides the caption/credit block. Honored only with slideshow_source."
+                },
                 "text_color": {
                     "type": "string"
                 },
@@ -355,6 +527,15 @@
                         "$ref": "#/$defs/slide"
                     }
                 },
+                "credit": {
+                    "type": "object",
+                    "description": "Authorship and rights for the story (slideshow creator/rights); rendered into the map attribution line for slideshow tours.",
+                    "properties": {
+                        "creator": { "type": "string" },
+                        "rights": { "type": "string" },
+                        "licenseUrl": { "type": "string", "format": "uri" }
+                    }
+                },
                 "layout": {
                     "type": "string",
                     "enum": ["landscape", "portrait"],
@@ -364,6 +545,58 @@
         }
     },
     "$defs": {
+        "media": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": ["string", "null"]
+                },
+                "caption": {
+                    "type": ["string", "null"]
+                },
+                "credit": {
+                    "type": ["string", "null"]
+                },
+                "thumb": {
+                    "type": "string"
+                },
+                "alt": {
+                    "type": "string"
+                },
+                "srcset": {
+                    "type": "string"
+                },
+                "sizes": {
+                    "type": "string"
+                },
+                "subtitles": {
+                    "type": ["string", "null"],
+                    "format": "uri",
+                    "description": "WebVTT subtitle file for an audio or video slide, rendered as a <track kind=\"subtitles\">."
+                },
+                "offset": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Start offset in seconds for audio/video media (slideshow audio.offset). Honored only with slideshow_source"
+                },
+                "loop": {
+                    "type": "boolean",
+                    "description": "Loop audio/video media (slideshow audio.loop). Honored only with slideshow_source"
+                },
+                "play": {
+                    "type": "string",
+                    "enum": ["auto", "click"],
+                    "description": "auto plays on activation; click arms paused for the visitor to start. Honored only with slideshow_source"
+                },
+                "stopOnExit": {
+                    "type": "boolean",
+                    "description": "Stop this media when leaving the slide (default true); false lets an audio bed continue. Honored only with slideshow_source"
+                },
+                "mediatype": {
+                    "type": ["object", "null"]
+                }
+            }
+        },
         "slide": {
             "type": "object",
             "properties": {
@@ -399,7 +632,41 @@
                             },
                             "minItems": 4,
                             "maxItems": 4,
-                            "description": "Image region [x, y, w, h] in image pixels (IIIF xywh convention) for image maps; the view fits the region on navigation"
+                            "description": "Image region [x, y, w, h] in image pixels (IIIF xywh convention) for image maps; the view fits the region on navigation. Negative origins are clamped to the canvas."
+                        },
+                        "rotation": {
+                            "type": "number",
+                            "description": "View rotation in degrees clockwise (slideshow rotation); absent means north-up. Honored only with slideshow_source"
+                        },
+                        "filter": {
+                            "type": "object",
+                            "description": "Per-slide image grading (slideshow filters), applied as a CSS filter() on the map viewport. Honored only with slideshow_source",
+                            "properties": {
+                                "brightness": { "type": "number", "minimum": 0, "maximum": 200 },
+                                "contrast": { "type": "number", "minimum": 0, "maximum": 200 },
+                                "saturate": { "type": "number", "minimum": 0, "maximum": 200 },
+                                "hueRotate": { "type": "number", "minimum": -180, "maximum": 180 },
+                                "sepia": { "type": "number", "minimum": 0, "maximum": 100 },
+                                "blur": { "type": "number", "minimum": 0, "maximum": 20 }
+                            }
+                        },
+                        "mask": {
+                            "type": "object",
+                            "description": "Spotlight mask (slideshow passepartout): normalized viewport fractions left visible while the rest is dimmed. Honored only with slideshow_source",
+                            "required": ["x", "y", "w", "h"],
+                            "properties": {
+                                "x": { "type": "number" },
+                                "y": { "type": "number" },
+                                "w": { "type": "number", "exclusiveMinimum": 0 },
+                                "h": { "type": "number", "exclusiveMinimum": 0 },
+                                "color": { "type": "string" },
+                                "invert": { "type": "boolean" },
+                                "opacity": { "type": "number", "minimum": 0, "maximum": 1 }
+                            }
+                        },
+                        "basemap": {
+                            "type": "string",
+                            "description": "Per-slide basemap override (multi-manifest tours): any map_type value or IIIF info.json URL. Absent keeps the story basemap. Honored only with slideshow_source."
                         },
                         "zoom": {
                             "type": "number"
@@ -432,39 +699,20 @@
                     }
                 },
                 "media": {
-                    "type": "object",
-                    "properties": {
-                        "url": {
-                            "type": ["string", "null"]
-                        },
-                        "caption": {
-                            "type": ["string", "null"]
-                        },
-                        "credit": {
-                            "type": ["string", "null"]
-                        },
-                        "thumb": {
-                            "type": "string"
-                        },
-                        "alt": {
-                            "type": "string"
-                        },
-                        "srcset": {
-                            "type": "string"
-                        },
-                        "sizes": {
-                            "type": "string"
-                        },
-                        "subtitles": {
-                            "type": ["string", "null"],
-                            "format": "uri",
-                            "description": "WebVTT subtitle file for an audio or video slide, rendered as a <track kind=\"subtitles\">."
-                        },
-                        "mediatype": {
-                            "type": ["object", "null"]
-                        }
+                    "$ref": "#/$defs/media"
+                },
+                "media_extra": {
+                    "type": ["array", "null"],
+                    "description": "Additional visible media for this slide (#358), rendered after media in order. Items without a non-empty url are skipped. In a IIIF manifest these are further painting annotations on the canvas.",
+                    "items": {
+                        "$ref": "#/$defs/media"
                     }
                 },
+                "media_layout": {
+                    "type": "string",
+                    "enum": ["stack", "row"],
+                    "description": "Layout of a multi-media slide (#358): stack piles the items vertically (the panel scrolls), row puts two items side by side. Defaults to stack; row with anything but two items falls back to stack."
+                },
                 "text": {
                     "type": "object",
                     "properties": {
@@ -515,11 +763,54 @@
                 },
                 "narration": {
                     "type": ["object", "null"],
-                    "description": "Spoken narration for this slide, played through a dedicated audio element. Storymap JSON only: in a IIIF manifest the closest spelling is a Sound body, which currently lands in media.url rather than here.",
+                    "description": "Spoken narration for this slide, played through a dedicated audio element. In a IIIF manifest this is a motivation: supplementing Sound/Video body, read and written alongside the painting annotation.",
                     "properties": {
                         "url": {
                             "type": "string",
                             "format": "uri"
+                        },
+                        "loop": {
+                            "type": "boolean",
+                            "description": "Loop the narration (slideshow audio.loop). Honored only with slideshow_source"
+                        },
+                        "offset": {
+                            "type": "number",
+                            "minimum": 0,
+                            "description": "Start offset in seconds (slideshow audio.offset). Honored only with slideshow_source"
+                        },
+                        "play": {
+                            "type": "string",
+                            "enum": ["auto", "click"],
+                            "description": "auto plays on navigation; click arms paused for the visitor to start (slideshow audio.play). Honored only with slideshow_source"
+                        },
+                        "stopOnExit": {
+                            "type": "boolean",
+                            "description": "Stop when leaving the slide (default true); false keeps an audio bed across slides while the URL is unchanged. Honored only with slideshow_source"
+                        },
+                        "stopAllPrevious": {
+                            "type": "boolean",
+                            "description": "Stop any other playing track before starting (default true); false allows ambient overlap. Honored only with slideshow_source"
+                        }
+                    },
+                    "required": ["url"]
+                },
+                "slidetimeout": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Per-slide autoplay dwell in milliseconds (slideshow slidetimeout): overrides the global autoplay interval for this slide; 0 holds. Absent means the global interval. Honored only with slideshow_source."
+                },
+                "imgoverlay": {
+                    "anyOf": [{ "type": "object" }, { "type": "null" }],
+                    "description": "Per-slide image overlay on the map (slideshow imgoverlay), shown while this slide is active. Honored only with slideshow_source",
+                    "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "size": { "type": "number", "exclusiveMinimum": 0 },
+                        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
+                        "extent": {
+                            "type": "array",
+                            "items": { "type": "number" },
+                            "minItems": 4,
+                            "maxItems": 4
                         }
                     },
                     "required": ["url"]
@@ -542,6 +833,15 @@
                 },
                 "uniqueid": {
                     "type": "string"
+                },
+                "provenance": {
+                    "type": "object",
+                    "description": "Provenance identifiers for the slide's source (slideshow manifest/canvas/image ids). Data-only, never rendered.",
+                    "properties": {
+                        "manifest": { "type": "string", "format": "uri" },
+                        "canvas": { "type": "string", "format": "uri" },
+                        "image": { "type": "string", "format": "uri" }
+                    }
                 }
             }
         }

package/src/core/Util.ts

@@ -359,11 +359,13 @@ export function slideTransitionDuration(from: number, to: number): number {
  * (`prefers-reduced-motion: reduce`) — slide/map glides collapse to
  * instant changes and autoplay stays off.
  */
+export const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+
 export function prefersReducedMotion(): boolean {
     return (
         typeof window !== "undefined" &&
         typeof window.matchMedia === "function" &&
-        window.matchMedia("(prefers-reduced-motion: reduce)").matches
+        window.matchMedia(REDUCED_MOTION_QUERY).matches
     );
 }
 

package/src/core/mixins.ts

@@ -8,12 +8,29 @@
 /** 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;
 }
 
 /**
@@ -25,7 +42,7 @@ export interface EventedInstance {
  * 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 {
+export interface DomMixedInstance<M = Record<string, unknown>> extends EventedInstance<M> {
     _el: Record<string, unknown>;
     data?: unknown;
 }
@@ -36,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 }[]>;
 
@@ -70,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 = (
@@ -111,7 +122,7 @@ export function Evented<T extends Constructor>(Base: T) {
         constructor(...args: any[]) {
             super(...args);
         }
-    };
+    } as Constructor<EventedInstance<M>> & T;
 }
 
 /*	DomMixed
@@ -121,7 +132,10 @@ 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
@@ -168,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/language/Language.ts

@@ -244,6 +244,13 @@ function setLanguage(code: string): LanguageEntry {
         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;
 }