@sakuzu/maplibre-gl-draw 1.0.0

package/dist/dispatcher/hit-test/topmost.js

@@ -0,0 +1,157 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { getDisplayFeatures } from '../../store/local-visibility.js';
+import { hitTestFeatureCompanions } from '../../view/feature-companion.js';
+import { clickCopies } from './local-frame.js';
+import { DEFAULT_HIT_TEST_OPTIONS } from './strategies/base.js';
+import { createVisibilityLookup } from './visibility-lookup.js';
+/**
+ * Creates the hit tester of the unified z traversal
+ *
+ * @internal
+ */
+export function createTopmostHitTester(deps) {
+    const { store, hitTestService, unproject, toleranceLngLat, datasets } = deps;
+    const test = (feature, coordinate, tolerance) => hitTestService.hitTestFeature(feature, coordinate, tolerance);
+    /**
+     * Builds the context of the companion hits (null unless the configuration can perform
+     * the test)
+     *
+     * It is not built when no provider at all is registered, so the conventional traversal
+     * changes neither in cost nor in path.
+     */
+    const companionContext = (point) => {
+        if (!deps.companions?.any())
+            return null;
+        const project = deps.project;
+        const getZoom = deps.getZoom;
+        if (!project || !getZoom)
+            return null;
+        return {
+            point,
+            project,
+            unproject: (p) => {
+                const { lng, lat } = unproject(p);
+                return { lng, lat };
+            },
+            zoom: getZoom(),
+            tolerancePx: deps.clickTolerancePx ?? DEFAULT_HIT_TEST_OPTIONS.clickTolerance,
+        };
+    };
+    /**
+     * Asks for a hit on the companions of one feature (a feature that is not visible is not
+     * asked)
+     */
+    const companionOf = (feature, context, visible) => {
+        if (!context)
+            return null;
+        if (!visible(feature))
+            return null;
+        const companions = deps.companions;
+        if (!companions)
+            return null;
+        const companion = hitTestFeatureCompanions(companions, feature, context);
+        return companion ? { kind: 'companion', companion } : null;
+    };
+    return (point, options) => {
+        const orderedFeatures = options?.orderedFeatures ?? getDisplayFeatures(store);
+        const companion = companionContext(point);
+        // Within one hit test, the visibility of a layer or a group is looked up only once per
+        // container.
+        const visible = createVisibilityLookup(store);
+        // On a map with no dataset at all (none is visible), the cost is kept the same as
+        // the conventional path. The spatial index is queried only once as well.
+        if (!datasets?.hasAny()) {
+            if (!companion) {
+                const hit = hitTestService.hitTest(point, unproject, orderedFeatures);
+                return hit ? { kind: 'store', feature: hit.feature } : null;
+            }
+            // A companion sits one z below the feature itself, so the features are examined one
+            // at a time from the front in the order "the feature itself -> its companions". The
+            // spatial index is queried only once.
+            const storeHits = new Set(hitTestService.hitTestAll(point, unproject, orderedFeatures).map((r) => r.feature.id));
+            for (let i = orderedFeatures.length - 1; i >= 0; i--) {
+                const feature = orderedFeatures[i];
+                if (storeHits.has(feature.id))
+                    return { kind: 'store', feature };
+                const companionHit = companionOf(feature, companion, visible);
+                if (companionHit)
+                    return companionHit;
+            }
+            return null;
+        }
+        const lngLat = unproject(point);
+        const tolerance = toleranceLngLat(point);
+        // The click on each copy of the world it can reach (the stored copy first; local-frame.ts)
+        const copies = clickCopies([lngLat.lng, lngLat.lat], tolerance);
+        const onCopies = (hitOn) => {
+            for (const copy of copies) {
+                const hit = hitOn(copy);
+                if (hit)
+                    return hit;
+            }
+            return null;
+        };
+        // 1. The above-store side
+        const above = onCopies((copy) => datasets.hitTestSide('above-store', copy, tolerance, test));
+        if (above)
+            return toTopHit(above);
+        // 2. The stacking order from the front. One hit test per frame is enough on the Store
+        //    side, so it is performed only once, at the moment a layer entry is first met.
+        let storeHits;
+        let byLayer;
+        const layerOrder = store.getLayerOrder();
+        for (let i = layerOrder.length - 1; i >= 0; i--) {
+            const entryId = layerOrder[i];
+            if (store.getLayer(entryId) !== undefined) {
+                if (!storeHits) {
+                    storeHits = new Set(hitTestService
+                        .hitTestAll(point, unproject, orderedFeatures)
+                        .map((result) => result.feature.id));
+                    byLayer = groupByLayer(orderedFeatures);
+                }
+                // Even when not a single feature itself was hit, a companion can still be hit
+                if (storeHits.size === 0 && !companion)
+                    continue;
+                const features = byLayer?.get(entryId);
+                if (!features)
+                    continue;
+                for (let j = features.length - 1; j >= 0; j--) {
+                    const feature = features[j];
+                    if (storeHits.has(feature.id))
+                        return { kind: 'store', feature };
+                    const companionHit = companionOf(feature, companion, visible);
+                    if (companionHit)
+                        return companionHit;
+                }
+                continue;
+            }
+            const entry = onCopies((copy) => datasets.hitTestEntry(entryId, copy, tolerance, test));
+            if (entry)
+                return toTopHit(entry);
+        }
+        // 3. The below-store side
+        const below = onCopies((copy) => datasets.hitTestSide('below-store', copy, tolerance, test));
+        return below ? toTopHit(below) : null;
+    };
+}
+/**
+ * Converts a dataset hit into a TopHit
+ */
+function toTopHit(hit) {
+    return { kind: 'dataset', dataset: hit.dataset, feature: hit.feature, row: hit.row };
+}
+/**
+ * Splits the features in display order per layer (the order is preserved)
+ */
+function groupByLayer(orderedFeatures) {
+    const byLayer = new Map();
+    for (const feature of orderedFeatures) {
+        const features = byLayer.get(feature.layerId);
+        if (features)
+            features.push(feature);
+        else
+            byLayer.set(feature.layerId, [feature]);
+    }
+    return byLayer;
+}

