@sjvair/map-sdk 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -165,7 +165,8 @@ in each level's color at the fill's opacity; choropleth only), or `"none"` (no o
 `hmsSmokePlugin` uses `"level"`.
 
 `zoomRange: { min?, max? }` on `pointsPlugin` limits every layer it draws (points, clusters,
-selection) to zooms from `min` (inclusive) up to `max` (exclusive), switching live while zooming.
+selection) to camera zooms from `min` (inclusive) up to `max` (exclusive), switching live while
+zooming. Two plugins whose ranges meet hand over with no gap, on the globe too.
 
 `hmsFirePlugin({ id?, source, hotspots?, layerLabel })` draws fires as flame icons sized and
 colored by FRP. With `hotspots`, it switches by itself while zooming, as sjvair.com's map does:
@@ -180,7 +181,23 @@ each level's label under its segment; long labels wrap. `legendTitle: "layer" |
 the legend section's title: `layerLabel` (default) or the entry type's label from the metadata
 provider (`monitorsPlugin` uses the latter, so its section reads "PM2.5"; `layerLabel` still names
 the layer in the list, selection bar and summary). `Legend` takes `order` (`"bottom-first"`,
-default, or `"top-first"`).
+default, or `"top-first"`) and `framed` (`true`, default, draws its own card; `false` draws no
+border, background, padding or fixed width, so a host's own card frames it). Without a frame,
+translucent swatches blend over the nearest ancestor with an opaque background (a see-through
+card is skipped), else `--background`; that color is read on mount, when `framed` changes, and on
+a theme change, but not when the card changes color through its own class or style.
+
+```svelte
+<div class="w-84 rounded-md bg-white shadow">
+	<h3>Legend</h3>
+	<Legend {map} framed={false} />
+</div>
+```
+
+`detail?(props)` on `pointsPlugin` gives a feature with no level a short text (such as "Level 2
+charger") shown where "No level" would be: in the feature list (plain text, no swatch), the row's
+accessible name ("Fresno Station, Level 2 charger"), and the tooltip. A feature with a level
+always shows its level. A plugin of your own sets the same `detail` on its `FeatureListItem`s.
 
 `collocationSitesPlugin({ id?, source, layerLabel })` draws collocation sites as sjvair.com does:
 each at its reference monitor, in that monitor's shape and level color (inactive gray, inside
@@ -329,8 +346,10 @@ time), and `movePlugin` moves it with the plugin's other layers.
 
 The cursor is a pointer over any interactive feature or cluster bubble. Where several plugins'
 features are under the pointer, the hover tooltip shows the one whose plugin has the highest
-`hoverPriority` (default 0), the topmost on a tie; a cluster bubble on top still hides what is
-beneath it, and clicks always go to the topmost.
+`hoverPriority` (default 0), the topmost on a tie. Over a cluster bubble, the bubble's tooltip
+shows unless a feature beneath belongs to a plugin with a higher `hoverPriority` than the
+bubble's (collocation sites under monitor clusters). Clicks always go to the topmost, so a click
+on a bubble still zooms into it.
 
 ```ts
 import type { CustomLayerInterface, MapPlugin, PluginContext } from "@sjvair/map-sdk";

package/dist/core/interactions.svelte.d.ts

@@ -10,7 +10,8 @@ export interface Hovered {
  * Listens on the map itself (`click`, `mousemove`, `mouseout`) and queries only the registered
  * layers, so registrations can come and go without re-binding listeners. Layers nobody registered
  * are never hit. A blocking layer (e.g. a cluster bubble, which zooms instead) is never hit either,
- * but when it is topmost at a point nothing beneath it is hit or hovered.
+ * and when it is topmost at a point nothing beneath it is hit; only a feature whose plugin
+ * outranks it in `hoverPriority` is hovered through it.
  */
 export declare class InteractionRouter {
     #private;

package/dist/core/interactions.svelte.js

@@ -4,7 +4,8 @@
  * Listens on the map itself (`click`, `mousemove`, `mouseout`) and queries only the registered
  * layers, so registrations can come and go without re-binding listeners. Layers nobody registered
  * are never hit. A blocking layer (e.g. a cluster bubble, which zooms instead) is never hit either,
- * but when it is topmost at a point nothing beneath it is hit or hovered.
+ * and when it is topmost at a point nothing beneath it is hit; only a feature whose plugin
+ * outranks it in `hoverPriority` is hovered through it.
  */
 export class InteractionRouter {
     // Bookkeeping only; nothing reads these reactively.
@@ -120,9 +121,25 @@ export class InteractionRouter {
         if (top?.blocking) {
             const properties = features[0].properties ?? {};
             const hit = top.toHit(properties);
+            // Clicks stay blocked, but the hover goes to the highest-priority feature beneath that
+            // outranks the blocking plugin.
+            let beneath = null;
+            let beneathPriority = top.priority;
+            for (const feature of features.slice(1)) {
+                const registration = byLayer.get(feature.layer.id);
+                if (!registration || registration.blocking)
+                    continue;
+                if (registration.priority <= beneathPriority)
+                    continue;
+                const below = registration.toHit(feature.properties ?? {});
+                if (!below)
+                    continue;
+                beneath = { ...below, pluginId: registration.pluginId };
+                beneathPriority = registration.priority;
+            }
             return {
                 hits: [],
-                hover: null,
+                hover: beneath,
                 blocked: true,
                 blocker: hit && { ...hit, pluginId: top.pluginId },
                 blockedBy: { registration: top, feature: { properties, geometry: features[0].geometry } }
@@ -194,7 +211,7 @@ export class InteractionRouter {
     };
     #onMove = (e) => {
         const found = this.#lookup([e.point.x, e.point.y]);
-        const hit = found.blocked ? found.blocker : found.hover;
+        const hit = found.blocked ? (found.hover ?? found.blocker) : found.hover;
         this.#hovered = hit ? { hit, lngLat: [e.lngLat.lng, e.lngLat.lat] } : null;
         this.#setPointer(found.blocked || hit !== null);
     };

package/dist/core/plugin.d.ts

@@ -48,6 +48,12 @@ export interface FeatureListItem {
     precision?: number;
     lngLat: [number, number];
     selectable: boolean;
+    /**
+     * A short text about a feature with no level (e.g. "Level 2 charger"), shown where its level
+     * would be: in the feature list, its row's accessible name, and the generic tooltip. Ignored
+     * when the item has a level.
+     */
+    detail?: string;
 }
 export type LegendData = {
     pluginId: string;
@@ -128,8 +134,9 @@ export interface MapPlugin {
     selectable?: boolean;
     /**
      * Which plugin's feature the hover tooltip shows where several are under the pointer: the
-     * highest wins, the topmost on a tie. Default 0. A blocking layer on top still hides what is
-     * beneath it, and clicks ignore this (topmost first).
+     * highest wins, the topmost on a tie. Default 0. Over a blocking layer (a cluster bubble), a
+     * feature beneath shows only if its plugin's priority is higher than the blocking plugin's.
+     * Clicks ignore this (topmost first), and a blocking layer on top still blocks them.
      */
     hoverPriority?: number;
     displayOptions?: Snippet;

package/dist/data/messages/en.json

@@ -8,6 +8,7 @@
 	"mapsdk_list_row": "{name}, {value} {units}, {level}",
 	"mapsdk_list_row_no_units": "{name}, {value}, {level}",
 	"mapsdk_list_row_no_value": "{name}, no reading",
+	"mapsdk_list_row_detail": "{name}, {detail}",
 	"mapsdk_list_empty": "Nothing on the map in this view",
 	"mapsdk_selected_count_one": "{count} selected",
 	"mapsdk_selected_count_other": "{count} selected",

package/dist/plugins/points.svelte.d.ts

@@ -60,8 +60,9 @@ export interface PointsOptions<P extends MapFeatureProperties> {
     sortKey?(props: P): number;
     /**
      * Limits every layer the plugin draws (points, clusters, selection) to a zoom range: visible
-     * from `min` (inclusive) up to `max` (exclusive). Set on the layers, so it switches live while
-     * zooming. Default: all zooms.
+     * from `min` (inclusive) up to `max` (exclusive) of the camera zoom, switching live while
+     * zooming (layer visibility, not layer zoom ranges, so ranges that meet leave no gap on a
+     * globe). Default: all zooms.
      */
     zoomRange?: {
         min?: number;
@@ -75,6 +76,12 @@ export interface PointsOptions<P extends MapFeatureProperties> {
      * it loads.
      */
     legendTitle?: "layer" | "entry-type";
+    /**
+     * A short text for a feature with no level (e.g. "Level 2 charger"), shown in the feature list,
+     * its accessible name, and the generic tooltip where "No level" would be. Ignored for a
+     * feature with a level.
+     */
+    detail?(props: P): string | undefined;
     /** Whether `features()` lists this plugin's features. Default true. */
     listed?: boolean;
     /** Tooltip content for a feature, below its name; `props` are its source properties. */

package/dist/plugins/points.svelte.js

@@ -93,6 +93,7 @@ export function pointsPlugin(options) {
             if (!ref)
                 continue;
             const [lng, lat] = geometry.coordinates;
+            const detail = options.detail?.(props)?.trim();
             items.push({
                 refKey: props.refKey,
                 ref,
@@ -102,7 +103,8 @@ export function pointsPlugin(options) {
                 units: scale?.units ?? "",
                 precision,
                 lngLat: [lng, lat],
-                selectable: selectable && selectionId(ref) !== null
+                selectable: selectable && selectionId(ref) !== null,
+                ...(detail ? { detail } : {})
             });
         }
         return items;
@@ -209,15 +211,39 @@ export function pointsPlugin(options) {
             }
             return spec;
         }
-        /** The spec limited to the plugin's zoom range. */
+        // The zoom range shows and hides the layers by the camera zoom, not with layer
+        // minzoom/maxzoom: on a globe MapLibre uses the next zoom's tiles a little before the camera
+        // gets there and leaves a layer out of tiles at or above its maxzoom, so two plugins whose
+        // ranges meet (fire groups below 10, hotspots from 10) would leave a gap where neither drew.
+        const { min, max } = options.zoomRange ?? {};
+        const ranged = min !== undefined || max !== undefined;
+        const inRange = () => {
+            const zoom = gl.getZoom();
+            return (min === undefined || zoom >= min) && (max === undefined || zoom < max);
+        };
+        let shown = ranged ? inRange() : true;
+        /** The spec, hidden while the camera is outside the plugin's zoom range. */
         function zoomed(spec) {
-            const { min, max } = options.zoomRange ?? {};
+            if (!ranged)
+                return spec;
+            const layout = spec.layout;
             return {
                 ...spec,
-                ...(min !== undefined ? { minzoom: min } : {}),
-                ...(max !== undefined ? { maxzoom: max } : {})
+                layout: { ...layout, visibility: shown ? "visible" : "none" }
             };
         }
+        const onZoom = () => {
+            if (dead || inRange() === shown)
+                return;
+            shown = !shown;
+            for (const layerId of layers) {
+                if (gl.getLayer(layerId)) {
+                    gl.setLayoutProperty(layerId, "visibility", shown ? "visible" : "none");
+                }
+            }
+        };
+        if (ranged)
+            gl.on("zoom", onZoom);
         function removeLayers() {
             for (const layerId of layers.toReversed()) {
                 if (gl.getLayer(layerId))
@@ -447,6 +473,8 @@ export function pointsPlugin(options) {
         });
         return () => {
             dead = true;
+            if (ranged)
+                gl.off("zoom", onZoom);
             providers = null;
             live = null;
         };

package/dist/ui/FeatureList.svelte

@@ -9,6 +9,7 @@
 		inView,
 		optionIdPart,
 		rowLabel,
+		levelText,
 		shownLevel,
 		sortItems,
 		typeaheadIndex,
@@ -330,6 +331,7 @@
 			{#each windowRows as row, i (row.key)}
 				{@const index = range.start + i}
 				{@const level = shownLevel(row)}
+				{@const levelPlace = levelText(row, map.messages)}
 				{@const isOn = isSelected(row)}
 				<!-- Options aren't focused: the listbox holds focus and handles keys (aria-activedescendant). -->
 				<!-- svelte-ignore a11y_click_events_have_key_events, a11y_interactive_supports_focus -->
@@ -360,12 +362,14 @@
 						{formatValue(row)}{#if row.units && row.value !== null}&nbsp;{row.units}{/if}
 					</span>
 					<span class="mapsdk-list-level text-xs">
-						<span
-							class="mapsdk-list-swatch"
-							class:neutral={!level?.color}
-							style:background={level?.color || undefined}
-						></span>
-						{level ? level.label : map.messages("mapsdk_no_level")}
+						{#if levelPlace.kind !== "detail"}
+							<span
+								class="mapsdk-list-swatch"
+								class:neutral={!level?.color}
+								style:background={level?.color || undefined}
+							></span>
+						{/if}
+						{levelPlace.text}
 					</span>
 				</div>
 			{/each}

package/dist/ui/Legend.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { onMount } from "svelte";
+	import { onMount, untrack } from "svelte";
 	import "./controls.css";
 	import type { MapContext } from "../core/create-map.svelte.js";
 	import { watchTheme } from "../view/create-gl-map.js";
@@ -8,9 +8,19 @@
 
 	let {
 		map,
-		order = "bottom-first"
+		order = "bottom-first",
+		framed = true
 	}: {
 		map: MapContext;
+		/**
+		 * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+		 * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+		 * then blend over the nearest ancestor with an opaque background (a see-through card is
+		 * skipped), else the `--background` token. The color is read on mount, when `framed`
+		 * changes, and on a theme change; a card that changes color through its own class or
+		 * style isn't re-read.
+		 */
+		framed?: boolean;
 		/**
 		 * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
 		 * last.
@@ -43,30 +53,50 @@
 		)
 	);
 
-	/** Computed colors can be oklch() or color(); a 1x1 canvas turns any of them into rgb. */
-	function resolveBackground(el: Element): string {
-		const css = getComputedStyle(el).backgroundColor;
+	/**
+	 * A computed color as rgb and whether it's opaque; computed colors can be oklch() or color(),
+	 * and a 1x1 canvas turns any of them into rgb.
+	 */
+	function toRgb(css: string): { rgb: string; opaque: boolean } {
 		const ctx = document.createElement("canvas").getContext("2d");
-		if (!ctx) return css;
+		if (!ctx) return { rgb: css, opaque: true };
 		ctx.clearRect(0, 0, 1, 1);
 		ctx.fillStyle = css;
 		ctx.fillRect(0, 0, 1, 1);
-		const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
-		return `rgb(${r}, ${g}, ${b})`;
+		const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+		return { rgb: `rgb(${r}, ${g}, ${b})`, opaque: a === 255 };
 	}
 
-	onMount(() => {
-		const update = () => {
-			if (root) background = resolveBackground(root);
-		};
-		update();
-		return watchTheme(root!, update);
+	/**
+	 * What translucent swatches blend over: the legend's own card, or without a frame the nearest
+	 * ancestor with an opaque background (the host's card), else the `--background` token.
+	 */
+	function resolveBackground(el: HTMLElement, frameless: boolean): string {
+		if (!frameless) return toRgb(getComputedStyle(el).backgroundColor).rgb;
+		for (let at = el.parentElement; at; at = at.parentElement) {
+			const color = toRgb(getComputedStyle(at).backgroundColor);
+			if (color.opaque) return color.rgb;
+		}
+		// A computed custom property has its var() references already substituted.
+		return toRgb(getComputedStyle(el).getPropertyValue("--background").trim()).rgb;
+	}
+
+	function update() {
+		if (root) background = resolveBackground(root, !framed);
+	}
+
+	onMount(() => watchTheme(root!, update));
+
+	// On mount, and again when `framed` changes.
+	$effect(() => {
+		void framed;
+		untrack(update);
 	});
 </script>
 
 <section
 	bind:this={root}
-	class="mapsdk-legend"
+	class={["mapsdk-legend", !framed && "mapsdk-legend-frameless"]}
 	aria-label={map.messages("mapsdk_legend_label")}
 	hidden={entries.length === 0}
 >
@@ -124,6 +154,17 @@
 		pointer-events: auto;
 	}
 
+	/* framed={false}: the host's card is the frame. */
+	.mapsdk-legend-frameless {
+		width: auto;
+		max-width: none;
+		padding: 0;
+		border: 0;
+		border-radius: 0;
+		background: none;
+		box-shadow: none;
+	}
+
 	.mapsdk-legend[hidden] {
 		display: none;
 	}

package/dist/ui/Legend.svelte.d.ts

@@ -2,6 +2,15 @@ import "./controls.css";
 import type { MapContext } from "../core/create-map.svelte.js";
 type $$ComponentProps = {
     map: MapContext;
+    /**
+     * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+     * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+     * then blend over the nearest ancestor with an opaque background (a see-through card is
+     * skipped), else the `--background` token. The color is read on mount, when `framed`
+     * changes, and on a theme change; a card that changes color through its own class or
+     * style isn't re-read.
+     */
+    framed?: boolean;
     /**
      * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
      * last.

package/dist/ui/TooltipItem.svelte

@@ -3,6 +3,7 @@
 	import type { MessageProvider } from "../data/messages.js";
 	import type { FeatureListItem } from "../core/plugin.js";
 	import { NO_LEVEL } from "../data/scale.js";
+	import { levelText } from "./feature-list.js";
 	import { levelChip } from "./level-chip.js";
 	import { formatValue } from "./value-format.js";
 
@@ -19,7 +20,8 @@
 
 	// A level with an empty color shows its label on the neutral chip.
 	const level = $derived(item.level !== NO_LEVEL ? item.level : null);
-	const levelLabel = $derived(level ? level.label : messages("mapsdk_no_level"));
+	// The level's label, else the item's detail (plain text, no chip), else "No level".
+	const levelPlace = $derived(levelText(item, messages));
 	const chipColors = $derived.by(() => {
 		const chip = levelChip(level?.color);
 		return chip ? `background:${chip.background};color:${chip.text}` : "";
@@ -39,9 +41,13 @@
 			{valueText}{#if item.units} {item.units}{/if}
 		</div>
 	{/if}
-	<span class="mapsdk-tooltip-chip text-xs" class:neutral={!chipColors} style={chipColors}>
-		{levelLabel}
-	</span>
+	{#if levelPlace.kind === "detail"}
+		<span class="mapsdk-tooltip-detail text-xs">{levelPlace.text}</span>
+	{:else}
+		<span class="mapsdk-tooltip-chip text-xs" class:neutral={!chipColors} style={chipColors}>
+			{levelPlace.text}
+		</span>
+	{/if}
 </div>
 
 <style>

package/dist/ui/feature-list.d.ts

@@ -27,5 +27,12 @@ export declare function shownLevel(item: FeatureListItem): Level | null;
 export declare function sortItems(items: FeatureListItem[], by: SortBy): FeatureListItem[];
 /** The first index at or after `from` (wrapping) whose name starts with `query`, any case; -1 if none. */
 export declare function typeaheadIndex(items: FeatureListItem[], query: string, from: number): number;
-/** A row's accessible name: name, value, units, and level label. */
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export declare function levelText(item: FeatureListItem, messages: MessageProvider): {
+    kind: "level" | "detail" | "none";
+    text: string;
+};
+/** A row's accessible name: name, value, units, and level label (or detail). */
 export declare function rowLabel(item: FeatureListItem, messages: MessageProvider, format: FormatProvider): string;

package/dist/ui/feature-list.js

@@ -65,16 +65,31 @@ export function typeaheadIndex(items, query, from) {
     }
     return -1;
 }
-/** A row's accessible name: name, value, units, and level label. */
-export function rowLabel(item, messages, format) {
-    if (item.value === null)
-        return messages("mapsdk_list_row_no_value", { name: item.name });
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export function levelText(item, messages) {
     const level = shownLevel(item);
+    if (level)
+        return { kind: "level", text: level.label };
+    const detail = item.detail?.trim();
+    if (detail)
+        return { kind: "detail", text: detail };
+    return { kind: "none", text: messages("mapsdk_no_level") };
+}
+/** A row's accessible name: name, value, units, and level label (or detail). */
+export function rowLabel(item, messages, format) {
+    const level = levelText(item, messages);
+    if (item.value === null) {
+        return level.kind === "detail"
+            ? messages("mapsdk_list_row_detail", { name: item.name, detail: level.text })
+            : messages("mapsdk_list_row_no_value", { name: item.name });
+    }
     const params = {
         name: item.name,
         value: typeof item.value === "number" ? formatValue(item.value, item.precision, format) : item.value,
         units: item.units,
-        level: level ? level.label : messages("mapsdk_no_level")
+        level: level.text
     };
     return messages(item.units ? "mapsdk_list_row" : "mapsdk_list_row_no_units", params);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sjvair/map-sdk",
 	"description": "Svelte 5 map components for SJVAir air-quality data",
-	"version": "0.1.0-beta.1",
+	"version": "0.1.0-beta.2",
 	"license": "MIT",
 	"repository": {
 		"type": "git",