@sakuzu/maplibre-gl-draw 1.0.0

package/dist/modes/handler.d.ts

@@ -0,0 +1,285 @@
+/**
+ * ModeHandler
+ *
+ * Handler interface for the drawing modes.
+ * Every mode implements this interface.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { DragNormalizedEvent, KeyNormalizedEvent, MouseNormalizedEvent } from '../dispatcher/types.js';
+import type { Mode } from '../store/types.js';
+/**
+ * An input whose coordinates go through snapping, as asked about by
+ * {@link ModeHandler.isSnapEnabledFor}.
+ *
+ * Corresponds one to one with the inputs whose coordinates InputRouter passes through snapping
+ * (click / mousemove / dragstart / dragmove / dragend).
+ */
+export type SnapInputType = 'click' | 'mousemove' | 'dragstart' | 'dragmove' | 'dragend';
+/**
+ * The services of the draw instance a mode works with, passed to
+ * {@link ModeHandler.onStart}.
+ *
+ * Note: the redraw is triggered automatically by RenderCoordinator subscribing to Store changes,
+ *       so a mode does not need to call requestRepaint() explicitly.
+ */
+export interface ModeContext {
+    /** The map the draw instance is attached to */
+    map: MapLibreMap;
+    /** The Store of the document; a mode writes features through it */
+    store: import('../store/store.js').Store;
+    /**
+     * The queries of the spatial index (it is derived from the Store, so a mode only reads it)
+     */
+    spatialIndex: import('../store/spatial/spatial-index.js').SpatialQuery;
+    /** The hit test of the features of the Store alone */
+    hitTestService: import('../dispatcher/hit-test/service.js').HitTestService;
+    /**
+     * Returns the foreground hit in the visual stacking order (unified z traversal)
+     *
+     * Traverses the features of the Store and the datasets in a single
+     * stacking order. Selection, drag and cursor decisions use this one (`hitTestService.hitTest`
+     * looks only at the Store, so it would grab a feature that is occluded by a dataset).
+     */
+    hitTestTopmost: import('../dispatcher/hit-test/topmost.js').HitTestTopmost;
+    /**
+     * Provider of the companion rendering and the companion hits (the ones of this draw instance)
+     *
+     * Used to return a consumed companion hit to the provider.
+     */
+    featureCompanions: import('../view/feature-companion.js').FeatureCompanionRegistry;
+    /**
+     * The selection scope of this draw instance (the extension points of the custom feature
+     * types, the auxiliary handles and the thinned handle sets)
+     *
+     * The same object the CustomLayer draws the selection UI with, so hit testing and rendering
+     * agree, and a second draw instance on the page never takes part.
+     */
+    selectionScope: import('../view/ui/selection-scope.js').SelectionScope;
+    /** The emitter of the `draw.*` events of the draw instance */
+    eventEmitter: import('../shared/utils/event-emitter.js').EventEmitter;
+    /** The resolved colors and sizes of the selection UI */
+    selectionStyle: import('../shared/config/selection.js').SelectionUIConfig;
+    /**
+     * Topology configuration (simultaneous movement of shared vertices, and so on)
+     *
+     * When omitted, it is treated as the default value (everything disabled).
+     */
+    topology?: import('../shared/config/topology.js').TopologyConfig;
+    /**
+     * Trace configuration (whether edge tracing is enabled or disabled)
+     *
+     * When omitted, it is treated as the default value (enabled). It is the same object that
+     * draw.tracing rewrites, so a switch at runtime takes effect on the very next input.
+     */
+    trace?: import('../shared/config/trace.js').TraceConfig;
+    /**
+     * The resolved snapping options
+     *
+     * Read so that the simultaneous movement of shared vertices shares the "modifier key for
+     * temporary disabling" with snapping. When snapping is not configured, it is omitted and
+     * the default 'alt' is assumed.
+     */
+    snapOptions?: import('../snapping/types.js').ResolvedSnapOptions;
+    /** Generates the default name of a new feature (such as "Polygon 3") */
+    autoNameGenerator: import('../shared/utils/name-generator.js').AutoNameGenerator;
+    /** The box selection strategies by feature type */
+    boxSelectionRegistry: import('../dispatcher/hit-test/box-strategy.js').BoxSelectionStrategyRegistry;
+    /** The plugin manager of the draw instance (omitted when none is set up) */
+    pluginManager?: import('../plugins/plugin-manager.js').PluginManager;
+    /** Requests a mode change, as `draw.setMode` does (the same refusals apply) */
+    setMode: (mode: Mode) => void;
+    /** Generates a new unique feature id */
+    generateFeatureId: () => string;
+    /**
+     * Gets the ID of the writable layer, the layer that new features are written into
+     *
+     * The active layer when it exists, is not locked, is visible and is not locally hidden,
+     * otherwise the first such layer, otherwise an empty string. A mode reads it when it
+     * commits a feature; when it is an empty string the mode must not create the feature: it
+     * discards the drawing (clears the tentative state) and returns to select.
+     */
+    getCurrentLayerId: () => string;
+    /**
+     * Whether the line widths of the features a drawing mode creates follow the zoom (the
+     * `scaleWithZoom` option of the instance)
+     *
+     * When it is true, a mode writes the zoom of the commit into `properties.createdZoom`, and
+     * the widths of the feature grow and shrink with the map from there. When it is false, it
+     * writes no created zoom and the widths stay the same on the screen.
+     */
+    scaleWithZoom: boolean;
+    /**
+     * Gets the most recent snapping result (always null when snapping is not configured)
+     *
+     * This is the only read port through which a mode learns about snapping. InputRouter passes
+     * the coordinates of click / mousemove through snapping before delivering them to the mode,
+     * so at the time of onClick / onMouseMove the result readable here is the snapping result
+     * corresponding to the event that was just delivered (tracing reads it).
+     */
+    getSnapResult?: () => import('../snapping/types.js').SnapResult | null;
+    /**
+     * Gets a feature of a dataset (omitted when it is not configured)
+     *
+     * This is the port through which a mode resolves to a feature a snap target that was snapped
+     * to data (a dataset). It is a feature that is not in the Store, so it cannot
+     * be looked up with store.getFeature (tracing reads it).
+     */
+    getDatasetFeature?: (datasetId: string, featureId: string) => import('../store/types.js').Feature | null;
+    /**
+     * Looks up, by extent, the features of the datasets usable for tracing
+     *
+     * This is the port for adding the features of data (a dataset) to the material
+     * of the edge graph. It returns an empty array when snapping to data is disabled.
+     */
+    getDatasetTraceFeatures?: (bbox: import('../store/types.js').BoundingBox) => import('../store/types.js').Feature[];
+}
+/**
+ * The implementation of an interaction mode: it receives the normalized input while it is the
+ * current mode.
+ *
+ * Register a custom mode with `draw.registerMode(name, factory)` or `Plugin.modes`, and enter
+ * it with `draw.setMode(name)`. The context is passed in `onStart()` and the implementation
+ * keeps it in a field; it is not passed to the event handlers. Every handler is optional. The
+ * coordinates of the pointer events have already gone through snapping (see
+ * `isSnapEnabledFor`).
+ *
+ * @example
+ * ```ts
+ * import type { ModeContext, ModeHandler, MouseNormalizedEvent } from '@sakuzu/maplibre-gl-draw';
+ *
+ * // A mode that logs the clicked position and returns to select on Escape
+ * class ProbeMode implements ModeHandler {
+ *   readonly modeName = 'probe';
+ *   private context: ModeContext | null = null;
+ *
+ *   onStart(context: ModeContext): void {
+ *     this.context = context;
+ *   }
+ *   onClick(event: MouseNormalizedEvent): void {
+ *     console.log(event.lngLat.lng, event.lngLat.lat);
+ *   }
+ *   onKeyDown(event: { key: string }): void {
+ *     if (event.key === 'Escape') this.context?.setMode('select');
+ *   }
+ * }
+ *
+ * draw.registerMode('probe', () => new ProbeMode());
+ * draw.setMode('probe');
+ * ```
+ */
+export interface ModeHandler {
+    /** The name the mode is registered under */
+    readonly modeName: Mode;
+    /**
+     * Whether the mode writes new features into a layer
+     *
+     * A mode that declares true is entered only while a layer can be written (while
+     * `ModeContext.getCurrentLayerId` returns a non-empty string); otherwise setMode is ignored
+     * and the current mode is kept. The built-in drawing modes declare it, and a plugin mode
+     * that creates features declares it to get the same gate. The declaration does not remove
+     * the check at commit time: the layer can stop being writable while the mode is active.
+     */
+    readonly writesFeatures?: boolean;
+    /** Called when the mode becomes the current mode; keep the context for later */
+    onStart?(context: ModeContext): void;
+    /** Called when another mode replaces it or the draw instance is destroyed */
+    onStop?(): void;
+    /** Called on a click */
+    onClick?(event: MouseNormalizedEvent): void;
+    /** Called on a double click */
+    onDoubleClick?(event: MouseNormalizedEvent): void;
+    /** Called on a mouse move */
+    onMouseMove?(event: MouseNormalizedEvent): void;
+    /**
+     * Called on a mouse down
+     * @returns returning true consumes the event (stops the propagation to MapLibre)
+     */
+    onMouseDown?(event: MouseNormalizedEvent): boolean | undefined;
+    /** Called on a mouse up */
+    onMouseUp?(event: MouseNormalizedEvent): void;
+    /** Called when a drag starts */
+    onDragStart?(event: DragNormalizedEvent): void;
+    /** Called during a drag */
+    onDragMove?(event: DragNormalizedEvent): void;
+    /** Called when a drag ends */
+    onDragEnd?(event: DragNormalizedEvent): void;
+    /**
+     * Called when a press ends without a release (a second finger touched the screen, or the
+     * browser cancelled the touch)
+     *
+     * Nothing is decided: the mode abandons the press, restores what the press changed and
+     * gives the pan back to MapLibre. It can arrive before onDragStart (a press that has not
+     * become a drag yet). The coordinates are the last known position.
+     */
+    onDragCancel?(event: DragNormalizedEvent): void;
+    /** Called on a key down (normalized) */
+    onKeyDown?(event: KeyNormalizedEvent): void;
+    /** Called on a key up (normalized) */
+    onKeyUp?(event: KeyNormalizedEvent): void;
+    /**
+     * Called after an external state change
+     *
+     * Used to reset the internal state of the mode after an external state change
+     * (a change applied from outside the mode) has been carried out.
+     * Example: when the state is changed externally while drawing in the Circle mode,
+     * the drawing state is reset.
+     */
+    onExternalStateChange?(): void;
+    /**
+     * Called after a selection change
+     *
+     * Used to update the internal state of the mode when the selection is changed from a plugin.
+     */
+    onSelectionChange?(): void;
+    /**
+     * Undoes a vertex while drawing
+     *
+     * Called when Cmd+Z/Ctrl+Z is pressed while drawing a LineString/Polygon.
+     * @returns whether the undo was carried out
+     */
+    undoVertex?(): boolean;
+    /**
+     * Redoes a vertex that was undone
+     *
+     * Called when Cmd+Shift+Z/Ctrl+Y is pressed while drawing.
+     * @returns whether the redo was carried out
+     */
+    redoVertex?(): boolean;
+    /**
+     * Returns the feature to prefer when snapping candidates are tied
+     *
+     * Read by InputRouter right before it passes the coordinates through snapping, and passed as
+     * the preferFeature of SnapContext. A drawing mode returns the anchor of the trace (the
+     * boundary it started tracing along), which prevents the snap target from jumping to another
+     * feature whose coordinates overlap exactly.
+     *
+     * @returns the feature to prefer, or null if there is none
+     */
+    getSnapPreference?(): {
+        featureId: string;
+        datasetId?: string;
+    } | null;
+    /**
+     * Returns, per input type, whether snapping is to be applied
+     *
+     * Read by InputRouter right before it passes the coordinates through snapping. An input type
+     * for which false is returned does not go through SnapService and reaches the mode with its
+     * raw coordinates. When this is omitted (and when true is returned), snapping is applied as
+     * before.
+     *
+     * The tolerance (10 pixels by default) is a value premised on "once per click", so in a
+     * drag-driven drawing that passes several hundred points in a single stroke (freehand), the
+     * intermediate sample points are pulled one after another to nearby vertices and a line drawn
+     * straight ends up bent. A port that can be switched off per input type is provided so that
+     * only the inside of the stroke can be let through untouched (the start point and the end
+     * point can remain snapped).
+     *
+     * @param inputType the type of the input for which snapping is about to be applied
+     * @returns true if snapping is to be applied
+     */
+    isSnapEnabledFor?(inputType: SnapInputType): boolean;
+}
+/**
+ * Creates a new {@link ModeHandler}; called every time the mode is entered.
+ */
+export type ModeFactory = () => ModeHandler;

