@projektemacher/storymapjs 0.10.7 → 0.11.0

package/README.md

@@ -10,7 +10,9 @@ This fork is a **viewer-only library**: it renders existing StoryMap JSON
 files (or IIIF Presentation manifests) with TypeScript + Vite + OpenLayers.
 There is no authoring tool — create your storymap JSON by hand or with your
 own code, and see `docs/` for the migration notes from the original
-Knight Lab release.
+Knight Lab release. The library also exports `storymapToManifest()`, which
+produces a IIIF manifest from a storymap document (`npm run convert:iiif`
+does the same from the command line; see `docs/storymap-as-iiif-manifest.md`).
 
 ## Development
 
@@ -37,8 +39,18 @@ Points are set to only display on mouseover in image mode, but you can set map_a
 
 ## Map Options
 
-To disable connecting lines on maps set `map_as_image: true` in the storymap
-options (the default `false` renders cartography).
+To disable connecting lines on maps set `show_lines: false` in the storymap
+options (the default `true` renders cartography with `show_history_line`).
+`map_as_image: true` is something else: image-map mode, only meaningful with
+`map_type: "iiif"` (the image itself becomes the map).
+
+`storymap.map` is the raw OpenLayers map, typed with the re-exported `ol`
+types, and `getBaseLayer()`, `getOverlayLayers()`, `getMinimap()`,
+`getMarkers()` and friends hand out the layers the viewer built. Listen for
+`imageready` to run code against the real imagery, and call
+`storymap.dispose()` when the embedding view goes away — see
+[docs/migration-from-knightlab.md](docs/migration-from-knightlab.md#reaching-the-map-layers-and-markers)
+for the full surface.
 
 The menubar buttons can be disabled individually:
 
@@ -62,6 +74,85 @@ More config options available to do what you want with the line:
 
 To disable zoom calculation/edit zoom level set calculate_zoom to false in the config options.
 
+### More data options
+
+Beyond the map options above, the storymap data takes `overlays[]`
+(stacked raster layers over the basemap), `tilejson` (a TileJSON source for
+the base layer), `overview_extent` (the overview slide's bounds),
+`keyboard` (page-wide arrow-key navigation for multi-viewer pages),
+per-slide `marker: { popup, audioBadge }` (the active marker's card, openable
+via `storymap.openMarkerPopup(n)`, and the narration/audio dot) and
+`narration: { url }` per slide. `autoplay_media` is global (wait for slide
+media to end while autoplaying); the per-slide dwell is `slidetimeout`.
+All are validated
+against `schema/storymap.schema.json` — read it (or `src/types.ts`) for the
+full list with defaults.
+
+`show_layers_control: true` adds a menubar disclosure button listing the
+`overlays[]` as checkboxes and `basemaps[]` as basemap radios, so the
+visitor can switch layers without touching code.
+
+`theme: "dark"` forces the dark palette, `"light"` pins the light one;
+unset, the widget follows `prefers-color-scheme`.
+
+### Slideshow-style tours
+
+Slides can carry per-slide presentation for image tours (a stop can restyle
+the view while it is active; everything is optional and validated against
+`schema/storymap.schema.json`):
+
+    location: {
+        region: [x, y, w, h],  // image-pixel stop (IIIF xywh); negative origins clamp to the canvas
+        rotation: 45,          // view rotation in degrees clockwise
+        filter: { sepia: 40 }, // brightness/contrast/saturate 0-200 (%), hueRotate -180-180 (°), sepia 0-100 (%), blur 0-20 (px)
+        mask: { x: 0.1, y: 0.1, w: 0.8, h: 0.8, opacity: 0.5 },  // spotlight mask (fractions) + color/invert
+        basemap: "osm:bright", // per-slide basemap (any map_type, IIIF info.json URL or image file)
+    },
+    narration: { url, loop, offset, play: "auto"|"click", stopOnExit, stopAllPrevious },
+    slidetimeout: 9000,        // per-slide autoplay dwell in ms (0 holds); default is the global autoplay
+    imgoverlay: { url, size, extent, opacity },  // image overlay while the slide is active
+
+Audio/video media take the same `offset`/`loop`/`play`/`stopOnExit` flags
+on the slide's `media` object (`stopAllPrevious` is narration-only).
+
+When a slide's IIIF `info.json` cannot be loaded, `iiif: { width, height,
+fallbackUrl }` paints the static image instead of a blank basemap. Without
+stated dimensions the viewer probes the fallback image's natural size first,
+but only for slideshow tours (15s timeout); other documents keep the logged
+error path. Per-slide static basemaps (`image_srv` pointing at a plain
+image file, absolute or same-origin relative) probe the same way, and a
+failed `info.json` fetch falls back to a probed static image in place.
+
+The player chrome is opt-in storymap options (absent means the default
+layout): `textmode: "left"|"right"|"bottom"` with `textsize` (10–80 %,
+bottom dock only — the player drops side-dock sizes too),
+`progressbar: "bar"|"dots"|"squares"|"block"|"thinblock"|"off"` (`true`
+means `"bar"`, `false` means hidden),
+`fxmode: "slide"|"fade"|"none"`, `mode: "static"` (stacked reading list with
+scroll-spy map sync), `hudcolor`/`hudbgcolor`/`hudopacity`,
+`shownav`/`show_headings`/`show_scrollbars`/`show_info` toggles and
+`viewerheight: "400px"`.
+
+**IIIF round-trip:** the per-slide fields do survive — `rotation`,
+`filter`, `mask`, `basemap`, `slidetimeout`, `imgoverlay`, `provenance`
+and the playback bags travel as `storymap:` terms (see
+[docs/storymap-as-iiif-manifest.md](docs/storymap-as-iiif-manifest.md)).
+The player chrome does **not**: it has no IIIF vocabulary and is
+translator-only (a storymap→manifest→storymap cycle drops it).
+
+These presentation fields render **only for slideshow tours** (documents
+loaded from that format, which set the internal `slideshow_source` marker).
+Hand-written storymap documents and IIIF manifests keep the long-standing
+rendering even when they name the new keys — captions always show, the
+autoplay interval stays global, the panel keeps its default dock. Hosts may
+pass `slideshow_source: true` explicitly as an escape hatch (e.g. in tests).
+
+Slideshow tours (W3C `AnnotationCollection` documents) load directly — by
+object, file or URL, following `next` pages — or convert offline with
+`npm run convert:slideshow -- [--settings settings.json] [--out out.json] <tour-url-or-file>`
+(see [docs/slideshow.md](docs/slideshow.md) for the field mapping,
+player-settings handling and loss table).
+
 Images can now be used in place of map pins.
 Use `image` inside the location object and include a url to use, together with
 `use_custom_marker: true` in the location object (or set `use_custom_markers:
@@ -92,7 +183,11 @@ an opaque slide panel instead of the gradient over the map), set
 
 Any value containing `{z}` renders as a raster XYZ layer; a path without `{z}`
 that looks like a URL/path renders as a vector style layer; anything else falls
