@sakuzu/maplibre-gl-draw 1.0.0

package/dist/modes/draw/polygon.js

@@ -0,0 +1,378 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createdZoomProperty, resolveCommitLayer } from './commit-layer.js';
+import { computeTracePath, isTraceEnabled, readTraceAnchor } from './trace-support.js';
+/** Tolerance for deciding a vertex click (in pixels) */
+const VERTEX_CLICK_TOLERANCE = 10;
+/**
+ * DrawPolygonMode implementation
+ *
+ * @internal
+ */
+export class DrawPolygonMode {
+    constructor() {
+        Object.defineProperty(this, "modeName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'draw_polygon'
+        });
+        Object.defineProperty(this, "writesFeatures", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: true
+        });
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "coordinates", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "isNearFirstVertex", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** The redo stack (holds the undone vertices) */
+        Object.defineProperty(this, "redoStack", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        /** The last mouse coordinate (for displaying the dashed line on undo/redo) */
+        Object.defineProperty(this, "lastMouseCoord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The Feature ID that is going to be created */
+        Object.defineProperty(this, "pendingFeatureId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The snap target of the previously confirmed click (the start point of the trace)
+         *
+         * It is reset to null for a click that did not snap and for a snap that cannot be traced.
+         */
+        Object.defineProperty(this, "traceAnchor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The trace path up to the cursor position (the unconfirmed vertices for the preview)
+         *
+         * They are inserted between the confirmed coordinates and the cursor point and drawn as
+         * tentative.
+         */
+        Object.defineProperty(this, "tracePreview", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    onStart(context) {
+        this.context = context;
+        // Change the cursor to a crosshair
+        this.context.map.getCanvas().style.cursor = 'crosshair';
+        // Clear the selection (not notified as a change)
+        this.context.store.transact(() => {
+            this.context.store.setSelection(null, []);
+        }, 'silent');
+        // Reset the state
+        this.coordinates = [];
+        this.isNearFirstVertex = false;
+        this.redoStack = [];
+        this.lastMouseCoord = null;
+        this.traceAnchor = null;
+        this.tracePreview = null;
+        // Generate the Feature ID in advance
+        this.pendingFeatureId = this.context.generateFeatureId();
+    }
+    onStop() {
+        // Restore the cursor
+        this.context.map.getCanvas().style.cursor = '';
+        // Clear the tentative state
+        this.context.store.setTentative(null);
+        this.coordinates = [];
+    }
+    /**
+     * Called after an external state change
+     *
+     * Resets the state of the drawing in progress so that the next drawing operation can start
+     * normally.
+     */
+    onExternalStateChange() {
+        // Reset the state
+        this.coordinates = [];
+        this.redoStack = [];
+        this.lastMouseCoord = null;
+        this.pendingFeatureId = null;
+        this.isNearFirstVertex = false;
+        this.traceAnchor = null;
+        this.tracePreview = null;
+        // Clear the tentative state
+        this.context.store.setTentative(null);
+    }
+    /**
+     * A double click while drawing is two clicks of the drawing; it never zooms the map
+     * (consumed by preventing its default action)
+     */
+    onDoubleClick(event) {
+        event.originalEvent.preventDefault();
+    }
+    onClick(event) {
+        // Complete when there are at least three points and the click is near the first vertex
+        if (this.coordinates.length >= 3 && this.isNearFirstVertex) {
+            this.finishPolygon();
+            return;
+        }
+        // Read the snap target of this click and first take in the sequence of boundary vertices
+        // between it and the previously confirmed click (tracing)
+        const anchor = readTraceAnchor(this.context, event);
+        const path = computeTracePath(this.context, this.traceAnchor, anchor);
+        if (path) {
+            this.coordinates.push(...path);
+        }
+        this.traceAnchor = anchor;
+        this.tracePreview = null;
+        // Add the vertex
+        const coord = [event.lngLat.lng, event.lngLat.lat];
+        this.coordinates.push(coord);
+        // Clear the redo stack when a new vertex is added
+        this.redoStack = [];
+        // Update the tentative state
+        // Note: the redraw is triggered automatically by RenderCoordinator subscribing to Store changes
+        this.updateTentative();
+    }
+    onMouseMove(event) {
+        // Save the last mouse coordinate (for displaying the dashed line on undo/redo)
+        this.lastMouseCoord = [event.lngLat.lng, event.lngLat.lat];
+        // Check whether it is near the first vertex
+        this.isNearFirstVertex = this.checkNearFirstVertex(event.point);
+        // When the snap target of the cursor is the same feature as the previously confirmed
+        // click, hold the path that is going to be inserted as a preview
+        this.tracePreview = computeTracePath(this.context, this.traceAnchor, readTraceAnchor(this.context, event));
+        // Update the cursor
+        if (this.coordinates.length >= 3 && this.isNearFirstVertex) {
+            this.context.map.getCanvas().style.cursor = 'pointer';
+        }
+        else {
+            this.context.map.getCanvas().style.cursor = 'crosshair';
+        }
+        // When there is at least one vertex, display the line up to the mouse position
+        if (this.coordinates.length > 0) {
+            this.updateTentative(this.lastMouseCoord);
+        }
+    }
+    onKeyDown(event) {
+        if (event.key === 'Escape') {
+            // Cancel
+            this.cancelPolygon();
+        }
+        else if (event.key === 'Enter') {
+            // Confirm
+            this.finishPolygon();
+        }
+        else if (event.key === 'Backspace' || event.key === 'Delete') {
+            // Remove the last vertex
+            this.removeLastVertex();
+        }
+    }
+    /**
+     * The feature to prefer when snapping candidates are tied (the boundary that tracing started
+     * along)
+     */
+    getSnapPreference() {
+        if (!this.traceAnchor || !isTraceEnabled(this.context))
+            return null;
+        return {
+            featureId: this.traceAnchor.featureId,
+            datasetId: this.traceAnchor.datasetId,
+        };
+    }
+    /**
+     * Checks whether it is near the first vertex
+     */
+    checkNearFirstVertex(screenPoint) {
+        if (this.coordinates.length === 0)
+            return false;
+        const firstCoord = this.coordinates[0];
+        const firstScreenPoint = this.context.map.project(firstCoord);
+        const dx = screenPoint.x - firstScreenPoint.x;
+        const dy = screenPoint.y - firstScreenPoint.y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        return distance <= VERTEX_CLICK_TOLERANCE;
+    }
+    /**
+     * Confirms the polygon
+     */
+    finishPolygon() {
+        // At least three points are required
+        if (this.coordinates.length < 3) {
+            return;
+        }
+        const { store, autoNameGenerator } = this.context;
+        // Discard the drawing when no layer can be written any more
+        const layerId = resolveCommitLayer(this.context);
+        if (layerId === null)
+            return;
+        // Generate the automatic name
+        const autoName = autoNameGenerator.generateName('Polygon');
+        // Create the closed ring (append the first point at the end)
+        const ring = [...this.coordinates, this.coordinates[0]];
+        // Use the ID generated in advance (generate a new one if there is none)
+        const featureId = this.pendingFeatureId ?? this.context.generateFeatureId();
+        // Create a new polygon feature
+        const feature = {
+            id: featureId,
+            type: 'Polygon',
+            coordinates: [ring],
+            layerId,
+            properties: {
+                ...createdZoomProperty(this.context),
+                ...(autoName !== undefined && { name: autoName }),
+            },
+            locked: false,
+            visible: true,
+        };
+        // Bundle the feature creation and the selection into a single transaction
+        // (so that both are undone at once on undo)
+        store.transact(() => {
+            store.createFeature(feature);
+            // Clear the tentative state
+            store.setTentative(null);
+            // Select the created feature
+            store.setSelection('feature', [feature.id]);
+        });
+        // Reset the state
+        this.coordinates = [];
+        this.isNearFirstVertex = false;
+        this.pendingFeatureId = null;
+        this.traceAnchor = null;
+        this.tracePreview = null;
+        // Return to the select mode
+        this.context.setMode('select');
+    }
+    /**
+     * Cancels the creation of the polygon
+     */
+    cancelPolygon() {
+        if (this.coordinates.length > 0) {
+            this.coordinates = [];
+            this.pendingFeatureId = null;
+            this.traceAnchor = null;
+            this.tracePreview = null;
+            this.context.store.setTentative(null);
+        }
+        else {
+            // Return to the select mode if drawing is not in progress
+            this.context.setMode('select');
+        }
+    }
+    /**
+     * Removes the last vertex
+     */
+    removeLastVertex() {
+        if (this.coordinates.length > 0) {
+            this.coordinates.pop();
+            // A vertex removed with Backspace/Delete cannot be redone
+            this.redoStack = [];
+            // The previously confirmed click changes, so the start point of the trace is discarded too
+            this.clearTrace();
+            this.updateTentative();
+        }
+    }
+    /**
+     * Undoes a vertex while drawing
+     */
+    undoVertex() {
+        if (this.coordinates.length === 0) {
+            return false;
+        }
+        const removed = this.coordinates.pop();
+        this.redoStack.push(removed);
+        this.clearTrace();
+        // Pass the mouse coordinate to keep the dashed line
+        this.updateTentative(this.lastMouseCoord ?? undefined);
+        return true;
+    }
+    /**
+     * Redoes a vertex that was undone
+     */
+    redoVertex() {
+        if (this.redoStack.length === 0) {
+            return false;
+        }
+        const restored = this.redoStack.pop();
+        this.coordinates.push(restored);
+        this.clearTrace();
+        // Pass the mouse coordinate to keep the dashed line
+        this.updateTentative(this.lastMouseCoord ?? undefined);
+        return true;
+    }
+    /**
+     * Discards the state of the trace
+     *
+     * On an undo / redo of a vertex the "previously confirmed click" changes, so the snap target
+     * that was held as the start point is not kept in use as it is.
+     */
+    clearTrace() {
+        this.traceAnchor = null;
+        this.tracePreview = null;
+    }
+    /**
+     * Updates the tentative state
+     */
+    updateTentative(mouseCoord) {
+        if (this.coordinates.length === 0) {
+            this.context.store.setTentative(null);
+            return;
+        }
+        // The coordinate array including the mouse position and the trace path up to it
+        // (the confirmed ones remain the leading coordinates.length entries)
+        const coords = mouseCoord
+            ? [...this.coordinates, ...(this.tracePreview ?? []), mouseCoord]
+            : [...this.coordinates];
+        // Highlight it when the cursor is near the first vertex (only when it can be closed with
+        // three or more points)
+        const highlightedVertexIndex = this.coordinates.length >= 3 && this.isNearFirstVertex ? 0 : undefined;
+        // Display it as a polygon (a closed shape) when there are at least two points
+        if (coords.length >= 2) {
+            // Display it as a closed ring
+            const ring = [...coords, coords[0]];
+            this.context.store.setTentative({
+                type: 'Polygon',
+                coordinates: [ring],
+                layerId: this.context.getCurrentLayerId(),
+                confirmedCount: this.coordinates.length, // Number of confirmed coordinates (before closing)
+                highlightedVertexIndex,
+                pendingFeatureId: this.pendingFeatureId ?? undefined,
+            });
+        }
+        else {
+            // Display it as a marker when there is only one point
+            this.context.store.setTentative({
+                type: 'Point',
+                coordinates: coords[0],
+                layerId: this.context.getCurrentLayerId(),
+                pendingFeatureId: this.pendingFeatureId ?? undefined,
+            });
+        }
+    }
+}

package/dist/modes/draw/trace-support.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Trace support for the drawing modes
+ *
+ * A small set of helpers, used in common by draw_line / draw_polygon, for deriving a trace
+ * path from a snapping result. A mode does not hold a SnapService and learns about snapping
+ * only through `getSnapResult()` of ModeContext (a port that does no more than read the most
+ * recent snapping result).
+ *
+ * InputRouter passes the coordinates of click / mousemove through snapping before delivering
+ * them to the mode, so at the time of onClick / onMouseMove the most recent readable result is
+ * the result corresponding to the event that was just delivered. However, there are also
+ * events delivered without going through snapping, such as `snap: false` of a synthetic input,
+ * so the result is taken only after confirming that its coordinates match the coordinates of
+ * the event (if they do not match, it is regarded as a stale result and ignored).
+ *
+ * The path itself is the shortest path of a graph assembled from the nearby edges
+ * (operations/trace-graph.ts). The feature ID and the dataset ID of the snap target are
+ * used only to resolve the exact coordinates of the endpoints (a vertex reference or the
+ * references to both ends of an edge); whether the two points belong to the same feature does
+ * not matter.
+ */
+import type { MouseNormalizedEvent } from '../../dispatcher/types.js';
+import type { Coordinate, VertexRef } from '../../store/types.js';
+import type { ModeContext } from '../handler.js';
+/**
+ * The vertex references of both ends of an edge, for when the snap was to that edge
+ */
+export interface TraceAnchorSegment {
+    /** The vertex reference of the start point of the edge */
+    startRef: VertexRef;
+    /** The vertex reference of the end point of the edge */
+    endRef: VertexRef;
+}
+/**
+ * An endpoint of a trace (the snap target of a single click)
+ *
+ * It has either vertex (snapped to a vertex) or segment (snapped to an edge). An endpoint that
+ * has neither (a snap to a guide or to an intersection without references) cannot be traced.
+ */
+export interface TraceAnchorEndpoint {
+    /** The coordinate decided by snapping (including a point in the middle of an edge) */
+    coordinate: Coordinate;
+    /** When snapped to a vertex, that vertex reference */
+    vertex?: VertexRef;
+    /** When snapped to an edge, the vertex references of both ends of that edge */
+    segment?: TraceAnchorSegment;
+}
+/**
+ * The snap target that becomes the start point or the end point of a trace
+ */
+export interface TraceAnchor {
+    /** The feature ID of the snap target */
+    featureId: string;
+    /** The dataset ID of the snap target (only for one from a dataset) */
+    datasetId?: string;
+    /** The geometric references and the coordinate of the snap target */
+    endpoint: TraceAnchorEndpoint;
+}
+/**
+ * Whether tracing is enabled (if there is no configuration, it is regarded as enabled)
+ */
+export declare function isTraceEnabled(context: ModeContext): boolean;
+/**
+ * Reads the snap target of the event that was just delivered as an endpoint of a trace
+ *
+ * Returns null for snaps that cannot be used for tracing (a guide, an intersection without
+ * vertex references, an external candidate without a feature ID) and when nothing was snapped.
+ */
+export declare function readTraceAnchor(context: ModeContext, event: MouseNormalizedEvent): TraceAnchor | null;
+/**
+ * Derives the path between the previous confirmed click and the current snap target
+ *
+ * Returns the shortest path of the graph assembled from the nearby edges, as the sequence of
+ * vertices to insert in between. Vertices whose coordinates match are folded into a single
+ * node, so edges of different features also form a path as long as they are connected by a
+ * shared vertex. Returns null when the two ends are not connected or when an endpoint cannot
+ * be resolved (the caller then treats it as a straight line).
+ */
+export declare function computeTracePath(context: ModeContext, from: TraceAnchor | null, to: TraceAnchor | null): Coordinate[] | null;

package/dist/modes/draw/trace-support.js

@@ -0,0 +1,161 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { resolveVertexCoordinates } from '../../operations/shared-vertex.js';
+import { buildTraceGraph, findTracePath } from '../../operations/trace-graph.js';
+import { degreesPerPixel } from '../../snapping/geometry.js';
+import { isSnapVisible } from '../../snapping/providers/shared.js';
+import { DEFAULT_SNAP_OPTIONS } from '../../snapping/types.js';
+/**
+ * The margin of the extent over which the material of the graph is collected
+ * (as a ratio of the bbox of the two endpoints)
+ */
+const TRACE_BBOX_MARGIN_RATIO = 0.2;
+/**
+ * Whether tracing is enabled (if there is no configuration, it is regarded as enabled)
+ */
+export function isTraceEnabled(context) {
+    return context.trace?.enabled !== false;
+}
+/**
+ * Reads the snap target of the event that was just delivered as an endpoint of a trace
+ *
+ * Returns null for snaps that cannot be used for tracing (a guide, an intersection without
+ * vertex references, an external candidate without a feature ID) and when nothing was snapped.
+ */
+export function readTraceAnchor(context, event) {
+    if (!isTraceEnabled(context))
+        return null;
+    const result = context.getSnapResult?.();
+    const target = result?.target;
+    if (!result || !target || target.featureId === undefined)
+        return null;
+    // For an event delivered without going through snapping (such as snap: false of a synthetic
+    // input), the most recent result belongs to a different coordinate, so it is not used
+    if (result.lngLat.lng !== event.lngLat.lng || result.lngLat.lat !== event.lngLat.lat) {
+        return null;
+    }
+    const coordinate = [result.lngLat.lng, result.lngLat.lat];
+    if (target.vertex) {
+        return {
+            featureId: target.featureId,
+            datasetId: target.datasetId,
+            endpoint: { coordinate, vertex: target.vertex },
+        };
+    }
+    const segment = target.segment;
+    if (segment?.startRef && segment.endRef) {
+        return {
+            featureId: target.featureId,
+            datasetId: target.datasetId,
+            endpoint: {
+                coordinate,
+                segment: { startRef: segment.startRef, endRef: segment.endRef },
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Looks up the feature of the snap target
+ *
+ * Where it is resolved from depends on its origin. One from the Store is looked up with
+ * store.getFeature, one from a dataset with getDatasetFeature.
+ */
+function anchorFeature(context, anchor) {
+    if (anchor.datasetId === undefined) {
+        return context.store.getFeature(anchor.featureId) ?? null;
+    }
+    return context.getDatasetFeature?.(anchor.datasetId, anchor.featureId) ?? null;
+}
+/**
+ * Turns the snap target into an endpoint of the graph (resolves the vertex references into
+ * actual coordinates)
+ */
+function toGraphEndpoint(context, anchor) {
+    const { coordinate, vertex, segment } = anchor.endpoint;
+    const feature = anchorFeature(context, anchor);
+    if (vertex) {
+        // For a snap to a vertex the snapped coordinate is the vertex itself, but if the feature
+        // can be looked up, that one is taken as authoritative
+        const resolved = feature ? resolveVertexCoordinates(feature, [vertex])[0] : undefined;
+        return { coordinate, node: resolved ?? coordinate };
+    }
+    if (!segment || !feature)
+        return null;
+    const start = resolveVertexCoordinates(feature, [segment.startRef])[0];
+    const end = resolveVertexCoordinates(feature, [segment.endRef])[0];
+    if (!start || !end)
+        return null;
+    return { coordinate, segment: { start, end } };
+}
+/**
+ * The extent over which the material of the graph is collected
+ *
+ * The bbox of the two endpoints is expanded by 20 percent of its size plus the snapping
+ * tolerance.
+ */
+function traceBounds(context, from, to) {
+    const minX = Math.min(from[0], to[0]);
+    const maxX = Math.max(from[0], to[0]);
+    const minY = Math.min(from[1], to[1]);
+    const maxY = Math.max(from[1], to[1]);
+    const tolerancePx = context.snapOptions?.tolerancePx ?? DEFAULT_SNAP_OPTIONS.tolerancePx;
+    const perPixel = degreesPerPixel((minY + maxY) / 2, context.map.getZoom());
+    const marginX = (maxX - minX) * TRACE_BBOX_MARGIN_RATIO + perPixel.lng * tolerancePx;
+    const marginY = (maxY - minY) * TRACE_BBOX_MARGIN_RATIO + perPixel.lat * tolerancePx;
+    return {
+        minX: minX - marginX,
+        minY: minY - marginY,
+        maxX: maxX + marginX,
+        maxY: maxY + marginY,
+    };
+}
+/**
+ * Collects the features that become the material of the graph
+ *
+ * The same scope as the targets of snapping, that is, the visible features of the Store and,
+ * when snapping to data is enabled, the visible features of the datasets.
+ */
+function collectTraceFeatures(context, bbox) {
+    const lng = (bbox.minX + bbox.maxX) / 2;
+    const lat = (bbox.minY + bbox.maxY) / 2;
+    // findNear looks up with a square extent, so the larger of the two radii is used
+    const radius = Math.max(bbox.maxX - lng, bbox.maxY - lat);
+    const features = [];
+    const seen = new Set();
+    for (const id of context.spatialIndex.findNear([lng, lat], radius)) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const feature = context.store.getFeature(id);
+        if (!feature)
+            continue;
+        if (!isSnapVisible(feature, context.store))
+            continue;
+        features.push(feature);
+    }
+    const display = context.getDatasetTraceFeatures?.(bbox);
+    if (display)
+        features.push(...display);
+    return features;
+}
+/**
+ * Derives the path between the previous confirmed click and the current snap target
+ *
+ * Returns the shortest path of the graph assembled from the nearby edges, as the sequence of
+ * vertices to insert in between. Vertices whose coordinates match are folded into a single
+ * node, so edges of different features also form a path as long as they are connected by a
+ * shared vertex. Returns null when the two ends are not connected or when an endpoint cannot
+ * be resolved (the caller then treats it as a straight line).
+ */
+export function computeTracePath(context, from, to) {
+    if (!from || !to)
+        return null;
+    const fromEndpoint = toGraphEndpoint(context, from);
+    const toEndpoint = toGraphEndpoint(context, to);
+    if (!fromEndpoint || !toEndpoint)
+        return null;
+    const bbox = traceBounds(context, fromEndpoint.coordinate, toEndpoint.coordinate);
+    const features = collectTraceFeatures(context, bbox);
+    return findTracePath(buildTraceGraph(features, bbox), fromEndpoint, toEndpoint);
+}