@sakuzu/maplibre-gl-draw 1.0.0

package/dist/display/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Display module
+ *
+ * Read-only layers that show large amounts of data (datasets). They are a
+ * path independent of the Store and do not go through the mechanisms of editing,
+ * undo or events.
+ *
+ * Only the symbols that src/index.ts publishes are listed here (see "The public
+ * surface" in CONTRIBUTING.md). Internal code imports from the defining file.
+ */
+export type { DatasetColumn, DatasetColumnarGeometry, DatasetColumnarGeometryType, DatasetColumnarInput, DatasetColumnarMixedGeometry, DatasetColumnarPrepared, DatasetDictionaryCodes, DatasetDictionaryColumn, } from './columnar/types.js';
+export type { DatasetCollisionThinning, DatasetThinningStats, ResolvedCollisionThinning, } from './thinning.js';
+export type { Dataset, DatasetBaseStyle, DatasetChangePayload, DatasetClickEventPayload, DatasetClickPayload, DatasetEventMap, DatasetFeatureInput, DatasetFeatureProvider, DatasetHoverPayload, DatasetOptions, DatasetOrder, DatasetPlacement, DatasetZoomScale, } from './types.js';

package/dist/display/index.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

package/dist/display/interaction.d.ts

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

package/dist/display/interaction.js

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Creates the interception
+ *
+ * @internal
+ */
+export function createDisplayInteractions(deps) {
+    const { manager, hitTestTopmost, notifyClick } = deps;
+    /** The dataset id and feature id being hovered */
+    let hoveredDatasetId = null;
+    let hoveredFeatureId = null;
+    function toCoordinate(event) {
+        return [event.lngLat.lng, event.lngLat.lat];
+    }
+    function clearHover(lngLat) {
+        if (hoveredDatasetId === null)
+            return;
+        const previous = manager.getInternal(hoveredDatasetId);
+        const datasetId = hoveredDatasetId;
+        hoveredDatasetId = null;
+        hoveredFeatureId = null;
+        // Report with feature: null that it left the target
+        previous?.emit('hover', { datasetId, feature: null, row: null, lngLat });
+    }
+    return {
+        handleClick(event) {
+            if (!manager.hasAny())
+                return;
+            const top = hitTestTopmost(event);
+            // Nothing happens when a feature of the Store is in front (that is the domain of the
+            // Store selection; neither the click of a dataset nor a no-hit notification is
+            // emitted). A companion of a feature (feature companion) is likewise the domain of the
+            // Store side, and the click is handed to the provider by the select mode.
+            if (top?.kind === 'store' || top?.kind === 'companion')
+                return;
+            const coordinate = toCoordinate(event);
+            if (top?.kind === 'dataset' && top.feature) {
+                // A feature of an interactive dataset was hit. Both the click of the dataset and
+                // the notification of the resolved result are emitted
+                const row = top.row ?? -1;
+                manager.getInternal(top.dataset.id)?.emit('click', {
+                    datasetId: top.dataset.id,
+                    feature: top.feature,
+                    row,
+                    lngLat: coordinate,
+                });
+                notifyClick?.({
+                    datasetId: top.dataset.id,
+                    feature: top.feature,
+                    row,
+                    lngLat: coordinate,
+                });
+                return;
+            }
+            // Nothing was there, or a non-interactive dataset merely blocked it: it is reported as
+            // a no-hit (the source of "click on empty space to deselect" on the host side)
+            notifyClick?.({ datasetId: null, feature: null, row: null, lngLat: coordinate });
+        },
+        handleMouseMove(event) {
+            const coordinate = toCoordinate(event);
+            if (!manager.hasAny()) {
+                clearHover(coordinate);
+                return;
+            }
+            const top = hitTestTopmost(event);
+            if (top?.kind !== 'dataset' || !top.feature) {
+                clearHover(coordinate);
+                return;
+            }
+            if (top.dataset.id === hoveredDatasetId && top.feature.id === hoveredFeatureId) {
+                // Nothing fires while the pointer only moves over the same feature
+                return;
+            }
+            clearHover(coordinate);
+            hoveredDatasetId = top.dataset.id;
+            hoveredFeatureId = top.feature.id;
+            manager.getInternal(top.dataset.id)?.emit('hover', {
+                datasetId: top.dataset.id,
+                feature: top.feature,
+                row: top.row ?? null,
+                lngLat: coordinate,
+            });
+        },
+        reset() {
+            hoveredDatasetId = null;
+            hoveredFeatureId = null;
+        },
+    };
+}

package/dist/display/manager.d.ts

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

package/dist/display/manager.js

@@ -0,0 +1,440 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { DatasetImpl } from './dataset.js';
+/**
+ * Default debounce time of the provider (ms)
+ *
+ * @internal
+ */
+export const DEFAULT_PROVIDER_DEBOUNCE_MS = 200;
+/**
+ * Manager of the datasets
+ *
+ * @internal
+ */
+export class DatasetManager {
+    constructor(deps) {
+        /** Index by id. The order is held by ordered */
+        Object.defineProperty(this, "datasets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /**
+         * The datasets in display order (from the back to the front)
+         *
+         * They are ordered as the below-store group, the layer-order group and the above-store group.
+         * Within each side, the later in the array, the more in front. The rendering, the hit testing
+         * and the listing all look only at this single sequence.
+         *
+         * Only the layer-order group is an exception: the order of this array does not decide their
+         * stacking order (the truth of the order is the stacking order of the Store,
+         * `getLayerOrder()`, alone).
+         */
+        Object.defineProperty(this, "ordered", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "deps", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "unsubscribeViewport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "providerDebounceMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Set by destroy: nothing can be added afterwards (it would never be disposed) */
+        Object.defineProperty(this, "destroyed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        this.deps = deps;
+        this.providerDebounceMs = deps.providerDebounceMs ?? DEFAULT_PROVIDER_DEBOUNCE_MS;
+    }
+    /**
+     * Adds a dataset
+     *
+     * @throws after destroy (the dataset, its provider and its timers would never be
+     *   released)
+     */
+    add(options) {
+        if (this.destroyed) {
+            throw new Error('Cannot add a dataset to a destroyed draw instance');
+        }
+        if (this.datasets.has(options.id)) {
+            throw new Error(`Dataset "${options.id}" already exists`);
+        }
+        const dataset = new DatasetImpl(options, {
+            requestRepaint: () => this.deps.requestRepaint(),
+            providerDebounceMs: this.providerDebounceMs,
+            pixelRatio: this.deps.pixelRatio,
+            triangulationScheduler: this.deps.triangulationScheduler,
+            pointStyle: this.deps.featureStyle?.point.point,
+            timeSlicing: this.deps.timeSlicing,
+            getZoom: () => this.deps.getZoom(),
+            getViewportState: () => ({
+                bounds: this.deps.getViewportBounds(),
+                zoom: this.deps.getZoom(),
+            }),
+            getPitchZoomDrop: () => {
+                const effective = this.deps.getEffectiveZoom?.();
+                if (effective === undefined || !Number.isFinite(effective))
+                    return 0;
+                const drop = this.deps.getZoom() - effective;
+                return drop > 0 ? drop : 0;
+            },
+            onRemove: (id) => {
+                this.datasets.delete(id);
+                const at = this.ordered.findIndex((c) => c.id === id);
+                if (at >= 0)
+                    this.ordered.splice(at, 1);
+                this.syncViewportSubscription();
+                this.deps.onDatasetRemove?.(id);
+            },
+        });
+        this.datasets.set(options.id, dataset);
+        // What is added goes to the front of its own side
+        this.ordered.splice(this.sideEnd(dataset.order), 0, dataset);
+        this.syncViewportSubscription();
+        if (dataset.hasProvider) {
+            // The first time is fetched through the same path as a change of the displayed range (the
+            // debounce)
+            dataset.scheduleProviderUpdate(this.deps.getViewportBounds(), this.deps.getZoom());
+        }
+        this.deps.requestRepaint();
+        this.deps.onDatasetAdd?.(options.id);
+        return dataset;
+    }
+    /**
+     * Gets a dataset
+     */
+    get(id) {
+        return this.datasets.get(id);
+    }
+    /**
+     * Gets the internal implementation of a dataset
+     *
+     * It is used by the internal paths (the interception of the hit testing) that perform
+     * operations not exposed on the public interface, such as firing an event.
+     */
+    getInternal(id) {
+        return this.datasets.get(id);
+    }
+    /**
+     * Removes a dataset
+     *
+     * Even with order 'layer-order', the stacking order of the Store is not touched (the manager
+     * does not know the Store). Taking the id off the order is the responsibility of the caller.
+     * Even if it stays on the order, an id without a dataset is skipped by both the rendering
+     * and the hit testing.
+     *
+     * @returns true when it was removed (false when it does not exist)
+     */
+    remove(id) {
+        const dataset = this.datasets.get(id);
+        if (!dataset)
+            return false;
+        dataset.remove();
+        return true;
+    }
+    /**
+     * Reorders a dataset
+     *
+     * The side (in front of or behind the Store, or taking part in the stacking order) and the
+     * position within that side can be changed. Only the order is moved; the visibility, the
+     * retained batches held and the state of the provider are not touched at all (no GPU resource
+     * is rebuilt).
+     *
+     * When it is moved to 'layer-order', the stacking order is decided by the stacking order of
+     * the Store alone (index takes no part in it). Putting the id on the order is the
+     * responsibility of the caller.
+     *
+     * @returns true when it was moved (false for an id that does not exist)
+     */
+    move(id, placement) {
+        const dataset = this.datasets.get(id);
+        if (!dataset)
+            return false;
+        const from = dataset.order;
+        const to = placement.order ?? from;
+        // Take it out of its current position first, then decide its position within the destination
+        const at = this.ordered.indexOf(dataset);
+        if (at >= 0)
+            this.ordered.splice(at, 1);
+        const start = this.sideStart(to);
+        const length = this.sideEnd(to) - start;
+        const index = placement.index === undefined ? (to === from ? at - start : length) : placement.index;
+        const moved = start + clamp(index, 0, length);
+        dataset.setOrder(to);
+        this.ordered.splice(moved, 0, dataset);
+        if (to === from && moved === at)
+            return true;
+        this.deps.requestRepaint();
+        this.deps.onDatasetsReorder?.(this.ordered.map((c) => c.id));
+        return true;
+    }
+    /**
+     * The list of datasets in display order (from the back to the front)
+     *
+     * They are returned as the below-store group, the layer-order group and the above-store group.
+     * The actual stacking order of a layer-order dataset is decided by the stacking order of the
+     * Store, so it does not match the order of this list.
+     */
+    list() {
+        return [...this.ordered];
+    }
+    /**
+     * The internal implementations of the datasets in display order (from the back to the front)
+     *
+     * The element supply of the analytic drape uses it. The truth of the stacking order is the
+     * stacking order of the Store, so this list exists to pass on "the classification into sides"
+     * and "the order within the same side".
+     */
+    listInternal() {
+        return [...this.ordered];
+    }
+    /**
+     * Reports the datasets that hand their polygons and lines to the analytic drape
+     *
+     * A dataset that handed them over does not push solid polygons and lines onto its retained
+     * batch (so that the same thing is not drawn twice). Passing null makes every dataset draw
+     * them itself as before.
+     */
+    setDrapedDatasets(ids) {
+        for (const dataset of this.datasets.values()) {
+            dataset.setDrapedFills(ids?.has(dataset.id) === true);
+        }
+    }
+    /**
+     * Whether there is at least one dataset (the hidden ones are not counted)
+     *
+     * The interception of the hit testing and the unified z scan only work while this is true. It
+     * is the short circuit that keeps a map without datasets from paying a cost on every
+     * mousemove.
+     */
+    hasAny() {
+        for (const dataset of this.datasets.values()) {
+            if (dataset.visible)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Starts a frame, before anything of it is drawn
+     *
+     * Each dataset decides the zoom band of its collision thinning from the zoom the frame draws
+     * with, so every layer of the frame reads the rows the frame draws.
+     *
+     * @param zoom The zoom the frame draws with
+     */
+    beginFrame(zoom) {
+        for (const dataset of this.ordered)
+            dataset.beginFrame(zoom);
+    }
+    /**
+     * Whether work remains that will change what the datasets draw without the host doing anything:
+     * a chunk the most recent frame left unbuilt, a huge polygon still being triangulated, or a
+     * call of a provider waiting for its debounce or its response
+     */
+    hasPendingWork() {
+        if ((this.deps.triangulationScheduler?.pendingCount ?? 0) > 0)
+            return true;
+        for (const dataset of this.ordered) {
+            if (dataset.hasPendingWork)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Draws the datasets of the given side in display order (from the back to the front)
+     *
+     * The 'layer-order' side is not drawn on this path (it is drawn from `drawOne` at its position
+     * within the stacking order).
+     *
+     * @param bounds The bbox of the expanded viewport that the rendering loop computed once.
+     *   When omitted it is looked up from deps at the point it becomes necessary
+     */
+    draw(order, target, projectionData, zoom, bounds) {
+        if (this.ordered.length === 0)
+            return;
+        let resolved = bounds;
+        for (let i = this.sideStart(order); i < this.sideEnd(order); i++) {
+            if (resolved === undefined)
+                resolved = this.deps.getViewportBounds();
+            this.ordered[i].draw(target, projectionData, zoom, resolved);
+        }
+    }
+    /**
+     * Draws a dataset as one entry of the stacking order
+     *
+     * Only a dataset whose order is 'layer-order' is drawn. Nothing happens for an id that does
+     * not exist or for a dataset on another side (the rendering loop skips that entry).
+     *
+     * @returns true when it was a drawing target
+     */
+    drawOne(id, target, projectionData, zoom, bounds) {
+        const dataset = this.datasets.get(id);
+        if (dataset?.order !== 'layer-order')
+            return false;
+        dataset.draw(target, projectionData, zoom, bounds ?? this.deps.getViewportBounds());
+        return true;
+    }
+    /**
+     * Returns the frontmost hit of the given side
+     *
+     * It looks through the side from the back (the front) onwards. A hidden dataset is skipped,
+     * but a dataset that is not interactive is not skipped (everything visible blocks). A
+     * dataset that cannot fire an event is returned with feature set to null.
+     */
+    hitTestSide(order, coordinate, toleranceLngLat, test) {
+        for (let i = this.sideEnd(order) - 1; i >= this.sideStart(order); i--) {
+            const hit = this.hitTestDataset(this.ordered[i], coordinate, toleranceLngLat, test);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    /**
+     * Returns the hit as one entry of the stacking order
+     *
+     * Only a dataset whose order is 'layer-order' is a target (an id that does not exist and a
+     * dataset on another side give null).
+     */
+    hitTestEntry(id, coordinate, toleranceLngLat, test) {
+        const dataset = this.datasets.get(id);
+        if (dataset?.order !== 'layer-order')
+            return null;
+        return this.hitTestDataset(dataset, coordinate, toleranceLngLat, test);
+    }
+    /**
+     * Decides the hit of a single dataset
+     */
+    hitTestDataset(dataset, coordinate, toleranceLngLat, test) {
+        if (!dataset.visible)
+            return null;
+        const hit = dataset.hitTestRow(coordinate, toleranceLngLat, test);
+        if (!hit)
+            return null;
+        // It blocks even when it is not interactive, but it cannot fire an event, so this is null
+        return dataset.interactive
+            ? { dataset, feature: hit.feature, row: hit.row }
+            : { dataset, feature: null, row: null };
+    }
+    /**
+     * The index of the start of a side (the range within the display order)
+     */
+    sideStart(order) {
+        if (order === 'below-store')
+            return 0;
+        const counts = this.sideCounts();
+        return order === 'layer-order' ? counts.below : counts.below + counts.layerOrder;
+    }
+    /**
+     * The index just past the end of a side
+     */
+    sideEnd(order) {
+        if (order === 'above-store')
+            return this.ordered.length;
+        const counts = this.sideCounts();
+        return order === 'below-store' ? counts.below : counts.below + counts.layerOrder;
+    }
+    /**
+     * The number of datasets of the first 2 sides (used to compute the boundaries of the sides)
+     */
+    sideCounts() {
+        let below = 0;
+        let layerOrder = 0;
+        for (const dataset of this.ordered) {
+            if (dataset.order === 'below-store')
+                below++;
+            else if (dataset.order === 'layer-order')
+                layerOrder++;
+        }
+        return { below, layerOrder };
+    }
+    /**
+     * Releases the retained-mode GPU resources of every dataset
+     *
+     * It is called when the rendering layer is disposed (the onRemove of CustomLayer). The
+     * datasets themselves remain, so they are built again on the next draw once the layer is
+     * recreated.
+     */
+    disposeRetained() {
+        for (const dataset of this.datasets.values()) {
+            dataset.disposeRetained();
+        }
+    }
+    /**
+     * Disposes every dataset
+     */
+    destroy() {
+        this.destroyed = true;
+        for (const dataset of [...this.datasets.values()]) {
+            dataset.dispose();
+        }
+        this.datasets.clear();
+        this.ordered = [];
+        this.syncViewportSubscription();
+    }
+    /**
+     * Rewires the subscription to the changes of the displayed range to whether any dataset
+     * needs them (the datasets that have a provider)
+     */
+    syncViewportSubscription() {
+        let needed = false;
+        for (const dataset of this.datasets.values()) {
+            if (dataset.needsViewportUpdates) {
+                needed = true;
+                break;
+            }
+        }
+        if (needed && !this.unsubscribeViewport) {
+            this.unsubscribeViewport = this.deps.onViewportChange(() => this.handleViewportChange());
+        }
+        else if (!needed && this.unsubscribeViewport) {
+            this.unsubscribeViewport();
+            this.unsubscribeViewport = null;
+        }
+    }
+    /** Schedules the call of the providers when the displayed range changed */
+    handleViewportChange() {
+        const bounds = this.deps.getViewportBounds();
+        const zoom = this.deps.getZoom();
+        for (const dataset of this.datasets.values()) {
+            if (dataset.hasProvider) {
+                dataset.scheduleProviderUpdate(bounds, zoom);
+            }
+        }
+    }
+}
+/**
+ * Clamps a value into a range
+ */
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}
+/**
+ * Creates a manager
+ *
+ * @internal
+ */
+export function createDatasetManager(deps) {
+    return new DatasetManager(deps);
+}

package/dist/display/packed-rtree.d.ts

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