@sjvair/map-sdk 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -374,6 +374,19 @@ function sitesPlugin(sites: Sites): MapPlugin {
 }
 ```
 
+An item for a shape (a polygon or line) can carry its `geometry` and, optionally, its `bbox`
+(`[west, south, east, north]`, from `geometryBbox(geometry)`). The list and the summary then count
+it as in view when the shape overlaps the view, not only when its `lngLat` is inside it: a smoke
+plume that fills the screen is listed even though its center is off-screen. Measure `bbox` once per
+data load (both are tested on every move); without it the box is computed each time. Focusing such
+a shape from the list while its `lngLat` is off-screen leaves the camera where it is, and its
+tooltip pins at a point of the shape in view: the view's center (beside the list panel) when the
+shape covers it, else a point inside its visible part. `map.focusedAnchor` is where the focused
+tooltip pins, and `map.anchorFor(item)` gives that point for any item without moving the camera
+(the hover tooltip uses it). `intersectsBounds(item, bounds)` is the in-view test. `shapesPlugin`
+and the presets built on it set `geometry` and `bbox` already. Bounds across the antimeridian are
+not handled.
+
 A plugin can also add a MapLibre custom layer, such as a wind layer from a library you add
 yourself, with `ctx.addCustomLayer(local, create)`. The host calls `create` with the namespaced id
 (the layer must use it) and adds the object it returns as is, in the plugin's draw-order slot. It is
@@ -440,7 +453,8 @@ and `getSelectionMode(id)` are reactive.
 
 `map.on("featureclick", ({ pluginId, ref, lngLat }) => …)` fires for every click on a feature,
 whatever the mode, and also for a pick in the feature list, so keyboard users get the same event;
-`lngLat` is the click point (the item's position for a list pick). It returns an unsubscribe
+`lngLat` is the click point. For a list pick it's where the item's tooltip pins: the item's
+position, or for a shape whose label point is off-screen, a point of the shape in view. It returns an unsubscribe
 function. For your own context menu, `map.featuresAt({ x, y })` returns the hits under
 a canvas point, topmost first, and `map.featureForElement(element)` returns the hit for a row of
 the feature list (an element with `data-mapsdk-ref`). Both return nothing while the map is
@@ -534,6 +548,36 @@ local sjvair.com stack at `http://localhost:8000`.
 
 ## Changes
 
+### 0.1.0-beta.6
+
+- **A category reading is shown once.** When a feature's value is its category level's code, the
+  list row, the tooltip, and the row's accessible name show only the level label. Smoke rows read
+  "Smoke, Light" (was "light Light"), burn status "Burning Discouraged", and heat score
+  "Moderate" (the 0–4 number is no longer shown). Number scales such as PM2.5 and fire power are
+  unchanged, and a category value that matches no level is still shown.
+- **New message key for hosts with their own catalog:** `mapsdk_list_row_level`
+  (`"{name}, {level}"`).
+
+### 0.1.0-beta.5
+
+- **Shapes that cover the view are in view.** The feature list and the view summary count a shape
+  when it overlaps the view, not only when its center (label point) is inside it. A smoke plume or
+  a big region that fills the screen, with its center off-screen, now has a list row and is
+  counted. Points are unchanged.
+- **Focusing such a shape doesn't move the map.** Before, focusing a row panned to center the
+  shape's label point (a plume's could be off Baja). Now the camera stays, and the tooltip pins at
+  a point of the shape in view, with no move event. A shape whose label point is on screen still
+  pans to it.
+- **Hover tooltips** in `"pinned"` mode follow the same rule: a hovered shape whose label point is
+  off-screen pins its tooltip inside the view instead of at the map's edge. If the map moves while
+  the pointer rests on the shape, the pin is found again when the map settles.
+- **`featureclick` from the list** (Enter on a row) reports that same in-view point for such a
+  shape, instead of its off-screen label point. A handler that pans to `lngLat` no longer sends
+  the map off to the shape's far-away center. Points and on-screen label points report their
+  position, as before.
+- **New API (all optional):** `FeatureListItem.geometry` and `.bbox`, `MapContext.focusedAnchor`
+  and `.anchorFor(item)`, `geometryBbox`, `intersectsBounds`, and the `Bbox` type.
+
 ### 0.1.0-beta.4
 
 Defaults from monitor-map 5.0's parity review against sjvair.com's map (4.3.0). Every map gets

package/dist/core/create-map.svelte.d.ts

@@ -5,7 +5,7 @@ import type { FeatureRef, SelectionMode, SpatialSelection } from "../data/types.
 import { BasemapState, type BasemapConfig } from "./basemap.svelte.js";
 import type { GlMapLike } from "./gl.js";
 import { type Hovered } from "./interactions.svelte.js";
