@sakuzu/maplibre-gl-draw 1.0.0

package/dist/snapping/types.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Type definitions for snapping
+ *
+ * The single entry point for coordinates is InputRouter, so replacing the
+ * coordinates of click / mousemove / dragmove there with SnapService makes every
+ * mode (including custom modes from plugins) and the vertex dragging of the select
+ * mode support snapping without any change.
+ *
+ * A candidate (SnapCandidate) has 2 shapes.
+ *
+ *   Point candidate (SnapPointCandidate)     Holds the coordinate as it is. Used for
+ *                                            vertices, intersections, guides, and
+ *                                            for an edge whose nearest point the
+ *                                            provider computed itself
+ *   Segment candidate (SnapSegmentCandidate) Holds the 2 end points of an edge. The
+ *                                            point closest to the cursor is computed
+ *                                            by SnapService
+ *
+ * The built-in edge provider returns segment candidates and leaves the computation
+ * of the nearest point (a projection in pixel space) to SnapService.
+ */
+import type { ModifierKeys } from '../dispatcher/types.js';
+import type { ScreenPoint } from '../shared/math/index.js';
+import type { SnapLngLat, SnapTargetKind } from '../shared/types/events.js';
+import type { BoundingBox, Coordinate, VertexRef } from '../store/types.js';
+export type { SnapLngLat, SnapResult, SnapTarget, SnapTargetKind, SnapTargetSegment, } from '../shared/types/events.js';
+/**
+ * A single vertex to leave out of the snapping candidates.
+ *
+ * A vertex being dragged would snap to itself, so it is excluded. Only 1 vertex is
+ * excluded, and the other vertices of the same feature are still included (so that a
+ * ring can be closed).
+ */
+export interface SnapExcludeVertex {
+    /** The ID of the target feature */
+    featureId: string;
+    /** The reference of the vertex to exclude */
+    vertex: VertexRef;
+}
+/**
+ * The state of one snapping resolution: the zoom, the exclusions and the modifier keys.
+ *
+ * The library builds it for every input; a caller passes part of it to
+ * `draw.snapping.resolve()` when it snaps a coordinate made outside the library.
+ */
+export interface SnapContext {
+    /** The current zoom level (used to convert the pixel tolerance into degrees) */
+    zoom: number;
+    /**
+     * The feature ID to exclude (that whole feature is removed from the candidates)
+     */
+    excludeFeatureId?: string;
+    /**
+     * The set of feature IDs to exclude (each of them is removed from the candidates
+     * entirely)
+     *
+     * The features being moved in a move drag (operation === 'move') go in here.
+     * A feature being moved travels with the cursor, so snapping to itself would repeat
+     * "pull the cursor back to its own position -> shift again by the grab offset on
+     * the next frame" and the view would oscillate. The reason for excluding them is
+     * the same as for excludeVertex; the only difference is that the target is a whole
+     * feature rather than a single vertex.
+     */
+    excludeFeatureIds?: ReadonlySet<string>;
+    /** The vertex to exclude (the vertex being dragged itself) */
+    excludeVertex?: SnapExcludeVertex;
+    /**
+     * The feature to prefer when both the priority and the distance are tied
+     *
+     * The source is the anchor of the tracing (the boundary that was first traced).
+     * When features whose boundary coordinates overlap exactly line up, the distances
+     * of the candidates tie and the winner ends up being decided by the order in which
+     * the candidates were listed, so this feature is made to win only on a tie, to keep
+     * the snapping target from jumping to another feature. It does not overturn a
+     * candidate that is closer.
+     */
+    preferFeature?: {
+        /** The feature ID to prefer */
+        featureId: string;
+        /** When it originates from a dataset, that dataset ID */
+        datasetId?: string;
+    };
+    /** The state of the modifier keys (used to decide on a temporary disabling) */
+    modifiers: ModifierKeys;
+}
+/**
+ * The context passed to {@link SnapProvider.candidates}: a {@link SnapContext} plus the cursor
+ * position and the tolerance in pixels and in degrees.
+ *
+ * A provider should honor the exclusions (`excludeFeatureId`, `excludeFeatureIds`,
+ * `excludeVertex`): the features being moved travel with the cursor, and snapping to them
+ * would pull the cursor back to itself.
+ */
+export interface SnapProviderContext extends SnapContext {
+    /** The cursor position in degrees */
+    lngLat: SnapLngLat;
+    /** The cursor position in screen px, relative to the map container */
+    point: ScreenPoint;
+    /** The tolerance in screen px (`options.snap.tolerancePx`) */
+    tolerancePx: number;
+    /** The tolerance converted into degrees of longitude at the current zoom */
+    toleranceLngDeg: number;
+    /** The tolerance converted into degrees of latitude at the cursor latitude and zoom */
+    toleranceLatDeg: number;
+}
+/**
+ * A snapping candidate that snaps to a fixed coordinate.
+ *
+ * A provider that computed the nearest point on an edge itself can return this shape
+ * with kind: 'edge'.
+ */
+export interface SnapPointCandidate {
+    /** The kind of the candidate */
+    kind: SnapTargetKind;
+    /** The coordinate to snap to, `[lng, lat]` in degrees */
+    coordinate: Coordinate;
+    /** The feature ID it originates from */
+    featureId?: string;
+    /**
+     * The dataset ID it originates from (only for candidates originating from a
+     * dataset)
+     */
+    datasetId?: string;
+    /** The vertex reference it originates from (used to decide on exclusion) */
+    vertex?: VertexRef;
+    /** A label for the host to show, passed on as `SnapTarget.description` */
+    description?: string;
+}
+/**
+ * A snapping candidate that snaps to the point of a segment closest to the cursor.
+ *
+ * The point closest to the cursor is computed by SnapService. Besides real edges
+ * (edge), construction guides (guide) are also returned in this shape.
+ */
+export interface SnapSegmentCandidate {
+    /** The kind of the candidate (a segment candidate is either an edge or a guide) */
+    kind: 'edge' | 'guide';
+    /** The start of the segment, `[lng, lat]` in degrees */
+    start: Coordinate;
+    /** The end of the segment, `[lng, lat]` in degrees */
+    end: Coordinate;
+    /**
+     * For a real edge, the vertex reference of the start. With both references, a click that
+     * snapped to the edge can start or end edge tracing
+     */
+    startRef?: VertexRef;
+    /** For a real edge, the vertex reference of the end */
+    endRef?: VertexRef;
+    /** The feature ID it originates from */
+    featureId?: string;
+    /**
+     * The dataset ID it originates from (only for candidates originating from a
+     * dataset)
+     */
+    datasetId?: string;
+    /** A label for the host to show, passed on as `SnapTarget.description` */
+    description?: string;
+}
+/**
+ * A snapping candidate returned by a {@link SnapProvider}: a point or a segment.
+ */
+export type SnapCandidate = SnapPointCandidate | SnapSegmentCandidate;
+/**
+ * A source of snapping candidates, such as external data the host wants to snap to.
+ *
+ * Register one with `draw.snapping.register(provider)`; the call returns a function that
+ * unregisters it. The library calls `candidates` for every pointer input while snapping is
+ * enabled, then cuts the candidates off by the tolerance and picks the winner by kind
+ * (vertex > intersection > edge > guide) and then by distance to the cursor. Candidates of a
+ * kind disabled in `options.snap.kinds` are ignored. `candidates` runs on every mouse move,
+ * so it should answer from an index rather than scan all the data.
+ *
+ * @example
+ * ```ts
+ * import type { SnapProvider } from '@sakuzu/maplibre-gl-draw';
+ *
+ * const stations: [number, number][] = [[139.767, 35.681], [139.7, 35.69]];
+ *
+ * const stationProvider: SnapProvider = {
+ *   name: 'stations',
+ *   candidates: (bbox) =>
+ *     stations
+ *       .filter(([lng, lat]) =>
+ *         lng >= bbox.minX && lng <= bbox.maxX && lat >= bbox.minY && lat <= bbox.maxY,
+ *       )
+ *       .map((coordinate) => ({ kind: 'vertex', coordinate, description: 'station' })),
+ * };
+ *
+ * const unregister = draw.snapping.register(stationProvider);
+ * // later
+ * unregister();
+ * ```
+ */
+export interface SnapProvider {
+    /** The provider name (for debugging and for detecting duplicate registrations) */
+    readonly name: string;
+    /**
+     * Lists the candidates near the cursor
+     *
+     * @param bbox The extent around the cursor widened by the tolerance, in degrees. Candidates
+     *   outside it may be returned; the library cuts them off
+     * @param ctx The cursor position, the tolerance, the exclusions and the modifier keys
+     * @returns The candidates. An empty array when there are none
+     */
+    candidates(bbox: BoundingBox, ctx: SnapProviderContext): SnapCandidate[];
+}
+/**
+ * The modifier key that stops snapping while it is held, or `'none'` for no such key.
+ */
+export type SnapDisableKey = 'alt' | 'shift' | 'ctrl' | 'meta' | 'none';
+/**
+ * The snapping options, given as `options.snap` of `createMapLibreGLDraw`.
+ *
+ * Every field can be omitted. Snapping applies to the pointer input of every drawing mode,
+ * of custom modes and of vertex dragging. Everything except `tolerancePx` and `disableKey`
+ * can be switched at runtime through `draw.snapping`.
+ *
+ * @example
+ * ```ts
+ * const draw = createMapLibreGLDraw(map, {
+ *   snap: {
+ *     tolerancePx: 12,
+ *     disableKey: 'shift',
+ *     kinds: { guide: false }, // vertices, edges and intersections only
+ *   },
+ * });
+ * ```
+ */
+export interface SnapOptions {
+    /** Whether snapping is enabled (default: true). Switch it with `draw.snapping.setEnabled` */
+    enabled?: boolean;
+    /**
+     * The distance from the cursor within which a candidate snaps, in screen px (default: 10).
+     * It is converted into degrees at the cursor latitude and the zoom, so it is the same on
+     * screen in every direction
+     */
+    tolerancePx?: number;
+    /**
+     * The modifier key that stops snapping while it is held down (default: 'alt';
+     * 'none' for no disabling)
+     */
+    disableKey?: SnapDisableKey;
+    /**
+     * The enabled flag of each kind (`vertex`, `edge`, `intersection`, `guide`). An omitted
+     * kind is enabled. Switch one with `draw.snapping.setKindEnabled`
+     */
+    kinds?: Partial<Record<SnapTargetKind, boolean>>;
+    /** Whether datasets are included as snapping targets (default: true) */
+    datasets?: boolean;
+    /**
+     * The step angle of the built-in north-based guides in degrees (default: 45, which gives 8
+     * guides; 15 gives 24). A value of 0 or less, or a non-finite value, gives the default.
+     * Change it at runtime with `draw.snapping.setGuideStep`
+     */
+    guideStepDegrees?: number;
+}
+/**
+ * The snapping options with every default filled in, as `draw.snapping.getOptions()` returns
+ * them.
+ *
+ * `enabled`, `kinds`, `datasets` and `guideStepDegrees` reflect the changes made at runtime. `kinds` is a copy;
+ * rewriting it has no effect.
+ */
+export type ResolvedSnapOptions = Required<Omit<SnapOptions, 'kinds'>> & {
+    /** The enabled flag of each kind (every kind is filled in) */
+    kinds: Record<SnapTargetKind, boolean>;
+};

