@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/snapping/providers/guide.js

@@ -19,8 +19,7 @@
  *
  * Only the north-based guide works from the very first segment. The built-in provider
  * reads the step angle from SnapOptions.guideStepDegrees at every query (through a
- * getter), so a change at runtime takes effect without rebuilding the provider. A
- * provider made with createGuideSnapProvider keeps the step it was built with.
+ * getter), so a change at runtime takes effect without rebuilding the provider.
  *
  * A guide is not an infinite line; it is cut off at the equivalent of 4096 pixels on
  * screen. The priority order stays SNAP_KIND_PRIORITY, so a real vertex,
@@ -97,48 +96,6 @@ function guideSegment(anchor, lengthMeters, bearing, description, backwardBearin
         description,
     };
 }
-/**
- * Creates a snapping provider of construction guides for `draw_line` and `draw_polygon`.
- *
- * The guides start at the last committed vertex (the anchor): the north-based guides at every
- * `northStepDegrees` from true north (from the first vertex on), and the extension and the
- * perpendiculars of the previous segment (from the second vertex on). Each guide is a
- * segment 4096 screen px long, returned as a candidate of kind `'guide'` whose description
- * comes from `messages` (`snapNorth`, `snapExtension`, `snapPerpendicular`). Outside those
- * two modes it returns no candidates.
- *
- * The draw instance already registers a built-in one, whose step is set with
- * `options.snap.guideStepDegrees` and changed at runtime with `draw.snapping.setGuideStep`.
- * Register another one to add guides at a second step on top of the built-in ones.
- *
- * @param deps The Store to read the drawing in progress from
- * @param options The step angle, the tile size and the messages
- * @returns A provider to pass to `draw.snapping.register`
- *
- * @example
- * ```ts
- * import { createGuideSnapProvider, type Plugin } from '@sakuzu/maplibre-gl-draw';
- *
- * // Guides every 15 degrees from north, in addition to the built-in ones
- * let unregister: (() => void) | undefined;
- * const fineGuides: Plugin = {
- *   name: 'fine-guides',
- *   onInstall(ctx) {
- *     unregister = draw.snapping.register(
- *       createGuideSnapProvider({ store: ctx.getStore() }, { northStepDegrees: 15 }),
- *     );
- *   },
- *   onUninstall() {
- *     unregister?.();
- *   },
- * };
- * draw.addPlugin(fineGuides);
- * ```
- */
-export function createGuideSnapProvider(deps, options = {}) {
-    const step = resolveGuideStepDegrees(options.northStepDegrees);
-    return createSteppedGuideSnapProvider(deps, () => step, options);
-}
 /**
  * Creates the guide provider whose step angle is read through a getter at every query
  * (the built-in provider reads the current `guideStepDegrees` of the SnapService this way)

package/dist/snapping/providers/intersection.js

@@ -28,7 +28,7 @@ function collectNearbySegments(deps, bbox, ctx) {
     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))
+        if (deps.snapTargets?.forFeature(feature))
             continue;
         if (!hasSnapEdges(feature.type))
             continue;

package/dist/snapping/providers/store.js

@@ -17,7 +17,7 @@
  *   - 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
+ * For a custom feature type, FeatureTypeHandler.getSnapTargets is used when it is
  * registered (the vertex provider calls it).
  */
 import { resolveMessages } from '../../messages.js';
@@ -43,7 +43,7 @@ export function createStoreVertexSnapProvider(deps) {
             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);
