@sjvair/monitor-map 4.2.0 → 5.0.0-beta.0

package/src/lib/ev-stations/ev-store.svelte.ts

@@ -0,0 +1,117 @@
+import type { FeatureCollection, Point } from "geojson";
+import {
+	encodeRef,
+	type DataSource,
+	type DataStatus,
+	type MapFeatureProperties
+} from "@sjvair/map-sdk/data";
+import { fetchEvStations } from "./ev-stations";
+import type { EvStation } from "./types";
+
+export type EvLevel = "lvl2" | "lvl3";
+
+/** A charger on the map: `name` is the station's name; chargers have no value. */
+export interface EvFeatureProperties extends MapFeatureProperties {
+	level: EvLevel;
+}
+
+export type FetchEvStations = (level: EvLevel, signal?: AbortSignal) => Promise<EvStation[]>;
+
+export interface EvStore {
+	/** One level's chargers for its plugin; `loading` until the first `load(level)`. */
+	dataSource(level: EvLevel): DataSource<EvFeatureProperties>;
+	/**
+	 * Fetches a level once; overlapping calls share the run. A failure sets the status to `error`
+	 * (its `retry()` fetches again) and rejects.
+	 */
+	load(level: EvLevel): Promise<void>;
+	/** A loaded station by id, from either level. */
+	station(id: string): EvStation | undefined;
+}
+
+/** NREL has this station in the wrong place, so it is left out (as in 4.x). */
+const DROPPED_STATION = 226154;
+
+function toFeatures(
+	stations: EvStation[],
+	level: EvLevel
+): FeatureCollection<Point, EvFeatureProperties> {
+	return {
+		type: "FeatureCollection",
+		features: stations.map((station) => ({
+			type: "Feature",
+			properties: {
+				refKey: encodeRef({ kind: "feature", id: String(station.id) }),
+				name: station.station_name ?? "",
+				value: null,
+				level
+			},
+			geometry: { type: "Point", coordinates: [station.longitude, station.latitude] }
+		}))
+	};
+}
+
+class EvLevelSource implements DataSource<EvFeatureProperties> {
+	status: DataStatus = $state.raw({ state: "loading" });
+	features: FeatureCollection<Point, EvFeatureProperties> | null = $state.raw(null);
+	readonly scale = null;
+	stations: EvStation[] = [];
+
+	#run: Promise<void> | null = null;
+	#loaded = false;
+
+	constructor(
+		private level: EvLevel,
+		private fetchStations: FetchEvStations
+	) {}
+
+	load(): Promise<void> {
+		if (this.#loaded) return Promise.resolve();
+		this.#run ??= this.#fetch();
+		return this.#run;
+	}
+
+	async #fetch(): Promise<void> {
+		if (this.status.state !== "loading") this.status = { state: "loading" };
+		try {
+			const stations = (await this.fetchStations(this.level)).filter(
+				(station) => station.id !== DROPPED_STATION
+			);
+			this.stations = stations;
+			this.features = toFeatures(stations, this.level);
+			this.status = { state: "ready" };
+			this.#loaded = true;
+		} catch (error) {
+			this.features = null;
+			this.status = {
+				state: "error",
+				error,
+				retry: () => {
+					this.load().catch(() => {});
+				}
+			};
+			throw error;
+		} finally {
+			this.#run = null;
+		}
+	}
+}
+
+/** EV chargers by level, each fetched when first wanted. */
+export function createEvStore(fetchStations: FetchEvStations = fetchEvStations): EvStore {
+	const levels = {
+		lvl2: new EvLevelSource("lvl2", fetchStations),
+		lvl3: new EvLevelSource("lvl3", fetchStations)
+	};
+	return {
+		dataSource: (level) => levels[level],
+		load: (level) => levels[level].load(),
+		station(id) {
+			for (const source of Object.values(levels)) {
+				const found = source.stations.find((station) => String(station.id) === id);
+				if (found) return found;
+			}
+			return undefined;
+		}
+	};
+}

package/src/lib/ev-stations/station-popup.svelte.ts