-import type { FeatureHit, MapPlugin } from "./plugin.js";
+import type { FeatureHit, FeatureListItem, MapPlugin } from "./plugin.js";
 export interface CameraState {
     center: [number, number];
     zoom: number;
@@ -52,7 +52,10 @@ export interface PluginOptions {
 export type FeatureClickHandler = (e: {
     pluginId: string;
     ref: FeatureRef;
-    /** The click point; for a pick in the feature list, the item's position. */
+    /**
+     * The click point. For a pick in the feature list, where the item's tooltip pins: its position,
+     * or for a shape whose label point is off-screen, a point of the shape in view.
+     */
     lngLat: [number, number];
 }) => void;
 /** Where a camera move ends up. `zoom` wins over `minZoom`. */
@@ -185,6 +188,18 @@ export interface MapContext {
     readonly focusedKey: string | null;
     /** Reactive. The plugin `focusFeature` was given with `focusedKey`, or `null`. */
     readonly focusedPluginId: string | null;
+    /**
+     * Reactive. Where the focused feature's tooltip pins, set by `focusFeature` (`null` without
+     * focus): its `lngLat`, or for a shape that overlaps the view with its `lngLat` off-screen, a
+     * point of the shape in the part of the view the list panel leaves clear. Fixed at focus
+     * time, so it stays on the feature if the map then moves.
+     */
+    readonly focusedAnchor: [number, number] | null;
+    /**
+     * Where `item`'s tooltip pins in the current view, without moving the camera: its `lngLat`,
+     * or for a shape (`geometry`) with its `lngLat` off-screen, a point of the shape in view.
+     */
+    anchorFor(item: FeatureListItem): [number, number];
     /** For MapView only: uses `gl` from now on. */
     attach(gl: GlMapLike): void;
     /** For MapView only: stops using the current GL map. */

package/dist/core/create-map.svelte.js

@@ -7,6 +7,7 @@ import { applyPick, selectionKeys } from "../data/selection.js";
 import { BasemapState } from "./basemap.svelte.js";
 import { InteractionRouter } from "./interactions.svelte.js";
 import { PluginHost } from "./plugin-host.svelte.js";
+import { intersectsBounds, shapeAnchor } from "./shape-view.js";
 /** Monitor-map's start view. */
 const DEFAULT_VIEW = {
     center: [-119.7987626619462, 36.76272050981146],
@@ -36,6 +37,7 @@ function sameSelection(a, b) {
         return a === b;
     return (a.kind === b.kind && a.ids.length === b.ids.length && a.ids.every((id, i) => id === b.ids[i]));
 }
+const inRect = (p, b) => p[0] >= b.west && p[0] <= b.east && p[1] >= b.south && p[1] <= b.north;
 function prefersReducedMotion() {
     return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
 }
@@ -55,6 +57,7 @@ class MapContextImpl {
     #glState = $state.raw(null);
     #focusedKey = $state(null);
     #focusedPluginId = $state(null);
+    #focusedAnchor = $state.raw(null);
     #selections = new SvelteMap();
     #featureClickHandlers = new Set();
     #router = new InteractionRouter();
@@ -63,6 +66,11 @@ class MapContextImpl {
     #destroyed = false;
     #listInset = 0;
     #listInsetSide = "left";
+    /** An animated ease that `focusFeature` started is still running (cleared on `moveend`). */
+    #focusEasing = false;
+    #onMoveEnd = () => {
+        this.#focusEasing = false;
+    };
     constructor(options) {
         const initialView = copyView(options.config.initialView ?? DEFAULT_VIEW);
         this.config = {
@@ -123,6 +131,9 @@ class MapContextImpl {
     get focusedPluginId() {
         return this.#focusedPluginId;
     }
+    get focusedAnchor() {
+        return this.#focusedAnchor;
+    }
     get hovered() {
         return this.#router.hovered;
     }
@@ -178,9 +189,15 @@ class MapContextImpl {
         const found = untrack(() => this.#findItem(refKey, pluginId));
         if (!found)
             return;
-        this.#emitClick(pluginId, found.item.ref, found.item.lngLat);
-        if (found.item.selectable)
-            this.#applyPick(pluginId, found.item.ref, additive);
+        const { item } = found;
+        // Where the row's tooltip pins: the focused anchor for the focused row, else a point of a
+        // shape in view (a point's own position for points and on-screen label points).
+        const focused = untrack(() => this.#focusedKey) === refKey &&
+            (untrack(() => this.#focusedPluginId) ?? pluginId) === pluginId;
+        const anchor = (focused && untrack(() => this.#focusedAnchor)) || this.anchorFor(item);
+        this.#emitClick(pluginId, item.ref, anchor);
+        if (item.selectable)
+            this.#applyPick(pluginId, item.ref, additive);
     }
     clearSelection(pluginId) {
         if (this.#destroyed)
@@ -225,19 +242,101 @@ class MapContextImpl {
             return;
         this.#focusedKey = refKey;
         this.#focusedPluginId = refKey === null ? null : (pluginId ?? null);
+        this.#focusedAnchor = null;
         const gl = this.#gl;
         if (!gl || refKey === null)
             return;
         const found = untrack(() => this.#findItem(refKey, pluginId));
         if (!found)
             return;
+        const { item } = found;
+        const place = this.#placeFor(item, gl);
+        this.#focusedAnchor = place.anchor;
+        if (!place.pan) {
+            // Stays where it is now: an earlier focus's ease that is still running stops here.
+            // With nothing running, no move at all.
+            if (this.#focusEasing) {
+                const { lng, lat } = gl.getCenter();
+                gl.easeTo({ center: [lng, lat], duration: 0 });
+                this.#focusEasing = false;
+            }
+            return;
+        }
+        const reduce = prefersReducedMotion();
         gl.easeTo({
-            center: found.item.lngLat,
+            center: place.anchor,
             // The middle of the part the panel leaves clear. An offset, not padding: MapLibre keeps
             // padding for later moves (zooms, the reported center), an offset applies to this one.
             ...(this.#listInset > 0 && { offset: [this.#listOffsetX(), 0] }),
-            ...(prefersReducedMotion() && { duration: 0 })
+            ...(reduce && { duration: 0 })
         });
+        // Set after the call: stopping an earlier move fires its `moveend` inside `easeTo`.
+        this.#focusEasing = !reduce;
+    }
+    anchorFor(item) {
+        const gl = this.#gl;
+        if (!gl || !item.geometry)
+            return item.lngLat;
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(item.lngLat, live) || !intersectsBounds(item, live))
+            return item.lngLat;
+        return (shapeAnchor(item.geometry, clear, clearCenter) ??
+            shapeAnchor(item.geometry, live, liveCenter) ??
+            item.lngLat);
+    }
+    /** The live view, and the part of it the list panel leaves clear, with their centers. */
+    #views(gl) {
+        const b = gl.getBounds();
+        const live = {
+            west: b.getWest(),
+            south: b.getSouth(),
+            east: b.getEast(),
+            north: b.getNorth()
+        };
+        const center = gl.getCenter();
+        const width = untrack(() => gl.getCanvas().clientWidth) || 0;
+        const share = width > 0 ? Math.min(Math.max(this.#listInset / width, 0), 0.99) : 0;
+        const cut = share * (live.east - live.west);
+        const clear = this.#listInsetSide === "left"
+            ? { ...live, west: live.west + cut }
+            : { ...live, east: live.east - cut };
+        return {
+            live,
+            clear,
+            liveCenter: [center.lng, center.lat],
+            clearCenter: [(clear.west + clear.east) / 2, center.lat]
+        };
+    }
+    /**
+     * Where focus puts `item`: `pan: false` keeps the camera (a shape in view whose `lngLat` is
+     * off-screen, with a point in the clear part); otherwise ease to center `anchor`.
+     */
+    #placeFor(item, gl) {
+        const { geometry, lngLat } = item;
+        if (!geometry)
+            return { anchor: lngLat, pan: true };
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(lngLat, live))
+            return { anchor: lngLat, pan: true };
+        if (intersectsBounds(item, live)) {
+            const inClear = shapeAnchor(geometry, clear, clearCenter);
+            if (inClear)
+                return { anchor: inClear, pan: false };
+            const inLive = shapeAnchor(geometry, live, liveCenter);
+            if (inLive)
+                return { anchor: inLive, pan: true };
+        }
+        const settled = untrack(() => this.#bounds);
+        if (settled && intersectsBounds(item, settled)) {
+            const middle = [
+                (settled.west + settled.east) / 2,
+                (settled.south + settled.north) / 2
+            ];
+            const inSettled = shapeAnchor(geometry, settled, middle);
+            if (inSettled)
+                return { anchor: inSettled, pan: true };
+        }
+        return { anchor: lngLat, pan: true };
     }
     #cameraOptions(target, gl) {
         const zoom = target.zoom ??
@@ -281,6 +380,7 @@ class MapContextImpl {
         this.#glState = gl;
         this.#host.attach(gl);
         this.#router.attach(gl);
+        gl.on("moveend", this.#onMoveEnd);
         this.basemap.attach(gl, () => this.#host.restyle(), () => {
             this.#ready = false;
             this.#readyRequested = false;
@@ -291,6 +391,8 @@ class MapContextImpl {
     detach() {
         if (!this.#gl)
             return;
+        this.#gl.off("moveend", this.#onMoveEnd);
+        this.#focusEasing = false;
         this.#router.detach();
         this.basemap.detach();
         this.#host.detach();
@@ -326,6 +428,7 @@ class MapContextImpl {
         this.#featureClickHandlers.clear();
         this.#focusedKey = null;
         this.#focusedPluginId = null;
+        this.#focusedAnchor = null;
         this.#destroyed = true;
     }
     /** A click on a feature: report it, then apply it to the top hit's plugin's selection. */

package/dist/core/plugin.d.ts

@@ -53,6 +53,19 @@ export interface FeatureListItem {
      */
     truncate?: boolean;
     lngLat: [number, number];
+    /**
+     * The feature's shape. When given, the item is in view (the feature list, the view summary)
+     * when the shape overlaps the view, not only when `lngLat` is inside it, and focusing or
+     * hovering it while `lngLat` is off-screen pins its tooltip at a point of the shape in view
+     * (focus then leaves the camera where it is).
+     */
+    geometry?: Geometry;
+    /**
+     * `geometry`'s bounding box, `[west, south, east, north]` (`geometryBbox`). Optional; computed
+     * from `geometry` when missing. A plugin listing many shapes should measure it once per data
+     * load, since the list and summary test every item on every move.
+     */
+    bbox?: [number, number, number, number];
     selectable: boolean;
     /**
      * A short text about a feature with no level (e.g. "Level 2 charger"), shown where its level

package/dist/core/shape-view.d.ts

@@ -0,0 +1,27 @@
+import type { Geometry } from "geojson";
+import type { Bounds } from "./create-map.svelte.js";
+/**
+ * Shapes against the view: a geometry's bounding box, whether it overlaps the view, and a point of
+ * it inside the view. Coordinates are planar lng/lat (as `labelPoint`); no antimeridian handling.
+ */
+/** `[west, south, east, north]`. */
+export type Bbox = [west: number, south: number, east: number, north: number];
+/** The geometry's bounding box, or `null` when it has no coordinates. */
+export declare function geometryBbox(geometry: Geometry): Bbox | null;
+/** Inside an outer ring and outside its holes, for any polygon of the geometry. */
+export declare function containsPoint(geometry: Geometry, p: [number, number]): boolean;
+/**
+ * Whether the item is in view: a shape (`geometry`) when it intersects `bounds` (bbox pre-check,
+ * then the exact test; holes count), anything else when its `lngLat` is inside. Edges included.
+ */
+export declare function intersectsBounds(item: {
+    lngLat: [number, number];
+    geometry?: Geometry;
+    bbox?: Bbox;
+}, bounds: Bounds): boolean;
+/**
+ * A point of the shape inside `view`: `center` when the shape contains it; otherwise a point well
+ * inside the shape's visible part (polygons: the largest clipped one, never in a hole; lines: the
+ * middle of the longest visible piece); `null` when nothing of it is visible.
+ */
+export declare function shapeAnchor(geometry: Geometry, view: Bounds, center: [number, number]): [number, number] | null;

package/dist/core/shape-view.js

@@ -0,0 +1,323 @@
+/** The geometry's bounding box, or `null` when it has no coordinates. */
+export function geometryBbox(geometry) {
+    let west = Infinity;
+    let south = Infinity;
+    let east = -Infinity;
+    let north = -Infinity;
+    const add = (p) => {
+        if (p[0] < west)
+            west = p[0];
+        if (p[0] > east)
+            east = p[0];
+        if (p[1] < south)
+            south = p[1];
+        if (p[1] > north)
+            north = p[1];
+    };
+    const walk = (g) => {
+        switch (g.type) {
+            case "Point":
+                add(g.coordinates);
+                break;
+            case "MultiPoint":
+            case "LineString":
+                g.coordinates.forEach(add);
+                break;
+            case "MultiLineString":
+            case "Polygon":
+                g.coordinates.forEach((ring) => ring.forEach(add));
+                break;
+            case "MultiPolygon":
+                g.coordinates.forEach((poly) => poly.forEach((ring) => ring.forEach(add)));
+                break;
+            case "GeometryCollection":
+                g.geometries.forEach(walk);
+                break;
+        }
+    };
+    walk(geometry);
+    return west <= east ? [west, south, east, north] : null;
+}
+const inRect = (p, b) => p[0] >= b.west && p[0] <= b.east && p[1] >= b.south && p[1] <= b.north;
+/** The polygons of a geometry (each an outer ring and holes), or `null` for a non-polygon. */
+function polygonsOf(g) {
+    if (g.type === "Polygon")
+        return [g.coordinates];
+    if (g.type === "MultiPolygon")
+        return g.coordinates;
+    return null;
+}
+function linesOf(g) {
+    if (g.type === "LineString")
+        return [g.coordinates];
+    if (g.type === "MultiLineString")
+        return g.coordinates;
+    return null;
+}
+/** Ring edges, closing an unclosed ring. Fewer than 3 points: no area, so no edges. */
+function ringEdges(ring) {
+    const n = ring.length;
+    if (n < 3)
+        return [];
+    const edges = [];
+    for (let i = 0; i < n - 1; i++)
+        edges.push([ring[i], ring[i + 1]]);
+    const [a, z] = [ring[0], ring[n - 1]];
+    if (a[0] !== z[0] || a[1] !== z[1])
+        edges.push([z, a]);
+    return edges;
+}
+function inRing(p, ring) {
+    let inside = false;
+    for (const [a, b] of ringEdges(ring)) {
+        if (a[1] > p[1] !== b[1] > p[1]) {
+            const x = ((b[0] - a[0]) * (p[1] - a[1])) / (b[1] - a[1]) + a[0];
+            if (p[0] < x)
+                inside = !inside;
+        }
+    }
+    return inside;
+}
+function inPolygon(p, polygon) {
+    const [outer, ...holes] = polygon;
+    return !!outer && inRing(p, outer) && !holes.some((hole) => inRing(p, hole));
+}
+/** Inside an outer ring and outside its holes, for any polygon of the geometry. */
+export function containsPoint(geometry, p) {
+    return polygonsOf(geometry)?.some((polygon) => inPolygon(p, polygon)) ?? false;
+}
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+const onSegment = (p, a, b) => Math.min(a[0], b[0]) <= p[0] &&
+    p[0] <= Math.max(a[0], b[0]) &&
+    Math.min(a[1], b[1]) <= p[1] &&
+    p[1] <= Math.max(a[1], b[1]);
+/** Whether segments ab and cd meet, touching and collinear overlaps included. */
+function segmentsMeet(a, b, c, d) {
+    const d1 = cross(c, d, a);
+    const d2 = cross(c, d, b);
+    const d3 = cross(a, b, c);
+    const d4 = cross(a, b, d);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0)))
+        return true;
+    return ((d1 === 0 && onSegment(a, c, d)) ||
+        (d2 === 0 && onSegment(b, c, d)) ||
+        (d3 === 0 && onSegment(c, a, b)) ||
+        (d4 === 0 && onSegment(d, a, b)));
+}
+function rectCorners(b) {
+    return [
+        [b.west, b.south],
+        [b.east, b.south],
+        [b.east, b.north],
+        [b.west, b.north]
+    ];
+}
+function segmentHitsRect(a, b, r) {
+    if (inRect(a, r) || inRect(b, r))
+        return true;
+    const c = rectCorners(r);
+    return c.some((p, i) => segmentsMeet(a, b, p, c[(i + 1) % 4]));
+}
+function polygonHitsRect(polygon, r) {
+    const edges = polygon.flatMap(ringEdges);
+    if (edges.length === 0)
+        return false;
+    if (edges.some(([a]) => inRect(a, r)))
+        return true;
+    if (rectCorners(r).some((p) => inPolygon(p, polygon)))
+        return true;
+    return edges.some(([a, b]) => segmentHitsRect(a, b, r));
+}
+/**
+ * Whether the item is in view: a shape (`geometry`) when it intersects `bounds` (bbox pre-check,
+ * then the exact test; holes count), anything else when its `lngLat` is inside. Edges included.
+ */
+export function intersectsBounds(item, bounds) {
+    const { geometry } = item;
+    const polygons = geometry && polygonsOf(geometry);
+    const lines = geometry && linesOf(geometry);
+    if (!geometry || (!polygons && !lines && geometry.type !== "Point")) {
+        return inRect(item.lngLat, bounds);
+    }
+    if (geometry.type === "Point")
+        return inRect(geometry.coordinates, bounds);
+    const box = item.bbox ?? geometryBbox(geometry);
+    if (!box ||
+        box[0] > bounds.east ||
+        box[2] < bounds.west ||
+        box[1] > bounds.north ||
+        box[3] < bounds.south) {
+        return false;
+    }
+    if (polygons)
+        return polygons.some((polygon) => polygonHitsRect(polygon, bounds));
+    return lines.some((line) => line.some((p, i) => i === 0 ? line.length === 1 && inRect(p, bounds) : segmentHitsRect(line[i - 1], p, bounds)));
+}
+/** Sutherland–Hodgman: the ring clipped to the rectangle (open, no repeated first point). */
+function clipRing(ring, r) {
+    let pts = ringEdges(ring).map(([a]) => [a[0], a[1]]);
+    const sides = [
+        [(p) => p[0] >= r.west, (a, b) => atX(a, b, r.west)],
+        [(p) => p[0] <= r.east, (a, b) => atX(a, b, r.east)],
+        [(p) => p[1] >= r.south, (a, b) => atY(a, b, r.south)],
+        [(p) => p[1] <= r.north, (a, b) => atY(a, b, r.north)]
+    ];
+    for (const [keep, cut] of sides) {
+        const out = [];
+        for (let i = 0; i < pts.length; i++) {
+            const cur = pts[i];
+            const prev = pts[(i + pts.length - 1) % pts.length];
+            if (keep(cur)) {
+                if (!keep(prev))
+                    out.push(cut(prev, cur));
+                out.push(cur);
+            }
+            else if (keep(prev)) {
+                out.push(cut(prev, cur));
+            }
+        }
+        pts = out;
+        if (pts.length === 0)
+            break;
+    }
+    return pts;
+}
+const atX = (a, b, x) => [
+    x,
+    a[1] + ((b[1] - a[1]) * (x - a[0])) / (b[0] - a[0])
+];
+const atY = (a, b, y) => [
+    a[0] + ((b[0] - a[0]) * (y - a[1])) / (b[1] - a[1]),
+    y
+];
+function openArea(pts) {
+    let area = 0;
+    for (let i = 0; i < pts.length; i++) {
+        const [a, b] = [pts[i], pts[(i + 1) % pts.length]];
+        area += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(area) / 2;
+}
+/**
+ * A point well inside the clipped polygon (outer ring, then holes): the midpoint of the widest
+ * interior span of a horizontal line through its middle. When that line has none (a C shape,
+ * bands around a hole), the widest span among lines between neighboring vertex heights.
+ */
+function polygonInteriorPoint(rings) {
+    const ys = [...new Set(rings.flatMap((ring) => ring.map((p) => p[1])))].sort((a, b) => a - b);
+    if (ys.length < 2)
+        return null;
+    const middle = widestSpan(rings, ys, [(ys[0] + ys[ys.length - 1]) / 2]);
+    if (middle)
+        return middle;
+    const gaps = [];
+    for (let i = 1; i < ys.length; i++)
+        gaps.push((ys[i - 1] + ys[i]) / 2);
+    return widestSpan(rings, ys, gaps);
+}
+/** The midpoint of the widest interior span on any of the horizontal `lines`. */
+function widestSpan(rings, ys, lines) {
+    let best = null;
+    let width = 0;
+    for (let y of lines) {
+        // On a vertex height the crossings double up; step off it.
+        if (ys.includes(y))
+            y += (ys[ys.length - 1] - ys[0]) * 1e-9;
+        const xs = [];
+        for (const ring of rings) {
+            for (let i = 0; i < ring.length; i++) {
+                const [a, b] = [ring[i], ring[(i + 1) % ring.length]];
+                if (a[1] > y !== b[1] > y)
+                    xs.push(atY(a, b, y)[0]);
+            }
+        }
+        xs.sort((a, b) => a - b);
+        for (let i = 0; i + 1 < xs.length; i += 2) {
+            if (xs[i + 1] - xs[i] > width) {
+                width = xs[i + 1] - xs[i];
+                best = [(xs[i] + xs[i + 1]) / 2, y];
+            }
+        }
+    }
+    return best;
+}
+/** Liang–Barsky: the segment clipped to the rectangle, or `null` when it misses. */
+function clipSegment(a, b, r) {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    let t0 = 0;
+    let t1 = 1;
+    const checks = [
+        [-dx, a[0] - r.west],
+        [dx, r.east - a[0]],
+        [-dy, a[1] - r.south],
+        [dy, r.north - a[1]]
+    ];
+    for (const [p, q] of checks) {
+        if (p === 0) {
+            if (q < 0)
+                return null;
+        }
+        else {
+            const t = q / p;
+            if (p < 0)
+                t0 = Math.max(t0, t);
+            else
+                t1 = Math.min(t1, t);
+            if (t0 > t1)
+                return null;
+        }
+    }
+    return [
+        [a[0] + t0 * dx, a[1] + t0 * dy],
+        [a[0] + t1 * dx, a[1] + t1 * dy]
+    ];
+}
+/**
+ * A point of the shape inside `view`: `center` when the shape contains it; otherwise a point well
+ * inside the shape's visible part (polygons: the largest clipped one, never in a hole; lines: the
+ * middle of the longest visible piece); `null` when nothing of it is visible.
+ */
+export function shapeAnchor(geometry, view, center) {
+    const polygons = polygonsOf(geometry);
+    if (polygons) {
+        if (inRect(center, view) && containsPoint(geometry, center))
+            return center;
+        // Visible parts, largest first; the first that yields a point wins.
+        const parts = [];
+        for (const polygon of polygons) {
+            if (!polygon[0] || ringEdges(polygon[0]).length === 0)
+                continue;
+            const rings = polygon.map((ring) => clipRing(ring, view));
+            const area = rings[0].length >= 3 ? openArea(rings[0]) : 0;
+            if (area > 0)
+                parts.push({ rings: rings.filter((r, i) => i === 0 || r.length >= 3), area });
+        }
+        parts.sort((a, b) => b.area - a.area);
+        for (const { rings } of parts) {
+            const at = polygonInteriorPoint(rings);
+            if (at)
+                return at;
+        }
+        return null;
+    }
+    const lines = linesOf(geometry);
+    if (lines) {
+        let best = null;
+        let length = -1;
+        for (const line of lines) {
+            for (let i = 1; i < line.length; i++) {
+                const piece = clipSegment(line[i - 1], line[i], view);
+                if (!piece)
+                    continue;
+                const len = Math.hypot(piece[1][0] - piece[0][0], piece[1][1] - piece[0][1]);
+                if (len > length) {
+                    length = len;
+                    best = [(piece[0][0] + piece[1][0]) / 2, (piece[0][1] + piece[1][1]) / 2];
+                }
+            }
+        }
+        return best;
+    }
+    return null;
+}

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_level": "{name}, {level}",
 	"mapsdk_list_row_detail": "{name}, {detail}",
 	"mapsdk_list_empty": "Nothing on the map in this view",
 	"mapsdk_selected_count_one": "{count} selected",

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { legendSection } from "./ui/legend-data.js";
 export type { LegendBar as LegendBarData, LegendSection } from "./ui/legend-data.js";
 export { rowLabel } from "./ui/feature-list.js";
 export type { SortBy } from "./ui/feature-list.js";
+export { geometryBbox, intersectsBounds } from "./core/shape-view.js";
+export type { Bbox } from "./core/shape-view.js";
 export { pointsPlugin } from "./plugins/points.svelte.js";
 export type { ClusterInfo, ClusterLayerArgs, PointsOptions, PointsTooltipEnv } from "./plugins/points.svelte.js";
 export type { ClusterLayers } from "./plugins/points-clusters.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { default as ViewSummary } from "./ui/ViewSummary.svelte";
 export { default as MapControls } from "./ui/MapControls.svelte";
 export { legendSection } from "./ui/legend-data.js";
 export { rowLabel } from "./ui/feature-list.js";
+export { geometryBbox, intersectsBounds } from "./core/shape-view.js";
 export { pointsPlugin } from "./plugins/points.svelte.js";
 export { colorExpression, levelKeyExpression, opacityExpression } from "./plugins/style.js";
 export { shapesPlugin } from "./plugins/shapes.svelte.js";

package/dist/plugins/shapes.svelte.js

@@ -1,3 +1,4 @@
+import { geometryBbox } from "../core/shape-view.js";
 import { untrack } from "svelte";
 import { decodeRef, selectionId } from "../data/refs.js";
 import { levelFor, NO_LEVEL } from "../data/scale.js";
@@ -88,6 +89,17 @@ export function shapesPlugin(options) {
     /** Plain mode ignores the source's scale. */
     const currentScale = () => (choropleth ? scales.current() : NO_SCALE);
     const legend = () => (choropleth ? scales.legend() : null);
+    // Each feature's label point and bbox, measured once per feature object (once per data load):
+    // `features()` runs on every move. Per plugin instance, so two maps share nothing.
+    const measured = new WeakMap();
+    const measure = (feature) => {
+        let m = measured.get(feature);
+        if (!m) {
+            m = { lngLat: labelPoint(feature.geometry), bbox: geometryBbox(feature.geometry) };
+            measured.set(feature, m);
+        }
+        return m;
+    };
     function features() {
         const collection = source.features;
         if (!collection)
@@ -101,8 +113,10 @@ export function shapesPlugin(options) {
             if (!props || !feature.geometry)
                 continue;
             const ref = decodeRef(props.refKey);
-            const lngLat = labelPoint(feature.geometry);
-            if (!ref || !lngLat)
+            if (!ref)
+                continue;
+            const { lngLat, bbox } = measure(feature);
+            if (!lngLat)
                 continue;
             items.push({
                 refKey: props.refKey,
@@ -113,6 +127,8 @@ export function shapesPlugin(options) {
                 units: scale?.units ?? "",
                 precision,
                 lngLat,
+                geometry: feature.geometry,
+                ...(bbox && { bbox }),
                 selectable: selectable && selectionId(ref) !== null
             });
         }

package/dist/ui/FeatureList.svelte

@@ -11,11 +11,11 @@
 		rowLabel,
 		levelText,
 		shownLevel,
+		shownValue,
 		sortItems,
 		typeaheadIndex,
 		type SortBy
 	} from "./feature-list.js";
-	import { formatValue as formatNumber } from "./value-format.js";
 
 	interface Props {
 		map: MapContext;
@@ -267,13 +267,6 @@
 		pick(rows[index], e.shiftKey || e.metaKey || e.ctrlKey);
 	}
 
-	function formatValue(row: Row): string {
-		if (row.value === null) return "";
-		return typeof row.value === "number"
-			? formatNumber(row.value, row.precision, map.format, row.truncate)
-			: row.value;
-	}
-
 	onDestroy(() => {
 		clearTimeout(typeaheadTimer);
 		clearTimeout(menuSentTimer);
@@ -332,6 +325,7 @@
 				{@const index = range.start + i}
 				{@const level = shownLevel(row)}
 				{@const levelPlace = levelText(row, map.messages)}
+				{@const value = shownValue(row, map.format)}
 				{@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 -->
@@ -359,7 +353,7 @@
 					</span>
 					<span class="mapsdk-list-name">{row.name}</span>
 					<span class="mapsdk-list-value">
-						{formatValue(row)}{#if row.units && row.value !== null}&nbsp;{row.units}{/if}
+						{value ?? ""}{#if row.units && value !== null}&nbsp;{row.units}{/if}
 					</span>
 					<span class="mapsdk-list-level text-xs">
 						{#if levelPlace.kind !== "detail"}

package/dist/ui/MapTooltip.svelte

@@ -70,11 +70,24 @@
 	// A found item anchors the tooltip at its point (stable while the pointer moves over it).
 	// In pointer mode a hovered hit is anchored at the pointer instead (a focused item stays
 	// pinned).
-	const anchor = $derived(
-		mode === "pointer" && !map.focusedKey
-			? (map.hovered?.lngLat ?? null)
-			: (item?.lngLat ?? map.hovered?.lngLat ?? null)
+	// A hovered shape whose point is off-screen pins at a point of it in view, found once per
+	// hovered feature (keyed on primitives), so pointer moves within it don't move the tooltip.
+	// It's found again when the map settles (`bounds`), so a pan or zoom under a resting pointer
+	// doesn't leave it off-screen.
+	const hoverKey = $derived(
+		!map.focusedKey && item && hitPluginId ? `${hitPluginId}\n${item.refKey}` : null
 	);
+	const hoverAnchor = $derived.by(() => {
+		if (hoverKey === null) return null;
+		void map.bounds;
+		return untrack(() => (item?.geometry ? map.anchorFor(item) : null));
+	});
+	const anchor = $derived.by((): [number, number] | null => {
+		if (mode === "pointer" && !map.focusedKey) return map.hovered?.lngLat ?? null;
+		// A focused feature that left the data has no item, so no tooltip.
+		if (map.focusedKey) return item ? (map.focusedAnchor ?? item.lngLat) : null;
+		return hoverAnchor ?? item?.lngLat ?? map.hovered?.lngLat ?? null;
+	});
 	const projected = $derived(anchor ? project(anchor) : null);
 	// Centered above the point; flipped below it near the top edge; inside the container.
 	const position = $derived.by(() => {

package/dist/ui/TooltipItem.svelte

@@ -3,9 +3,8 @@
 	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 { levelText, shownValue } from "./feature-list.js";
 	import { levelChip } from "./level-chip.js";
-	import { formatValue } from "./value-format.js";
 
 	// The generic tooltip body under a feature's name: its value and a chip with its level. Shared
 	// by MapTooltip and by plugins that show it for features they don't list.
@@ -26,13 +25,8 @@
 		const chip = levelChip(level?.color);
 		return chip ? `background:${chip.background};color:${chip.text}` : "";
 	});
-	const valueText = $derived(
-		item.value == null
-			? null
-			: typeof item.value === "number"
-				? formatValue(item.value, item.precision, format, item.truncate)
-				: item.value
-	);
+	// A category reading shows only its level chip: its value is the level's code.
+	const valueText = $derived(shownValue(item, format));
 </script>
 
 <div class="mapsdk-tooltip-item">

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

@@ -16,13 +16,21 @@ export declare const MENU_EVENT_WINDOW_MS = 1000;
  * separator and different rows never share a fragment.
  */
 export declare function optionIdPart(pluginId: string, refKey: string): string;
-/** Items whose point is inside `bounds`, edges included. No antimeridian handling (the Valley). */
+/**
+ * Items in `bounds`, edges included: a shape (`geometry`) when it overlaps them, anything else when
+ * its point is inside. No antimeridian handling (the Valley).
+ */
 export declare function inView(items: FeatureListItem[], bounds: Bounds): FeatureListItem[];
 /**
  * The item's level, or null for `NO_LEVEL`. A level with an empty color is still shown, by its
  * label on a neutral swatch.
  */
 export declare function shownLevel(item: FeatureListItem): Level | null;
+/**
+ * The value as shown, or `null` for none. A category reading, whose value is its level's code
+ * (smoke's "light", the heat score's 2), shows no value: its level label already says it.
+ */
+export declare function shownValue(item: FeatureListItem, format: FormatProvider): string | null;
 /** A sorted copy. `value`: highest first, null values and no level last; ties and `name` by name. */
 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. */

package/dist/ui/feature-list.js

@@ -1,3 +1,4 @@
+import { intersectsBounds } from "../core/shape-view.js";
 import { NO_LEVEL } from "../data/scale.js";
 import { formatValue } from "./value-format.js";
 /**
@@ -14,11 +15,12 @@ export function optionIdPart(pluginId, refKey) {
     const escape = (text) => text.replace(/[^A-Za-z0-9]/g, (c) => `_${c.codePointAt(0).toString(16)}_`);
     return `${escape(pluginId)}--${escape(refKey)}`;
 }
-/** Items whose point is inside `bounds`, edges included. No antimeridian handling (the Valley). */
+/**
+ * Items in `bounds`, edges included: a shape (`geometry`) when it overlaps them, anything else when
+ * its point is inside. No antimeridian handling (the Valley).
+ */
 export function inView(items, bounds) {
-    return items.filter(({ lngLat: [lng, lat] }) => {
-        return lng >= bounds.west && lng <= bounds.east && lat >= bounds.south && lat <= bounds.north;
-    });
+    return items.filter((item) => intersectsBounds(item, bounds));
 }
 /**
  * The item's level, or null for `NO_LEVEL`. A level with an empty color is still shown, by its
@@ -27,6 +29,20 @@ export function inView(items, bounds) {
 export function shownLevel(item) {
     return item.level !== NO_LEVEL ? item.level : null;
 }
+/**
+ * The value as shown, or `null` for none. A category reading, whose value is its level's code
+ * (smoke's "light", the heat score's 2), shows no value: its level label already says it.
+ */
+export function shownValue(item, format) {
+    if (item.value === null)
+        return null;
+    const level = shownLevel(item);
+    if (level && level.value !== null && level.value === item.value)
+        return null;
+    return typeof item.value === "number"
+        ? formatValue(item.value, item.precision, format, item.truncate)
+        : item.value;
+}
 const collator = new Intl.Collator("en-US");
 /** A value's sort weight; `null` sorts last. Category values sort by their level's tier. */
 function weight(item) {
@@ -80,16 +96,18 @@ export function levelText(item, messages) {
 /** 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) {
+    const value = shownValue(item, format);
+    if (value === null) {
+        // A category reading: its level is its value.
+        if (item.value !== null && level.kind === "level")
+            return messages("mapsdk_list_row_level", { name: item.name, level: level.text });
         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.truncate)
-            : item.value,
+        value,
         units: item.units,
         level: level.text
     };

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.4",
+	"version": "0.1.0-beta.6",
 	"license": "MIT",
 	"repository": {
 		"type": "git",