@sjvair/map-sdk 0.0.0-stage → 0.1.0-beta.1

package/dist/data/types.d.ts

@@ -0,0 +1,69 @@
+import type { FeatureCollection, Geometry } from "geojson";
+import type { Scale, ScaleRef } from "./scale-types.js";
+export type FeatureRef = {
+    kind: "monitor";
+    id: string;
+} | {
+    kind: "region";
+    type: string;
+    code: string;
+} | {
+    kind: "feature";
+    id: string;
+};
+export type SpatialSelection = {
+    kind: "monitors" | "regions";
+    ids: string[];
+};
+export type SelectionMode = "none" | "single" | "multiple";
+export interface MapFeatureProperties {
+    refKey: string;
+    name: string;
+    value: number | string | null;
+}
+/** A monitor on the map: what the monitors preset draws and its tooltips show. */
+export interface MonitorFeatureProperties extends MapFeatureProperties {
+    /** The server's monitor type (e.g. "purpleair", "airnow"); picks the marker shape. */
+    type: string;
+    isActive: boolean;
+    isSjvair: boolean;
+    location: "inside" | "outside";
+    /** When the reading was taken (ISO 8601), for the tooltip. */
+    timestamp?: string | null;
+}
+export type DataStatus = {
+    state: "loading";
+} | {
+    state: "ready";
+} | {
+    state: "error";
+    error: unknown;
+    retry(): void;
+} | {
+    state: "unavailable";
+    reason: string;
+};
+export interface DataSource<P extends MapFeatureProperties = MapFeatureProperties> {
+    readonly status: DataStatus;
+    readonly features: FeatureCollection<Geometry, P> | null;
+    readonly scale: ScaleRef | Scale | null;
+}
+/**
+ * A collocation site: drawn at its reference monitor with that monitor's type, location,
+ * activity, and reading, plus the collocated monitor's reading. Readings are null when a
+ * monitor isn't in the monitors store (inactive, filtered out, or not loaded yet).
+ */
+export interface CollocationFeatureProperties extends MonitorFeatureProperties {
+    /**
+     * The reference monitor's own name (the tooltip shows it); null when it isn't in the
+     * monitors store.
+     */
+    referenceName: string | null;
+    colocatedId: string;
+    /** Null when the collocated monitor isn't in the monitors store. */
+    colocatedName: string | null;
+    /** The collocated monitor's type, for its tooltip's "(N avg)" note; null when unknown. */
+    colocatedType: string | null;
+    colocatedValue: number | null;
+    colocatedTimestamp: string | null;
+}

