@sakuzu/maplibre-gl-draw 1.0.0

package/dist/snapping/providers/shared.js

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Shared helpers of the built-in snapping providers
+ *
+ * They gather the narrowing down of candidate features and the listing of edges that
+ * the providers originating from the Store (vertex, edge, intersection) use in
+ * common. The behavior is the same as in the original providers/store.ts; only the
+ * location was moved so that the intersection provider can reuse it.
+ */
+import { getSegmentGrid, querySegmentIndicesInBBox, SEGMENT_INDEX_THRESHOLD, } from '../../shared/math/segment-grid.js';
+import { forEachPart, hasSnapEdges, isClosedCoords, isInBBox, makeRefFactory, } from '../../shared/utils/feature-segments.js';
+import { isSameVertexRef } from '../../shared/utils/vertex-ref.js';
+import { isLocallyHidden } from '../../store/local-visibility.js';
+import { computeVertexHandles } from '../../view/ui/handles.js';
+export { collectFeatureSegments, collectFeatureSegmentsInBBox, hasSnapEdges, segmentIntersectsBBox, } from '../../shared/utils/feature-segments.js';
+/**
+ * Whether the feature is a snapping target (whether it is displayed)
+ *
+ * It looks at both the shared visible cascade (feature / group / layer) and the local
+ * hiding that applies to this client only.
+ */
+export function isSnapVisible(feature, store) {
+    if (!feature.visible)
+        return false;
+    if (!store.getLayer(feature.layerId)?.visible)
+        return false;
+    if (feature.groupId && store.getGroup(feature.groupId)?.visible === false)
+        return false;
+    return !isLocallyHidden(feature, store);
+}
+/**
+ * Lists the candidate features near the bbox
+ */
+export function queryFeatures(deps, bbox, ctx) {
+    const lng = (bbox.minX + bbox.maxX) / 2;
+    const lat = (bbox.minY + bbox.maxY) / 2;
+    // findNear queries a square extent, so the larger of the tolerances is used
+    const tolerance = Math.max(bbox.maxX - lng, bbox.maxY - lat);
+    const features = [];
+    const seen = new Set();
+    for (const id of deps.spatialIndex.findNear([lng, lat], tolerance)) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (id === ctx.excludeFeatureId)
+            continue;
+        if (ctx.excludeFeatureIds?.has(id))
+            continue;
+        const feature = deps.store.getFeature(id);
+        if (!feature)
+            continue;
+        if (!isSnapVisible(feature, deps.store))
+            continue;
+        features.push(feature);
+    }
+    return features;
+}
+/**
+ * Whether the vertex is to be excluded
+ */
+export function isExcludedVertex(featureId, vertex, ctx) {
+    const exclude = ctx.excludeVertex;
+    if (!exclude || !vertex)
+        return false;
+    return exclude.featureId === featureId && isSameVertexRef(vertex, exclude.vertex);
+}
+/**
+ * Gathers the vertices of one coordinate sequence (a line / a ring) that are inside
+ * the bbox
+ *
+ * The vertices and the vertex references listed are exactly the same as in
+ * computeVertexHandles (view/ui/handles.ts). The last item of a ring is a copy of the
+ * first one, so no handle is produced for it (through the index, the last item is
+ * normalized to index 0 and the duplicate is dropped). A line produces a handle on
+ * its last vertex even when it is closed, so it is not normalized.
+ */
+function collectPartVerticesInBBox(coords, ring, part, isRing, bbox, out) {
+    const closedRing = isRing && isClosedCoords(coords);
+    const vertexCount = closedRing ? coords.length - 1 : coords.length;
+    if (vertexCount === 0)
+        return;
+    const toRef = makeRefFactory(ring, part);
+    // For a small part, building an index costs more, so it is scanned as it is
+    if (coords.length < SEGMENT_INDEX_THRESHOLD) {
+        for (let i = 0; i < vertexCount; i++) {
+            if (!isInBBox(coords[i], bbox))
+                continue;
+            out.push({ position: coords[i], vertexRef: toRef(i) });
+        }
+        return;
+    }
+    // Both ends of an edge that falls within the bbox become vertex candidates. For a
+    // vertex inside the bbox, an edge touching it always falls within the bbox, so
+    // nothing is missed
+    const seen = new Set();
+    const indices = [];
+    for (const segment of querySegmentIndicesInBBox(getSegmentGrid(coords), bbox)) {
+        for (const raw of [segment, segment + 1]) {
+            const index = closedRing && raw === vertexCount ? 0 : raw;
+            if (index >= vertexCount)
+                continue;
+            if (seen.has(index))
+                continue;
+            seen.add(index);
+            indices.push(index);
+        }
+    }
+    // Aligned to the same order as a full scan (ascending by index)
+    indices.sort((a, b) => a - b);
+    for (const index of indices) {
+        if (!isInBBox(coords[index], bbox))
+            continue;
+        out.push({ position: coords[index], vertexRef: toRef(index) });
+    }
+}
+/**
+ * Gathers the vertices of a feature that are inside the bbox
+ *
+ * The bbox is the cursor position +- the tolerance (in longitude and in latitude),
+ * and the distance test of SnapService measures the pixel distance with the same
+ * conversion. A vertex outside the bbox can therefore never be inside the tolerance,
+ * and discarding it here does not change the candidates.
+ *
+ * For types without edges (Point / MultiPoint / custom types), the full listing of
+ * computeVertexHandles is simply narrowed down by the bbox, as before.
+ */
+export function collectVertexCandidatesInBBox(feature, bbox) {
+    const candidates = [];
+    if (!hasSnapEdges(feature.type)) {
+        for (const handle of computeVertexHandles(feature)) {
+            // Only Point / MultiPoint reach this path, and a vertex reference is always
+            // attached
+            if (!handle.vertexRef)
+                continue;
+            if (!isInBBox(handle.position, bbox))
+                continue;
+            candidates.push({ position: handle.position, vertexRef: handle.vertexRef });
+        }
+        return candidates;
+    }
+    forEachPart(feature, (coords, ring, part, isRing) => {
+        collectPartVerticesInBBox(coords, ring, part, isRing, bbox, candidates);
+    });
+    return candidates;
+}