-back to classic OSM raster.
+back to classic OSM raster — except `"none"`, which builds no map at all and
+runs the story as text and media only. A full template naming a known provider
+(`https://tile.openstreetmap.org/{z}/{x}/{y}.png`) is credited to that
+provider; anything else gets the generic "Map data" line (add your own via
+`attribution`).
 
 ### Switching the basemap at runtime
 
@@ -103,11 +198,18 @@ current slide is re-fitted after the swap.
 
 ### Icons
 
-Default pins use the bundled `vco-icons` font (`dist/css/icons/`, referenced via
-relative `./icons/...` URLs from `dist/css/storymap.css`), so pins render on
-subpath deploys, bundler consumers (Vite leaves absolute `/css/...` untouched)
-and `file://`/Electron hosts without extra configuration. Import the stylesheet
-once (`import "@projektemacher/storymapjs/css/storymap.css"`).
+Default pins use the bundled `vco-icons` font (`dist/css/icons/`). The SCSS
+source uses the absolute public path (`/css/icons/...`) so `vite dev` serves
+the fonts directly; `vite build` rewrites them to relative `./icons/...` in
+`dist/css/storymap.css`, so pins render on subpath deploys, for bundler
+consumers and on `file://`/Electron hosts without extra configuration.
+Import the stylesheet once
+(`import "@projektemacher/storymapjs/css/storymap.css"`).
+
+Font themes (`font_css: "stock:<name>"`) resolve via `import.meta.url`, so
+they only work script-tagged, unbundled. A bundler consumer imports the theme
+instead (`import "@projektemacher/storymapjs/css/fonts/font.default.css"`)
+and passes `font_css: false` for no injected `<link>`.
 
 ## Custom HTML in slide content
 
