Repository navigation
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
map-loadingplugin 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-loadingonly hides the page body until the app mounts — an anti-flicker mechanism, not a per-map loading message.load()runs insideloadApp()after theim-coreand provider chunks have downloaded, so nothing registered through the manifest can cover the chunk-download phase.middleslot accepts panels/controls "for loading screens", but it only exists once the React app mounts — andcreateRoot()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 beforecreateRoot()would discard it — so hosts can have the message on screen from first paint.Dismissal is automatic on
map:firstidle, on the component's.im-c-errorfailure markup (watched viaMutationObserver— providers don't forward native maperrorevents), onmap:destroy, or after a safetytimeout(default 60s,0disables). The overlay also re-arms acrossremoveApp/loadAppcycles:map:readyre-shows it for a freshly created map, while an app reopened with preserved state dismisses immediately viaapp:opened.Everything is configurable:
text,spinner,content(Node/string/function for bespoke markup),className,role,adoptselector,fullscreen(viewport coverage formapOnly/launcher opens),deferred(waits for the open button to be hidden — coveringbuttonFirst/hybridlaunches and re-arming on each close),errorSelector,timeout,dismissOnFirstIdle,onShow/onDismiss(reason)callbacks, plusshow(),dismiss(),isShown()anddestroy()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.mjsandpackage.jsonexports (./plugins/map-loadingand./plugins/map-loading/css), adocs/plugins/map-loading.mdpage, and a listing indocs/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
role="status") loading state from the first moment — including slow connections where the vendor/provider chunks take seconds to arrive.map:destroyor explicitdismiss()), never trapping the user under a stuck overlay.deferred+fullscreengivebuttonFirst/hybrida loading state from the moment the open button is pressed.Disadvantages / trade-offs
deferredmode detects "load started" by watching for the open button being hidden — a small coupling to how the launcher signals a load (aMutationObserveron the container's parent).map:readybackstops it if that signal ever changes.once('idle')semantics).Risks
querySelectormatches inside the container; it can't false-positive on anything but the component's own error markup (or a host-configurederrorSelector).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 productionandBUILD_TARGET=map-loading npx rollup --config rollup.esm.mjs— both emitindex.js, the lazyim-map-loading-pluginmanifest chunk anddist/css/index.css.inlinemap under network throttling — overlay visible from first paint to first idle, dismissed cleanly;deferred+fullscreenon abuttonFirstmap — overlay appears on launcher click and clears at first idle.