@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/utils/event-emitter.d.ts

@@ -0,0 +1,262 @@
+/**
+ * EventEmitter
+ *
+ * The component that notifies the outside of state changes.
+ * Events can be subscribed to in a form such as draw.on('feature.create', ...).
+ */
+import type { DatasetClickEventPayload, MapClickEventPayload, RenderSlot, SnapResult } from '../types/events.js';
+import type { Feature, Group, Layer, Metadata, Mode, SelectionType, UpdateSource } from '../types/model.js';
+/**
+ * Names of the editing operations of draw.geometry
+ */
+export type GeometryOperationName = 'union' | 'subtract' | 'intersect' | 'buffer' | 'split';
+/**
+ * Notification emitted when a geometric operation has been applied
+ *
+ * status expresses the outcome of the operation. 'applied' means that a result feature was
+ * created; 'empty' means that the operation itself succeeded but the result had no area (an
+ * intersection that does not overlap, a subtraction where everything was taken away, a buffer
+ * where every input became empty, a split that did not divide the polygon). When it is
+ * 'empty', the inputs are not modified at all and resultIds is empty.
+ *
+ * The result of the boolean editing operations (union / subtract / intersect) is always a
+ * single one, so the length of resultIds is at most 1. A buffer creates a result per input, so
+ * there can be several. A split produces two or more results. resultId is the first element of
+ * resultIds (null when it is empty), a shorthand for subscribers that only deal with
+ * operations producing a single result.
+ *
+ * The inputIds of a split are in the order [the polygon being cut, the line that cuts] (the
+ * line is an input of the operation but remains without being removed).
+ */
+export interface GeometryAppliedPayload {
+    /** Name of the operation */
+    operation: GeometryOperationName;
+    /** IDs of the input features (in z order; the last one is in the foreground) */
+    inputIds: string[];
+    /** ID of the result feature. null when the result is empty */
+    resultId: string | null;
+    /** IDs of the result features (in z order). An empty array when the result is empty */
+    resultIds: string[];
+    /** Outcome of the operation */
+    status: 'applied' | 'empty';
+}
+/**
+ * Every feature change of one store flush (one transaction, or one mutation outside a
+ * transaction)
+ *
+ * It is emitted once per flush that changes features, after the per-feature events of the
+ * same flush, and carries all of them. A subscriber that rebuilds a view on any change
+ * subscribes to this instead of the per-feature events, so a bulk load of N features costs
+ * one rebuild rather than N.
+ */
+export interface FeaturesChangePayload {
+    /** The features created */
+    created: Feature[];
+    /** The features updated, each with the feature before the update */
+    updated: {
+        feature: Feature;
+        previous: Feature;
+    }[];
+    /** The features deleted, as they were when they were deleted */
+    deleted: Feature[];
+    /**
+     * Source of the flush ('local', 'silent' or 'batch' from core, 'remote' from a replaced
+     * store, or a value of a plugin)
+     */
+    source: UpdateSource;
+}
+/**
+ * The events of a draw instance by their internal names, with their payloads
+ *
+ * A plugin subscribes to them with `on` of {@link PluginContext}. They are the events the host
+ * receives with `draw.on`, named without the `draw.` prefix: `feature.create` here is
+ * `draw.feature.create` there ({@link EventPayloads} describes each one).
+ */
+export interface EventMap {
+    /** A feature was created */
+    'feature.create': {
+        feature: Feature;
+    };
+    /** A feature was updated (with the feature before the update) */
+    'feature.update': {
+        feature: Feature;
+        previous: Feature;
+    };
+    /** A feature was deleted */
+    'feature.delete': {
+        feature: Feature;
+    };
+    /** Every feature change of one Store notification, after the per-feature events */
+    'features.change': FeaturesChangePayload;
+    /** The selection changed */
+    'selection.change': {
+        type: SelectionType | null;
+        ids: string[];
+        previousType: SelectionType | null;
+        previousIds: string[];
+    };
+    /** The mode changed */
+    'mode.change': {
+        mode: Mode;
+        previousMode: Mode;
+    };
+    /** A layer was created */
+    'layer.create': {
+        layer: Layer;
+    };
+    /** A layer was updated (with the layer before the update) */
+    'layer.update': {
+        layer: Layer;
+        previous: Layer;
+    };
+    /** A layer was deleted */
+    'layer.delete': {
+        layer: Layer;
+    };
+    /** The stacking order of the layers changed */
+    'layer.reorder': {
+        order: string[];
+        previous: string[];
+    };
+    /** A group was created */
+    'group.create': {
+        group: Group;
+    };
+    /** A group was updated (with the group before the update) */
+    'group.update': {
+        group: Group;
+        previous: Group;
+    };
+    /** A group was deleted */
+    'group.delete': {
+        group: Group;
+    };
+    /** The metadata of the document changed */
+    'metadata.change': {
+        metadata: Metadata;
+        previous: Metadata;
+    };
+    /** The image mode asks the host for an image file, to place at the carried position */
+    'image.request': {
+        coordinate: [number, number];
+        zoom: number;
+        layerId: string;
+    };
+    /** An operation of `draw.geometry` finished */
+    'geometry.applied': GeometryAppliedPayload;
+    /**
+     * Change of the snapping result
+     *
+     * Emitted when the snapping target changes (and, when snapping to an edge whose coordinates
+     * move, when the coordinates change). When snapping is lost, it is emitted once with no
+     * target.
+     */
+    'snap.change': SnapResult;
+    /**
+     * Resolution result of the click interception on datasets
+     *
+     * Emits on one channel whether a click in select mode hit a feature of a dataset
+     * (datasetId / feature are carried) or hit nothing (both are null).
+     * It is not emitted for a click that hit a feature of the Store.
+     */
+    'dataset.click': DatasetClickEventPayload;
+    /**
+     * A dataset was added
+     *
+     * Emitted by `addDataset` once the dataset is listed, so a handler can get it
+     * by its id. A plugin that follows every dataset (to subscribe to its `change`)
+     * subscribes to this and to `dataset.remove`, and lists the datasets that already exist
+     * once when it is installed.
+     */
+    'dataset.add': {
+        datasetId: string;
+    };
+    /**
+     * A dataset was removed
+     *
+     * Emitted by `removeDataset` and by the `remove` of the dataset, once it is no
+     * longer listed. It is not emitted when the draw instance is destroyed. A dataset added
+     * again under the same id is a new object, announced by a new `dataset.add`.
+     */
+    'dataset.remove': {
+        datasetId: string;
+    };
+    /**
+     * The order of the datasets changed
+     *
+     * Emitted by `moveDataset` when it moved a dataset within its side or to
+     * another side. `order` is the ids in display order, from the back to the front (the same
+     * as `getDatasets`). A move that leaves everything where it was emits nothing, and
+     * adding or removing a dataset emits `dataset.add` or `dataset.remove` instead.
+     */
+    'dataset.reorder': {
+        order: string[];
+    };
+    /**
+     * Map click in select mode
+     *
+     * Emits the normalized click as is on one channel, regardless of whether anything was hit
+     * and of what was hit (the coordinates are before snapping). It is for read-only
+     * subscription and does not affect the selection behavior of the modes. It is used by
+     * callers that need "a click anywhere on the map".
+     */
+    'map.click': MapClickEventPayload;
+    /**
+     * Addition or removal of frames (the CustomLayer per interval) and changes of the intervals
+     *
+     * On receiving this, the host re-places the native layers that correspond to the separators
+     * between the frames (it carries the same content as getRenderSlots).
+     */
+    'renderslots.change': {
+        slots: RenderSlot[];
+    };
+    /**
+     * Failure of an asynchronous load that no call returns
+     *
+     * `image`: the image of an Image feature could not be decoded (`featureId`). It is emitted
+     * once per feature and image, the decode is not retried, and the feature is drawn without
+     * its image. The error is the one that was thrown.
+     */
+    'load.error': LoadErrorPayload;
+}
+/**
+ * The payload of the load.error event
+ */
+export interface LoadErrorPayload {
+    /** Where the load was: the image of an Image feature */
+    source: 'image';
+    /** The Image feature whose image failed */
+    featureId: string;
+    /** What was thrown */
+    error: unknown;
+}
+/**
+ * Event listener type
+ */
+export type EventListener<K extends keyof EventMap> = (data: EventMap[K]) => void;
+/**
+ * EventEmitter interface
+ */
+export interface EventEmitter {
+    /**
+     * Registers an event listener
+     */
+    on<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
+    /**
+     * Unregisters an event listener
+     */
+    off<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
+    /**
+     * Emits an event
+     */
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+}
+/**
+ * EventEmitter implementation
+ */
+export declare class EventEmitterImpl implements EventEmitter {
+    private listeners;
+    on<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
+    off<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+}

