@sjvair/monitor-map 3.6.2 → 4.0.0

package/src/lib/MonitorMapLayout.svelte

@@ -1,10 +1,25 @@
 <script lang="ts">
 	import type { Snippet } from "svelte";
 	import { onDestroy, untrack } from "svelte";
+	import { searchParams } from "sv-router";
 	import MapShell from "$lib/map/MapShell.svelte";
-	import MonitorsDisplayOptions from "$lib/monitors/components/MonitorsDisplayOptions.svelte";
-	import MapLayersDisplayOptions from "$lib/components/MapLayersDisplayOptions.svelte";
-	import MapStyleDisplayOptions from "$lib/map/MapStyleDisplayOptions.svelte";
+	import OptionsGroup from "$lib/options/OptionsGroup.svelte";
+	import PollutantMenu from "$lib/options/menus/PollutantMenu.svelte";
+	import MonitorsMenu from "$lib/options/menus/MonitorsMenu.svelte";
+	import LayersMenu from "$lib/options/menus/LayersMenu.svelte";
+	import OverlaysMenu from "$lib/options/menus/OverlaysMenu.svelte";
+	import SettingsMenu from "$lib/options/menus/SettingsMenu.svelte";
+	import {
+		applyPollutantSelection,
+		currentSelection,
+		parsePollutantParam
+	} from "$lib/options/pollutant-param";
+	import Legend from "$lib/legend/Legend.svelte";
+	import {
+		fireSmokeLegendSections,
+		pollutantLegendSection,
+		type LegendSection
+	} from "$lib/legend/legend-data";
 	import { monitorsManager } from "$lib/monitors/monitors.svelte";
 	import { monitorsMapIntegration } from "$lib/monitors/monitors-map-integration.svelte";
 	import { windMapIntegration } from "$lib/wind/wind.svelte";
@@ -12,14 +27,12 @@
 	import type { SomeMapIntegration } from "$lib/map/integrations/types";
 	import { collocationSitesManager } from "$lib/collocation-sites/collocations.svelte";
 	import { collocationSitesMapIntegration } from "$lib/collocation-sites/collocations-map-integration.svelte";
-	import EvStationsDisplayOptions from "$lib/ev-stations/components/EvStationsDisplayOptions.svelte";
 	import { evStationsMapIntegration } from "$lib/ev-stations/ev-stations-map-integration.svelte";
 	import { hmsManager } from "$lib/hms/hms.svelte";
 	import { hmsFireMapIntegration } from "$lib/hms/hms-fire-map-integration.svelte";
-	import { hmsSmokeMapIntegration } from "$lib/hms/hms-smoke-map-integration.svelte";
-	import MapLegend from "$lib/MapLegend.svelte";
+	import { FIRE_LEGEND_CATEGORIES } from "$lib/hms/hms-fire-icon-manager";
+	import { hmsSmokeMapIntegration, SMOKE_LEGEND } from "$lib/hms/hms-smoke-map-integration.svelte";
 	import Search from "$lib/search/Search.svelte";
-	import { searchParams } from "sv-router";
 	import { useMonitorMapRouter } from "./router-context";
 
 	interface Props {
@@ -40,6 +53,14 @@
 		evStationsMapIntegration
 	];
 
+	const pollutantTargets = { manager: monitorsManager, integration: monitorsMapIntegration };
+
+	// "?pollutant=none" must disable monitors before the effects below first run, so the
+	// state->URL effect never sees enabled monitors and overwrites the param.
+	if (parsePollutantParam(route.search.pollutant) === "none") {
+		monitorsMapIntegration.enabled = false;
+	}
+
 	monitorsManager.init(route.search.pollutant);
 	collocationSitesManager.init();
 	hmsManager.init();
@@ -49,30 +70,30 @@
 
 	let panelOpen = $derived(route.pathname.startsWith(`${basePath}/monitor/`));
 
