Skip to content

Add a map-loading plugin for an accessible overlay while maps initialise - #709

Open
Nooshu wants to merge 2 commits into
DEFRA:mainfrom
Nooshu:feat/map-loading-plugin
Open

Nooshu wants to merge 2 commits into
DEFRA:mainfrom
Nooshu:feat/map-loading-plugin

Conversation

@Nooshu

@Nooshu Nooshu commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a new map-loading plugin that shows an accessible loading overlay over the map while the app downloads, mounts and loads its first tiles.

The component has no consumer-facing loading indicator today:

  • im-is-loading only hides the page body until the app mounts — an anti-flicker mechanism, not a per-map loading message.
  • A plugin's load() runs inside loadApp() after the im-core and provider chunks have downloaded, so nothing registered through the manifest can cover the chunk-download phase.
  • The documented middle slot accepts panels/controls "for loading screens", but it only exists once the React app mounts — and createRoot() discards anything already inside the container at that point.

So the plugin manages the overlay itself, outside the app: the map container is wrapped in a positioned element and the overlay appended as a sibling, which survives the React mount and covers the whole window from script execution to map:firstidle. If the page server-rendered an overlay inside the container it is adopted — moved out before createRoot() would discard it — so hosts can have the message on screen from first paint.

import createMapLoadingPlugin from '@defra/interactive-map/plugins/map-loading'

const mapLoadingPlugin = createMapLoadingPlugin({ container: 'map' })

const interactiveMap = new InteractiveMap('map', {
  plugins: [mapLoadingPlugin]
})

Dismissal is automatic on map:firstidle, on the component's .im-c-error failure markup (watched via MutationObserver — providers don't forward native map error events), on map:destroy, or after a safety timeout (default 60s, 0 disables). The overlay also re-arms across removeApp/loadApp cycles: map:ready re-shows it for a freshly created map, while an app reopened with preserved state dismisses immediately via app:opened.

Everything is configurable: text, spinner, content (Node/string/function for bespoke markup), className, role, adopt selector, fullscreen (viewport coverage for mapOnly/launcher opens), deferred (waits for the open button to be hidden — covering buttonFirst/hybrid launches and re-arming on each close), errorSelector, timeout, dismissOnFirstIdle, onShow/onDismiss(reason) callbacks, plus show(), dismiss(), isShown() and destroy() on the plugin instance and --im-map-loading-* CSS variables for theming (the overlay lives outside the app root, so the app's own custom properties don't reach it).

Wiring: plugin entry added to webpack.umd.mjs, rollup.esm.mjs and package.json exports (./plugins/map-loading and ./plugins/map-loading/css), a docs/plugins/map-loading.md page, and a listing in docs/plugins.md.

The approach was proven in a real consumer service (Planning Inspectorate's identify-consultees), where the same constraints were hit building a loading state for an inline map.

Advantages

  • Users get an immediate, accessible (role="status") loading state from the first moment — including slow connections where the vendor/provider chunks take seconds to arrive.
  • Failure paths keep working: the overlay always clears (error marker, timeout, map:destroy or explicit dismiss()), never trapping the user under a stuck overlay.
  • Launcher behaviours are covered too: deferred + fullscreen give buttonFirst/hybrid a loading state from the moment the open button is pressed.

Disadvantages / trade-offs

  • The overlay necessarily lives outside the React app, so it can't use plugin context, the app's CSS variables, or the slot system — it re-creates those affordances with its own options and CSS variables.
  • deferred mode detects "load started" by watching for the open button being hidden — a small coupling to how the launcher signals a load (a MutationObserver on the container's parent). map:ready backstops it if that signal ever changes.
  • Dismissal is keyed to the first idle only — later tile/data loads aren't re-flagged (matches maplibre's once('idle') semantics).

Risks

  • Low: entirely additive — a new plugin directory plus three one-line wiring entries. No existing code paths change.
  • The observer-based dismissal only reads querySelector matches inside the container; it can't false-positive on anything but the component's own error markup (or a host-configured errorSelector).

Test plan

  • npx jest plugins/map-loading — 53 tests, 100% statements/branches/functions/lines.
  • npm run lint — clean.
  • npx jest — full suite, 429 suites / 5951 tests pass.
  • BUILD_TARGET=map-loading npx webpack --config webpack.umd.mjs --mode production and BUILD_TARGET=map-loading npx rollup --config rollup.esm.mjs — both emit index.js, the lazy im-map-loading-plugin manifest chunk and dist/css/index.css.
  • Manual: register the plugin on an inline map under network throttling — overlay visible from first paint to first idle, dismissed cleanly; deferred + fullscreen on a buttonFirst map — overlay appears on launcher click and clears at first idle.

Nooshu and others added 2 commits November 17, 2026 11:40
The component has no consumer-facing loading indicator: im-is-loading
only hides the page body until the app mounts, and a plugin's load()
runs inside loadApp() after the im-core and provider chunks download, so
nothing registered through the manifest can cover the chunk-download
phase. createRoot() also discards anything already inside the container
when the app mounts.

The map-loading plugin manages the overlay itself, outside the app: the
container is wrapped in a positioned element and the overlay appended as
a sibling, so it survives the React mount and covers the whole window
from script execution to first idle. Dismissal happens on map:firstidle,
on the component's .im-c-error failure markup, on map:destroy, or after
a safety timeout, and the overlay re-arms across removeApp/loadApp
cycles.

Everything is configurable: message text, spinner, custom content,
adoption of server-rendered markup, fullscreen positioning for mapOnly
and launcher behaviours, deferred activation for buttonFirst/hybrid, the
error selector, the timeout, dismissal on first idle, show/dismiss
callbacks and --im-map-loading-* CSS variables for theming.
…s-reduced-motion

Skip the overlay on fast first-idle loads, and keep a static spinner ring when reduced motion is preferred.

Co-authored-by: Cursor <cursoragent@cursor.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant