@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/api/datasets.d.ts

@@ -0,0 +1,263 @@
+/**
+ * `draw.datasets`: large data that is drawn but not edited, and is not part of the document
+ */
+import type { Feature as GeoJSONFeature, Geometry, Position } from 'geojson';
+import type { BBox } from '../geometry/types.js';
+import type { PreparedTable, Table } from '../table/index.js';
+import type { ScreenPoint } from './events.js';
+import type { FeatureStyle, FeatureType, StyleRule } from './model.js';
+/**
+ * A row of a dataset, given and read as a GeoJSON feature. Its geometry may be `null`, as
+ * GeoJSON allows; such a row is kept in the table and is not drawn.
+ *
+ * Besides the members of GeoJSON, a row may carry `style`, its own look, which wins over the
+ * color of the style rule and the base style of the dataset. A row read back carries the look
+ * it was given merged over the base style, when that has a key.
+ */
+export type DatasetRow = GeoJSONFeature<Geometry | null> & {
+    /** The look of the row; it wins over the style rule and the base style of the dataset */
+    style?: FeatureStyle;
+};
+/**
+ * Where a dataset is stacked: below the layers of the document, above them, or inside the
+ * layer order.
+ */
+export type DatasetOrder = 'below-store' | 'above-store' | 'layer-order';
+/** Where a dataset goes in the stacking order. */
+export interface DatasetPlacement {
+    /** The division of the stacking order */
+    order?: DatasetOrder;
+    /** The position within the division, 0 at the back */
+    index?: number;
+}
+/**
+ * The default look of the rows of a dataset for each part a style rule colors (`point`,
+ * `stroke` and `fill`). A row without a look of its own takes it.
+ */
+export type DatasetBaseStyle = Partial<Record<'point' | 'stroke' | 'fill', FeatureStyle>>;
+/** The scale factor and the opacity the rows of a dataset are drawn with at a zoom. */
+export type DatasetZoomScale = (zoom: number) => {
+    scale: number;
+    opacity: number;
+};
+/**
+ * A function that returns the rows of the range in view, for a dataset whose rows are fetched
+ * as the map moves.
+ *
+ * @param bbox - The range in view, in degrees
+ * @param zoom - The zoom of the map
+ * @returns The rows of the range
+ */
+export type DatasetProvider = (bbox: BBox, zoom: number) => Promise<DatasetRow[]>;
+/** How the point rows of a dataset that overlap on the screen are thinned out. */
+export interface DatasetCollisionThinning {
+    /** Whether the thinning is on; false when it is left out */
+    enabled?: boolean;
+    /** The zoom from which every row is drawn; 17 when it is left out */
+    fullDisplayZoom?: number;
+    /** The margin around each marker, in screen pixels; 2 when it is left out */
+    marginPx?: number;
+}
+/** What the thinning of a dataset is doing now, for a message such as "showing n of N". */
+export interface DatasetThinningStats {
+    /** Whether the thinning is on */
+    enabled: boolean;
+    /** Whether it is thinning out rows at the current zoom */
+    active: boolean;
+    /** The number of rows */
+    total: number;
+    /** The number of rows drawn */
+    visible: number;
+    /** The zoom band the drawn rows were chosen for, or `null` */
+    band: number | null;
+}
+/** The events of one dataset, by name, with their payloads. */
+export interface DatasetEvents {
+    /** A row was clicked */
+    clicked: {
+        datasetId: string;
+        rowIndex: number;
+        row: DatasetRow;
+        lngLat: Position;
+        point: ScreenPoint;
+    };
+    /** The pointer moved over a row, or off every row (`rowIndex` and `row` are then `null`) */
+    hovered: {
+        datasetId: string;
+        rowIndex: number | null;
+        row: DatasetRow | null;
+        lngLat: Position;
+        point: ScreenPoint;
+    };
+    /** The rows, the look, the visibility, the selection or the thinning changed */
+    changed: {
+        reason: 'rows' | 'style' | 'visibility' | 'selection' | 'thinning';
+    };
+}
+/**
+ * What `datasets.add` takes. The rows are given in one of three ways, told apart by the name
+ * of the field: `rows`, `table` or `provider`. With none of them the dataset starts empty: it
+ * can be placed at once (`layers.reorder` takes its ID when its order is `layer-order`), and
+ * its rows are given later with `setRows` or `setTable`.
+ */
+export type DatasetOptions = {
+    /** The ID */
+    id: string;
+    /** The rule that colors the rows from their attributes */
+    styleRule?: StyleRule;
+    /** The default look */
+    baseStyle?: DatasetBaseStyle;
+    /** Whether the rows can be clicked and snapped to */
+    interactive?: boolean;
+    /** Where it is stacked */
+    order?: DatasetOrder;
+    /** The scale factor and the opacity by zoom */
+    zoomScale?: DatasetZoomScale;
+    /** The thinning of overlapping points */
+    collisionThinning?: DatasetCollisionThinning;
+    /** Picks the point rows that another renderer draws; they are not drawn by the dataset */
+    externalPointRender?: (row: DatasetRow) => boolean;
+} & ({
+    /** The rows as GeoJSON features */
+    rows: readonly DatasetRow[];
+} | {
+    /** The rows as a table, prepared or not */
+    table: Table | PreparedTable;
+} | {
+    /** The function that returns the rows of the range in view */
+    provider: DatasetProvider;
+} | {
+    /** No rows yet: they are given later with `setRows` or `setTable` */
+    rows?: undefined;
+    /** No table yet */
+    table?: undefined;
+    /** No provider */
+    provider?: undefined;
+});
+/**
+ * Large data drawn on the map and not edited; it is not part of the document.
+ */
+export interface Dataset {
+    /** The ID */
+    readonly id: string;
+    /** Where it is stacked */
+    readonly order: DatasetOrder;
+    /** Whether the rows can be clicked and snapped to */
+    readonly interactive: boolean;
+    /** Whether it is visible */
+    readonly visible: boolean;
+    /** Shows or hides the dataset. */
+    setVisible(visible: boolean): void;
+    /** Replaces every row. */
+    setRows(rows: readonly DatasetRow[]): void;
+    /** Replaces every row with a table. */
+    setTable(table: Table | PreparedTable): void;
+    /** Replaces the style rule; `undefined` removes it. */
+    setStyleRule(rule: StyleRule | undefined): void;
+    /**
+     * The style rule, or `undefined` when none is set: the rule last given to `setStyleRule`, or
+     * the one given to `datasets.add` when it was not replaced.
+     */
+    getStyleRule(): StyleRule | undefined;
+    /** Replaces the scale factor and the opacity by zoom; `null` removes them. */
+    setZoomScale(zoomScale: DatasetZoomScale | null): void;
+    /** The scale factor and the opacity by zoom, or `null` when none is set. */
+    getZoomScale(): DatasetZoomScale | null;
+    /** Replaces the default look; `undefined` removes it. */
+    setBaseStyle(style: DatasetBaseStyle | undefined): void;
+    /** Replaces the function that picks the point rows another renderer draws. */
+    setExternalPointRender(predicate: ((row: DatasetRow) => boolean) | undefined): void;
+    /** The default look, or `undefined` when none is set. */
+    getBaseStyle(): DatasetBaseStyle | undefined;
+    /** Every row, in drawing order, without the rule colors and the default look. */
+    listRows(): DatasetRow[];
+    /** The rows whose extent meets the range, with the rule colors and the default look. */
+    listVisibleRows(bbox: BBox): DatasetRow[];
+    /** The indexes of the rows drawn now whose extent meets the range, in ascending order. */
+    listDrawnRows(bbox: BBox): Int32Array;
+    /** Reads a row as a GeoJSON feature; `undefined` when there is no such row. */
+    getRow(index: number): DatasetRow | undefined;
+    /** The ID of a row, or `null` when there is no such row or it has no ID. */
+    getRowId(index: number): string | null;
+    /** The type of the geometry of a row, or `null` when there is no such row. */
+    getRowType(index: number): FeatureType | null;
+    /** The extent of a row, or `null` when there is no such row or it has no geometry. */
+    getRowBounds(index: number): BBox | null;
+    /** The position of a point row, or `null` when the row is not a point. */
+    getRowPoint(index: number): Position | null;
+    /** The index of the row with this ID, or `null` when there is none. */
+    findRow(id: string): number | null;
+    /** Replaces the IDs of the selected rows. */
+    setSelectedRowIds(ids: readonly string[]): void;
+    /** The IDs of the selected rows. */
+    getSelectedRowIds(): string[];
+    /** Replaces the thinning of overlapping points; `null` turns it off. */
+    setCollisionThinning(options: DatasetCollisionThinning | null): void;
+    /** The thinning in effect with every default filled in, or `null` when it is off. */
+    getCollisionThinning(): Required<DatasetCollisionThinning> | null;
+    /** The IDs of the rows the thinning draws, or `null` when it thins nothing. */
+    listVisibleRowIds(): ReadonlySet<string> | null;
+    /** What the thinning is doing now. */
+    getThinningStats(): DatasetThinningStats;
+    /** A number that changes whenever the rows drawn change. */
+    getDrawnRowsRevision(): number;
+    /** Fetches the rows of the provider again on the next move of the map. */
+    refresh(): void;
+    /** Subscribes to an event of this dataset and returns the function that unsubscribes. */
+    on<K extends keyof DatasetEvents>(event: K, listener: (payload: DatasetEvents[K]) => void): () => void;
+    /** Unsubscribes from an event of this dataset. */
+    off<K extends keyof DatasetEvents>(event: K, listener: (payload: DatasetEvents[K]) => void): void;
+}
+/**
+ * The datasets on the map, in stacking order.
+ */
+export interface DatasetsCollection {
+    /**
+     * Gets a dataset by ID.
+     *
+     * @returns The dataset, or `undefined` when there is none with this ID
+     */
+    get(id: string): Dataset | undefined;
+    /** Lists the datasets in stacking order. */
+    list(): Dataset[];
+    /** Counts the datasets. */
+    count(): number;
+    /** Whether a dataset with this ID exists. */
+    has(id: string): boolean;
+    /**
+     * Adds a dataset and returns it.
+     *
+     * @throws `DrawError` with the code `already-exists` when the ID is taken, or
+     *   `invalid-input` when the options are wrong
+     */
+    add(options: DatasetOptions): Dataset;
+    /**
+     * Adds several datasets in one transaction, all of them or none, and returns them.
+     *
+     * @throws `DrawError` as {@link DatasetsCollection.add} does, for any of the options;
+     *   nothing is added then
+     */
+    addMany(options: readonly DatasetOptions[]): Dataset[];
+    /**
+     * Removes a dataset.
+     *
+     * @returns True when it was removed
+     * @throws `DrawError` with the code `not-found` when there is no dataset with this ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Removes several datasets in one transaction: all of them or none.
+     *
+     * @returns True when they were removed
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist; nothing
+     *   is removed then
+     */
+    removeMany(ids: readonly string[]): boolean;
+    /**
+     * Moves a dataset in the stacking order.
+     *
+     * @returns True when it moved
+     * @throws `DrawError` with the code `not-found` when there is no dataset with this ID
+     */
+    move(id: string, placement: DatasetPlacement): boolean;
+}

