@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/draw.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `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 as soon as the
+ * style accepts them, and added again after `setStyle`. 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,18 @@
+// 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 as soon as the
+ * style accepts them, and added again after `setStyle`. 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;
+    }
+}

package/dist/api/events.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The events: one list, `DrawEvents`, that applications and extensions subscribe to alike
+ *
+ * An event is named `resource.pastParticiple`. A change of the document carries its source,
+ * and `document.changed` arrives once per transaction with every change of it.
+ */
+import type { Position } from 'geojson';
+import type { Dataset, DatasetRow } from './datasets.js';
+import type { DrawError } from './errors.js';
+import type { Hit } from './extension/provider.js';
+import type { UpdateSource } from './extension/store.js';
+import type { Feature, FeatureInput, FileData, Group, Layer, LoadResult, Metadata, MoveTarget } from './model.js';
+import type { LayerStackEntry, Mode, Selection, SelectionType, SnapResult, VertexSelection } from './state.js';
+/** A point on the screen, as `[x, y]` in CSS pixels. */
+export type ScreenPoint = [number, number];
+/**
+ * Everything one transaction changed, as `document.changed` and the subscribers of the Store
+ * receive it. It arrives once per transaction, and each category is present only when the
+ * transaction changed it.
+ *
+ * `document.changed` fires only for a transaction that changed the document (features, layers,
+ * groups, metadata or files); the selection, the editing and the mode are carried along when
+ * the same transaction changed them. A change of the state of this client alone has its own
+ * event (`selection.changed`, `mode.changed` and so on).
+ */
+export interface DocumentChange {
+    /** Where the writes came from */
+    source?: UpdateSource;
+    /**
+     * True when the notification replaces the whole document at once, as a Store given in the
+     * `store` option does when it takes a document from elsewhere. The current mode drops what
+     * it was drawing then (`ModeHandler.onCancel`), because the shape it holds may refer to
+     * what is gone. A Store sets it; the changes that come with it list what was replaced.
+     */
+    reset?: boolean;
+    /** The features created, updated and deleted */
+    features?: {
+        created?: Feature[];
+        updated?: Array<{
+            id: string;
+            feature: Feature;
+            previous: Feature;
+            /** True while a drag or a drawing is in progress; a final update always follows */
+            isIntermediate?: boolean;
+        }>;
+        deleted?: Feature[];
+    };
+    /** The layers created, updated and deleted, and the change of their stacking order */
+    layers?: {
+        created?: Layer[];
+        updated?: Array<{
+            id: string;
+            layer: Layer;
+            previous: Layer;
+        }>;
+        deleted?: Layer[];
+        orderChanged?: {
+            order: string[];
+            previous: string[];
+        };
+    };
+    /** The groups created, updated and deleted */
+    groups?: {
+        created?: Group[];
+        updated?: Array<{
+            id: string;
+            group: Group;
+            previous: Group;
+        }>;
+        deleted?: Group[];
+    };
+    /** The new order of the items of a layer */
+    layerReorder?: {
+        layerId: string;
+        order: string[];
+        previous: string[];
+    };
+    /** The new order of the features of a group */
+    groupReorder?: {
+        groupId: string;
+        featureIds: string[];
+        previous: string[];
+    };
+    /** The new selection and the one before it */
+    selection?: {
+        type: SelectionType | null;
+        ids: string[];
+        previousType: SelectionType | null;
+        previousIds: string[];
+    };
+    /** The IDs of the features whose editing started and ended */
+    editing?: {
+        started?: string[];
+        ended?: string[];
+    };
+    /** The new mode and the one before it */
+    mode?: {
+        mode: Mode;
+        previous: Mode;
+    };
+    /** The new metadata and the one before it */
+    metadata?: {
+        metadata: Metadata;
+        previous: Metadata;
+    };
+    /** The embedded files created and deleted */
+    files?: {
+        created?: FileData[];
+        deleted?: FileData[];
+    };
+}
+/**
+ * The events, by name, with their payloads.
+ */
+export interface DrawEvents {
+    /** A feature was created */
+    'feature.created': {
+        feature: Feature;
+        source: string;
+    };
+    /** A feature changed; `intermediate` is true while a drag is in progress */
+    'feature.updated': {
+        feature: Feature;
+        previous: Feature;
+        source: string;
+        intermediate: boolean;
+    };
+    /** A feature was deleted */
+    'feature.deleted': {
+        feature: Feature;
+        source: string;
+    };
+    /** A feature moved between layers or groups */
+    'feature.moved': {
+        feature: Feature;
+        from: MoveTarget;
+        to: MoveTarget;
+        source: string;
+    };
+    /** A layer was created */
+    'layer.created': {
+        layer: Layer;
+        source: string;
+    };
+    /** A layer changed */
+    'layer.updated': {
+        layer: Layer;
+        previous: Layer;
+        source: string;
+    };
+    /** A layer was deleted */
+    'layer.deleted': {
+        layer: Layer;
+        source: string;
+    };
+    /** The stacking order of the layers changed */
+    'layer.reordered': {
+        order: readonly string[];
+        previous: readonly string[];
+        source: string;
+    };
+    /** A group was created */
+    'group.created': {
+        group: Group;
+        source: string;
+    };
+    /** A group changed */
+    'group.updated': {
+        group: Group;
+        previous: Group;
+        source: string;
+    };
+    /** A group was ungrouped */
+    'group.deleted': {
+        group: Group;
+        source: string;
+    };
+    /** The title or the description changed */
+    'metadata.updated': {
+        metadata: Metadata;
+        previous: Metadata;
+        source: string;
+    };
+    /**
+     * Every change of one transaction that changed the document (features, layers, groups,
+     * metadata or files); it arrives once per such transaction, after the events of the
+     * resources. A change of the selection, the mode or another state of this client alone does
+     * not fire it.
+     */
+    'document.changed': DocumentChange;
+    /** A document was loaded */
+    'document.loaded': {
+        result: LoadResult;
+        source: string;
+    };
+    /** The selection changed */
+    'selection.changed': {
+        selection: Selection;
+        previous: Selection;
+    };
+    /** The vertex selection changed */
+    'vertexSelection.changed': {
+        selection: VertexSelection | null;
+        previous: VertexSelection | null;
+    };
+    /** A drag started */
+    'drag.started': {
+        kind: 'feature' | 'vertex' | 'handle';
+        featureIds: string[];
+    };
+    /** A drag ended; `cancelled` is true when it was cancelled */
+    'drag.ended': {
+        kind: 'feature' | 'vertex' | 'handle';
+        featureIds: string[];
+        cancelled: boolean;
+    };
+    /** The mode changed */
+    'mode.changed': {
+        mode: Mode;
+        previous: Mode;
+    };
+    /** The items this client hides changed; `ids` is the whole set after the change */
+    'hidden.changed': {
+        ids: readonly string[];
+    };
+    /** Read-only was turned on or off */
+    'readOnly.changed': {
+        readOnly: boolean;
+    };
+    /** The interaction lock was turned on or off */
+    'interactionLock.changed': {
+        locked: boolean;
+    };
+    /** The snapping target changed */
+    'snap.changed': {
+        result: SnapResult | null;
+    };
+    /**
+     * The shape being drawn changed, or was cleared (`feature` is `null`). It fires once per
+     * change, with no throttling: at each vertex, at each move of the pointer that moves the
+     * shape, and when the shape is created, cancelled or left. `feature` has the type, the
+     * geometry and the layer of the shape, the ID it will be created with, and the radius of a
+     * circle; it is a copy that the drawing does not change afterwards. `confirmedVertices` and
+     * `highlightVertex` are the options the shape was shown with (`ModeContext.preview.set`):
+     * each is left out when it was not given, and both when the shape is cleared.
+     */
+    'preview.changed': {
+        feature: FeatureInput | null;
+        confirmedVertices?: number;
+        highlightVertex?: number;
+    };
+    /**
+     * A click on the map in the select mode, whether it hit something or not. `lngLat` is the
+     * position of the pointer before snapping, and `hit` the frontmost thing under it (a feature,
+     * a row of a dataset, a companion), or `null` when the click hit nothing
+     */
+    'map.clicked': {
+        lngLat: Position;
+        point: ScreenPoint;
+        hit: Hit | null;
+    };
+    /** A row of a dataset was clicked */
+    'dataset.clicked': {
+        datasetId: string;
+        rowIndex: number;
+        row: DatasetRow;
+        lngLat: Position;
+        point: ScreenPoint;
+    };
+    /** A dataset was added */
+    'dataset.added': {
+        dataset: Dataset;
+    };
+    /** A dataset was removed */
+    'dataset.removed': {
+        datasetId: string;
+    };
+    /** The stacking order of the datasets changed */
+    'dataset.reordered': {
+        order: readonly string[];
+        previous: readonly string[];
+    };
+    /**
+     * The image mode asks for an image to place at a position: the application picks a file
+     * and loads it with `document.load(file, { coordinate: lngLat, zoom, layerId })`. `lngLat` is
+     * the clicked position when a click led to the mode (a listener of `map.clicked` entered it),
+     * and the center of the map when the mode was entered otherwise
+     */
+    'image.requested': {
+        lngLat: Position;
+        zoom: number;
+        layerId: string;
+    };
+    /** The divisions of the stacking order changed */
+    'layerStack.changed': {
+        entries: readonly LayerStackEntry[];
+    };
+    /** Loading or reading an image failed */
+    error: {
+        error: DrawError;
+        source: string;
+        featureId?: string;
+    };
+}
+/** A function that receives the payload of an event. */
+export type DrawEventListener<K extends keyof DrawEvents = keyof DrawEvents> = (payload: DrawEvents[K]) => void;