@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/impl/extension-host.js

@@ -0,0 +1,361 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { DrawError } from '../errors.js';
+import { adaptCompanionProvider, adaptHandleProvider, adaptSnapProvider, installFeatureType, } from './adapters.js';
+import { createExtensionContext, createModeContext, createScreenContext, createSubscriptions, createTerrainAnchors, toHit, } from './contexts.js';
+import { createExtensionsCollections, createRegistry, OVERRIDABLE_TYPES } from './extensions.js';
+import { preparePatch } from './features.js';
+import { bridgeMode, createInputRoute, deliverPointerLeave, toPointerEvent } from './input.js';
+import { createOverlayStack, terrainAnchorsOf } from './render-context.js';
+import { validateExtension } from './validate-extension.js';
+/** The feature types of the engine, which a custom type cannot take the name of */
+const BUILT_IN_TYPES = new Set([
+    'Point',
+    'LineString',
+    'Polygon',
+    'MultiPoint',
+    'MultiLineString',
+    'MultiPolygon',
+    'Image',
+    'Circle',
+    'Freehand',
+]);
+/**
+ * Builds the host of the extensions of an engine
+ *
+ * @internal
+ */
+export function createExtensionHost(deps) {
+    const { map, context, customLayer, modeManager, featureCompanions } = deps;
+    const { store } = context;
+    const terrain = customLayer.getTerrainContext();
+    let destroyed = false;
+    let attached = null;
+    const getDraw = () => {
+        if (!attached) {
+            throw new DrawError('invalid-state', 'The draw instance is not attached to its extensions yet');
+        }
+        return attached;
+    };
+    const screen = createScreenContext({
+        map,
+        pixelRatio: context.pixelRatioSource,
+        selectionExtensions: context.selectionScope.extensions,
+    });
+    const adapterDeps = {
+        map,
+        store,
+        screen,
+        clickTolerancePx: context.options.clickTolerance,
+        hitTestService: context.hitTestService,
+        boxSelectionRegistry: context.boxSelectionRegistry,
+        selectionExtensions: context.selectionScope.extensions,
+        auxiliaryHandles: context.selectionScope.auxiliaryHandles,
+        featureCompanions,
+        snapTargets: context.snapTargets,
+        customLayer,
+        spatialIndex: context.spatialIndex,
+        anchors: (state) => terrainAnchorsOf(state, createTerrainAnchors),
+        registerSnapProvider: (provider) => context.snapService.register(provider),
+        applyPatch(featureId, patch, final) {
+            const feature = store.getFeature(featureId);
+            if (!feature || store.isReadOnly())
+                return;
+            store.updateFeature(featureId, preparePatch(feature, patch), { isIntermediate: !final });
+        },
+    };
+    const overlays = createOverlayStack(customLayer, adapterDeps);
+    /** An installer that installs nothing once the instance is destroyed */
+    const guarded = (installer) => ({
+        ...installer,
+        install: (name, value) => (destroyed ? () => { } : installer.install(name, value)),
+    });
+    const registries = {
+        plugins: createRegistry(guarded({
+            kind: 'plugin',
+            validate: (_, plugin) => validateExtension('plugin', plugin),
+            install: (_, plugin) => installPlugin(plugin),
+        })),
+        modes: createRegistry(guarded({
+            kind: 'mode',
+            validate: (_, factory) => validateExtension('mode', factory),
+            isTakenElsewhere: (name) => modeManager.hasMode(name),
+            install: (name, factory) => modeManager.registerMode(name, () => {
+                const handle = createModeContext(modeServices, screen);
+                try {
+                    return bridgeMode(name, factory(handle.context), handle.dispose, handle.entering);
+                }
+                catch (error) {
+                    handle.dispose();
+                    throw error;
+                }
+            }),
+        })),
+        featureTypes: createRegistry(guarded({
+            kind: 'feature type',
+            validate: (_, definition) => validateExtension('feature type', definition),
+            isTakenElsewhere: (name) => BUILT_IN_TYPES.has(name),
+            install: (name, definition) => installFeatureType(definition, adapterDeps, OVERRIDABLE_TYPES.has(name)),
+        })),
+        overlays: createRegistry(guarded({
+            kind: 'overlay',
+            validate: (_, overlay) => validateExtension('overlay', overlay),
+            install: (_, overlay) => overlays.add(overlay),
+        })),
+        snapProviders: createRegistry(guarded({
+            kind: 'snap provider',
+            validate: (_, provider) => validateExtension('snap provider', provider),
+            install: (_, provider) => context.snapService.register(adaptSnapProvider(provider, screen)),
+        })),
+        handleProviders: createRegistry(guarded({
+            kind: 'handle provider',
+            validate: (_, provider) => validateExtension('handle provider', provider),
+            isTakenElsewhere: (name) => context.selectionScope.auxiliaryHandles.get(name) !== undefined,
+            install: (_, provider) => context.selectionScope.auxiliaryHandles.register(adaptHandleProvider(provider, adapterDeps)),
+        })),
+        companionProviders: createRegistry(guarded({
+            kind: 'companion provider',
+            validate: (_, provider) => validateExtension('companion provider', provider),
+            isTakenElsewhere: (name) => featureCompanions.get(name) !== undefined,
+            install: (_, provider) => featureCompanions.register(adaptCompanionProvider(provider, adapterDeps)),
+        })),
+    };
+    const collections = createExtensionsCollections(registries);
+    const services = {
+        map,
+        store,
+        terrain,
+        pixelRatio: context.pixelRatioSource,
+        autoNameGenerator: context.autoNameGenerator,
+        selectionExtensions: context.selectionScope.extensions,
+        spatialIndex: context.spatialIndex,
+        modeManager,
+        getDraw,
+        collections,
+    };
+    const unproject = (point) => map.unproject([point.x, point.y]);
+    const modeServices = {
+        ...services,
+        hitTestTopmost(point, tolerancePx) {
+            const tester = tolerancePx === undefined || tolerancePx === context.options.clickTolerance
+                ? deps.hitTestTopmost
+                : deps.hitTestTopmostWith(tolerancePx);
+            return tester(point);
+        },
+        distanceToFeaturePx(feature, point) {
+            const hit = context.hitTestService.hitTestAll(point, unproject, [feature])[0];
+            if (!hit)
+                return 0;
+            const onePixel = Math.abs(unproject({ x: point.x + 1, y: point.y }).lng - unproject(point).lng);
+            return onePixel > 0 ? hit.distance / onePixel : 0;
+        },
+        snapPoint(point) {
+            const lngLat = unproject(point);
+            const handler = modeManager.getHandler();
+            const prefer = handler?.getSnapPreference?.() ?? undefined;
+            return context.snapService.resolve({ lng: lngLat.lng, lat: lngLat.lat }, point, {
+                zoom: map.getZoom(),
+                modifiers: { shift: false, ctrl: false, alt: false, meta: false },
+                ...(prefer && { preferFeature: prefer }),
+            });
+        },
+        listTraceRows(bbox) {
+            return deps.listTraceRows({ minX: bbox[0], minY: bbox[1], maxX: bbox[2], maxY: bbox[3] });
+        },
+        getWritableLayerId: context.getWritableLayerId,
+        generateId: context.generateFeatureId,
+        scaleWithZoom: context.options.scaleWithZoom,
+        selectionStyle: context.selectionStyle,
+        boxSelectionStyle: context.renderingConfig.boxSelectionStyle,
+        notifyDrawCommit: (feature) => announceDrawCommit(feature),
+    };
+    /**
+     * Installs a plugin: calls its onAdd with a context that records what the plugin adds, and
+     * returns the removal, which calls its onRemove and removes what it added
+     */
+    function installPlugin(plugin) {
+        const subscriptions = createSubscriptions();
+        const added = [];
+        const disposeAll = () => {
+            subscriptions.endAll();
+            for (let i = added.length - 1; i >= 0; i--)
+                added[i]();
+            added.length = 0;
+        };
+        const base = createExtensionContext(services, screen, subscriptions);
+        const pluginContext = {
+            get draw() {
+                return 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;
+            },
+            extensions: createExtensionsCollections(registries, (remove) => added.push(remove)),
+        };
+        try {
+            plugin.onAdd(pluginContext);
+        }
+        catch (error) {
+            disposeAll();
+            throw error;
+        }
+        return () => {
+            try {
+                plugin.onRemove?.();
+            }
+            catch (error) {
+                console.error(`Error in plugin "${plugin.name}" onRemove:`, error);
+            }
+            finally {
+                disposeAll();
+            }
+        };
+    }
+    /** Calls a hook of every plugin in turn; one that throws is reported and skipped */
+    function eachPlugin(hook, call) {
+        for (const plugin of registries.plugins.values()) {
+            try {
+                if (call(plugin) === true)
+                    return true;
+            }
+            catch (error) {
+                console.error(`Error in plugin "${plugin.name}" ${hook}:`, error);
+            }
+        }
+        return false;
+    }
+    /** Tells every plugin that a drawing mode created a feature */
+    function announceDrawCommit(feature) {
+        eachPlugin('onDrawCommit', (plugin) => {
+            plugin.interaction?.onDrawCommit?.(feature);
+            return false;
+        });
+    }
+    const featureOf = (id) => store.getFeature(id);
+    const click = (hook) => (featureId, event) => {
+        const feature = featureOf(featureId);
+        if (!feature || !event)
+            return false;
+        return eachPlugin(hook, (plugin) => {
+            const handler = plugin.interaction?.[hook];
+            return handler?.call(plugin.interaction, feature, toPointerEvent(event)) === true;
+        });
+    };
+    const interactions = {
+        filterSelectionCandidates(candidateIds) {
+            let filtered = candidateIds;
+            eachPlugin('filterSelection', (plugin) => {
+                const filter = plugin.interaction?.filterSelection;
+                if (filter)
+                    filtered = filter.call(plugin.interaction, filtered);
+                return false;
+            });
+            return filtered;
+        },
+        handleFeatureClick: click('onFeatureClick'),
+        handleFeatureDoubleClick: click('onFeatureDoubleClick'),
+        isPluginInteracting: () => eachPlugin('isBusy', (plugin) => plugin.interaction?.isBusy?.() === true),
+        finishPluginInteraction() {
+            eachPlugin('finish', (plugin) => {
+                plugin.interaction?.finish?.();
+                return false;
+            });
+        },
+        cancelPluginInteraction() {
+            eachPlugin('cancel', (plugin) => {
+                plugin.interaction?.cancel?.();
+                return false;
+            });
+        },
+        getPluginInteractionContainer() {
+            let container = null;
+            eachPlugin('container', (plugin) => {
+                if (plugin.interaction?.isBusy?.() !== true)
+                    return false;
+                container = plugin.interaction.container?.() ?? null;
+                return container !== null;
+            });
+            return container;
+        },
+        notifyFeatureCreated(featureId) {
+            const feature = featureOf(featureId);
+            if (feature)
+                announceDrawCommit(feature);
+        },
+    };
+    const input = createInputRoute(() => registries.plugins.values());
+    const onPointerLeave = () => deliverPointerLeave(registries.plugins.values(), modeManager.getHandler());
+    let listening = false;
+    const watches = [];
+    /**
+     * The image mode asks the application for a file (`image.requested`), and the application
+     * places the image by loading the file. The image that load places is the commit of the
+     * image mode, which the plugins hear of as the commits of the other drawing modes
+     */
+    function watchImageCommits(draw) {
+        let requested = false;
+        watches.push(draw.on('image.requested', () => {
+            requested = true;
+        }), draw.on('document.loaded', ({ result }) => {
+            if (!requested || result.format !== 'image')
+                return;
+            requested = false;
+            for (const id of result.featureIds) {
+                const feature = featureOf(id);
+                if (feature)
+                    announceDrawCommit(feature);
+            }
+        }));
+    }
+    return {
+        collections,
+        input,
+        interactions,
+        hitAt: (point) => toHit(modeServices.hitTestTopmost(point), (feature) => modeServices.distanceToFeaturePx(feature, point)),
+        attach(draw, documentStore) {
+            attached = draw;
+            watchImageCommits(draw);
+            // A Store that replaces its whole document says so with `reset`: the mode drops what it
+            // was drawing, as it does for an Escape
+            if (documentStore) {
+                watches.push(documentStore.subscribe((changes) => {
+                    if (changes.reset === true && !destroyed)
+                        modeManager.notifyStateReset();
+                }));
+            }
+        },
+        start() {
+            if (listening || destroyed)
+                return;
+            listening = true;
+            map.getCanvasContainer().addEventListener('mouseleave', onPointerLeave);
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            for (const stop of watches.splice(0))
+                stop();
+            if (listening) {
+                listening = false;
+                map.getCanvasContainer().removeEventListener('mouseleave', onPointerLeave);
+            }
+            // The plugins go first, with what they added, then the rest in the reverse order
+            registries.plugins.clear();
+            registries.companionProviders.clear();
+            registries.handleProviders.clear();
+            registries.snapProviders.clear();
+            registries.overlays.clear();
+            registries.featureTypes.clear();
+            registries.modes.clear();
+            destroyed = true;
+        },
+    };
+}

