@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/api/state.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The state of this client: the mode, the selection, the vertex selection, the snapping
+ * result, the stacking order and the terrain diagnostics
+ */
+import type { Position } from 'geojson';
+/** The names of the built-in modes. */
+export declare const MODES: readonly ["select", "draw_point", "draw_line", "draw_polygon", "draw_image", "draw_circle", "draw_freehand"];
+/**
+ * The name of a mode: how the input is received. One of {@link MODES}, or the name of a mode
+ * added with `draw.extensions.modes.add`.
+ */
+export type Mode = (typeof MODES)[number] | (string & {});
+/** What the selection holds: features, groups or layers. */
+export type SelectionType = 'feature' | 'group' | 'layer';
+/** What this client has selected: the type and the IDs. The selection holds one type at a time. */
+export interface Selection {
+    /** The type of the selected items, or `null` when nothing is selected */
+    type: SelectionType | null;
+    /** The IDs of the selected items */
+    ids: readonly string[];
+}
+/**
+ * A vertex of a feature, as the part, the ring and the index within the ring.
+ */
+export interface VertexRef {
+    /** The part of a Multi geometry; 0 when it is left out */
+    part?: number;
+    /** The ring of a polygon, 0 for the outer ring; 0 for lines and points */
+    ring: number;
+    /** The index of the vertex within the ring */
+    index: number;
+}
+/** The selected vertices of one feature. */
+export interface VertexSelection {
+    /** The ID of the feature */
+    featureId: string;
+    /** The selected vertices */
+    vertices: readonly VertexRef[];
+}
+/**
+ * Where the pointer snapped to. When nothing was snapped to, `lngLat` is the position of the
+ * pointer and `target` is absent.
+ */
+export interface SnapResult {
+    /** The position after snapping */
+    lngLat: Position;
+    /** What was snapped to */
+    target?: {
+        /**
+         * The kind of the target; a kind of its own that a snap provider gave its candidate is
+         * kept as it is
+         */
+        kind: 'vertex' | 'edge' | 'intersection' | 'guide' | (string & {});
+        /** The ID of the feature, for a target of the document */
+        featureId?: string;
+        /** The ID of the dataset, for a target of a dataset */
+        datasetId?: string;
+        /** A description to show */
+        description?: string;
+        /** The vertex, for a vertex target */
+        vertex?: VertexRef;
+        /** The segment, for an edge or a guide */
+        segment?: {
+            start: Position;
+            end: Position;
+        };
+    };
+}
+/**
+ * How a mode wants the positions of its input snapped, as `ModeHandler.snapPreference` declares
+ * it. It is read before every input is snapped, so a mode whose preference changes
+ * while it draws declares it as a getter.
+ */
+export interface SnapPreference {
+    /**
+     * The feature to prefer when snapping candidates are at the same distance, such as the
+     * boundary a trace started along; none when it is left out or `null`
+     */
+    prefer?: {
+        featureId: string;
+        datasetId?: string;
+    } | null;
+    /**
+     * The inputs whose position is not snapped, by the name of their receiver; every input is
+     * snapped when it is left out. A stroke drawn by dragging leaves out `onDrag`, so that its
+     * inner points follow the pointer while its ends still snap.
+     */
+    unsnapped?: readonly ('onClick' | 'onPointerMove' | 'onDragStart' | 'onDrag' | 'onDragEnd')[];
+}
+/**
+ * One division of the stacking order: the map layer that draws one run of the layer order
+ * between two entries that come from outside the document.
+ */
+export interface LayerStackEntry {
+    /** The ID of the map layer that draws the run */
+    readonly layerId: string;
+    /** The index in the layer order where the run starts (inclusive) */
+    readonly from: number;
+    /** The index in the layer order where the run ends (exclusive) */
+    readonly to: number;
+}
+/**
+ * The state the terrain was drawn with, for diagnostics. Its fields follow the drawing and
+ * carry a weaker promise than the rest of the API.
+ */
+export interface TerrainDiagnostics {
+    /** The terrain state of the last drawing */
+    readonly render: {
+        /** Whether the terrain was on and its elevation data usable */
+        readonly active: boolean;
+        /** The Mercator rectangle the elevation data covers, `[x0, y0, 1 / width, 1 / height]` */
+        readonly atlasRect: readonly [number, number, number, number];
+        /** The size of the elevation data in texels, `[width, height]` */
+        readonly atlasSize: readonly [number, number];
+        /** The factor from meters to Mercator z at the latitude of the center of the screen */
+        readonly elevationScale: number;
+        /** The lift above the ground in meters */
+        readonly liftMeters: number;
+        /** The subdivision step in meters (0 means no subdivision) */
+        readonly stepMeters: number;
+        /** The grid spacing of the subdivision, in Mercator units */
+        readonly stepGrid: number;
+        /** The generation of the subdivision; it counts the changes of the step */
+        readonly generation: number;
+    };
+    /** How the areas were laid on the terrain in the last drawing */
+    readonly drape: {
+        /** Whether the analytic drape was used */
+        readonly used: boolean;
+        /** Why it was not used */
+        readonly reason: string;
+        /** The number of features laid on the drape */
+        readonly featureCount: number;
+        /** The number of edges */
+        readonly edgeCount: number;
+        /** The number of tiles drawn */
+        readonly tileCount: number;
+        /** The largest number of runs in one cell */
+        readonly maxRunsPerCell: number;
+        /** The largest number of edges in one cell */
+        readonly maxEdgesPerCell: number;
+        /** The largest number of edges in one tile of the view */
+        readonly maxTileEdges: number;
+        /** The number of cells cut short for going over the budget */
+        readonly truncatedCells: number;
+        /** The number of tiles that could not be evaluated and were not drawn */
+        readonly unfitTiles: number;
+        /** The number of runs whose cell origin was inside the feature */
+        readonly insideRuns: number;
+        /** The number of features left off the drape */
+        readonly excluded: number;
+        /** The number of features drawn without the drape */
+        readonly immediate: number;
+    };
+}

package/dist/api/state.js

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** The names of the built-in modes. */
+export const MODES = [
+    'select',
+    'draw_point',
+    'draw_line',
+    'draw_polygon',
+    'draw_image',
+    'draw_circle',
+    'draw_freehand',
+];

package/dist/{display → dataset}/chunk.d.ts

@@ -1 +1 @@
-export { CHUNK_TARGET_SIZE, CHUNK_TARGET_VERTICES, chunkTargetSizeFor, LARGE_CHUNK_TARGET_SIZE, LARGE_DATASET_THRESHOLD, } from './partition.js';
+export { CHUNK_TARGET_SIZE, CHUNK_TARGET_VERTICES, chunkTargetSizeFor, LARGE_CHUNK_TARGET_SIZE, LARGE_DATASET_THRESHOLD, } from '../table/partition.js';

package/dist/{display → dataset}/chunk.js

@@ -1,8 +1,9 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+import { coordinatesOf } from '../shared/utils/coordinates.js';
 import { getBoundingBox } from '../shared/utils/feature-bbox.js';
-import { CHUNK_TARGET_SIZE, partitionRows } from './partition.js';
-export { CHUNK_TARGET_SIZE, CHUNK_TARGET_VERTICES, chunkTargetSizeFor, LARGE_CHUNK_TARGET_SIZE, LARGE_DATASET_THRESHOLD, } from './partition.js';
+import { CHUNK_TARGET_SIZE, partitionRows } from '../table/partition.js';
+export { CHUNK_TARGET_SIZE, CHUNK_TARGET_VERTICES, chunkTargetSizeFor, LARGE_CHUNK_TARGET_SIZE, LARGE_DATASET_THRESHOLD, } from '../table/partition.js';
 /**
  * Whether two bboxes intersect
  *
@@ -17,7 +18,7 @@ export function boundsIntersect(a, b) {
  * @internal
  */
 export function countVertices(feature) {
-    const geometry = feature;
+    const geometry = { type: feature.type, coordinates: coordinatesOf(feature) };
     const walk = (value, depth) => {
         if (!Array.isArray(value))
             return 0;

package/dist/{display → dataset}/dataset.js

@@ -4,11 +4,11 @@ import { DEFAULT_FEATURE_STYLE_CONFIG } from '../shared/config/feature-style.js'
 import { sanitizeDrawFactors } from '../view/renderers/draw-factors.js';
 import { TerrainContext } from '../view/terrain/context.js';
 import { DisplayChunkSet } from './chunk-set.js';
-import { ColumnarSource } from './columnar/source.js';
 import { DisplayProviderLoader } from './provider.js';
 import { drawSelectionHighlight, hitTestDisplayFeatures, sameFeatureIds, } from './selection.js';
 import { FeatureArraySource } from './source.js';
 import { DisplayFeatureStyler } from './style.js';
+import { TableSource } from './table-source.js';
 import { CollisionThinningState, pointMarkerRadiusPx } from './thinning.js';
 import { normalizeDisplayFeature } from './types.js';
 // The importers of these moved names keep their path (the definitions live in the parts)
@@ -218,12 +218,9 @@ export class DatasetImpl {
             writable: true,
             value: (feature) => feature.type === 'Point' && this.externalPointRender?.(feature) === true
         });
-        const given = [options.features, options.columnar, options.provider].filter((input) => input !== undefined);
+        const given = [options.rows, options.table, options.provider].filter((input) => input !== undefined);
         if (given.length > 1) {
-            throw new Error(`Dataset "${options.id}": only one of features, columnar and provider can be given`);
-        }
-        if (options.prepared && !options.columnar) {
-            throw new Error(`Dataset "${options.id}": prepared is given without columnar`);
+            throw new Error(`Dataset "${options.id}": only one of rows, table and provider can be given`);
         }
         this.id = options.id;
         this.currentOrder = options.order ?? 'below-store';
@@ -267,11 +264,11 @@ export class DatasetImpl {
                 },
             })
             : null;