@@ -123,14 +225,22 @@ images, lists, emphasis and spans in your slides, e.g.:
 
 The `vco-note` span renders as a small grey note, like the built-in credits.
 
-**Caution:** the text is rendered raw — it is not sanitized. Only load
-storymaps from sources you trust.
+**Caution:** the text is sanitized, but sanitizing is a mitigation rather
+than a guarantee. Prose and media formatting survive (`class`, `alt`, `width`,
+table attributes, and so on), scripts and other executable tags are dropped
+with their contents, event-handler attributes are stripped, every URL
+attribute is checked to be `http(s)`, and `<iframe>` embeds are rebuilt into
+a sandboxed, `no-referrer` element. `style`, `id` and `name` are _not_ allowed,
+and a link's `target` is always forced to `_blank`. The same sanitizer covers
+media credit, media caption, the navigation headline and the map attribution
+line. Still: only load storymaps from sources you trust.
 
 ## GDPR consent for external services
 
 Set the `consent_required` option to `true` to ask for permission before
 anything is loaded from external services (media embeds such as YouTube,
-Twitter or SoundCloud, map tiles, and external font CSS):
+Twitter or SoundCloud, slide narration audio, map tiles, and external font
+CSS):
 
     {
         "consent_required": true,
@@ -138,17 +248,58 @@ Twitter or SoundCloud, map tiles, and external font CSS):
     }
 
 Each service asks with an Allow/Deny panel; answering one panel resolves every
-pending panel of the same service. If a decision was already stored in the
-cookie, the panel is skipped entirely. Denied services show a placeholder
+pending panel of the same service. Denied services show a placeholder
 instead of the media, and the map renders without tiles until they are
-allowed. Decisions are stored in a cookie (`storymapjs-consent`) for 90
-days — clearing cookies asks again.
+allowed.
+
+Before the story loads, one dialog lists every external service it uses (map
+tiles, media services including slide narration, external fonts) with three
+choices: **Allow all**, **Decline all**, or a decision per service. A story
+with no map (`map_type: "none"`) has no tile row to answer. The dialog is
+skipped once every service has a stored decision; per-service panels still
+appear for services discovered later (e.g. a preloaded slide).
+
+Decisions are stored in `localStorage` under `storymapjs-consent` and have no
+expiry — clearing site data asks again.
+
+The consent labels are **not** fully translated. `src/language/locale/en.json`
+defines every string (34 keys across 29 locale files: English plus 28
+translations). German is missing 1 key, most locales are missing 9 (the audio
+badge, autoplay, layer-switcher, iframe-title and narration-consent strings),
+and five locales (`et`, `is`, `nn`, `ur`, `sr`) are missing 18–19 (additionally
+the fullscreen, consent-dialog, error and overview strings). Run
+`npm run check:locales` to see the current state — it reports the gap per
+locale and is expected to be runnable without failing.
 
 ## Troubleshooting
 
 If a storymap fails to render, open the browser console: the viewer logs
 fetch and validation errors (e.g. "could not load storymap data from ...").