@@ -0,0 +1,64 @@
+import { mount, unmount, untrack } from "svelte";
+import { Popup } from "@maptiler/sdk";
+import { maptilerMap, type MapContext } from "@sjvair/map-sdk";
+import EvPopup from "./EvPopup.svelte";
+import type { EvStation } from "./types";
+
+export interface StationPopups {
+	/** Opens `station`'s popup at `lngLat`, closing any other; it belongs to plugin `pluginId`. */
+	open(pluginId: string, station: EvStation, lngLat: [number, number]): void;
+	close(): void;
+}
+
+/**
+ * The EV station popup, 4.x's (a MapTiler `Popup` with a close button that a map click leaves
+ * open). One is open at a time; it closes on a basemap switch, when its plugin leaves the map,
+ * and when the GL map is replaced. Call it during component setup: its effects live as long as
+ * the component.
+ */
+export function stationPopups(map: MapContext): StationPopups {
+	let current: { popup: Popup; pluginId: string } | null = $state.raw(null);
+
+	function close() {
+		const open = current;
+		current = null;
+		open?.popup.remove();
+	}
+
+	// A basemap switch or a new GL map closes it.
+	$effect(() => {
+		void map.basemap.current;
+		void map.gl;
+		untrack(close);
+	});
+
+	// So does its plugin leaving the map (its level turned off). A Marker Clusters flip removes and
+	// re-adds the plugin in one pass, so the popup stays: the station is still there.
+	$effect(() => {
+		const ids = map.plugins.map((plugin) => plugin.id);
+		const open = current;
+		if (open && !ids.includes(open.pluginId)) untrack(close);
+	});
+
+	$effect(() => () => untrack(close));
+
+	return {
+		open(pluginId, station, lngLat) {
+			close();
+			const gl = maptilerMap(map);
+			if (!gl) return;
+			const target = document.createElement("div");
+			const instance = mount(EvPopup, { target, props: { station } });
+			const popup = new Popup({ closeButton: true, closeOnClick: false, maxWidth: "none" })
+				.setLngLat(lngLat)
+				.setDOMContent(target);
+			popup.on("close", () => {
+				unmount(instance);
+				if (current?.popup === popup) current = null;
+			});
+			current = { popup, pluginId };
+			popup.addTo(gl);
+		},
+		close
+	};
+}

package/src/lib/ev-stations/types.ts

