@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/{display/columnar/source.js → dataset/table-source.js}

@@ -1,16 +1,38 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
-import { toPackedPointStyle } from '../../view/renderers/batch-manager.js';
-import { toLineInstanceColor } from '../../view/renderers/line/line-geometry.js';
-import { toInstancedPointShape, } from '../../view/renderers/point/point-instance.js';
-import { evaluateStyleRuleValue, getStyleRuleChannel } from '../../view/style-rule.js';
-import { toDisplayChunks } from '../chunk.js';
-import { COLLECT_SLICE_ROWS, FIXED_WIDTH_ZOOM, isDrapedGeometry, PackedLinesBuilder, PackedPointsBuilder, pushFallback, } from '../retained.js';
-import { DisplaySpatialIndex } from '../spatial.js';
-import { prepareDatasetColumnar } from './prepare.js';
-import { ColumnarTable, columnValue, isDictionaryColumn, } from './table.js';
+/**
+ * The contents given as a table (`TableSource`)
+ *
+ * It implements the contract of `source.ts` over the typed arrays of the table. What a draw and a
+ * hit test need is read from the arrays as they are: the chunks and the spatial index come from
+ * `prepareTable` (computed in a Worker, or here when it was not given), and the rows of
+ * a chunk are packed straight into the GPU arrays. A feature is built only for a row that is
+ * asked for (a hit, the selection, `getFeatures`, the analytic drape, a row drawn in immediate
+ * mode).
+ *
+ * The styles are resolved once per geometry type and rule color, not per row: the rows have no
+ * individual style, so two rows of the same type with the same rule color look the same. The
+ * resolution goes through the same styler and the same resolver as the features, so a row looks
+ * exactly as its feature would.
+ *
+ * A row is read from the geometry column that holds it: the one column of a table of one type, or
+ * the child of a mixed geometry column that the row names, at the row within that child. Each row
+ * is collected as its type is (the decisions of `collectFeature`), so the rows of a mixed table
+ * are drawn in the order of the table whatever the order within the children.
+ */
+import { drawPropertyKey } from '../shared/properties.js';
+import { geometryFromCoordinates } from '../shared/utils/coordinates.js';
+import { isPreparedTable, prepareTable } from '../table/prepare.js';
+import { columnValue, isDictionaryColumn, TableReader, } from '../table/table.js';
+import { toPackedPointStyle } from '../view/renderers/batch-manager.js';
+import { toLineInstanceColor } from '../view/renderers/line/line-geometry.js';
+import { toInstancedPointShape } from '../view/renderers/point/point-instance.js';
+import { evaluateStyleRuleValue, getStyleRuleChannel } from '../view/style-rule.js';
+import { toDisplayChunks } from './chunk.js';
+import { COLLECT_SLICE_ROWS, FIXED_WIDTH_ZOOM, isDrapedGeometry, PackedLinesBuilder, PackedPointsBuilder, pushFallback, } from './retained.js';
+import { DisplaySpatialIndex } from './spatial.js';
 /** The column the zoom of creation of a row is read from (the same key as on a feature) */
-const CREATED_ZOOM_COLUMN = 'createdZoom';
+const CREATED_ZOOM_COLUMN = drawPropertyKey('createdZoom');
 /** The key of the slots for "no rule color" */
 const NO_RULE_COLOR = '';
 /** The slots of a geometry type (created on the first request) */
