@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/math/transform.js

@@ -0,0 +1,189 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { pixelsToDegreesLat, pixelsToDegreesLng } from './distance.js';
+/**
+ * Clamps a latitude into the valid range
+ *
+ * MapLibre's project() throws an error when the latitude is outside the range -90 to 90, and
+ * the latitude can fall outside that range, for example when a large image is placed at a low
+ * zoom level.
+ *
+ * @param latitude - The latitude to clamp (degrees)
+ * @returns The latitude clamped into the range -89.9 to 89.9
+ */
+export function clampLatitude(latitude) {
+    return Math.max(-89.9, Math.min(89.9, latitude));
+}
+/**
+ * Clamps the latitude of a coordinate into the valid range
+ *
+ * @param coord - The coordinate to clamp [lng, lat]
+ * @returns The coordinate with its latitude clamped
+ */
+export function clampCoordinate(coord) {
+    return [coord[0], clampLatitude(coord[1])];
+}
+/**
+ * Converts a longitude/latitude into a Mercator coordinate (in the range 0-1)
+ *
+ * @param coord Longitude/latitude coordinate [lng, lat]
+ * @returns Mercator coordinate [x, y] (in the range 0-1)
+ */
+export function lngLatToMercator(coord) {
+    const x = (coord[0] + 180) / 360;
+    const y = (1 -
+        Math.log(Math.tan((coord[1] * Math.PI) / 180) + 1 / Math.cos((coord[1] * Math.PI) / 180)) /
+            Math.PI) /
+        2;
+    return [x, y];
+}
+/**
+ * The injected anchor projection (per map)
+ *
+ * A single page can have several rendering instances (the screen + a thumbnail + a
+ * preview + printing), so holding just one globally would make hit testing use the frame of
+ * the instance that was created last. Keying by the map structurally rules out that mix-up.
+ */
+const anchorProjectors = new WeakMap();
+/**
+ * Injects an anchor projection (the view layer calls this per map; null removes it)
+ */
+export function setAnchorProjector(map, projector) {
+    if (projector)
+        anchorProjectors.set(map, projector);
+    else
+        anchorProjectors.delete(map);
+}
+/**
+ * Gets the anchor projection that is currently injected
+ */
+export function getAnchorProjector(map) {
+    return anchorProjectors.get(map) ?? null;
+}
+/**
+ * Creates a CoordinateTransform from a MapLibre map
+ *
+ * When terrain is enabled, project goes through the anchor projection (elevation included, one
+ * matrix pass). With terrain enabled, MapLibre's map.project internally raycasts against the
+ * terrain mesh, which measured at roughly 307μs per point (roughly 1μs without terrain). Hit
+ * testing calls project for every vertex, so editing would not hold up as is.
+ *
+ * unproject is called for only a single screen point (roughly 43μs), so MapLibre's is used as
+ * is. That is also because it has to solve the intersection with the terrain mesh by
+ * raycasting, which cannot be obtained from matrices alone.
+ *
+ * @param map MapLibre map instance
+ * @returns A CoordinateTransform instance
+ */
+export function createCoordinateTransform(map) {
+    return {
+        project: (coord) => {
+            const anchored = anchorProjectors.get(map)?.project(coord[0], coord[1]);
+            if (anchored)
+                return anchored;
+            const p = map.project([coord[0], coord[1]]);
+            return { x: p.x, y: p.y };
+        },
+        unproject: (point) => {
+            const ll = map.unproject([point.x, point.y]);
+            return { lng: ll.lng, lat: ll.lat };
+        },
+    };
+}
+/**
+ * Applies a margin in pixels to a bounding box
+ *
+ * When zoom is passed, the expansion is done on the map plane. When it is not passed, the
+ * expansion round-trips through screen coordinates. It must not round-trip when there is
+ * terrain: with terrain enabled, project projects a point at the height of the ground surface
+ * and unproject casts a ray from the screen onto the ground surface and comes back, so the
+ * round trip is no longer the identity mapping. With a tilted view, the returned values drift
+ * by kilometers, and the box appears far away from the feature, with a different shape too.
+ *
+ * @param coords Coordinates of the 4 corners of the bounding box
+ *   [topLeft, topRight, bottomRight, bottomLeft]
+ * @param margin Margin size (pixels)
+ * @param transform Coordinate transformation interface
+ * @param zoom Current zoom (when passed, the expansion is done on the map plane; required when
+ *   there is terrain)
+ * @returns Coordinates of the 4 corners after the margin is applied
+ */
+export function applyMarginToBoundingBox(coords, margin, transform, zoom) {
+    if (zoom !== undefined)
+        return marginOnMapPlane(coords, margin, zoom);
+    // Convert the 4 corners into screen coordinates (clamp the latitude to prevent
+    // out-of-range errors)
+    const corners = [
+        transform.project(clampCoordinate(coords.topLeft)),
+        transform.project(clampCoordinate(coords.topRight)),
+        transform.project(clampCoordinate(coords.bottomRight)),
+        transform.project(clampCoordinate(coords.bottomLeft)),
+    ];
+    // Compute the center of the OBB
+    const centerX = (corners[0].x + corners[1].x + corners[2].x + corners[3].x) / 4;
+    const centerY = (corners[0].y + corners[1].y + corners[2].y + corners[3].y) / 4;
+    // Expand each vertex outward from the center
+    const expandedCorners = corners.map((corner) => {
+        const dx = corner.x - centerX;
+        const dy = corner.y - centerY;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        if (dist === 0)
+            return corner;
+        // Extend by the margin while keeping the direction of the vector
+        const scale = (dist + margin) / dist;
+        return {
+            x: centerX + dx * scale,
+            y: centerY + dy * scale,
+        };
+    });
+    // Convert into geographic coordinates
+    const topLeftResult = transform.unproject(expandedCorners[0]);
+    const topRightResult = transform.unproject(expandedCorners[1]);
+    const bottomRightResult = transform.unproject(expandedCorners[2]);
+    const bottomLeftResult = transform.unproject(expandedCorners[3]);
+    return {
+        topLeft: [topLeftResult.lng, topLeftResult.lat],
+        topRight: [topRightResult.lng, topRightResult.lat],
+        bottomRight: [bottomRightResult.lng, bottomRightResult.lat],
+        bottomLeft: [bottomLeftResult.lng, bottomLeftResult.lat],
+    };
+}
+/**
+ * Widens the 4 corners outward from the center on the map plane
+ *
+ * It does not round-trip through screen coordinates, so it is affected by neither terrain nor
+ * tilt. How many degrees one pixel amounts to is derived from the latitude of the center and
+ * the current zoom.
+ */
+function marginOnMapPlane(coords, margin, zoom) {
+    const corners = [coords.topLeft, coords.topRight, coords.bottomRight, coords.bottomLeft];
+    const centerLng = (corners[0][0] + corners[1][0] + corners[2][0] + corners[3][0]) / 4;
+    const centerLat = (corners[0][1] + corners[1][1] + corners[2][1] + corners[3][1]) / 4;
+    const degPerPxLng = pixelsToDegreesLng(1, centerLat, zoom);
+    const degPerPxLat = pixelsToDegreesLat(1, centerLat, zoom);
+    if (!(degPerPxLng > 0) || !(degPerPxLat > 0)) {
+        return {
+            topLeft: coords.topLeft,
+            topRight: coords.topRight,
+            bottomRight: coords.bottomRight,
+            bottomLeft: coords.bottomLeft,
+        };
+    }
+    // The vertical and horizontal scales differ, so convert into pixel-equivalent amounts
+    // first and then widen
+    const expanded = corners.map(([lng, lat]) => {
+        const dx = (lng - centerLng) / degPerPxLng;
+        const dy = (lat - centerLat) / degPerPxLat;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        if (dist === 0)
+            return [lng, lat];
+        const scale = (dist + margin) / dist;
+        return [centerLng + dx * scale * degPerPxLng, centerLat + dy * scale * degPerPxLat];
+    });
+    return {
+        topLeft: expanded[0],
+        topRight: expanded[1],
+        bottomRight: expanded[2],
+        bottomLeft: expanded[3],
+    };
+}