+                const custom = deps.snapTargets?.forFeature(feature);
                 if (custom) {
                     for (const candidate of custom(feature, ctx)) {
                         const featureId = candidate.featureId ?? feature.id;
@@ -87,7 +87,7 @@ export function createStoreEdgeSnapProvider(deps) {
             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))
+                if (deps.snapTargets?.forFeature(feature))
                     continue;
                 if (!hasSnapEdges(feature.type))
                     continue;

package/dist/snapping/service.js

@@ -62,11 +62,13 @@ function isSameResult(a, b) {
 /**
  * Whether the new candidate replaces the current best candidate
  */
-function isBetterCandidate(best, priority, distancePx, preferred) {
+function isBetterCandidate(best, priority, distancePx, preferred, rank) {
     if (best.priority !== priority)
         return priority < best.priority;
     if (best.distancePx !== distancePx)
         return distancePx < best.distancePx;
+    if (best.rank !== rank)
+        return rank > best.rank;
     // Only on a complete tie does a candidate of the preferred feature overturn the one
     // that arrived first
     return preferred && !best.preferred;
@@ -115,15 +117,14 @@ export function createSnapService(deps = {}) {
      * 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) {
+    function evaluate(best, coordinate, target, priority, cursor, perPixel, preferred, rank) {
         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)) {
+        if (best && !isBetterCandidate(best, priority, distancePx, preferred, rank)) {
             return best;
         }
-        return { coordinate, target, priority, distancePx, preferred };
+        return { coordinate, target, priority, distancePx, rank, preferred };
     }
     /** How far a longitude moves to reach its copy nearest to the cursor (0 in most cases) */
     function turnToCursor(lng, cursorLng) {
@@ -196,7 +197,9 @@ export function createSnapService(deps = {}) {
                         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 };
+                    const target = {
+                        kind: (!isSegmentCandidate(candidate) && candidate.ownKind) || candidate.kind,
+                    };
                     if (candidate.featureId !== undefined)
                         target.featureId = candidate.featureId;
                     if (candidate.datasetId !== undefined)
@@ -219,7 +222,9 @@ export function createSnapService(deps = {}) {
                     const preferred = ctx.preferFeature !== undefined &&
                         candidate.featureId === ctx.preferFeature.featureId &&
                         candidate.datasetId === ctx.preferFeature.datasetId;
-                    best = evaluate(best, coordinate, target, cursor, perPixel, preferred);
+                    const rank = isSegmentCandidate(candidate) ? 0 : (candidate.priority ?? 0);
+                    const priority = SNAP_KIND_PRIORITY[candidate.kind];
+                    best = evaluate(best, coordinate, target, priority, cursor, perPixel, preferred, rank);
                 }
             }
         }
@@ -244,6 +249,12 @@ export function createSnapService(deps = {}) {
         setEnabled(value) {
             enabled = value;
         },
+        setTolerance(px) {
+            options.tolerancePx = px;
+        },
+        setDisableKey(key) {
+            options.disableKey = key;
+        },
         isEnabled() {
             return enabled;
         },

package/dist/snapping/types.d.ts

@@ -40,8 +40,7 @@ export interface SnapExcludeVertex {
 /**
  * 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.
+ * The library builds it for every input.
  */
 export interface SnapContext {
     /** The current zoom level (used to convert the pixel tolerance into degrees) */
@@ -125,6 +124,13 @@ export interface SnapPointCandidate {
     vertex?: VertexRef;
     /** A label for the host to show, passed on as `SnapTarget.description` */
     description?: string;
+    /** The priority among candidates of the same kind at the same distance; higher wins */
+    priority?: number;
+    /**
+     * The kind of its own a provider gave the candidate, passed on as `SnapTarget.kind`; the
+     * candidate is ranked and switched on and off by `kind`
+     */
+    ownKind?: string;
 }
 /**
  * A snapping candidate that snaps to the point of a segment closest to the cursor.
@@ -169,27 +175,6 @@ export type SnapCandidate = SnapPointCandidate | SnapSegmentCandidate;
  * (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) */
@@ -209,22 +194,11 @@ export interface SnapProvider {
  */
 export type SnapDisableKey = 'alt' | 'shift' | 'ctrl' | 'meta' | 'none';
 /**
- * The snapping options, given as `options.snap` of `createMapLibreGLDraw`.
+ * The snapping options of the engine (`createDraw` translates its `snapping` option).
  *
  * 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` */