package/dist/modes/handler.js

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

package/dist/modes/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Modes module
+ *
+ * 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 { ModeContext, ModeFactory, ModeHandler, SnapInputType } from './handler.js';

package/dist/modes/index.js

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

package/dist/modes/manager.d.ts

@@ -0,0 +1,15 @@
+import type { ModeHandler } from './handler.js';
+/**
+ * Options of ModeManagerImpl
+ */
+export interface ModeManagerOptions {
+    /**
+     * Whether the mode of the handler can be entered now
+     *
+     * Asked on every setMode (except the one to select) with a handler that the factory of the
+     * requested mode has just created; it reads what the mode declares (for example
+     * `writesFeatures`). When it returns false the request is ignored and the current mode is
+     * kept, like the interaction lock. When it is omitted, every registered mode can be entered.
+     */
+    canEnter?: (handler: ModeHandler) => boolean;
+}

package/dist/modes/manager.js

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * ModeManager implementation
+ *
+ * Subscribes to the mode state of the Store and switches the handler when the mode changes.
+ *
+ * @internal
+ */
+export class ModeManagerImpl {
+    constructor(store, options = {}) {
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: store
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+        Object.defineProperty(this, "currentHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "factories", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "unsubscribe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The handler created by setMode to ask canEnter, which starts when the Store reports the
+         * mode change (so a mode is never constructed twice for one transition)
+         */
+        Object.defineProperty(this, "pending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /**
+     * Sets the context
+     */
+    setContext(context) {
+        this.context = context;
+    }
+    getMode() {
+        return this.store.getMode();
+    }
+    setMode(mode) {
+        if (mode === this.store.getMode())
+            return true;
+        // A mode without a factory is refused before the Store changes, so the Store, the
+        // draw.mode.change event and the running handler never disagree (a typo in a mode name
+        // is reported, not half applied).
+        const factory = this.factories.get(mode);
+        if (!factory) {
+            console.warn(`Mode "${mode}" is not registered`);
+            return false;
+        }
+        // While the interaction lock is on, transitions to drawing modes (anything other than
+        // select) are refused. In the read-only state only select is allowed, which prevents
+        // entering an editing mode. This is not a write gate, so it is a suppression independent
+        // of readOnly, and returning to select is always allowed.
+        if (mode !== 'select' && this.store.isInteractionLocked())
+            return false;
+        // A mode that the canEnter predicate rejects (for example, one that writes features
+        // while no layer can be written) is refused in the same way.
+        const { canEnter } = this.options;
+        if (canEnter && mode !== 'select') {
+            const handler = factory();
+            if (!canEnter(handler))
+                return false;
+            this.pending = { mode, handler };
+        }
+        // Following SSoT, the mode change is carried out through the Store
+        // The result of the mode change is handled in handleModeChange through the Store subscription
+        this.store.setMode(mode);
+        return this.store.getMode() === mode;
+    }
+    registerMode(mode, factory) {
+        this.factories.set(mode, factory);
+        return () => {
+            if (this.factories.get(mode) === factory)
+                this.unregisterMode(mode);
+        };
+    }
+    unregisterMode(mode) {
+        if (!this.factories.has(mode))
+            return;
+        if (mode !== 'select' && this.store.getMode() === mode)
+            this.setMode('select');
+        if (this.pending?.mode === mode)
+            this.pending = null;
+        this.factories.delete(mode);
+    }
+    getHandler() {
+        return this.currentHandler;
+    }
+    /**
+     * Starts the initial mode and starts subscribing to the Store
+     */
+    start() {
+        // Subscribe to the mode changes of the Store
+        this.unsubscribe = this.store.subscribe((changes) => {
+            if (changes.mode) {
+                this.handleModeChange(changes.mode.mode);
+            }
+        });
+        // Start the handler of the initial mode
+        const currentMode = this.store.getMode();
+        const factory = this.factories.get(currentMode);
+        if (factory) {
+            this.currentHandler = factory();
+            if (this.context) {
+                this.currentHandler.onStart?.(this.context);
+            }
+        }
+    }
+    /**
+     * Stops the current mode and unsubscribes
+     */
+    stop() {
+        if (this.currentHandler) {
+            this.currentHandler.onStop?.();
+        }
+        this.currentHandler = null;
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+    }
+    /**
+     * Handles a mode change notification from the Store
+     */
+    handleModeChange(mode) {
+        const factory = this.factories.get(mode);
+        if (!factory) {
+            console.warn(`Mode "${mode}" is not registered`);
+            return;
+        }
+        // End the current mode
+        if (this.currentHandler) {
+            this.currentHandler.onStop?.();
+        }
+        // Start the new mode (the handler that setMode created for canEnter, when there is one)
+        const pending = this.pending;
+        this.pending = null;
+        this.currentHandler = pending?.mode === mode ? pending.handler : factory();
+        if (this.context) {
+            this.currentHandler.onStart?.(this.context);
+        }
+    }
+    /**
+     * Notifies the current mode handler of an external state change
+     */
+    notifyStateReset() {
+        this.currentHandler?.onExternalStateChange?.();
+    }
+    /**
+     * Notifies the current mode handler of a selection change
+     */
+    notifySelectionChange() {
+        this.currentHandler?.onSelectionChange?.();
+    }
+    /**
+     * Undoes a vertex while drawing
+     */
+    undoVertex() {
+        return this.currentHandler?.undoVertex?.() ?? false;
+    }
+    /**
+     * Redoes a vertex that was undone
+     */
+    redoVertex() {
+        return this.currentHandler?.redoVertex?.() ?? false;
+    }
+}

package/dist/modes/select/box-selection.d.ts

@@ -0,0 +1,52 @@
+import type { BoxSelection, Coordinate, Feature } from '../../store/types.js';
+import type { ModeContext } from '../handler.js';
+/**
+ * Detect the features inside the box
+ *
+ * First the candidates are obtained quickly through the SpatialIndex (rbush),
+ * and then a precise inside-the-box test is performed.
+ */
+export declare function queryFeaturesInBox(boxSelection: BoxSelection, context: ModeContext): string[];
+type Rect = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/**
+ * The rectangles, in longitudes within [-180, 180], that a box drawn on the screen covers
+ *
+ * The corners come from the map unprojected as they are, so a box drawn across the
+ * antimeridian has a longitude beyond ±180 at one side. It is brought back into [-180, 180]
+ * and split at the line into two rectangles, and the box as drawn is kept as well; a box as
+ * wide as the world covers every longitude.
+ */
+export declare function boxRects(start: Coordinate, end: Coordinate): Rect[];
+/**
+ * Decide whether a feature is inside the box
+ *
+ * Uses BoxSelectionStrategyRegistry to perform the appropriate test per feature type.
+ * - Point: whether the center coordinate is inside the box
+ * - LineString: intersection test between the geometry and the box
+ * - Polygon: intersection test between the geometry and the box
+ * - Text/Image: intersection test between the OBB (the bounding box that accounts for rotation)
+ *   and the box
+ */
+export declare function isFeatureInBox(feature: Feature, rect: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}, boxSelectionRegistry: ModeContext['boxSelectionRegistry']): boolean;
+/**
+ * The fallback box selection test
+ *
+ * Performs a simple coordinate-based test for feature types that are not registered.
+ */
+export declare function fallbackBoxSelection(feature: Feature, rect: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}): boolean;
+export {};