@sakuzu/maplibre-gl-draw 1.0.0

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

@@ -0,0 +1,333 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { clickCopies, toleranceDegrees } from './local-frame.js';
+import { DEFAULT_HIT_TEST_OPTIONS, HitTestStrategyRegistry } from './strategies/base.js';
+import { CircleHitTestStrategy } from './strategies/circle.js';
+import { ImageHitTestStrategy } from './strategies/image.js';
+import { LineHitTestStrategy } from './strategies/line.js';
+import { MultiLineStringHitTestStrategy, MultiPointHitTestStrategy, MultiPolygonHitTestStrategy, } from './strategies/multi.js';
+import { PointHitTestStrategy } from './strategies/point.js';
+import { PolygonHitTestStrategy } from './strategies/polygon.js';
+import { createVisibilityLookup } from './visibility-lookup.js';
+/**
+ * The types tested in screen space (the symbols drawn without a depth test)
+ *
+ * Polygons, lines, circles and images are draped onto the ground surface and are occluded
+ * correctly by depth, so the longitude/latitude path remains the correct one for them.
+ */
+const SCREEN_SPACE_TYPES = new Set(['Point', 'MultiPoint']);
+/**
+ * The HitTestService implementation
+ *
+ * @internal
+ */
+export class HitTestServiceImpl {
+    constructor(store, spatialIndex, options = {}) {
+        Object.defineProperty(this, "spatialIndex", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "registry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "imageStrategy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The extra reach (in CSS pixels) for narrowing down the candidates, per feature type */
+        Object.defineProperty(this, "candidateReach", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** The anchor projection of the symbols (terrain aware; without it only the conventional
+         * path is used) */
+        Object.defineProperty(this, "anchorScreen", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The shape a feature is drawn with (the stored shape when there is no resolver) */
+        Object.defineProperty(this, "drawnShape", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.store = store;
+        this.spatialIndex = spatialIndex;
+        this.anchorScreen = options.anchorScreen ?? null;
+        this.drawnShape = options.drawnShape ?? ((feature) => feature);
+        this.options = { ...DEFAULT_HIT_TEST_OPTIONS, ...options };
+        const tileSize = options.tileSize ?? 512;
+        // Register the default strategies
+        this.registry = new HitTestStrategyRegistry();
+        this.registry.register(new PointHitTestStrategy());
+        this.registry.register(new LineHitTestStrategy());
+        this.registry.register(new PolygonHitTestStrategy());
+        this.registry.register(new CircleHitTestStrategy());
+        // The Multi geometries (a hit if any part is hit / the distance is the minimum over the
+        // parts)
+        this.registry.register(new MultiPointHitTestStrategy());
+        this.registry.register(new MultiLineStringHitTestStrategy());
+        this.registry.register(new MultiPolygonHitTestStrategy());
+        // Freehand uses the same strategy as LineString
+        const freehandStrategy = new LineHitTestStrategy();
+        // Create a wrapper with geometryType changed to Freehand
+        this.registry.register({
+            geometryType: 'Freehand',
+            test: freehandStrategy.test.bind(freehandStrategy),
+            distance: freehandStrategy.distance.bind(freehandStrategy),
+            testDistance: freehandStrategy.testDistance.bind(freehandStrategy),
+        });
+        // The Image strategy (it depends on the zoom level and the tile size)
+        this.imageStrategy = new ImageHitTestStrategy(tileSize);
+        this.registry.register(this.imageStrategy);
+    }
+    /**
+     * Updates the tile size
+     */
+    setTileSize(tileSize) {
+        this.imageStrategy.setTileSize(tileSize);
+    }
+    /**
+     * Registers a custom strategy
+     */
+    registerStrategy(strategy) {
+        return this.registry.register(strategy);
+    }
+    /**
+     * Registers the extra reach for narrowing down the candidates
+     *
+     * A type whose value changes with the zoom or with settings is registered as a function
+     * (it is evaluated on every query).
+     */
+    registerCandidateReach(type, reachPx) {
+        this.candidateReach.set(type, reachPx);
+        return () => {
+            if (this.candidateReach.get(type) === reachPx)
+                this.candidateReach.delete(type);
+        };
+    }
+    /**
+     * The maximum of the registered extra reaches (in CSS pixels)
+     *
+     * Widening the candidate set is cheap (the precise test of the second stage drops the
+     * extras), so the search is not split per type and is done once with the single maximum.
+     */
+    maxCandidateReachPx() {
+        let max = 0;
+        for (const reach of this.candidateReach.values()) {
+            const value = typeof reach === 'function' ? reach() : reach;
+            if (Number.isFinite(value) && value > max)
+                max = value;
+        }
+        return max;
+    }
+    /**
+     * Widens the radius of the candidate search (degrees of longitude) by the extra reach
+     *
+     * The degrees per pixel are obtained by dividing the already computed toleranceLngLat by
+     * clickTolerance (so no additional call to unproject is made). Only when clickTolerance is
+     * 0 is one pixel measured directly.
+     *
+     * The radius is a square box in degrees. A latitude reach needs only radius * cos φ
+     * (local-frame.ts), so the box never misses a candidate.
+     */
+    expandSearchRadius(toleranceLngLat, tolerancePx, screenPoint, unproject) {
+        const reachPx = this.maxCandidateReachPx();
+        if (reachPx <= 0)
+            return toleranceLngLat;
+        const degPerPx = tolerancePx > 0 ? toleranceLngLat / tolerancePx : toleranceDegrees(unproject, screenPoint, 1);
+        return toleranceLngLat + reachPx * degPerPx;
+    }
+    /**
+     * Returns the frontmost hit in the visual stacking order
+     *
+     * The arbitration walks the indices of orderedFeatures in descending order (from the
+     * front) and takes the first feature that satisfies test(). The distance is not used (the
+     * visual stacking order is the only order: a point on top of a polygon wins, and a
+     * polygon in front occludes a point behind it).
+     */
+    hitTest(screenPoint, unproject, orderedFeatures) {
+        const results = this.hitTestAll(screenPoint, unproject, orderedFeatures);
+        if (results.length === 0)
+            return null;
+        if (results.length === 1)
+            return results[0];
+        const byId = new Map(results.map((r) => [r.feature.id, r]));
+        for (let i = orderedFeatures.length - 1; i >= 0; i--) {
+            const result = byId.get(orderedFeatures[i].id);
+            if (result)
+                return result;
+        }
+        // The candidates are narrowed down from orderedFeatures, so this is never reached
+        // (a safety net)
+        return results[0];
+    }
+    hitTestAll(screenPoint, unproject, orderedFeatures) {
+        const lngLat = unproject(screenPoint);
+        const coordinate = [lngLat.lng, lngLat.lat];
+        // The tolerance is a screen length. It is converted into degrees of longitude at the
+        // click latitude by measuring the ground length of clickTolerance pixels, so it does not
+        // depend on the bearing (see local-frame.ts)
+        const tolerance = this.options.clickTolerance;
+        const toleranceLngLat = toleranceDegrees(unproject, screenPoint, tolerance);
+        // Stage 1: narrow down the candidates with the spatial index.
+        // The search radius is widened by the registered extra reach
+        // (registerCandidateReach). Unlike the approach of baking the appearance into the bbox
+        // of the index, this does not depend on the state or the zoom. The tolerance passed to
+        // the second stage is toleranceLngLat as before (only the candidate set widens; the
+        // semantics of a hit are decided by the strategy).
+        const searchRadius = this.expandSearchRadius(toleranceLngLat, tolerance, screenPoint, unproject);
+        // The click on each copy of the world it can reach (the stored copy alone away from the
+        // antimeridian; local-frame.ts)
+        const copies = clickCopies(coordinate, searchRadius);
+        const candidatesByCopy = copies.map((copy) => new Set(this.spatialIndex.findNear(copy, searchRadius)));
+        const isCandidate = (id) => candidatesByCopy.some((set) => set.has(id));
+        // Filter down to the visible features only.
+        // A lock forbids interaction, not selection, so nothing is excluded here for it
+        // (a locked feature can still be selected, and moving / transforming / deleting it is
+        // rejected on the interaction side).
+        // Hidden features (visible=false on the feature / layer / group) are not drawn, so they
+        // are excluded from the selection targets.
+        // Layers and groups are looked up only once per container (not once per feature).
+        const selectable = createVisibilityLookup(this.store);
+        const visibleCandidates = orderedFeatures.filter((f) => {
+            if (!isCandidate(f.id))
+                return false;
+            return selectable(f);
+        });
+        // Symbols (points) are tested in screen space. This works only while the terrain is
+        // enabled; when it is disabled null is returned and the conventional path is used as
+        // before.
+        const degPerPx = tolerance > 0 ? toleranceLngLat / tolerance : 0;
+        const screen = this.hitTestAnchorsInScreenSpace(screenPoint, orderedFeatures, tolerance, degPerPx, selectable);
+        // Stage 2: the precise test
+        const results = screen ? [...screen.results] : [];
+        for (const feature of visibleCandidates) {
+            // Types already tested in screen space are not sent down the longitude/latitude path
+            // (they would be added twice)
+            if (screen?.handledTypes.has(feature.type))
+                continue;
+            const strategy = this.registry.get(feature.type);
+            if (!strategy)
+                continue;
+            // The feature is tested against the click on each copy it is a candidate of, and the
+            // nearest hit counts. It is tested in the shape it is drawn with (the result keeps the
+            // stored feature)
+            const shape = this.drawnShape(feature);
+            let best = null;
+            for (let i = 0; i < copies.length; i++) {
+                if (!candidatesByCopy[i].has(feature.id))
+                    continue;
+                const copy = copies[i];
+                let distance = null;
+                // A strategy that has testDistance finishes the test and the distance computation in
+                // a single scan
+                if (strategy.testDistance) {
+                    distance = strategy.testDistance(shape, copy, toleranceLngLat);
+                }
+                else if (strategy.test(shape, copy, toleranceLngLat)) {
+                    distance = strategy.distance(shape, copy);
+                }
+                if (distance !== null && (best === null || distance < best))
+                    best = distance;
+            }
+            if (best !== null)
+                results.push({ feature, distance: best });
+        }
+        // Sort by distance
+        results.sort((a, b) => a.distance - b.distance);
+        return results;
+    }
+    /**
+     * Tests the anchors of the symbols in screen coordinates
+     *
+     * The candidates are the points that fall within the field of view. Occluded points are
+     * candidates too (they are drawn without a depth test and are actually visible). The
+     * spatial index is not used: as long as the longitude/latitude obtained by unprojecting
+     * the click point lands on the terrain surface in front, nearness in longitude/latitude
+     * does not agree with nearness on screen.
+     *
+     * The distance is converted back into a longitude difference so that it can be lined up
+     * with the other results (it is multiplied by the longitude difference per screen pixel).
+     * The meaning of the ordering does not change.
+     *
+     * @returns null when the anchor projection is unusable (it falls back to the conventional
+     *   path)
+     */
+    hitTestAnchorsInScreenSpace(screenPoint, orderedFeatures, tolerancePx, degPerPx, selectable) {
+        const projector = this.anchorScreen;
+        if (!projector)
+            return null;
+        const results = [];
+        let usable = false;
+        for (const feature of orderedFeatures) {
+            if (!SCREEN_SPACE_TYPES.has(feature.type))
+                continue;
+            if (!selectable(feature))
+                continue;
+            const reachPx = tolerancePx + this.candidateReachPx(feature.type);
+            const parts = feature.type === 'MultiPoint'
+                ? feature.coordinates
+                : [feature.coordinates];
+            let nearest = Number.POSITIVE_INFINITY;
+            for (const coord of parts) {
+                const point = projector.project(coord);
+                // null means the anchor projection is unusable (the terrain is disabled, or the
+                // point is behind the camera). In the former case nothing at all is projected, so
+                // this whole path is not used.
+                if (!point)
+                    continue;
+                usable = true;
+                const distance = Math.hypot(point.x - screenPoint.x, point.y - screenPoint.y);
+                if (distance < nearest)
+                    nearest = distance;
+            }
+            if (nearest <= reachPx) {
+                results.push({ feature, distance: nearest * degPerPx });
+            }
+        }
+        if (!usable)
+            return null;
+        return { results, handledTypes: SCREEN_SPACE_TYPES };
+    }
+    /**
+     * The extra reach registered for a type (in CSS pixels)
+     */
+    candidateReachPx(type) {
+        const reach = this.candidateReach.get(type);
+        if (reach === undefined)
+            return 0;
+        const value = typeof reach === 'function' ? reach() : reach;
+        return Number.isFinite(value) && value > 0 ? value : 0;
+    }
+    hitTestFeature(feature, coordinate, toleranceLngLat) {
+        const strategy = this.registry.get(feature.type);
+        if (!strategy)
+            return false;
+        return strategy.test(this.drawnShape(feature), coordinate, toleranceLngLat);
+    }
+}

package/dist/dispatcher/hit-test/strategies/base.d.ts

@@ -0,0 +1,136 @@
+/**
+ * HitTestStrategy
+ *
+ * Interface for the precise test logic of each geometry type.
+ */
+import type { Coordinate, Feature, FeatureType } from '../../../store/types.js';
+/**
+ * A vertex handle or a midpoint handle that was hit.
+ */
+export interface VertexHit {
+    /** The id of the feature the handle belongs to */
+    featureId: string;
+    /** The index of the vertex in its ring or line (for a midpoint, the vertex before it) */
+    vertexIndex: number;
+    /** The index of the ring for a Polygon (0 = the outer ring) */
+    ringIndex?: number;
+    /** The position of the handle, `[lng, lat]` in degrees */
+    coordinate: Coordinate;
+    /** Whether it is a vertex or the midpoint of an edge */
+    type: 'vertex' | 'midpoint';
+}
+/**
+ * A feature hit by a click, with its distance from the click.
+ */
+export interface HitTestResult {
+    /** The feature that was hit */
+    feature: Feature;
+    /**
+     * The distance from the click to the feature, in degrees of longitude at the click latitude
+     * (see {@link HitTestStrategy})
+     */
+    distance: number;
+}
+/**
+ * The hit tolerances, in screen px.
+ */
+export interface HitTestOptions {
+    /** Tolerance for the click test (pixels) */
+    clickTolerance: number;
+    /** Tolerance for vertex handles (pixels) */
+    vertexTolerance: number;
+    /** Tolerance for midpoint handles (pixels) */
+    midpointTolerance: number;
+}
+/**
+ * Default hit test options
+ *
+ * The only default of the click tolerance: the `clickTolerance` option of a draw instance
+ * falls back to it too.
+ */
+export declare const DEFAULT_HIT_TEST_OPTIONS: HitTestOptions;
+/**
+ * The precise hit test of one feature type, as registered through the `hitTest` of a
+ * `CustomFeatureHandler`.
+ *
+ * The library first narrows the candidates with its spatial index and then calls `test` on
+ * each candidate from the front; the first that returns `true` receives the click. The
+ * tolerance is the click tolerance (a screen length) expressed in degrees of longitude
+ * at the click latitude. It does not depend on the bearing. To compare a latitude
+ * difference, divide it by cos φ of the click latitude (or multiply the tolerance by cos φ):
+ * one degree of latitude is 1 / cos φ times longer on screen than one degree of longitude.
+ * Distances are returned in the same unit.
+ *
+ * @example
+ * ```ts
+ * import type { HitTestStrategy } from '@sakuzu/maplibre-gl-draw';
+ *
+ * // A marker type hit within the tolerance around its single position
+ * const markerHitTest: HitTestStrategy = {
+ *   geometryType: 'Marker',
+ *   test(feature, [lng, lat], tolerance) {
+ *     return this.distance(feature, [lng, lat]) <= tolerance;
+ *   },
+ *   distance(feature, [lng, lat]) {
+ *     const [x, y] = feature.coordinates as [number, number];
+ *     const cos = Math.cos((lat * Math.PI) / 180);
+ *     return Math.hypot(x - lng, (y - lat) / cos);
+ *   },
+ * };
+ * ```
+ */
+export interface HitTestStrategy {
+    /** The feature type this strategy tests; a registration replaces the one for the type */
+    readonly geometryType: FeatureType;
+    /**
+     * Tests whether the feature was hit
+     *
+     * @param feature The feature to test
+     * @param coordinate The click coordinate [lng, lat]
+     * @param toleranceLngLat The tolerance (degrees of longitude at the click latitude)
+     * @returns true if it was hit
+     */
+    test(feature: Feature, coordinate: Coordinate, toleranceLngLat: number): boolean;
+    /**
+     * Computes the distance to the center or the nearest point of the feature
+     *
+     * @param feature The target feature
+     * @param coordinate The reference coordinate [lng, lat]
+     * @returns The distance (degrees of longitude at the reference latitude)
+     */
+    distance(feature: Feature, coordinate: Coordinate): number;
+    /**
+     * Performs the hit test and the distance computation in a single scan
+     *
+     * When it is equivalent to test() returning true, it returns the same distance as
+     * distance(). Outside the tolerance it returns null. Strategies without an
+     * implementation are substituted by test() + distance().
+     *
+     * @param feature The feature to test
+     * @param coordinate The click coordinate [lng, lat]
+     * @param toleranceLngLat The tolerance (degrees of longitude at the click latitude)
+     * @returns The distance (same unit) if within the tolerance, null if outside
+     */
+    testDistance?(feature: Feature, coordinate: Coordinate, toleranceLngLat: number): number | null;
+}
+/**
+ * Hit testing strategy registry
+ */
+export declare class HitTestStrategyRegistry {
+    private strategies;
+    /**
+     * Registers a strategy
+     *
+     * @returns a function that cancels the registration and puts back the strategy it replaced
+     *   (it does nothing once another strategy has been registered for the type)
+     */
+    register(strategy: HitTestStrategy): () => void;
+    /**
+     * Gets a strategy
+     */
+    get(geometryType: FeatureType): HitTestStrategy | undefined;
+    /**
+     * Gets all registered strategies
+     */
+    getAll(): HitTestStrategy[];
+}

package/dist/dispatcher/hit-test/strategies/base.js

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Default hit test options
+ *
+ * The only default of the click tolerance: the `clickTolerance` option of a draw instance
+ * falls back to it too.
+ */
+export const DEFAULT_HIT_TEST_OPTIONS = {
+    clickTolerance: 6,
+    vertexTolerance: 8,
+    midpointTolerance: 6,
+};
+/**
+ * Hit testing strategy registry
+ */
+export class HitTestStrategyRegistry {
+    constructor() {
+        Object.defineProperty(this, "strategies", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Registers a strategy
+     *
+     * @returns a function that cancels the registration and puts back the strategy it replaced
+     *   (it does nothing once another strategy has been registered for the type)
+     */
+    register(strategy) {
+        return registerRestoring(this.strategies, strategy.geometryType, strategy);
+    }
+    /**
+     * Gets a strategy
+     */
+    get(geometryType) {
+        return this.strategies.get(geometryType);
+    }
+    /**
+     * Gets all registered strategies
+     */
+    getAll() {
+        return Array.from(this.strategies.values());
+    }
+}
+/**
+ * Sets a value in a registry keyed by type, and returns the function that cancels it: the
+ * value it replaced comes back (a built-in strategy overridden by an extension, for example).
+ * Cancelling after another value has been set for the key does nothing.
+ *
+ * @internal
+ */
+export function registerRestoring(registry, key, value) {
+    const replaced = registry.get(key);
+    registry.set(key, value);
+    return () => {
+        if (registry.get(key) !== value)
+            return;
+        if (replaced === undefined)
+            registry.delete(key);
+        else
+            registry.set(key, replaced);
+    };
+}

package/dist/dispatcher/hit-test/strategies/circle.d.ts

@@ -0,0 +1,10 @@
+import type { Coordinate, Feature, FeatureType } from '../../../store/types.js';
+import type { HitTestStrategy } from './base.js';
+/**
+ * Hit testing strategy for the Circle type
+ */
+export declare class CircleHitTestStrategy implements HitTestStrategy {
+    readonly geometryType: FeatureType;
+    test(feature: Feature, coordinate: Coordinate, toleranceLngLat: number): boolean;
+    distance(feature: Feature, coordinate: Coordinate): number;
+}

package/dist/dispatcher/hit-test/strategies/circle.js

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * CircleHitTestStrategy
+ *
+ * Hit testing strategy for Circle features.
+ * It tests whether the distance from the center is within the radius.
+ */
+import { haversineDistanceMeters, metersToLng } from '../../../shared/math/index.js';
+import { getCircleRadius } from '../../../shared/utils/property.js';
+/**
+ * Hit testing strategy for the Circle type
+ */
+export class CircleHitTestStrategy {
+    constructor() {
+        Object.defineProperty(this, "geometryType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'Circle'
+        });
+    }
+    test(feature, coordinate, toleranceLngLat) {
+        const center = feature.coordinates;
+        const radiusMeters = getCircleRadius(feature);
+        if (radiusMeters === undefined || radiusMeters <= 0) {
+            return false;
+        }
+        // Compute the distance from the center (meters)
+        const distanceMeters = haversineDistanceMeters(coordinate, center);
+        // Convert the tolerance to meters
+        // toleranceLngLat is a longitude difference, so convert it using the latitude
+        const toleranceMeters = Math.abs(metersToLng(1, center[1])) > 0
+            ? (toleranceLngLat / metersToLng(1, center[1])) * 1
+            : 0;
+        // Simplified tolerance computation, taking the pixel tolerance into account
+        // The actual tolerance is roughly 10-20 meters (it depends on the zoom level)
+        const effectiveTolerance = Math.max(toleranceMeters, 10);
+        return distanceMeters <= radiusMeters + effectiveTolerance;
+    }
+    distance(feature, coordinate) {
+        const center = feature.coordinates;
+        const radiusMeters = getCircleRadius(feature);
+        if (radiusMeters === undefined || radiusMeters <= 0) {
+            return Number.POSITIVE_INFINITY;
+        }
+        // Distance from the center (meters)
+        const distanceMeters = haversineDistanceMeters(coordinate, center);
+        // Return the distance from the boundary of the circle
+        // Negative inside (the closer to the boundary, the closer to 0), positive outside
+        const distanceFromEdge = distanceMeters - radiusMeters;
+        // For hit testing, return the absolute distance from the boundary
+        // Inside it is the distance to the boundary, and outside it is also the distance to it
+        return Math.abs(distanceFromEdge);
+    }
+}

package/dist/dispatcher/hit-test/strategies/image.d.ts

@@ -0,0 +1,22 @@
+import type { Coordinate, Feature } from '../../../store/types.js';
+import type { HitTestStrategy } from './base.js';
+/**
+ * ImageHitTestStrategy
+ */
+export declare class ImageHitTestStrategy implements HitTestStrategy {
+    readonly geometryType: "Image";
+    private tileSize;
+    constructor(tileSize?: number);
+    /**
+     * Updates the tile size
+     */
+    setTileSize(tileSize: number): void;
+    test(feature: Feature, coordinate: Coordinate, toleranceLngLat: number): boolean;
+    distance(feature: Feature, coordinate: Coordinate): number;
+    /**
+     * Computes the dimensions (in degrees) and the rotation of an image feature
+     *
+     * It uses the same size computation logic as ImageRenderer
+     */
+    private computeDims;
+}