@projektemacher/storymapjs 0.10.8 → 0.11.0

package/src/storymap/to-iiif.ts

@@ -18,6 +18,19 @@ import type {
     StorymapSlide,
     StorymapSlideLocation,
 } from "../types";
+// Explicit `.ts` extension: scripts/convert-to-iiif.mjs imports this module
+// straight into node --experimental-strip-types, whose ESM resolution does
+// not try extensions. Extensionless (repo style) breaks `npm run convert:iiif`
+// and tests/convert-cli.test.ts catches it.
+import {
+    LOCATION_PROPERTIES,
+    asRecord,
+    isDuplicateNarration,
+    isHttpUrl,
+    isLonLatBox,
+    languageMap,
+    writePlaybackTerms,
+} from "./iiif-shared.ts";
 
 /**
  * The document {@link storymapToManifest} reads: the `{ "storymap": {...} }`
@@ -99,6 +112,12 @@ export interface StorymapManifestAnnotation {
     accessibilitySummary?: StorymapLanguageMap;
     body: StorymapManifestContentResource;
     target: string | StorymapManifestSpecificResource;
+    /** Playback flags (slideshow audio terms); foreign members, absent when unset. */
+    "storymap:loop"?: boolean;
+    "storymap:offset"?: number;
+    "storymap:play"?: string;
+    "storymap:stopOnExit"?: boolean;
+    "storymap:stopAllPrevious"?: boolean;
 }
 
 /** A painting annotation whose target is a region of a larger image (§2.8). */
@@ -161,6 +180,16 @@ export interface StorymapManifestCanvas {
     "storymap:type"?: string;
     "storymap:mediaSrcset"?: unknown;
     "storymap:mediaSizes"?: unknown;
+    /** View directives (slideshow rotation/basemap/filter/mask); navPlace carries them when lat/lon exist. */
+    "storymap:rotation"?: number;
+    "storymap:basemap"?: string;
+    "storymap:filter"?: unknown;
+    "storymap:mask"?: unknown;
+    /** Per-slide autoplay dwell (slideshow slidetimeout) and image overlay. */
+    "storymap:slidetimeout"?: number;
+    "storymap:imgoverlay"?: unknown;
+    /** Provenance identifiers (slideshow manifest/canvas/image ids). */
+    "storymap:provenance"?: unknown;
     navPlace?: StorymapManifestFeatureCollection;
 }
 
