@sjvair/monitor-map 4.1.0 → 4.2.0

package/dist/lib/map/map-style-state.svelte.js

@@ -5,7 +5,12 @@ import { variantForStyle } from "./basemap";
 class MapStyleState {
     referenceStyle = $state.raw(DefaultMapStyle.getReferenceStyle());
     variant = $state.raw(DefaultMapStyle);
+    // The variant last handed to setStyle (loaded or still loading); null once a load has failed
+    // with nothing left to fall back to, so that any later selection is tried again.
     applied = DefaultMapStyle;
+    // The variant the map last finished loading, which a failed change falls back to.
+    loaded = DefaultMapStyle;
+    stopWaiting = null;
     selectReferenceStyle(style) {
         this.referenceStyle = style;
         this.selectVariant(variantForStyle(style, this.variant));
@@ -19,17 +24,63 @@ class MapStyleState {
         this.selectVariant(DefaultMapStyle);
     }
     apply() {
+        if (!mapManager.map || this.variant === this.applied)
+            return;
+        this.load(this.variant);
+    }
+    load(variant) {
         const map = mapManager.map;
-        if (!map || this.variant === this.applied)
+        if (!map)
             return;
-        this.applied = this.variant;
+        // A newer change supersedes one still in flight.
+        this.stopWaiting?.();
+        this.applied = variant;
         // setStyle wipes every custom source/layer; re-add enabled integrations once it loads.
-        map.once("style.load", () => {
+        const onLoad = () => {
+            this.stopWaiting?.();
+            this.loaded = variant;
             mapManager.styleLoading = false;
             integrationsManager.refresh();
-        });
+        };
+        // "error" also fires for tiles, sprites and glyphs; only the style document failing means
+        // the change failed.
+        const onError = (event) => {
+            if (!isRequestFor(event.error, variant.getExpandedStyleURL()))
+                return;
+            this.stopWaiting?.();
+            this.recover(variant);
+        };
+        this.stopWaiting = () => {
+            map.off("style.load", onLoad);
+            map.off("error", onError);
+            this.stopWaiting = null;
+        };
+        map.on("style.load", onLoad);
+        map.on("error", onError);
         mapManager.styleLoading = true;
-        map.setStyle(this.variant);
+        map.setStyle(variant);
     }
+    /**
+     * A style that fails to load leaves the map with no style at all, so go back to the last one
+     * that loaded and make the selection say so. When that one fails too (e.g. offline) there is
+     * nothing to draw on: `styleLoading` stays set, since integrations cannot add layers to a
+     * missing style, and the next selection starts a fresh attempt.
+     */
+    recover(failed) {
+        if (failed === this.loaded) {
+            this.applied = null;
+            return;
+        }
+        this.variant = this.loaded;
+        this.referenceStyle = this.loaded.getReferenceStyle();
+        this.load(this.loaded);
+    }
+}
+/** Whether a map "error" event's error is a failed request for `url`, ignoring the query. */
+function isRequestFor(error, url) {
+    const failed = error?.url;
+    if (typeof failed !== "string")
+        return false;
+    return failed.split("?")[0] === url.split("?")[0];
 }
 export const mapStyleState = new MapStyleState();

package/dist/lib/monitors/monitor-details.svelte.d.ts

@@ -0,0 +1,15 @@
+import { type MonitorDetails } from "@sjvair/sdk";
+export type MonitorDetailsStatus = "loading" | "ready" | "not-found" | "failed";
+/**
+ * One monitor, fetched by id. Unlike `monitorsManager.latest`, this does not depend on the
+ * map's pollutant or on the monitor being active, so the detail panel can show any monitor.
+ */
+export declare class MonitorDetailsState {
+    #private;
+    monitor: MonitorDetails | null;
+    status: MonitorDetailsStatus;
+    load(id: string): Promise<void>;
+    /** Re-fetches the monitor already shown. A failure keeps the data on screen. */
+    refresh(): Promise<void>;
+    retry(): Promise<void>;
+}

package/dist/lib/monitors/monitor-details.svelte.js

@@ -0,0 +1,63 @@
+import { getMonitorDetails } from "@sjvair/sdk";
+/**
+ * One monitor, fetched by id. Unlike `monitorsManager.latest`, this does not depend on the
+ * map's pollutant or on the monitor being active, so the detail panel can show any monitor.
+ */
+export class MonitorDetailsState {
+    monitor = $state.raw(null);
+    status = $state("loading");
+    #id = null;
+    // Bumped per request; a response for anything but the latest request is dropped.
+    #request = 0;
+    async load(id) {
+        this.#id = id;
+        const request = ++this.#request;
+        this.monitor = null;
+        this.status = "loading";
+        try {
+            const monitor = await getMonitorDetails(id);
+            if (request !== this.#request)
+                return;
+            this.monitor = monitor;
+            this.status = "ready";
+        }
+        catch (error) {
+            if (request !== this.#request)
+                return;
+            if (isNotFound(error)) {
+                this.status = "not-found";
+                return;
+            }
+            console.error(error);
+            this.status = "failed";
+        }
+    }
+    /** Re-fetches the monitor already shown. A failure keeps the data on screen. */
+    async refresh() {
+        if (this.status !== "ready" || this.#id === null)
+            return;
+        const request = ++this.#request;
+        try {
+            const monitor = await getMonitorDetails(this.#id);
+            if (request !== this.#request)
+                return;
+            this.monitor = monitor;
+        }
+        catch (error) {
+            if (request === this.#request)
+                console.error(error);
+        }
+    }
+    retry() {
+        return this.#id === null ? Promise.resolve() : this.load(this.#id);
+    }
+}
+/**
+ * The SDK rejects a failed request with `cause.result.status` set to the HTTP status, or,
+ * when it could not parse the error body, with the `Response` itself as the cause.
+ */
+function isNotFound(error) {
+    const cause = error
+        ?.cause;
+    return cause?.result?.status === 404 || cause?.status === 404;
+}

package/dist/lib/monitors/monitors-map-integration.svelte.js

@@ -257,9 +257,9 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
             clickManager.unregister([this.referenceId]);
             this.tooltipManager.disable();
             this.renderer.remove();
-            this.icons.loadIcons().then(() => {
-                if (mapManager.styleLoading)
-                    return;
+            // Clustering may be toggled again before the icons arrive; only the latest apply runs.
+            this.supersedePending();
+            this.whenIconsLoad(() => {
                 this.renderer.apply(this.handleMonitorClick);
                 this.tooltipManager.enable();
                 this.applySelectedState();
@@ -271,9 +271,7 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
             this.tooltipManager.enable();
             clickManager.unregister([this.referenceId]);
             super.apply();
-            this.icons.loadIcons().then(() => {
-                if (mapManager.styleLoading)
-                    return;
+            this.whenIconsLoad(() => {
                 clickManager.register([this.referenceId], this.handleMonitorClick);
                 this.applySelectedState();
             });

package/dist/lib/monitors/monitors.svelte.d.ts

@@ -2,6 +2,13 @@ import { type MonitorData, type MonitorLatestType, type MonitorsMeta, type SJVAi
 import { XMap } from "@tstk/builtin-extensions";
 import { Interval } from "@tstk/utils";
 import type { MonitorsDataSource } from "./types";
+export interface MonitorsInitOptions {
+    /**
+     * Start the 2-minute polling once the initial load finishes. Defaults to true; pass false to
+     * load the data without showing a map (`resumeAutoUpdate()` starts polling later).
+     */
+    autoUpdate?: boolean;
+}
 declare class MonitorsManager implements MonitorsDataSource {
     #private;
     autoUpdate: Interval;
@@ -15,12 +22,15 @@ declare class MonitorsManager implements MonitorsDataSource {
     /**
      * Safe to call from several places: overlapping calls share one run, and a failed run can
      * be retried. An explicit "pm25"/"o3" wins over a call without one, whichever came first;
-     * between two explicit values the most recent wins.
+     * between two explicit values the most recent wins. Polling starts when the run finishes
+     * unless every call sharing it passed `autoUpdate: false`. A no-op once initialized, so it
+     * never restarts polling either: that is `resumeAutoUpdate()`.
      */
-    init(urlPollutant?: string | number | boolean): Promise<void>;
+    init(urlPollutant?: string | number | boolean, options?: MonitorsInitOptions): Promise<void>;
     /**
-     * Restarts polling after something stopped it (MonitorMapLayout stops it on destroy),
-     * refreshing first since the data may be stale. A no-op before init or while polling.
+     * Starts polling when it is not running: after something stopped it (MonitorMapLayout stops
+     * it on destroy) or after an init that opted out of it. Refreshes first since the data may
+     * be stale. A no-op before init or while polling.
      */
     resumeAutoUpdate(): void;
     update(): Promise<void>;

package/dist/lib/monitors/monitors.svelte.js

@@ -12,6 +12,7 @@ class MonitorsManager {
     levels = $derived(this.meta?.entryType(this.pollutant ?? this.meta.default_pollutant).asIter.levels || null);
     #initPromise = null;
     #requestedPollutant = null;
+    #requestedAutoUpdate = false;
     constructor() {
         // Refetch monitors when the pollutant changes after the initial load, wherever the change
         // comes from (Pollutant menu, URL sync, a host's own UI). Clearing first blanks the markers
@@ -36,17 +37,22 @@ class MonitorsManager {
     /**
      * Safe to call from several places: overlapping calls share one run, and a failed run can
      * be retried. An explicit "pm25"/"o3" wins over a call without one, whichever came first;
-     * between two explicit values the most recent wins.
+     * between two explicit values the most recent wins. Polling starts when the run finishes
+     * unless every call sharing it passed `autoUpdate: false`. A no-op once initialized, so it
+     * never restarts polling either: that is `resumeAutoUpdate()`.
      */
-    init(urlPollutant) {
+    init(urlPollutant, options = {}) {
         if (this.initialized)
             return Promise.resolve();
+        if (options.autoUpdate !== false)
+            this.#requestedAutoUpdate = true;
         if (urlPollutant === "pm25" || urlPollutant === "o3") {
             this.#requestedPollutant = urlPollutant;
         }
         this.#initPromise ??= this.#runInit().finally(() => {
             this.#initPromise = null;
             this.#requestedPollutant = null;
+            this.#requestedAutoUpdate = false;
         });
         return this.#initPromise;
     }
@@ -80,12 +86,14 @@ class MonitorsManager {
         }
         this.pollutant = fetchedPollutant;
         this.latest = latest;
-        this.autoUpdate.start();
+        if (this.#requestedAutoUpdate)
+            this.autoUpdate.start();
         this.initialized = true;
     }
     /**
-     * Restarts polling after something stopped it (MonitorMapLayout stops it on destroy),
-     * refreshing first since the data may be stale. A no-op before init or while polling.
+     * Starts polling when it is not running: after something stopped it (MonitorMapLayout stops
+     * it on destroy) or after an init that opted out of it. Refreshes first since the data may
+     * be stale. A no-op before init or while polling.
      */
     resumeAutoUpdate() {
         if (!this.initialized || this.autoUpdate.isActive)

package/dist/lib/monitors/panel-pollutant.d.ts

@@ -0,0 +1,37 @@
+/** The pollutants the detail panel can show, in order of preference. */
+export declare const PANEL_POLLUTANTS: readonly ["pm25", "o3"];
+export type PanelPollutant = (typeof PANEL_POLLUTANTS)[number];
+/** The slice of the SDK's `MonitorDetails` this module reads. */
+export interface PanelMonitor {
+    type: string;
+    is_active: boolean;
+    latest: Partial<Record<PanelPollutant, {
+        value?: string;
+    }>>;
+}
+/** The slice of the SDK's `MonitorsMeta` this module reads. */
+export interface PanelMeta {
+    monitors: Record<string, {
+        entries: Record<string, unknown>;
+    } | undefined>;
+}
+export interface PanelPollutantChoice {
+    /** Null when the monitor has no reading and its type publishes neither pollutant. */
+    pollutant: PanelPollutant | null;
+    /** Whether the monitor has a current reading for `pollutant`. */
+    hasReading: boolean;
+}
+/** The panel pollutants this monitor has a current, numeric reading for. */
+export declare function readingPollutants(monitor: Pick<PanelMonitor, "latest">): PanelPollutant[];
+/**
+ * The panel pollutants this monitor type publishes. The API marks each entry type with a
+ * `published` flag the SDK does not type; a type that carries the entry without the flag
+ * counts as publishing it.
+ */
+export declare function publishedPollutants(monitorType: string, meta: PanelMeta): PanelPollutant[];
+/**
+ * The pollutant the detail panel shows: the map's when the monitor has it, otherwise the one
+ * the monitor has. A monitor with no current reading (inactive, or nothing reported) still
+ * gets a pollutant when there is one to chart, so its past data can be browsed.
+ */
+export declare function choosePanelPollutant(mapPollutant: PanelPollutant | null, monitor: PanelMonitor, meta: PanelMeta): PanelPollutantChoice;

package/dist/lib/monitors/panel-pollutant.js

@@ -0,0 +1,43 @@
+/** The pollutants the detail panel can show, in order of preference. */
+export const PANEL_POLLUTANTS = ["pm25", "o3"];
+/** The panel pollutants this monitor has a current, numeric reading for. */
+export function readingPollutants(monitor) {
+    return PANEL_POLLUTANTS.filter((pollutant) => {
+        const value = monitor.latest[pollutant]?.value;
+        return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value));
+    });
+}
+/**
+ * The panel pollutants this monitor type publishes. The API marks each entry type with a
+ * `published` flag the SDK does not type; a type that carries the entry without the flag
+ * counts as publishing it.
+ */
+export function publishedPollutants(monitorType, meta) {
+    const entries = meta.monitors[monitorType]?.entries ?? {};
+    return PANEL_POLLUTANTS.filter((pollutant) => {
+        const entry = entries[pollutant];
+        return entry !== undefined && entry.published !== false;
+    });
+}
+/**
+ * The pollutant the detail panel shows: the map's when the monitor has it, otherwise the one
+ * the monitor has. A monitor with no current reading (inactive, or nothing reported) still
+ * gets a pollutant when there is one to chart, so its past data can be browsed.
+ */
+export function choosePanelPollutant(mapPollutant, monitor, meta) {
+    const withReading = readingPollutants(monitor);
+    // The API keeps returning an inactive monitor's last reading, however old, so only an
+    // active monitor's readings count as current.
+    if (monitor.is_active && withReading.length > 0) {
+        const pollutant = mapPollutant && withReading.includes(mapPollutant) ? mapPollutant : withReading[0];
+        return { pollutant, hasReading: true };
+    }
+    // Nothing current: chart what the type publishes, or failing that what it last reported.
+    const published = publishedPollutants(monitor.type, meta);
+    const chartable = published.length > 0 ? published : withReading;
+    if (chartable.length > 0) {
+        const pollutant = mapPollutant && chartable.includes(mapPollutant) ? mapPollutant : chartable[0];
+        return { pollutant, hasReading: false };
+    }
+    return { pollutant: null, hasReading: false };
+}

package/dist/lib/options/OptionsBar.svelte

@@ -42,7 +42,14 @@
 	function onkeydown(e: KeyboardEvent) {
 		if (e.key !== "Escape") return;
 		panelOpen = false;
-		if (isWideLayout()) menus.closeAll();
+		if (!isWideLayout()) return;
+		// Focus on a row would be left inside the hidden dropdown; hand it back to the trigger.
+		const focused = document.activeElement;
+		const trigger = focused
+			?.closest("[data-options-menu]")
+			?.querySelector<HTMLElement>(":scope > button");
+		menus.closeAll();
+		if (trigger !== focused) trigger?.focus();
 	}
 </script>
 

package/dist/lib/options/OptionsMenu.svelte

@@ -33,10 +33,19 @@
 
 <div
 	role="presentation"
+	data-options-menu
 	class="group/menu relative md:first:[&>button]:rounded-l-md md:last:[&>button]:rounded-r-md"
 	onmouseenter={() => {
 		if (isWideLayout()) menus.closeOthers(id);
 	}}
+	onfocusout={(e) => {
+		// Toolbar only: focus moving on to something outside this menu (tabbing past the last
+		// row) closes its dropdown. No destination means a click on something unfocusable, which
+		// the outside-click handler in OptionsBar decides.
+		const next = e.relatedTarget;
+		if (!isWideLayout() || !(next instanceof Node) || e.currentTarget.contains(next)) return;
+		menus.close(id);
+	}}
 >
 	<button
 		type="button"
@@ -61,7 +70,7 @@
 			"max-md:pt-1 md:absolute md:top-full md:z-20 md:min-w-64 md:pt-1",
 			alignRight ? "md:right-0" : "md:left-0",
 			open ? "block" : "hidden",
-			!disabled && "md:group-hover/menu:block md:group-has-[:focus-visible]/menu:block"
+			!disabled && "md:group-hover/menu:block"
 		]}
 	>
 		<div class="py-1 md:max-h-[69vh] md:overflow-y-auto md:rounded-md md:bg-white md:shadow-lg">

package/dist/lib/shared-load.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Wraps a loader so overlapping calls share one run and a resolved run is reused, while a
+ * rejected run is forgotten: the next call tries again.
+ */
+export declare function sharedLoad<T>(load: () => Promise<T>): () => Promise<T>;

package/dist/lib/shared-load.js

@@ -0,0 +1,14 @@
+/**
+ * Wraps a loader so overlapping calls share one run and a resolved run is reused, while a
+ * rejected run is forgotten: the next call tries again.
+ */
+export function sharedLoad(load) {
+    let pending = null;
+    return () => {
+        pending ??= load().catch((error) => {
+            pending = null;
+            throw error;
+        });
+        return pending;
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sjvair/monitor-map",
 	"description": "SJVAir's interactive monitor map",
-	"version": "4.1.0",
+	"version": "4.2.0",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/SJVAir/monitor-map"

package/src/lib/LazyMapLayout.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+	import type { Component, Snippet } from "svelte";
+	import LoadScreen from "./LoadScreen.svelte";
+	import LoadError from "./LoadError.svelte";
+	import { loadMonitorDetailPanel, loadMonitorMapLayout } from "./lazy-chunks";
+	import { useMonitorMapRouter } from "./router-context";
+
+	interface Props {
+		children: Snippet;
+	}
+
+	let { children }: Props = $props();
+
+	const { route, basePath } = useMonitorMapRouter();
+
+	let Layout: Component<Props> | null = $state.raw(null);
+	let failed = $state(false);
+
+	function load() {
+		failed = false;
+		loadMonitorMapLayout().then(
+			(module) => (Layout = module.default),
+			(error) => {
+				console.error(error);
+				failed = true;
+			}
+		);
+	}
+
+	load();
+	// On a link straight to a monitor, fetch its panel alongside the layout; the panel's own
+	// wrapper only mounts (and would only ask for it) once the layout has arrived. A failure is
+	// reported by that wrapper when it asks again.
+	if (route.pathname.startsWith(`${basePath}/monitor/`)) {
+		loadMonitorDetailPanel().catch(() => {});
+	}
+</script>
+
+<!-- The layout renders the same LoadScreen from the same shared state, so it carries on
+     from this one without restarting. -->
+{#if Layout}
+	<Layout>{@render children()}</Layout>
+{:else}
+	<div class="relative h-full w-full">
+		<LoadScreen>
+			{#snippet error()}
+				{#if failed}
+					<LoadError message="Couldn't load the map." onretry={load} />
+				{/if}
+			{/snippet}
+		</LoadScreen>
+	</div>
+{/if}

package/src/lib/LazyMonitorDetailPanel.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	import type { Component } from "svelte";
+	import LoadError from "./LoadError.svelte";
+	import { loadMonitorDetailPanel } from "./lazy-chunks";
+
+	let Panel: Component | null = $state.raw(null);
+	let failed = $state(false);
+
+	function load() {
+		failed = false;
+		loadMonitorDetailPanel().then(
+			(module) => (Panel = module.default),
+			(error) => {
+				console.error(error);
+				failed = true;
+			}
+		);
+	}
+
+	load();
+</script>
+
+{#if Panel}
+	<Panel />
+{:else}
+	<div class="flex h-full w-full items-center justify-center bg-white">
+		{#if failed}
+			<LoadError message="Couldn't load this monitor." onretry={load} />
+		{:else}
+			<p class="text-sm text-gray-500">Loading…</p>
+		{/if}
+	</div>
+{/if}

package/src/lib/LoadError.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	interface Props {
+		message: string;
+		onretry: () => void;
+	}
+
+	let { message, onretry }: Props = $props();
+</script>
+
+<div class="flex flex-col items-center gap-3 px-4 text-center" role="alert">
+	<p class="text-gray-700">{message}</p>
+	<button
+		type="button"
+		class="rounded-md bg-gray-800 px-4 py-2 text-sm font-medium text-white hover:bg-gray-700"
+		onclick={onretry}
+	>
+		Try again
+	</button>
+</div>

package/src/lib/LoadScreen.svelte

@@ -23,8 +23,16 @@
 </script>
 
 <script lang="ts">
+	import type { Snippet } from "svelte";
 	import type { Attachment } from "svelte/attachments";
 
+	interface Props {
+		/** Rendered under the logo while the load screen is up, e.g. a load failure and a retry */
+		error?: Snippet;
+	}
+
+	let { error }: Props = $props();
+
 	const animationTrigger: Attachment<HTMLDivElement> = () => {
 		loadScreenState.entered = true;
 	};
@@ -32,7 +40,7 @@
 
 {#if loadScreenState.enabled}
 	<div
-		class="absolute top-0 left-0 z-50 flex h-full w-full items-center justify-center overflow-hidden bg-white"
+		class="absolute top-0 left-0 z-50 flex h-full w-full flex-col items-center justify-center gap-6 overflow-hidden bg-white"
 		{@attach animationTrigger}
 	>
 		<div class="flex justify-around gap-4">
@@ -64,5 +72,6 @@
 				class:opacity-0={!loadScreenState.entered}
 			/>
 		</div>
+		{@render error?.()}
 	</div>
 {/if}