@projektemacher/storymapjs 0.10.8 → 0.11.0

package/dist/docs/api/media/migration-from-knightlab.md

@@ -72,15 +72,16 @@ element, ... }` to configure the underlying OpenLayers map; `element`
 
 ## Changed options and map types
 
-| Old                                           | New                                                                                                                                                              |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `map_type: "zoomify"` (+ `options.zoomify`)   | preferred: `map_type: "iiif"` with `options.iiif = { url, attribution }` (IIIF Image API 2/3); zoomify still works as a legacy image-pyramid basemap (see below) |
-| `map_type: "stamen:toner"` etc.               | `"stamen:*"` types are deprecated and remapped: `stamen:watercolor` → `ch-watercolor`, others → `osm:standard`                                                   |
-| Stadia Maps paid tiles via `map_access_token` | Recommended: free OpenStreetMap vector styles, e.g. `map_type: "osm:bright"` (OpenFreeMap), or any style JSON URL                                                |
-| Bundled `map_access_token`                    | removed — pass `map_access_token` in the options if you use Mapbox/Stadia tiles                                                                                  |
-| Bundled Flickr API key                        | removed — pass `api_key_flickr` in the options if you use `flickr.com/photos` API URLs                                                                           |
-| `relative_date: true` (moment.js)             | removed — format dates in the story text                                                                                                                         |
-| `font_css: "stock:<name>"` (or a path)        | paths now resolve against the page URL (not the library location), plus the font files ship via `@fontsource-utils/scss`; no separate font CSS link needed       |
+| Old                                           | New                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `map_type: "zoomify"` (+ `options.zoomify`)   | preferred: `map_type: "iiif"` with `options.iiif = { url, attribution }` (IIIF Image API 2/3); zoomify still works as a legacy image-pyramid basemap (see below)                                                                                                                                                                                                                                                                            |
+| `map_type: "stamen:toner"` etc.               | `"stamen:*"` types are deprecated and remapped: `stamen:watercolor` → `ch-watercolor`, others → `osm:standard`                                                                                                                                                                                                                                                                                                                              |
+| Stadia Maps paid tiles via `map_access_token` | Recommended: free OpenStreetMap vector styles, e.g. `map_type: "osm:bright"` (OpenFreeMap), or any style JSON URL                                                                                                                                                                                                                                                                                                                           |
+| Bundled `map_access_token`                    | removed — pass `map_access_token` in the options if you use Mapbox/Stadia tiles                                                                                                                                                                                                                                                                                                                                                             |
+| Bundled Flickr API key                        | removed — pass `api_key_flickr` in the options if you use `flickr.com/photos` API URLs                                                                                                                                                                                                                                                                                                                                                      |
+| `relative_date: true` (moment.js)             | removed — format dates in the story text                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `font_css: "stock:<name>"` (or a path)        | paths now resolve against the page URL (not the library location), plus the font files ship via `@fontsource-utils/scss`; no separate font CSS link needed                                                                                                                                                                                                                                                                                  |
+| `font_css: false` (bundler consumers)         | `stock:<name>` resolves via `import.meta.url`, which only survives when this package is _not_ processed by a bundler — bundling inlines `dist/js/storymap.js` into a chunk and the theme URL breaks. Instead `import "@projektemacher/storymapjs/css/fonts/font.default.css"` (fingerprinted, `files/` rebased by the bundler) and pass `font_css: false` for no injected `<link>`. `"none"` works too for JSON. A failing theme only warns |
 
 ## A story with no map
 
@@ -122,11 +123,12 @@ their neutral values, and the map setters are no-ops.
 | Twitter `@nickname` rendering         | tweets from `x.com` URLs are now parsed too (fixes `@undefined` nicknames); no migration needed                                                                                                                              |
 | Ricoh360/theta360 embeds (#391)       | service no longer available (won't fix) — paste the provider's `<iframe>` snippet into the slide text if the service returns                                                                                                 |
 
-Extra media per slide (#358, partial): each slide still has one primary
-`media` item, but an `<iframe>` embed snippet pasted into the slide `text`
-field now renders sanitized (scripts, event handlers and non-https sources
-dropped) — use this for a second video/map/embed or as the migration path
-for removed media types:
+Extra media per slide (#358, partial): a slide takes `media_extra` (a list of
+further media items, rendered after the primary one) plus `media_layout`
+(`stack`, the default, or `row` for two side-by-side items). An `<iframe>`
+embed snippet pasted into the slide `text` field still renders sanitized
+(scripts, event handlers and non-https sources dropped) — keep that as the
+migration path for removed media types:
 
 ```html
 <p>Extra footage:</p>