@@ -232,28 +261,6 @@ const IMAGE_FORMATS: Record<string, string> = {
 const VIDEO_HOSTS = ["youtube.com", "youtu.be", "vimeo.com", "dailymotion.com", "vine.co"];
 const SOUND_HOSTS = ["soundcloud.com"];
 
-/**
- * Keys copied out of navPlace Feature properties, in the order they are
- * written. This list mirrors the reader's (`src/storymap/iiif.ts`): `popup`
- * and `audioBadge` are marker presentation with no IIIF vocabulary of their
- * own, and omitting them here silently drops them on the round trip.
- */
-const LOCATION_PROPERTIES = [
-    "name",
-    "zoom",
-    "line",
-    "icon",
-    "iconSize",
-    "image",
-    "use_custom_marker",
-    "popup",
-    "audioBadge",
-] as const;
-
-function isHttpUrl(value: unknown): value is string {
-    return typeof value === "string" && /^https?:\/\//i.test(value);
-}
-
 function classifyMediaUrl(url: string): { type: string; format?: string } {
     const ext = url.split(/[?#]/)[0].split(".").pop()?.toLowerCase();
     // Own-property check: a bare lookup hits Object.prototype, so a URL
@@ -278,10 +285,6 @@ function classifyMediaUrl(url: string): { type: string; format?: string } {
     return { type: "Text", format: "text/html" };
 }
 
-function languageMap(value: string): StorymapLanguageMap {
-    return { none: [value] };
-}
-
 /**
  * A value worth writing: neither absent nor the empty string. A type guard, so
  * a declared `string | null` member narrows to the string it is.
@@ -290,28 +293,11 @@ function present<T>(value: T | null | undefined): value is T {
     return value !== undefined && value !== null && value !== "";
 }
 
-/** A plain object, or null for anything else (arrays included). */
-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>;
-}
-
 /** An array of `T`, or an empty one. */
 function asArray<T>(value: unknown): T[] {
     return Array.isArray(value) ? (value as T[]) : [];
 }
 
-/** A `[west, south, east, north]` box of four finite numbers. */
-function isLonLatBox(value: unknown): value is [number, number, number, number] {
-    return (
-        Array.isArray(value) &&
-        value.length === 4 &&
-        value.every((n) => typeof n === "number" && Number.isFinite(n))
-    );
-}
-
 /**
  * Convert a legacy storymap document to a IIIF Presentation 3.0 manifest.
  *
@@ -367,6 +353,23 @@ export function storymapToManifest(name: string, legacy: StorymapDocument): Stor
         ],
         items: canvases,
     };
+    // Story credit (slideshow `creator`/`rights`): structured metadata
+    // entries, which the reader keeps in `data.metadata`. The dedicated
+    // `provider`/`rights` slots stay untouched — provider names the
+    // publisher, which the converter does not know (§3.2).
+    const credit = storymap.credit;
+    if (credit && typeof credit.creator === "string" && credit.creator !== "") {
+        manifest.metadata.push({
+            label: languageMap("Creator"),
+            value: languageMap(credit.creator),
+        });
+    }
+    if (credit && typeof credit.rights === "string" && credit.rights !== "") {
+        manifest.metadata.push({
+            label: languageMap("Rights"),
+            value: languageMap(credit.rights),
+        });
+    }
 
     // `structures` carries the groups (§3.5). A storymap states a slide's
     // group as a plain string; P3 states it as a Range over the canvases it
@@ -468,7 +471,12 @@ function buildMapConfig(
     if (storymap.map_center_offset !== undefined) {
         config["storymap:mapCenterOffset"] = storymap.map_center_offset;
     }
-    const fontCss: unknown = legacy.font_css || storymap.font_css;
+    // false is meaningful (no injected theme) and must survive the legacy
+    // fallback; everything else keeps the previous `||` semantics.
+    const fontCss: unknown =
+        legacy.font_css === false || storymap.font_css === false
+            ? false
+            : legacy.font_css || storymap.font_css;
     if (present(fontCss)) {
         config["storymap:fontCss"] = fontCss;
     }
@@ -590,7 +598,20 @@ function buildCanvas(
                         ...buildAnnotationPresentation(slide),
                         body: buildBody(slide, isImageMap),
                         target: buildRegionTarget(canvasId, slide.location?.region) ?? canvasId,
+                        // Playback flags for audio/video media (slideshow
+                        // audio terms); absent stays absent.
+                        ...writePlaybackTerms(slide.media ?? {}),
                     },
+                    // Narration is a supplementing Sound body (V1 of #358):
+                    // "additional to the painting", with no rendering rules
+                    // attached — exactly what the dedicated audio element
+                    // plays. Skipped when it duplicates the painting URL.
+                    ...buildNarration(canvasId, slide),
+                    // Extra visible media as further painting annotations (V2
+                    // of #358): IIIF expresses multiple media per canvas as
+                    // multiple paintings. The layout (media_layout) has no
+                    // term and stays viewer-side.
+                    ...buildExtraPaintings(canvasId, slide),
                     // Georeference Extension annotations for the placed rasters
                     // (§2.10). The layers are map-wide but an annotation is
                     // canvas-scoped, so they are written on the first canvas and
@@ -617,6 +638,48 @@ function buildCanvas(
     return canvas;
 }
 
+/**
+ * A slide's extra visible media as further `painting` annotations (V2 of
+ * #358). Each extra reuses the primary's body and presentation builders, so
+ * captions, credits and alt text travel the same way; extras without a usable
+ * url are skipped, matching the viewer.
+ */
+function buildExtraPaintings(canvasId: string, slide: StorymapSlide): StorymapManifestAnnotation[] {
+    const extras = Array.isArray(slide.media_extra) ? slide.media_extra : [];
+    return extras
+        .filter((item) => typeof item?.url === "string" && item.url !== "")
+        .map((item, index) => ({
+            id: `${canvasId}/annotation/extra-${index + 1}`,
+            type: "Annotation",
+            motivation: "painting",
+            ...buildAnnotationPresentation({ media: item }),
+            body: buildBody({ media: item }, false),
+            target: canvasId,
+        }));
+}
+
+/**
+ * A slide narration as a `motivation: "supplementing"` annotation (V1 of
+ * #358). The body is always a `Sound`: narration plays through the
+ * dedicated audio element, which never renders video.
+ */
+function buildNarration(canvasId: string, slide: StorymapSlide): StorymapManifestAnnotation[] {
+    const url = slide.narration?.url;
+    if (typeof url !== "string" || url === "" || isDuplicateNarration([slide.media?.url], url)) {
+        return [];
+    }
+    return [
+        {
+            id: `${canvasId}/annotation/narration`,
+            type: "Annotation",
+            motivation: "supplementing",
+            body: { id: url, type: "Sound" },
+            target: canvasId,
+            ...writePlaybackTerms(slide.narration ?? {}),
+        },
+    ];
+}
+
 /**
  * A map's georeferenced rasters as Georeference Extension annotations
  * (§2.10).
@@ -855,6 +918,30 @@ function buildCanvasTerms(slide: StorymapSlide): Partial<StorymapManifestCanvas>
     if (present(slide.media?.sizes)) {
         terms["storymap:mediaSizes"] = slide.media?.sizes;
     }
+    // View directives that also ride the navPlace properties (which only
+    // exist when the slide has lat/lon): the canvas terms are the fallback
+    // for image-region-only slides, and the reader prefers navPlace.
+    if (typeof slide.location?.rotation === "number") {
+        terms["storymap:rotation"] = slide.location.rotation;
+    }
+    if (present(slide.location?.basemap) && typeof slide.location?.basemap === "string") {
+        terms["storymap:basemap"] = slide.location.basemap;
+    }
+    if (present(slide.location?.filter)) {
+        terms["storymap:filter"] = slide.location?.filter;
+    }
+    if (present(slide.location?.mask)) {
+        terms["storymap:mask"] = slide.location?.mask;
+    }
+    if (typeof slide.slidetimeout === "number") {
+        terms["storymap:slidetimeout"] = slide.slidetimeout;
+    }
+    if (present(slide.imgoverlay)) {
+        terms["storymap:imgoverlay"] = slide.imgoverlay;
+    }
+    if (present(slide.provenance)) {
+        terms["storymap:provenance"] = slide.provenance;
+    }
     return terms;
 }