package/dist/dispatcher/hit-test/visibility-lookup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Visibility lookup for hit testing
+ *
+ * Whether a feature can be selected is decided by the visible flag of the feature itself,
+ * its layer and its group. A single hit test asks this once per feature, so looking the
+ * store up for every feature makes one test O(N^2) on implementations where reading a
+ * layer costs time proportional to the feature count N (such as a replaced DocumentStore
+ * that copies the order array on every read). Here each layer and group is looked up only
+ * once per hit test, and features reuse the result of that lookup.
+ *
+ * The lookup is built for each hit test call (it is never carried over across store changes).
+ */
+import type { Store } from '../../store/store.js';
+import type { Feature } from '../../store/types.js';
+export type VisibilityLookup = (feature: Feature) => boolean;
+/**
+ * Builds the lookup for a single hit test.
+ *
+ * Features that are not visible (any of feature / layer / group has visible=false) are not
+ * drawn, so they are excluded from the targets. A lock forbids interaction, not selection,
+ * so it is not consulted here.
+ */
+export declare function createVisibilityLookup(store: Store): VisibilityLookup;

package/dist/dispatcher/hit-test/visibility-lookup.js

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Builds the lookup for a single hit test.
+ *
+ * Features that are not visible (any of feature / layer / group has visible=false) are not
+ * drawn, so they are excluded from the targets. A lock forbids interaction, not selection,
+ * so it is not consulted here.
+ */
+export function createVisibilityLookup(store) {
+    const layers = new Map();
+    const groups = new Map();
+    const layerVisible = (id) => {
+        let visible = layers.get(id);
+        if (visible === undefined) {
+            const layer = store.getLayer(id);
+            visible = !layer || layer.visible;
+            layers.set(id, visible);
+        }
+        return visible;
+    };
+    const groupVisible = (id) => {
+        let visible = groups.get(id);
+        if (visible === undefined) {
+            const group = store.getGroup(id);
+            visible = !group || group.visible;
+            groups.set(id, visible);
+        }
+        return visible;
+    };
+    return (feature) => {
+        if (!feature.visible)
+            return false;
+        if (!layerVisible(feature.layerId))
+            return false;
+        if (feature.groupId && !groupVisible(feature.groupId))
+            return false;
+        return true;
+    };
+}

package/dist/dispatcher/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dispatcher module
+ *
+ * Responsible for accepting user input and routing it to modes.
+ * The input handling layer of the Flux architecture.
+ *
+ * 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 { BoxSelectionStrategy, BoxSelectionStrategyRegistry, } from './hit-test/box-strategy.js';
+export type { HitTestService, UnprojectFunction } from './hit-test/service.js';
+export type { HitTestOptions, HitTestResult, HitTestStrategy, VertexHit, } from './hit-test/strategies/base.js';
+export { PointHitTestStrategy } from './hit-test/strategies/point.js';
+export type { HitTestTopmost, TopHit, TopmostHitTestOptions } from './hit-test/topmost.js';
+export type { DragNormalizedEvent, KeyNormalizedEvent, MapClickEventPayload, ModifierKeys, MouseNormalizedEvent, NormalizedEvent, PointerOriginalEvent, PointerType, } from './types.js';