@@ -157,9 +159,10 @@ storymap JSON sources.
   before; the mini map is an OpenLayers `OverviewMap` control.
 - New basemap options: vector styles via `map_type: "osm:<style>"` (OpenFreeMap)
   or a Mapbox style JSON URL.
-- All OL types (`Map`, `View`, `Layer`, `Source`, `Feature`, ...) are
-  re-exported, so a consumer can type its own overlays without depending on
-  `ol` directly.
+- The `Ol*` aliases re-exported from `src/main.ts` (`OlMap`, `OlView`,
+  `OlLayer`, `OlTileLayer`, `OlVectorLayer`, `OlSource`, `OlProjection`) let
+  a consumer type the map and layers without depending on `ol` directly;
+  anything beyond those (features, geometries, coordinates) still needs `ol`.
 
 ### Direct Leaflet calls → OpenLayers
 
@@ -201,16 +204,18 @@ names and behaviour (`storymap._map.<method>()`, `marker.<method>()`); the OL
 engine implements them as thin wrappers over `storymap.map`. Two methods are
 deprecated no-ops and one is gone:
 
-| Original method                                                                                           | Status                                                                                                                                                                                                                               |
-| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `updateDisplay`, `goTo`, `panTo`, `zoomTo`, `viewTo`                                                      | unchanged                                                                                                                                                                                                                            |
-| `getBoundsZoom`, `markerOverview`, `calculateMarkerZooms`                                                 | unchanged (`getBoundsZoom()` now returns `number \| undefined` instead of a falsy value)                                                                                                                                             |
-| `createMiniMap`, `createMarkers`, `createMarker`                                                          | unchanged                                                                                                                                                                                                                            |
-| `setMapOffset`, `calculateMinMaxZoom`, `updateMinMaxZoom`, `initialMapLocation`                           | unchanged                                                                                                                                                                                                                            |
-| `show()` / `hide()` (map and marker)                                                                      | **deprecated no-ops** — they were already empty in the original viewer. Style `.vco-mapmarker` or use `marker.active(false)`                                                                                                         |
-| `map.addTo(container)` / `map.removeFrom(container)`                                                      | unchanged — inherited from the `DomMixed` mixin: append/remove the map container and fire `added`/`removed`. The engine override re-targets and re-measures the OpenLayers viewport, so a move into a differently sized parent works |
-| `marker.createPopup()`                                                                                    | **deprecated no-op** — it never did anything upstream either (empty base body, commented-out Leaflet body), so the `map_popup` option that called it had no effect. Still accepted, still inert                                      |
-| `marker.addTo()`, `marker.removeFrom()`, `marker.updateDisplay()`, `marker.active()`, `marker.location()` | unchanged                                                                                                                                                                                                                            |
+| Original method                                                                                           | Status                                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `updateDisplay`, `goTo`, `panTo`, `zoomTo`, `viewTo`                                                      | unchanged                                                                                                                                                                                                                                                         |
+| `getBoundsZoom`, `markerOverview`, `calculateMarkerZooms`                                                 | unchanged (`getBoundsZoom()` now returns `number \| undefined` instead of a falsy value)                                                                                                                                                                          |
+| `createMiniMap`, `createMarkers`, `createMarker`                                                          | unchanged                                                                                                                                                                                                                                                         |
+| `setMapOffset`, `calculateMinMaxZoom`, `updateMinMaxZoom`, `initialMapLocation`                           | unchanged                                                                                                                                                                                                                                                         |
+| `show()` / `hide()` (map and marker)                                                                      | **deprecated no-ops** — they were already empty in the original viewer. Style `.vco-mapmarker` or use `marker.active(false)`                                                                                                                                      |
+| `map.addTo(container)` / `map.removeFrom(container)`                                                      | unchanged — inherited from the `DomMixed` mixin: append/remove the map container and fire `added`/`removed`. The engine override re-targets and re-measures the OpenLayers viewport, so a move into a differently sized parent works                              |
+| `marker.createPopup()`                                                                                    | **deprecated no-op** — it never did anything upstream either (empty base body, commented-out Leaflet body), so the `map_popup` option that called it had no effect. Still accepted, still inert. Use `marker.openPopup()` / `storymap.openMarkerPopup(n)` instead |
+| `marker.addTo()`, `marker.removeFrom()`, `marker.updateDisplay()`, `marker.active()`, `marker.location()` | unchanged                                                                                                                                                                                                                                                         |
+| `marker.openPopup()` / `closePopup()` / `togglePopup()` / `isPopupEnabled()` / `popupOpen`                | **new** — programmatic control of the popup card (`marker: { popup: true }`); `openPopup()` returns false when disabled or not a real marker, `popupOpen` reports the state                                                                                       |
+| `storymap.openMarkerPopup(n)` / `closeMarkerPopup(n?)` / `isPopupOpen(n)`                                 | **new** — open/close/query a stop's card from the viewer; `openMarkerPopup` navigates to `n` first and returns false (changing nothing) when disabled, out of range, disposed or mapless                                                                          |
 
 Marker helpers that Leaflet provided on the marker object (`getLatLng`,
 `setIcon`, `bindPopup`) are gone; use `marker.latLon()`, the