package/dist/snapping/providers/store.d.ts

@@ -0,0 +1 @@
+export type { StoreSnapProviderDeps } from './shared.js';

package/dist/snapping/providers/store.js

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Built-in snapping providers (the vertices and edges of the Store)
+ *
+ * It narrows down the features near the cursor with SpatialIndex.findNear and lists
+ * the vertex and edge candidates per type. Intersections are handled by
+ * providers/intersection.ts, and construction guides by providers/guide.ts.
+ *
+ * What is left out.
+ *
+ *   - Hidden features (both the shared visible flag and local hiding)
+ *   - The features of ctx.excludeFeatureId / ctx.excludeFeatureIds
+ *   - The vertex of ctx.excludeVertex and the edges touching it (the vertex being
+ *     dragged sits on the cursor, so the edges touching it would always be at a
+ *     distance of 0)
+ *   - The tentative feature being drawn (it is not a feature of the Store, so it never
+ *     enters in the first place)
+ *
+ * For a custom feature type, CustomFeatureHandler.getSnapTargets is used when it is
+ * registered (the vertex provider calls it).
+ */
+import { resolveMessages } from '../../messages.js';
+import { DEFAULT_SNAP_OPTIONS, } from '../types.js';
+import { createSteppedGuideSnapProvider } from './guide.js';
+import { createStoreIntersectionSnapProvider } from './intersection.js';
+import { collectFeatureSegmentsInBBox, collectVertexCandidatesInBBox, hasSnapEdges, isExcludedVertex, queryFeatures, segmentIntersectsBBox, } from './shared.js';
+/**
+ * Builds the vertex provider for the Store
+ *
+ * The vertices and the vertex references per type are aligned with the vertex
+ * handles of the selection UI (computeVertexHandles). The inner rings (holes) of a
+ * Polygon and the parts of the Multi variants are targets as they are. The listing
+ * is narrowed down to the extent that falls within the bbox (a huge feature uses the
+ * index).
+ *
+ * @internal
+ */
+export function createStoreVertexSnapProvider(deps) {
+    return {
+        name: 'core:store-vertex',
+        candidates(bbox, ctx) {
+            const candidates = [];
+            for (const feature of queryFeatures(deps, bbox, ctx)) {
+                // A custom type is left to the registered getSnapTargets
+                const custom = deps.snapTargets?.get(feature.type);
+                if (custom) {
+                    for (const candidate of custom(feature, ctx)) {
+                        const featureId = candidate.featureId ?? feature.id;
+                        if (!('start' in candidate) && isExcludedVertex(featureId, candidate.vertex, ctx)) {
+                            continue;
+                        }
+                        candidates.push({ ...candidate, featureId });
+                    }
+                    continue;
+                }
+                for (const vertex of collectVertexCandidatesInBBox(feature, bbox)) {
+                    if (isExcludedVertex(feature.id, vertex.vertexRef, ctx))
+                        continue;
+                    const candidate = {
+                        kind: 'vertex',
+                        coordinate: vertex.position,
+                        featureId: feature.id,
+                        vertex: vertex.vertexRef,
+                    };
+                    candidates.push(candidate);
+                }
+            }
+            return candidates;
+        },
+    };
+}
+/**
+ * Builds the edge provider for the Store
+ *
+ * The candidates are returned as segments (2 end points), and the computation of the
+ * point closest to the cursor is left to SnapService. The vertex references of both
+ * ends are included as well (tracing reads them).
+ *
+ * @internal
+ */
+export function createStoreEdgeSnapProvider(deps) {
+    return {
+        name: 'core:store-edge',
+        candidates(bbox, ctx) {
+            const candidates = [];
+            for (const feature of queryFeatures(deps, bbox, ctx)) {
+                // The candidates of a custom type are returned by the vertex provider
+                // (getSnapTargets)
+                if (deps.snapTargets?.get(feature.type))
+                    continue;
+                if (!hasSnapEdges(feature.type))
+                    continue;
+                collectFeatureSegmentsInBBox(feature, bbox, (start, end, startRef, endRef) => {
+                    if (!segmentIntersectsBBox(start, end, bbox))
+                        return;
+                    // An edge touching the vertex being dragged passes over the cursor, so it is
+                    // excluded
+                    if (isExcludedVertex(feature.id, startRef, ctx))
+                        return;
+                    if (isExcludedVertex(feature.id, endRef, ctx))
+                        return;
+                    const candidate = {
+                        kind: 'edge',
+                        start,
+                        end,
+                        startRef,
+                        endRef,
+                        featureId: feature.id,
+                    };
+                    candidates.push(candidate);
+                });
+            }
+            return candidates;
+        },
+    };
+}
+/**
+ * Builds the full set of built-in providers (in the order vertex -> edge ->
+ * intersection -> guide)
+ *
+ * @internal
+ */
+export function createBuiltInSnapProviders(deps, options = {}) {
+    const messages = resolveMessages(options.messages);
+    return [
+        createStoreVertexSnapProvider(deps),
+        createStoreEdgeSnapProvider(deps),
+        createStoreIntersectionSnapProvider({ ...deps, messages }),
+        createSteppedGuideSnapProvider({ store: deps.store }, options.getNorthStepDegrees ?? (() => DEFAULT_SNAP_OPTIONS.guideStepDegrees), { tileSize: options.tileSize, messages }),
+    ];
+}

