@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/impl/shared.d.ts

@@ -0,0 +1,64 @@
+import type { Store } from '../../store/store.js';
+import type { Feature, Group, Layer, SelectionType } from '../../store/types.js';
+import { DrawError } from '../errors.js';
+/** The error for an ID that names nothing of its kind */
+export declare function notFound(kind: string, id: unknown): DrawError;
+/** The error for an input of the wrong shape or value */
+export declare function invalidInput(message: string, details?: unknown): DrawError;
+/** Whether the value is a plain object (not null, not an array) */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Throws unless the value is a plain object */
+export declare function requireRecord(value: unknown, what: string): void;
+/** Throws unless the value is an array of strings, and returns it without repeated IDs */
+export declare function requireIds(value: unknown, what?: string): string[];
+/** Throws unless the value is a non-empty string */
+export declare function requireId(value: unknown, what?: string): string;
+/** Throws unless the key of the object is absent or a boolean */
+export declare function optionalBoolean(value: Record<string, unknown>, key: string): void;
+/** Throws unless the key of the object is absent or a string */
+export declare function optionalString(value: Record<string, unknown>, key: string): void;
+/** Throws unless the keys of the object are all among the allowed ones */
+export declare function onlyKeys(value: Record<string, unknown>, allowed: readonly string[], what: string): void;
+/** Throws unless the index is absent or an integer from 0 */
+export declare function optionalIndex(value: unknown): number | undefined;
+/**
+ * The keys of a filter that must match; a key given as `undefined` does not filter
+ *
+ * @returns The entries to compare
+ */
+export declare function filterEntries(filter: unknown, allowed: readonly string[]): Array<[string, unknown]>;
+/** Whether an item matches every entry of a filter */
+export declare function matches(item: object, entries: Array<[string, unknown]>): boolean;
+/** Whether a patch changes nothing but `locked` and `visible`, which a lock still allows */
+export declare function onlyLockOrVisibility(patch: object): boolean;
+/** Whether the ID names a feature, a group or a layer */
+export declare function isTaken(store: Store, id: string): boolean;
+/** The layer that lists a group, or else the layer the group records */
+export declare function layerOfGroup(store: Store, group: Group): Layer | undefined;
+/**
+ * Runs `fn` with the locks of the features, groups and layers of the Store ignored by the
+ * writes of the resources; read-only is still enforced. Nested calls keep ignoring them until
+ * the outermost one ends.
+ */
+export declare function withLocksIgnored<T>(store: Store, fn: () => T): T;
+/** Whether the writes to the Store ignore the locks now (see {@link withLocksIgnored}) */
+export declare function locksIgnored(store: Store): boolean;
+/**
+ * Whether a lock refuses a write to the feature: it, its group or its layer is locked, and
+ * the write does not ignore the locks
+ */
+export declare function featureLocked(store: Store, feature: Feature): boolean;
+/**
+ * Whether a lock refuses a write to the group: it or its layer is locked, and the write does
+ * not ignore the locks
+ */
+export declare function groupLocked(store: Store, group: Group): boolean;
+/** Whether a lock refuses a write to the layer: it is locked, and the write does not ignore it */
+export declare function layerLocked(store: Store, layer: Layer): boolean;
+/**
+ * Whether an item can be seen: it exists, its own visible flag and the ones of its group and
+ * layer are on, and this client hides none of them
+ */
+export declare function isShown(store: Store, type: SelectionType, id: string): boolean;
+/** Looks an item of a type up, or undefined */
+export declare function getItem(store: Store, type: SelectionType, id: string): Feature | Group | Layer | undefined;

package/dist/api/impl/shared.js