@@ -223,17 +228,17 @@ construction, so check it before first use in an async setup). Everything the
 viewer keeps internally is available through accessors on `storymap` (and on
 `storymap._map` for the engine methods):
 
-| Accessor                                                     | Returns                                                            |
-| ------------------------------------------------------------ | ------------------------------------------------------------------ |
-| `getBaseLayer()`                                             | the base tile/vector layer                                         |
-| `getOverlayLayers()` / `getOverlayLayer(i)`                  | overlay layers / one by index (`null` if out of range)             |
-| `getOverlayCount()`                                          | number of overlays                                                 |
-| `setOverlayVisible(i, on)` / `setOverlayOpacity(i, opacity)` | show/hide and fade one overlay                                     |
-| `getMinimap()`                                               | the `OverviewMap` control, or its inner map via `getOverviewMap()` |
-| `getLine()` / `getLineActive()`                              | the full and the travelled route `VectorLayer`                     |
-| `getMarker(n)` / `getMarkers()`                              | one marker or all of them, in slide order                          |
-| `setExtraAttributions(html)`                                 | extra attribution HTML, listed after the source credits            |
-| `isImageSpace()`                                             | whether the map is a IIIF image in image space (see below)         |
+| Accessor                                                     | Returns                                                                                                                           |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `getBaseLayer()`                                             | the base tile/vector layer                                                                                                        |
+| `getOverlayLayers()` / `getOverlayLayer(i)`                  | overlay layers / one by index (`null` if out of range)                                                                            |
+| `getOverlayCount()`                                          | number of overlays                                                                                                                |
+| `setOverlayVisible(i, on)` / `setOverlayOpacity(i, opacity)` | show/hide and fade one overlay                                                                                                    |
+| `getMinimap()`                                               | the inner overview `ol/Map` (`OlMap \| null`), not the `OverviewMap` control itself — there is no accessor for the control object |
+| `getLine()` / `getLineActive()`                              | the full and the travelled route `VectorLayer`                                                                                    |
+| `getMarker(n)` / `getMarkers()`                              | one marker or all of them, in slide order                                                                                         |
+| `setExtraAttributions(html)`                                 | extra attribution HTML, listed after the source credits                                                                           |
+| `isImageSpace()`                                             | whether the map is a IIIF image in image space (see below)                                                                        |
 
 `tile_source_factory` may return a full `ol/layer/Layer` (not just a source)
 anywhere a layer is built, so custom layers can carry their own opacity,
