@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/{maplibre-gl-draw.js → api/impl/engine.js}

@@ -1,28 +1,25 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
-import { createDrawAPI } from './api/api.js';
-import { createContext } from './api/context.js';
-import { createImportExportAPI } from './api/import-export/index.js';
-import { toleranceDegrees } from './dispatcher/hit-test/local-frame.js';
-import { createTopmostHitTester } from './dispatcher/hit-test/topmost.js';
-import { createInputRouter } from './dispatcher/input-router.js';
-import { createInputNormalizer } from './dispatcher/normalizer.js';
-import { createDisplayInteractions } from './display/interaction.js';
-import { createDatasetManager } from './display/manager.js';
-import { effectiveZoomForCamera } from './display/thinning.js';
-import { TriangulationScheduler } from './display/triangulation.js';
-import { DrawCircleMode, DrawFreehandMode, DrawImageMode, DrawLineMode, DrawPointMode, DrawPolygonMode, } from './modes/draw/index.js';
-import { SelectMode } from './modes/select/mode.js';
-import { createPluginContext } from './plugins/plugin-context.js';
-import { createPluginManager } from './plugins/plugin-manager.js';
-import { SnapIndicatorRenderer } from './snapping/indicator.js';
-import { createDisplaySnapProviders } from './snapping/providers/display.js';
-import { EventBridgeImpl } from './store/event-bridge.js';
-import { createRenderCoordinator } from './view/coordinator.js';
-import { createFeatureCompanionRegistry } from './view/feature-companion.js';
-import { attachSlotLayers } from './view/layer/attach.js';
-import { createCustomLayer } from './view/layer/index.js';
-import { DEFAULT_VIEWPORT_EXPANSION_FACTOR, getExpandedViewportBounds } from './view/viewport.js';
+import { createDisplayInteractions } from '../../dataset/interaction.js';
+import { createDatasetManager } from '../../dataset/manager.js';
+import { effectiveZoomForCamera } from '../../dataset/thinning.js';
+import { TriangulationScheduler } from '../../dataset/triangulation.js';
+import { toleranceDegrees } from '../../dispatcher/hit-test/local-frame.js';
+import { createTopmostHitTester } from '../../dispatcher/hit-test/topmost.js';
+import { createInputRouter } from '../../dispatcher/input-router.js';
+import { createInputNormalizer } from '../../dispatcher/normalizer.js';
+import { DrawImageMode, drawCircleMode, drawFreehandMode, drawLineMode, drawPointMode, drawPolygonMode, } from '../../modes/draw/index.js';
+import { SelectMode } from '../../modes/select/mode.js';
+import { SnapIndicatorRenderer } from '../../snapping/indicator.js';
+import { createDisplaySnapProviders } from '../../snapping/providers/display.js';
+import { createRenderCoordinator } from '../../view/coordinator.js';
+import { createFeatureCompanionRegistry } from '../../view/feature-companion.js';
+import { attachSlotLayers } from '../../view/layer/attach.js';
+import { createCustomLayer } from '../../view/layer/index.js';
+import { DEFAULT_VIEWPORT_EXPANSION_FACTOR, getExpandedViewportBounds, } from '../../view/viewport.js';
+import { createContext } from './engine-context.js';
+import { connectEngineEvents, connectStoreEvents, createEventHub } from './events.js';
+import { createExtensionHost } from './extension-host.js';
 /**
  * The releases of one draw instance, run in the reverse order of the acquisitions
  *
@@ -60,37 +57,11 @@ function createTeardown() {
     };
 }
 /**
- * Creates a draw instance on a MapLibre map: the drawing and editing tools, their rendering and
- * their input handling.
+ * Builds the engine of a draw instance on a map
  *
- * It can be called before, while or after the map loads. The render layers are added as soon
- * as the style accepts layers, and added again after `setStyle`. Unless
- * `initDefaultLayer: false` is given, the document starts with one empty layer. The instance
- * turns off the map's box zoom (Shift + drag selects features instead) and gives it back on
- * {@link MapLibreGLDraw.destroy}. Several instances can share a page, each on its own map.
- *
- * @param map the MapLibre map to draw on
- * @param options the options; every one can be omitted (see {@link Options})
- * @returns the draw instance
- *
- * @example
- * ```typescript
- * import { createMapLibreGLDraw } from '@sakuzu/maplibre-gl-draw';
- * import * as maplibregl from 'maplibre-gl';
- *
- * const map = new maplibregl.Map({
- *   container: 'map',
- *   style: 'https://demotiles.maplibre.org/style.json',
- *   center: [139.767, 35.681],
- *   zoom: 12,
- * });
- * const draw = createMapLibreGLDraw(map, { defaultMode: 'select' });
- *
- * draw.setMode('draw_polygon');
- * draw.on('draw.feature.create', ({ feature }) => console.log('Created', feature.id));
- * ```
+ * @internal
  */