-The `error` event also fires for programmatic consumers.
+The `error` event also fires for programmatic consumers. The full event
+reference (payloads included) is [docs/events.md](docs/events.md).
+
+## Accessibility
+
+Supported, and covered by tests: text alternatives on slide images
+(decorative `alt=""` included); real `<button>` menubar actions and slide
+navigation; polite live-region slide announcements; reduced-motion handling
+of the slide glide and autoplay; an embed page that does not disable zoom;
+sanitized author tables that keep their semantics; slides hidden from
+assistive tech while inactive (`aria-hidden` + `inert`), with a layer
+switcher built from native checkboxes, radios and fieldsets; keyboard
+operable map pins and message dismissal; a skip link to the slide content;
+an autoplay pause/resume toggle; slide text pronounced in its own language
+(`lang`); consent dialogs exposed with labels and focus; media errors
+announced as alerts; and a motion kill-switch that also honors an
+OS reduced-motion toggle flipped mid-story.
+
+Known limitations (not fixed here): map markers are pointer-only; audio and
+video have no viewer-side captions or transcripts; narration ships without a
+transcript; focus moves only when the layer panel closes with Escape; labels
+and announcements are hardcoded English; several muted text colors fall
+below 4.5:1; third-party embeds are the vendor's conformance. No VPAT or
+ACR is claimed — §508 conformance is decided per deliverable by an
+external audit.
 
 ## Bundled credentials
 

package/dist/assets/demo-bWnOyfUw.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DQ32hWBM.js";function t(e){document.title=`StoryMapJS: `+e.title}window.storymap=new e(`storymap-embed`,`./demo.json`,{},{title:t});

package/dist/assets/harness-C3JUv5Ii.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DQ32hWBM.js";import{n as t,t as n}from"./harness-support-CjfZIVeb.js";window.__smErrors=[],window.__smReady=!1,window.addEventListener(`error`,e=>{window.__smErrors.push(String(e.message||e))});var r=new URLSearchParams(window.location.search),i=r.get(`manifest`),a=r.get(`slideshow`),o=r.get(`url`),s=i===null?a===null?r.get(`example`):a:i,c=i===null?a===null?`/examples/`:`/examples-slideshow/`:`/examples-iiif/`,l={};if(r.get(`options`))try{l=JSON.parse(r.get(`options`))}catch(e){window.__smErrors.push(`harness: bad options param: `+e)}var u=t(window);u&&(l.tile_source_factory=u);var d=o??c+s+`.json`;fetch(d).then(e=>e.json()).then(t=>{let i=new e(`storymap-embed`,a!==null&&o===null?d:t,l,{error:e=>{window.__smErrors.push(`storymap: `+(e.message||String(e)))}});window.__sm=i,n(i,r.get(`record`),window),window.__smReady=!0}).catch(e=>{window.__smErrors.push(`harness: `+(e&&e.message?e.message:String(e))),window.__smReady=!0});

package/dist/assets/harness-multi-XZNex3tb.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DQ32hWBM.js";import{n as t,t as n}from"./harness-support-CjfZIVeb.js";window.__smErrors=[],window.__smReady=!1,window.addEventListener(`error`,e=>{window.__smErrors.push(String(e.message||e))});var r=new URLSearchParams(window.location.search),i={a:r.get(`a`)??`katrina`,b:r.get(`b`)??`seurat`},a={a:o(r.get(`aopts`)),b:o(r.get(`bopts`))};for(let[e,n]of Object.entries(a)){let r=t(window);r&&(n.tile_source_factory=r),a[e]=n}function o(e){if(!e)return{};try{return JSON.parse(e)}catch(e){return window.__smErrors.push(`harness-multi: bad options: `+e),{}}}async function s(e){let t=await fetch(`/examples/`+i[e]+`.json`);if(!t.ok)throw Error(`no example `+i[e]);return t.json()}var c=r.get(`shared`)===`1`?await s(`a`):null;try{let t=c??await s(`a`);window.__smA=new e(`sm-a`,t,a.a,{}),n(window.__smA,r.get(`record`),window,`A`);let i=c??await s(`b`);window.__smB=new e(`sm-b`,i,a.b,{}),n(window.__smB,r.get(`record`),window,`B`)}catch(e){window.__smErrors.push(`harness-multi: `+(e?.message??e))}window.__smReady=!0;