@@ -1,6 +1,3 @@
-import type { Feature, Geometry } from "geojson";
-import type { MapGeoJSONFeature } from "@maptiler/sdk";
-
 export interface EvStation {
 	access_code: string;
 	access_days_time: string;
@@ -25,34 +22,3 @@ export interface EvStation {
 	ev_network: string;
 	ev_pricing: string;
 }
-
-export interface EvStationMarkerProperties {
-	icon: string;
-	id: number;
-	level: "lvl2" | "lvl3";
-	station_name: string;
-	facility_type: string;
-	ev_network: string;
-	station_phone: string;
-	street_address: string;
-	city: string;
-	state: string;
-	zip: string;
-	access_days_time: string;
-	access_detail_code: string;
-	cards_accepted: string | null;
-	ev_pricing: string;
-	ev_connector_types: string; // JSON.stringify(string[])
-}
-
-export type EvStationMapFeature = Feature<Geometry, EvStationMarkerProperties>;
-
-export interface EvStationClusterMapFeature extends MapGeoJSONFeature {
-	properties: {
-		cluster: true;
-		cluster_id: number;
-		point_count: number;
-		point_count_abbreviated: string | number;
-	};
-	// level is derived from feature.source: "ev-stations-lvl2" | "ev-stations-lvl3"
-}

package/src/lib/ev-stations/zip-codes.ts

@@ -48,7 +48,6 @@ export const SanJoaquin = [
 export const Stanislaus = [
 	"95355",
 	"95350",
-	"94550",
 	"95351",
 	"95307",
 	"95380",
@@ -80,7 +79,6 @@ export const Stanislaus = [
 ];
 
 export const Merced = [
-	"95023",
 	"95380",
 	"93635",
 	"95301",
@@ -101,13 +99,11 @@ export const Merced = [
 	"95369",
 	"95303",
 	"95317",
-	"95325",
 	"93665",
 	"95342",
 	"95344",
 	"95343",
 	"93661",
-	"09534",
 	"95312"
 ];
 
@@ -141,7 +137,6 @@ export const Fresno = [
 	"93706",
 	"93711",
 	"93705",
-	"93245",
 	"93612",
 	"93657",
 	"93710",
@@ -189,7 +184,6 @@ export const Fresno = [
 	"93652",
 	"93627",
 	"93606",
-	"93665",
 	"93628",
 	"93605",
 	"93607",
@@ -235,8 +229,7 @@ export const Fresno = [
 	"93888",
 	"93844",
 	"93784",
-	"93780",
-	"93633"
+	"93780"
 ];
 
 export const Kings = [
@@ -247,7 +240,6 @@ export const Kings = [
 	"93204",
 	"93656",
 	"93242",
-	"93249",
 	"93266",
 	"93201",
 	"93202",
@@ -288,12 +280,9 @@ export const Tulare = [
 	"93238",
 	"93261",
 	"93641",
-	"93255",
 	"93603",
 	"93244",
 	"93262",
-	"93549",
-	"93628",
 	"93208",
 	"93227",
 	"93237",
@@ -412,7 +401,6 @@ export const Calaveras = [
 export const Tuolumne = [
 	"95370",
 	"95327",
-	"95247",
 	"95383",
 	"95321",
 	"95379",
@@ -423,8 +411,6 @@ export const Tuolumne = [
 	"95310",
 	"95346",
 	"95364",
-	"95224",
-	"93541",
 	"95305",
 	"95335",
 	"95314",
@@ -438,7 +424,6 @@ export const Mono = ["93514", "93546", "93517", "96107", "93529", "96133", "9354
 
 export const Mariposa = [
 	"95338",
-	"95333",
 	"93601",
 	"95311",
 	"95329",
@@ -468,3 +453,31 @@ export const Inyo = [
 	"93522",
 	"93530"
 ];
+
+/**
+ * Every county's ZIPs once, sorted: the EV charger query's `zip` list. A ZIP that spans two
+ * counties is in both lists above; `scripts/check-ev-zips.mjs` checks the lists against the
+ * Census ZCTA-to-county file.
+ *
+ * The county lists began as a hand-scraped list. 5.0 only removes ZIPs with no land in their
+ * county; it adds none. Border ZIPs with some San Joaquin land (95632 Galt, 95641 Isleton,
+ * 94505 Discovery Bay) are left out (decided 2026-11-07): their chargers sit mostly outside
+ * the county. Revisit if users ask for chargers just over the county line.
+ */
+export const EV_ZIP_CODES: readonly string[] = [
+	...new Set([
+		...SanJoaquin,
+		...Stanislaus,
+		...Merced,
+		...Madera,
+		...Fresno,
+		...Kings,
+		...Tulare,
+		...Kern,
+		...Calaveras,
+		...Tuolumne,
+		...Mono,
+		...Mariposa,
+		...Inyo
+	])
+].sort();

package/src/lib/index.ts

@@ -15,9 +15,11 @@
  * ```svelte
  * <!-- app root -->
  * <script>
- *   import { provideMonitorMapRouter } from "@sjvair/monitor-map";
+ *   import { configureMonitorMap, provideMonitorMapRouter } from "@sjvair/monitor-map";
  *   import { route, navigate, p, isActive, Router } from "./router";
  *
+ *   // Once at startup, before the map or the EV layer is used. The library reads no keys itself.
+ *   configureMonitorMap({ maptilerKey, nrelKey });
  *   provideMonitorMapRouter({ route, navigate, p, isActive, basePath: "/my-map" });
  * </script>
  *
@@ -25,111 +27,18 @@
  * ```
  *
  * A host that must stay light at startup imports from the subpath entries instead:
- * `provideMonitorMapRouter`/`monitorsManager` from "@sjvair/monitor-map/core" (no map), and
+ * `configureMonitorMap`/`provideMonitorMapRouter`/`monitorsManager` from
+ * "@sjvair/monitor-map/core" (no map), and
  * `monitorMapRoutes` from "@sjvair/monitor-map/routes" (same tree, lazy layout and routes).
  * `monitorMapRoutes` from this entry stays eager.
  */
 export { monitorMapRoutes } from "./routes";
+export { configureMonitorMap, monitorMapConfig, type MonitorMapConfig } from "./config.svelte.js";
 export {
 	ROUTER_KEY,
 	provideMonitorMapRouter,
 	useMonitorMapRouter,
 	type MonitorMapRouterApi
 } from "./router-context";
-
-// State managers
-export { monitorsManager } from "./monitors/monitors.svelte";
-export type { MonitorsManager, MonitorsInitOptions } from "./monitors/monitors.svelte";
-export { collocationSitesManager } from "./collocation-sites/collocations.svelte";
-export type { CollocationSitesManager } from "./collocation-sites/collocations.svelte";
-export { evStationsManager } from "./ev-stations/ev-stations.svelte";
-export type { EvStationsManager } from "./ev-stations/ev-stations.svelte";
-export { hmsManager } from "./hms/hms.svelte";
-export type { HMSManager } from "./hms/hms.svelte";
-export { mapManager, DefaultMapStyle, initializeMap } from "./map/map-manager.svelte.js";
-export type { MapManager } from "./map/map-manager.svelte.js";
-
-// Map integrations
-export {
-	monitorsMapIntegration,
-	MonitorsMapIntegration
-} from "./monitors/monitors-map-integration.svelte";
-export { collocationSitesMapIntegration } from "./collocation-sites/collocations-map-integration.svelte";
-export { evStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
-export { windMapIntegration } from "./wind/wind.svelte";
-export { baseLayerSeperator } from "./map/integrations/base-layer-seperator";
-export { hmsFireMapIntegration } from "./hms/hms-fire-map-integration.svelte";
-export { hmsSmokeMapIntegration } from "./hms/hms-smoke-map-integration.svelte";
-
-// Components
-export { default as Map } from "./map/Map.svelte";
-export { default as MapShell, type MapShellProps } from "./map/MapShell.svelte";
-export {
-	default as LoadScreen,
-	loadScreenState,
-	enable as enableLoadScreen,
-	disable as disableLoadScreen
-} from "./LoadScreen.svelte";
-export type { LoadScreenState } from "./LoadScreen.svelte";
-
-// Options toolbar / panel (compose these inside MapShell's `menu` snippet)
-export { default as OptionsBar } from "./options/OptionsBar.svelte";
-export { default as OptionsGroup } from "./options/OptionsGroup.svelte";
-export { default as OptionsMenu } from "./options/OptionsMenu.svelte";
-export { default as CheckboxRow } from "./options/rows/CheckboxRow.svelte";
-export { default as RadioRow } from "./options/rows/RadioRow.svelte";
-export { default as SubmenuRow } from "./options/rows/SubmenuRow.svelte";
-export { default as GroupRow } from "./options/rows/GroupRow.svelte";
-export { default as MarkerIcon } from "./options/rows/MarkerIcon.svelte";
-export { default as PollutantMenu } from "./options/menus/PollutantMenu.svelte";
-export { default as MonitorsMenu } from "./options/menus/MonitorsMenu.svelte";
-export { default as LayersMenu } from "./options/menus/LayersMenu.svelte";
-export { default as OverlaysMenu } from "./options/menus/OverlaysMenu.svelte";
-export { default as SettingsMenu } from "./options/menus/SettingsMenu.svelte";
-export { resetMapOptions } from "./options/reset-map-options";
-export { mapStyleState } from "./map/map-style-state.svelte.js";
-export type { MapStyleState } from "./map/map-style-state.svelte.js";
-
-// Legend
-export { default as Legend } from "./legend/Legend.svelte";
-export { default as LegendBar } from "./legend/LegendBar.svelte";
-export {
-	pollutantLegendSection,
-	fireSmokeLegendSections,
-	type LegendSection,
-	type LegendBarData,
-	type LegendCategory
-} from "./legend/legend-data";
-export { FIRE_LEGEND_CATEGORIES } from "./hms/hms-fire-icon-manager";
-export { SMOKE_LEGEND } from "./hms/hms-smoke-map-integration.svelte";
-
-// Integration base classes (extend these to add custom map features)
-export { MapIntegration } from "./map/integrations/map-integration.svelte";
-export { MapLayerIntegration } from "./map/integrations/map-layer-integration.svelte";
-export { MapIconLayerIntegration as MapGeoJSONIntegration } from "./map/integrations/map-geojson-integration.svelte";
-
-// Types
-export type { SomeMapIntegration } from "./map/integrations/types";
-export type { WindMapIntegration } from "./wind/wind.svelte";
-export type { EvStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
-export type { HMSFireMapIntegration } from "./hms/hms-fire-map-integration.svelte";
-export type { HMSSmokeMapIntegration } from "./hms/hms-smoke-map-integration.svelte";
-export type { HMSFireGroup } from "./hms/hms.svelte";
-export type {
-	MonitorMapFeature,
-	MonitorMarkerProperties,
-	MonitorClusterMapFeature,
-	MonitorClusterMarkerProperties,
-	MonitorsDataSource,
-	MonitorsPollutant
-} from "./monitors/types";
-export type {
-	CollocationSiteMapFeature,
-	CollocationSiteMarkerProperties
-} from "./collocation-sites/types";
-export type {
-	EvStation,
-	EvStationMarkerProperties,
-	EvStationMapFeature,
-	EvStationClusterMapFeature
-} from "./ev-stations/types";
+export { monitorsManager } from "./monitors/monitors.svelte.js";
+export type { MonitorsManager, MonitorsInitOptions } from "./monitors/monitors.svelte.js";

package/src/lib/legend/Legend.svelte

@@ -1,15 +1,25 @@
 <script lang="ts">
 	import { ChevronDownIcon, InfoIcon } from "@lucide/svelte";
-	import LegendBar from "./LegendBar.svelte";
-	import type { LegendSection } from "./legend-data";
+	import { Legend, legendSection, type MapContext } from "@sjvair/map-sdk";
 
-	let { sections }: { sections: Array<LegendSection> } = $props();
+	let { map }: { map: MapContext } = $props();
 
 	// Independent of which sections are active, so toggling a layer doesn't reset it.
 	let collapsed = $state(false);
+
+	// What map-sdk's Legend would list: a scale with levels, or a status line for a plugin that is
+	// loading or failing. The card is hidden while there is none.
+	const hasSections = $derived(
+		map.plugins.some((plugin) => {
+			const data = plugin.legend?.();
+			if (!data) return false;
+			if ("status" in data) return data.status.state !== "ready";
+			return legendSection(data, map.format) !== null;
+		})
+	);
 </script>
 
-{#if sections.length}
+{#if hasSections}
 	<div class="pointer-events-auto w-84 max-w-[calc(100vw-2rem)] rounded-md bg-white shadow">
 		<button
 			type="button"
@@ -21,20 +31,9 @@
 			<span class="flex-1 text-left">Legend</span>
 			<ChevronDownIcon size={18} class="transition-transform {collapsed ? '-rotate-90' : ''}" />
 		</button>
-		{#if !collapsed}
-			<div class="flex flex-col gap-3 border-t border-gray-200 px-4 py-3">
-				{#each sections as section (section.id)}
-					<div>
-						<p class="mb-2 text-center text-sm font-semibold">
-							{section.title}
-							{#if section.unit}
-								<span class="text-xs font-normal text-gray-500">({section.unit})</span>
-							{/if}
-						</p>
-						<LegendBar bar={section.bar} />
-					</div>
-				{/each}
-			</div>
-		{/if}
+		<!-- Kept mounted (hidden) when collapsed so the legend doesn't re-read the theme on expand. -->
+		<div class="border-t border-gray-200 px-4 py-3 {collapsed ? 'hidden' : ''}">
+			<Legend {map} order="top-first" framed={false} />
+		</div>
 	</div>
 {/if}

package/src/lib/levels.ts

@@ -0,0 +1,24 @@
+import { levelFor, NO_LEVEL, type Level, type Scale } from "@sjvair/map-sdk/data";
+
+/** The color for a reading no level covers, as map-sdk draws an inactive monitor. */
+export const NEUTRAL_LEVEL_COLOR = "#969696";
+
+/** The scale level a reading falls in, or null when there is no scale or no level covers it. */
+export function readingLevel(
+	value: string | number | null | undefined,
+	scale: Scale | null
+): Level | null {
+	if (!scale) return null;
+	const level = levelFor(value, scale);
+	return level === NO_LEVEL ? null : level;
+}
+
+/** A reading as the panel shows it: cut off to a whole number, or "–" when not a number. */
+export function readingDisplay(value: string | number | null | undefined): string {
+	// Number("") and Number(null) are 0, not a reading.
+	if (value === null || value === undefined || (typeof value === "string" && !value.trim())) {
+		return "–";
+	}
+	const number = Math.trunc(Number(value));
+	return Number.isFinite(number) ? number.toString() : "–";
+}

package/src/lib/map/MapShell.svelte

@@ -1,13 +1,13 @@
 <script lang="ts" module>
 	import type { Snippet } from "svelte";
-	import type { SomeMapIntegration } from "$lib/map/integrations/types";
+	import type { MapContext } from "@sjvair/map-sdk";
 
 	export interface MapShellProps {
-		/** Map integrations to register, e.g. [monitorsMapIntegration] */
-		integrations: Array<SomeMapIntegration>;
+		/** The map to show, from `createMap()` (the monitor map uses `createLiveMap()`). */
+		map: MapContext;
 		/**
 		 * True once the caller's own data managers have finished their initial
-		 * load. The shell hides the load screen once the map is idle AND this
+		 * load. The shell hides the load screen once the map is ready AND this
 		 * is true.
 		 */
 		ready: boolean;
@@ -56,13 +56,12 @@
 
 <script lang="ts">
 	import LoadScreen, { disable as disableLoadScreen } from "$lib/LoadScreen.svelte";
-	import Map from "$lib/map/Map.svelte";
+	import { MapView } from "@sjvair/map-sdk";
 	import OptionsBar from "$lib/options/OptionsBar.svelte";
-	import { mapManager } from "$lib/map/map-manager.svelte.js";
 	import { useMonitorMapRouter } from "$lib/router-context";
 
 	let {
-		integrations,
+		map,
 		ready,
 		loadError,
 		panelOpen,
@@ -76,28 +75,14 @@
 	}: MapShellProps = $props();
 
 	const basePath = providedBasePath ?? (routerEscapeHatch ? useMonitorMapRouter().basePath : "");
-	const TRANSITION_MS = 300;
 
 	$effect(() => {
-		// mapManager.map is only ever assigned once its own initial "load" has
-		// already fired (see initializeMap in map-manager.svelte.ts), so by the time this
-		// effect sees a non-null map, it's already safe to reveal — waiting for a
-		// further "idle" event here is unreliable since one may never fire again.
-		if (mapManager.map && ready) {
+		// `map.ready` is map-sdk's signal that the style loaded and the map went idle.
+		if (map.ready && ready) {
 			disableLoadScreen();
 		}
 	});
 
-	$effect(() => {
-		if (panelOpen) {
-			// Container width snapped to open; resize after layout settles
-			requestAnimationFrame(() => mapManager.map?.resize());
-		} else {
-			// Container width snaps back after the transform transition ends
-			setTimeout(() => mapManager.map?.resize(), TRANSITION_MS);
-		}
-	});
-
 	/**
 	 * HACK: Fix for escaping sv-router and allowing navigation to other pages,
 	 * as well as navigating back
@@ -131,7 +116,15 @@
 <div class="relative flex h-full w-full flex-col md:flex-row">
 	<LoadScreen error={loadError} />
 	<div class="relative flex-1 overflow-hidden">
-		<Map {integrations} />
+		<MapView
+			{map}
+			label="Air quality monitor map"
+			controls="engine"
+			featureList={{ position: "top-right", reveal: "focus" }}
+			selectionBar={false}
+			tooltip="pointer"
+			class="h-full w-full"
+		/>
 		{@render overlays?.()}
 		{#if menu || search}
 			<OptionsBar {search}>{@render menu?.()}</OptionsBar>