package/dist/snapping/types.js

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The priority of each kind (smaller wins)
+ *
+ * @internal
+ */
+export const SNAP_KIND_PRIORITY = {
+    vertex: 0,
+    intersection: 1,
+    edge: 2,
+    guide: 3,
+};
+/**
+ * Decides whether it is a segment candidate
+ *
+ * @internal
+ */
+export function isSegmentCandidate(candidate) {
+    return 'start' in candidate;
+}
+/**
+ * The default of the enabled flag of each kind (all enabled)
+ *
+ * @internal
+ */
+export const DEFAULT_SNAP_KINDS = {
+    vertex: true,
+    edge: true,
+    intersection: true,
+    guide: true,
+};
+/**
+ * The defaults of the snapping options
+ *
+ * kinds is a nested object, so the caller must copy it before rewriting it.
+ *
+ * @internal
+ */
+export const DEFAULT_SNAP_OPTIONS = {
+    enabled: true,
+    tolerancePx: 10,
+    disableKey: 'alt',
+    kinds: DEFAULT_SNAP_KINDS,
+    datasets: true,
+    guideStepDegrees: 45,
+};
+/**
+ * Normalizes the step angle of the north-based guides: a value of 0 or less, or a non-finite
+ * value, gives the default (45 degrees)
+ *
+ * @internal
+ */
+export function resolveGuideStepDegrees(degrees) {
+    return degrees !== undefined && Number.isFinite(degrees) && degrees > 0
+        ? degrees
+        : DEFAULT_SNAP_OPTIONS.guideStepDegrees;
+}
+/**
+ * Builds the enabled flag of each kind with the defaults filled in
+ *
+ * @internal
+ */
+export function resolveSnapKinds(kinds) {
+    return { ...DEFAULT_SNAP_KINDS, ...kinds };
+}