package/dist/assets/harness-support-CjfZIVeb.js

@@ -0,0 +1 @@
+function e(e,t,r,i=``){let a=(t??``).split(`,`).map(e=>e.trim()).filter(Boolean);if(a.length!==0){r.__events=r.__events??[];for(let t of a)e.on(t,e=>{r.__events.push({type:t,viewer:i,payload:n(e)})})}}function t(e){return typeof e.__tileSourceFactory==`function`?e.__tileSourceFactory:void 0}function n(e){if(typeof e!=`object`||!e)return e;let t={};for(let[a,o]of Object.entries(e))if(typeof o!=`object`||!o)t[a]=typeof o==`function`?`[fn]`:o;else if(a===`source`||a===`layer`)t[a]={type:o.constructor?.name??null,state:typeof o.getState==`function`?o.getState():void 0,url:o.url_??o.href_??r(o,`url`)};else if(a===`target`)t[a]=i(o);else if(Array.isArray(o))t[a]=o.map(e=>n(e));else{let e=Object.getPrototypeOf(o);t[a]=e===Object.prototype||e===null?n(o):{type:o.constructor?.name??null}}return t}function r(e,t){try{return e.get?.(t)}catch{return}}function i(e){let t=a(e)?e:a(e?.map)?e.map:a(e?._map)?e._map:null;if(!t)return{type:e?.constructor?.name??null};let n=t.getView(),r=t.getSize();return{type:e?.constructor?.name??null,size:r?[r[0],r[1]]:null,center:n?.getCenter?.()??null,resolution:n?.getResolution?.()??null,projection:n?.getProjection?.()?.getCode?.()??null}}function a(e){return!!e&&typeof e.getSize==`function`&&typeof e.getView==`function`}export{t as n,e as t};

package/dist/assets/index-wHPqGrBS.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";var e=[{id:`katrina`,title:`Hurricane Katrina`,kind:`Map`},{id:`population`,title:`US Population Shifts`,kind:`Map`},{id:`marktwain`,title:`Mark Twain's Travels`,kind:`Map`},{id:`seurat`,title:`A Sunday on La Grande Jatte`,kind:`Large image (legacy)`},{id:`iiif-wellcome`,title:`Wellcome Collection (IIIF)`,kind:`IIIF`},{id:`president`,title:`A Month in the Life of President Obama`,kind:`Map`},{url:`https://s3.amazonaws.com/uploads.knightlab.com/storymapjs/a1a349b51799ee49e96bed10cc235e7f/garden-of-earthly-delights/published.json`,thumb:`bosch-garden`,title:`The Garden of Earthly Delights – Hieronymus Bosch`,kind:`Knight Lab example`},{url:`https://uploads.knightlab.com/storymapjs/3df56e350378e51781746bfb2a2ea428/test/published.json`,thumb:`southern-literary-trail`,title:`Southern Literary Trail`,kind:`Georgia Humanities`}];function t(e){let t=e.url??`examples/`+e.id+`.json`,n=e.thumb??e.id??``,r=document.createElement(`a`);r.className=`card`,r.href=`./embed/index.html?url=${encodeURIComponent(t)}`;let i=document.createElement(`span`);i.className=`header-image`;let a=document.createElement(`span`);a.className=`header-image-background bw`,a.style.backgroundImage=`url('./thumbs/${n}.jpg'), linear-gradient(135deg, #b8b8b8, #646464)`,a.setAttribute(`role`,`img`),a.setAttribute(`aria-label`,e.title),i.append(a);let o=document.createElement(`article`);o.className=`card-content`;let s=document.createElement(`h3`);s.textContent=e.title,o.append(s);let c=document.createElement(`footer`);return c.textContent=e.kind,r.append(i,o,c),r}var n=document.getElementById(`examples-cards`);if(n){n.classList.add(`cards-link`);for(let r of e)n.append(t(r))}var r=document.getElementById(`demo-frame`);if(r){let e=()=>{r.style.height=window.innerHeight-20+`px`};e(),window.addEventListener(`resize`,e)}