-	// Keep monitorsManager.pollutant and the "pollutant" URL param in sync, both directions.
-	// init() only seeds pollutant on the manager's first-ever initialization; this effect is what
-	// applies a later "?pollutant=" change (e.g. navigating in from elsewhere) to an already-running manager.
+	// Keep the Pollutant menu's selection (pm25 / o3 / none) and the "pollutant" URL param in
+	// sync, both directions. init() only seeds the pollutant on the manager's first-ever
+	// initialization; this effect applies a later "?pollutant=" change (e.g. navigating in from
+	// elsewhere) to an already-running map.
 	$effect(() => {
-		const urlPollutant = route.search.pollutant;
-		// Read monitorsManager.pollutant via untrack: this effect must only react to the URL
-		// changing (e.g. navigating in from elsewhere), not to monitorsManager.pollutant itself.
-		// Tracking it here would make a UI-driven pollutant change (e.g. the display-options
-		// toggle) re-trigger this effect before the manager->URL effect below can sync the URL,
-		// so this effect would see the still-stale URL and immediately revert the user's change.
-		if (
-			monitorsManager.initialized &&
-			(urlPollutant === "pm25" || urlPollutant === "o3") &&
-			untrack(() => monitorsManager.pollutant) !== urlPollutant
-		) {
-			monitorsManager.pollutant = urlPollutant;
-		}
+		const selection = parsePollutantParam(route.search.pollutant);
+		if (!monitorsManager.initialized || !selection) return;
+		// Read current state via untrack: this effect must only react to the URL changing. Tracking
+		// state here would make a UI-driven change re-trigger this effect before the effect below
+		// syncs the URL, so it would see the stale URL and revert the user's change.
+		untrack(() => {
+			if (
+				currentSelection(monitorsManager.pollutant, monitorsMapIntegration.enabled) !== selection
+			) {
+				applyPollutantSelection(selection, pollutantTargets);
+			}
+		});
 	});
 
-	// ...and the reverse: reflect UI-driven pollutant changes (e.g. the display-options toggle) back to the URL.
+	// ...and the reverse: reflect UI-driven changes back to the URL.
 	$effect(() => {
-		const pollutant = monitorsManager.pollutant;
-		if (pollutant && searchParams.get("pollutant") !== pollutant) {
-			searchParams.set("pollutant", pollutant);
+		const selection = currentSelection(monitorsManager.pollutant, monitorsMapIntegration.enabled);
+		if (selection && searchParams.get("pollutant") !== selection) {
+			searchParams.set("pollutant", selection);
 		}
 	});
 
@@ -82,6 +103,18 @@
 		monitorsMapIntegration.selectedMonitorId = null;
 	});
 
+	const legendSections: Array<LegendSection> = $derived.by(() => {
+		const sections: Array<LegendSection> = [];
+		if (monitorsMapIntegration.enabled && monitorsManager.pollutant && monitorsManager.levels) {
+			const pollutant = pollutantLegendSection(monitorsManager.pollutant, monitorsManager.levels);
+			if (pollutant) sections.push(pollutant);
+		}
+		if (hmsFireMapIntegration.enabled && hmsSmokeMapIntegration.enabled) {
+			sections.push(...fireSmokeLegendSections(FIRE_LEGEND_CATEGORIES, SMOKE_LEGEND));
+		}
+		return sections;
+	});
+
 	onDestroy(() => {
 		monitorsManager.autoUpdate.stop();
 	});