@@ -248,6 +253,22 @@ custom layer with no explicit z-index lands wherever OpenLayers puts it,
 which is above the lines — set one explicitly if the layer must sit inside
 the stack.
 
+### Layer switcher
+
+`show_layers_control: true` adds a disclosure button to the menubar with
+basemap radios and overlay checkboxes. Basemap candidates come from
+`basemaps[]` (entry 0 is the initial basemap unless `map_type` says
+otherwise; omit for an overlays-only control); overlay rows come from the
+built `overlays[]` entries, so a malformed entry never gets a row and row
+_i_ is always layer _i_. `label` may be a function for host i18n (re-invoked
+on `refreshLabels()`), `locked: true` renders a row checked and disabled,
+`control: false` hides a row without removing the overlay — but function
+labels survive only in constructor options, because `mergeData()` lets
+storymap JSON overwrite same-named option keys. A runtime basemap swap
+rebuilds layers but never the view, so candidates needing another
+projection are refused with a warning; switching fires `basemapchange` /
+`overlaychange`, and the visitor's choice is never persisted.
+
 ### Image space vs. georeferenced
 
 `map_type: "iiif"` is a mercator map by default. With `map_as_image: true` the
@@ -297,8 +318,9 @@ viewer's own pan/zoom set, `view` merges over the computed default).
 For source classes the templates cannot express (WMS, authenticated or
 gridded sources), use the `tile_source_factory` option. It is consulted
 for every base, overlay and minimap layer before the built-in
-`map_type` handling — return a `TileLayer` (or a bare `Source`, which
-is wrapped in one), or `null`/`undefined` to fall through:
+`map_type` handling — return any `ol/layer/Layer` (used as-is) or a bare
+`Source` (which is wrapped in a `TileLayer`), or `null`/`undefined` to fall
+through:
 
 ```js
 import TileLayer from "ol/layer/Tile";
@@ -306,7 +328,7 @@ import TileWMS from "ol/source/TileWMS";
 
 new StoryMap("embed", data, {
     map_type: "wms:flood",
-    tile_source_factory: (map_type, { createDefault }) =>
+    tile_source_factory: (map_type, { options, createDefault }) =>
         map_type.startsWith("wms:")
             ? new TileLayer({
                   source: new TileWMS({
@@ -319,6 +341,12 @@ new StoryMap("embed", data, {
 });
 ```
 
+The second factory argument also carries the resolved `options`
+(`{ options, createDefault }`). A factory may return any `ol/layer/Layer`
+(used as-is — including sourceless layers such as Allmaps'
+`WarpedMapLayer`), a bare `Source` (wrapped in a `TileLayer`), or
+`null`/`undefined` to fall through to the default `map_type` handling.
+
 Custom sources must carry their own attributions (via the returned
 source or the `attribution` option) — only the built-in `osm*` types
 are credited automatically. `tile_source_factory` is constructor- and