package/dist/api/document.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `draw.document`: the whole document, to load and to write out
+ */
+import type { FeatureCollection } from 'geojson';
+import type { DrawDocument, LoadOptions, LoadResult, LoadSource } from './model.js';
+/**
+ * The whole document: features, layers, groups and metadata.
+ */
+export interface DocumentResource {
+    /**
+     * Reads a file, a JSON string, a document of the library or GeoJSON.
+     *
+     * `options.mode` decides whether the document is replaced or the features are added; it is
+     * `replace` for a document of the library and `merge` for GeoJSON when it is left out.
+     *
+     * The source is read (and an image decoded) first; then every write is one transaction with
+     * the source `load`, whatever the format: one `document.changed` and one notification of the
+     * Store, one step for a subscriber that records changes. A load that fails writes nothing.
+     * The layer of `options.layer` and the group of `options.group` are created in that
+     * transaction too.
+     *
+     * @returns What was read, or `null` when the document is read-only
+     * @throws `DrawError` (the promise rejects; every failure is a `DrawError`) with the code
+     *   `unsupported-format` when the source cannot be read (text that is not JSON, data that is
+     *   neither a document of the library nor GeoJSON, an image file that cannot be decoded), or
+     *   `invalid-input` when the document is not valid (a document of the library that breaks
+     *   its format, an embedded image that is broken, an image without `coordinate`, `layer`
+     *   with `layerId`, `layer` or `group` with a document of the library), `not-found` for a
+     *   `layerId` the document does not have, or `already-exists` for an ID of `layer` or
+     *   `group` that is taken
+     */
+    load(source: LoadSource, options?: LoadOptions): Promise<LoadResult | null>;
+    /**
+     * Reads several sources and writes all of them in one transaction with the source `load`:
+     * one `document.changed` and one notification of the Store, so that an import of several
+     * files is one step to undo and one change to send. Every source is read first, in order; the
+     * writes then follow in the same order, each as `load` would write it, against the document
+     * the earlier items left (a document of the library replaces what the earlier items wrote).
+     * `document.loaded` arrives once per item, after the writes.
+     *
+     * An item may name with `layerId` a layer that an earlier item creates with `layer`, so the
+     * items can fill one new layer and a group of it. A layer named by `layerId` that an earlier
+     * item removed is replaced with the active layer. With `layer` and `group` in the options of
+     * the items, an import of one layer per file and one group per folder is still one
+     * transaction.
+     *
+     * @param items - The sources, each with the options `load` takes
+     * @returns What was read from each item, in the order of the items, or `null` when the
+     *   document is read-only
+     * @throws `DrawError` (the promise rejects) as `load` does, for the first item that cannot
+     *   be read (`not-found` for a `layerId` that neither the document nor an earlier item has);
+     *   nothing is written then. `invalid-input` when `items` is not an array of objects
+     *   with a `source`
+     */
+    loadMany(items: readonly {
+        source: LoadSource;
+        options?: LoadOptions;
+    }[]): Promise<LoadResult[] | null>;
+    /** The whole document in the format of the library. */
+    toJSON(): DrawDocument;
+    /**
+     * The whole document as GeoJSON. The values of the library are kept in `properties` under
+     * the prefixed keys.
+     */
+    toGeoJSON(): FeatureCollection;
+}