-export function createMapLibreGLDraw(map, options = {}) {
+export function createEngine(map, options = {}, build = {}) {
     // 1. Create the context
     const context = createContext(map, options);
     const { store, modeManager, eventEmitter, spatialIndex, hitTestService, featureStyle, selectionStyle, renderingConfig, topology, trace, snapService, pixelRatioSource, } = context;
@@ -101,8 +72,8 @@ export function createMapLibreGLDraw(map, options = {}) {
         context.selectionScope.clear();
         context.snapTargets.clear();
     });
-    // 2. Create the EventBridge
-    const eventBridge = new EventBridgeImpl(store, eventEmitter);
+    const triangulationScheduler = new TriangulationScheduler();
+    triangulationScheduler.setSlicing(renderingConfig.timeSlicing !== false);
     // 2.5 Create the manager of the datasets.
     // Culls with the same expanded viewport as the rendering loop, and calls the
     // provider on a change of the displayed range (moveend). It never touches the
@@ -133,12 +104,12 @@ export function createMapLibreGLDraw(map, options = {}) {
         // Rendering that draws complete frames (printing, thumbnails) turns off time
         // slicing and triangulates on the spot: setting the threshold to infinity
         // puts every polygon on the synchronous path
-        triangulationScheduler: renderingConfig.timeSlicing === false
-            ? new TriangulationScheduler({ vertexThreshold: Number.POSITIVE_INFINITY })
-            : new TriangulationScheduler(),
-        timeSlicing: renderingConfig.timeSlicing,
-        // Announce the datasets that come and go and their reordering (draw.dataset.add,
-        // draw.dataset.remove and draw.dataset.reorder)
+        triangulationScheduler,
+        // Read when a dataset is added, so a change at runtime applies to the datasets added after
+        get timeSlicing() {
+            return renderingConfig.timeSlicing;
+        },
+        // Announce the datasets that come and go and their reordering
         onDatasetAdd: (datasetId) => eventEmitter.emit('dataset.add', { datasetId }),
         onDatasetRemove: (datasetId) => eventEmitter.emit('dataset.remove', { datasetId }),
         onDatasetsReorder: (order) => eventEmitter.emit('dataset.reorder', { order }),
@@ -158,7 +129,7 @@ export function createMapLibreGLDraw(map, options = {}) {
     // own Store.
     const featureCompanions = createFeatureCompanionRegistry();
     const unproject = (p) => map.unproject([p.x, p.y]);
-    const hitTestTopmost = createTopmostHitTester({
+    const topmostDeps = {
         store,
         hitTestService,
         unproject,
@@ -173,9 +144,13 @@ export function createMapLibreGLDraw(map, options = {}) {
             return { x: projected.x, y: projected.y };
         },
         getZoom: () => map.getZoom(),
-        clickTolerancePx: context.options.clickTolerance,
+        // Read at each hit, so a change of the option applies at once
+        get clickTolerancePx() {
+            return context.options.clickTolerance;
+        },
         companions: featureCompanions,
-    });
+    };
+    const hitTestTopmost = createTopmostHitTester(topmostDeps);
     // 2.7 Snapping to data (datasets).
     // Adds the vertices, edges and intersections of the displayed datasets as
     // snapping candidates. The data itself is only read, and whether it is
@@ -207,16 +182,15 @@ export function createMapLibreGLDraw(map, options = {}) {
         // this instance (the modes hit test against the same scope)
         selectionScope: context.selectionScope,
         // The separators of the stacking order (external entries) and the frames.
-        // Additions and removals of separators are announced by an event
-        // (draw.renderslots.change)
+        // Additions and removals of separators are announced (layerStack.changed)
         isExternalEntry: context.isExternalEntry,
-        onSlotsChange: (slots) => eventEmitter.emit('renderslots.change', { slots }),
-        // The failure to load the image of an Image feature (draw.load.error)
+        onSlotsChange: (slots) => eventEmitter.emit('layerStack.change', { slots }),
+        // The failure to load the image of an Image feature (an error event)
         onImageError: (featureId, error) => eventEmitter.emit('load.error', { source: 'image', featureId, error }),
     });
     // 3.5 Add the snapping indicator as a built-in overlay
     // (it comes in front of the selection UI because order: 'overlay')
-    customLayer.addOverlayRenderer(new SnapIndicatorRenderer({ snapService }));
+    customLayer.addOverlay(new SnapIndicatorRenderer({ snapService, look: context.snapIndicator }));
     // Repaint when the snapping result changes (the Store does not change, so
     // the RenderCoordinator does not run)
     const repaintOnSnapChange = () => map.triggerRepaint();
@@ -227,23 +201,39 @@ export function createMapLibreGLDraw(map, options = {}) {
     const renderCoordinator = createRenderCoordinator({ map, store });
     // 5. Set up the ModeManager
     modeManager.registerMode('select', () => new SelectMode());
-    modeManager.registerMode('draw_point', () => new DrawPointMode());
-    modeManager.registerMode('draw_line', () => new DrawLineMode());
-    modeManager.registerMode('draw_polygon', () => new DrawPolygonMode());
     modeManager.registerMode('draw_image', () => new DrawImageMode());
-    modeManager.registerMode('draw_circle', () => new DrawCircleMode());
-    modeManager.registerMode('draw_freehand', () => new DrawFreehandMode());
-    // 6. Create the PluginManager.
-    // The PluginContext is initialized lazily after the PluginManager is created
-    let pluginContext = null;
-    const pluginManager = createPluginManager(() => {
-        if (!pluginContext) {
-            throw new Error('PluginContext not initialized');
-        }
-        return pluginContext;
-    }, modeManager);
-    // 7. Create the import/export API
-    const importExportAPI = createImportExportAPI(context);
+    // 6.5 Create the host of the extensions of the extension contract, and add the built-in
+    // modes written to that contract through it
+    const extensions = createExtensionHost({
+        map,
+        context,
+        customLayer,
+        modeManager,
+        featureCompanions,
+        hitTestTopmost,
+        hitTestTopmostWith: (tolerancePx) => createTopmostHitTester({
+            ...topmostDeps,
+            toleranceLngLat: (point) => toleranceDegrees(unproject, point, tolerancePx),
+            clickTolerancePx: tolerancePx,
+        }),
+        listTraceRows: (bbox) => snapService.isDatasetsEnabled()
+            ? displaySnap.queryRows(bbox).map(({ datasetId, feature }) => ({
+                datasetId,
+                rowIndex: datasets.get(datasetId)?.findRow(feature.id) ?? -1,
+                feature,
+            }))
+            : [],
+    });
+    extensions.collections.modes.addMany([
+        { name: 'draw_point', factory: drawPointMode },
+        { name: 'draw_line', factory: drawLineMode },
+        { name: 'draw_polygon', factory: drawPolygonMode },
+        { name: 'draw_circle', factory: drawCircleMode },
+        { name: 'draw_freehand', factory: drawFreehandMode },
+    ]);
+    // The position of the click being handled, for what a click causes
+    let clickPosition = null;
+    // 7. The context of the modes of the engine (select and image)
     const modeContext = {
         map,
         store,
@@ -258,69 +248,20 @@ export function createMapLibreGLDraw(map, options = {}) {
         trace,
         autoNameGenerator: context.autoNameGenerator,
         boxSelectionRegistry: context.boxSelectionRegistry,
-        pluginManager,
+        plugins: extensions.interactions,
         generateFeatureId: context.generateFeatureId,
         getCurrentLayerId: context.getWritableLayerId,
-        scaleWithZoom: context.options.scaleWithZoom,
+        // Read when a feature is committed, so a change of the option applies at once
+        get scaleWithZoom() {
+            return context.options.scaleWithZoom;
+        },
         setMode: (mode) => modeManager.setMode(mode),
+        getClickPosition: () => clickPosition,
         // The key that temporarily disables shared vertices is shared with the
         // disableKey of the snapping
         snapOptions: context.snapOptions,
-        // The only opening through which a mode learns about snapping (the
-        // SnapService itself is not passed)
-        getSnapResult: () => snapService?.getResult() ?? null,
-        // The opening that resolves a snap target on data into a feature (read by
-        // the tracing)
-        getDatasetFeature: (datasetId, featureId) => displaySnap.getFeature(datasetId, featureId),
-        // The features of the data put on the edge graph of the tracing (empty
-        // when snapping to data is disabled)
-        getDatasetTraceFeatures: (bbox) => snapService.isDatasetsEnabled() ? displaySnap.queryFeatures(bbox) : [],
     };
     modeManager.setContext(modeContext);
-    // 7. Initialize the PluginContext.
-    // Helper function that looks up which layer an item belongs to
-    const findLayerForItem = (itemId) => {
-        for (const layer of store.getAllLayers()) {
-            if (layer.order.includes(itemId)) {
-                return layer.id;
-            }
-        }
-        return undefined;
-    };
-    // Helper function that looks up which group a feature belongs to
-    const findGroupForFeature = (featureId) => {
-        for (const group of store.getAllGroups()) {
-            if (group.featureIds.includes(featureId)) {
-                return group.id;
-            }
-        }
-        return undefined;
-    };
-    // Initialize the PluginContext.
-    // The implementations of all PluginContext methods are gathered in
-    // createPluginContext.
-    // The draw instance is referenced lazily (through the closure, to cope
-    // with the circular initialization).
-    let drawApi = null;
-    pluginContext = createPluginContext({
-        store,
-        eventEmitter,
-        autoNameGenerator: context.autoNameGenerator,
-        spatialIndex,
-        getActiveLayerId: context.getActiveLayerId,
-        findLayerForItem,
-        findGroupForFeature,
-        getModeManager: () => modeManager,
-        // The anchors and the selection extents of this instance (never another instance's)
-        terrain: customLayer.getTerrainContext(),
-        selectionExtensions: context.selectionScope.extensions,
-        getDraw: () => {
-            if (!drawApi) {
-                throw new Error('MapLibreGLDraw not initialized');
-            }
-            return drawApi;
-        },
-    });
     // 7. Create the InputNormalizer and the InputRouter.
     // The hit testing of the datasets comes in as an
     // interception of the InputRouter.
@@ -343,23 +284,36 @@ export function createMapLibreGLDraw(map, options = {}) {
         modeManager,
         context: modeContext,
         map,
-        pluginManager,
         displayInteractions,
         // Emit a click in select mode as a public event (draw.map.click)
         notifyMapClick: (payload) => eventEmitter.emit('map.click', payload),
+        trackClick: (lngLat) => {
+            clickPosition = lngLat;
+        },
         snapService,
+        extensionInput: extensions.input,
+    });
+    // 8. Set up
+    // The events of the instance follow the Store and the signals of the engine
+    const events = createEventHub();
+    const stopStoreEvents = connectStoreEvents(events, store);
+    const stopEngineEvents = connectEngineEvents(events, eventEmitter, {
+        hitAt: (point) => extensions.hitAt(point),
+    });
+    teardown.add(() => {
+        stopStoreEvents();
+        stopEngineEvents();
+        events.clear();
     });
-    // 7. Set up
-    eventBridge.start();
     renderCoordinator.start();
-    // Keep the render slots on the map. The slots are added as soon as the style
-    // accepts layers, whenever the draw instance is created (before, during or
-    // after the map loads), and they are restored after a style change. The
-    // native layers of the separators are placed between the slots by the host,
-    // which receives 'draw.renderslots.change'
+    // Keep the frames of the stacking order on the map. They are added as soon as the style
+    // accepts layers, whenever the draw instance is created (before, during or after the map
+    // loads), and they are restored after a style change. The native layers of the separators
+    // are placed between the frames by the host, which receives layerStack.changed
     teardown.add(attachSlotLayers(map, () => customLayer.getSlotLayers()));
     inputNormalizer.attach();
     inputRouter.start();
+    extensions.start();
     modeManager.start();
     // Disable the boxZoom of MapLibre (because Shift + drag is used for box
     // selection), and give it back in the state it was found in: the host or another draw
@@ -373,35 +327,49 @@ export function createMapLibreGLDraw(map, options = {}) {
         else
             map.boxZoom.disable();
     });
-    // Set the default mode
-    modeManager.setMode(context.options.defaultMode);
-    // 9. Create the public API
-    drawApi = createDrawAPI(context, { inputNormalizer, inputRouter }, eventBridge, customLayer, importExportAPI, { modeManager, renderCoordinator }, { pluginManager, spatialIndex, datasets, featureCompanions });
-    // The public API releases what it created itself (the input, the modes, the rendering, the
-    // plugins and the layers on the map) first, then the rest goes in the reverse order
-    teardown.add(drawApi.destroy);
-    drawApi.destroy = () => teardown.run();
-    ignoreRegistrationsAfterDestroy(drawApi, () => teardown.done);
-    return drawApi;
-}
-/**
- * Makes the registrations of a destroyed instance do nothing
- *
- * Every other call on a destroyed instance works on its inert Store and reaches neither the
- * map nor a timer, but a registration would install something (a plugin, a mode, a renderer,
- * a provider) that nothing is left to release. They are ignored instead and return a cancel
- * function that does nothing.
- */
-function ignoreRegistrationsAfterDestroy(draw, isDestroyed) {
-    const noop = () => { };
-    const guard = (fn, whenDestroyed) => {
-        return (...args) => (isDestroyed() ? whenDestroyed : fn(...args));
+    // Set the default mode (unless the caller attaches the public object of the modes first)
+    const enterDefaultMode = () => {
+        if (!teardown.done)
+            modeManager.setMode(context.options.defaultMode);
+    };
+    if (!build.deferDefaultMode)
+        enterDefaultMode();
+    // 9. The release of what was set up above: the input, the modes, the rendering and the
+    // layers on the map, then the rest in the reverse order
+    teardown.add(() => {
+        inputRouter.stop();
+        inputNormalizer.detach();
+        modeManager.stop();
+        renderCoordinator.stop();
+        context.autoNameGenerator.dispose();
+        // There can be several frames, so remove all of them
+        for (const layer of customLayer.getSlotLayers()) {
+            if (map.getLayer(layer.id))
+                map.removeLayer(layer.id);
+        }
+        // After the plugins are removed (their onRemove can still read the index)
+        spatialIndex.destroy();
+    });
+    // The extensions go first, while everything they use is there
+    teardown.add(() => extensions.destroy());
+    return {
+        map,
+        context,
+        customLayer,
+        modeManager,
+        datasets,
+        inputRouter,
+        extensions,
+        events,
+        runtime: {
+            setDragThreshold: (px) => inputNormalizer.setDragThreshold(px),
+            setTimeSlicing(enabled) {
+                renderingConfig.timeSlicing = enabled;
+                triangulationScheduler.setSlicing(enabled);
+            },
+        },
+        isDestroyed: () => teardown.done,
+        enterDefaultMode,
+        destroy: () => teardown.run(),
     };
-    draw.addPlugin = guard(draw.addPlugin, noop);
-    draw.registerMode = guard(draw.registerMode, noop);
-    draw.registerFeatureHandler = guard(draw.registerFeatureHandler, noop);
-    draw.addOverlayRenderer = guard(draw.addOverlayRenderer, noop);
-    draw.registerAuxiliaryHandleProvider = guard(draw.registerAuxiliaryHandleProvider, noop);
-    draw.registerFeatureCompanionProvider = guard(draw.registerFeatureCompanionProvider, noop);
-    draw.snapping.register = guard(draw.snapping.register, noop);
 }