@@ -0,0 +1,178 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { isFeatureLocked, isGroupLocked } from '../../store/lock.js';
+import { DrawError } from '../errors.js';
+// ============================================================================
+// Errors
+// ============================================================================
+/** The error for an ID that names nothing of its kind */
+export function notFound(kind, id) {
+    return new DrawError('not-found', `There is no ${kind} with the ID ${JSON.stringify(id)}`, {
+        id,
+    });
+}
+/** The error for an input of the wrong shape or value */
+export function invalidInput(message, details) {
+    return new DrawError('invalid-input', message, details);
+}
+// ============================================================================
+// Checks of the arguments
+// ============================================================================
+/** Whether the value is a plain object (not null, not an array) */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Throws unless the value is a plain object */
+export function requireRecord(value, what) {
+    if (!isRecord(value))
+        throw invalidInput(`${what} must be an object`);
+}
+/** Throws unless the value is an array of strings, and returns it without repeated IDs */
+export function requireIds(value, what = 'The IDs') {
+    if (!Array.isArray(value) || value.some((id) => typeof id !== 'string')) {
+        throw invalidInput(`${what} must be an array of strings`);
+    }
+    return [...new Set(value)];
+}
+/** Throws unless the value is a non-empty string */
+export function requireId(value, what = 'The ID') {
+    if (typeof value !== 'string' || value === '') {
+        throw invalidInput(`${what} must be a non-empty string`);
+    }
+    return value;
+}
+/** Throws unless the key of the object is absent or a boolean */
+export function optionalBoolean(value, key) {
+    if (key in value && value[key] !== undefined && typeof value[key] !== 'boolean') {
+        throw invalidInput(`${key} must be a boolean`);
+    }
+}
+/** Throws unless the key of the object is absent or a string */
+export function optionalString(value, key) {
+    if (key in value && value[key] !== undefined && typeof value[key] !== 'string') {
+        throw invalidInput(`${key} must be a string`);
+    }
+}
+/** Throws unless the keys of the object are all among the allowed ones */
+export function onlyKeys(value, allowed, what) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            throw invalidInput(`${what} cannot have the key ${key}`);
+    }
+}
+/** Throws unless the index is absent or an integer from 0 */
+export function optionalIndex(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw invalidInput('index must be an integer from 0');
+    }
+    return value;
+}
+/**
+ * The keys of a filter that must match; a key given as `undefined` does not filter
+ *
+ * @returns The entries to compare
+ */
+export function filterEntries(filter, allowed) {
+    if (filter === undefined)
+        return [];
+    requireRecord(filter, 'The filter');
+    onlyKeys(filter, allowed, 'The filter');
+    return Object.entries(filter).filter(([, value]) => value !== undefined);
+}
+/** Whether an item matches every entry of a filter */
+export function matches(item, entries) {
+    const record = item;
+    return entries.every(([key, value]) => record[key] === value);
+}
+/** Whether a patch changes nothing but `locked` and `visible`, which a lock still allows */
+export function onlyLockOrVisibility(patch) {
+    return Object.keys(patch).every((key) => key === 'locked' || key === 'visible');
+}
+// ============================================================================
+// Lookups of the document
+// ============================================================================
+/** Whether the ID names a feature, a group or a layer */
+export function isTaken(store, id) {
+    return (store.getFeature(id) !== undefined ||
+        store.getGroup(id) !== undefined ||
+        store.getLayer(id) !== undefined);
+}
+/** The layer that lists a group, or else the layer the group records */
+export function layerOfGroup(store, group) {
+    return store.getLayer(group.layerId);
+}
+/** How deep each Store is in `transact` calls with `ignoreLocks` */
+const lockBypassDepth = new WeakMap();
+/**
+ * Runs `fn` with the locks of the features, groups and layers of the Store ignored by the
+ * writes of the resources; read-only is still enforced. Nested calls keep ignoring them until
+ * the outermost one ends.
+ */
+export function withLocksIgnored(store, fn) {
+    lockBypassDepth.set(store, (lockBypassDepth.get(store) ?? 0) + 1);
+    try {
+        return fn();
+    }
+    finally {
+        const depth = (lockBypassDepth.get(store) ?? 1) - 1;
+        if (depth === 0)
+            lockBypassDepth.delete(store);
+        else
+            lockBypassDepth.set(store, depth);
+    }
+}
+/** Whether the writes to the Store ignore the locks now (see {@link withLocksIgnored}) */
+export function locksIgnored(store) {
+    return lockBypassDepth.has(store);
+}
+/**
+ * Whether a lock refuses a write to the feature: it, its group or its layer is locked, and
+ * the write does not ignore the locks
+ */
+export function featureLocked(store, feature) {
+    return !locksIgnored(store) && isFeatureLocked(feature, store);
+}
+/**
+ * Whether a lock refuses a write to the group: it or its layer is locked, and the write does
+ * not ignore the locks
+ */
+export function groupLocked(store, group) {
+    return !locksIgnored(store) && isGroupLocked(group, () => layerOfGroup(store, group));
+}
+/** Whether a lock refuses a write to the layer: it is locked, and the write does not ignore it */
+export function layerLocked(store, layer) {
+    return !locksIgnored(store) && layer.locked;
+}
+/**
+ * Whether an item can be seen: it exists, its own visible flag and the ones of its group and
+ * layer are on, and this client hides none of them
+ */
+export function isShown(store, type, id) {
+    const layerShown = (layerId) => store.getLayer(layerId)?.visible === true && !store.isHidden(layerId);
+    const groupShown = (group) => group.visible && !store.isHidden(group.id) && layerShown(group.layerId);
+    if (type === 'layer')
+        return layerShown(id);
+    if (type === 'group') {
+        const group = store.getGroup(id);
+        return group !== undefined && groupShown(group);
+    }
+    const feature = store.getFeature(id);
+    if (!feature?.visible || store.isHidden(id))
+        return false;
+    if (feature.groupId) {
+        const group = store.getGroup(feature.groupId);
+        if (group && !groupShown(group))
+            return false;
+    }
+    return layerShown(feature.layerId);
+}
+/** Looks an item of a type up, or undefined */
+export function getItem(store, type, id) {
+    if (type === 'feature')
+        return store.getFeature(id);
+    if (type === 'group')
+        return store.getGroup(id);
+    return store.getLayer(id);
+}