package/dist/shared/types/events.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The payloads of the public events that are defined by the areas above shared/
+ *
+ * The EventEmitter (shared/utils/event-emitter.ts) types every event, so the payloads it
+ * carries sit here, below every layer. The defining areas re-export them.
+ */
+import type { Coordinate, Feature, VertexRef } from './model.js';
+/**
+ * Payload of draw.map.click (an event exposed on the instance)
+ *
+ * This exists to emit the normalized click of select mode as a single stream, as-is,
+ * regardless of whether anything was hit or of what was hit. The coordinates are the
+ * ones from before snapping (the raw normalized event). It is meant for read-only
+ * subscription and has no effect at all on the selection behavior of the mode.
+ */
+export interface MapClickEventPayload {
+    /** Map coordinates [lng, lat] */
+    lngLat: Coordinate;
+    /** Screen coordinates */
+    point: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Payload of draw.dataset.click (a public instance event)
+ *
+ * It reports in one event how a click in the select mode was resolved by the interception of the
+ * datasets. When a feature of an interactive dataset is hit, datasetId and
+ * feature are filled in; when nothing at all was hit (including a block by a non-interactive
+ * dataset) both are null. It does not fire for a click that hit a feature of the Store (that
+ * is the domain of selection.change on the selection side of the Store). The host can treat this
+ * null as "a click on empty space = clearing the data selection".
+ */
+export interface DatasetClickEventPayload {
+    /** Id of the dataset that was hit. null when there was no hit */
+    datasetId: string | null;
+    /** The feature that was hit. null when there was no hit */
+    feature: Feature | null;
+    /**
+     * The row of the feature in its dataset (its index in the features given to the
+     * dataset, or its row in a columnar table). null when there was no hit
+     */
+    row: number | null;
+    /** Map coordinate [lng, lat] */
+    lngLat: Coordinate;
+}
+/**
+ * A geographic coordinate (the same shape as the lngLat of a normalized event)
+ */
+export interface SnapLngLat {
+    /** The longitude in degrees */
+    lng: number;
+    /** The latitude in degrees */
+    lat: number;
+}
+/**
+ * The kind of a snapping target
+ *
+ * The priority order is vertex > intersection > edge > guide, and ties are decided by
+ * distance.
+ */
+export type SnapTargetKind = 'vertex' | 'edge' | 'intersection' | 'guide';
+/**
+ * A segment to snap to (an edge or a guide)
+ */
+export interface SnapTargetSegment {
+    /** The start point of the segment */
+    start: Coordinate;
+    /** The end point of the segment */
+    end: Coordinate;
+    /** For a real edge, the vertex reference of the start point */
+    startRef?: VertexRef;
+    /** For a real edge, the vertex reference of the end point */
+    endRef?: VertexRef;
+}
+/**
+ * Information about a snapping target
+ *
+ * The geometric references of the target (vertex / segment) are read by tracing and
+ * by the rendering of the guide line.
+ */
+export interface SnapTarget {
+    /** The kind of the target */
+    kind: SnapTargetKind;
+    /** The feature ID of the target (only for candidates originating from the Store) */
+    featureId?: string;
+    /**
+     * The dataset ID of the target (only for candidates originating from a
+     * dataset)
+     */
+    datasetId?: string;
+    /** A description for display (read by the status bar and the like) */
+    description?: string;
+    /** When the target is a vertex, its vertex reference */
+    vertex?: VertexRef;
+    /** When the target is an edge or a guide, its segment */
+    segment?: SnapTargetSegment;
+}
+/**
+ * The result of snapping
+ *
+ * When nothing was snapped to, the input coordinate goes into lngLat as it is and no
+ * target is attached.
+ */
+export interface SnapResult {
+    /** The coordinate after snapping (the input as it is when nothing was snapped to) */
+    lngLat: SnapLngLat;
+    /** The snapping target (absent when nothing was snapped to) */
+    target?: SnapTarget;
+}
+/**
+ * One frame of the stacking order: the maplibre layer that draws one run of the layer order
+ * between two external entries
+ *
+ * When the `isExternalEntry` option marks entries of the layer order as external, the draw
+ * instance draws each run between them in a maplibre custom layer of its own, so the host can
+ * place its own maplibre layers between the frames. `getRenderSlots()` lists the frames, and
+ * the `draw.renderslots.change` event announces a change of them.
+ */
+export interface RenderSlot {
+    /** The maplibre layer ID of the custom layer that draws this run */
+    readonly layerId: string;
+    /** The index in the layer order where the run starts (inclusive) */
+    readonly from: number;
+    /** The index in the layer order where the run ends (exclusive) */
+    readonly to: number;
+}

package/dist/shared/types/events.js

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