package/dist/dispatcher/index.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { PointHitTestStrategy } from './hit-test/strategies/point.js';

package/dist/dispatcher/input-router.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dispatcher/input-router.js

@@ -0,0 +1,288 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { nearestLongitude, wrapLongitude } from '../shared/math/longitude.js';
+/**
+ * The event types that are stopped while the pointer is held
+ *
+ * Only the ones that determine coordinates are stopped. Stopping mousedown /
+ * mouseup / the drag events would also break the pan and zoom of MapLibre.
+ */
+const HELD_EVENT_TYPES = new Set([
+    'click',
+    'dblclick',
+    'mousemove',
+]);
+/**
+ * The first coordinate of a shape being drawn (null when there is none)
+ */
+function firstTentativeCoordinate(tentative) {
+    let value = tentative?.coordinates;
+    while (Array.isArray(value) && Array.isArray(value[0]))
+        value = value[0];
+    if (Array.isArray(value) && typeof value[0] === 'number' && typeof value[1] === 'number') {
+        return value;
+    }
+    return null;
+}
+/**
+ * Brings the longitudes of an event onto the stored copy of the world
+ *
+ * The rule, from the point of view of the pointer:
+ *
+ * - A click, a move or a press on its own lands in [-180, 180], the range the features are
+ *   stored in. This is the same point hit testing starts from (`clickCopies` in
+ *   hit-test/local-frame.ts), so a point placed or a feature picked on the copy east of the
+ *   antimeridian gets its stored longitude
+ * - While a shape is being drawn, the pointer goes to the copy nearest to the first vertex of the
+ *   shape instead, so a line drawn across the antimeridian stays continuous (170 then 190, not
+ *   170 then -170, which would run the other way round the world). Its vertices can then lie a
+ *   little beyond ±180; the rendering and the export deal with that
+ * - A drag moves every coordinate of its events by the one shift decided from where it started
+ *   (`dragStartLngLat`), so the distance dragged never jumps by 360 degrees when the pointer
+ *   crosses the antimeridian during the drag
+ *
+ * Away from the antimeridian, on the main copy of the world, nothing changes and the event is
+ * returned as it is.
+ */
+function toStoredCopy(event, reference) {
+    if (!('lngLat' in event))
+        return event;
+    const anchor = 'dragStartLngLat' in event ? event.dragStartLngLat.lng : event.lngLat.lng;
+    const target = reference ? nearestLongitude(anchor, reference[0]) : wrapLongitude(anchor);
+    const shift = target - anchor;
+    if (shift === 0)
+        return event;
+    const moved = { ...event, lngLat: { lng: event.lngLat.lng + shift, lat: event.lngLat.lat } };
+    if ('dragStartLngLat' in event) {
+        moved.dragStartLngLat = {
+            lng: event.dragStartLngLat.lng + shift,
+            lat: event.dragStartLngLat.lat,
+        };
+    }
+    return moved;
+}
+/**
+ * Creates an InputRouter
+ *
+ * @internal
+ */
+export function createInputRouter(deps) {
+    const { normalizer, modeManager, context, map, pluginManager, displayInteractions, notifyMapClick, snapService, } = deps;
+    let boundHandleEvent = null;
+    /**
+     * Whether input originating from the pointer is currently held
+     *
+     * While the keyboard is determining the coordinates, as with a numeric input
+     * panel, interruption by the real pointer is stopped. What is stopped is only the
+     * events that "determine" coordinates (click / dblclick / mousemove); mousedown /
+     * mouseup / the drag events are let through (so as not to kill the pan and zoom of
+     * MapLibre; drawing modes do not consume them).
+     */
+    let pointerHeld = false;
+    /**
+     * Builds the snapping context
+     *
+     * While a vertex / midpoint is being dragged, the grabbed vertex itself is
+     * excluded (the other vertices of the same feature stay as candidates so that a
+     * ring can be closed). The exclusion can be derived from the drag state of the
+     * Store, so no modification is needed on the select mode side.
+     *
+     * While a move drag is in progress, the features being moved are excluded whole.
+     * A feature being moved travels with the cursor, so if it stayed a candidate it
+     * would always sit inside the tolerance, the cursor would be pulled back to its
+     * own position, and it would repeat "drift every frame by the offset from when it
+     * was grabbed, then leave the tolerance and catch up all at once" (which looks
+     * like a vibration). It is the same reasoning as excludeVertex for a vertex drag,
+     * except that the unit that is removed is the whole feature.
+     *
+     * The feature to prefer when candidates tie is read from the current mode (a
+     * drawing mode returns the boundary it started tracing).
+     */
+    function buildSnapContext(modifiers) {
+        const dragState = context.store.getDragState();
+        const isVertexDrag = dragState?.operation === 'vertex' || dragState?.operation === 'midpoint';
+        const excludeVertex = isVertexDrag && dragState?.activeFeatureId && dragState.activeVertex
+            ? { featureId: dragState.activeFeatureId, vertex: dragState.activeVertex }
+            : undefined;
+        const moving = dragState?.operation === 'move' ? dragState.movingFeatureIds : undefined;
+        const excludeFeatureIds = moving && moving.length > 0 ? new Set(moving) : undefined;
+        const preferFeature = modeManager.getHandler()?.getSnapPreference?.() ?? undefined;
+        return {
+            zoom: map.getZoom(),
+            excludeVertex,
+            excludeFeatureIds,
+            preferFeature,
+            modifiers,
+        };
+    }
+    /**
+     * Replaces lngLat with the snapped coordinates just before delivery to the mode
+     *
+     * When nothing was snapped, the event is returned as-is (no pointless copy).
+     *
+     * Whether snapping is wanted is asked of the current mode per input type
+     * (isSnapEnabledFor). A mode that does not declare it snaps for every input type
+     * (as before).
+     */
+    function applySnap(event, inputType) {
+        if (!snapService || event.snap === false)
+            return event;
+        if (modeManager.getHandler()?.isSnapEnabledFor?.(inputType) === false)
+            return event;
+        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, lngLat: { lng: result.lngLat.lng, lat: result.lngLat.lat } };
+    }
+    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;
+        const handler = modeManager.getHandler();
+        if (!handler)
+            return;
+        // 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 },
+                    });
+                }
+                break;
+            }
+            case 'dblclick':
+                handler.onDoubleClick?.(event);
+                break;
+            case 'mousedown':
+                handleMouseDown(handler, event);
+                break;
+            case 'mouseup':
+                handler.onMouseUp?.(event);
+                break;
+            case 'mousemove': {
+                const snapped = applySnap(event, 'mousemove');
+                // Call the onMouseMove of the plugins (they do not consume it)
+                pluginManager?.handleMouseMove(snapped);
+                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
+                // when coming back).
+                if (handler.modeName === 'select') {
+                    displayInteractions?.handleMouseMove(snapped);
+                }
+                else {
+                    displayInteractions?.reset();
+                }
+                break;
+            }
+            case 'contextmenu':
+                // contextmenu currently has no special handling
+                break;
+            // 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;
+            }
+            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);
+                handler.onDragMove?.(snapped);
+                break;
+            }
+            case 'dragend': {
+                const snapped = applySnap(event, 'dragend');
+                handler.onDragEnd?.(snapped);
+                break;
+            }
+            // 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;
+                }
+                handler.onKeyDown?.(event);
+                break;
+            case 'keyup':
+                handler.onKeyUp?.(event);
+                break;
+        }
+    }
+    function handleClick(handler, event) {
+        handler.onClick?.(event);
+    }
+    function handleMouseDown(handler, event) {
+        if (handler.onMouseDown) {
+            const consumed = handler.onMouseDown(event);
+            // When the event has been consumed, stop it from propagating to MapLibre
+            if (consumed) {
+                const original = event.originalEvent;
+                original.stopPropagation();
+                // MapLibre listens to touchstart as a passive listener, where preventDefault() is
+                // ignored and makes the browser warn. The pan and the pinch of a touch are left to
+                // MapLibre, so only a mouse press has its default action prevented.
+                if (!('touches' in original)) {
+                    original.preventDefault();
+                }
+            }
+        }
+    }
+    function start() {
+        boundHandleEvent = handleEvent;
+        normalizer.on(boundHandleEvent);
+    }
+    function stop() {
+        if (boundHandleEvent) {
+            normalizer.off(boundHandleEvent);
+            boundHandleEvent = null;
+        }
+    }
+    return {
+        start,
+        stop,
+        dispatch: (event) => handleEvent(event, { synthetic: true }),
+        setPointerHold(held) {
+            pointerHeld = held;
+        },
+        isPointerHeld() {
+            return pointerHeld;
+        },
+    };
+}

package/dist/dispatcher/normalizer.d.ts

@@ -0,0 +1 @@
+export {};