package/dist/api/impl/extensions.js

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { DrawError } from '../errors.js';
+import { invalidInput, notFound } from './shared.js';
+/**
+ * Creates the registry of one kind of extension
+ *
+ * @internal
+ */
+export function createRegistry(installer) {
+    const entries = new Map();
+    const requireName = (name) => {
+        if (typeof name !== 'string' || name === '') {
+            throw invalidInput(`The name of the ${installer.kind} must be a non-empty string`);
+        }
+        return name;
+    };
+    const uninstall = (name, entry) => {
+        if (entries.get(name) !== entry)
+            return;
+        entries.delete(name);
+        entry.uninstall();
+    };
+    return {
+        get: (name) => entries.get(name)?.value,
+        names: () => [...entries.keys()],
+        values: () => [...entries.values()].map((entry) => entry.value),
+        count: () => entries.size,
+        has: (name) => entries.has(name),
+        holds: (name, value) => entries.get(name)?.value === value,
+        add(list, options) {
+            if (!Array.isArray(list))
+                throw invalidInput(`The ${installer.kind}s must be an array`);
+            const seen = new Set();
+            for (const [rawName, value] of list) {
+                const name = requireName(rawName);
+                installer.validate(name, value);
+                const takenElsewhere = !options?.overriding && installer.isTakenElsewhere?.(name);
+                if (seen.has(name) || entries.has(name) || takenElsewhere) {
+                    throw new DrawError('already-exists', `There is already a ${installer.kind} named ${JSON.stringify(name)}`, { name });
+                }
+                seen.add(name);
+            }
+            const added = [];
+            try {
+                for (const [name, value] of list) {
+                    const entry = { value, uninstall: installer.install(name, value) };
+                    entries.set(name, entry);
+                    added.push([name, entry]);
+                }
+            }
+            catch (error) {
+                for (let i = added.length - 1; i >= 0; i--)
+                    uninstall(added[i][0], added[i][1]);
+                throw error;
+            }
+            let removed = false;
+            return () => {
+                if (removed)
+                    return;
+                removed = true;
+                for (let i = added.length - 1; i >= 0; i--)
+                    uninstall(added[i][0], added[i][1]);
+            };
+        },
+        remove(names) {
+            if (!Array.isArray(names))
+                throw invalidInput('The names must be an array');
+            for (const name of names) {
+                if (!entries.has(name))
+                    throw notFound(installer.kind, name);
+            }
+            for (const name of new Set(names)) {
+                const entry = entries.get(name);
+                if (entry)
+                    uninstall(name, entry);
+            }
+            return true;
+        },
+        clear() {
+            for (const [name, entry] of [...entries].reverse())
+                uninstall(name, entry);
+        },
+    };
+}
+/** The name of an extension that carries one, as a checked string */
+function nameOf(value, kind) {
+    const name = value?.name;
+    if (typeof name !== 'string' || name === '') {
+        throw invalidInput(`The ${kind} must have a non-empty name`);
+    }
+    return name;
+}
+/** The collection of the extensions that are named by a member */
+function namedCollection(registry, kind, record) {
+    const addAll = (values) => {
+        if (!Array.isArray(values))
+            throw invalidInput(`The ${kind}s must be an array`);
+        const remove = registry.add(values.map((value) => [nameOf(value, kind), value]));
+        record?.(remove);
+        return remove;
+    };
+    return {
+        get: (name) => registry.get(name),
+        list: () => registry.names(),
+        count: () => registry.count(),
+        has: (name) => registry.has(name),
+        add: (value) => addAll([value]),
+        addMany: addAll,
+        remove: (name) => registry.remove([name]),
+        removeMany: (names) => registry.remove(names),
+    };
+}
+/**
+ * The collections of `draw.extensions` over the registries
+ *
+ * @param record - Receives the remover of every addition; a plugin context passes it to
+ *   remove what the plugin added when the plugin is removed
+ * @internal
+ */
+export function createExtensionsCollections(registries, record) {
+    const plugins = namedCollection(registries.plugins, 'plugin', record);
+    const pluginsCollection = {
+        get: (name) => registries.plugins.get(name),
+        list: () => registries.plugins.values(),
+        count: plugins.count,
+        has: plugins.has,
+        add: plugins.add,
+        addMany: plugins.addMany,
+        remove: plugins.remove,
+        removeMany: plugins.removeMany,
+        getApi: (name) => registries.plugins.get(name)?.api,
+    };
+    const modes = {
+        get: (name) => registries.modes.get(name),
+        list: () => registries.modes.names(),
+        count: () => registries.modes.count(),
+        has: (name) => registries.modes.has(name),
+        add: (name, factory) => modes.addMany([{ name, factory }]),
+        addMany(entries) {
+            if (!Array.isArray(entries))
+                throw invalidInput('The modes must be an array');
+            const remove = registries.modes.add(entries.map((entry) => {
+                if (typeof entry !== 'object' || entry === null) {
+                    throw invalidInput('A mode must be given as { name, factory }');
+                }
+                return [entry.name, entry.factory];
+            }));
+            record?.(remove);
+            return remove;
+        },
+        remove: (name) => registries.modes.remove([name]),
+        removeMany: (names) => registries.modes.remove(names),
+    };
+    const byType = namedCollectionByType(registries.featureTypes, record);
+    const overlays = namedCollection(registries.overlays, 'overlay', record);
+    const snapProviders = namedCollection(registries.snapProviders, 'snap provider', record);
+    const handleProviders = namedCollection(registries.handleProviders, 'handle provider', record);
+    const companionProviders = namedCollection(registries.companionProviders, 'companion provider', record);
+    return {
+        plugins: pluginsCollection,
+        modes,
+        featureTypes: byType,
+        overlays,
+        snapProviders,
+        handleProviders,
+        companionProviders,
+    };
+}
+/**
+ * The built-in feature types a definition can override, with the kind of geometry their
+ * features hold
+ *
+ * @internal
+ */
+export const OVERRIDABLE_TYPES = new Map([
+    ['Point', 'Point'],
+    ['LineString', 'LineString'],
+    ['Polygon', 'Polygon'],
+    ['Circle', 'Point'],
+    ['Freehand', 'LineString'],
+    ['Image', 'Point'],
+]);
+/** The type of a feature type definition, as a checked string */
+function typeOf(definition) {
+    const type = definition?.type;
+    if (typeof type !== 'string' || type === '') {
+        throw invalidInput('A feature type must have a non-empty type');
+    }
+    return type;
+}
+/** The feature types, named by their `type` */
+function namedCollectionByType(registry, record) {
+    const addAll = (definitions) => {
+        if (!Array.isArray(definitions))
+            throw invalidInput('The feature types must be an array');
+        const remove = registry.add(definitions.map((definition) => [typeOf(definition), definition]));
+        record?.(remove);
+        return remove;
+    };
+    return {
+        override(definition) {
+            const type = typeOf(definition);
+            const geometry = OVERRIDABLE_TYPES.get(type);
+            if (geometry === undefined) {
+                throw invalidInput(`${JSON.stringify(type)} is not a built-in type that can be overridden`, {
+                    type,
+                });
+            }
+            if (definition.geometry !== geometry) {
+                throw invalidInput(`A definition that overrides ${type} must have the geometry ${geometry}`, {
+                    type,
+                    geometry: definition.geometry,
+                });
+            }
+            const remove = registry.add([[type, definition]], { overriding: true });
+            record?.(remove);
+            return remove;
+        },
+        get: (name) => registry.get(name),
+        list: () => registry.names(),
+        count: () => registry.count(),
+        has: (name) => registry.has(name),
+        add: (definition) => addAll([definition]),
+        addMany: addAll,
+        remove: (name) => registry.remove([name]),
+        removeMany: (names) => registry.remove(names),
+    };
+}