@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/impl/contexts.js

@@ -0,0 +1,466 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { formatColor } from '../../shared/color.js';
+import { DRAW_PROPERTY_KEYS, getDrawProperty } from '../../shared/properties.js';
+import { coordinatesOf } from '../../shared/utils/coordinates.js';
+import { isWritableLayer } from '../../store/writable-layer.js';
+import { anchorElevationMeters, getAnchorElevationGeneration, projectAnchor, } from '../../view/terrain/anchor.js';
+import { bindTerrainState } from '../../view/terrain/binding.js';
+import { anchorGhostOpacity } from '../../view/terrain/occlusion.js';
+import { computeBoundingBox, hasZeroArea } from '../../view/ui/selection-ui/index.js';
+import { mergeOptions } from './options.js';
+import { toDatasetRow } from './rows.js';
+// ============================================================================
+// Conversions
+// ============================================================================
+/**
+ * A point on the screen as the contract gives it
+ *
+ * @internal
+ */
+export function toScreenPoint(point) {
+    return [point.x, point.y];
+}
+/**
+ * A position as the contract gives it
+ *
+ * @internal
+ */
+export function toPosition(lngLat) {
+    return [lngLat.lng, lngLat.lat];
+}
+/**
+ * A snapping result of the engine in the shape of the contract
+ *
+ * @internal
+ */
+export function toSnapResult(result, fallback) {
+    if (!result)
+        return { lngLat: fallback };
+    const out = { lngLat: toPosition(result.lngLat) };
+    const target = result.target;
+    if (target) {
+        out.target = { kind: target.kind };
+        if (target.featureId !== undefined)
+            out.target.featureId = target.featureId;
+        if (target.datasetId !== undefined)
+            out.target.datasetId = target.datasetId;
+        if (target.description !== undefined)
+            out.target.description = target.description;
+        if (target.vertex !== undefined)
+            out.target.vertex = target.vertex;
+        if (target.segment !== undefined) {
+            out.target.segment = { start: target.segment.start, end: target.segment.end };
+        }
+    }
+    return out;
+}
+/** A value of an RGBA color from 0 to 1, as the internal styles hold them */
+function isRgba(value) {
+    return Array.isArray(value) && value.length === 4 && value.every((v) => typeof v === 'number');
+}
+/** The internal look of the selection with its colors written as CSS colors */
+function withCssColors(value) {
+    if (isRgba(value))
+        return formatColor(value);
+    if (Array.isArray(value))
+        return value.map(withCssColors);
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, withCssColors(v)]));
+    }
+    return value;
+}
+/**
+ * The look of the selection in the shape of the contract: what the options give, over the
+ * look the engine resolved from the defaults
+ *
+ * @param config - The look of the selection the engine draws with
+ * @param box - The look of the box selection the engine draws with
+ * @param given - The look of the selection the options give
+ * @internal
+ */
+export function toSelectionStyle(config, box, given) {
+    const resolved = {
+        ...withCssColors(config),
+        boxSelection: {
+            fillColor: formatColor([box.fillColor[0], box.fillColor[1], box.fillColor[2], 1]),
+            fillOpacity: box.fillColor[3],
+            strokeColor: formatColor(box.strokeColor),
+            strokeWidth: box.strokeWidth,
+        },
+    };
+    return mergeOptions(resolved, (given ?? {}));
+}
+/**
+ * The shape being drawn, as the engine keeps it, for a feature input of the contract
+ *
+ * @internal
+ */
+export function toTentative(input, layerId, pendingFeatureId) {
+    const state = {
+        type: input.type,
+        coordinates: coordinatesOf(input),
+        layerId,
+    };
+    if (pendingFeatureId !== undefined)
+        state.pendingFeatureId = pendingFeatureId;
+    const properties = input.properties ?? {};
+    const radius = properties[DRAW_PROPERTY_KEYS.radiusMeters];
+    const angle = properties[DRAW_PROPERTY_KEYS.radiusHandleAngle];
+    if (typeof radius === 'number')
+        state.radiusMeters = radius;
+    if (typeof angle === 'number')
+        state.radiusHandleAngle = angle;
+    return state;
+}
+/**
+ * The terrain anchors over the terrain state of an instance
+ *
+ * @internal
+ */
+export function createTerrainAnchors(terrain) {
+    const anchors = {
+        project(lngLat) {
+            const point = projectAnchor(terrain, lngLat[0], lngLat[1]);
+            return point ? [point.x, point.y] : null;
+        },
+        elevation: (lngLat) => anchorElevationMeters(terrain, lngLat[0], lngLat[1]),
+        ghostOpacity: (lngLat) => anchorGhostOpacity(terrain, lngLat[0], lngLat[1]),
+        generation: () => getAnchorElevationGeneration(terrain),
+    };
+    // The building blocks of the second entry find the state behind the anchors
+    bindTerrainState(anchors, terrain);
+    return anchors;
+}
+/**
+ * The automatic names over the name generator of an instance
+ *
+ * @internal
+ */
+export function createNameGenerator(generator) {
+    return {
+        next(type) {
+            if (type === 'Layer')
+                return generator.generateLayerName();
+            if (type === 'Group')
+                return generator.generateGroupName();
+            return generator.generateName(type);
+        },
+    };
+}
+/**
+ * The conversion between the map and the screen of an instance
+ *
+ * @internal
+ */
+export function createScreenContext(services, boundsOf) {
+    const { map } = services;
+    const project = (lngLat) => toScreenPoint(map.project([lngLat[0], lngLat[1]]));
+    return {
+        project,
+        unproject: (point) => toPosition(map.unproject(point)),
+        bounds(feature) {
+            const own = boundsOf?.(feature);
+            if (own !== undefined)
+                return own;
+            const box = computeBoundingBox(feature, services.selectionExtensions);
+            if (!box)
+                return null;
+            const corners = [box.topLeft, box.topRight, box.bottomRight, box.bottomLeft].map(project);
+            return {
+                min: [Math.min(...corners.map((c) => c[0])), Math.min(...corners.map((c) => c[1]))],
+                max: [Math.max(...corners.map((c) => c[0])), Math.max(...corners.map((c) => c[1]))],
+            };
+        },
+        outline(feature) {
+            const extensions = services.selectionExtensions;
+            const box = computeBoundingBox(feature, extensions);
+            if (!box)
+                return [];
+            if (hasZeroArea(box)) {
+                // A feature with no area has the frame of a point: its outline, or its extent, in
+                // pixels around its position
+                const [x, y] = project(box.center);
+                return extensions
+                    .resolvePointFrameCorners(feature, { x, y }, 0)
+                    .map((corner) => [corner.x, corner.y]);
+            }
+            return [box.topLeft, box.topRight, box.bottomRight, box.bottomLeft].map(project);
+        },
+        get zoom() {
+            return map.getZoom();
+        },
+        get pixelRatio() {
+            return services.pixelRatio.resolve();
+        },
+    };
+}
+/** @internal */
+export function createSubscriptions() {
+    const all = new Set();
+    return {
+        track(unsubscribe) {
+            let done = false;
+            const end = () => {
+                if (done)
+                    return;
+                done = true;
+                all.delete(end);
+                unsubscribe();
+            };
+            all.add(end);
+            return end;
+        },
+        endAll() {
+            for (const end of [...all])
+                end();
+        },
+    };
+}
+/**
+ * Builds the part every context of an extension has
+ *
+ * @param subscriptions - Where the subscriptions of the extension are kept
+ * @internal
+ */
+export function createExtensionContext(services, screen, subscriptions) {
+    const { store, spatialIndex, map } = services;
+    const listeners = new Map();
+    const forget = (event, listener) => {
+        const byEvent = listeners.get(listener);
+        byEvent?.delete(event);
+        if (byEvent?.size === 0)
+            listeners.delete(listener);
+    };
+    const subscribe = (event, listener, once) => {
+        const draw = services.getDraw();
+        const wrapped = once
+            ? (payload) => {
+                end();
+                listener(payload);
+            }
+            : listener;
+        const end = subscriptions.track(() => {
+            forget(event, listener);
+            draw.off(event, wrapped);
+        });
+        draw.on(event, wrapped);
+        let byEvent = listeners.get(listener);
+        if (!byEvent) {
+            byEvent = new Map();
+            listeners.set(listener, byEvent);
+        }
+        byEvent.get(event)?.();
+        byEvent.set(event, end);
+        return end;
+    };
+    return {
+        get draw() {
+            return services.getDraw();
+        },
+        store: services.store,
+        on: (event, listener) => subscribe(event, listener, false),
+        off(event, listener) {
+            listeners.get(listener)?.get(event)?.();
+        },
+        once: (event, listener) => subscribe(event, listener, true),
+        terrain: createTerrainAnchors(services.terrain),
+        names: createNameGenerator(services.autoNameGenerator),
+        screen,
+        invalidate(filter) {
+            if (filter?.type !== undefined)
+                spatialIndex.invalidateType(filter.type);
+            if (filter?.ids !== undefined)
+                spatialIndex.invalidate(filter.ids);
+            if (filter?.type === undefined && filter?.ids === undefined) {
+                spatialIndex.invalidate(store.listFeatures().map((feature) => feature.id));
+            }
+            map.triggerRepaint();
+        },
+        // The same object as draw.drawing, read when it is asked for: the draw instance is attached
+        // after the host is built
+        get drawing() {
+            return services.getDraw().drawing;
+        },
+    };
+}
+/**
+ * A topmost hit of the engine in the shape of the contract
+ *
+ * @internal
+ */
+export function toHit(top, distanceToFeaturePx) {
+    if (!top)
+        return null;
+    switch (top.kind) {
+        case 'store':
+            return {
+                kind: 'feature',
+                id: top.feature.id,
+                featureId: top.feature.id,
+                distancePx: distanceToFeaturePx(top.feature),
+            };
+        case 'dataset':
+            if (!top.feature)
+                return null;
+            return {
+                kind: 'dataset',
+                id: top.feature.id,
+                datasetId: top.dataset.id,
+                distancePx: 0,
+            };
+        case 'companion': {
+            const own = top.companion.hit.contractHit;
+            return (own ?? {
+                kind: 'companion',
+                id: top.companion.hit.id,
+                featureId: top.companion.featureId,
+                distancePx: 0,
+            });
+        }
+    }
+}
+/**
+ * Builds the context of a mode: the common part, and the hit testing, the snapping, the
+ * committing of features by the rules of the built-in modes, the preview and the cursor
+ *
+ * @internal
+ */
+export function createModeContext(services, screen) {
+    const { store, map } = services;
+    const subscriptions = createSubscriptions();
+    const base = createExtensionContext(services, screen, subscriptions);
+    /** The ID the shape being drawn will have once it is committed */
+    let pendingId = null;
+    /** The cursor the mode set while it was entered, which `cursor.reset` goes back to */
+    let modeCursor = '';
+    let entering = false;
+    /** Whether the mode has set a cursor, which is taken back when it is left */
+    let cursorSet = false;
+    const clearPreview = () => {
+        pendingId = null;
+        if (store.getTentative() !== null)
+            store.setTentative(null);
+    };
+    const context = {
+        get draw() {
+            return services.getDraw();
+        },
+        store: base.store,
+        on: base.on,
+        off: base.off,
+        once: base.once,
+        terrain: base.terrain,
+        names: base.names,
+        screen: base.screen,
+        invalidate: base.invalidate,
+        get drawing() {
+            return base.drawing;
+        },
+        setMode: (mode) => services.modeManager.setMode(mode),
+        hitTest(point, options) {
+            const at = { x: point[0], y: point[1] };
+            return toHit(services.hitTestTopmost(at, options?.tolerancePx), (feature) => services.distanceToFeaturePx(feature, at));
+        },
+        snap(point) {
+            const result = services.snapPoint({ x: point[0], y: point[1] });
+            return toSnapResult(result, toPosition(result.lngLat));
+        },
+        commitFeature(input) {
+            if (store.isReadOnly() || store.isInteractionLocked())
+                return null;
+            const layerId = input.layerId ?? services.getWritableLayerId();
+            if (layerId === '' || !isWritableLayer(store.getLayer(layerId), store)) {
+                // The layer went away, or was locked or hidden, while drawing: the drawing is dropped
+                clearPreview();
+                services.modeManager.setMode('select');
+                return null;
+            }
+            const properties = { ...(input.properties ?? {}) };
+            if (properties.name === undefined) {
+                const name = services.autoNameGenerator.generateName(input.type);
+                if (name !== undefined)
+                    properties.name = name;
+            }
+            if (services.scaleWithZoom &&
+                getDrawProperty({ properties }, 'createdZoom') === undefined) {
+                properties[DRAW_PROPERTY_KEYS.createdZoom] = map.getZoom();
+            }
+            const id = input.id ?? pendingId ?? undefined;
+            const feature = store.transact(() => {
+                const created = services.getDraw().features.create({
+                    ...input,
+                    ...(id !== undefined && { id }),
+                    layerId,
+                    properties: properties,
+                });
+                clearPreview();
+                return created;
+            });
+            if (feature)
+                services.notifyDrawCommit(feature);
+            return feature;
+        },
+        preview: {
+            set(feature, options) {
+                if (feature.id !== undefined)
+                    pendingId = feature.id;
+                pendingId ?? (pendingId = services.generateId());
+                const layerId = feature.layerId ?? services.getWritableLayerId();
+                const state = toTentative(feature, layerId, pendingId);
+                if (options?.confirmedVertices !== undefined) {
+                    state.confirmedCount = options.confirmedVertices;
+                }
+                if (options?.highlightVertex !== undefined) {
+                    state.highlightedVertexIndex = options.highlightVertex;
+                }
+                store.setTentative(state);
+            },
+            clear: clearPreview,
+        },
+        cursor: {
+            set(cursor) {
+                if (entering)
+                    modeCursor = cursor;
+                cursorSet = true;
+                map.getCanvas().style.cursor = cursor;
+            },
+            reset() {
+                map.getCanvas().style.cursor = modeCursor;
+            },
+        },
+        get selectionStyle() {
+            return toSelectionStyle(services.selectionStyle, services.boxSelectionStyle, services.getDraw().options.get().selectionStyle);
+        },
+        listTraceRows: (bbox) => services
+            .listTraceRows(bbox)
+            .filter((entry) => entry.rowIndex >= 0)
+            .map(({ datasetId, rowIndex, feature }) => ({
+            datasetId,
+            rowIndex,
+            row: toDatasetRow(feature),
+        })),
+        writableLayer() {
+            const id = services.getWritableLayerId();
+            return id === '' ? null : (store.getLayer(id) ?? null);
+        },
+    };
+    return {
+        context,
+        entering(run) {
+            entering = true;
+            try {
+                run();
+            }
+            finally {
+                entering = false;
+            }
+        },
+        dispose() {
+            subscriptions.endAll();
+            if (cursorSet)
+                map.getCanvas().style.cursor = '';
+            cursorSet = false;
+        },
+    };
+}

