@projektemacher/storymapjs 0.10.7 → 0.10.8

package/src/storymap/validate.ts

@@ -27,6 +27,10 @@ interface SchemaNode {
     items?: SchemaNode;
     required?: string[];
     properties?: Record<string, SchemaNode>;
+    /** Value must satisfy at least one of these. */
+    anyOf?: SchemaNode[];
+    /** Annotation only — see `formatMatches`. */
+    format?: string;
     [key: string]: unknown;
 }
 
@@ -50,14 +54,46 @@ function typeMatches(value: unknown, type: string | string[]): boolean {
                 return typeof value === "boolean";
             case "null":
                 return value === null;
-            case "uri":
-                return typeof value === "string";
             default:
                 return true;
         }
     });
 }
 
+/**
+ * JSON Schema `format` is an annotation by default, so it is only checked
+ * where it costs nothing. The schema uses it twice, both for icon/image URLs.
+ * Note this was previously listed as a *type* in `typeMatches`, where it was
+ * unreachable: `typeMatches` is only ever called with `schemaNode.type`.
+ */
+/**
+ * A malformed `pattern` in the schema used to throw straight out of
+ * validation, aborting `new StoryMap(...)` instead of reporting an error.
+ */
+function safeRegExp(pattern: string, value: string): boolean {
+    try {
+        return new RegExp(pattern).test(value);
+    } catch {
+        // an unusable pattern must not make the document fail to load
+        return true;
+    }
+}
+
+function formatMatches(value: unknown, format: string): boolean {
+    if (typeof value !== "string") {
+        return true;
+    }
+    if (format === "uri" || format === "uri-reference") {
+        try {
+            new URL(value, "https://example.invalid/");
+            return true;
+        } catch {
+            return false;
+        }
+    }
+    return true;
+}
+
 function validateAgainstSchema(
     value: unknown,
     schemaNode: SchemaNode,
@@ -78,6 +114,36 @@ function validateAgainstSchema(
         return;
     }
 
+    // anyOf — the schema uses it for map_bbox, map_overview_center and the
+    // legacy zoomify block. It was not implemented at all, so those three
+    // fields (including map_bbox's "exactly 4 numbers" rule) were accepted
+    // completely unvalidated at runtime and by the CLI.
+    if (schemaNode.anyOf) {
+        // try each branch into a scratch error list; the value is valid if any
+        // branch accepts it
+        const branchErrors: StorymapError[][] = schemaNode.anyOf.map((branch) => {
+            const collected: StorymapError[] = [];
+            validateAgainstSchema(value, branch, path, collected);
+            return collected;
+        });
+        const anyOfValid = branchErrors.some((collected) => collected.length === 0);
+        if (!anyOfValid) {
+            // report the closest branch: the most likely intent
+            let best = branchErrors[0] ?? [];
+            for (const candidate of branchErrors) {
+                if (candidate.length > 0 && candidate.length < best.length) {
+                    best = candidate;
+                }
+            }
+            errors.push(...best);
+            errors.push({
+                path,
+                message: `must match one of the ${schemaNode.anyOf.length} allowed shapes`,
+            });
+            return;
+        }
+    }
+
     // type
     if (schemaNode.type) {
         if (!typeMatches(value, schemaNode.type)) {
@@ -115,11 +181,19 @@ function validateAgainstSchema(
         if (schemaNode.minLength !== undefined && value.length < schemaNode.minLength) {
             errors.push({ path, message: `must be at least ${schemaNode.minLength} characters` });
         }
-        if (schemaNode.pattern !== undefined && !new RegExp(schemaNode.pattern).test(value)) {
+        if (schemaNode.maxLength !== undefined && value.length > schemaNode.maxLength) {
+            errors.push({ path, message: `must be at most ${schemaNode.maxLength} characters` });
+        }
+        if (schemaNode.pattern !== undefined && !safeRegExp(schemaNode.pattern, value)) {
             errors.push({ path, message: `must match ${schemaNode.pattern}` });
         }
     }
 
+    // format (annotation)
+    if (schemaNode.format && !formatMatches(value, schemaNode.format)) {
+        errors.push({ path, message: `must be a valid ${schemaNode.format}` });
+    }
+
     // array constraints
     if (Array.isArray(value)) {
         if (schemaNode.minItems !== undefined && value.length < schemaNode.minItems) {
@@ -128,10 +202,9 @@ function validateAgainstSchema(
         if (schemaNode.maxItems !== undefined && value.length > schemaNode.maxItems) {
             errors.push({ path, message: `must have at most ${schemaNode.maxItems} items` });
         }
-        if (schemaNode.items) {
-            value.forEach((item, i) =>
-                validateAgainstSchema(item, schemaNode.items, `${path}[${i}]`, errors),
-            );
+        const items = schemaNode.items;
+        if (items) {
+            value.forEach((item, i) => validateAgainstSchema(item, items, `${path}[${i}]`, errors));
         }
     }
 

package/src/types.ts

@@ -1,4 +1,7 @@
 // Shared types for the StoryMapJS codebase.
+import type { Tile as TileLayer } from "ol/layer";
+import type Layer from "ol/layer/Layer";
+import type Source from "ol/source/Source";
 
 // ---------- Storymap data (exchange format) ----------
 
@@ -12,6 +15,12 @@ export interface StorymapSlideLocation {
     lat?: number;
     lon?: number;
     zoom?: number;
+    /**
+     * Image region `[x, y, w, h]` in image pixels (IIIF xywh convention,
+     * StrollView-style image stops): the view fits the region on
+     * navigation; image maps (`map_type: "iiif"` + `map_as_image`) only.
+     */
+    region?: [number, number, number, number];
     line?: boolean;
     icon?: string;
     iconSize?: number[];
@@ -32,8 +41,56 @@ export interface StorymapSlideMedia {
     url?: string | null;
     caption?: string | null;
     credit?: string | null;
+    /**
+     * Accessible description of the media, used as the image's `alt` when the
+     * media is an image. In IIIF this is the painting annotation's
+     * `accessibilitySummary`.
+     */
+    alt?: string | null;
     thumb?: string | null;
     mediatype?: MediaTypeMatch | null;
+    /**
+     * WebVTT subtitle file for an audio or video slide, rendered as a
+     * `<track kind="subtitles">`. IIIF has no subtitle term, so this stays a
+     * storymap-JSON field; the authoring guide notes the
+     * `TextualBody` + `format: text/vtt` shape we also accept.
+     */
+    subtitles?: string | null;
+    [key: string]: unknown;
+}
+
+/**
+ * Optional spoken narration for one slide, played through a dedicated audio
+ * element rather than the slide's media frame — a tour stop usually has a
+ * picture and a recording, not one media item. Storymap JSON only: the
+ * closest manifest spelling is a `Sound` body, which currently lands in
+ * `media.url` rather than here.
+ */
+/**
+ * Per-slide marker presentation, consolidated. `location.*` keeps working as
+ * the legacy spelling and `marker.*` wins when present — see
+ * docs/plans/iiif-media-tours.md §2.
+ *
+ * In a IIIF manifest none of this is a `storymap:` term: it all arrives in the
+ * `navPlace` Feature's `properties` bag (`icon`, `iconSize`, `image`, `name`,
+ * `popup`, `audioBadge`), which is a GeoJSON foreign-member bag and so needs
+ * no vocabulary registration.
+ */
+export interface StorymapSlideMarker {
+    icon?: string;
+    iconSize?: number[];
+    image?: string;
+    /** The marker label; in a manifest this is `properties.name`. */
+    label?: string;
+    /** Show the popup card when this (active) marker is clicked. */
+    popup?: boolean;
+    /** Mark slides that carry narration or audio media with a small badge. */
+    audioBadge?: boolean;
+    [key: string]: unknown;
+}
+
+export interface StorymapSlideNarration {
+    url: string;
     [key: string]: unknown;
 }
 
@@ -43,15 +100,33 @@ export interface StorymapSlideBackground {
     opacity?: number;
 }
 
+/**
+ * One slide of a storymap.
+ *
+ * The nullable members (`| null`) are not decoration: the storymap JSON uses
+ * `null` to mean "explicitly absent" and the viewer seeds its own defaults
+ * with `null` before the data is merged in, so a plain `?` would not type.
+ */
 export interface StorymapSlide {
     type?: string;
     date?: string | Record<string, unknown> | null;
     group?: string;
-    location?: StorymapSlideLocation;
-    media?: StorymapSlideMedia;
-    text?: StorymapSlideText;
+    /**
+     * The language tag this slide's text was read in (§3.4 of
+     * docs/plans/iiif-interop.md). A IIIF manifest states its text as a
+     * language map; the reader picks the viewer's configured language and
+     * reports which one it used, so a host can offer a language switch.
+     * Absent for language-neutral (`none`) text, and for a single-language
+     * storymap.
+     */
+    language?: string;
+    location?: StorymapSlideLocation | null;
+    media?: StorymapSlideMedia | null;
+    marker?: StorymapSlideMarker | null;
+    narration?: StorymapSlideNarration | null;
+    text?: StorymapSlideText | null;
     background?: StorymapSlideBackground | string | null;
-    uniqueid?: string;
+    uniqueid?: string | null;
     [key: string]: unknown;
 }
 
@@ -67,6 +142,21 @@ export interface StorymapDataWrapper {
 
 // ---------- StoryMap / Map options ----------
 
+/**
+ * Custom tile layer/source factory (see
+ * `StorymapOptions.tile_source_factory`). `createDefault` runs the
+ * built-in `map_type` handling, so a factory can decorate or delegate.
+ *
+ * May return any `ol/layer/Layer` (used as-is — this is what lets a
+ * third-party layer such as an Allmaps `WarpedMapLayer` render), a bare
+ * `Source` (wrapped in a `TileLayer`), or `null`/`undefined` to fall
+ * through to the default `map_type` handling.
+ */
+export type TileSourceFactory = (
+    map_type: string,
+    context: { options: StorymapOptions; createDefault: () => TileLayer },
+) => Layer | TileLayer | Source | null | undefined;
+
 export interface StorymapOptions {
     width: number;
     height: number;
@@ -75,7 +165,6 @@ export interface StorymapOptions {
     default_bg_color: { r: number; g: number; b: number };
     map_size_sticky: number;
     map_center_offset: { left: number; top: number } | null;
-    less_bounce: boolean;
     start_at_slide: number;
     call_to_action: boolean;
     call_to_action_text: string;
@@ -89,7 +178,6 @@ export interface StorymapOptions {
     skinny_size: number;
     duration: number;
     ease: unknown;
-    dragging: boolean;
     trackResize: boolean;
     /**
      * Navigate slides with arrow keys anywhere on the page (default false:
@@ -101,6 +189,13 @@ export interface StorymapOptions {
     nocache: boolean;
     /** Advance slides automatically every N milliseconds; 0 disables (issue #380) */
     autoplay: number;
+    /**
+     * With autoplay on, wait for the current slide's audio or video to end
+     * before advancing instead of using the `autoplay` millisecond timer,
+     * which stays as the fallback. Slides without playable media keep the
+     * timer, so a mixed story never stalls.
+     */
+    autoplay_media: boolean;
     /** Show a progress bar in the menubar (issue #247) */
     show_progress: boolean;
     /** Show the slide headline as a label on the active map marker (issue #243) */
@@ -110,6 +205,15 @@ export interface StorymapOptions {
     /** Override the overview fit center (issues #107, #271) */
     map_overview_center: { lat: number; lon: number } | null;
     map_type: string;
+    /**
+     * Custom OpenLayers tile layer/source factory (issue #473): consulted
+     * by the tile layer factory before the built-in `map_type` switch, for
+     * every base, overlay and minimap layer. Return a `TileLayer` (or a
+     * bare `Source`, auto-wrapped in one) for custom handling — e.g. WMS —
+     * or `null`/`undefined` to fall through to the default types.
+     * Constructor- and runtime-only: functions cannot ride storymap JSON.
+     */
+    tile_source_factory: TileSourceFactory | null;
     attribution: string;
     /**
      * Stacked raster overlays above the base map, below the route lines.
@@ -119,7 +223,6 @@ export interface StorymapOptions {
      */
     overlays: StorymapOverlayLayer[];
     map_mini: boolean;
-    map_subdomains: string;
     map_as_image: boolean;
     map_access_token: string;
     map_background_color: string;
@@ -160,7 +263,9 @@ export interface StorymapOptions {
     /**
      * Ask for permission before loading anything from external services
      * (media embeds, map tiles, external font CSS) — GDPR consent mode.
-     * Grants are remembered per service in a cookie for 90 days.
+     * Decisions are remembered per service in `localStorage` under
+     * `storymapjs-consent` with no expiry: clearing site data is what makes
+     * the viewer ask again.
      */
     consent_required: boolean;
     /** Slide text color override, sets --vco-color-text (issue #177) */
@@ -170,14 +275,13 @@ export interface StorymapOptions {
     /** Show the great-circle route distance in the menubar (issue #341) */
     show_distance: boolean;
     /**
-     * Raw OpenLayers map configuration. `controls` and `interactions` replace
-     * the StoryMapJS defaults, `view` is merged over the computed default view
+     * Raw OpenLayers map configuration. `controls` replaces the StoryMapJS
+     * defaults, `interactions` are *added to* the viewer's own pan/zoom
+     * interactions, and `view` is merged over the computed default view
      * and `element` (an HTMLElement or DOM id) replaces the auto-created map
      * container div.
      */
     map_options: StorymapMapOptions;
-    map_popup: boolean;
-    zoom_distance: number;
     calculate_zoom: boolean;
     line_follows_path: boolean;
     line_color: string;
@@ -190,12 +294,17 @@ export interface StorymapOptions {
     show_history_line: boolean;
     use_custom_markers: boolean;
     iiif: { url: string; attribution: string };
+    tilejson?: StorymapTilejson;
+    /**
+     * The `seeAlso` targets a IIIF manifest points at, recorded but not
+     * fetched — see `loadSeeAlso()` (§5.2 of docs/plans/iiif-interop.md).
+     */
+    see_also?: { id: string; type: string }[];
     map_height: number;
     storyslider_height: number;
     slide_padding_lr: number;
     slide_default_fade: string;
     menubar_default_y: number;
-    path_gfx: string;
     script_path: string;
     font_css: string;
     language: string;
@@ -219,14 +328,43 @@ export interface AnimationHandle {
 
 // ---------- map ----------
 
+/**
+ * TileJSON 2.1 tile source metadata, from a manifest's map configuration
+ * service (§2.9 of docs/plans/iiif-interop.md).
+ *
+ * This is how a manifest states a tile source: `tiles` is the URL template and
+ * the rest is the standard metadata around it, where a keyword basemap
+ * (`osm`, `stadia`, `iiif`, …) has no such thing to say. `minzoom`,
+ * `maxzoom`, `bounds` and `scheme` constrain the source; `center` and `zoom`
+ * set the initial view.
+ */
+export interface StorymapTilejson {
+    /** URL template, e.g. `https://tiles.example.org/{z}/{x}/{y}.png` */
+    tiles: string | string[];
+    /** Lowest zoom level the source has tiles for */
+    minzoom?: number;
+    /** Highest zoom level the source has tiles for */
+    maxzoom?: number;
+    /** `[west, south, east, north]`, WGS84 lon/lat, of the covered area */
+    bounds?: [number, number, number, number];
+    /** `xyz` (default) or `tms`, which flips the tile row order */
+    scheme?: "xyz" | "tms";
+    /** `[lon, lat, zoom]` of the map's default view */
+    center?: [number, number, number];
+}
+
 /**
  * A stacked raster overlay above the base map (StorymapOptions.overlays).
  * Presentation is declarative: hosts no longer need to reach into the
  * layer objects for blend modes, clips or stacking tweaks.
  */
 export interface StorymapOverlayLayer {
-    /** Any `map_type` value the tile layer factory accepts */
-    map_type: string;
+    /**
+     * Any `map_type` value the tile layer factory accepts. Required unless
+     * the entry carries a `georeference` (a placed IIIF image instead of
+     * a tile source).
+     */
+    map_type?: string;
     /** Layer opacity 0..1 (default 1) */
     opacity?: number;
     /** Initial visibility (default true) */
@@ -245,6 +383,52 @@ export interface StorymapOverlayLayer {
     blendMode?: string;
     /** Clip box `[west, south, east, north]` in lon/lat (mercator maps) */
     extent?: [number, number, number, number];
+    /**
+     * IIIF Georeference Extension placement instead of a tile source. The
+     * ground control points are fitted affinely and the image is placed on
+     * the geographic map, so this is the manifest-side equivalent of a
+     * georeferenced raster overlay.
+     */
+    georeference?: StorymapGeoreference;
+}
+
+/**
+ * A IIIF Georeference Extension annotation body plus the image it places
+ * (`overlays[].georeference`). The `body` is the annotation payload of
+ * `iiif.io/api/extension/georef` verbatim: a GeoJSON FeatureCollection of
+ * ground control points pairing `properties.resourceCoords` (image pixels)
+ * with `geometry.coordinates` (WGS84 lon/lat), optionally carrying a
+ * `transformation` hint.
+ *
+ * The viewer fits the affine (first-order polynomial) case and places the
+ * image with OpenLayers' reprojection, which requires an axis-aligned
+ * placement; rotated or skewed sheets, higher-order polynomials and thin
+ * plate splines are reported and skipped — see the "Geo-referenced layers"
+ * section of docs/storymap-as-iiif-manifest.md.
+ */
+export interface StorymapGeoreference {
+    /** IIIF Image API service base (or a full-size image URL) to place */
+    url: string;
+    /** Image width in pixels (the resourceCoords space) */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Georeference annotation body: the GCP FeatureCollection */
+    body: StorymapGeoreferenceBody;
+}
+
+export interface StorymapGeoreferenceBody {
+    type?: string;
+    /** `polynomial` with `order: 1`, or absent; other values are skipped */
+    transformation?: { type?: string; options?: { order?: number } };
+    features: StorymapGroundControlPoint[];
+}
+
+/** One ground control point: an image pixel paired with a WGS84 position */
+export interface StorymapGroundControlPoint {
+    type?: string;
+    properties?: { resourceCoords?: [number, number] };
+    geometry?: { type?: string; coordinates?: number[] };
 }
 
 /** OpenLayers passthrough options (see StorymapOptions.map_options) */
@@ -255,26 +439,39 @@ export interface StorymapMapOptions {
     view?: Record<string, unknown>;
     /** Replaces the default (empty) controls list */
     controls?: unknown[];
-    /** Replaces the default (empty) interactions list */
+    /**
+     * Added to the viewer's own pan/zoom interactions (not a replacement:
+     * the viewer's defaults are always added). `controls` *is* a
+     * replacement, since the viewer adds none of its own.
+     */
     interactions?: unknown[];
     /** Any other ol/Map constructor option (layers, pixelRatio, ...) */
     [key: string]: unknown;
 }
 
+/**
+ * A resolved geographic coordinate.
+ *
+ * `lat`/`lon` are required: this type is for points the map can actually
+ * focus on. A *slide* may carry a `location` without coordinates (an image
+ * region, an icon only) — that is `StorymapSlideLocation`, which keeps them
+ * optional. `lng` is accepted as a legacy alias on input only.
+ */
 export interface LatLngLiteral {
-    lat: number | undefined;
-    lon?: number | undefined;
-    lng?: number | undefined;
+    lat: number;
+    lon: number;
+    lng?: number;
 }
 
-export interface MapMarkerData {
+/**
+ * A marker's data: the slide it was created from, plus the `real_marker` flag
+ * the marker sets once it has confirmed numeric lat/lon. A separate interface
+ * used to drift from `StorymapSlide` (narrower `text`, its own `location`),
+ * which then made `Map._createMarker(slide)` unassignable.
+ */
+export type MapMarkerData = StorymapSlide & {
     real_marker?: boolean;
-    location?: StorymapSlideLocation;
-    media?: StorymapSlideMedia & { mediatype?: MediaTypeMatch | null };
-    text?: { headline?: string };
-    type?: string;
-    [key: string]: unknown;
-}
+};
 
 export type IconSpec = {
     url: string;