package/dist/api/impl/validate-extension.d.ts

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

package/dist/api/impl/validate-extension.js

@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The shape of an extension, checked before it is added
+ *
+ * `draw.extensions.*.add` hands every value to {@link validateExtension} before anything is
+ * installed, so a value of the wrong shape is refused with `DrawError('invalid-input')` and
+ * nothing is added. The checks follow the contract types: a required member must be there with
+ * the right type, and an optional member, when it is given, must have the right type too. The
+ * name is checked by the collection itself.
+ */
+import { DrawError } from '../errors.js';
+/** The kinds of GeoJSON geometry a feature type can declare */
+const GEOMETRY_TYPES = new Set([
+    'Point',
+    'LineString',
+    'Polygon',
+    'MultiPoint',
+    'MultiLineString',
+    'MultiPolygon',
+    'GeometryCollection',
+]);
+/** The receivers of the input a plugin may give */
+const INPUT_HANDLERS = [
+    'onPointerDown',
+    'onPointerMove',
+    'onPointerUp',
+    'onPointerLeave',
+    'onClick',
+    'onDoubleClick',
+    'onDragStart',
+    'onDrag',
+    'onDragEnd',
+    'onDragCancel',
+    'onKeyDown',
+    'onKeyUp',
+];
+/** The hooks of the interaction of a plugin */
+const INTERACTION_HOOKS = [
+    'filterSelection',
+    'onFeatureClick',
+    'onFeatureDoubleClick',
+    'onDrawCommit',
+    'isBusy',
+    'finish',
+    'cancel',
+    'container',
+];
+/** What each kind requires and allows, besides its name */
+const SHAPES = {
+    plugin: { required: ['onAdd'], optional: ['onRemove'] },
+    'feature type': {
+        required: [],
+        optional: [
+            'appliesTo',
+            'hitTest',
+            'boxSelect',
+            'bounds',
+            'outline',
+            'bbox',
+            'handles',
+            'onHandleDrag',
+            'onHandleDragStart',
+            'onHandleDragEnd',
+            'snapCandidates',
+        ],
+    },
+    overlay: {
+        required: ['onAdd', 'draw', 'onRemove'],
+        optional: ['drawForLayer', 'drawVertices', 'hasPendingWork'],
+    },
+    'snap provider': { required: ['candidates'], optional: [] },
+    'handle provider': {
+        required: ['handles', 'onDrag'],
+        optional: ['globalHandles', 'onDragStart', 'onDragEnd'],
+    },
+    'companion provider': { required: ['has', 'draw', 'hitTest'], optional: ['onClick'] },
+};
+/** The error for a value of the wrong shape */
+function wrongShape(kind, message, member) {
+    return new DrawError('invalid-input', `The ${kind} ${message}`, member === undefined ? { kind } : { kind, member });
+}
+/** Whether the value is an object that is not an array */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Checks that the members named are functions: required ones must be there */
+function requireFunctions(kind, value, required, optional, prefix = '') {
+    for (const member of required) {
+        if (typeof value[member] !== 'function') {
+            throw wrongShape(kind, `must have the function ${prefix}${member}`, `${prefix}${member}`);
+        }
+    }
+    for (const member of optional) {
+        if (value[member] !== undefined && typeof value[member] !== 'function') {
+            throw wrongShape(kind, `has ${prefix}${member} that is not a function`, `${prefix}${member}`);
+        }
+    }
+}
+/** Checks an optional group of functions, such as the input receivers of a plugin */
+function optionalGroup(kind, value, member, names) {
+    const group = value[member];
+    if (group === undefined)
+        return;
+    if (!isObject(group))
+        throw wrongShape(kind, `has ${member} that is not an object`, member);
+    requireFunctions(kind, group, [], names, `${member}.`);
+}
+/** Checks an optional number, finite and, when asked, not negative */
+function optionalNumber(kind, value, member, nonNegative) {
+    const number = value[member];
+    if (number === undefined)
+        return;
+    if (typeof number !== 'number' || !Number.isFinite(number) || (nonNegative && number < 0)) {
+        const what = nonNegative ? 'a finite number of 0 or more' : 'a finite number';
+        throw wrongShape(kind, `has ${member} that is not ${what}`, member);
+    }
+}
+/**
+ * Checks that a value has the shape of an extension of the kind; the name is not checked
+ *
+ * @param kind - The kind of extension the value is added as
+ * @param value - The value given to `add`
+ * @throws `DrawError` with the code `invalid-input` when the value does not have the shape
+ * @internal
+ */
+export function validateExtension(kind, value) {
+    if (kind === 'mode') {
+        if (typeof value !== 'function')
+            throw wrongShape(kind, 'must be a function');
+        return;
+    }
+    if (!isObject(value))
+        throw wrongShape(kind, 'must be an object');
+    const shape = SHAPES[kind];
+    requireFunctions(kind, value, shape.required, shape.optional);
+    switch (kind) {
+        case 'plugin':
+            optionalGroup(kind, value, 'input', INPUT_HANDLERS);
+            optionalGroup(kind, value, 'interaction', INTERACTION_HOOKS);
+            return;
+        case 'feature type': {
+            if (typeof value.geometry !== 'string' || !GEOMETRY_TYPES.has(value.geometry)) {
+                throw wrongShape(kind, 'must name a kind of GeoJSON geometry in geometry', 'geometry');
+            }
+            const renderer = value.renderer;
+            if (!isObject(renderer))
+                throw wrongShape(kind, 'must have a renderer', 'renderer');
+            requireFunctions(kind, renderer, ['onAdd', 'draw', 'onRemove'], [], 'renderer.');
+            optionalNumber(kind, value, 'hitPaddingPx', true);
+            return;
+        }
+        case 'overlay':
+            optionalNumber(kind, value, 'order', false);
+            return;
+        default:
+            return;
+    }
+}

