@loidolt/theme-maps 0.7.0

package/dist/core/types.d.ts

@@ -0,0 +1,110 @@
+/** `[longitude, latitude]`, in that order, as GeoJSON and MapLibre both use. */
+export type LngLat = [number, number];
+/** `[[west, south], [east, north]]`. */
+export type LngLatBounds = [LngLat, LngLat];
+export type Position = number[];
+export type Geometry = {
+    type: 'Point';
+    coordinates: Position;
+} | {
+    type: 'MultiPoint';
+    coordinates: Position[];
+} | {
+    type: 'LineString';
+    coordinates: Position[];
+} | {
+    type: 'MultiLineString';
+    coordinates: Position[][];
+} | {
+    type: 'Polygon';
+    coordinates: Position[][];
+} | {
+    type: 'MultiPolygon';
+    coordinates: Position[][][];
+} | {
+    type: 'GeometryCollection';
+    geometries: Geometry[];
+};
+export interface Feature<P = Record<string, unknown>> {
+    type: 'Feature';
+    id?: string | number;
+    geometry: Geometry | null;
+    properties: P | null;
+}
+export interface FeatureCollection<P = Record<string, unknown>> {
+    type: 'FeatureCollection';
+    features: Array<Feature<P>>;
+}
+export type GeoJSON = Geometry | Feature | FeatureCollection;
+/** A MapLibre style document. Structural: any valid style object fits. */
+export interface StyleSpecification {
+    version: 8;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    sources: Record<string, Record<string, unknown>>;
+    layers: Array<Record<string, unknown> & {
+        id: string;
+        type: string;
+    }>;
+    glyphs?: string;
+    sprite?: string;
+    [key: string]: unknown;
+}
+/** Where the map is looking. */
+export interface MapViewState {
+    center: LngLat;
+    zoom: number;
+    bearing: number;
+    pitch: number;
+    bounds: LngLatBounds;
+}
+/** A click on the map. */
+export interface MapClickEvent {
+    lngLat: LngLat;
+    point: [number, number];
+    /** Rendered features under the pointer, topmost first. */
+    features: unknown[];
+}
+/** A click on, or pointer over, a feature of one layer. */
+export interface LayerFeatureEvent {
+    /** The topmost feature of the layer under the pointer. */
+    feature: Feature & {
+        layer?: {
+            id: string;
+        };
+        source?: string;
+        state?: Record<string, unknown>;
+    };
+    /** Every feature of the layer under the pointer. */
+    features: Feature[];
+    lngLat: LngLat;
+    point: [number, number];
+}
+/** One entry in a map legend. */
+export interface LegendItem {
+    label: string;
+    color: string;
+    /** How the key is drawn: a filled square, a line, or a dot. */
+    shape?: 'fill' | 'line' | 'dot';
+}
+/** A continuous scale in a map legend: its colours from least to most, and the end labels. */
+export interface LegendGradient {
+    colors: string[];
+    min: string;
+    max: string;
+}
+/** A place the non-visual feature list offers. */
+export interface MapFeatureItem {
+    id: string | number;
+    label: string;
+    lngLat: LngLat;
+    /** A second line, e.g. an address or a status. */
+    description?: string;
+}
+/** A layer's row in `LayerManager`: what it shows and sets. */
+export interface LayerState {
+    id: string;
+    label: string;
+    visible: boolean;
+    opacity: number;
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/*
+ * Minimal GeoJSON and map types, kept structural so `/core` needs neither MapLibre nor
+ * `@types/geojson` to type-check.
+ */
+export {};

package/dist/core/workers/client.d.ts

@@ -0,0 +1,26 @@
+import type { Feature, FeatureCollection, LngLat, LngLatBounds } from '../types.js';
+export interface SpatialWorkerOptions {
+    /** Starts the worker. Defaults to the one this package ships, found next to this file. */
+    workerFactory?: () => Worker;
+    /** Give up on a request after this many milliseconds. */
+    timeout?: number;
+}
+export interface SpatialWorker {
+    /** `worker` while a worker is answering; `main-thread` where none could start. */
+    readonly mode: 'worker' | 'main-thread';
+    /** Indexes a collection, replacing what was there. Resolves to the number of features indexed. */
+    load(features: FeatureCollection, options?: {
+        idProperty?: string;
+    }): Promise<number>;
+    search(bounds: LngLatBounds, limit?: number): Promise<Feature[]>;
+    nearest(point: LngLat, count?: number): Promise<Feature[]>;
+    /** The loaded collection simplified for `zoom`. */
+    simplify(zoom: number, pixels?: number): Promise<FeatureCollection>;
+    terminate(): void;
+}
+/**
+ * Spatial indexing and simplification off the main thread, so a map of tens of thousands of
+ * features stays smooth while it pans. Falls back to the main thread — with the same answers —
+ * where workers are unavailable (the server, tests) or the worker fails to start.
+ */
+export declare function createSpatialWorker(options?: SpatialWorkerOptions): SpatialWorker;

package/dist/core/workers/client.js

@@ -0,0 +1,88 @@
+import { createSpatialHandler } from './handler.js';
+const defaultWorker = () => new Worker(new URL('./spatial.worker.js', import.meta.url), { type: 'module' });
+/**
+ * Spatial indexing and simplification off the main thread, so a map of tens of thousands of
+ * features stays smooth while it pans. Falls back to the main thread — with the same answers —
+ * where workers are unavailable (the server, tests) or the worker fails to start.
+ */
+export function createSpatialWorker(options = {}) {
+    const { timeout = 30_000 } = options;
+    let nextId = 1;
+    let worker = null;
+    let local = null;
+    let lastLoad = null;
+    const pending = new Map();
+    const settle = (response) => {
+        const entry = pending.get(response.id);
+        if (!entry)
+            return;
+        pending.delete(response.id);
+        clearTimeout(entry.timer);
+        if (response.ok)
+            entry.resolve(response.result);
+        else
+            entry.reject(new Error(response.error));
+    };
+    /** Moves to the main thread, replaying the last load so the index is not lost. */
+    const fallBack = () => {
+        worker?.terminate();
+        worker = null;
+        local ??= createSpatialHandler();
+        const queued = [...pending];
+        if (lastLoad && !queued.some(([, entry]) => entry.request === lastLoad)) {
+            local({ ...lastLoad, id: 0 });
+        }
+        for (const [id, entry] of queued)
+            settle(local({ ...entry.request, id }));
+    };
+    try {
+        if (options.workerFactory || typeof Worker !== 'undefined') {
+            worker = (options.workerFactory ?? defaultWorker)();
+            worker.addEventListener('message', (event) => settle(event.data));
+            worker.addEventListener('error', fallBack);
+        }
+    }
+    catch {
+        worker = null;
+    }
+    if (!worker)
+        local = createSpatialHandler();
+    const send = (request) => {
+        if (request.type === 'load')
+            lastLoad = request;
+        const id = nextId++;
+        if (!worker) {
+            const response = local({ ...request, id });
+            return response.ok
+                ? Promise.resolve(response.result)
+                : Promise.reject(new Error(response.error));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error(`Spatial worker: "${request.type}" took longer than ${timeout} ms`));
+            }, timeout);
+            pending.set(id, { request, resolve: resolve, reject, timer });
+            worker.postMessage({ ...request, id });
+        });
+    };
+    return {
+        get mode() {
+            return worker ? 'worker' : 'main-thread';
+        },
+        load: (features, { idProperty } = {}) => send({ type: 'load', features, idProperty }),
+        search: (bounds, limit) => send({ type: 'search', bounds, limit }),
+        nearest: (point, count) => send({ type: 'nearest', point, count }),
+        simplify: (zoom, pixels) => send({ type: 'simplify', zoom, pixels }),
+        terminate() {
+            worker?.terminate();
+            worker = null;
+            for (const [id, entry] of pending) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error('Spatial worker terminated'));
+                pending.delete(id);
+            }
+            local ??= createSpatialHandler();
+        },
+    };
+}

