@projektemacher/storymapjs 0.10.8 → 0.11.0

package/src/storymap/iiif.ts

@@ -15,54 +15,24 @@ import type {
     StorymapSlideMedia,
 } from "../types";
 import { readGroundControlPoints } from "../map/georeference";
+import {
+    LOCATION_PROPERTIES,
+    asBoolean,
+    asNumber,
+    asRecord,
+    asString,
+    asStringArray,
+    clampRegion,
+    escapeText,
+    isDuplicateNarration,
+    isLonLatBox,
+    readPlaybackBag,
+} from "./iiif-shared";
 
 const PRESENTATION_3_CONTEXT = "iiif.io/api/presentation/3/context.json";
 const MAPCONFIG_PROFILE = "mapconfig";
 const STORYMAP_PREFIX = "storymap:";
 
-/** Keys copied verbatim from navPlace Feature properties onto the location. */
-const LOCATION_PROPERTIES = [
-    "name",
-    "zoom",
-    "line",
-    "icon",
-    "iconSize",
-    "image",
-    "use_custom_marker",
-    // marker presentation with no IIIF vocabulary of its own: a GeoJSON
-    // foreign member needs no registration, which is why these live here
-    // rather than in a storymap: term (docs/plans/iiif-media-tours.md §2)
-    "popup",
-    "audioBadge",
-] as const;
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return null;
-    }
-    return value as Record<string, unknown>;
-}
-
-function asString(value: unknown): string | null {
-    return typeof value === "string" && value !== "" ? value : null;
-}
-
-function asNumber(value: unknown): number | null {
-    return typeof value === "number" && !isNaN(value) ? value : null;
-}
-
-function asBoolean(value: unknown): boolean | null {
-    return typeof value === "boolean" ? value : null;
-}
-
-function asStringArray(value: unknown): string[] {
-    if (typeof value === "string") return [value];
-    if (Array.isArray(value)) {
-        return value.filter((entry): entry is string => typeof entry === "string");
-    }
-    return [];
-}
-
 /**
  * Reads a IIIF xywh image region (`storymap:imageRegion`): an array of
  * exactly 4 finite numbers ([x, y, w, h] in image pixels). Returns null
@@ -161,8 +131,8 @@ function isEmptySelector(sel: ReadSelector): boolean {
 
 /** A `PointSelector` is a pin, which the viewer cannot fit, so we synthesize
  *  a square of 5% of the canvas's smaller side, centred on the point and
- *  clamped to the canvas. Stated once, here: the annotation-driven stops in
- *  docs/plans/iiif-media-tours.md consume this rather than re-deriving it. */
+ *  clamped to the canvas. Stated once, here, so annotation-driven stops
+ *  share it rather than re-deriving it. */
 const POINT_SQUARE_FRACTION = 0.05;
 
 function pointToRegion(
@@ -190,8 +160,11 @@ function readSelectorEntry(entry: unknown, out: ReadSelector, depth = 0): void {
             const match = /xywh=(pixel:)?([^,]+),([^,]+),([^,]+),([^,]+)/.exec(raw);
             if (match) {
                 const parts = match.slice(2).map(Number);
+                // Origins may be negative (slideshow overshoots its canvas);
+                // clamping to the canvas happens in readSelector, which knows
+                // the size. Only the size must already be positive here.
                 if (parts.length === 4 && parts.every((n) => Number.isFinite(n))) {
-                    if (parts[0] >= 0 && parts[1] >= 0 && parts[2] > 0 && parts[3] > 0) {
+                    if (parts[2] > 0 && parts[3] > 0) {
                         out.region = parts as [number, number, number, number];
                     }
                 }
@@ -273,7 +246,14 @@ export function readSelector(
         }
     }
 
-    if (out.region === null && out.point !== null) {
+    if (out.region !== null) {
+        const clamped = clampRegion(out.region, width, height);
+        out.region = clamped;
+        if (clamped === null && out.point !== null) {
+            // fully outside the canvas: fall back to the point square
+            out.region = pointToRegion(out.point, width, height);
+        }
+    } else if (out.point !== null) {
         out.region = pointToRegion(out.point, width, height);
     }
 
@@ -312,7 +292,7 @@ export function flattenLanguageMap(value: unknown): string {
  * type 'object'" — so the array branch below is producer leniency, not
  * conformance. The `label` ("Credit", "Rights holder", a language-tagged term)
  * is half of what a real institutional manifest ships, and reading only
- * `.value` dropped it. See docs/plans/iiif-interop.md §2.1.
+ * `.value` dropped it.
  */
 function readRequiredStatement(statement: unknown): { label: string; value: string } {
     const entries = Array.isArray(statement)
@@ -437,8 +417,7 @@ function collectionToStorymapData(collection: Record<string, unknown>): Storymap
             "A Presentation 3 Collection references its members from other documents, and " +
             "the converter is synchronous, so it contributes no slides rather than " +
             "mangling them. To build a multi-manifest tour, fetch the members and " +
-            "concatenate their manifestToStorymapData() slides yourself " +
-            "(see docs/plans/iiif-interop.md §2.2).",
+            "concatenate their manifestToStorymapData() slides yourself.",
     );
 
     return data;
@@ -550,8 +529,8 @@ function readMapConfig(manifest: Record<string, unknown>): Record<string, unknow
 /**
  * What a painting annotation tells us about a slide's media.
  *
- * This is the **shared body record** the annotation-driven stops in
- * docs/plans/iiif-media-tours.md read: `type` is how a `Sound` body is told
+ * This is the **shared body record** for annotation-driven stops:
+ * `type` is how a `Sound` body is told
  * from an `Image` or a `TextualBody`. Anything else that needs a field from
  * the body belongs on this record rather than in a second reader.
  */
@@ -582,6 +561,27 @@ export interface PaintingBody {
      * in storymap JSON is the documented route.
      */
     subtitles: string | null;
+    /**
+     * Playback flags from `storymap:` foreign members on the painting
+     * annotation (slideshow audio terms); absent stays absent.
+     */
+    offset?: number;
+    loop?: boolean;
+    play?: "auto" | "click";
+    stopOnExit?: boolean;
+}
+
+/**
+ * Reads `storymap:` playback flags off a painting annotation into the
+ * painting body: `offset` (seconds), `loop`, `play` and `stopOnExit`
+ * (painting annotations never carry `stopAllPrevious`).
+ */
+function readPaintingPlayback(
+    annotationRecord: Record<string, unknown>,
+    painting: { offset?: number; loop?: boolean; play?: "auto" | "click"; stopOnExit?: boolean },
+): void {
+    const { stopAllPrevious: _dropped, ...bag } = readPlaybackBag(annotationRecord);
+    Object.assign(painting, bag);
 }
 
 /**
@@ -642,18 +642,101 @@ function readFirstTypedBody(body: unknown): Record<string, unknown> | null {
     return url === null ? null : record;
 }
 
+/** Every body of a `body` array that yields a URL, in order (#358). */
+function readPaintingBodies(body: unknown): Record<string, unknown>[] {
+    if (Array.isArray(body)) {
+        return body.flatMap((entry) => readPaintingBodies(entry));
+    }
+    const record = asRecord(body);
+    if (!record) return [];
+    const url = asString(record.id) ?? asString(record.value);
+    return url === null ? [] : [record];
+}
+
 /**
- * Reads the slide media URL from the canvas's painting annotation body:
+ * Reads the slide media URLs from the canvas's painting annotation bodies:
  * typed bodies contribute their `id`, TextualBody (HTML) content its `value`
  * - the legacy format stores both in `media.url`. Also returns the region of
  * a selector on the annotation target, and the body fields listed on
  * {@link PaintingBody}.
+ *
+ * Every painting match is collected in order (#358): the first becomes the
+ * slide's `media`, further ones its `media_extra`.
  */
-function readPainting(
+function readPaintings(
     canvas: Record<string, unknown>,
     width: number | null = null,
     height: number | null = null,
-): PaintingBody | null {
+): PaintingBody[] {
+    const found: PaintingBody[] = [];
+    const annotationPages = Array.isArray(canvas.items) ? canvas.items : [];
+    for (const page of annotationPages) {
+        const pageRecord = asRecord(page);
+        if (!pageRecord) continue;
+        const annotations = Array.isArray(pageRecord.items) ? pageRecord.items : [];
+        for (const annotation of annotations) {
+            const annotationRecord = asRecord(annotation);
+            if (!annotationRecord) continue;
+            // motivation may be an array (notably ["painting","supplementing"]):
+            // accept when any entry names painting. An absent or unparsable
+            // motivation stays lenient (treated as painting), as before — only
+            // the array form is new.
+            const rawMotivation = annotationRecord.motivation;
+            const motivations = Array.isArray(rawMotivation) ? rawMotivation : [rawMotivation];
+            const isPainting = motivations.some((m) => {
+                const s = asString(m);
+                return s === null || s === "painting";
+            });
+            if (!isPainting) continue;
+            for (const body of readPaintingBodies(annotationRecord.body)) {
+                const painting: PaintingBody = {
+                    url: asString(body.id) ?? asString(body.value) ?? "",
+                    region: readSelector(annotationRecord.target, width, height).region,
+                    type: asString(body.type),
+                    format: asString(body.format),
+                    // P3 puts label / requiredStatement / accessibilitySummary on
+                    // the Annotation; some producers put them on the body, so the
+                    // body is still consulted as a fallback (§2.7)
+                    label:
+                        flattenLanguageMap(annotationRecord.label) ||
+                        flattenLanguageMap(body.label) ||
+                        null,
+                    accessibilitySummary:
+                        flattenLanguageMap(annotationRecord.accessibilitySummary) ||
+                        flattenLanguageMap(body.accessibilitySummary) ||
+                        null,
+                    credit: readAnnotationCredit(annotationRecord) ?? readBodyCredit(body),
+                    thumbnail: readThumbnailId(body.thumbnail),
+                    duration: asNumber(body.duration),
+                    start: asNumber(body.start),
+                    end: asNumber(body.end),
+                    subtitles: readBodySubtitles(annotationRecord.body),
+                };
+                readPaintingPlayback(annotationRecord, painting);
+                found.push(painting);
+            }
+        }
+    }
+    return found;
+}
+
+/**
+ * Reads a slide narration from `motivation: "supplementing"` annotations:
+ * the first `Sound`/`Video` body wins. Painting bodies are skipped here —
+ * the painting reader owns them, including the array-motivation form — and
+ * anything else (commenting, tagging, …) belongs to the annotation stops.
+ *
+ * Playback flags ride `storymap:` foreign members on the annotation (or the
+ * body as a fallback), which need no vocabulary registration.
+ */
+function readSupplementing(canvas: Record<string, unknown>): {
+    url: string;
+    loop?: boolean;
+    offset?: number;
+    play?: "auto" | "click";
+    stopOnExit?: boolean;
+    stopAllPrevious?: boolean;
+} | null {
     const annotationPages = Array.isArray(canvas.items) ? canvas.items : [];
     for (const page of annotationPages) {
         const pageRecord = asRecord(page);
@@ -662,33 +745,24 @@ function readPainting(
         for (const annotation of annotations) {
             const annotationRecord = asRecord(annotation);
             if (!annotationRecord) continue;
-            const motivation = asString(annotationRecord.motivation);
-            if (motivation !== null && motivation !== "painting") continue;
+            const rawMotivation = annotationRecord.motivation;
+            const motivations = Array.isArray(rawMotivation) ? rawMotivation : [rawMotivation];
+            if (!motivations.some((m) => asString(m) === "supplementing")) continue;
             const body = readFirstTypedBody(annotationRecord.body);
             if (body === null) continue;
-            return {
-                url: asString(body.id) ?? asString(body.value) ?? "",
-                region: readSelector(annotationRecord.target, width, height).region,
-                type: asString(body.type),
-                format: asString(body.format),
-                // P3 puts label / requiredStatement / accessibilitySummary on
-                // the Annotation; some producers put them on the body, so the
-                // body is still consulted as a fallback (§2.7)
-                label:
-                    flattenLanguageMap(annotationRecord.label) ||
-                    flattenLanguageMap(body.label) ||
-                    null,
-                accessibilitySummary:
-                    flattenLanguageMap(annotationRecord.accessibilitySummary) ||
-                    flattenLanguageMap(body.accessibilitySummary) ||
-                    null,
-                credit: readAnnotationCredit(annotationRecord) ?? readBodyCredit(body),
-                thumbnail: readThumbnailId(body.thumbnail),
-                duration: asNumber(body.duration),
-                start: asNumber(body.start),
-                end: asNumber(body.end),
-                subtitles: readBodySubtitles(annotationRecord.body),
-            };
+            const type = asString(body.type);
+            if (type !== "Sound" && type !== "Video") continue;
+            const url = asString(body.id) ?? asString(body.value);
+            if (url === null) continue;
+            const narration: {
+                url: string;
+                loop?: boolean;
+                offset?: number;
+                play?: "auto" | "click";
+                stopOnExit?: boolean;
+                stopAllPrevious?: boolean;
+            } = { url, ...readPlaybackBag(annotationRecord), ...readPlaybackBag(body) };
+            return narration;
         }
     }
     return null;
@@ -728,6 +802,28 @@ function readFeatureLocation(feature: unknown): StorymapSlideLocation | null {
             if (value === undefined || value === null || value === "") continue;
             locationProps[key] = value;
         }
+        // Narrow the slideshow-driven keys the verbatim copy cannot check:
+        // a mistyped value must not reach the map as a wrong-typed field.
+        if (typeof location.rotation !== "number" || !Number.isFinite(location.rotation)) {
+            delete location.rotation;
+        }
+        if (typeof location.basemap !== "string" || location.basemap === "") {
+            delete location.basemap;
+        }
+        const filter = asRecord(location.filter);
+        if (location.filter !== undefined && filter === null) delete location.filter;
+        const mask = asRecord(location.mask);
+        if (location.mask !== undefined) {
+            if (
+                mask === null ||
+                typeof mask.x !== "number" ||
+                typeof mask.y !== "number" ||
+                typeof mask.w !== "number" ||
+                typeof mask.h !== "number"
+            ) {
+                delete location.mask;
+            }
+        }
     }
     return location;
 }
@@ -956,7 +1052,11 @@ function canvasToSlide(
     // requiredStatement / accessibilitySummary as caption, credit and alt
     // text (§2.7 — the `mediaCaption`/`mediaCredit`/`mediaAlt` canvas terms are
     // gone). srcset/sizes remain terms: IIIF has no vocabulary for either.
-    const painting = readPainting(record, asNumber(record.width), asNumber(record.height));
+    const paintings = readPaintings(record, asNumber(record.width), asNumber(record.height));
+    // the first painting is the slide's media; further ones are its
+    // media_extra (#358)
+    const painting = paintings[0] ?? null;
+    const extraPaintings = paintings.slice(1);
     const caption = painting?.label ?? null;
     const credit = painting?.credit ?? null;
     const alt = painting?.accessibilitySummary ?? null;
@@ -984,14 +1084,41 @@ function canvasToSlide(
         if (sizes !== null) media.sizes = sizes;
         if (thumbnail !== null) media.thumb = thumbnail;
         if (painting?.subtitles != null) media.subtitles = painting.subtitles;
+        if (painting?.offset !== undefined) media.offset = painting.offset;
+        if (painting?.loop !== undefined) media.loop = painting.loop;
+        if (painting?.play !== undefined) media.play = painting.play;
+        if (painting?.stopOnExit !== undefined) media.stopOnExit = painting.stopOnExit;
         slide.media = media;
     }
+    if (extraPaintings.length > 0) {
+        slide.media_extra = extraPaintings.map((extra) => {
+            const item: StorymapSlideMedia = { url: extra.url };
+            if (extra.label !== null) item.caption = extra.label;
+            if (extra.credit !== null) item.credit = extra.credit;
+            if (extra.accessibilitySummary !== null) item.alt = extra.accessibilitySummary;
+            return item;
+        });
+    }
+
+    // narration: a supplementing Sound/Video body plays as the slide's
+    // narration (V1 of #358). Skipped when it duplicates a painting URL —
+    // a body carrying both motivations is already the slide's media.
+    const supplement = readSupplementing(record);
+    const mediaUrls = new Set(
+        [slide.media?.url, ...(slide.media_extra ?? []).map((item) => item.url)].filter(
+            (url): url is string => typeof url === "string" && url !== "",
+        ),
+    );
+    if (supplement !== null && !isDuplicateNarration([...mediaUrls], supplement.url)) {
+        const { url, ...flags } = supplement;
+        slide.narration = { url, ...flags };
+    }
 
     // location: canvas navPlace, falling back to a manifest-level navPlace
     // aggregated in items order (both are allowed by the proposal)
     const location = readLocation(record.navPlace) ?? readFeatureLocation(manifestFeature);
     if (location !== null) slide.location = location;
-    // IIIF xywh region (StrollView-style image stops): [x, y, w, h] pixels.
+    // IIIF xywh region (slideshow-style image stops): [x, y, w, h] pixels.
     // The extension term wins over the interoperable spelling — an Image API
     // Selector on the painting annotation target
     // region: the painting annotation's target selector, the only source since
@@ -1000,6 +1127,72 @@ function canvasToSlide(
     if (region !== null) {
         slide.location = { ...(slide.location ?? {}), region };
     }
+    // View directives as canvas `storymap:` terms: the fallback for slides
+    // without lat/lon (no navPlace to carry them). navPlace wins when both
+    // spell the same key.
+    const canvasRotation = record[STORYMAP_PREFIX + "rotation"];
+    if (
+        slide.location?.rotation === undefined &&
+        typeof canvasRotation === "number" &&
+        Number.isFinite(canvasRotation)
+    ) {
+        slide.location = { ...(slide.location ?? {}), rotation: canvasRotation };
+    }
+    const canvasBasemap = record[STORYMAP_PREFIX + "basemap"];
+    if (
+        slide.location?.basemap === undefined &&
+        typeof canvasBasemap === "string" &&
+        canvasBasemap !== ""
+    ) {
+        slide.location = { ...(slide.location ?? {}), basemap: canvasBasemap };
+    }
+    const canvasFilter = asRecord(record[STORYMAP_PREFIX + "filter"]);
+    if (slide.location?.filter === undefined && canvasFilter !== null) {
+        slide.location = { ...(slide.location ?? {}), filter: canvasFilter };
+    }
+    const canvasMask = asRecord(record[STORYMAP_PREFIX + "mask"]);
+    if (slide.location?.mask === undefined && canvasMask !== null) {
+        const mx = canvasMask.x;
+        const my = canvasMask.y;
+        const mw = canvasMask.w;
+        const mh = canvasMask.h;
+        if (
+            typeof mx === "number" &&
+            typeof my === "number" &&
+            typeof mw === "number" &&
+            typeof mh === "number"
+        ) {
+            slide.location = {
+                ...(slide.location ?? {}),
+                mask: { ...canvasMask, x: mx, y: my, w: mw, h: mh },
+            };
+        }
+    }
+    const canvasSlidetimeout = record[STORYMAP_PREFIX + "slidetimeout"];
+    if (
+        slide.slidetimeout === undefined &&
+        typeof canvasSlidetimeout === "number" &&
+        Number.isFinite(canvasSlidetimeout) &&
+        canvasSlidetimeout >= 0
+    ) {
+        slide.slidetimeout = canvasSlidetimeout;
+    }
+    const canvasImgoverlay = asRecord(record[STORYMAP_PREFIX + "imgoverlay"]);
+    if (slide.imgoverlay === undefined && canvasImgoverlay !== null) {
+        const overlayUrl = asString(canvasImgoverlay.url);
+        if (overlayUrl !== null) slide.imgoverlay = { ...canvasImgoverlay, url: overlayUrl };
+    }
+    const canvasProvenance = asRecord(record[STORYMAP_PREFIX + "provenance"]);
+    if (slide.provenance === undefined && canvasProvenance !== null) {
+        const provenance: Record<string, unknown> = {};
+        for (const key of ["manifest", "canvas", "image"]) {
+            const value = asString(canvasProvenance[key]);
+            if (value !== null) provenance[key] = value;
+        }
+        if (Object.keys(provenance).length > 0) {
+            slide.provenance = provenance as StorymapSlide["provenance"];
+        }
+    }
 
     // StoryMap extension terms
     const slideType = asString(record[STORYMAP_PREFIX + "type"]);
@@ -1027,21 +1220,11 @@ function canvasToSlide(
  */
 const STOP_MOTIVATIONS = new Set(["commenting", "tagging", "classifying", "describing"]);
 
-/** Escapes the five characters that would otherwise be markup, so a
- *  `text/plain` annotation body cannot inject HTML. The renderer sanitizes
- *  slide text as well; this keeps the stored value honest on its own. */
-function escapeText(value: string): string {
-    return value
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&#39;");
-}
-
 /**
  * A `text/plain` body becomes one paragraph per blank-line-separated block,
- * escaped. A `text/html` body is passed through as markup — the slide text
+ * escaped (`escapeText` is shared with the slideshow translator, which
+ * wraps single paragraphs the same way). A `text/html` body is passed
+ * through as markup — the slide text
  * pipeline (`sanitizeSlideText`, via `media/types/Text.ts`) sanitizes whatever
  * it is given, which is the same path a storymap JSON `text.text` takes.
  */
@@ -1666,8 +1849,15 @@ function applyMapConfig(data: StorymapData, config: Record<string, unknown>): vo
         if (left !== null && top !== null) data.map_center_offset = { left, top };
     }
 
-    const fontCss = asString(readTerm(config, "fontCss"));
-    if (fontCss !== null) data.font_css = fontCss;
+    const fontCssRaw = readTerm(config, "fontCss");
+    if (fontCssRaw === false) {
+        // a manifest can disable the injected theme exactly like storymap
+        // JSON with font_css: false (the host bundles the theme itself)
+        data.font_css = false;
+    } else {
+        const fontCss = asString(fontCssRaw);
+        if (fontCss !== null) data.font_css = fontCss;
+    }
 
     const callToAction = asBoolean(readTerm(config, "callToAction"));
     if (callToAction !== null) data.call_to_action = callToAction;
@@ -1731,9 +1921,8 @@ function applyMapConfig(data: StorymapData, config: Record<string, unknown>): vo
 
 /** Reads a `[west, south, east, north]` lon/lat box of four finite numbers. */
 function readLonLatBox(value: unknown): [number, number, number, number] | null {
-    if (!Array.isArray(value) || value.length !== 4) return null;
-    if (!value.every((n) => typeof n === "number" && Number.isFinite(n))) return null;
-    const [west, south, east, north] = value as number[];
+    if (!isLonLatBox(value)) return null;
+    const [west, south, east, north] = value;
     if (east <= west || north <= south) return null;
     return [west, south, east, north];
 }