package/dist/api/layers.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `draw.layers`: the layers of the document
+ */
+import type { Layer, LayerFilter, LayerInput, LayerPatch } from './model.js';
+/**
+ * The layers of the document, with the standard methods of a collection, the stacking order
+ * and the active layer.
+ *
+ * A wrong argument (an ID that does not exist, an input of the wrong shape) throws a
+ * `DrawError` and changes nothing. A refusal because of the state (read-only, a lock) returns
+ * `null` or `false` and changes nothing. A method whose name ends in `Many` runs in one
+ * transaction: all of it happens or none of it does.
+ */
+export interface LayersCollection {
+    /**
+     * Gets a layer by ID.
+     *
+     * @returns The layer, or `undefined` when there is none with this ID
+     */
+    get(id: string): Layer | undefined;
+    /**
+     * Gets layers by ID, in the order of the IDs.
+     *
+     * @returns One entry per ID: the layer, or `undefined` when there is none with that ID
+     */
+    getMany(ids: readonly string[]): (Layer | undefined)[];
+    /**
+     * Lists the layers in stacking order, from the back.
+     *
+     * @param filter - Keeps only the layers that match every key given
+     */
+    list(filter?: LayerFilter): Layer[];
+    /**
+     * Counts the layers.
+     *
+     * @param filter - Counts only the layers that match every key given
+     */
+    count(filter?: LayerFilter): number;
+    /** Whether a layer with this ID exists. */
+    has(id: string): boolean;
+    /**
+     * Creates a layer and returns it as it was stored.
+     *
+     * @returns The new layer, or `null` when the document is read-only
+     * @throws `DrawError` with the code `invalid-input` when the input has the wrong shape, or
+     *   `already-exists` when its ID is taken
+     */
+    create(input: LayerInput): Layer | null;
+    /**
+     * Creates several layers in one transaction: all of them or none.
+     *
+     * @returns The new layers in the order of the inputs, or `null` when the document is
+     *   read-only
+     * @throws `DrawError` as {@link LayersCollection.create} does, for any of the inputs;
+     *   nothing is created then
+     */
+    createMany(inputs: readonly LayerInput[]): Layer[] | null;
+    /**
+     * Changes the keys given in the patch and returns the layer after the change.
+     *
+     * @returns The changed layer, or `null` when the change is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when there is no layer with this ID, or
+     *   `invalid-input` when the patch has the wrong shape
+     */
+    update(id: string, patch: LayerPatch): Layer | null;
+    /**
+     * Changes several layers in one transaction: all of them or none.
+     *
+     * @returns The changed layers in the order of the patches, or `null` when the change is
+     *   refused
+     * @throws `DrawError` as {@link LayersCollection.update} does, for any of the patches;
+     *   nothing changes then
+     */
+    updateMany(patches: readonly {
+        id: string;
+        patch: LayerPatch;
+    }[]): Layer[] | null;
+    /**
+     * Deletes a layer with its features and groups.
+     *
+     * @returns True when it was deleted, false when the deletion is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when there is no layer with this ID
+     */
+    delete(id: string): boolean;
+    /**
+     * Deletes several layers in one transaction: all of them or none.
+     *
+     * @returns True when they were deleted, false when the deletion is refused
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist; nothing
+     *   is deleted then
+     */
+    deleteMany(ids: readonly string[]): boolean;
+    /**
+     * Changes the stacking order.
+     *
+     * Besides the layers, the order may place the datasets whose order is `layer-order` and the
+     * entries the `isExternalEntry` option recognizes. An entry of the stacking order that is
+     * not a layer and is left out of `order` keeps its position; the entries given fill the
+     * other positions in the order given, and those new to the stacking order go to the front.
+     *
+     * @param order - The IDs of every layer, and of the other entries to place, from the back
+     * @returns True when the order changed, false when the change is refused (read-only)
+     * @throws `DrawError` with the code `invalid-input` when the IDs do not list every layer
+     *   or list an ID twice, or `not-found` when one of them is not a layer, a `layer-order`
+     *   dataset or an entry the `isExternalEntry` option recognizes
+     */
+    reorder(order: readonly string[]): boolean;
+    /**
+     * The stacking order as {@link LayersCollection.reorder} takes it: the IDs of every layer and
+     * of the other entries placed on it (the datasets whose order is `layer-order` and the
+     * entries the `isExternalEntry` option recognizes), from the back. An entry that is no longer
+     * one of those is left out, so the array can be changed and given to `reorder` as it is.
+     *
+     * @returns A frozen array of IDs
+     */
+    getOrder(): readonly string[];
+    /**
+     * The layer that drawn features go into.
+     *
+     * @returns The active layer, or `null` when there is no layer
+     */
+    getActive(): Layer | null;
+    /**
+     * Changes the layer that drawn features go into.
+     *
+     * @returns True when it changed, false when the layer cannot take drawn features (a lock)
+     * @throws `DrawError` with the code `not-found` when there is no layer with this ID
+     */
+    setActive(id: string): boolean;
+}

package/dist/api/layers.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

package/dist/api/metadata.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `draw.metadata`: the title and the description of the document
+ */
+import type { Metadata } from './model.js';
+/**
+ * The title and the description of the document.
+ */
+export interface MetadataResource {
+    /** The title and the description. */
+    get(): Metadata;
+    /**
+     * Changes the fields given and returns the metadata after the change.
+     *
+     * @returns The changed metadata, or `null` when the document is read-only
+     * @throws `DrawError` with the code `invalid-input` when a field has the wrong type
+     */
+    update(patch: Partial<Metadata>): Metadata | null;
+}

package/dist/api/metadata.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};