package/dist/store/change-merger.d.ts

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

package/dist/store/change-merger.js

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Merges new changes into the existing pendingChanges
+ *
+ * Because multiple changes occur during a transaction,
+ * they need to be gathered into a single StateChanges object.
+ *
+ * @internal
+ */
+export function mergeChanges(pendingChanges, changes) {
+    const result = { ...pendingChanges };
+    // features
+    if (changes.features) {
+        if (!result.features) {
+            result.features = {};
+        }
+        if (changes.features.created) {
+            result.features.created = [...(result.features.created || []), ...changes.features.created];
+        }
+        if (changes.features.updated) {
+            result.features.updated = [...(result.features.updated || []), ...changes.features.updated];
+        }
+        if (changes.features.deleted) {
+            result.features.deleted = [...(result.features.deleted || []), ...changes.features.deleted];
+        }
+    }
+    // layers
+    if (changes.layers) {
+        if (!result.layers) {
+            result.layers = {};
+        }
+        if (changes.layers.created) {
+            result.layers.created = [...(result.layers.created || []), ...changes.layers.created];
+        }
+        if (changes.layers.updated) {
+            result.layers.updated = [...(result.layers.updated || []), ...changes.layers.updated];
+        }
+        if (changes.layers.deleted) {
+            result.layers.deleted = [...(result.layers.deleted || []), ...changes.layers.deleted];
+        }
+        if (changes.layers.orderChanged) {
+            result.layers.orderChanged = changes.layers.orderChanged;
+        }
+    }
+    // groups
+    if (changes.groups) {
+        if (!result.groups) {
+            result.groups = {};
+        }
+        if (changes.groups.created) {
+            result.groups.created = [...(result.groups.created || []), ...changes.groups.created];
+        }
+        if (changes.groups.updated) {
+            result.groups.updated = [...(result.groups.updated || []), ...changes.groups.updated];
+        }
+        if (changes.groups.deleted) {
+            result.groups.deleted = [...(result.groups.deleted || []), ...changes.groups.deleted];
+        }
+    }
+    // layerReorder (dedicated to reordering within a layer)
+    if (changes.layerReorder) {
+        result.layerReorder = changes.layerReorder;
+    }
+    // groupReorder (dedicated to reordering within a group)
+    if (changes.groupReorder) {
+        result.groupReorder = changes.groupReorder;
+    }
+    // selection
+    if (changes.selection) {
+        result.selection = changes.selection;
+    }
+    // editing
+    if (changes.editing) {
+        if (!result.editing) {
+            result.editing = {};
+        }
+        if (changes.editing.started) {
+            result.editing.started = [...(result.editing.started || []), ...changes.editing.started];
+        }
+        if (changes.editing.ended) {
+            result.editing.ended = [...(result.editing.ended || []), ...changes.editing.ended];
+        }
+    }
+    // tentative
+    if (changes.tentative) {
+        result.tentative = changes.tentative;
+    }
+    // mode
+    if (changes.mode) {
+        result.mode = changes.mode;
+    }
+    // uiStateChanged
+    if (changes.uiStateChanged) {
+        result.uiStateChanged = true;
+    }
+    // metadata
+    if (changes.metadata) {
+        result.metadata = changes.metadata;
+    }
+    return result;
+}

package/dist/store/draw-store.d.ts

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