package/dist/core/workers/handler.d.ts

@@ -0,0 +1,6 @@
+import type { SpatialRequest, SpatialResponse } from './protocol.js';
+/**
+ * Answers spatial requests. The worker runs this; so does the client itself, on the main thread,
+ * wherever a worker cannot start — the answers are the same either way.
+ */
+export declare function createSpatialHandler(): (request: SpatialRequest) => SpatialResponse;

package/dist/core/workers/handler.js

@@ -0,0 +1,53 @@
+import { createLevelOfDetail } from '../lod.js';
+import { createSpatialIndex } from '../spatial.js';
+/**
+ * Answers spatial requests. The worker runs this; so does the client itself, on the main thread,
+ * wherever a worker cannot start — the answers are the same either way.
+ */
+export function createSpatialHandler() {
+    let index = createSpatialIndex();
+    let collection = { type: 'FeatureCollection', features: [] };
+    let detail = null;
+    return (request) => {
+        try {
+            switch (request.type) {
+                case 'load': {
+                    const property = request.idProperty;
+                    index = createSpatialIndex({
+                        getId: property
+                            ? (feature, position) => feature.properties?.[property] ?? position
+                            : undefined,
+                    });
+                    index.load(request.features);
+                    collection = request.features;
+                    detail = null;
+                    return { id: request.id, ok: true, result: index.size };
+                }
+                case 'search':
+                    return {
+                        id: request.id,
+                        ok: true,
+                        result: index.search(request.bounds, { limit: request.limit }),
+                    };
+                case 'nearest':
+                    return { id: request.id, ok: true, result: index.nearest(request.point, request.count) };
+                case 'simplify':
+                    detail ??= createLevelOfDetail(collection, { pixels: request.pixels });
+                    return { id: request.id, ok: true, result: detail.at(request.zoom) };
+                default:
+                    return {
+                        id: request.id,
+                        ok: false,
+                        error: `Unknown request "${request.type}"`,
+                    };
+            }
+        }
+        catch (error) {
+            return {
+                id: request.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+}

package/dist/core/workers/protocol.d.ts

@@ -0,0 +1,32 @@
+import type { FeatureCollection, LngLat, LngLatBounds } from '../types.js';
+/** What the spatial worker can be asked. */
+export type SpatialRequest = {
+    id: number;
+    type: 'load';
+    features: FeatureCollection;
+    idProperty?: string;
+} | {
+    id: number;
+    type: 'search';
+    bounds: LngLatBounds;
+    limit?: number;
+} | {
+    id: number;
+    type: 'nearest';
+    point: LngLat;
+    count?: number;
+} | {
+    id: number;
+    type: 'simplify';
+    zoom: number;
+    pixels?: number;
+};
+export type SpatialResponse = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};

package/dist/core/workers/protocol.js

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

package/dist/core/workers/spatial.worker.d.ts

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

package/dist/core/workers/spatial.worker.js

@@ -0,0 +1,12 @@
+/*
+ * The spatial worker. It only relays messages to the same handler the client can run itself —
+ * all the logic lives in `handler.ts`, where it can be tested without a worker.
+ *
+ * Bundlers that pre-bundle dependencies can lose the worker URL the client computes; import
+ * this file through the bundler instead (`@loidolt/theme-maps/spatial.worker?worker` with Vite)
+ * and pass it as `workerFactory`.
+ */
+import { createSpatialHandler } from './handler.js';
+const handle = createSpatialHandler();
+const scope = self;
+scope.onmessage = (event) => scope.postMessage(handle(event.data));

package/dist/deck.d.ts

@@ -0,0 +1,18 @@
+/** The slice of `@deck.gl/mapbox`'s `MapboxOverlay` that `DeckOverlay` uses. */
+export interface DeckOverlayInstance {
+    setProps(props: Record<string, unknown>): void;
+    onAdd?(map: unknown): HTMLElement;
+    onRemove?(map: unknown): void;
+    finalize?(): void;
+}
+export interface DeckModule {
+    MapboxOverlay: new (props: Record<string, unknown>) => DeckOverlayInstance;
+}
+export type DeckLoader = () => Promise<unknown> | unknown;
+/** Registers how to load `@deck.gl/mapbox`. `null` unregisters. */
+export declare function setDeckLoader(loader: DeckLoader | null): void;
+/**
+ * Resolves `@deck.gl/mapbox` through the registered loader, else a global `deck` from a script
+ * tag. Resolves `null` rather than rejecting when neither is there.
+ */
+export declare function loadDeck(): Promise<DeckModule | null>;

package/dist/deck.js

@@ -0,0 +1,27 @@
+/*
+ * deck.gl, for large-data visualisation over the map. An optional peer this package never
+ * imports itself; register it once where you use it:
+ *
+ *   import { setDeckLoader } from '@loidolt/theme-maps';
+ *   setDeckLoader(() => import('@deck.gl/mapbox'));
+ */
+let registered = null;
+let cached = null;
+/** Registers how to load `@deck.gl/mapbox`. `null` unregisters. */
+export function setDeckLoader(loader) {
+    registered = loader;
+    cached = null;
+}
+/**
+ * Resolves `@deck.gl/mapbox` through the registered loader, else a global `deck` from a script
+ * tag. Resolves `null` rather than rejecting when neither is there.
+ */
+export function loadDeck() {
+    cached ??= Promise.resolve()
+        .then(registered ?? (() => globalThis.deck))
+        .then((module) => typeof module?.MapboxOverlay === 'function'
+        ? module
+        : null)
+        .catch(() => null);
+    return cached;
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { default as BasemapSwitcher } from './components/BasemapSwitcher.svelte';
+export { default as CircleLayer } from './components/CircleLayer.svelte';
+export { default as CoordinateDisplay } from './components/CoordinateDisplay.svelte';
+export { default as DeckOverlay } from './components/DeckOverlay.svelte';
+export { default as FillExtrusionLayer } from './components/FillExtrusionLayer.svelte';
+export { default as FillLayer } from './components/FillLayer.svelte';
+export { default as HeatmapLayer } from './components/HeatmapLayer.svelte';
+export { default as LayerManager } from './components/LayerManager.svelte';
+export { default as LineLayer } from './components/LineLayer.svelte';
+export { default as MapControl } from './components/MapControl.svelte';
+export { default as MapFeatureList } from './components/MapFeatureList.svelte';
+export { default as MapLegend } from './components/MapLegend.svelte';
+export { default as MapLegendGroup } from './components/MapLegendGroup.svelte';
+export { default as MapMarker } from './components/MapMarker.svelte';
+export { default as MapPopup } from './components/MapPopup.svelte';
+export { default as MapSource } from './components/MapSource.svelte';
+export { default as MapView } from './components/MapView.svelte';
+export { default as RasterLayer } from './components/RasterLayer.svelte';
+export { default as SymbolLayer } from './components/SymbolLayer.svelte';
+export { loadMapLibre, setMapLibreLoader, setMapLibreWorkerUrl } from './maplibre.js';
+export type { MapLibreLoader, MapLibreModule } from './maplibre.js';
+export { loadDeck, setDeckLoader } from './deck.js';
+export type { DeckLoader, DeckModule, DeckOverlayInstance } from './deck.js';
+export { getMapContext } from './internal/context.js';
+export type { LayerEntry, MapContext } from './internal/context.js';
+export type { LayerPaint, LayerProps } from './internal/use-layer.svelte.js';
+export * from './core/index.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+export { default as BasemapSwitcher } from './components/BasemapSwitcher.svelte';
+export { default as CircleLayer } from './components/CircleLayer.svelte';
+export { default as CoordinateDisplay } from './components/CoordinateDisplay.svelte';
+export { default as DeckOverlay } from './components/DeckOverlay.svelte';
+export { default as FillExtrusionLayer } from './components/FillExtrusionLayer.svelte';
+export { default as FillLayer } from './components/FillLayer.svelte';
+export { default as HeatmapLayer } from './components/HeatmapLayer.svelte';
+export { default as LayerManager } from './components/LayerManager.svelte';
+export { default as LineLayer } from './components/LineLayer.svelte';
+export { default as MapControl } from './components/MapControl.svelte';
+export { default as MapFeatureList } from './components/MapFeatureList.svelte';
+export { default as MapLegend } from './components/MapLegend.svelte';
+export { default as MapLegendGroup } from './components/MapLegendGroup.svelte';
+export { default as MapMarker } from './components/MapMarker.svelte';
+export { default as MapPopup } from './components/MapPopup.svelte';
+export { default as MapSource } from './components/MapSource.svelte';
+export { default as MapView } from './components/MapView.svelte';
+export { default as RasterLayer } from './components/RasterLayer.svelte';
+export { default as SymbolLayer } from './components/SymbolLayer.svelte';
+export { loadMapLibre, setMapLibreLoader, setMapLibreWorkerUrl } from './maplibre.js';
+export { loadDeck, setDeckLoader } from './deck.js';
+export { getMapContext } from './internal/context.js';
+export * from './core/index.js';

package/dist/internal/context.d.ts

@@ -0,0 +1,39 @@
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { MapColors } from '@loidolt/theme-tokens';
+import type { StyleSpecification } from '../core/types.js';
+import type { MapLibreModule } from '../maplibre.js';
+/** A layer as the map knows it — what `LayerManager` lists. */
+export interface LayerEntry {
+    id: string;
+    label: string;
+    type: string;
+}
+export interface MapContext {
+    readonly map: MapLibreMap | null;
+    readonly lib: MapLibreModule | null;
+    /** The style has loaded, so sources and layers can be added. */
+    readonly loaded: boolean;
+    /** Goes up whenever a style (re)loads; everything on the map re-adds itself then. */
+    readonly styleVersion: number;
+    readonly colors: MapColors;
+    /** Goes up whenever `colors` changes. */
+    readonly colorVersion: number;
+    readonly reducedMotion: boolean;
+    /** Which basemap is showing: `default`, `blank`, or the id of one passed to the switcher. */
+    readonly basemap: string;
+    setBasemap(id: string, style?: string | StyleSpecification): void;
+    readonly layers: LayerEntry[];
+    registerLayer(entry: LayerEntry): () => void;
+}
+export interface SourceContext {
+    readonly id: string;
+    /** The source exists on the current style. */
+    readonly ready: boolean;
+}
+export declare const setMapContext: (context: MapContext) => MapContext;
+/** The enclosing map, or `null` outside one. */
+export declare const getMapContext: () => MapContext | null;
+/** The enclosing map; throws with a clear message outside one. */
+export declare function requireMapContext(component: string): MapContext;
+export declare const setSourceContext: (context: SourceContext) => SourceContext;
+export declare const getSourceContext: () => SourceContext | null;

package/dist/internal/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const MAP = Symbol('loidolt-map');
+const SOURCE = Symbol('loidolt-map-source');
+export const setMapContext = (context) => setContext(MAP, context);
+/** The enclosing map, or `null` outside one. */
+export const getMapContext = () => getContext(MAP) ?? null;
+/** The enclosing map; throws with a clear message outside one. */
+export function requireMapContext(component) {
+    const context = getMapContext();
+    if (!context)
+        throw new Error(`${component} must be placed inside a <MapView>.`);
+    return context;
+}
+export const setSourceContext = (context) => setContext(SOURCE, context);
+export const getSourceContext = () => getContext(SOURCE) ?? null;

package/dist/internal/safely.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs a teardown step that may find the map already gone. When a `MapView` unmounts, its map
+ * can be removed before its children clean up, and MapLibre throws on a removed map.
+ */
+export declare function safely(step: () => void): void;

package/dist/internal/safely.js

@@ -0,0 +1,12 @@
+/**
+ * Runs a teardown step that may find the map already gone. When a `MapView` unmounts, its map
+ * can be removed before its children clean up, and MapLibre throws on a removed map.
+ */
+export function safely(step) {
+    try {
+        step();
+    }
+    catch {
+        /* the map was removed first; there is nothing left to undo */
+    }
+}

package/dist/internal/use-layer.svelte.d.ts

@@ -0,0 +1,45 @@
+import type { MapColors } from '@loidolt/theme-tokens';
+import type { LayerFeatureEvent } from '../core/types.js';
+export type LayerPaint = Record<string, unknown>;
+/** What every layer component accepts. */
+export interface LayerProps {
+    /** Unique on the map. */
+    id: string;
+    /** The source to draw from. Defaults to the enclosing `MapSource`. */
+    source?: string;
+    /** For vector tiles: which layer of the tiles to draw. */
+    sourceLayer?: string;
+    /** Draw beneath this layer rather than on top of everything. */
+    beforeId?: string;
+    /** A MapLibre filter expression. */
+    filter?: unknown[];
+    minZoom?: number;
+    maxZoom?: number;
+    visible?: boolean;
+    /**
+     * MapLibre paint properties, merged over this layer type's themed defaults. Pass a function
+     * of the theme colours to have them follow light and dark.
+     */
+    paint?: LayerPaint | ((colors: MapColors) => LayerPaint);
+    /** MapLibre layout properties. */
+    layout?: Record<string, unknown>;
+    /** Names the layer in `LayerManager`. Defaults to `id`. */
+    label?: string;
+    /** A click on a feature of this layer. */
+    onClick?: (event: LayerFeatureEvent) => void;
+    /** The pointer entering a feature of this layer, or `null` as it leaves. */
+    onHover?: (event: LayerFeatureEvent | null) => void;
+}
+type Defaults = (colors: MapColors) => {
+    paint?: LayerPaint;
+    layout?: Record<string, unknown>;
+};
+/**
+ * Adds a layer of `type` to the enclosing map and keeps it in step with its props: added on
+ * every style load, diffed on every change (only what changed is sent), recoloured on a theme
+ * change, removed on unmount.
+ */
+export declare function useLayer(type: string, props: () => LayerProps, defaults?: Defaults): {
+    readonly added: boolean;
+};
+export {};