package/dist/data/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { type CreateMapOptions, type MapContext } from "./core/create-map.svelte.js";
+export { defaultBasemaps } from "./view/create-gl-map.js";
+export { default as MapView } from "./view/MapView.svelte";
+export type { FeatureListOptions, ListPosition } from "./view/list-placement.js";
+export { default as Legend } from "./ui/Legend.svelte";
+export { default as FeatureList } from "./ui/FeatureList.svelte";
+export { default as MapTooltip } from "./ui/MapTooltip.svelte";
+export { default as SelectionBar } from "./ui/SelectionBar.svelte";
+export { default as ViewSummary } from "./ui/ViewSummary.svelte";
+export { default as MapControls } from "./ui/MapControls.svelte";
+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 { 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";
+export { colorExpression, levelKeyExpression, opacityExpression } from "./plugins/style.js";
+export type { ThemeColors, ValueInput } from "./plugins/style.js";
+export { shapesPlugin } from "./plugins/shapes.svelte.js";
+export type { ShapesOptions } from "./plugins/shapes.svelte.js";
+export { monitorShape, monitorsPlugin } from "./presets/monitors.js";
+export type { MonitorShape, MonitorsPluginOptions } from "./presets/monitors.js";
+export { regionsPlugin } from "./presets/regions.js";
+export type { RegionsPluginOptions } from "./presets/regions.js";
+export { calHeatScorePlugin } from "./presets/calheatscore.js";
+export type { CalHeatScorePluginOptions } from "./presets/calheatscore.js";
+export { forecastZonesPlugin } from "./presets/forecast-zones.js";
+export type { ForecastZonesPluginOptions } from "./presets/forecast-zones.js";
+export { summaryText } from "./ui/view-summary.js";
+export { getMapContext } from "./core/context.js";
+export type { BlockingClick, FeatureHit, FeatureListItem, LayerSpecWithoutId, LegendData, MapPlugin, PluginContext, Providers } from "./core/plugin.js";
+export type { GlMapLike } from "./core/gl.js";
+export type { CustomLayerInterface } from "@maptiler/sdk";
+export type { Hovered } from "./core/interactions.svelte.js";
+export type { BasemapConfig } from "./core/basemap.svelte.js";
+export type { Bounds, CameraState, CameraTarget, CreateMapOptions, FeatureClickHandler, MapConfig, MapContext, PluginOptions } from "./core/create-map.svelte.js";
+/**
+ * The attached MapTiler `Map`, or `null` while detached: an escape hatch for markers and popups
+ * only. The host must never add sources or layers through it; plugins own those.
+ */
+export declare function maptilerMap(map: MapContext): import("@maptiler/sdk").Map | null;
+/**
+ * Creates a map's state and services; show it with `<MapView map={…} />`. Without
+ * `config.basemaps`, the basemaps are MapTiler Streets v4 and its variants, as on today's map.
+ */
+export declare function createMap(options: CreateMapOptions): MapContext;
+export { hmsSmokePlugin } from "./presets/hms-smoke.js";
+export type { HmsSmokePluginOptions } from "./presets/hms-smoke.js";
+export { hmsFirePlugin } from "./presets/hms-fire.js";
+export type { HmsFirePluginOptions } from "./presets/hms-fire.js";
+export { cleanFires, groupFires } from "./presets/fire-groups.js";
+export type { FireDetection, FireGroup } from "./presets/fire-groups.js";
+export { collocationSitesPlugin, COLLOCATION_CROSSHAIR_COLOR } from "./presets/collocation-sites.js";
+export type { CollocationSitesPluginOptions } from "./presets/collocation-sites.js";
+export { circle, CROSSHAIR_ICON_SIZE, square, triangle, withCrosshair } from "./plugins/icons.js";

package/dist/index.js

@@ -0,0 +1,41 @@
+import { createMap as createMapContext } from "./core/create-map.svelte.js";
+import { defaultBasemaps } from "./view/create-gl-map.js";
+export { defaultBasemaps } from "./view/create-gl-map.js";
+export { default as MapView } from "./view/MapView.svelte";
+export { default as Legend } from "./ui/Legend.svelte";
+export { default as FeatureList } from "./ui/FeatureList.svelte";
+export { default as MapTooltip } from "./ui/MapTooltip.svelte";
+export { default as SelectionBar } from "./ui/SelectionBar.svelte";
+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 { pointsPlugin } from "./plugins/points.svelte.js";
+export { colorExpression, levelKeyExpression, opacityExpression } from "./plugins/style.js";
+export { shapesPlugin } from "./plugins/shapes.svelte.js";
+export { monitorShape, monitorsPlugin } from "./presets/monitors.js";
+export { regionsPlugin } from "./presets/regions.js";
+export { calHeatScorePlugin } from "./presets/calheatscore.js";
+export { forecastZonesPlugin } from "./presets/forecast-zones.js";
+export { summaryText } from "./ui/view-summary.js";
+export { getMapContext } from "./core/context.js";
+/**
+ * The attached MapTiler `Map`, or `null` while detached: an escape hatch for markers and popups
+ * only. The host must never add sources or layers through it; plugins own those.
+ */
+export function maptilerMap(map) {
+    return map.gl;
+}
+/**
+ * Creates a map's state and services; show it with `<MapView map={…} />`. Without
+ * `config.basemaps`, the basemaps are MapTiler Streets v4 and its variants, as on today's map.
+ */
+export function createMap(options) {
+    const basemaps = options.config.basemaps ?? defaultBasemaps();
+    return createMapContext({ ...options, config: { ...options.config, basemaps } });
+}
+export { hmsSmokePlugin } from "./presets/hms-smoke.js";
+export { hmsFirePlugin } from "./presets/hms-fire.js";
+export { cleanFires, groupFires } from "./presets/fire-groups.js";
+export { collocationSitesPlugin, COLLOCATION_CROSSHAIR_COLOR } from "./presets/collocation-sites.js";
+export { circle, CROSSHAIR_ICON_SIZE, square, triangle, withCrosshair } from "./plugins/icons.js";

package/dist/plugins/icons.d.ts

@@ -0,0 +1,21 @@
+export declare function square(color: string, borderWidth: number, borderColor?: string): string;
+export declare function circle(color: string, borderWidth: number, borderColor?: string): string;
+export declare function triangle(color: string, borderWidth: number, borderColor?: string): string;
+/** The size of a `withCrosshair` image: a 24px marker plus the crosshair around it (56px). */
+export declare const CROSSHAIR_ICON_SIZE: number;
+/**
+ * A 24px marker SVG (`circle`, `square`, `triangle`) centered in a crosshair of `color`, as
+ * monitor-map draws collocation sites. The result is `CROSSHAIR_ICON_SIZE` pixels square.
+ */
+export declare function withCrosshair(baseSvg: string, color: string): string;
+export declare function fireIcon(color: string, size: number): string;
+/** Room around the marker for the ring and the check badge. */
+export declare const SELECTED_OVERLAY_PADDING = 6;
+/**
+ * The selection mark drawn over a selected marker `size` pixels across: a ring around it in
+ * `highlight` plus a check mark badge, so selection never relies on color alone. The image is
+ * `size + 2 * SELECTED_OVERLAY_PADDING` pixels square, centered on the marker. Colors are
+ * concrete values read from the `--highlight` and `--highlight-foreground` tokens at setup.
+ */
+export declare function selectedOverlay(highlight: string, checkColor: string, size: number): string;
+export declare function asDataURI(svg: string): string;

package/dist/plugins/icons.js

@@ -0,0 +1,73 @@
+import { darken } from "color2k";
+// Marker shapes ported from monitor-map (src/lib/map/icons.ts). Shapes and sizes are
+// presentation; every color comes in from a scale level or a theme token.
+/**
+ * A slightly darker stroke for a fill color. color2k throws on an empty or unparseable color
+ * (monitor-map crashed on `darken("")`), so those keep the color itself.
+ */
+function strokeFor(color) {
+    try {
+        return darken(color, 0.1);
+    }
+    catch {
+        return color;
+    }
+}
+export function square(color, borderWidth, borderColor) {
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <rect x="${borderWidth / 2}" y="${borderWidth / 2}" width="${24 - borderWidth}" height="${24 - borderWidth}"
+      fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+export function circle(color, borderWidth, borderColor) {
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="12" cy="12" r="${12 - borderWidth}" fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+export function triangle(color, borderWidth, borderColor) {
+    const points = `${12},${borderWidth} ${24 - borderWidth},${24 - borderWidth} ${borderWidth},${24 - borderWidth}`;
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <polygon points="${points}"
+      fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+// monitor-map's collocation crosshair (src/lib/map/icons.ts): a ring with ticks around a marker.
+const CROSSHAIR_PATH = "M495.9 248H392c-4.4 0-8 3.6-8 8s3.6 8 8 8H495.9C491.7 390.2 390.2 491.7 264 495.9V392c0-4.4-3.6-8-8-8s-8 3.6-8 8V495.9C121.8 491.7 20.3 390.2 16.1 264H120c4.4 0 8-3.6 8-8s-3.6-8-8-8H16.1C20.3 121.8 121.8 20.3 248 16.1V120c0 4.4 3.6 8 8 8s8-3.6 8-8V16.1C390.2 20.3 491.7 121.8 495.9 248zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256z";
+const CROSSHAIR_PADDING = 16;
+/** The size of a `withCrosshair` image: a 24px marker plus the crosshair around it (56px). */
+export const CROSSHAIR_ICON_SIZE = 24 + CROSSHAIR_PADDING * 2;
+/**
+ * A 24px marker SVG (`circle`, `square`, `triangle`) centered in a crosshair of `color`, as
+ * monitor-map draws collocation sites. The result is `CROSSHAIR_ICON_SIZE` pixels square.
+ */
+export function withCrosshair(baseSvg, color) {
+    const size = CROSSHAIR_ICON_SIZE;
+    const inner = baseSvg.replace("<svg ", `<svg x="${CROSSHAIR_PADDING}" y="${CROSSHAIR_PADDING}" `);
+    return `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" xmlns="http://www.w3.org/2000/svg">${inner}<svg x="0" y="0" width="${size}" height="${size}" viewBox="-8 -8 528 528"><path d="${CROSSHAIR_PATH}" fill="${color}" stroke="${color}" stroke-width="5"/></svg></svg>`;
+}
+export function fireIcon(color, size) {
+    return `<svg width="${size}" height="${size}" viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" fill="${color}"><path d="M200-400q0 52 21 98.5t60 81.5q-1-5-1-9v-9q0-32 12-60t35-51l113-111 113 111q23 23 35 51t12 60v9q0 4-1 9 39-35 60-81.5t21-98.5q0-50-18.5-94.5T608-574q-20 13-42 19.5t-45 6.5q-62 0-107.5-41T361-690q-39 33-69 68.5t-50.5 72Q221-513 210.5-475T200-400Zm240 52-57 56q-11 11-17 25t-6 29q0 32 23.5 55t56.5 23q33 0 56.5-23t23.5-55q0-16-6-29.5T497-292l-57-56Zm0-492v132q0 34 23.5 57t57.5 23q18 0 33.5-7.5T582-658l18-22q74 42 117 117t43 163q0 134-93 227T440-80q-134 0-227-93t-93-227q0-129 86.5-245T440-840Zm400 320q-17 0-28.5-11.5T800-560q0-17 11.5-28.5T840-600q17 0 28.5 11.5T880-560q0 17-11.5 28.5T840-520Zm-40-120v-200h80v200h-80Z"/></svg>`;
+}
+/** Room around the marker for the ring and the check badge. */
+export const SELECTED_OVERLAY_PADDING = 6;
+/**
+ * The selection mark drawn over a selected marker `size` pixels across: a ring around it in
+ * `highlight` plus a check mark badge, so selection never relies on color alone. The image is
+ * `size + 2 * SELECTED_OVERLAY_PADDING` pixels square, centered on the marker. Colors are
+ * concrete values read from the `--highlight` and `--highlight-foreground` tokens at setup.
+ */
+export function selectedOverlay(highlight, checkColor, size) {
+    const total = size + 2 * SELECTED_OVERLAY_PADDING;
+    const c = total / 2;
+    const ring = size / 2 + 2.5;
+    const b = SELECTED_OVERLAY_PADDING;
+    const bx = total - b;
+    return `<svg width="${total}" height="${total}" viewBox="0 0 ${total} ${total}" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="${c}" cy="${c}" r="${ring}" fill="none" stroke="${highlight}" stroke-width="3"/>
+    <circle cx="${bx}" cy="${b}" r="${b - 0.5}" fill="${highlight}" stroke="${checkColor}" stroke-width="1"/>
+    <path d="M${bx - 2.5} ${b} l1.75 1.75 l3.25 -3.5" fill="none" stroke="${checkColor}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>`;
+}
+export function asDataURI(svg) {
+    return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}

package/dist/plugins/points-clusters.d.ts

@@ -0,0 +1,60 @@
+import type { ExpressionSpecification, FilterSpecification } from "@maptiler/sdk";
+import type { GlMapLike } from "../core/gl.js";
+import type { BlockingClick, FeatureHit, LayerSpecWithoutId } from "../core/plugin.js";
+import type { Scale } from "../data/scale-types.js";
+import type { MapFeatureProperties } from "../data/types.js";
+import type { ThemeColors } from "./style.js";
+/** A hovered cluster bubble. */
+export interface ClusterInfo<P extends MapFeatureProperties> {
+    group: string;
+    pointCount: number;
+    /** The cluster feature's properties, including `cluster.properties` aggregates. */
+    properties: Readonly<Record<string, unknown>>;
+    /** Every point in the cluster; rejects if the cluster is gone, empty once torn down. */
+    leaves(): Promise<Array<{
+        props: P;
+        lngLat: [number, number];
+    }>>;
+}
+/** What custom cluster layers are built from. */
+export interface ClusterLayerArgs {
+    group: string;
+    sourceId: string;
+    scale: Scale;
+    theme: ThemeColors;
+    /**
+     * The `icon-image` for the plugin's icon of `category` at the level `levelKey` evaluates to
+     * (use `levelKeyExpression`); registers that category's images.
+     */
+    iconImage(category: string, levelKey: ExpressionSpecification): ExpressionSpecification;
+    /** The `icon-size` that shows an icon at its `size` (images are drawn larger for HiDPI). */
+    iconSizeScale: number;
+}
+export type ClusterLayers = Array<{
+    local: string;
+    spec: LayerSpecWithoutId;
+}>;
+export declare const CLUSTERED: FilterSpecification;
+/** Cluster bubbles: a neutral circle with the count. */
+export declare function defaultClusterLayers({ sourceId, theme }: ClusterLayerArgs): ClusterLayers;
+/** What a cluster hover hit names: the data generation it was hovered in, the id, the group. */
+export interface ClusterRef {
+    generation: number;
+    clusterId: number;
+    group: string;
+}
+/**
+ * The hover hit for a bubble: a `{ kind: "feature", id: "cluster:<generation>:<id>:<group>" }`
+ * ref (cluster ids are only meaningful for the data they were made from) carrying the bubble's
+ * properties. No side effects: lookups call it too.
+ */
+export declare function clusterHit(pluginId: string, generation: number, group: string, props: Record<string, unknown>): FeatureHit | null;
+/** The cluster a hover hit names, or null for any other hit. */
+export declare function parseClusterHit(hit: FeatureHit): ClusterRef | null;
+/** A cluster's points, from its source; `[]` once `isDead`. */
+export declare function clusterLeaves<P extends MapFeatureProperties>(gl: GlMapLike, sourceId: string, clusterId: number, pointCount: number, isDead: () => boolean): Promise<Array<{
+    props: P;
+    lngLat: [number, number];
+}>>;
+/** Zooms in far enough to expand a clicked bubble; no animation under reduced motion. */
+export declare function zoomIntoCluster(gl: GlMapLike, sourceId: string, feature: BlockingClick, isDead: () => boolean, pluginId: string): void;

package/dist/plugins/points-clusters.js

@@ -0,0 +1,93 @@
+import { encodeRef } from "../data/refs.js";
+export const CLUSTERED = ["has", "point_count"];
+function prefersReducedMotion() {
+    return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+/** Cluster bubbles: a neutral circle with the count. */
+export function defaultClusterLayers({ sourceId, theme }) {
+    return [
+        {
+            local: "clusters",
+            spec: {
+                type: "circle",
+                source: sourceId,
+                filter: CLUSTERED,
+                paint: {
+                    "circle-radius": ["step", ["get", "point_count"], 12, 10, 16, 25, 20],
+                    "circle-color": theme.neutral,
+                    "circle-stroke-color": theme.foreground,
+                    "circle-stroke-width": 1
+                }
+            }
+        },
+        {
+            local: "cluster-count",
+            spec: {
+                type: "symbol",
+                source: sourceId,
+                filter: CLUSTERED,
+                layout: {
+                    "text-field": ["get", "point_count_abbreviated"],
+                    "text-size": 12,
+                    "text-allow-overlap": true
+                },
+                paint: { "text-color": theme.foreground }
+            }
+        }
+    ];
+}
+const CLUSTER_ID = /^cluster:(\d+):(\d+):(.*)$/s;
+/**
+ * The hover hit for a bubble: a `{ kind: "feature", id: "cluster:<generation>:<id>:<group>" }`
+ * ref (cluster ids are only meaningful for the data they were made from) carrying the bubble's
+ * properties. No side effects: lookups call it too.
+ */
+export function clusterHit(pluginId, generation, group, props) {
+    const clusterId = props.cluster_id;
+    if (typeof clusterId !== "number")
+        return null;
+    const ref = { kind: "feature", id: `cluster:${generation}:${clusterId}:${group}` };
+    return { pluginId, ref, refKey: encodeRef(ref), name: "", properties: { ...props } };
+}
+/** The cluster a hover hit names, or null for any other hit. */
+export function parseClusterHit(hit) {
+    if (hit.ref.kind !== "feature")
+        return null;
+    const match = CLUSTER_ID.exec(hit.ref.id);
+    if (!match)
+        return null;
+    return { generation: Number(match[1]), clusterId: Number(match[2]), group: match[3] };
+}
+/** A cluster's points, from its source; `[]` once `isDead`. */
+export async function clusterLeaves(gl, sourceId, clusterId, pointCount, isDead) {
+    const clusters = isDead() ? undefined : gl.getSource(sourceId);
+    if (!clusters)
+        return [];
+    const leaves = await clusters.getClusterLeaves(clusterId, pointCount, 0);
+    if (isDead())
+        return [];
+    return leaves.flatMap((leaf) => leaf.geometry.type === "Point"
+        ? [
+            {
+                props: leaf.properties,
+                lngLat: leaf.geometry.coordinates.slice(0, 2)
+            }
+        ]
+        : []);
+}
+/** Zooms in far enough to expand a clicked bubble; no animation under reduced motion. */
+export function zoomIntoCluster(gl, sourceId, feature, isDead, pluginId) {
+    const clusterId = feature.properties.cluster_id;
+    if (typeof clusterId !== "number" || feature.geometry.type !== "Point")
+        return;
+    const [lng, lat] = feature.geometry.coordinates;
+    const clusters = gl.getSource(sourceId);
+    clusters?.getClusterExpansionZoom(clusterId).then((zoom) => {
+        if (isDead())
+            return;
+        gl.easeTo({ center: [lng, lat], zoom, ...(prefersReducedMotion() && { duration: 0 }) });
+    }, (error) => {
+        if (!isDead())
+            console.warn(`map-sdk: plugin "${pluginId}" could not expand a cluster`, error);
+    });
+}

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

@@ -0,0 +1,93 @@
+import type { GeoJSONSourceSpecification } from "@maptiler/sdk";
+import { type Snippet } from "svelte";
+import type { FeatureListItem, MapPlugin, Providers } from "../core/plugin.js";
+import type { Scale } from "../data/scale-types.js";
+import type { DataSource, MapFeatureProperties } from "../data/types.js";
+import { type ClusterInfo, type ClusterLayerArgs, type ClusterLayers } from "./points-clusters.js";
+import { type ThemeColors } from "./style.js";
+export type { ClusterInfo, ClusterLayerArgs } from "./points-clusters.js";
+/** What tooltip content gets: the map's providers and the plugin's resolved scale. */
+export interface PointsTooltipEnv extends Providers {
+    /** Null while it resolves or when unavailable. */
+    scale: Scale | null;
+    /** Decimal places for values, as the list items carry it. */
+    precision: number;
+}
+export interface PointsOptions<P extends MapFeatureProperties> {
+    id: string;
+    source: DataSource<P>;
+    /** Already-translated layer name for the list and summary. */
+    layerLabel: string;
+    selectable?: boolean;
+    /**
+     * How a selected feature shows. "ring" (default): a highlight ring and check mark over it.
+     * "enlarge": the icon draws at 1.3x with no ring (icons only; circles are unchanged).
+     */
+    selectedStyle?: "ring" | "enlarge";
+    icon?: {
+        category(props: P): string;
+        /**
+         * An SVG `size` pixels square, filled with `color`; `theme` for outlines. `levelIndex` is the
+         * level's position in the scale, or -1 for the neutral image.
+         */
+        draw(category: string, color: string, theme: ThemeColors, levelIndex?: number): string;
+        size: number;
+        /** Draws in `mutedColor` whatever the value (e.g. an inactive monitor). */
+        muted?(props: P): boolean;
+        /** The color of muted images. Default: the theme's `--muted-foreground`. */
+        mutedColor?: string;
+    };
+    /** Used when there is no `icon`. */
+    circle?: {
+        radius: number;
+    };
+    /**
+     * One clustered source per group. Cluster bubbles hide what is beneath them from clicks and
+     * hovers; clicking one zooms in to expand it.
+     */
+    cluster?: {
+        radius: number;
+        maxZoom: number;
+        groupBy?(props: P): string;
+        /** MapLibre `clusterProperties`: aggregates the layers and tooltip can read. */
+        properties?: GeoJSONSourceSpecification["clusterProperties"];
+        /** Replaces the neutral count bubbles. Local ids get the group appended. */
+        layers?(args: ClusterLayerArgs): ClusterLayers;
+        /** Tooltip content for a hovered cluster. Without it, hovering a bubble shows nothing. */
+        tooltip?(cluster: ClusterInfo<P>, env: PointsTooltipEnv): Snippet | undefined;
+    };
+    /** Higher draws on top (and, clustered, a group with a higher key draws above the others). */
+    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.
+     */
+    zoomRange?: {
+        min?: number;
+        max?: number;
+    };
+    /** How the legend shows a range scale: a gradient (default) or labeled blocks. */
+    legendDisplay?: "gradient" | "blocks";
+    /**
+     * What titles the legend section: `layerLabel` (default) or, for a source with a `ScaleRef`,
+     * the entry type's label from the metadata provider (e.g. "PM2.5"), with `layerLabel` until
+     * it loads.
+     */
+    legendTitle?: "layer" | "entry-type";
+    /** Whether `features()` lists this plugin's features. Default true. */
+    listed?: boolean;
+    /** Tooltip content for a feature, below its name; `props` are its source properties. */
+    tooltip?(item: FeatureListItem, props: P, env: PointsTooltipEnv): Snippet | undefined;
+    /**
+     * The `tooltip` content shows the feature's name itself, so no name header is drawn above
+     * it.
+     */
+    tooltipShowsName?: boolean;
+}
+/**
+ * Points with value-based color: anything with coordinates. Draws circles, or icons by
+ * category (one image per category and level color), optionally clustered per group, with a
+ * highlight ring and check mark over selected features.
+ */
+export declare function pointsPlugin<P extends MapFeatureProperties>(options: PointsOptions<P>): MapPlugin;