package/dist/api/impl/create-draw.js

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createDatasets } from './datasets.js';
+import { guardAfterDestroy } from './destroy-guard.js';
+import { createDocument } from './document.js';
+import { createDrawing, createDrawingResource } from './drawing.js';
+import { createEngine } from './engine.js';
+import { createFeatures } from './features.js';
+import { createGroups } from './groups.js';
+import { createHidden } from './hidden.js';
+import { createLayers } from './layers.js';
+import { createMetadata } from './metadata.js';
+import { checkDrawOptions, createOptions, toEngineOptions } from './options.js';
+import { createSelection, createVertexSelection } from './selection.js';
+import { invalidInput, notFound, requireRecord, withLocksIgnored } from './shared.js';
+/** The methods of the instance that return a promise: after destroy they reject */
+const ASYNC_MEMBERS = new Set(['document.load', 'document.loadMany']);
+/**
+ * Builds the draw instance on an engine and hands it to the extensions of the engine
+ *
+ * @param options - The options the instance was created with
+ * @param setExternalEntry - Replaces the function that tells the entries from outside the
+ *   document, which the engine asks
+ * @internal
+ */
+export function createDrawOnEngine(engine, options = {}, setExternalEntry = () => { }) {
+    const drawOptions = createOptions(engine, options, setExternalEntry);
+    drawOptions.applyCreation();
+    const { context, modeManager, events, map } = engine;
+    const { store } = context;
+    const view = store;
+    const deps = {
+        store,
+        generateId: context.generateFeatureId,
+        autoNameGenerator: context.autoNameGenerator,
+        getActiveLayerId: context.getActiveLayerId,
+        setActiveLayerId: context.setActiveLayerId,
+        getStyleOptions: drawOptions.getStyle,
+        spatialIndex: context.spatialIndex,
+    };
+    const features = createFeatures(deps);
+    const groups = createGroups(deps);
+    // Set once destroy has run to the end, so that the extensions removed by it can still read
+    // the instance
+    let destroyed = false;
+    const members = {
+        features,
+        layers: createLayers(deps, (id) => engine.datasets.get(id)?.order === 'layer-order' || context.isExternalEntry?.(id) === true),
+        groups,
+        datasets: createDatasets(engine.datasets, events, context.eventEmitter),
+        hidden: createHidden(deps),
+        selection: createSelection(deps, { features, groups }),
+        vertexSelection: createVertexSelection(deps),
+        drawing: createDrawingResource(engine),
+        metadata: createMetadata(deps),
+        options: { get: drawOptions.get, update: drawOptions.update },
+        document: createDocument(deps, (result, source) => events.emit('document.loaded', { result, source })),
+        extensions: engine.extensions.collections,
+        getMap: () => map,
+        getStore: () => view,
+        getMode: () => modeManager.getMode(),
+        setMode(mode) {
+            if (typeof mode !== 'string')
+                throw invalidInput('The mode must be a string');
+            if (!modeManager.hasMode(mode))
+                throw notFound('mode', mode);
+            return modeManager.setMode(mode);
+        },
+        isReadOnly: () => store.isReadOnly(),
+        setReadOnly(value) {
+            store.setReadOnly(value === true);
+        },
+        isInteractionLocked: () => store.isInteractionLocked(),
+        setInteractionLocked(value) {
+            store.setInteractionLock(value === true);
+            // A drawing mode cannot run under the lock
+            if (value === true && modeManager.getMode() !== 'select')
+                modeManager.setMode('select');
+        },
+        transact(fn, transactOptions) {
+            if (transactOptions !== undefined)
+                requireRecord(transactOptions, 'The options');
+            const run = () => store.transact(fn, transactOptions?.source);
+            return transactOptions?.ignoreLocks === true ? withLocksIgnored(store, run) : run();
+        },
+        on: (event, listener) => events.on(event, listener),
+        off: (event, listener) => events.off(event, listener),
+        once: (event, listener) => events.once(event, listener),
+        ...createDrawing(engine),
+        destroy() {
+            if (destroyed)
+                return;
+            try {
+                engine.destroy();
+            }
+            finally {
+                destroyed = true;
+            }
+        },
+    };
+    // After destroy, every method but destroy throws invalid-state
+    const draw = guardAfterDestroy(members, () => destroyed, {
+        asyncMembers: ASYNC_MEMBERS,
+        skip: new Set(['destroy']),
+    });
+    engine.extensions.attach(draw, options.store);
+    return draw;
+}
+/**
+ * Puts a draw instance on a map and returns it.
+ *
+ * @internal
+ */
+export function createDraw(map, options = {}) {
+    checkDrawOptions(options);
+    // The engine asks this function, so that the option can change while the instance runs
+    let isExternalEntry = options.isExternalEntry;
+    const engine = createEngine(map, toEngineOptions(options, (id) => isExternalEntry?.(id) === true), { deferDefaultMode: true });
+    const draw = createDrawOnEngine(engine, options, (fn) => {
+        isExternalEntry = fn;
+    });
+    engine.enterDefaultMode();
+    return draw;
+}