@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/dispatcher/input-router.js

@@ -67,7 +67,7 @@ function toStoredCopy(event, reference) {
  * @internal
  */
 export function createInputRouter(deps) {
-    const { normalizer, modeManager, context, map, pluginManager, displayInteractions, notifyMapClick, snapService, } = deps;
+    const { normalizer, modeManager, context, map, displayInteractions, notifyMapClick, trackClick, snapService, extensionInput, } = deps;
     let boundHandleEvent = null;
     /**
      * Whether input originating from the pointer is currently held
@@ -126,68 +126,140 @@ export function createInputRouter(deps) {
      */
     function applySnap(event, inputType) {
         if (!snapService || event.snap === false)
-            return event;
-        if (modeManager.getHandler()?.isSnapEnabledFor?.(inputType) === false)
-            return event;
+            return { event, result: null };
+        if (modeManager.getHandler()?.isSnapEnabledFor?.(inputType) === false) {
+            return { event, result: null };
+        }
         const result = snapService.resolve(event.lngLat, event.point, buildSnapContext(event.modifiers));
         if (result.lngLat.lng === event.lngLat.lng && result.lngLat.lat === event.lngLat.lat) {
-            return event;
+            return { event, result: result.target ? result : null };
+        }
+        return {
+            event: { ...event, lngLat: { lng: result.lngLat.lng, lat: result.lngLat.lat } },
+            result,
+        };
+    }
+    /**
+     * What a consumed event stops besides the receivers after it: a consumed press does not
+     * reach the map (no pan starts) and a consumed double click does not zoom it
+     */
+    function stopConsumed(event) {
+        if (event.type === 'mousedown') {
+            const original = event.originalEvent;
+            original.stopPropagation();
+            if (!('touches' in original))
+                original.preventDefault();
+        }
+        else if (event.type === 'dblclick') {
+            event.originalEvent.preventDefault();
+        }
+    }
+    /**
+     * Hands the event to the plugins of the extensions, then to a mode written to the extension
+     * contract
+     *
+     * @returns 'consumed' when the event goes no further, 'mode' when a mode of the contract
+     *   received it, 'engine' when the mode is a mode of the engine the router calls
+     */
+    function toExtensions(handler, event, snapped, snap) {
+        if (!extensionInput)
+            return 'engine';
+        if (extensionInput.toPlugins(event, snapped, snap)) {
+            stopConsumed(event);
+            return 'consumed';
+        }
+        const consumed = extensionInput.toMode(handler, event, snapped, snap);
+        if (consumed === undefined)
+            return 'engine';
+        if (consumed) {
+            stopConsumed(event);
+            return 'consumed';
+        }
+        return 'mode';
+    }
+    /**
+     * A click: to the extensions, the mode, the datasets and the map.clicked notification
+     *
+     * @returns Whether a receiver took it
+     */
+    function handleClickEvent(handler, event) {
+        // Deliver to the mode with the snapped coordinates (if nothing snapped,
+        // the original event is used unchanged)
+        const { event: snapped, result } = applySnap(event, 'click');
+        const route = toExtensions(handler, event, snapped, result);
+        if (route === 'consumed')
+            return true;
+        if (route === 'engine')
+            handleClick(handler, snapped);
+        // Delivery to datasets happens only in select mode. A click
+        // in a drawing mode places a vertex, and delivering that same click as a
+        // click on the data as well would make the host application's "click to
+        // select" fire by mistake while drawing (for example, starting to draw a
+        // circle on top of a huge polygon of data would cover the whole screen with
+        // the selection highlight). The rule that a hit in the Store always wins is
+        // decided on the interception side, so the selection behavior of the mode
+        // during select is unaffected.
+        if (handler.modeName === 'select')
+            displayInteractions?.handleClick(snapped);
+        // Emit the click of select mode as a single stream regardless of whether
+        // anything was hit (draw.map.click). display.click is designed not to fire
+        // when a feature in the Store is hit, so a host application that needs "a
+        // click anywhere on the map" (placing a comment pin, for instance) watches
+        // this one. The coordinates are copied from the raw event before snapping.
+        if (handler.modeName === 'select') {
+            notifyMapClick?.({
+                lngLat: [event.lngLat.lng, event.lngLat.lat],
+                point: { x: event.point.x, y: event.point.y },
+            });
         }
-        return { ...event, lngLat: { lng: result.lngLat.lng, lat: result.lngLat.lat } };
+        return route === 'engine' && handler.onClick !== undefined;
     }
+    /**
+     * Hands an event to the extensions and the mode
+     *
+     * @returns Whether a receiver took it: a plugin or a mode of the contract consumed it, or
+     *   the mode of the engine has a receiver for it
+     */
     function handleEvent(input, options = {}) {
         // Only input originating from the real pointer is stopped while held.
         // Synthetic input (dispatch) is let through
         if (pointerHeld && !options.synthetic && HELD_EVENT_TYPES.has(input.type))
-            return;
+            return false;
         const handler = modeManager.getHandler();
         if (!handler)
-            return;
+            return false;
         // The single place where the longitude of the input is decided (see toStoredCopy)
         const event = toStoredCopy(input, firstTentativeCoordinate(context.store.getTentative()));
         switch (event.type) {
-            case 'click': {
-                // Deliver to the mode with the snapped coordinates (if nothing snapped,
-                // the original event is used unchanged)
-                const snapped = applySnap(event, 'click');
-                handleClick(handler, snapped);
-                // Delivery to datasets happens only in select mode. A click
-                // in a drawing mode places a vertex, and delivering that same click as a
-                // click on the data as well would make the host application's "click to
-                // select" fire by mistake while drawing (for example, starting to draw a
-                // circle on top of a huge polygon of data would cover the whole screen with
-                // the selection highlight). The rule that a hit in the Store always wins is
-                // decided on the interception side, so the selection behavior of the mode
-                // during select is unaffected.
-                if (handler.modeName === 'select')
-                    displayInteractions?.handleClick(snapped);
-                // Emit the click of select mode as a single stream regardless of whether
-                // anything was hit (draw.map.click). display.click is designed not to fire
-                // when a feature in the Store is hit, so a host application that needs "a
-                // click anywhere on the map" (placing a comment pin, for instance) watches
-                // this one. The coordinates are copied from the raw event before snapping.
-                if (handler.modeName === 'select') {
-                    notifyMapClick?.({
-                        lngLat: [event.lngLat.lng, event.lngLat.lat],
-                        point: { x: event.point.x, y: event.point.y },
-                    });
+            case 'click':
+                trackClick?.([event.lngLat.lng, event.lngLat.lat]);
+                try {
+                    return handleClickEvent(handler, event);
                 }
-                break;
+                finally {
+                    trackClick?.(null);
+                }
+            case 'dblclick': {
+                const taken = engineOr(toExtensions(handler, event, event, null), handler.onDoubleClick, () => handler.onDoubleClick?.(event));
+                // A double click never zooms the map while a drawing mode is active, whether or not
+                // anything took it: its clicks were meant for the drawing
+                if (handler.writesFeatures === true)
+                    event.originalEvent.preventDefault();
+                return taken;
             }
-            case 'dblclick':
-                handler.onDoubleClick?.(event);
-                break;
             case 'mousedown':
-                handleMouseDown(handler, event);
-                break;
+                return engineOr(toExtensions(handler, event, event, null), handler.onMouseDown, () => handleMouseDown(handler, event));
             case 'mouseup':
-                handler.onMouseUp?.(event);
-                break;
+                return engineOr(toExtensions(handler, event, event, null), handler.onMouseUp, () => handler.onMouseUp?.(event));
             case 'mousemove': {
-                const snapped = applySnap(event, 'mousemove');
-                // Call the onMouseMove of the plugins (they do not consume it)
-                pluginManager?.handleMouseMove(snapped);
-                handler.onMouseMove?.(snapped);
+                const { event: snapped, result } = applySnap(event, 'mousemove');
+                if (extensionInput?.toPlugins(event, snapped, result))
+                    return true;
+                const consumed = extensionInput?.toMode(handler, event, snapped, result);
+                if (consumed === true)
+                    return true;
+                if (consumed === undefined)
+                    handler.onMouseMove?.(snapped);
                 // The hover of datasets is likewise limited to select mode,
                 // by the same rule as click. When switching to a drawing mode, a hover that
                 // is still held is discarded (so that it does not fire on the stale target
@@ -198,53 +270,64 @@ export function createInputRouter(deps) {
                 else {
                     displayInteractions?.reset();
                 }
-                break;
+                return consumed === undefined && handler.onMouseMove !== undefined;
             }
             case 'contextmenu':
                 // contextmenu currently has no special handling
-                break;
+                return false;
             // The start and end of a drag also go through snapping. This is to keep
             // "start drawing exactly at a corner of a boundary and end at a corner" for
             // drag-driven drawing (freehand). The drag operations of select mode use
             // dragStartLngLat (the press position from before the threshold was exceeded)
             // as their start position, so they are unaffected by the replacement here.
             case 'dragstart': {
-                const snapped = applySnap(event, 'dragstart');
-                handler.onDragStart?.(snapped);
-                break;
+                const { event: snapped, result } = applySnap(event, 'dragstart');
+                return engineOr(toExtensions(handler, event, snapped, result), handler.onDragStart, () => handler.onDragStart?.(snapped));
             }
             case 'dragmove': {
-                const snapped = applySnap(event, 'dragmove');
-                // Call the onDragMove of the plugins (they do not consume it; the
-                // counterpart of onMouseMove)
-                pluginManager?.handleDragMove(snapped);
+                const { event: snapped, result } = applySnap(event, 'dragmove');
+                if (extensionInput?.toPlugins(event, snapped, result))
+                    return true;
+                const consumed = extensionInput?.toMode(handler, event, snapped, result);
+                if (consumed !== undefined)
+                    return consumed;
                 handler.onDragMove?.(snapped);
-                break;
+                return handler.onDragMove !== undefined;
             }
             case 'dragend': {
-                const snapped = applySnap(event, 'dragend');
-                handler.onDragEnd?.(snapped);
-                break;
+                const { event: snapped, result } = applySnap(event, 'dragend');
+                return engineOr(toExtensions(handler, event, snapped, result), handler.onDragEnd, () => handler.onDragEnd?.(snapped));
             }
             // A press ended without a release (a second finger, or the browser cancelled the
             // touch). No coordinates are decided, so it does not go through snapping, and it
             // is never held: the mode must always get the chance to abort the press.
             case 'dragcancel':
-                handler.onDragCancel?.(event);
-                break;
-            case 'keydown':
-                // Call the onKeyDown of the plugins first
-                if (pluginManager?.handleKeyDown(event)) {
-                    // Handled by a plugin
-                    break;
-                }
+                return engineOr(toExtensions(handler, event, event, null), handler.onDragCancel, () => handler.onDragCancel?.(event));
+            case 'keydown': {
+                if (extensionInput?.toPlugins(event, event, null))
+                    return true;
+                const consumed = extensionInput?.toMode(handler, event, event, null);
+                if (consumed !== undefined)
+                    return consumed;
                 handler.onKeyDown?.(event);
-                break;
+                return handler.onKeyDown !== undefined;
+            }
             case 'keyup':
-                handler.onKeyUp?.(event);
-                break;
+                return engineOr(toExtensions(handler, event, event, null), handler.onKeyUp, () => handler.onKeyUp?.(event));
         }
     }
+    /**
+     * Runs the receiver of the mode of the engine when the route leads to it
+     *
+     * @param receiver - The receiver of the mode of the engine, to tell whether it has one
+     * @returns Whether a receiver took the event
+     */
+    function engineOr(route, receiver, run) {
+        if (route !== 'engine')
+            return route === 'consumed';
+        run();
+        return receiver !== undefined;
+    }
     function handleClick(handler, event) {
         handler.onClick?.(event);
     }

package/dist/dispatcher/normalizer.js

@@ -77,7 +77,7 @@ export function createInputNormalizer(map, options = {}) {
     const canvas = map.getCanvas();
     const listeners = new Set();
     const opts = { ...DEFAULT_OPTIONS, ...options };
-    const profiles = createProfiles(opts);
+    let profiles = createProfiles(opts);
     // State management
     let press = null;
     /**
@@ -509,5 +509,9 @@ export function createInputNormalizer(map, options = {}) {
     function off(handler) {
         listeners.delete(handler);
     }
-    return { attach, detach, on, off };
+    const setDragThreshold = (px) => {
+        opts.dragThreshold = px;
+        profiles = createProfiles(opts);
+    };
+    return { attach, detach, on, off, setDragThreshold };
 }

package/dist/dispatcher/types.d.ts

@@ -22,7 +22,7 @@ export interface ModifierKeys {
  * `'touch'` is one finger of a touch screen, `'pen'` a stylus (reported either through
  * the touch events, as on iPadOS, or through the mouse events the browser emits for
  * it), and `'mouse'` everything else. Input with no `pointerType` (synthetic input
- * through `draw.input`, for example) is treated as `'mouse'`.
+ * of the tests, for example) is treated as `'mouse'`.
  */
 export type PointerType = 'mouse' | 'touch' | 'pen';
 /**
@@ -68,6 +68,11 @@ export interface MouseNormalizedEvent {
      * which synthetic input chooses whether to go through snapping.
      */
     snap?: boolean;
+    /**
+     * Whether the event was made from code (`draw.drawing`) at an exact position, not by the
+     * pointer; the modes apply no click tolerance to it (`DrawPointerEvent.programmatic`)
+     */
+    programmatic?: boolean;
 }
 /**
  * A normalized drag event: the start, each move, the end or the cancellation of a press

package/dist/extension/feature-handler.d.ts

@@ -1,182 +1 @@
-/**
- * The feature handler contract of an extension
- *
- * The shape an extension implements to add a custom feature type: its renderer, its hit
- * testing, its box selection, its bounding boxes, its resize and its snapping candidates, all
- * registered at once with `registerFeatureHandler`. It is types only and sits low in the layer
- * order, so the view, snapping and operations layers read it without reaching up into api.
- */
-import type { BoxSelectionStrategy } from '../dispatcher/hit-test/box-strategy.js';
-import type { HitTestStrategy } from '../dispatcher/hit-test/strategies/index.js';
-import type { ResizeState } from '../operations/resize.js';
-import type { HandleType } from '../shared/config/constants.js';
-import type { BoundingBox, Coordinate, Feature } from '../shared/types/model.js';
-import type { BoundingBoxCoords } from '../shared/types/selection-box.js';
-import type { SnapCandidate, SnapProviderContext } from '../snapping/types.js';
-import type { HandleInfo } from '../view/ui/handles.js';
-import type { PointFrameExtent } from '../view/ui/selection-ui/index.js';
-import type { CustomFeatureRenderer } from './renderers.js';
-/**
- * Custom resize result
- *
- * The result of the resize computation for a custom feature.
- * Used when processing different from the standard resize (changing scale) is needed.
- */
-export interface CustomResizeResult {
-    /** The new coordinates */
-    coordinates: Coordinate;
-    /** The new width (in pixels, optional) */
-    width?: number;
-    /** The new height (in pixels, optional) */
-    height?: number;
-}
-/**
- * The type of a custom resize computation function
- */
-export type CustomResizeCalculator = (handle: HandleType, state: ResizeState, currentLngLat: {
-    lng: number;
-    lat: number;
-}, feature: Feature) => CustomResizeResult | null;
-/**
- * A custom feature type: how its features are drawn, hit, selected, resized and snapped to
- *
- * Register it with `draw.registerFeatureHandler(handler)`, usually from `onInstall` of a
- * {@link Plugin}. The registration belongs to that draw instance, and the returned function
- * removes it. Features of the type are ordinary features in the Store (`type` is the name of
- * the handler), so they are saved, exported, grouped and stacked like the built-in types;
- * GeoJSON export writes the type in `maplibre-gl-draw:featureType` so that it comes back.
- *
- * `type`, `renderer` and `hitTest` are required. The rest have fallbacks: box selection and
- * the bounding box use the coordinates, and without `getSelectionBoundingBox` no selection UI
- * is drawn.
- *
- * @example
- * ```ts
- * import type { CustomFeatureHandler, Feature } from '@sakuzu/maplibre-gl-draw';
- *
- * // A "marker" type: one coordinate, drawn as a square, hit within the tolerance
- * const distanceTo = (feature: Feature, [lng, lat]: [number, number]) => {
- *   const [x, y] = feature.coordinates as [number, number];
- *   return Math.hypot(x - lng, y - lat);
- * };
- *
- * const markerHandler: CustomFeatureHandler = {
- *   type: 'marker',
- *   renderer: markerRenderer, // see CustomFeatureRenderer
- *   hitTest: {
- *     geometryType: 'marker',
- *     test: (feature, coordinate, tolerance) => distanceTo(feature, coordinate) <= tolerance,
- *     distance: (feature, coordinate) => distanceTo(feature, coordinate),
- *   },
- * };
- *
- * const unregister = draw.registerFeatureHandler(markerHandler);
- * draw.addFeature({ type: 'marker', coordinates: [139.767, 35.681] });
- * ```
- */
-export interface CustomFeatureHandler {
-    /** The feature type name */
-    readonly type: string;
-    /** The custom renderer */
-    readonly renderer: CustomFeatureRenderer;
-    /** The custom hit testing strategy */
-    readonly hitTest: HitTestStrategy;
-    /** The custom box selection strategy (when omitted, a coordinate-based fallback is used) */
-    readonly boxSelection?: BoxSelectionStrategy;
-    /**
-     * The resize strategy (applied when computeCustomResize returns null)
-     * - 'scale': changes the scale property (as an Image does)
-     * - 'coordinates': changes the coordinates directly (the same as Polygon and LineString)
-     * - when omitted: a generic check (decided by the presence of the scale property)
-     */
-    readonly resizeStrategy?: 'scale' | 'coordinates';
-    /**
-     * Bounding box computation
-     *
-     * Used for viewport filtering in SpatialIndex.
-     * When omitted, a simple bounding box is computed from the coordinates.
-     *
-     * @param feature The target feature
-     * @param tileSize The tile size (512 by default)
-     */
-    getBoundingBox?(feature: Feature, tileSize: number): BoundingBox;
-    /**
-     * The additional reach for narrowing down candidates (in CSS pixels)
-     *
-     * The first stage of hit testing narrows down candidates with a radius equivalent to
-     * clickTolerance, so when the hitTest strategy of this type treats a wider area as a hit
-     * (icons and the like), the candidate is dropped before the precise test is reached.
-     * Registering "how far from the center a hit can occur" here widens the candidate search
-     * radius by that much.
-     *
-     * The test itself is still decided by the hitTest strategy as before (only the number of
-     * candidates increases slightly). A value that changes with zoom or with settings is
-     * registered as a function (it is evaluated on every query).
-     */
-    readonly candidateReachPx?: number | (() => number);
-    /**
-     * The half width and half height of the selection box of a zero-area point (in CSS pixels)
-     *
-     * A point keeps its zero area and is treated with the "point appearance" (box only, no resize
-     * or rotation handles, move inside the box). This function only decides the dimensions of that
-     * box (the special treatment of zero area itself does not change).
-     *
-     * When it is omitted, or returns null, the default 12px square is used.
-     *
-     * @param feature The target feature
-     */
-    getPointFrameExtent?(feature: Feature): PointFrameExtent | null;
-    /**
-     * Bounding box computation for the selection UI
-     *
-     * Used for the visual feedback of the selected state (bounding box, handles).
-     * Returns an OBB (Oriented Bounding Box) that takes rotation into account.
-     * When omitted, no selection UI is drawn.
-     *
-     * @param feature The target feature
-     * @param tileSize The tile size (512 by default)
-     */
-    getSelectionBoundingBox?(feature: Feature, tileSize: number): BoundingBoxCoords;
-    /**
-     * Returns additional resize handles
-     *
-     * Returns the handles to display in addition to the standard four corner handles.
-     * When omitted, only the four corner handles are shown.
-     * Called only for a single selection.
-     *
-     * @param feature The target feature
-     * @param bbox The bounding box for the selection UI
-     */
-    getAdditionalResizeHandles?(feature: Feature, bbox: BoundingBoxCoords): HandleInfo[];
-    /**
-     * Custom resize computation
-     *
-     * Provides custom resize logic such as edge-midpoint handles.
-     * Returning null applies the standard resize (changing scale).
-     *
-     * @param handle The type of the handle being operated
-     * @param state The state of the resize operation
-     * @param currentLngLat The current mouse coordinate
-     * @param feature The target feature
-     */
-    computeCustomResize?(handle: HandleType, state: ResizeState, currentLngLat: {
-        lng: number;
-        lat: number;
-    }, feature: Feature): CustomResizeResult | null;
-    /**
-     * Returns the snapping candidates
-     *
-     * An extension point that lets a custom type provide its own vertices and edges as snapping
-     * targets. The built-in vertex provider calls this when there is a registration for the type
-     * of the target feature (when it is called, the standard enumeration of the vertices and edges
-     * of that feature is not performed).
-     *
-     * The returned candidates may be either point candidates that have a coordinate
-     * (kind: 'vertex' and the like) or segment candidates that have two endpoints (kind: 'edge').
-     * The nearest point on a segment candidate is computed by SnapService.
-     *
-     * @param feature The target feature
-     * @param ctx The snapping context (includes the cursor position, the tolerance and exclusions)
-     */
-    getSnapTargets?(feature: Feature, ctx: SnapProviderContext): SnapCandidate[];
-}
+export {};

package/dist/extension/index.d.ts

@@ -1,9 +1,6 @@
 /**
- * The contracts an extension implements
- *
- * The types a plugin, a custom feature type or an overlay implements to plug into the
- * extension points of a draw instance. The registration itself is on the instance
- * (`registerFeatureHandler`, `addOverlayRenderer` and so on).
+ * The contracts of the engine for the feature types that are not built in and for the
+ * overlays. The extension contract of `api/extension/` is installed into them.
  */
-export type { CustomFeatureHandler, CustomResizeCalculator, CustomResizeResult, } from './feature-handler.js';
-export type { CustomFeatureRenderer, CustomOverlayRenderer, CustomRendererDrawContext, LayerAwareOverlayRenderer, } from './renderers.js';
+export type { FeatureTypeHandler, TypeResizeCalculator, TypeResizeResult, } from './feature-handler.js';
+export type { EngineOverlayRenderer, FeatureTypeRenderer, FrameDrawContext, LayeredOverlayRenderer, } from './renderers.js';