@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/utils/property.js

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Property helpers
+ *
+ * Utilities for handling the properties of a feature (feature.properties) in a type-safe way.
+ *
+ * This library's own data such as createdZoom/rotation/scale has to round-trip through
+ * GeoJSON with the maplibre-gl-draw: prefix, so it is held inside feature.properties under
+ * keys without the prefix.
+ */
+import { INTERNAL_PROPERTIES } from '../config/constants.js';
+/**
+ * Gets the zoom at which the feature was created (`properties.createdZoom`)
+ *
+ * The drawing modes record it. Line widths follow the map from that zoom, and an Image is
+ * drawn at its size in pixels at that zoom (see {@link FeatureStyle.strokeWidth}).
+ *
+ * @returns The zoom, or undefined when the feature has none (it then keeps the same width on
+ *   the screen)
+ *
+ * @example
+ * ```ts
+ * const feature = draw.getFeature(id);
+ * const zoom = feature ? getCreatedZoom(feature) : undefined;
+ * ```
+ */
+export function getCreatedZoom(feature) {
+    const value = feature.properties[INTERNAL_PROPERTIES.CREATED_ZOOM];
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * Sets the zoom at which a feature was created, in a `properties` object
+ *
+ * Use it on the properties of a {@link FeatureInput} before `addFeature`, so that the new
+ * feature scales with the map from the current zoom like a drawn one.
+ *
+ * @example
+ * ```ts
+ * const properties: Record<string, unknown> = {};
+ * setCreatedZoom(properties, map.getZoom());
+ * draw.addFeature({
+ *   type: 'LineString',
+ *   coordinates: [
+ *     [139.76, 35.68],
+ *     [139.78, 35.69],
+ *   ],
+ *   properties,
+ * });
+ * ```
+ */
+export function setCreatedZoom(properties, zoom) {
+    properties[INTERNAL_PROPERTIES.CREATED_ZOOM] = zoom;
+}
+/**
+ * Gets the rotation of the feature in degrees (`properties.rotation`, 0 when unset)
+ */
+export function getRotation(feature) {
+    const value = feature.properties[INTERNAL_PROPERTIES.ROTATION];
+    return typeof value === 'number' ? value : 0;
+}
+/**
+ * Sets the rotation in degrees, in a `properties` object (the properties of a
+ * {@link FeatureInput} before `addFeature`, say)
+ */
+export function setRotation(properties, rotation) {
+    properties[INTERNAL_PROPERTIES.ROTATION] = rotation;
+}
+/**
+ * Gets the scale of the feature (`properties.scale`, 1 when unset), which resizing an Image
+ * changes
+ */
+export function getScale(feature) {
+    const value = feature.properties[INTERNAL_PROPERTIES.SCALE];
+    return typeof value === 'number' ? value : 1;
+}
+/**
+ * Sets the scale of the feature
+ */
+export function setScale(properties, scale) {
+    properties[INTERNAL_PROPERTIES.SCALE] = scale;
+}
+/**
+ * Gets the name of the feature
+ */
+export function getFeatureName(feature) {
+    const value = feature.properties.name;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Sets the name of the feature
+ */
+export function setFeatureName(properties, name) {
+    properties.name = name;
+}
+/**
+ * Gets the description of the feature
+ */
+export function getFeatureDescription(feature) {
+    const value = feature.properties.description;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Sets the description of the feature
+ */
+export function setFeatureDescription(properties, description) {
+    properties.description = description;
+}
+/**
+ * Gets the properties of an Image feature in a type-safe way.
+ *
+ * It validates and extracts each field from feature.properties (Record<string, unknown>).
+ * Use it instead of a dangerous cast such as `as unknown as ImageProperties`.
+ */
+export function getImageProperties(feature) {
+    const p = feature.properties;
+    return {
+        imageFileId: typeof p.imageFileId === 'string' ? p.imageFileId : '',
+        imageWidth: typeof p.imageWidth === 'number' ? p.imageWidth : 0,
+        imageHeight: typeof p.imageHeight === 'number' ? p.imageHeight : 0,
+        createdZoom: typeof p.createdZoom === 'number' ? p.createdZoom : 0,
+        rotation: typeof p.rotation === 'number' ? p.rotation : undefined,
+        scale: typeof p.scale === 'number' ? p.scale : undefined,
+    };
+}
+/**
+ * Gets the radius (meters) of a Circle feature. undefined when it is unset or invalid.
+ */
+export function getCircleRadius(feature) {
+    const value = feature.properties.radiusMeters;
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * Gets the angle (degrees) of the radius handle of a Circle feature. The default is 135
+ * (toward the southwest).
+ */
+export function getRadiusHandleAngle(feature) {
+    const value = feature.properties.radiusHandleAngle;
+    return typeof value === 'number' ? value : 135;
+}

package/dist/shared/utils/vertex-ref.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Vertex reference utilities
+ *
+ * A vertex is pointed at by the triple of part number + ring number + vertex index
+ * (VertexRef), so comparison and lookup use the functions here rather than numeric === or
+ * Array#includes.
+ *
+ * part is optional, and when omitted it means 0 (the first part). The vertex reference of a
+ * single geometry has no part, so comparison treats undefined and 0 as the same.
+ */
+import type { VertexRef } from '../types/model.js';
+/**
+ * Gets the part number of a vertex reference (0 when omitted)
+ */
+export declare function getVertexPart(ref: VertexRef): number;
+/**
+ * Whether two vertex references point at the same vertex
+ */
+export declare function isSameVertexRef(a: VertexRef, b: VertexRef): boolean;
+/**
+ * Whether an array of vertex references contains the given vertex
+ */
+export declare function hasVertexRef(refs: readonly VertexRef[], ref: VertexRef): boolean;

package/dist/shared/utils/vertex-ref.js

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Gets the part number of a vertex reference (0 when omitted)
+ */
+export function getVertexPart(ref) {
+    return ref.part ?? 0;
+}
+/**
+ * Whether two vertex references point at the same vertex
+ */
+export function isSameVertexRef(a, b) {
+    return getVertexPart(a) === getVertexPart(b) && a.ring === b.ring && a.index === b.index;
+}
+/**
+ * Whether an array of vertex references contains the given vertex
+ */
+export function hasVertexRef(refs, ref) {
+    return refs.some((r) => isSameVertexRef(r, ref));
+}

package/dist/snapping/custom-targets.d.ts

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

package/dist/snapping/custom-targets.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Creates the snapping candidate registry of one draw instance
+ *
+ * @internal
+ */
+export function createSnapTargetsRegistry() {
+    const providers = new Map();
+    return {
+        register(type, provider) {
+            providers.set(type, provider);
+            return () => {
+                if (providers.get(type) === provider)
+                    providers.delete(type);
+            };
+        },
+        get: (type) => providers.get(type),
+        clear: () => providers.clear(),
+    };
+}

package/dist/snapping/geometry.d.ts

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

package/dist/snapping/geometry.js

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Distance computation for snapping
+ *
+ * The tolerance is held in pixels. The conversion between pixels and degrees depends
+ * on the latitude and the zoom (in Mercator, 1 pixel in the longitude direction is
+ * constant regardless of the latitude, but in the latitude direction it shrinks by
+ * cos(lat)). Distances are therefore also converted into pixels before being
+ * compared.
+ */
+import { DEFAULT_TILE_SIZE, pixelsToDegreesLat, pixelsToDegreesLng } from '../shared/math/index.js';
+/**
+ * Computes the degrees per pixel from the latitude of the cursor position and the
+ * zoom
+ *
+ * @internal
+ */
+export function degreesPerPixel(latitude, zoom, tileSize = DEFAULT_TILE_SIZE) {
+    return {
+        lng: pixelsToDegreesLng(1, latitude, zoom, tileSize),
+        lat: pixelsToDegreesLat(1, latitude, zoom, tileSize),
+    };
+}
+/**
+ * Computes the distance between 2 points in pixels
+ *
+ * @internal
+ */
+export function distanceInPixels(a, b, perPixel) {
+    const dx = (a[0] - b[0]) / perPixel.lng;
+    const dy = (a[1] - b[1]) / perPixel.lat;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * Computes the point on a segment closest to the cursor
+ *
+ * The projection is done in pixel space (staying in degree space would distort the
+ * longitude direction at high latitudes). The returned value never goes beyond the
+ * end points of the segment.
+ *
+ * @internal
+ */
+export function nearestPointOnSegment(point, start, end, perPixel) {
+    const px = point[0] / perPixel.lng;
+    const py = point[1] / perPixel.lat;
+    const ax = start[0] / perPixel.lng;
+    const ay = start[1] / perPixel.lat;
+    const bx = end[0] / perPixel.lng;
+    const by = end[1] / perPixel.lat;
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lengthSquared = dx * dx + dy * dy;
+    // A segment of length 0 is its start point itself
+    if (lengthSquared === 0) {
+        return [start[0], start[1]];
+    }
+    let t = ((px - ax) * dx + (py - ay) * dy) / lengthSquared;
+    t = Math.max(0, Math.min(1, t));
+    return [start[0] + t * (end[0] - start[0]), start[1] + t * (end[1] - start[1])];
+}

package/dist/snapping/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Snapping module
+ *
+ * It provides snapping (SnapService) and its extension point (SnapProvider).
+ * The replacement of the coordinates is done by InputRouter.
+ *
+ * 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 { SnapIndicatorStyles } from './indicator.js';
+export { DEFAULT_SNAP_GUIDE_LINE_STYLE, DEFAULT_SNAP_INDICATOR_STYLES } from './indicator.js';
+export type { GuideSnapProviderDeps, GuideSnapProviderOptions } from './providers/guide.js';
+export { createGuideSnapProvider } from './providers/guide.js';
+export type { ResolvedSnapOptions, SnapCandidate, SnapContext, SnapDisableKey, SnapExcludeVertex, SnapLngLat, SnapOptions, SnapPointCandidate, SnapProvider, SnapProviderContext, SnapResult, SnapSegmentCandidate, SnapTarget, SnapTargetKind, SnapTargetSegment, } from './types.js';

package/dist/snapping/index.js

@@ -0,0 +1,4 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { DEFAULT_SNAP_GUIDE_LINE_STYLE, DEFAULT_SNAP_INDICATOR_STYLES } from './indicator.js';
+export { createGuideSnapProvider } from './providers/guide.js';

package/dist/snapping/indicator.d.ts

@@ -0,0 +1,19 @@
+import type { PointStyle } from '../shared/types/style.js';
+import type { SDFStrokeStyle } from '../view/renderers/line/sdf-line.js';
+import type { SnapTargetKind } from './types.js';
+/**
+ * The symbol drawn at the snapped point, per kind of snap target.
+ */
+export type SnapIndicatorStyles = Record<SnapTargetKind, PointStyle>;
+/**
+ * The style of the guide line drawn under the symbol while a guide is snapped to: 1 px, the
+ * snap color `#00C7BE`, dashed `[4, 4]` (distinct from the `[8, 6]` of the drawing in
+ * progress).
+ */
+export declare const DEFAULT_SNAP_GUIDE_LINE_STYLE: SDFStrokeStyle;
+/**
+ * The symbols drawn at the snapped point, all in the snap color `#00C7BE`: `vertex` an
+ * outlined circle of 14 px, `edge` an outlined square of 12 px, `intersection` a filled
+ * circle of 8 px and `guide` an outlined circle of 10 px.
+ */
+export declare const DEFAULT_SNAP_INDICATOR_STYLES: SnapIndicatorStyles;

package/dist/snapping/indicator.js

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** The snapping color (#00C7BE) */
+const SNAP_COLOR = [0.0, 0.78, 0.745, 1.0];
+const VERTEX_STYLE = {
+    shape: 'circle',
+    size: 14,
+    fillColor: SNAP_COLOR,
+    fillOpacity: 0,
+    strokeColor: SNAP_COLOR,
+    strokeWidth: 2,
+    strokeOpacity: 1.0,
+};
+const EDGE_STYLE = {
+    shape: 'square',
+    size: 12,
+    fillColor: SNAP_COLOR,
+    fillOpacity: 0,
+    strokeColor: SNAP_COLOR,
+    strokeWidth: 2,
+    strokeOpacity: 1.0,
+};
+/**
+ * The symbol of an intersection
+ *
+ * To tell it apart from a vertex (a circle with an outline only), it is a slightly
+ * smaller filled circle. The shapes PointShapeRenderer can actually draw are the
+ * circle and the square, so a diamond cannot be used.
+ */
+const INTERSECTION_STYLE = {
+    shape: 'circle',
+    size: 8,
+    fillColor: SNAP_COLOR,
+    fillOpacity: 1.0,
+    strokeColor: SNAP_COLOR,
+    strokeWidth: 0,
+    strokeOpacity: 0,
+};
+/**
+ * The symbol of a guide
+ *
+ * It appears together with the guide line (dashed), so the point is a smallish circle
+ * with an outline.
+ */
+const GUIDE_STYLE = {
+    shape: 'circle',
+    size: 10,
+    fillColor: SNAP_COLOR,
+    fillOpacity: 0,
+    strokeColor: SNAP_COLOR,
+    strokeWidth: 2,
+    strokeOpacity: 1.0,
+};
+/**
+ * The dash pattern of a guide line (told apart from the [8, 6] of Tentative)
+ */
+const GUIDE_DASH_ARRAY = [4, 4];
+/**
+ * The style of the guide line drawn under the symbol while a guide is snapped to: 1 px, the
+ * snap color `#00C7BE`, dashed `[4, 4]` (distinct from the `[8, 6]` of the drawing in
+ * progress).
+ */
+export const DEFAULT_SNAP_GUIDE_LINE_STYLE = {
+    width: 1,
+    color: SNAP_COLOR,
+    opacity: 1.0,
+    lineStyle: 'dashed',
+    dashArray: GUIDE_DASH_ARRAY,
+};
+/**
+ * The symbols drawn at the snapped point, all in the snap color `#00C7BE`: `vertex` an
+ * outlined circle of 14 px, `edge` an outlined square of 12 px, `intersection` a filled
+ * circle of 8 px and `guide` an outlined circle of 10 px.
+ */
+export const DEFAULT_SNAP_INDICATOR_STYLES = {
+    vertex: VERTEX_STYLE,
+    edge: EDGE_STYLE,
+    intersection: INTERSECTION_STYLE,
+    guide: GUIDE_STYLE,
+};
+/**
+ * The renderer of the snapping indicator
+ *
+ * @internal
+ */
+export class SnapIndicatorRenderer {
+    constructor(deps) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'snap-indicator'
+        });
+        Object.defineProperty(this, "order", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'overlay'
+        });
+        Object.defineProperty(this, "snapService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "styles", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "guideLineStyle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.snapService = deps.snapService;
+        this.styles = { ...DEFAULT_SNAP_INDICATOR_STYLES, ...deps.styles };
+        this.guideLineStyle = deps.guideLineStyle ?? DEFAULT_SNAP_GUIDE_LINE_STYLE;
+    }
+    onAdd(_gl, _map) {
+        // It uses the existing drawing primitives, so it holds no GPU resources of its own
+    }
+    draw(projectionData, zoom, context) {
+        const result = this.snapService.getResult();
+        if (!result?.target)
+            return;
+        const target = result.target;
+        // For a guide, the guide line of the snapping target itself is shown dashed (laid
+        // under the symbol)
+        if (target.kind === 'guide' && target.segment) {
+            const line = [
+                [target.segment.start[0], target.segment.start[1]],
+                [target.segment.end[0], target.segment.end[1]],
+            ];
+            context.sdfLineRenderer.draw(line, this.guideLineStyle, { widthUnit: 'pixels', closed: false }, zoom, projectionData);
+        }
+        const style = this.styles[target.kind];
+        context.pointShapeRenderer.draw([result.lngLat.lng, result.lngLat.lat], style, zoom);
+    }
+    onRemove() {
+        // There are no resources to release
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Snapping providers for datasets (vertex, edge, intersection)
+ *
+ * They add the reference data imported from the library (datasets)
+ * as passive snapping targets. They never touch the data itself; they only read the
+ * features the dataset holds.
+ *
+ * The targets are only the displayed features of a displayed (visible) dataset.
+ * Whether it is interactive is not looked at (snapping works on what is visible).
+ *
+ * The candidates are listed in the same manner as the Store version
+ * (providers/store.ts): vertices are gathered with computeVertexHandles and edges
+ * with collectFeatureSegments. Both featureId and datasetId are attached to a
+ * candidate, and the vertex references of both ends are attached to an edge (tracing
+ * reads them).
+ *
+ * For intersections, the pairs of segments of "display x display" and
+ * "display x Store" are computed (Store x Store is the responsibility of
+ * providers/intersection.ts).
+ */
+import type { DatasetManager } from '../../display/manager.js';
+import { type Messages } from '../../messages.js';
+import type { SpatialIndex } from '../../store/spatial/spatial-index.js';
+import type { Store } from '../../store/store.js';
+import type { BoundingBox, Feature } from '../../store/types.js';
+import type { SnapTargetsRegistry } from '../custom-targets.js';
+import type { SnapProvider } from '../types.js';
+/**
+ * The dependencies of the providers for datasets
+ */
+export interface DisplaySnapProviderDeps {
+    /** The manager of the datasets */
+    datasets: DatasetManager;
+    /** The Store (used as the counterpart of an intersection) */
+    store: Store;
+    /** The SpatialIndex (used as the counterpart of an intersection) */
+    spatialIndex: SpatialIndex;
+    /** Whether snapping to the data is enabled (options.datasets of SnapService) */
+    isEnabled: () => boolean;
+    /** The snapping candidates of the custom feature types of this draw instance */
+    snapTargets?: SnapTargetsRegistry;
+    /**
+     * The messages table the description of an intersection comes from (the same entry as
+     * an intersection originating from the Store; default: English)
+     */
+    messages?: Pick<Messages, 'snapIntersection'>;
+}
+/**
+ * The full set of providers that were built
+ */
+export interface DisplaySnapProviders {
+    /** The vertex, edge and intersection providers */
+    providers: SnapProvider[];
+    /**
+     * Looks up a feature of a dataset
+     *
+     * This is the entry point through which tracing resolves the feature of a snapping
+     * target (it is wired to ModeContext.getDatasetFeature).
+     */
+    getFeature(datasetId: string, featureId: string): Feature | null;
+    /**
+     * Looks up the features of a displayed dataset that fall within an extent
+     *
+     * This is the entry point through which tracing gathers the material for the graph
+     * of edges (it is wired to ModeContext.getDatasetTraceFeatures).
+     */
+    queryFeatures(bbox: BoundingBox): Feature[];
+}
+/**
+ * Builds the snapping providers for datasets
+ */
+export declare function createDisplaySnapProviders(deps: DisplaySnapProviderDeps): DisplaySnapProviders;