@sjvair/monitor-map 4.1.0 → 4.2.0

package/src/lib/map/MapShell.svelte

@@ -11,6 +11,11 @@
 		 * is true.
 		 */
 		ready: boolean;
+		/**
+		 * Rendered on the load screen, under the logo, for as long as the load screen is up.
+		 * Render it only when the caller's initial load failed (e.g. a message and a retry).
+		 */
+		loadError?: Snippet;
 		/** True when the routed detail panel (`children`) should be visible */
 		panelOpen: boolean;
 		/**
@@ -59,6 +64,7 @@
 	let {
 		integrations,
 		ready,
+		loadError,
 		panelOpen,
 		knownRoutes = [],
 		menu,
@@ -123,7 +129,7 @@
 </script>
 
 <div class="relative flex h-full w-full flex-col md:flex-row">
-	<LoadScreen />
+	<LoadScreen error={loadError} />
 	<div class="relative flex-1 overflow-hidden">
 		<Map {integrations} />
 		{@render overlays?.()}

package/src/lib/map/integrations/map-geojson-integration.svelte.ts

@@ -33,16 +33,45 @@ export abstract class MapIconLayerIntegration<
 	T = Record<string, unknown>
 > extends MapGeoJSONIntegration<T> {
 	abstract icons: MapIconManager;
+	private generation = 0;
+
+	/**
+	 * Drops every callback still waiting on icons. `apply()` and `remove()` call it, so a
+	 * subclass overriding `apply()` without calling `super.apply()` first must call it itself.
+	 */
+	protected supersedePending(): void {
+		this.generation++;
+	}
+
+	/**
+	 * Runs `run` once the icons have loaded, unless an `apply()` or `remove()` has happened
+	 * since (the state it was scheduled for is gone) or a basemap change is in flight (the
+	 * refresh on "style.load" re-applies).
+	 */
+	protected whenIconsLoad(run: () => void): void {
+		const generation = this.generation;
+		this.icons
+			.loadIcons()
+			.then(() => {
+				if (generation !== this.generation || mapManager.styleLoading) return;
+				run();
+			})
+			.catch(console.error);
+	}
 
 	apply() {
 		if (!mapManager.map) return;
 
-		this.icons.loadIcons().then(() => {
-			// A basemap change started while icons loaded; the refresh on "style.load" re-applies.
-			if (mapManager.styleLoading) return;
+		this.supersedePending();
+		this.whenIconsLoad(() => {
 			this.removeLayerAndSource();
 			mapManager.map?.addSource(this.referenceId, this.mapSource);
 			super.apply();
 		});
 	}
+
+	remove() {
+		this.supersedePending();
+		super.remove();
+	}
 }

package/src/lib/map/map-style-state.svelte.ts

@@ -7,7 +7,12 @@ import { variantForStyle } from "./basemap";
 class MapStyleState {
 	referenceStyle: ReferenceMapStyle = $state.raw(DefaultMapStyle.getReferenceStyle());
 	variant: MapStyleVariant = $state.raw(DefaultMapStyle);
-	private applied: MapStyleVariant = 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.
+	private applied: MapStyleVariant | null = DefaultMapStyle;
+	// The variant the map last finished loading, which a failed change falls back to.
+	private loaded: MapStyleVariant = DefaultMapStyle;
+	private stopWaiting: (() => void) | null = null;
 
 	selectReferenceStyle(style: ReferenceMapStyle): void {
 		this.referenceStyle = style;
@@ -25,17 +30,64 @@ class MapStyleState {
 	}
 
 	private apply(): void {
+		if (!mapManager.map || this.variant === this.applied) return;
+		this.load(this.variant);
+	}
+
+	private load(variant: MapStyleVariant): void {
 		const map = mapManager.map;
-		if (!map || this.variant === this.applied) return;
-		this.applied = this.variant;
+		if (!map) return;
+		// 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: { error?: unknown }) => {
+			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.
+	 */
+	private recover(failed: MapStyleVariant): void {
+		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: unknown, url: string): boolean {
+	const failed = (error as { url?: unknown } | null | undefined)?.url;
+	if (typeof failed !== "string") return false;
+	return failed.split("?")[0] === url.split("?")[0];
 }
 
 export const mapStyleState = new MapStyleState();

package/src/lib/monitors/monitor-details.svelte.ts

@@ -0,0 +1,66 @@
+import { getMonitorDetails, 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 class MonitorDetailsState {
+	monitor: MonitorDetails | null = $state.raw(null);
+	status: MonitorDetailsStatus = $state("loading");
+
+	#id: string | null = null;
+	// Bumped per request; a response for anything but the latest request is dropped.
+	#request = 0;
+
+	async load(id: string): Promise<void> {
+		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(): Promise<void> {
+		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(): Promise<void> {
+		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: unknown): boolean {
+	const cause = (error as { cause?: { status?: unknown; result?: { status?: unknown } } } | null)
+		?.cause;
+	return cause?.result?.status === 404 || cause?.status === 404;
+}

package/src/lib/monitors/monitors-map-integration.svelte.ts

@@ -274,8 +274,9 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 			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();
@@ -286,8 +287,7 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 			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/src/lib/monitors/monitors.svelte.ts

@@ -12,6 +12,14 @@ import { Interval } from "@tstk/utils";
 import { untrack } from "svelte";
 import type { MonitorsDataSource, MonitorsPollutant } 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;
+}
+
 class MonitorsManager implements MonitorsDataSource {
 	autoUpdate: Interval = new Interval(async () => await this.update(), 2 * 60 * 1000);
 	initialized: boolean = $state(false);
@@ -29,6 +37,7 @@ class MonitorsManager implements MonitorsDataSource {
 
 	#initPromise: Promise<void> | null = null;
 	#requestedPollutant: MonitorsPollutant | null = null;
+	#requestedAutoUpdate = false;
 
 	constructor() {
 		// Refetch monitors when the pollutant changes after the initial load, wherever the change
@@ -54,11 +63,15 @@ 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> {
 		if (this.initialized) return Promise.resolve();
 
+		if (options.autoUpdate !== false) this.#requestedAutoUpdate = true;
+
 		if (urlPollutant === "pm25" || urlPollutant === "o3") {
 			this.#requestedPollutant = urlPollutant;
 		}
@@ -66,6 +79,7 @@ class MonitorsManager implements MonitorsDataSource {
 		this.#initPromise ??= this.#runInit().finally(() => {
 			this.#initPromise = null;
 			this.#requestedPollutant = null;
+			this.#requestedAutoUpdate = false;
 		});
 
 		return this.#initPromise;
@@ -105,13 +119,14 @@ class MonitorsManager implements MonitorsDataSource {
 
 		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(): void {
 		if (!this.initialized || this.autoUpdate.isActive) return;

package/src/lib/monitors/panel-pollutant.ts

@@ -0,0 +1,76 @@
+/** The pollutants the detail panel can show, in order of preference. */
+export const PANEL_POLLUTANTS = ["pm25", "o3"] as const;
+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;
+	// Only the panel pollutants are read; the SDK's `latest` has more entry types, without an
+	// index signature.
+	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 function readingPollutants(monitor: Pick<PanelMonitor, "latest">): PanelPollutant[] {
+	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: string, meta: PanelMeta): PanelPollutant[] {
+	const entries = meta.monitors[monitorType]?.entries ?? {};
+	return PANEL_POLLUTANTS.filter((pollutant) => {
+		const entry = entries[pollutant] as { published?: boolean } | undefined;
+		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: PanelPollutant | null,
+	monitor: PanelMonitor,
+	meta: PanelMeta
+): PanelPollutantChoice {
+	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/src/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/src/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/src/lib/shared-load.ts

@@ -0,0 +1,15 @@
+/**
+ * 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<T>(load: () => Promise<T>): () => Promise<T> {
+	let pending: Promise<T> | null = null;
+
+	return () => {
+		pending ??= load().catch((error: unknown) => {
+			pending = null;
+			throw error;
+		});
+		return pending;
+	};
+}