package/dist/api/draw.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `Draw`: the draw instance, its resources and the members that belong to no resource
+ */
+import type { Map as MaplibreMap } from 'maplibre-gl';
+import type { DatasetsCollection } from './datasets.js';
+import type { DocumentResource } from './document.js';
+import type { DrawingResource } from './drawing.js';
+import type { DrawEvents } from './events.js';
+import type { StoreView, UpdateSource } from './extension/store.js';
+import type { ExtensionsCollections } from './extensions.js';
+import type { FeaturesCollection } from './features.js';
+import type { GroupsCollection } from './groups.js';
+import type { HiddenCollection } from './hidden.js';
+import type { LayersCollection } from './layers.js';
+import type { MetadataResource } from './metadata.js';
+import type { DrawOptions, OptionsResource } from './options.js';
+import type { SelectionResource, VertexSelectionResource } from './selection.js';
+import type { LayerStackEntry, Mode, TerrainDiagnostics } from './state.js';
+/** The options of {@link Draw.transact} */
+export interface TransactOptions {
+    /** Where the writes come from; `'local'` when left out */
+    source?: UpdateSource;
+    /**
+     * Whether the writes ignore the locks of the features, groups and layers; read-only still
+     * refuses them. False when left out.
+     */
+    ignoreLocks?: boolean;
+}
+/**
+ * A draw instance on a map: the collections and resources of the document and of this
+ * client, and the members that belong to no resource.
+ */
+export interface Draw {
+    /** The features of the document */
+    readonly features: FeaturesCollection;
+    /** The layers of the document */
+    readonly layers: LayersCollection;
+    /** The groups of the document */
+    readonly groups: GroupsCollection;
+    /** The large data that is drawn but not edited, outside the document */
+    readonly datasets: DatasetsCollection;
+    /** What this client hides without changing the document */
+    readonly hidden: HiddenCollection;
+    /** What this client has selected */
+    readonly selection: SelectionResource;
+    /** The selected vertices of one feature in this client */
+    readonly vertexSelection: VertexSelectionResource;
+    /** The shape the current drawing mode is drawing, to drive it from code */
+    readonly drawing: DrawingResource;
+    /** The title and the description of the document */
+    readonly metadata: MetadataResource;
+    /** The options that can change while the instance runs */
+    readonly options: OptionsResource;
+    /** The whole document, to load and to write out */
+    readonly document: DocumentResource;
+    /** The plugins, modes, feature types, overlays and providers */
+    readonly extensions: ExtensionsCollections;
+    /** The map the instance draws on. */
+    getMap(): MaplibreMap;
+    /** The Store, to read the document and the state and to subscribe to their changes. */
+    getStore(): StoreView;
+    /** The current mode. */
+    getMode(): Mode;
+    /**
+     * Changes the mode.
+     *
+     * @returns False when the mode cannot be entered now
+     * @throws `DrawError` with the code `not-found` when there is no mode with this name
+     */
+    setMode(mode: Mode): boolean;
+    /** Whether the document is read-only. */
+    isReadOnly(): boolean;
+    /** Turns read-only on or off. */
+    setReadOnly(value: boolean): void;
+    /** Whether the interaction lock is on. */
+    isInteractionLocked(): boolean;
+    /** Turns the interaction lock on or off. */
+    setInteractionLocked(value: boolean): void;
+    /**
+     * Runs `fn` as one transaction: its writes arrive as one `document.changed`.
+     *
+     * In nested calls the source of the outermost call wins. With `ignoreLocks`, the writes of
+     * `fn` through the resources of this instance ignore the locks of the features, groups and
+     * layers, as a change applied again from a record needs; read-only still refuses them, and
+     * what the user does with the pointer and the keys still respects the locks. A nested call
+     * inside such a call ignores them as well.
+     *
+     * @param options - `source` names where the writes come from; `ignoreLocks` lets them
+     *   change locked features, groups and layers
+     * @returns What `fn` returns
+     */
+    transact<T>(fn: () => T, options?: TransactOptions): T;
+    /**
+     * Subscribes to an event.
+     *
+     * @returns The function that unsubscribes
+     */
+    on<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): () => void;
+    /** Unsubscribes from an event. */
+    off<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): void;
+    /**
+     * Subscribes to the next occurrence of an event only.
+     *
+     * @returns The function that unsubscribes before it occurs
+     */
+    once<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): () => void;
+    /** Whether some drawing work has not finished yet. */
+    hasPendingWork(): boolean;
+    /** The divisions of the stacking order, one per run of layers. */
+    getLayerStack(): readonly LayerStackEntry[];
+    /** Diagnostics; their fields follow the drawing and carry a weaker promise. */
+    readonly debug: {
+        /** The state the terrain was drawn with. */
+        terrain(): TerrainDiagnostics;
+    };
+    /**
+     * Removes the instance from the map and releases everything it holds. A second call does
+     * nothing; every other method of the instance and of its collections then throws `DrawError`
+     * with the code `invalid-state` (`document.load` rejects with it).
+     */
+    destroy(): void;
+}
+/**
+ * Puts a draw instance on a map and returns it.
+ *
+ * It can be called before, while or after the map loads. The layers are added on top of the map
+ * as soon as the style accepts them. After `setStyle`, with or without `diff`, they are on top
+ * again: added again after a full replacement, and moved above the layers of the new style after
+ * a diff. A layer added to the map later goes above them and stays there until the style changes.
+ * Unless `initDefaultLayer: false` is given, the document starts with one empty layer. Several
+ * instances can share a page, each on its own map.
+ *
+ * @param map - The map to draw on
+ * @param options - The options; every one can be omitted
+ * @returns The draw instance
+ */
+export declare function createDraw(map: MaplibreMap, options?: DrawOptions): Draw;