-        if (options.features) {
-            this.setFeatures(options.features);
+        if (options.rows) {
+            this.setRows(options.rows);
         }
-        else if (options.columnar) {
-            this.setColumnar(options.columnar, options.prepared);
+        else if (options.table) {
+            this.setTable(options.table);
         }
     }
     /** Draw order (the current side) */
@@ -307,12 +304,12 @@ export class DatasetImpl {
         this.emit('change', { reason: 'visibility' });
         this.deps.requestRepaint();
     }
-    setFeatures(features) {
-        this.applySource(new FeatureArraySource(features.map(normalizeDisplayFeature)));
+    setRows(rows) {
+        this.applySource(new FeatureArraySource(rows.map(normalizeDisplayFeature)));
         this.deps.requestRepaint();
     }
-    setColumnar(input, prepared) {
-        this.applySource(new ColumnarSource(input, prepared));
+    setTable(table) {
+        this.applySource(new TableSource(table));
         this.deps.requestRepaint();
     }
     setStyleRule(rule) {
@@ -350,6 +347,9 @@ export class DatasetImpl {
     getBaseStyle() {
         return this.styler.base;
     }
+    getStyleRule() {
+        return this.styler.rule;
+    }
     getFeatures() {
         return this.source.features();
     }
@@ -472,7 +472,7 @@ export class DatasetImpl {
         const source = this.source;
         // A table of points has nothing for it (and its rows are not built into features for
         // nothing)
-        if (source instanceof ColumnarSource && source.table.onlyPoints)
+        if (source instanceof TableSource && source.table.onlyPoints)
             return [];
         const features = [];
         for (let row = 0; row < source.length; row++) {
@@ -515,10 +515,10 @@ export class DatasetImpl {
         // hidden rows)
         return source.index.searchWhere(bounds, (row) => thinning.isDrawnRow(row) && source.thinningRole(row) !== 'skip');
     }
-    getRowFeature(row) {
-        if (!this.hasRow(row))
-            return null;
-        return this.styler.prepareIfStyled(this.source.featureAt(row));
+    getRow(index) {
+        if (!this.hasRow(index))
+            return undefined;
+        return this.styler.prepareIfStyled(this.source.featureAt(index));
     }
     getRowId(row) {
         return this.hasRow(row) ? this.source.idOf(row) : null;
@@ -731,8 +731,8 @@ export class DatasetImpl {
     /**
      * Applies new contents (the chunks, the index and the caches come with them)
      *
-     * The only triggers for rebuilding the retained batches are this path (setFeatures,
-     * setColumnar and applying a provider result) and setStyleRule / setBaseStyle.
+     * The only triggers for rebuilding the retained batches are this path (setRows,
+     * setTable and applying a provider result) and setStyleRule / setBaseStyle.
      */
     applySource(source) {
         this.source = source;

package/dist/dataset/interaction.d.ts

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

package/dist/{display → dataset}/interaction.js

@@ -13,7 +13,10 @@ export function createDisplayInteractions(deps) {
     function toCoordinate(event) {
         return [event.lngLat.lng, event.lngLat.lat];
     }
-    function clearHover(lngLat) {
+    function toPoint(event) {
+        return { x: event.point.x, y: event.point.y };
+    }
+    function clearHover(lngLat, point) {
         if (hoveredDatasetId === null)
             return;
         const previous = manager.getInternal(hoveredDatasetId);
@@ -21,7 +24,7 @@ export function createDisplayInteractions(deps) {
         hoveredDatasetId = null;
         hoveredFeatureId = null;
         // Report with feature: null that it left the target
-        previous?.emit('hover', { datasetId, feature: null, row: null, lngLat });
+        previous?.emit('hover', { datasetId, feature: null, row: null, lngLat, point });
     }
     return {
         handleClick(event) {
@@ -44,35 +47,43 @@ export function createDisplayInteractions(deps) {
                     feature: top.feature,
                     row,
                     lngLat: coordinate,
+                    point: toPoint(event),
                 });
                 notifyClick?.({
                     datasetId: top.dataset.id,
                     feature: top.feature,
                     row,
                     lngLat: coordinate,
+                    point: toPoint(event),
                 });
                 return;
             }
             // Nothing was there, or a non-interactive dataset merely blocked it: it is reported as
             // a no-hit (the source of "click on empty space to deselect" on the host side)
-            notifyClick?.({ datasetId: null, feature: null, row: null, lngLat: coordinate });
+            notifyClick?.({
+                datasetId: null,
+                feature: null,
+                row: null,
+                lngLat: coordinate,
+                point: toPoint(event),
+            });
         },
         handleMouseMove(event) {
             const coordinate = toCoordinate(event);
             if (!manager.hasAny()) {
-                clearHover(coordinate);
+                clearHover(coordinate, toPoint(event));
                 return;
             }
             const top = hitTestTopmost(event);
             if (top?.kind !== 'dataset' || !top.feature) {
-                clearHover(coordinate);
+                clearHover(coordinate, toPoint(event));
                 return;
             }
             if (top.dataset.id === hoveredDatasetId && top.feature.id === hoveredFeatureId) {
                 // Nothing fires while the pointer only moves over the same feature
                 return;
             }
-            clearHover(coordinate);
+            clearHover(coordinate, toPoint(event));
             hoveredDatasetId = top.dataset.id;
             hoveredFeatureId = top.feature.id;
             manager.getInternal(top.dataset.id)?.emit('hover', {
@@ -80,6 +91,7 @@ export function createDisplayInteractions(deps) {
                 feature: top.feature,
                 row: top.row ?? null,
                 lngLat: coordinate,
+                point: toPoint(event),
             });
         },
         reset() {

package/dist/dataset/manager.d.ts

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

package/dist/dataset/provider.d.ts

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

package/dist/{display → dataset}/retained.d.ts

@@ -4,7 +4,7 @@ import type { RetainedRendererSet } from '../view/renderers/retained.js';
  *
  * What cannot be finished in one frame is advanced by the budget of the frame and handed on. The
  * caller keeps drawing the batches of the previous version until it is finished
- * (`display/chunk-set.ts`). It is built the same way as the one-shot build
+ * (`dataset/chunk-set.ts`). It is built the same way as the one-shot build
  * (`buildChunkBatches`); only the unit of bundling differs.
  */
 export interface ChunkBuildJob {

package/dist/{display → dataset}/retained.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
 import { generateCirclePolygon } from '../shared/math/index.js';
+import { coordinatesOf } from '../shared/utils/coordinates.js';
 import { getCircleRadius, getCreatedZoom } from '../shared/utils/property.js';
 import { toLineBatchItem, toPointInstanceData } from '../view/renderers/batch-manager.js';
 import { NEUTRAL_DRAW_FACTORS } from '../view/renderers/draw-factors.js';
@@ -741,29 +742,29 @@ export function collectFeature(feature, draft, styles, isExternallyRenderedPoint
     const skipSolid = skipDrapedFills && isDrapedGeometry(feature);
     switch (feature.type) {
         case 'Point':
-            collectPoint(feature, feature.coordinates, draft, styles, isExternallyRenderedPoint);
+            collectPoint(feature, coordinatesOf(feature), draft, styles, isExternallyRenderedPoint);
             return;
         case 'MultiPoint':
             // Whether the predicate applies to Point alone is up to the predicate itself (the test is
             // in one place)
-            for (const coord of feature.coordinates) {
+            for (const coord of coordinatesOf(feature)) {
                 collectPoint(feature, coord, draft, styles, isExternallyRenderedPoint);
             }
             return;
         case 'LineString':
         case 'Freehand':
-            collectLine(feature, feature.coordinates, draft, styles, skipSolid);
+            collectLine(feature, coordinatesOf(feature), draft, styles, skipSolid);
             return;
         case 'MultiLineString':
-            for (const coords of feature.coordinates) {
+            for (const coords of coordinatesOf(feature)) {
                 collectLine(feature, coords, draft, styles, skipSolid);
             }
             return;
         case 'Polygon':
-            collectPolygon(feature, feature.coordinates, draft, styles, 0, skipSolid);
+            collectPolygon(feature, coordinatesOf(feature), draft, styles, 0, skipSolid);
             return;
         case 'MultiPolygon': {
-            const parts = feature.coordinates;
+            const parts = coordinatesOf(feature);
             for (let i = 0; i < parts.length; i++) {
                 collectPolygon(feature, parts[i], draft, styles, i, skipSolid);
             }
@@ -773,7 +774,7 @@ export function collectFeature(feature, draft, styles, isExternallyRenderedPoint
             const radiusMeters = getCircleRadius(feature);
             if (!radiusMeters || radiusMeters <= 0)
                 return;
-            const center = feature.coordinates;
+            const center = coordinatesOf(feature);
             collectPolygon(feature, [generateCirclePolygon(center, radiusMeters)], draft, styles);
             return;
         }

package/dist/dataset/source.d.ts

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

package/dist/{display → dataset}/source.js

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+import { coordinatesOf } from '../shared/utils/coordinates.js';
+import { chunkTargetSizeFor } from '../table/partition.js';
 import { computeFeatureBounds, partitionIntoChunks } from './chunk.js';
-import { chunkTargetSizeFor } from './partition.js';
 import { collectFeatures } from './retained.js';
 import { maxStylePointRadiusOf } from './selection.js';
 import { DisplaySpatialIndex } from './spatial.js';
@@ -59,6 +60,13 @@ export class FeatureArraySource {
             writable: true,
             value: null
         });
+        /** The features of the rows with a geometry, found on the first request */
+        Object.defineProperty(this, "withGeometry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         this.length = list.length;
         // The bboxes are shared by the spatial index and the chunk splitting (not computed twice)
         this.bounds = computeFeatureBounds(list);
@@ -83,7 +91,7 @@ export class FeatureArraySource {
         if (ids.size === 0)
             return rows;
         for (let row = 0; row < this.list.length; row++) {
-            if (ids.has(this.list[row].id))
+            if (ids.has(this.list[row].id) && this.hasGeometry(row))
                 rows.push(row);
         }
         return rows;
@@ -98,13 +106,18 @@ export class FeatureArraySource {
         return this.rowById.get(id) ?? -1;
     }
     features() {
-        return this.list;
+        if (!this.withGeometry) {
+            // The rows without a geometry (NaN coordinates) are left out, as a table leaves them out
+            const all = this.list.every((_, row) => this.hasGeometry(row));
+            this.withGeometry = all ? this.list : this.list.filter((_, row) => this.hasGeometry(row));
+        }
+        return this.withGeometry;
     }
     thinningRole(row) {
         return featureThinningRole(this.list[row]);
     }
     pointOf(row) {
-        return this.list[row].coordinates;
+        return coordinatesOf(this.list[row]);
     }
     styleRadiusOf(row) {
         return this.list[row].style?.pointRadius;

package/dist/dataset/spatial.d.ts

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

package/dist/{display → dataset}/spatial.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
-import { buildPackedRTree, searchPackedRTree } from './packed-rtree.js';
+import { buildPackedRTree, searchPackedRTree } from '../table/packed-rtree.js';
 /**
  * Spatial index of a dataset
  *

package/dist/dataset/style.d.ts

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

package/dist/{display → dataset}/style.js

@@ -89,7 +89,7 @@ export class DisplayFeatureStyler {
         const channel = getStyleRuleChannel(feature.type);
         const ruleColor = this.styleCache.resolve(feature, this.styleRule);
         const style = this.effectiveStyle(feature.style, ruleColor, channel);
-        const prepared = style === feature.style ? feature : { ...feature, style };
+        const prepared = style === feature.style ? feature : { ...feature, style: style ?? {} };
         this.preparedCache.set(feature.id, prepared);
         return prepared;
     }

package/dist/dataset/table-source.d.ts

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