@projektemacher/storymapjs 0.10.8 → 0.11.0

package/CHANGELOG

@@ -1,3 +1,84 @@
+0.11.0 (2026-10-07)
+------------------------
+Added
+-----
+- Inactive slides are hidden from assistive tech (`aria-hidden` + `inert`
+  in `Slide.setActive()`), so screen readers no longer read every
+  off-screen slide; preloading (including iframes) is unaffected
+- Keyboard access: map pins are focusable buttons (Enter/Space activates,
+  focus returns on popup close), messages dismiss from the keyboard, and a
+  skip link jumps to the slide content. Autoplay gains a menubar
+  pause/resume toggle; slide text carries its `lang`; consent dialogs are
+  labelled dialogues with focus; media errors announce via `role=alert`
+- Reduced motion is honored everywhere it matters: map glides, line draw,
+  background fades, nav intro, smooth scroll and the loader freeze, and an
+  OS toggle flipped mid-story stops autoplay. Touch targets are 44px,
+  muted text meets contrast, and focus rings are visible
+- Programmatic popup cards: `storymap.openMarkerPopup(n)` navigates to the
+  stop and opens its card (false and no navigation when disabled, out of
+  range, disposed or mapless), plus `closeMarkerPopup(n?)` and
+  `isPopupOpen(n)`. The marker itself exposes `openPopup()` /
+  `closePopup()` / `togglePopup()` / `isPopupEnabled()` / `popupOpen`,
+  and the `StoryMapMarker` type is exported for hosts
+- `popupopen` / `popupclose` (`{ marker_number, current_slide }`) and a
+  viewer-level `markerclick` re-fire, so hosts can tell marker clicks apart
+  from programmatic navigation
+- `tweetAuthor()` next to `tweetId()`: `Twitter` extracts both through the
+  shared helpers instead of its own regex
+- `font_css: false` (or `"none"`) injects no theme stylesheet for
+  bundler consumers that import it themselves; the consent dialog lists no
+  font service for it, and a failing theme load warns with its URL. The
+  IIIF `storymap:fontCss` term round-trips `false`
+- Layer switcher: `show_layers_control: true` adds a menubar disclosure
+  button with basemap radios (`basemaps[]`, entry 0 initial unless
+  `map_type` says otherwise) and overlay checkboxes (rows track built
+  layers, so malformed entries never appear). Overlay `label` (string or
+  function), `locked` (checked and disabled) and `control: false` (hidden
+  row) annotate entries; cross-projection basemaps are refused with a
+  warning. Fires `basemapchange` / `overlaychange`, also on the viewer
+- IIIF narration (V1 of #358): a `motivation: "supplementing"` Sound/Video
+  body plays as `slide.narration`, and the writer emits one back. Array
+  `motivation` values are honored everywhere — previously an array read as
+  "no motivation" and was accepted as the canvas painting, shadowing the
+  real media
+- Second visible media slot (V2 of #358): `media_extra` renders further media
+  items after the primary one (`media_layout: "stack"`, the default, or
+  `"row"` for two side-by-side items); documents without it render
+  identically. Extra `painting` annotations read as `media_extra` and are
+  written back, so the slot round-trips — only the layout stays viewer-side,
+  IIIF has no term for it. Consent, the audio badge and the popup thumbnail
+  all see every item
+- Dark theme without a second stylesheet: every widget colour is a
+  `--vco-*` custom property (Sass values kept as fallbacks, so the default
+  render is unchanged); `theme: "dark"` forces the dark palette, `"light"`
+  pins the light one, unset follows `prefers-color-scheme`. The unshippable
+  `VCO.StoryMap.Dark.scss` / `Variables.Dark.scss` pair is deleted, the
+  dead widget reset is live again, and dark text pairs clear AA. The
+  landing page follows the OS scheme too
+- Typed events: every emitter has an `*Events` map (exported from the
+  library), so `storymap.on("chnage", …)` is a compile error and handlers
+  infer their payload. `fire()` can no longer be handed a `type`/`target`
+  in the payload, `off()` removes all matches, and teardowns detach
+  their listeners
+- Full XYZ templates naming a known provider are credited to it
+  (`tile.openstreetmap.org` and subdomains, `stadiamaps.com`,
+  `openmaptiles.org`, `mapbox.com`, `arcgisonline.com`/`esri.com`,
+  `carto.com`/`basemaps.cartocdn.com` — subdomains match their parent), in
+  both the rendered line and the source attributions. Relative templates
+  still render "Map data"
+
+Changed
+-------
+- The IIIF reader/writer share `src/storymap/iiif-shared.ts`
+  (`LOCATION_PROPERTIES`, JSON guards, bbox and URL checks) instead of
+  three copies; the writer's Node CLI import carries an explicit `.ts`
+  extension, which type-stripping resolution requires
+- Map attribution comes from one provider-credit table (linked HTML and
+  plain text cannot drift apart); font-theme URL helpers live in
+  `src/storymap/font-css.ts` (re-exported from `StoryMap`)
+- Error paths log with `console.warn`, prefixed `StoryMapJS:`, instead of
+  `console.log`
+
 0.10.8 (2026-09-29)
 ------------------------
 Code audit: one regression, a set of latent bugs, seven stored-XSS sinks, a

package/README.md

@@ -39,8 +39,10 @@ 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()`,
@@ -72,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:
@@ -103,7 +184,10 @@ 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 — except `"none"`, which builds no map at all and
-runs the story as text and media only.
+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
 
@@ -114,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
 
@@ -172,9 +263,11 @@ 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; 28 bundled locales fall back to English for the keys
-they lack — most are missing one, a handful are missing around ten (the
-per-service consent prompts and the fullscreen button labels). Run
+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.
 
@@ -182,7 +275,31 @@ locale and is expected to be runnable without failing.
 
 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-DBpeF31K.js → demo-bWnOyfUw.js}

@@ -1 +1 @@
-import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DXalctuR.js";function t(e){document.title=`StoryMapJS: `+e.title}window.storymap=new e(`storymap-embed`,`./demo.json`,{},{title:t});
+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-CYHgI0a9.js → harness-multi-XZNex3tb.js}

@@ -1 +1 @@
-import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DXalctuR.js";import{n as t,t as n}from"./harness-support-Do7sIp2j.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;
+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-Do7sIp2j.js → harness-support-CjfZIVeb.js}

@@ -1 +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: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};
+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};