@@ -25,7 +47,7 @@ function slotsOfType(maps, type) {
 /**
  * The styles of the rows of a table, resolved once per geometry type and rule color
  */
-class ColumnarStyleSlots {
+class TableStyleSlots {
     constructor(table, styler, resolver) {
         Object.defineProperty(this, "table", {
             enumerable: true,
@@ -150,27 +172,28 @@ class ColumnarStyleSlots {
         return {
             id: '',
             type,
-            coordinates: [],
+            geometry: geometryFromCoordinates(type, []),
             layerId: '',
+            groupId: undefined,
             properties: {},
-            style: this.styler.effectiveStyle(undefined, color, getStyleRuleChannel(type)),
+            style: this.styler.effectiveStyle(undefined, color, getStyleRuleChannel(type)) ?? {},
             locked: false,
             visible: true,
         };
     }
 }
 /**
- * The contents of a dataset given as a columnar table
+ * The contents of a dataset given as a table
  *
  * @internal
  */
-export class ColumnarSource {
+export class TableSource {
     /**
-     * @param prepared The result of `prepareDatasetColumnar` for this table (computed here when
-     *   omitted)
-     * @throws when the table does not add up, or when `prepared` was made for another length
+     * @param given The table, or the result of `prepareTable` (the preparation is computed here
+     *   for a bare table)
+     * @throws when the table does not add up, or when a prepared table does not match its table
      */
-    constructor(input, prepared) {
+    constructor(given) {
         Object.defineProperty(this, "table", {
             enumerable: true,
             configurable: true,
@@ -235,13 +258,18 @@ export class ColumnarSource {
             writable: true,
             value: null
         });
-        this.table = new ColumnarTable(input);
+        const prepared = isPreparedTable(given) ? given : null;
+        const input = prepared ? prepared.table : given;
+        this.table = new TableReader(input);
         this.length = this.table.length;
-        const ready = prepared ?? prepareDatasetColumnar(input);
-        if (ready.length !== this.length || ready.bounds.length !== this.length * 4) {
-            throw new Error(`Columnar input: prepared was made for ${ready.length} rows, the table has ${this.length}`);
+        const ready = prepared ?? prepareTable(input);
+        if (!(ready.rowBounds instanceof Float64Array) || !(ready.indexBoxes instanceof Float64Array)) {
+            throw new Error('Table: a prepared table must be made by prepareTable');
+        }
+        if (ready.length !== this.length || ready.rowBounds.length !== this.length * 4) {
+            throw new Error(`Table: the prepared table was made for ${ready.length} rows, the table has ${this.length}`);
         }
-        this.bounds = ready.bounds;
+        this.bounds = ready.rowBounds;
         this.chunks = toDisplayChunks({
             rows: ready.chunkRows,
             offsets: ready.chunkOffsets,
@@ -405,7 +433,7 @@ export class ColumnarSource {
             key[0] !== context.styleKey ||
             key[1] !== context.styler ||
             key[2] !== resolver) {
-            this.slots = new ColumnarStyleSlots(this.table, context.styler, resolver);
+            this.slots = new TableStyleSlots(this.table, context.styler, resolver);
             this.slotsKey = [context.styleKey, context.styler, resolver];
         }
         return this.slots;

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

@@ -7,16 +7,6 @@
  * polygons and MultiPoint are always drawn. The overlap is tested with the size actually drawn
  * (the radius + the outline + `marginPx`), and the winners are picked greedily from the front
  * of the draw order for each integer zoom band, so panning does not swap them.
- *
- * @example
- * ```ts
- * const places = draw.addDataset({
- *   id: 'places',
- *   features,
- *   collisionThinning: { enabled: true, fullDisplayZoom: 17, marginPx: 2 },
- * });
- * const { total, visible } = places.getThinningStats(); // "showing 1,200 of 50,000"
- * ```
  */
 export interface DatasetCollisionThinning {
     /** Whether the thinning is enabled (false by default = everything is drawn as before) */

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

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+import { coordinatesOf } from '../shared/utils/coordinates.js';
 /**
  * The zoom at which the thinning stops (default). At or above it every feature is drawn
  *
@@ -476,7 +477,7 @@ export function selectCollisionWinners(input) {
     const rows = {
         length: features.length,
         thinningRole: (row) => featureThinningRole(features[row]),
-        pointOf: (row) => features[row].coordinates,
+        pointOf: (row) => coordinatesOf(features[row]),
         styleRadiusOf: (row) => features[row].style?.pointRadius,
         idOf: (row) => features[row].id,
     };
@@ -498,7 +499,7 @@ export function featureThinningRole(feature) {
         return 'skip';
     if (feature.type !== 'Point')
         return 'winner';
-    const coord = feature.coordinates;
+    const coord = coordinatesOf(feature);
     if (!Array.isArray(coord) || typeof coord[0] !== 'number' || typeof coord[1] !== 'number') {
         return 'winner';
     }

package/dist/dataset/triangulation.d.ts

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

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

@@ -1,6 +1,14 @@
+/**
+ * Type definitions of the datasets
+ *
+ * It defines the types for showing large numbers of features that are not being edited, quickly
+ * and with attribute-driven styles. It is a path independent of the Store (editing, undo,
+ * events), and there is no editing API here.
+ */
+import type { Feature as GeoJSONFeature, Geometry as GeoJSONGeometry } from 'geojson';
 import type { BoundingBox, Coordinate, Feature, StyleRule } from '../shared/types/model.js';
+import type { PreparedTable, Table } from '../table/types.js';
 import type { StyleRuleChannel } from '../view/style-rule.js';
-import type { DatasetColumnarInput, DatasetColumnarPrepared } from './columnar/types.js';
 import type { DatasetCollisionThinning, DatasetThinningStats, ResolvedCollisionThinning } from './thinning.js';
 /**
  * The default style of a dataset, per geometry channel.
@@ -14,34 +22,22 @@ import type { DatasetCollisionThinning, DatasetThinningStats, ResolvedCollisionT
  */
 export type DatasetBaseStyle = Partial<Record<StyleRuleChannel, Feature['style']>>;
 /**
- * A feature passed to a dataset.
+ * A row passed to a dataset: a GeoJSON feature.
  *
- * It accepts the same coordinate shapes as a feature of the Store (including Multi and holes).
- * It is not put into the Store, so the layer it belongs to, the lock and the visibility can be
- * omitted (when omitted they are treated as an empty string, false and true respectively).
- * `Feature` satisfies this type, so a feature taken out of the Store can be passed as it is.
- * Positions with a third element (an elevation from GeoJSON) are truncated to `[lng, lat]`.
+ * The geometry is a GeoJSON geometry of any type but `GeometryCollection`. A null geometry (or a
+ * `GeometryCollection`) gives a row without a geometry: it keeps its place and its id but is
+ * neither drawn nor hit. Positions with a third element (an elevation) are truncated to
+ * `[lng, lat]`. The id is turned into a string with `String()` (the row number as a string when
+ * omitted) and should be unique within the dataset. The properties are what the style rule
+ * reads.
+ *
+ * Besides the members of GeoJSON, a row may carry `style`, its individual style, which wins
+ * over the rule color and the base style.
  */
-export interface DatasetFeatureInput {
-    /** The feature id, unique within the dataset */
-    id: string;
-    /** The geometry type, the same values as a feature of the Store */
-    type: Feature['type'];
-    /** The coordinates in `[lng, lat]` degrees, shaped as for `type` (holes and Multi included) */
-    coordinates: Feature['coordinates'];
-    /** The attributes the style rule reads (`{}` when omitted) */
-    properties?: Record<string, unknown>;
-    /** The individual style; it wins over the rule color and the base style */
+export type DatasetRow = GeoJSONFeature<GeoJSONGeometry | null> & {
+    /** The individual style of the row; it wins over the rule color and the base style */
     style?: Feature['style'];
-    /** The layer id (`''` when omitted). Kept on the feature; the dataset does not use it */
-    layerId?: string;
-    /** The group id. Kept on the feature; the dataset does not use it */
-    groupId?: string;
-    /** The lock flag (`false` when omitted). Kept on the feature; nothing is edited here */
-    locked?: boolean;
-    /** `false` hides this feature (`true` when omitted) */
-    visible?: boolean;
-}
+};
 /**
  * Where a dataset is drawn relative to the layers of the Store.
  *
@@ -56,7 +52,7 @@ export interface DatasetFeatureInput {
  */
 export type DatasetOrder = 'below-store' | 'above-store' | 'layer-order';
 /**
- * The destination of {@link MapLibreGLDraw.moveDataset}: a side and a position
+ * The destination of a move of a dataset (`draw.datasets.move`): a side and a position
  * within it.
  *
  * order is the side (in front of or behind the Store) and index is the position within that
@@ -77,26 +73,16 @@ export interface DatasetPlacement {
     index?: number;
 }
 /**
- * Fetches the features of a dataset for the displayed range.
+ * Fetches the rows of a dataset for the displayed range.
  *
  * It is called, debounced by 200 ms, when the displayed range changes. `bbox` is the range in
  * degrees rounded out to the boundaries of the tiles at the integer zoom, and `zoom` is the
  * zoom at the time of the call. A result is cached per rounded range, so a small pan or zoom
  * causes no call; {@link Dataset.invalidateProviderCache} discards the cache. Only
  * the result of the last request is applied, and a rejected promise is logged with
- * `console.error` and leaves the features shown as they are.
- *
- * @example
- * ```ts
- * const provider: DatasetFeatureProvider = async (bbox, zoom) => {
- *   const url = `/api/parcels?bbox=${bbox.minX},${bbox.minY},${bbox.maxX},${bbox.maxY}&z=${zoom}`;
- *   const response = await fetch(url);
- *   return response.json(); // DatasetFeatureInput[]
- * };
- * draw.addDataset({ id: 'parcels', provider });
- * ```
+ * `console.error` and leaves the rows shown as they are.
  */
-export type DatasetFeatureProvider = (bbox: BoundingBox, zoom: number) => Promise<DatasetFeatureInput[]>;
+export type DatasetFeatureProvider = (bbox: BoundingBox, zoom: number) => Promise<DatasetRow[]>;
 /**
  * Returns the size and opacity factors of a dataset for a zoom.
  *
@@ -121,39 +107,35 @@ export type DatasetZoomScale = (zoom: number) => {
     opacity: number;
 };
 /**
- * The options of {@link MapLibreGLDraw.addDataset}.
+ * The options of a dataset the engine adds (`draw.datasets.add` checks and translates them).
  *
- * Only `id` is required. Give at most one of `features` (static), `columnar` (static, as
- * columns of typed arrays) and `provider` (fetched for the displayed range).
+ * Only `id` is required. Give at most one of `rows` (static GeoJSON features), `table`
+ * (static, as columns of typed arrays) and `provider` (fetched for the displayed range).
  */
 export interface DatasetOptions {
     /**
      * The dataset id. It must be unique among the datasets of the draw
-     * instance; a duplicate makes `addDataset` throw. With `order: 'layer-order'` it is
+     * instance; a duplicate makes the addition throw. With `order: 'layer-order'` it is
      * also the id placed in the layer order of the Store
      */
     id: string;
     /**
-     * The static features, drawn in array order (the last in front). Cannot be given together
-     * with `columnar` or `provider` (it throws). Replace them later with
-     * {@link Dataset.setFeatures}
+     * The static rows as GeoJSON features, drawn in array order (the last in front). Cannot be
+     * given together with `table` or `provider` (it throws). Replace them later with
+     * {@link Dataset.setRows}
      */
-    features?: DatasetFeatureInput[];
+    rows?: readonly DatasetRow[];
     /**
-     * The static rows as columns of typed arrays, drawn in row order (the last in front); the
-     * fast way in for a large table, read in a Worker if need be. Cannot be given together with
-     * `features` or `provider` (it throws). Replace them later with
-     * {@link Dataset.setColumnar}
+     * The static rows as a table (from `@sakuzu/maplibre-gl-draw/table`), drawn in row order (the
+     * last in front); the fast way in for a large table, read in a Worker if need be. A table
+     * prepared with `prepareTable` is taken as it is, and the dataset computes none of the
+     * preparation on the main thread. Cannot be given together with `rows` or `provider` (it
+     * throws). Replace it later with {@link Dataset.setTable}
      */
-    columnar?: DatasetColumnarInput;
+    table?: Table | PreparedTable;
     /**
-     * What `prepareDatasetColumnar` computed for `columnar` (in a Worker, say). The dataset then
-     * computes none of it on the main thread. Only with `columnar` (it throws otherwise)
-     */
-    prepared?: DatasetColumnarPrepared;
-    /**
-     * Fetches the features for the displayed range. Cannot be given together with `features` or
-     * `columnar` (it throws)
+     * Fetches the rows for the displayed range. Cannot be given together with `rows` or `table`
+     * (it throws)
      */
     provider?: DatasetFeatureProvider;
     /**
@@ -205,13 +187,18 @@ export interface DatasetClickPayload {
     /** The feature that was hit, as normalized by the dataset */
     feature: Feature;
     /**
-     * The row of the feature: its index in the features given to the dataset (or in the result
-     * of the provider), or its row in the columnar table. A host that keeps its own columns reads
+     * The row of the feature: its index in the rows given to the dataset (or in the result of
+     * the provider), or its row in the table. A host that keeps its own columns reads
      * the values of the row from them
      */
     row: number;
     /** The clicked position `[lng, lat]` in degrees */
     lngLat: Coordinate;
+    /** The clicked point on the screen, in CSS pixels */
+    point?: {
+        x: number;
+        y: number;
+    };
 }
 /**
  * The payload of the `hover` event of a {@link Dataset}.
@@ -228,6 +215,11 @@ export interface DatasetHoverPayload {
     row: number | null;
     /** The pointer position `[lng, lat]` in degrees */
     lngLat: Coordinate;
+    /** The pointer position on the screen, in CSS pixels */
+    point?: {
+        x: number;
+        y: number;
+    };
 }
 /**
  * The payload of the `change` event of a {@link Dataset}.
@@ -236,8 +228,8 @@ export interface DatasetHoverPayload {
  * changed. It exists so that a host that builds another representation from the contents of a
  * dataset, such as label rendering, gets a trigger to rebuild it.
  *
- * - features: the features were replaced (setFeatures, setColumnar, or a provider result
- *   applied). The rows are new, and so are the drawn rows
+ * - features: the rows were replaced (setRows, setTable, or a provider result applied). The
+ *   rows are new, and so are the drawn rows
  * - style: the style rule or the base style changed (the drawn rows may have changed with it)
  * - visibility: it was actually switched between shown and hidden
  * - selection: the selected features actually changed
@@ -268,40 +260,10 @@ export interface DatasetEventMap {
  *
  * It is meant for overlaying tens of thousands of read-only records, such as parcels or a
  * table of places. The features never enter the Store, so none of the following applies to
- * them: editing, undo / redo, the `draw.feature.*` events, the selection UI, and
- * `getAllFeatures()` / `export()`. A caller who wants to edit one copies it into the Store with
- * `addFeature`; the library does not relate the two. Create one with
- * {@link MapLibreGLDraw.addDataset}.
- *
- * @example
- * ```ts
- * const parcels = draw.addDataset({
- *   id: 'parcels',
- *   features: [
- *     {
- *       id: 'p1',
- *       type: 'Polygon',
- *       coordinates: [[[139.76, 35.68], [139.77, 35.68], [139.77, 35.69], [139.76, 35.68]]],
- *       properties: { population: 4200 },
- *     },
- *   ],
- *   styleRule: {
- *     kind: 'graduated',
- *     property: 'population',
- *     breaks: [1000, 5000],
- *     colors: ['#eff3ff', '#6baed6', '#2171b5'],
- *     other: '#cccccc',
- *   },
- *   interactive: true,
- * });
- *
- * const unsubscribe = parcels.on('click', ({ feature }) => {
- *   console.log(feature.id, feature.properties);
- * });
- *
- * parcels.setVisible(false); // hide without discarding the features
- * parcels.remove(); // the same as draw.removeDataset('parcels')
- * ```
+ * them: editing, undo / redo, the events of the features, the selection UI, and
+ * `draw.features.list()` / `draw.document`. A caller who wants to edit one copies it into the
+ * document with `draw.features.create`; the library does not relate the two. The public
+ * `Dataset` of `draw.datasets` is built on it.
  */
 export interface Dataset {
     /** The dataset id given at creation */
@@ -309,7 +271,7 @@ export interface Dataset {
     /**
      * Where it is drawn relative to the Store (the current side)
      *
-     * When the side is changed with `moveDataset`, this value becomes the new side.
+     * When the side is changed by a move, this value becomes the new side.
      */
     readonly order: DatasetOrder;
     /** Whether click / hover are fired (hits are blocked even with false) */
@@ -324,28 +286,28 @@ export interface Dataset {
      */
     setVisible(visible: boolean): void;
     /**
-     * Replaces all the features that are shown (there is no partial update). The selection
-     * drops the ids that disappear
+     * Replaces all the rows that are shown with GeoJSON features (there is no partial update).
+     * The selection drops the ids that disappear
      */
-    setFeatures(features: DatasetFeatureInput[]): void;
+    setRows(rows: readonly DatasetRow[]): void;
     /**
-     * Replaces all the rows that are shown with a columnar table (there is no partial update).
-     * The selection drops the ids that disappear
+     * Replaces all the rows that are shown with a table (there is no partial update). The
+     * selection drops the ids that disappear
      *
      * The arrays are kept and read as they are, not copied. The rows are packed straight into the
      * GPU arrays, and a row becomes a feature only when it is asked for (a hit, the selection,
      * `getFeatures`, `collectVisible`). The bboxes, the spatial chunks and the spatial index of the
-     * hit testing are computed here unless `prepared` brings them.
+     * hit testing are computed here, unless the table was prepared with `prepareTable`.
      *
-     * @param input The table
-     * @param prepared What `prepareDatasetColumnar` (from `@sakuzu/maplibre-gl-draw/columnar`)
-     *   computed for this table, typically in the Worker that read it
-     * @throws when the shape of the table does not add up, or when `prepared` was made for a table
-     *   of another length
+     * @param table The table, or the result of `prepareTable` (from
+     *   `@sakuzu/maplibre-gl-draw/table`), typically computed in the Worker that read it
+     * @throws when the shape of the table does not add up
      */
-    setColumnar(input: DatasetColumnarInput, prepared?: DatasetColumnarPrepared): void;
+    setTable(table: Table | PreparedTable): void;
     /** Replaces the style rule (undefined clears it) */
     setStyleRule(rule: StyleRule | undefined): void;
+    /** The style rule in effect (undefined when not set) */
+    getStyleRule(): StyleRule | undefined;
     /**
      * Replaces the zoom-dependent drawing factors (null clears them)
      *
@@ -380,7 +342,7 @@ export interface Dataset {
      * The features currently held, in draw order, as normalized by the dataset. The rule
      * colors and the base style are not merged in (use `collectVisible` for that)
      *
-     * For a columnar table every row with a geometry is built into a feature on the first call
+     * For a table every row with a geometry is built into a feature on the first call
      * (and kept), which costs as much as giving the rows as features in the first place.
      */
     getFeatures(): Feature[];
@@ -414,10 +376,10 @@ export interface Dataset {
      * The narrowing uses the spatial index and builds no feature, so the cost is proportional to
      * the number of rows in the range. It is the entry point for code that walks only what is
      * drawn, such as placing text next to points: choose rows with the `getRow*` reads and build
-     * the features of the chosen ones alone with `getRowFeature`.
+     * the features of the chosen ones alone with `getRow`.
      *
-     * A row is the one reported as `row` by `click` and `hover`: the index in the features given
-     * (or in the result of the provider), or the row of the columnar table. The numbers hold until
+     * A row is the one reported as `row` by `click` and `hover`: the index in the rows given (or
+     * in the result of the provider), or the row of the table. The numbers hold until
      * the contents are replaced (a `change` with the reason `features`).
      *
      * @param bounds The range in degrees (`minX` / `maxX` are longitudes, `minY` / `maxY`
@@ -426,14 +388,15 @@ export interface Dataset {
      */
     collectDrawnRows(bounds: BoundingBox): Int32Array;
     /**
-     * The feature of a row, with the rule colors and the base style applied (the same feature
+     * Reads a row as a feature, with the rule colors and the base style applied (the same feature
      * `collectVisible` returns for that row)
      *
-     * A row of a columnar table is built into a feature on each call.
+     * A row of a table is built into a feature on each call.
      *
-     * @returns null when the row is out of range
+     * @param index The row
+     * @returns undefined when the row is out of range
      */
-    getRowFeature(row: number): Feature | null;
+    getRow(index: number): Feature | undefined;
     /**
      * The id of a row, without building its feature
      *
@@ -478,7 +441,7 @@ export interface Dataset {
      * of the retained rendering. The retained batches are not touched, so switching the selection
      * never rebuilds a GPU resource.
      *
-     * An id that is not held is ignored. An id that disappears through setFeatures or through a
+     * An id that is not held is ignored. An id that disappears through setRows, setTable or a
      * provider result is dropped from the selection automatically.
      */
     setSelectedIds(ids: string[]): void;
@@ -554,7 +517,7 @@ export interface Dataset {
     off<K extends keyof DatasetEventMap>(event: K, handler: (payload: DatasetEventMap[K]) => void): void;
     /**
      * Removes the dataset and releases its GPU resources; the same as
-     * {@link MapLibreGLDraw.removeDataset}, including the `draw.dataset.remove` event.
+     * `draw.datasets.remove`, including the `dataset.removed` event.
      * Calling it again does nothing
      */
     remove(): void;

package/dist/dataset/types.js

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** Recursively checks whether it contains a position with 3 or more elements */
+function hasExtraPositionElements(value) {
+    if (typeof value[0] === 'number') {
+        return value.length !== 2;
+    }
+    return value.some(hasExtraPositionElements);
+}
+/** Returns a copy with every position truncated to the 2 elements [longitude, latitude] */
+function truncatePositions(value) {
+    if (typeof value[0] === 'number') {
+        return [value[0], value[1]];
+    }
+    return value.map(truncatePositions);
+}
+/**
+ * Normalizes a row into a feature of the same shape as in the Store
+ *
+ * It fills in the fields a row does not have and, since it is not put into the Store, layerId is
+ * an empty string. A row without a geometry (null, or a GeometryCollection) becomes a hidden
+ * Point with NaN coordinates, so it keeps its place but is neither drawn nor hit. The
+ * coordinates may contain 3-element positions (with an elevation), so a copy truncated to 2
+ * elements is made only when they do (ordinary input with only 2 elements is not copied).
+ *
+ * @param input The row
+ * @param index The row number, the id of a row without one
+ * @internal
+ */
+export function normalizeDisplayFeature(input, index) {
+    const id = input.id === undefined || input.id === null ? String(index) : String(input.id);
+    const properties = (input.properties ?? {});
+    const geometry = input.geometry;
+    if (!geometry || geometry.type === 'GeometryCollection') {
+        return {
+            id,
+            type: 'Point',
+            geometry: { type: 'Point', coordinates: [Number.NaN, Number.NaN] },
+            layerId: '',
+            groupId: undefined,
+            properties,
+            style: input.style ?? {},
+            locked: false,
+            visible: false,
+        };
+    }
+    const coords = geometry.coordinates;
+    return {
+        id,
+        type: geometry.type,
+        geometry: hasExtraPositionElements(coords)
+            ? { type: geometry.type, coordinates: truncatePositions(coords) }
+            : geometry,
+        layerId: '',
+        groupId: undefined,
+        properties,
+        style: input.style ?? {},
+        locked: false,
+        visible: true,
+    };
+}