@@ -95,17 +128,22 @@
 	{basePath}
 >
 	{#snippet menu()}
-		<MonitorsDisplayOptions />
-		<EvStationsDisplayOptions />
-		<MapLayersDisplayOptions />
-		<MapStyleDisplayOptions />
+		<OptionsGroup>
+			<PollutantMenu />
+			<MonitorsMenu />
+		</OptionsGroup>
+		<OptionsGroup>
+			<LayersMenu />
+			<OverlaysMenu />
+			<SettingsMenu />
+		</OptionsGroup>
+	{/snippet}
+	{#snippet search()}
+		<Search />
 	{/snippet}
 	{#snippet overlays()}
-		<div class="pointer-events-none absolute bottom-0 left-0 z-10">
-			<MapLegend />
-		</div>
-		<div class="absolute top-4 left-20 z-10">
-			<Search />
+		<div class="pointer-events-none absolute bottom-4 left-4 z-10">
+			<Legend sections={legendSections} />
 		</div>
 	{/snippet}
 	{@render children()}

package/src/lib/collocation-sites/collocations-map-integration.svelte.ts

@@ -25,6 +25,11 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 	icons: CollocationIconManager = new CollocationIconManager(monitorsManager);
 	tooltipManager: TooltipManager = new TooltipManager();
 
+	/** The option only applies while monitors are shown with PM2.5. */
+	get available(): boolean {
+		return monitorsMapIntegration.enabled && monitorsManager.pollutant === "pm25";
+	}
+
 	features: Array<CollocationSiteMapFeature> = $derived.by(() => {
 		if (
 			!monitorsManager.meta ||
@@ -93,8 +98,10 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 				mapManager.setDataSource(this.referenceId, features);
 			});
 
+			// Remove the layer while the option is unavailable (Ozone or Pollutant = None); restore
+			// it when it becomes available again if the user still has it checked.
 			$effect(() => {
-				if (monitorsManager.pollutant === "o3") {
+				if (!this.available) {
 					untrack(() => this.remove());
 				} else if (untrack(() => this.enabled)) {
 					untrack(() => this.apply());
@@ -104,6 +111,10 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 	}
 
 	apply() {
+		if (!this.available) {
+			this.remove();
+			return;
+		}
 		if (!mapManager.map) return;
 
 		if (!this.tooltipManager.has(this.referenceId)) {
@@ -114,6 +125,11 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 
 		super.apply();
 	}
+
+	remove() {
+		this.tooltipManager.disable();
+		super.remove();
+	}
 }
 
 export const collocationSitesMapIntegration = new CollocationSitesMapIntegration();

package/src/lib/ev-stations/ev-stations-map-integration.svelte.ts

@@ -26,7 +26,7 @@ class EvStationsMapIntegration
 	implements EvStationsClusterContext
 {
 	referenceId: string = "ev-stations";
-	enabled: boolean = $state(true);
+	enabled: boolean = $state(false);
 	clustered: boolean = $state(true);
 
 	icons: EvStationIconManager = new EvStationIconManager();
@@ -35,8 +35,8 @@ class EvStationsMapIntegration
 	private currentPopup: Popup | null = null;
 
 	displayOptions = $derived.by(() => ({
-		lvl2: new MapDisplayOption("Level 2", false, this.icons.get("ev-station-lvl2")!),
-		lvl3: new MapDisplayOption("Level 3", false, this.icons.get("ev-station-lvl3")!)
+		lvl2: new MapDisplayOption("Level 2", true, this.icons.get("ev-station-lvl2")!),
+		lvl3: new MapDisplayOption("Level 3", true, this.icons.get("ev-station-lvl3")!)
 	}));
 
 	features: Array<EvStationMapFeature> = $derived.by(() => {
@@ -115,23 +115,38 @@ class EvStationsMapIntegration
 		super();
 
 		$effect.root(() => {
-			// Lazy-fetch level data when integration is enabled and level is toggled on
+			// Lazy-fetch level data only once the integration is enabled and the level is on
 			$effect(() => {
-				if (this.displayOptions.lvl2.value && evStationsManager.lvl2Stations === undefined) {
+				if (
+					this.enabled &&
+					this.displayOptions.lvl2.value &&
+					evStationsManager.lvl2Stations === undefined
+				) {
 					evStationsManager.loadLvl2Stations();
 				}
 			});
 
 			$effect(() => {
-				if (this.displayOptions.lvl3.value && evStationsManager.lvl3Stations === undefined) {
+				if (
+					this.enabled &&
+					this.displayOptions.lvl3.value &&
+					evStationsManager.lvl3Stations === undefined
+				) {
 					evStationsManager.loadLvl3Stations();
 				}
 			});
 
+			// Every effect below early-returns while disabled so a data refresh can't re-add the layer.
+			// `enabled` is read untracked: the base class's own effect already applies/removes on
+			// enabled changes, and tracking it here would apply twice. The guard comes after each
+			// effect's tracked reads so its dependencies are always collected; returning before
+			// reading anything would leave the effect permanently dead.
+
 			// Push filter changes to the unclustered layer
 			$effect(() => {
 				const filter = this.filters;
 				if (!mapManager.map || this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				if (mapManager.map.getLayer(this.referenceId)) {
 					mapManager.map.setFilter(this.referenceId, filter);
 				}
@@ -141,6 +156,7 @@ class EvStationsMapIntegration
 			$effect(() => {
 				const features = this.features;
 				if (!mapManager.map || this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				mapManager.setDataSource(this.referenceId, features);
 			});
 
@@ -148,6 +164,7 @@ class EvStationsMapIntegration
 			$effect(() => {
 				void this.featuresByLevel;
 				if (!mapManager.map || !this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				this.renderer.syncFeatures();
 			});
 
@@ -156,6 +173,7 @@ class EvStationsMapIntegration
 				void this.clustered;
 				const hasFeatures = Object.keys(this.featuresByLevel).length > 0;
 				if (!untrack(() => mapManager.map) || !hasFeatures) return;
+				if (!untrack(() => this.enabled)) return;
 				untrack(() => this.apply());
 			});
 		});
@@ -171,6 +189,7 @@ class EvStationsMapIntegration
 			this.tooltipManager.disable();
 			this.renderer.remove();
 			this.icons.loadIcons().then(() => {
+				if (mapManager.styleLoading) return;
 				this.renderer.apply(this.handleStationClick);
 				this.tooltipManager.enable();
 			});
@@ -180,6 +199,7 @@ class EvStationsMapIntegration
 			clickManager.unregister([this.referenceId]);
 			super.apply();
 			this.icons.loadIcons().then(() => {
+				if (mapManager.styleLoading) return;
 				clickManager.register([this.referenceId], this.handleStationClick);
 				this.tooltipManager.enable();
 			});

package/src/lib/hms/hms-fire-icon-manager.ts

@@ -1,9 +1,10 @@
 import { asDataURI, fireIcon } from "$lib/map/icons";
 import { MapIconManager } from "$lib/map/integrations/map-icon-manager";
+import type { LegendCategory } from "$lib/legend/legend-data";
 
-type FRPTier = "sm" | "md" | "lg" | "xl" | "xxl";
+export type FRPTier = "sm" | "md" | "lg" | "xl" | "xxl";
 
-const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
+export const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
 	sm: { color: "#FFD700", size: 20 },
 	md: { color: "#FF8C00", size: 24 },
 	lg: { color: "#FF4500", size: 28 },
@@ -11,6 +12,19 @@ const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
 	xxl: { color: "#8B0000", size: 36 }
 };
 
+const FRP_TIER_LABELS: Record<FRPTier, string> = {
+	sm: "<10",
+	md: "10-49",
+	lg: "50-149",
+	xl: "150-349",
+	xxl: "≥350"
+};
+
+/** Fire legend blocks (MW), in tier order, using the same colors as the map icons. */
+export const FIRE_LEGEND_CATEGORIES: Array<LegendCategory> = (
+	Object.keys(FRP_TIERS) as Array<FRPTier>
+).map((tier) => ({ color: FRP_TIERS[tier].color, label: FRP_TIER_LABELS[tier] }));
+
 export function getTierIconId(frp: number): string {
 	if (frp < 10) return "hms-fire-sm";
 	if (frp < 50) return "hms-fire-md";

package/src/lib/hms/hms-fire-map-integration.svelte.ts

@@ -89,7 +89,7 @@ class HMSFireMapIntegration extends MapIconLayerIntegration<FireProperties> {
 		this.icons
 			.loadIcons()
 			.then(() => {
-				if (!mapManager.map || !this.enabled) return;
+				if (!mapManager.map || !this.enabled || mapManager.styleLoading) return;
 				this.remove();
 				this.zoomedIn = mapManager.map.getZoom() >= ZOOM_THRESHOLD;
 				mapManager.map.addSource(this.referenceId, this.mapSource);

package/src/lib/hms/hms-smoke-map-integration.svelte.ts

@@ -4,6 +4,16 @@ import type { HMSSmokeGeoJSON } from "@sjvair/sdk/hms";
 import { mapManager } from "$lib/map/map.svelte";
 import { MapGeoJSONIntegration } from "$lib/map/integrations/map-geojson-integration.svelte";
 import { hmsManager } from "./hms.svelte";
+import type { SmokeDensityStyle } from "$lib/legend/legend-data";
+
+/** Smoke fill styles, shared by the map layer and the legend so they can't drift apart. */
+export const SMOKE_DENSITY_STYLES = {
+	light: { label: "Light", color: "#bfc8c3", opacity: 0.2 },
+	medium: { label: "Medium", color: "#757b78", opacity: 0.3 },
+	heavy: { label: "Heavy", color: "#333634", opacity: 0.4 }
+} satisfies Record<string, SmokeDensityStyle>;
+
+export const SMOKE_LEGEND: Array<SmokeDensityStyle> = Object.values(SMOKE_DENSITY_STYLES);
 
 type SmokeProperties = {
 	id: string;
@@ -36,20 +46,28 @@ class HMSSmokeMapIntegration extends MapGeoJSONIntegration<SmokeProperties> {
 					"match",
 					["get", "density"],
 					"light",
-					"#bfc8c3",
+					SMOKE_DENSITY_STYLES.light.color,
+					"medium",
+					SMOKE_DENSITY_STYLES.medium.color,
+					SMOKE_DENSITY_STYLES.heavy.color
+				],
+				"fill-opacity": [
+					"match",
+					["get", "density"],
+					"light",
+					SMOKE_DENSITY_STYLES.light.opacity,
 					"medium",
-					"#757b78",
-					"#333634"
+					SMOKE_DENSITY_STYLES.medium.opacity,
+					SMOKE_DENSITY_STYLES.heavy.opacity
 				],
-				"fill-opacity": ["match", ["get", "density"], "light", 0.2, "medium", 0.3, 0.4],
 				"fill-outline-color": [
 					"match",
 					["get", "density"],
 					"light",
-					"#bfc8c3",
+					SMOKE_DENSITY_STYLES.light.color,
 					"medium",
-					"#757b78",
-					"#333634"
+					SMOKE_DENSITY_STYLES.medium.color,
+					SMOKE_DENSITY_STYLES.heavy.color
 				]
 			}
 		};

package/src/lib/index.ts

@@ -59,7 +59,6 @@ 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 Menu } from "./map/Menu.svelte";
 export {
 	default as LoadScreen,
 	loadScreenState,
@@ -67,12 +66,37 @@ export {
 	disable as disableLoadScreen
 } from "./LoadScreen.svelte";
 export type { LoadScreenState } from "./LoadScreen.svelte";
-export { default as MonitorsDisplayOptions } from "./monitors/components/MonitorsDisplayOptions.svelte";
-export { default as EvStationsDisplayOptions } from "./ev-stations/components/EvStationsDisplayOptions.svelte";
-export { default as MapLayersDisplayOptions } from "./components/MapLayersDisplayOptions.svelte";
-export { default as MapStyleDisplayOptions } from "./map/MapStyleDisplayOptions.svelte";
-export { default as ToggleSwitch } from "./components/ToggleSwitch.svelte";
-export { default as SegmentedControl } from "./components/SegmentedControl.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";

package/src/lib/legend/Legend.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+	import { ChevronDownIcon, InfoIcon } from "@lucide/svelte";
+	import LegendBar from "./LegendBar.svelte";
+	import type { LegendSection } from "./legend-data";
+
+	let { sections }: { sections: Array<LegendSection> } = $props();
+
+	// Independent of which sections are active, so toggling a layer doesn't reset it.
+	let collapsed = $state(false);
+</script>
+
+{#if sections.length}
+	<div class="pointer-events-auto w-84 max-w-[calc(100vw-2rem)] rounded-md bg-white shadow">
+		<button
+			type="button"
+			class="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-semibold"
+			aria-expanded={!collapsed}
+			onclick={() => (collapsed = !collapsed)}
+		>
+			<InfoIcon size={18} class="text-gray-500" />
+			<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}
+	</div>
+{/if}

package/src/lib/legend/LegendBar.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import {
+		blocksBackground,
+		gradientBackground,
+		tickPosition,
+		type LegendBarData
+	} from "./legend-data";
+
+	let { bar }: { bar: LegendBarData } = $props();
+
+	const background = $derived(
+		bar.kind === "gradient"
+			? gradientBackground(bar.colors)
+			: blocksBackground(bar.categories.map((category) => category.color))
+	);
+
+	// Labels placed on exact stop positions: gradient ticks, or block breakpoints.
+	const positioned = $derived(bar.kind === "gradient" ? bar.ticks : (bar.breakpoints ?? null));
+</script>
+
+<div class="h-3 rounded" style:background></div>
+{#if positioned}
+	<div class="relative mt-1 h-4 text-xs">
+		{#each positioned as label, i (i)}
+			{@const isFirst = i === 0}
+			{@const isLast = i === positioned.length - 1}
+			<span
+				class={[
+					"absolute top-0 whitespace-nowrap",
+					isFirst && "left-0",
+					isLast && "right-0",
+					!isFirst && !isLast && "-translate-x-1/2"
+				]}
+				style:left={!isFirst && !isLast ? `${tickPosition(i, positioned.length)}%` : undefined}
+				>{label}</span
+			>
+		{/each}
+	</div>
+{:else if bar.kind === "blocks"}
+	<div class="mt-1 flex text-xs">
+		{#each bar.categories as category, i (i)}
+			<span class="min-w-0 flex-1 text-center break-words">{category.label ?? ""}</span>
+		{/each}
+	</div>
+{/if}

package/src/lib/legend/legend-data.ts

@@ -0,0 +1,101 @@
+import type { SJVAirEntryLevel } from "@sjvair/sdk";
+import { mix } from "color2k";
+import type { MonitorsPollutant } from "$lib/monitors/types";
+
+export interface LegendCategory {
+	color: string;
+	label?: string;
+}
+
+export type LegendBarData =
+	| { kind: "gradient"; colors: Array<string>; ticks: Array<string> }
+	| { kind: "blocks"; categories: Array<LegendCategory>; breakpoints?: Array<string> };
+
+export interface LegendSection {
+	id: string;
+	title: string;
+	unit?: string;
+	bar: LegendBarData;
+}
+
+export interface SmokeDensityStyle {
+	label: string;
+	color: string;
+	opacity: number;
+}
+
+const POLLUTANT_TITLES: Record<MonitorsPollutant, { title: string; unit: string }> = {
+	pm25: { title: "PM2.5", unit: "µg/m³" },
+	o3: { title: "Ozone", unit: "ppb" }
+};
+
+/**
+ * Pollutant legend built from the monitors meta levels — the same levels the map markers are
+ * colored by, so the two can never disagree. One tick per level, at that level's color stop.
+ */
+export function pollutantLegendSection(
+	pollutant: MonitorsPollutant,
+	levels: ReadonlyArray<Pick<SJVAirEntryLevel, "color" | "range">>
+): LegendSection | null {
+	if (levels.length === 0) return null;
+	return {
+		id: "pollutant",
+		...POLLUTANT_TITLES[pollutant],
+		bar: {
+			kind: "gradient",
+			colors: levels.map((level) => level.color),
+			ticks: levels.map((level) => String(Math.floor(level.range[0])))
+		}
+	};
+}
+
+/** Fire & Smoke share one toggle, so they render as two independent bars. */
+export function fireSmokeLegendSections(
+	fireTiers: ReadonlyArray<LegendCategory>,
+	smoke: ReadonlyArray<SmokeDensityStyle>
+): Array<LegendSection> {
+	return [
+		{ id: "fire", title: "Fire", unit: "MW", bar: { kind: "blocks", categories: [...fireTiers] } },
+		{
+			id: "smoke",
+			title: "Smoke Density",
+			bar: {
+				kind: "blocks",
+				categories: smoke.map(({ label, color, opacity }) => ({
+					label,
+					color: swatchOverWhite(color, opacity)
+				}))
+			}
+		}
+	];
+}
+
+/** Approximates how a translucent fill layer looks over a light basemap. */
+export function swatchOverWhite(color: string, opacity: number): string {
+	return mix("#ffffff", color, opacity);
+}
+
+export function gradientBackground(colors: ReadonlyArray<string>): string {
+	if (colors.length === 0) return "none";
+	if (colors.length === 1) return colors[0];
+	return `linear-gradient(to right, ${colors.join(", ")})`;
+}
+
+/** Hard-edged equal-width blocks: each color repeated at both edges of its own share. */
+export function blocksBackground(colors: ReadonlyArray<string>): string {
+	const count = colors.length;
+	if (count === 0) return "none";
+	const stops = colors.map(
+		(color, i) => `${color} ${percent(i / count)}, ${color} ${percent((i + 1) / count)}`
+	);
+	return `linear-gradient(to right, ${stops.join(", ")})`;
+}
+
+/** Percent position of the index-th of `count` evenly spaced labels. */
+export function tickPosition(index: number, count: number): number {
+	return count <= 1 ? 0 : (index / (count - 1)) * 100;
+}
+
+function percent(fraction: number): string {
+	return `${(fraction * 100).toFixed(2)}%`;
+}