@@ -342,14 +370,26 @@ factory.
   [docs/storymap-as-iiif-manifest.md](storymap-as-iiif-manifest.md#geo-referenced-layers).
 - The editor, staging/backend infrastructure, AWS/GitHub hosting scripts and the
   Python authoring server are gone — this is a viewer-only library.
-
-## Events (unchanged, plus two new ones)
-
-`change` (with `current_slide`, and now also `current_id` — the slide's
-`uniqueid`, for deep-linking), `loaded`, `title`, `dataloaded`,
-`fontLoaded`, plus the listener map in the constructor — all work as before.
-`markerAdded`/`markerRemoved` still fire on the map object, and `imageready`
-is new (see above).
+- **Slideshow tours** are a third input format: W3C `AnnotationCollection`
+  documents (the format of slideshow-style guided image tours) load
+  directly by object, file or URL, auto-detected after the IIIF branch
+  (`slideshow: false` opts out). A pure translator converts them to
+  storymap data — per-slide image regions, rotation, filter grading,
+  spotlight masks, per-slide basemaps, narration with playback flags and
+  player chrome — which renders only for slideshow tours (the internal
+  `slideshow_source` marker; other documents are unaffected). Convert
+  offline with `npm run convert:slideshow`; the full mapping is in
+  [docs/slideshow.md](slideshow.md).
+
+## Events (unchanged, plus new ones)
+
+The canonical reference is [docs/events.md](events.md) — one table per
+emitter, with payloads. What changed in migration terms: `change` gains
+`current_id`, `loaded`, `title`, `dataloaded`, `fontLoaded`,
+`transitionstart`/`transitionend`, `error` and the constructor listener map
+all work as before; `markerAdded`/`markerRemoved` still fire on the map
+object; `imageready`, `markerclick` and `popupopen`/`popupclose` are new
+(see above).
 
 Two additions for IIIF tours: `await storymap.loadAnnotations()` fetches a
 manifest's externally referenced annotation pages and appends them as stops,

package/dist/docs/api/media/slideshow.md

@@ -0,0 +1,109 @@
+# Slideshow tours as StoryMapJS data
+
+Slideshow tours are W3C `AnnotationCollection` documents with per-stop
+image targets and a `strollview` extension object (slideshow-style guided
+image tours). The viewer reads them through
+`slideshowToStorymapData()` (`src/storymap/from-slideshow.ts`), the
+counterpart of `manifestToStorymapData()` for that format: pure, so the
+same document always produces the same story. Detection is narrow
+(`isSlideshowCollection` — type plus extension markers, never a P3
+`Manifest`/`Collection`), auto-detects by default, and disables with the
+`slideshow: false` option.
+
+```sh
+# convert a tour (URL or file) with optional player settings
+npm run convert:slideshow -- --settings settings.json --out tour.storymap.json <tour-url-or-file>
+```
+
+## Slide mapping (one annotation = one slide, in page order)
+
+| Tour field                               | Story field                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `label`                                  | story `title` (first slide headline)                                        |
+| `creator` / `rights`                     | story `credit` (+ map attribution)                                          |
+| `TextualBody value`                      | `text.text` (`text/html` verbatim)                                          |
+| target `#x,y,w,h`                        | `location.region` (origins clamped)                                         |
+| annotation / canvas ids                  | `uniqueid` + `provenance`                                                   |
+| `rotation` (non-zero)                    | `location.rotation`                                                         |
+| `filters`                                | `location.filter` (`hue_rotate` → `hueRotate`)                              |
+| `passepartout` + color/invert            | `location.mask`                                                             |
+| `audio`                                  | `narration` (full flag bag)                                                 |
+| `image_srv`                              | `location.basemap` (IIIF services and plain image files alike)              |
+| `image_static`                           | `media.url` + story `fallbackUrl`                                           |
+| `manifest_id` / `canvas_id` / `image_id` | `provenance.{manifest,canvas,image}` (canvas falls back to the target base) |
+
+`rotation: 0`, `filters: false`, `passepartout: false` and `audio: false`
+are omitted (the viewer defaults match). A target without a fragment, or
+with an unusable one, keeps the whole canvas with a warning. Audio that
+duplicates the slide media URL is kept once, as media.
+
+## Legacy v1 tours
+
+v1 documents (`AnnotationPageSequence`, one page per slide, `metadata`
+with plain `title`/`author`/`license`) map page-by-page: bodies
+concatenate with a space, the last `#x,y,w,h` fragment wins, the
+`uniqueid` is the page's first annotation id (provenance comes from the
+target's `manifest_id`/`canvas_id`/`image_id`), and the metadata becomes
+title + credit. v1 has no filters/rotation/mask/audio/static fields.
+Detection is by context plus shape, never Presentation 3.
+
+## Player settings mapping
+
+| Setting                              | Option                                                                                                                         |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `mode`                               | `mode` (`standard`/`static`)                                                                                                   |
+| `viewerheight`                       | `viewerheight` (validated `px`/`%`/`vh`)                                                                                       |
+| `autoplay` + `slidetimeout`          | `autoplay` ms (`false`/absent → `0`)                                                                                           |
+| `fxmode`                             | `fxmode` (`basic` → `slide`)                                                                                                   |
+| `progressbar`                        | `progressbar` (`false`/`"off"` → `false`)                                                                                      |
+| `textmode`                           | `textmode`                                                                                                                     |
+| `textsize`                           | `textsize`, bottom dock only (side docks ignore it — the player drops the declaration too: `"20%"/2` is `NaN` inside `calc()`) |
+| `hudcolor`/`hudbgcolor`/`hudopacity` | direct strings for the colors; `hudopacity` converts `"75"` → `75`                                                             |
+| `shownav`                            | `shownav`                                                                                                                      |
+| `showfullscreen`                     | `fullscreen`                                                                                                                   |
+| `showinfo`                           | `show_info`                                                                                                                    |
+| `showscrollbars`/`showheadings`      | `show_scrollbars`/`show_headings`                                                                                              |
+| `bgcolor`                            | `map_background_color` (approximation, documented)                                                                             |
+| `imgoverlay` + `imgoverlayurl`       | fanned out to every slide's `imgoverlay` (`"50%"` → `0.5`)                                                                     |
+
+## Loss table (warned, one `console.warn` per kind)
+
+Provenance identifiers beyond `uniqueid` (kept data-only in
+`slide.provenance`), unfollowed `next` pages (inline documents; the URL
+loader and CLI follow the chain), unknown `mode`/`fxmode`/`play`/`textmode`/
+`progressbar` values (unknown `audio.play` falls back to `auto`),
+unparsable bottom-dock `textsize`/`hudopacity`/`viewerheight`/`slidetimeout`
+(`slidetimeout` falls back to 6000), overlay enabled without a URL,
+unusable `passepartout` shapes (omitted), `imgoverlaysize` unparsable
+(silently defaults to `0.5` with no warning), audio that duplicates the
+slide media URL (kept once, as media), malformed targets/annotations, empty
+pages (skipped). Everything else translates silently — legacy v1 tours map
+fully (above) — and every translator output validates against
+`schema/storymap.schema.json`.
+
+Translated tours render through the slideshow-gated presentation fields
+(`slideshow_source`), so internal documents are unaffected — see the
+README's slideshow section.
+
+## Corpus
+
+Observed tours (structural facts only; no content archived). Hunt grounds
+exhausted per the stop rule: Forum Wissen embeds are consent-walled,
+code search doesn't index the tour JSONs, museum/partner repos hold only
+manifests — the canonical
+[`strollview-format-lib`](https://github.com/seigedigital/strollview-format-lib)
+(v1/v2 parsers, samples) is the authoritative shape reference.
+
+| Tour                      | Ver | Stops | Targets              | Extras seen                                                       | Audio                    | Services                                |
+| ------------------------- | --- | ----- | -------------------- | ----------------------------------------------------------------- | ------------------------ | --------------------------------------- |
+| Uni der Dinge (Göttingen) | v2  | 19    | frag, bare, negative | filters obj, mask obj, rotation 0                                 | none                     | IIIF 2/3, custom API                    |
+| 47 Ronin (emakimono)      | v2  | 35    | frag                 | all `false`                                                       | none                     | single `.ptif` service                  |
+| John Low (VKC)            | v2  | 36    | frag, bare, negative | mask obj (incl. tiny/out-of-range), `image_static`                | `auto`/`n/a`, Drive + S3 | IIIF 2/3 mixed                          |
+| DDD AAA (test tour)       | v2  | 17    | frag, bare           | rotation 35/181, `play: "click"`, `application/ogg`, missing keys | `click` + `auto`         | IIIF                                    |
+| Demo (Leipzig)            | v1  | 8 pp  | frag, bare           | — (v1 has none)                                                   | —                        | IIIF 2 (`.jpx` bases serve `info.json`) |
+| format-lib 1-01           | v1  | 8 pp  | frag, bare           | —                                                                 | —                        | IIIF                                    |
+
+Never observed in the wild: `next` page chains, non-IIIF image files,
+`audio.play` beyond `auto`/`click`, `mode`/`fxmode` beyond
+`standard`/`basic`. Those paths are proven synthetically (paging chain
+unit tests, local static-image e2e) and warn loudly if met.