package/dist/snapping/service.d.ts

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

package/dist/snapping/service.js

@@ -0,0 +1,272 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { DEFAULT_TILE_SIZE } from '../shared/math/index.js';
+import { nearestLongitude, wrapLongitude } from '../shared/math/longitude.js';
+import { isSameVertexRef } from '../shared/utils/vertex-ref.js';
+import { degreesPerPixel, distanceInPixels, nearestPointOnSegment } from './geometry.js';
+import { createBuiltInSnapProviders } from './providers/store.js';
+import { DEFAULT_SNAP_OPTIONS, isSegmentCandidate, resolveGuideStepDegrees, resolveSnapKinds, SNAP_KIND_PRIORITY, } from './types.js';
+/**
+ * Whether it is temporarily disabled by a modifier key
+ */
+function isDisabledByModifier(modifiers, key) {
+    if (key === 'none')
+        return false;
+    return modifiers[key];
+}
+/**
+ * Whether the vertex references are the same (two unspecified ones also count as the
+ * same)
+ */
+function isSameVertex(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return isSameVertexRef(a, b);
+}
+/**
+ * Whether the segments of the snapping targets are the same (two unspecified ones also
+ * count as the same)
+ *
+ * Even when the snapped point does not move, a different segment means a different
+ * snapping target, so it is treated as a change.
+ */
+function isSameSegment(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return (a.start[0] === b.start[0] &&
+        a.start[1] === b.start[1] &&
+        a.end[0] === b.end[0] &&
+        a.end[1] === b.end[1]);
+}
+/**
+ * Whether the 2 results are the same (used to decide whether to emit an event)
+ */
+function isSameResult(a, b) {
+    // The first resolution counts as a change only when something was snapped to (not
+    // being snapped is the default state)
+    if (!a)
+        return b.target === undefined;
+    if (a.target === undefined && b.target === undefined)
+        return true;
+    if (a.target === undefined || b.target === undefined)
+        return false;
+    return (a.target.kind === b.target.kind &&
+        a.target.featureId === b.target.featureId &&
+        a.target.datasetId === b.target.datasetId &&
+        a.target.description === b.target.description &&
+        isSameVertex(a.target.vertex, b.target.vertex) &&
+        isSameSegment(a.target.segment, b.target.segment) &&
+        a.lngLat.lng === b.lngLat.lng &&
+        a.lngLat.lat === b.lngLat.lat);
+}
+/**
+ * Whether the new candidate replaces the current best candidate
+ */
+function isBetterCandidate(best, priority, distancePx, preferred) {
+    if (best.priority !== priority)
+        return priority < best.priority;
+    if (best.distancePx !== distancePx)
+        return distancePx < best.distancePx;
+    // Only on a complete tie does a candidate of the preferred feature overturn the one
+    // that arrived first
+    return preferred && !best.preferred;
+}
+/**
+ * Creates a SnapService
+ *
+ * @internal
+ */
+export function createSnapService(deps = {}) {
+    // kinds is nested, so it is copied (so that the defaults object is not rewritten)
+    const options = {
+        ...DEFAULT_SNAP_OPTIONS,
+        ...deps.options,
+        kinds: resolveSnapKinds(deps.options?.kinds),
+        datasets: deps.options?.datasets ?? DEFAULT_SNAP_OPTIONS.datasets,
+        guideStepDegrees: resolveGuideStepDegrees(deps.options?.guideStepDegrees),
+    };
+    const tileSize = deps.tileSize ?? DEFAULT_TILE_SIZE;
+    const providers = [];
+    let enabled = options.enabled;
+    let lastResult = null;
+    if (deps.store && deps.spatialIndex) {
+        providers.push(...createBuiltInSnapProviders({ store: deps.store, spatialIndex: deps.spatialIndex, snapTargets: deps.snapTargets }, {
+            tileSize,
+            ...deps.guide,
+            // Read at every query, so setGuideStep takes effect without rebuilding the provider
+            getNorthStepDegrees: () => options.guideStepDegrees,
+        }));
+    }
+    /**
+     * Stores the result and emits an event when it changed
+     */
+    function publish(result) {
+        const changed = !isSameResult(lastResult, result);
+        lastResult = result;
+        if (changed) {
+            deps.eventEmitter?.emit('snap.change', result);
+        }
+        return result;
+    }
+    /**
+     * Evaluates a single candidate and updates best
+     *
+     * They are compared by the priority of the kind first and then by distance, and only
+     * when the distances tie as well does the candidate matching preferFeature
+     * (preferred) win. Otherwise the one that arrived first is kept.
+     */
+    function evaluate(best, coordinate, target, cursor, perPixel, preferred) {
+        const distancePx = distanceInPixels(coordinate, cursor, perPixel);
+        if (distancePx > options.tolerancePx)
+            return best;
+        const priority = SNAP_KIND_PRIORITY[target.kind];
+        if (best && !isBetterCandidate(best, priority, distancePx, preferred)) {
+            return best;
+        }
+        return { coordinate, target, priority, distancePx, preferred };
+    }
+    /** How far a longitude moves to reach its copy nearest to the cursor (0 in most cases) */
+    function turnToCursor(lng, cursorLng) {
+        return nearestLongitude(lng, cursorLng) - lng;
+    }
+    /** A coordinate moved along the longitude (the same array when it does not move) */
+    function moveBy(coordinate, turn) {
+        return turn === 0 ? coordinate : [coordinate[0] + turn, coordinate[1]];
+    }
+    function resolve(lngLat, point, ctx) {
+        if (!enabled || isDisabledByModifier(ctx.modifiers, options.disableKey)) {
+            return publish({ lngLat });
+        }
+        const perPixel = degreesPerPixel(lngLat.lat, ctx.zoom, tileSize);
+        const toleranceLngDeg = perPixel.lng * options.tolerancePx;
+        const toleranceLatDeg = perPixel.lat * options.tolerancePx;
+        const cursor = [lngLat.lng, lngLat.lat];
+        // The cursor on each copy of the world its tolerance reaches. The features are stored in
+        // [-180, 180], while the cursor comes in the unwrapped longitude of the view (above 180 on
+        // the copy east of the antimeridian, where the rendering draws the stored features a second
+        // time). The candidates are looked up around the cursor brought into [-180, 180], and also
+        // on the neighbouring copy when the tolerance runs past ±180. Each candidate is then taken
+        // on its copy nearest to the cursor (a segment moves by the turn of its start), so it is
+        // evaluated and returned in the frame of the cursor; a candidate already in that frame (a
+        // guide drawn from the tentative) does not move. Away from the antimeridian this is the
+        // cursor alone, and nothing moves.
+        const stored = wrapLongitude(lngLat.lng);
+        const copies = [stored];
+        if (stored + toleranceLngDeg > 180)
+            copies.push(stored - 360);
+        if (stored - toleranceLngDeg < -180)
+            copies.push(stored + 360);
+        let best = null;
+        for (const copyLng of copies) {
+            const copyLngLat = copyLng === lngLat.lng ? lngLat : { lng: copyLng, lat: lngLat.lat };
+            const bbox = {
+                minX: copyLng - toleranceLngDeg,
+                minY: lngLat.lat - toleranceLatDeg,
+                maxX: copyLng + toleranceLngDeg,
+                maxY: lngLat.lat + toleranceLatDeg,
+            };
+            const providerCtx = {
+                ...ctx,
+                lngLat: copyLngLat,
+                point,
+                tolerancePx: options.tolerancePx,
+                toleranceLngDeg,
+                toleranceLatDeg,
+            };
+            for (const provider of providers) {
+                let candidates;
+                try {
+                    candidates = provider.candidates(bbox, providerCtx);
+                }
+                catch (error) {
+                    // An exception from one provider does not stop snapping as a whole
+                    console.error(`Error in snap provider "${provider.name}":`, error);
+                    continue;
+                }
+                for (const candidate of candidates) {
+                    // Candidates of a disabled kind are not evaluated
+                    if (!options.kinds[candidate.kind])
+                        continue;
+                    let coordinate;
+                    if (isSegmentCandidate(candidate)) {
+                        const turn = turnToCursor(candidate.start[0], lngLat.lng);
+                        coordinate = nearestPointOnSegment(cursor, moveBy(candidate.start, turn), moveBy(candidate.end, turn), perPixel);
+                    }
+                    else {
+                        coordinate = moveBy(candidate.coordinate, turnToCursor(candidate.coordinate[0], lngLat.lng));
+                    }
+                    // The target keeps the stored coordinates (it names the geometry that was snapped to)
+                    const target = { kind: candidate.kind };
+                    if (candidate.featureId !== undefined)
+                        target.featureId = candidate.featureId;
+                    if (candidate.datasetId !== undefined)
+                        target.datasetId = candidate.datasetId;
+                    if (candidate.description !== undefined)
+                        target.description = candidate.description;
+                    if (isSegmentCandidate(candidate)) {
+                        const segment = { start: candidate.start, end: candidate.end };
+                        if (candidate.startRef !== undefined)
+                            segment.startRef = candidate.startRef;
+                        if (candidate.endRef !== undefined)
+                            segment.endRef = candidate.endRef;
+                        target.segment = segment;
+                    }
+                    else if (candidate.vertex !== undefined) {
+                        target.vertex = candidate.vertex;
+                    }
+                    // Whether it matches the "preferred feature" used as the tie-break on a tie
+                    // (two unspecified datasetIds also count as a match)
+                    const preferred = ctx.preferFeature !== undefined &&
+                        candidate.featureId === ctx.preferFeature.featureId &&
+                        candidate.datasetId === ctx.preferFeature.datasetId;
+                    best = evaluate(best, coordinate, target, cursor, perPixel, preferred);
+                }
+            }
+        }
+        if (!best) {
+            return publish({ lngLat });
+        }
+        return publish({
+            lngLat: { lng: best.coordinate[0], lat: best.coordinate[1] },
+            target: best.target,
+        });
+    }
+    return {
+        resolve,
+        register(provider) {
+            providers.push(provider);
+            return () => {
+                const index = providers.indexOf(provider);
+                if (index >= 0)
+                    providers.splice(index, 1);
+            };
+        },
+        setEnabled(value) {
+            enabled = value;
+        },
+        isEnabled() {
+            return enabled;
+        },
+        setKindEnabled(kind, value) {
+            options.kinds[kind] = value;
+        },
+        isKindEnabled(kind) {
+            return options.kinds[kind];
+        },
+        setDatasetsEnabled(value) {
+            options.datasets = value;
+        },
+        isDatasetsEnabled() {
+            return options.datasets;
+        },
+        setGuideStep(degrees) {
+            options.guideStepDegrees = resolveGuideStepDegrees(degrees);
+        },
+        getResult() {
+            return lastResult;
+        },
+        getOptions() {
+            return { ...options, enabled, kinds: { ...options.kinds } };
+        },
+    };
+}