package/dist/shared/utils/event-emitter.js

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * EventEmitter implementation
+ */
+export class EventEmitterImpl {
+    constructor() {
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    off(event, listener) {
+        const set = this.listeners.get(event);
+        if (set) {
+            set.delete(listener);
+        }
+    }
+    emit(event, data) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        // Take a snapshot so that listeners being added or removed during emit has no effect,
+        // and isolate each one individually so that an exception from a single listener does not
+        // drag in the following listeners or the internal processing of the Core (EventBridge and
+        // so on).
+        for (const listener of [...set]) {
+            try {
+                listener(data);
+            }
+            catch (error) {
+                console.error(`Error in event listener for "${String(event)}":`, error);
+            }
+        }
+    }
+}

package/dist/shared/utils/feature-bbox.d.ts

@@ -0,0 +1,8 @@
+import type { BoundingBox, Feature } from '../types/model.js';
+/**
+ * A utility function that computes a bounding box (for public use)
+ *
+ * @param feature the feature
+ * @param tileSize the tile size (512 by default)
+ */
+export declare function getBoundingBox(feature: Feature, tileSize?: number): BoundingBox;

package/dist/shared/utils/feature-bbox.js

@@ -0,0 +1,207 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The bounding box of a feature
+ *
+ * A pure function of the feature (and the tile size for Image). The spatial index of the Store
+ * (store/spatial) and the datasets (display/) both use it.
+ */
+import { circleBoundingBox } from '../../geometry/circle.js';
+import { pixelsToDegreesLat, pixelsToDegreesLng, rotateCoordinateOnSphere } from '../math/index.js';
+import { forEachCoordinateDeep } from './coordinates.js';
+import { getCircleRadius, getCreatedZoom, getImageProperties } from './property.js';
+/**
+ * Computes the bounding box of a feature
+ *
+ * For an Image, the size at createdZoom is converted into geographic coordinates
+ */
+function computeBoundingBox(feature, tileSize) {
+    const { type, coordinates } = feature;
+    // For an Image
+    if (type === 'Image') {
+        const coord = coordinates;
+        const [lng, lat] = coord;
+        const props = getImageProperties(feature);
+        const style = feature.style;
+        const imageWidth = style?.width || props.imageWidth || 100;
+        const imageHeight = style?.height || props.imageHeight || 100;
+        const scale = props.scale ?? 1;
+        // createdZoom defaults to 14 when missing. getImageProperties().createdZoom returns 0 when
+        // missing, so ?? does not work; therefore getCreatedZoom(number|undefined) is used.
+        const createdZoom = getCreatedZoom(feature) ?? 14;
+        const rotation = props.rotation ?? 0;
+        const displayWidth = imageWidth * scale;
+        const displayHeight = imageHeight * scale;
+        // Convert the pixel size into degrees
+        const halfWidthDeg = pixelsToDegreesLng(displayWidth / 2, lat, createdZoom, tileSize);
+        const halfHeightDeg = pixelsToDegreesLat(displayHeight / 2, lat, createdZoom, tileSize);
+        // Compute the bounding box taking rotation into account
+        return computeRotatedBoundingBox(lng, lat, halfWidthDeg, halfHeightDeg, rotation);
+    }
+    // For a Circle
+    if (type === 'Circle') {
+        const coord = coordinates;
+        const [lng, lat] = coord;
+        const radiusMeters = getCircleRadius(feature);
+        if (!radiusMeters || radiusMeters <= 0) {
+            return { minX: lng, minY: lat, maxX: lng, maxY: lat };
+        }
+        // The extent of the geodesic circle as it is drawn (a circle over a pole spans every
+        // longitude up to the pole)
+        const extent = circleBoundingBox(coord, radiusMeters);
+        if (!extent) {
+            return { minX: lng, minY: lat, maxX: lng, maxY: lat };
+        }
+        const [minX, minY, maxX, maxY] = extent;
+        return { minX, minY, maxX, maxY };
+    }
+    // For Point, LineString, Polygon, Freehand and the Multi types
+    return computeCoordinateBoundingBox(feature);
+}
+/** The bounding box for empty or unreadable coordinates (the origin) */
+const EMPTY_BOUNDING_BOX = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+/**
+ * A cache of AABBs determined by the coordinates alone (the key is the coordinate array
+ * reference)
+ *
+ * Premise: coordinate arrays are never rewritten in place (updating coordinates in the Store
+ * follows the immutable-update convention of swapping in a new array, both in the core memory
+ * implementation and in external store implementations). Therefore the cache stays valid as
+ * long as the array reference is the same, and when the coordinates change the key changes so
+ * the entry is naturally rebuilt and the old value is reclaimed by the GC. For that reason
+ * there is no invalidation logic (the same pattern as the segment grid and the snapping index
+ * of hit testing).
+ *
+ * Image / Circle / custom calculators also depend on things other than the coordinates (size,
+ * rotation, radius, tile size), so they are not cached. Point is a single vertex and has no
+ * traversal cost, so it is not cached either.
+ */
+const coordinateBoundingBoxCache = new WeakMap();
+/**
+ * Computes the bounding box determined by the coordinates alone (with caching)
+ *
+ * For a selected feature on the order of 100,000 vertices this is called every frame, so on a
+ * cache hit it does not traverse and only returns a copy of the value.
+ */
+function computeCoordinateBoundingBox(feature) {
+    const { type, coordinates } = feature;
+    if (type === 'Point') {
+        const [lng, lat] = coordinates;
+        return { minX: lng, minY: lat, maxX: lng, maxY: lat };
+    }
+    // Every other type (the built-in line and area types, and a custom type without its own
+    // bounding box calculator) is measured by the extent of its coordinates
+    if (!Array.isArray(coordinates)) {
+        return { ...EMPTY_BOUNDING_BOX };
+    }
+    const cached = coordinateBoundingBoxCache.get(coordinates);
+    if (cached) {
+        // Return a new object every time so that the cache is not polluted if the caller mutates it
+        return { ...cached };
+    }
+    const bbox = computeCoordinateBoundingBoxUncached(type, coordinates);
+    coordinateBoundingBoxCache.set(coordinates, bbox);
+    return { ...bbox };
+}
+/**
+ * Obtains the AABB by traversing the nested coordinates directly
+ *
+ * It takes the min and max without building an intermediate array (a flattened coordinate
+ * sequence).
+ */
+function computeCoordinateBoundingBoxUncached(type, coordinates) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let count = 0;
+    const visit = (coord) => {
+        const [cLng, cLat] = coord;
+        if (cLng < minX)
+            minX = cLng;
+        if (cLat < minY)
+            minY = cLat;
+        if (cLng > maxX)
+            maxX = cLng;
+        if (cLat > maxY)
+            maxY = cLat;
+        count++;
+    };
+    if (type === 'LineString' || type === 'Freehand') {
+        const coords = coordinates;
+        for (let i = 0; i < coords.length; i++) {
+            visit(coords[i]);
+        }
+    }
+    else if (type === 'Polygon') {
+        // A Polygon is an array of the outer ring and the inner rings (holes)
+        const rings = coordinates;
+        for (let r = 0; r < rings.length; r++) {
+            const ring = rings[r];
+            for (let i = 0; i < ring.length; i++) {
+                visit(ring[i]);
+            }
+        }
+    }
+    else {
+        // The Multi types have a nesting depth that differs per type, so a depth-independent
+        // traversal is used. The bounding box is simply the union of all the parts.
+        forEachCoordinateDeep(coordinates, visit);
+    }
+    if (count === 0) {
+        return { ...EMPTY_BOUNDING_BOX };
+    }
+    return { minX, minY, maxX, maxY };
+}
+/**
+ * Computes the bounding box taking rotation into account
+ *
+ * It rotates the four corners using a spherical rotation (Rodrigues' rotation formula) and
+ * computes the AABB (axis-aligned bounding box) from the rotated coordinates.
+ *
+ * @param centerLng the longitude of the center
+ * @param centerLat the latitude of the center
+ * @param halfWidthDeg the half width (in degrees)
+ * @param halfHeightDeg the half height (in degrees)
+ * @param rotationDeg the rotation angle (in degrees, counterclockwise)
+ * @returns the bounding box
+ */
+function computeRotatedBoundingBox(centerLng, centerLat, halfWidthDeg, halfHeightDeg, rotationDeg) {
+    // With no rotation, return a simple AABB
+    if (rotationDeg === 0) {
+        return {
+            minX: centerLng - halfWidthDeg,
+            minY: centerLat - halfHeightDeg,
+            maxX: centerLng + halfWidthDeg,
+            maxY: centerLat + halfHeightDeg,
+        };
+    }
+    const center = [centerLng, centerLat];
+    // The coordinates of the four corners before rotation
+    const corners = [
+        [centerLng - halfWidthDeg, centerLat + halfHeightDeg], // top-left (northwest)
+        [centerLng + halfWidthDeg, centerLat + halfHeightDeg], // top-right (northeast)
+        [centerLng - halfWidthDeg, centerLat - halfHeightDeg], // bottom-left (southwest)
+        [centerLng + halfWidthDeg, centerLat - halfHeightDeg], // bottom-right (southeast)
+    ];
+    // Apply the spherical rotation
+    const rotatedCorners = corners.map((coord) => rotateCoordinateOnSphere(coord, center, rotationDeg));
+    // Compute the AABB from the rotated coordinates
+    const lngs = rotatedCorners.map((c) => c[0]);
+    const lats = rotatedCorners.map((c) => c[1]);
+    return {
+        minX: Math.min(...lngs),
+        minY: Math.min(...lats),
+        maxX: Math.max(...lngs),
+        maxY: Math.max(...lats),
+    };
+}
+/**
+ * A utility function that computes a bounding box (for public use)
+ *
+ * @param feature the feature
+ * @param tileSize the tile size (512 by default)
+ */
+export function getBoundingBox(feature, tileSize = 512) {
+    return computeBoundingBox(feature, tileSize);
+}

package/dist/shared/utils/feature-segments.d.ts

@@ -0,0 +1,23 @@
+import type { BoundingBox, Coordinate, Feature } from '../types/model.js';
+/**
+ * Whether the feature type has edges (whether it is a target of edge snapping)
+ *
+ * It is aligned with the types that support vertex editing. Point has vertices only,
+ * and Circle / Image / Freehand are out of scope.
+ */
+export declare function hasSnapEdges(type: string): boolean;
+/**
+ * Whether the segment overlaps the bbox (a cheap preliminary test)
+ *
+ * The real test against the tolerance is done by SnapService using the distance to
+ * the nearest point, so all this guarantees is that nothing is missed.
+ */
+export declare function segmentIntersectsBBox(start: Coordinate, end: Coordinate, bbox: BoundingBox): boolean;
+/**
+ * Gathers only the edges of a feature that fall within the bbox
+ *
+ * The result is the same as applying a preliminary bbox filter to
+ * collectFeatureSegments; only for a huge part is the listing narrowed down with a
+ * segment grid index.
+ */
+export declare function collectFeatureSegmentsInBBox(feature: Feature, bbox: BoundingBox, visit: SegmentVisitor): void;