@projektemacher/storymapjs 0.10.8 → 0.11.0

package/src/types.ts

@@ -17,10 +17,38 @@ export interface StorymapSlideLocation {
     zoom?: number;
     /**
      * Image region `[x, y, w, h]` in image pixels (IIIF xywh convention,
-     * StrollView-style image stops): the view fits the region on
+     * slideshow-style image stops): the view fits the region on
      * navigation; image maps (`map_type: "iiif"` + `map_as_image`) only.
      */
     region?: [number, number, number, number];
+    /**
+     * View rotation in degrees clockwise (slideshow `rotation`). Applied to
+     * the map view on navigation; absent means north-up (0). Image and geo
+     * maps alike; purely presentational. Honored only with
+     * `slideshow_source`.
+     */
+    rotation?: number;
+    /**
+     * Per-slide image grading (slideshow `filters`): applied as a CSS
+     * `filter()` on the map viewport. All fields optional; absent means
+     * unfiltered. `hueRotate` is degrees (-180..180), `blur` is CSS pixels.
+     * Honored only with `slideshow_source`.
+     */
+    filter?: StorymapSlideFilter;
+    /**
+     * Spotlight mask (slideshow `passepartout`): normalized viewport
+     * fractions `{x, y, w, h}` (0..1) left visible while the rest is dimmed
+     * with `color`. `invert` dims the inside instead of the outside.
+     * Absent means no mask. Honored only with `slideshow_source`.
+     */
+    mask?: StorymapSlideMask;
+    /**
+     * Per-slide basemap override (multi-manifest slideshow tours): any
+     * `map_type` value or IIIF `info.json` URL. Absent keeps the story
+     * basemap. The layer is cached, so returning to a slide is free.
+     * Honored only with `slideshow_source`.
+     */
+    basemap?: string;
     line?: boolean;
     icon?: string;
     iconSize?: number[];
@@ -29,6 +57,35 @@ export interface StorymapSlideLocation {
     [key: string]: unknown;
 }
 
+/**
+ * Declarative CSS filter grading for one slide (slideshow `filters`).
+ * Rendered by `buildSlideFilter()`; unknown keys never reach CSS.
+ */
+export interface StorymapSlideFilter {
+    brightness?: number;
+    contrast?: number;
+    saturate?: number;
+    hueRotate?: number;
+    sepia?: number;
+    blur?: number;
+    [key: string]: unknown;
+}
+
+/**
+ * Spotlight mask geometry (slideshow `passepartout`). Fractions of the
+ * visible map area; `color` is a `#rgb`/`#rrggbb`/`#rrggbbaa`/`rgb(a)` string.
+ */
+export interface StorymapSlideMask {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color?: string;
+    invert?: boolean;
+    opacity?: number;
+    [key: string]: unknown;
+}
+
 export type MediaTypeMatch = {
     type: string;
     name: string;
@@ -56,20 +113,35 @@ export interface StorymapSlideMedia {
      * `TextualBody` + `format: text/vtt` shape we also accept.
      */
     subtitles?: string | null;
+    /**
+     * Start offset in seconds for audio/video media (slideshow `audio.offset`).
+     * Applied once the media metadata is available; absent or negative means 0.
+     * Honored only with `slideshow_source`.
+     */
+    offset?: number;
+    /**
+     * Loop audio/video media (slideshow `audio.loop`). Absent means no loop.
+     * Honored only with `slideshow_source`.
+     */
+    loop?: boolean;
+    /**
+     * `auto` (default) plays on activation; `click` arms the media paused and
+     * lets the visitor start it (slideshow `audio.play`). Absent means `auto`.
+     * Honored only with `slideshow_source`.
+     */
+    play?: "auto" | "click";
+    /**
+     * Stop this media when leaving the slide (default true). `false` lets an
+     * audio bed continue across slides (slideshow ambient audio). Honored
+     * only with `slideshow_source`.
+     */
+    stopOnExit?: boolean;
     [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.
+ * the legacy spelling and `marker.*` wins when present.
  *
  * 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`,
@@ -89,8 +161,46 @@ export interface StorymapSlideMarker {
     [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. In a IIIF manifest this is a
+ * `motivation: "supplementing"` Sound/Video body, read and written alongside
+ * the painting annotation.
+ */
 export interface StorymapSlideNarration {
     url: string;
+    /**
+     * Loop the narration (slideshow `audio.loop`). Absent means no loop.
+     * Note: a looping narration never fires `ended`, so `autoplay_media`
+     * falls back to its millisecond timer for that slide. Honored only with
+     * `slideshow_source`.
+     */
+    loop?: boolean;
+    /**
+     * Start offset in seconds (slideshow `audio.offset`), applied once the
+     * audio metadata is available. Absent or negative means 0. Honored only
+     * with `slideshow_source`.
+     */
+    offset?: number;
+    /**
+     * `auto` (default) plays on navigation; `click` arms the narration
+     * paused and lets the visitor start it (slideshow `audio.play`).
+     * Honored only with `slideshow_source`.
+     */
+    play?: "auto" | "click";
+    /**
+     * Stop the narration when leaving the slide (default true). `false`
+     * keeps an audio bed playing across slides while the URL is unchanged
+     * (slideshow ambient audio). Honored only with `slideshow_source`.
+     */
+    stopOnExit?: boolean;
+    /**
+     * Stop any other playing narration/ambient track before starting this
+     * one (default true). `false` allows the ambient overlap of two tracks.
+     * Honored only with `slideshow_source`.
+     */
+    stopAllPrevious?: boolean;
     [key: string]: unknown;
 }
 
@@ -112,8 +222,7 @@ export interface StorymapSlide {
     date?: string | Record<string, unknown> | null;
     group?: string;
     /**
-     * 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
+     * The language tag this slide's text was read in. 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
@@ -122,17 +231,90 @@ export interface StorymapSlide {
     language?: string;
     location?: StorymapSlideLocation | null;
     media?: StorymapSlideMedia | null;
+    /**
+     * Additional visible media for this slide (#358), rendered after `media`
+     * in order. Items without a non-empty `url` are skipped, so a document
+     * without this field renders identically. In a IIIF manifest these are
+     * further `painting` annotations on the canvas; the slide layout
+     * (`media_layout`) has no IIIF term and stays viewer-side.
+     */
+    media_extra?: StorymapSlideMedia[] | null;
+    /**
+     * 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`. Ignored for a single media item.
+     */
+    media_layout?: "stack" | "row";
     marker?: StorymapSlideMarker | null;
     narration?: StorymapSlideNarration | null;
     text?: StorymapSlideText | null;
     background?: StorymapSlideBackground | string | null;
     uniqueid?: string | null;
+    /**
+     * Provenance identifiers for the slide's source (slideshow
+     * `manifest_id`/`canvas_id`/`image_id`): which manifest, canvas and
+     * image the stop was translated from. Data-only (deep links, export);
+     * never rendered.
+     */
+    provenance?: StorymapSlideProvenance | null;
+    /**
+     * Per-slide autoplay dwell in milliseconds (slideshow `slidetimeout`):
+     * overrides the global `autoplay` interval for this slide; `0` holds on
+     * this slide. Absent means the global interval. Honored only with
+     * `slideshow_source`.
+     */
+    slidetimeout?: number;
+    /**
+     * Per-slide image overlay on the map (slideshow `imgoverlay`): a placed
+     * image shown while this slide is active. Absent means no overlay.
+     * Honored only with `slideshow_source`.
+     */
+    imgoverlay?: StorymapImageOverlay | null;
+    [key: string]: unknown;
+}
+
+/**
+ * A per-slide image overlay (slideshow `imgoverlay`). `url` is a full-size
+ * image; `extent` pins it to `[west, south, east, north]` (lon/lat, or raw
+ * image pixels on image-space maps) and defaults to the current view;
+ * `size` scales it as a fraction of the viewport width; `opacity` is 0..1.
+ */
+export interface StorymapImageOverlay {
+    url: string;
+    size?: number;
+    opacity?: number;
+    extent?: [number, number, number, number];
+    [key: string]: unknown;
+}
+
+/**
+ * Provenance identifiers for one slide's source: the manifest, canvas and
+ * image a stop was translated from. Data-only.
+ */
+export interface StorymapSlideProvenance {
+    manifest?: string;
+    canvas?: string;
+    image?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Authorship and rights for the story as a whole (slideshow
+ * `creator`/`rights`). Rendered into the map attribution line for
+ * slideshow tours; the license URL stays data-only for hosts.
+ */
+export interface StorymapCredit {
+    creator?: string;
+    rights?: string;
+    licenseUrl?: string;
     [key: string]: unknown;
 }
 
 export interface StorymapData {
     uniqueid?: string;
     slides: StorymapSlide[];
+    credit?: StorymapCredit | null;
     [key: string]: unknown;
 }
 
@@ -157,6 +339,14 @@ export type TileSourceFactory = (
     context: { options: StorymapOptions; createDefault: () => TileLayer },
 ) => Layer | TileLayer | Source | null | undefined;
 
+/**
+ * Named progress indicator styles (slideshow `progressbar`), shared by the
+ * translator (which emits them) and the menubar (which renders them) so the
+ * set cannot drift.
+ */
+export const PROGRESSBAR_STYLES = ["bar", "dots", "squares", "block", "thinblock"] as const;
+export type ProgressbarStyle = (typeof PROGRESSBAR_STYLES)[number];
+
 export interface StorymapOptions {
     width: number;
     height: number;
@@ -198,10 +388,40 @@ export interface StorymapOptions {
     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) */
+    /**
+     * Progress indicator style (slideshow `progressbar`): `false`/`"off"`
+     * hides it (same as `show_progress: false`), `true`/`"bar"` is the
+     * classic fill bar, `dots`/`squares` render one step per slide,
+     * `block`/`thinblock` are fill-bar height variants. Absent means the
+     * `show_progress` boolean decides and the style is `"bar"`. Honored
+     * only with `slideshow_source`.
+     */
+    progressbar?:
+        | boolean
+        | "bar"
+        | "dots"
+        | "squares"
+        | "block"
+        | "thinblock"
+        | "off"; /** Show the slide headline as a label on the active map marker (issue #243) */
     marker_labels: boolean;
     /** Default text alignment for slide text: left, center or right (issue #244) */
     text_align: "left" | "center" | "right";
+    /**
+     * Slide panel dock (slideshow `textmode`): which side the text panel
+     * occupies 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`.
+     */
+    textmode?: "left" | "right" | "bottom";
+    /**
+     * Slide panel size as a percentage (slideshow `textsize`): percent of
+     * the width for side docks, of the height for the bottom dock.
+     * Range 10..80; absent keeps the built-in 50/50 split. Honored only
+     * with `slideshow_source`.
+     */
+    textsize?: number;
     /** Override the overview fit center (issues #107, #271) */
     map_overview_center: { lat: number; lon: number } | null;
     map_type: string;
@@ -222,6 +442,15 @@ export interface StorymapOptions {
      * (default) means base map only.
      */
     overlays: StorymapOverlayLayer[];
+    /** Show the basemap/overlay switcher in the menubar (default false) */
+    show_layers_control: boolean;
+    /**
+     * Selectable base maps for the layer switcher. Entry 0 is the initial
+     * basemap unless `map_type` says otherwise; omit for an overlays-only
+     * control. Constructor- and runtime-only when labels are functions
+     * (functions cannot ride storymap JSON — see `label`).
+     */
+    basemaps?: StorymapBasemap[];
     map_mini: boolean;
     map_as_image: boolean;
     map_access_token: string;
@@ -274,6 +503,88 @@ export interface StorymapOptions {
     text_background_color: string;
     /** Show the great-circle route distance in the menubar (issue #341) */
     show_distance: boolean;
+    /**
+     * 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`.
+     */
+    fxmode?: "slide" | "fade" | "none";
+    /**
+     * 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`.
+     */
+    mode?: "standard" | "static";
+    /**
+     * HUD foreground color override (slideshow `hudcolor`): sets the
+     * `--vco-hud-fg` CSS variable. Absent follows the theme. Honored only
+     * with `slideshow_source`.
+     */
+    hudcolor?: string;
+    /**
+     * HUD background color override (slideshow `hudbgcolor`): sets the
+     * `--vco-hud-bg` CSS variable. Absent follows the theme. Honored only
+     * with `slideshow_source`.
+     */
+    hudbgcolor?: string;
+    /**
+     * HUD opacity percent 0..100 (slideshow `hudopacity`): applied to the
+     * HUD background. Absent means fully opaque theme background. Honored
+     * only with `slideshow_source`.
+     */
+    hudopacity?: number;
+    /**
+     * Show the previous/next slide navigation (slideshow `shownav`).
+     * Default true; `false` hides the nav chrome (keyboard/AT navigation
+     * still works, like `show_progress: false` keeps the story usable).
+     * Honored only with `slideshow_source`.
+     */
+    shownav?: boolean;
+    /**
+     * Render slide headlines (slideshow `showheadings`). Default true;
+     * `false` hides headline elements via CSS. Honored only with
+     * `slideshow_source`.
+     */
+    show_headings?: boolean;
+    /**
+     * Show scrollbars in the slide panel (slideshow `showscrollbars`).
+     * Default true; `false` hides them via CSS (content still scrolls).
+     * Honored only with `slideshow_source`.
+     */
+    show_scrollbars?: boolean;
+    /**
+     * Fixed viewer height (slideshow `viewerheight`), e.g. `"400px"`:
+     * applied as a container height override when set. Absent keeps the
+     * measured-container behavior. Only `px`, `%` and `vh` units accepted.
+     * Honored only with `slideshow_source`.
+     */
+    viewerheight?: string;
+    /**
+     * Show media captions and credits (slideshow `showinfo`). Default true;
+     * `false` hides the caption/credit block. Honored only with
+     * `slideshow_source`.
+     */
+    show_info?: boolean;
+    /**
+     * Detect slideshow tours automatically (default `true`): an
+     * `AnnotationCollection` shaped like one loads through the translator.
+     * Set `false` to disable detection (such documents then fail validation
+     * as before).
+     */
+    slideshow?: boolean;
+    /**
+     * @internal Source marker: true when the loaded document came from a
+     * slideshow tour (set programmatically by the viewer, never from data).
+     * The slideshow-motivated presentation fields (location
+     * rotation/filter/mask/basemap, narration/media playback bags,
+     * slidetimeout, imgoverlay, and the player-chrome options above) render
+     * only with this set — internal documents keep the long-standing
+     * behavior. Absent from constructor defaults and schema, so storymap
+     * data cannot inject it; it travels via options copies. Hosts may pass
+     * it explicitly as an escape hatch.
+     */
+    slideshow_source?: boolean;
     /**
      * Raw OpenLayers map configuration. `controls` replaces the StoryMapJS
      * defaults, `interactions` are *added to* the viewer's own pan/zoom
@@ -293,11 +604,24 @@ export interface StorymapOptions {
     show_lines: boolean;
     show_history_line: boolean;
     use_custom_markers: boolean;
-    iiif: { url: string; attribution: string };
+    /**
+     * IIIF image service for image maps. `url` is the `info.json`; `width`
+     * and `height` record the canvas size so region clamping and the static
+     * fallback work without another fetch; `fallbackUrl` is a full-size
+     * image used when `info.json` cannot be loaded (slideshow
+     * `image_static`).
+     */
+    iiif: {
+        url: string;
+        attribution: string;
+        width?: number;
+        height?: number;
+        fallbackUrl?: 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).
+     * fetched — see `loadSeeAlso()`.
      */
     see_also?: { id: string; type: string }[];
     map_height: number;
@@ -306,8 +630,18 @@ export interface StorymapOptions {
     slide_default_fade: string;
     menubar_default_y: number;
     script_path: string;
-    font_css: string;
+    /**
+     * Font theme stylesheet: `stock:<name>`, a URL/path, or `false` for no
+     * injected stylesheet (the host bundles the theme itself).
+     */
+    font_css: string | false;
     language: string;
+    /**
+     * Colour theme: `"dark"` forces the dark palette, `"light"` pins the
+     * light one (overriding an OS dark preference), unset follows
+     * `prefers-color-scheme`. Construction-time only, like `map_type`.
+     */
+    theme?: "dark" | "light";
     api_key_flickr: string;
     [key: string]: unknown;
 }
@@ -330,7 +664,7 @@ export interface AnimationHandle {
 
 /**
  * TileJSON 2.1 tile source metadata, from a manifest's map configuration
- * service (§2.9 of docs/plans/iiif-interop.md).
+ * service.
  *
  * 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
@@ -353,6 +687,20 @@ export interface StorymapTilejson {
     center?: [number, number, number];
 }
 
+/**
+ * A selectable base map for the layer switcher (`StorymapOptions.basemaps`).
+ */
+export interface StorymapBasemap {
+    /** Any `map_type` value. */
+    map_type: string;
+    /**
+     * Control row label. Defaults to `map_type`. A function is re-invoked
+     * on every `refreshLabels()` for host i18n (constructor options only —
+     * see `StorymapOverlayLayer.label`).
+     */
+    label?: string | (() => string);
+}
+
 /**
  * A stacked raster overlay above the base map (StorymapOptions.overlays).
  * Presentation is declarative: hosts no longer need to reach into the
@@ -381,6 +729,23 @@ export interface StorymapOverlayLayer {
     className?: string;
     /** CSS mix-blend-mode for the layer container (needs className) */
     blendMode?: string;
+    /**
+     * Control row label for the layer switcher (`show_layers_control`).
+     * Defaults to `map_type`. A function is re-invoked on every
+     * `refreshLabels()` for host i18n — but only when the entry comes from
+     * constructor options: `mergeData()` overwrites option keys with the
+     * storymap JSON, so a document carrying `overlays` replaces function
+     * labels with its own strings.
+     */
+    label?: string | (() => string);
+    /**
+     * Render the row checked and disabled: an overlay the visitor may add
+     * back but not remove (e.g. a georeferenced scan the story is built on).
+     * The control never toggles a locked entry.
+     */
+    locked?: boolean;
+    /** false hides the row from the control without removing the overlay. */
+    control?: boolean;
     /** Clip box `[west, south, east, north]` in lon/lat (mercator maps) */
     extent?: [number, number, number, number];
     /**