package/dist/api/draw.js

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createDraw as createDrawInstance } from './impl/create-draw.js';
+/**
+ * Puts a draw instance on a map and returns it.
+ *
+ * It can be called before, while or after the map loads. The layers are added on top of the map
+ * as soon as the style accepts them. After `setStyle`, with or without `diff`, they are on top
+ * again: added again after a full replacement, and moved above the layers of the new style after
+ * a diff. A layer added to the map later goes above them and stays there until the style changes.
+ * Unless `initDefaultLayer: false` is given, the document starts with one empty layer. Several
+ * instances can share a page, each on its own map.
+ *
+ * @param map - The map to draw on
+ * @param options - The options; every one can be omitted
+ * @returns The draw instance
+ */
+export function createDraw(map, options) {
+    return createDrawInstance(map, options);
+}

package/dist/api/drawing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `draw.drawing`: the shape the current drawing mode is drawing, driven from outside the
+ * pointer and the keys
+ */
+import type { Position } from 'geojson';
+/**
+ * The shape the current drawing mode is drawing, driven from code: to draw from typed
+ * coordinates, from another input device, or in an automated run.
+ *
+ * `addVertex`, `moveTo` and `finish` act as the input they stand for would: they are made into
+ * the same pointer and key events the map gives, at the point of the screen the position
+ * projects to, and go the same way as that input, through the `input` receivers of the plugins
+ * first and then to the mode. The position is used as it is: nothing snaps it, and the event
+ * carries it as its snapped position. A mode that ignores clicks, or a plugin that consumes
+ * them, ignores or consumes these as well.
+ *
+ * Extensions reach the same object as `ctx.drawing`.
+ */
+export interface DrawingResource {
+    /**
+     * Whether a drawing mode is drawing: a shape is in progress, or the mode is ready to place its
+     * first vertex (the current mode writes features).
+     */
+    isActive(): boolean;
+    /**
+     * Whether a shape is in progress: the mode shows a shape that is not created yet. False
+     * while a drawing mode waits for its first vertex.
+     */
+    isDrawing(): boolean;
+    /**
+     * Places a vertex at a position, as a click there would: the pointer moves there, then
+     * clicks. It does not snap. What the click does is up to the mode: the point mode creates the
+     * point, and a click on the closing vertex of a line or an area finishes it. The position is
+     * exact, so the click tolerance of the pointer (10 px) does not apply: a vertex a few pixels
+     * from the last one is placed, and one near the closing vertex does not finish the shape.
+     * Only a position exactly equal to the closing vertex (the last vertex of a line, the first
+     * of an area) finishes it, and one exactly equal to the last vertex of an area is not placed
+     * again.
+     *
+     * @param position - The position, as `[longitude, latitude]` in degrees
+     * @returns True when the mode (or a plugin) took the click; false when no drawing mode is
+     *   active or nothing took it
+     * @throws `DrawError` with the code `invalid-input` when the position is not two finite
+     *   numbers
+     */
+    addVertex(position: Position): boolean;
+    /**
+     * Moves the pointer to a position, as a pointer move there would: the preview of the shape
+     * follows it. It does not snap, and, as with `addVertex`, the position is exact. It does
+     * nothing when no drawing mode is active.
+     *
+     * @param position - The position, as `[longitude, latitude]` in degrees
+     * @throws `DrawError` with the code `invalid-input` when the position is not two finite
+     *   numbers
+     */
+    moveTo(position: Position): void;
+    /**
+     * Completes the shape in progress, as a double click on its last vertex or Enter would: the
+     * mode creates the feature from the vertices placed so far, as soon as there are enough of
+     * them (2 for a line, 3 for an area), wherever the last one is.
+     *
+     * @returns True when the shape was completed; false when no shape is in progress, or the mode
+     *   did not complete it (too few vertices)
+     */
+    finish(): boolean;
+    /**
+     * Cancels the shape in progress, as an Escape does while drawing: the mode drops it
+     * (`ModeHandler.onCancel`), the preview is cleared and the mode stays the current one. When
+     * no shape is in progress it does nothing; unlike an Escape, it does not leave the mode.
+     *
+     * @returns True when a shape was in progress and was cancelled
+     */
+    cancel(): boolean;
+    /**
+     * Removes the last vertex of the shape in progress.
+     *
+     * @returns True when a vertex was removed; false when nothing is being drawn or the mode has
+     *   no vertex to remove
+     */
+    undoVertex(): boolean;
+    /**
+     * Puts back the vertex the last `undoVertex` removed.
+     *
+     * @returns True when a vertex was put back
+     */
+    redoVertex(): boolean;
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The error thrown for a wrong argument
+ *
+ * A method throws it when an argument is wrong (an ID that does not exist, an input of the
+ * wrong shape) and changes nothing. A refusal because of the state (read-only, a lock) is not
+ * an error: the method returns `null` or `false` instead.
+ */
+/**
+ * Why a {@link DrawError} was thrown.
+ *
+ * - `not-found`: an ID that does not exist
+ * - `already-exists`: an ID that is already taken
+ * - `invalid-input`: an input of the wrong shape or value
+ * - `unsupported-format`: a source that cannot be read
+ * - `invalid-state`: a call that is not possible in the current situation, such as deleting
+ *   a feature while it is being drawn, or any call on an instance that was destroyed
+ */
+export type DrawErrorCode = 'not-found' | 'already-exists' | 'invalid-input' | 'unsupported-format' | 'invalid-state';
+/**
+ * The error a method throws when an argument is wrong; the method has changed nothing.
+ */
+export declare class DrawError extends Error {
+    /** Why it was thrown */
+    readonly code: DrawErrorCode;
+    /** More about the cause, such as the ID that was not found */
+    readonly details?: unknown;
+    /**
+     * Creates the error
+     *
+     * @param code - Why it is thrown
+     * @param message - A description in English, for logs
+     * @param details - More about the cause
+     */
+    constructor(code: DrawErrorCode, message: string, details?: unknown);
+}

package/dist/api/errors.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The error a method throws when an argument is wrong; the method has changed nothing.
+ */
+export class DrawError extends Error {
+    /**
+     * Creates the error
+     *
+     * @param code - Why it is thrown
+     * @param message - A description in English, for logs
+     * @param details - More about the cause
+     */
+    constructor(code, message, details) {
+        super(message);
+        /** Why it was thrown */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** More about the cause, such as the ID that was not found */
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'DrawError';
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}