@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/features.d.ts

@@ -0,0 +1,188 @@
+/**
+ * `draw.features`: the features of the document
+ */
+import type { Feature, FeatureFilter, FeatureInput, FeaturePatch, FeatureStyleResolved, MoveTarget } from './model.js';
+/**
+ * The features of the document, with the standard methods of a collection and the verbs
+ * that move, combine and split them.
+ *
+ * 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 FeaturesCollection {
+    /**
+     * Gets a feature by ID.
+     *
+     * @returns The feature, or `undefined` when there is none with this ID
+     */
+    get(id: string): Feature | undefined;
+    /**
+     * Gets features by ID, in the order of the IDs.
+     *
+     * @returns One entry per ID: the feature, or `undefined` when there is none with that ID
+     */
+    getMany(ids: readonly string[]): (Feature | undefined)[];
+    /**
+     * Lists the features in stacking order, from the back.
+     *
+     * @param filter - Keeps only the features that match every key given
+     */
+    list(filter?: FeatureFilter): Feature[];
+    /**
+     * Counts the features.
+     *
+     * @param filter - Counts only the features that match every key given
+     */
+    count(filter?: FeatureFilter): number;
+    /** Whether a feature with this ID exists. */
+    has(id: string): boolean;
+    /**
+     * Whether the feature can be edited now: the document is not read-only, and neither the
+     * feature nor its group nor its layer is locked. A refused edit returns `null` or `false`
+     * for the same reasons.
+     *
+     * @throws `DrawError` with the code `not-found` when there is no feature with this ID
+     */
+    isEditable(id: string): boolean;
+    /**
+     * Creates a feature and returns it as it was stored.
+     *
+     * @returns The new feature, or `null` when the document is read-only
+     * @throws `DrawError` with the code `invalid-input` when the input has the wrong shape,
+     *   `already-exists` when its ID is taken, `not-found` when its layer or group does not
+     *   exist, or `invalid-state` when the input names no layer and the document has no layer
+     *   to put it in
+     */
+    create(input: FeatureInput): Feature | null;
+    /**
+     * Creates several features in one transaction: all of them or none.
+     *
+     * @returns The new features in the order of the inputs, or `null` when the document is
+     *   read-only
+     * @throws `DrawError` as {@link FeaturesCollection.create} does, for any of the inputs;
+     *   nothing is created then
+     */
+    createMany(inputs: readonly FeatureInput[]): Feature[] | null;
+    /**
+     * Changes the keys given in the patch and returns the feature after the change.
+     *
+     * `properties` and `style` are merged key by key, and a key given as `undefined` is
+     * removed.
+     *
+     * @returns The changed feature, or `null` when the change is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when there is no feature with this ID, or
+     *   `invalid-input` when the patch has the wrong shape
+     */
+    update(id: string, patch: FeaturePatch): Feature | null;
+    /**
+     * Changes several features in one transaction: all of them or none.
+     *
+     * @returns The changed features in the order of the patches, or `null` when the change is
+     *   refused
+     * @throws `DrawError` as {@link FeaturesCollection.update} does, for any of the patches;
+     *   nothing changes then
+     */
+    updateMany(patches: readonly {
+        id: string;
+        patch: FeaturePatch;
+    }[]): Feature[] | null;
+    /**
+     * Deletes a feature.
+     *
+     * @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 feature with this ID
+     */
+    delete(id: string): boolean;
+    /**
+     * Deletes several features 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;
+    /**
+     * Moves a feature to another layer, into a group or out of its group; `index` of the
+     * target sets its position there.
+     *
+     * @returns True when it moved, false when the move is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when the feature or the target does not
+     *   exist
+     */
+    move(id: string, to: MoveTarget): boolean;
+    /**
+     * Moves several features in one transaction, keeping their order: all of them or none.
+     *
+     * @returns True when they moved, false when the move is refused
+     * @throws `DrawError` with the code `not-found` when one of the features or the target does
+     *   not exist; nothing moves then
+     */
+    moveMany(ids: readonly string[], to: MoveTarget): boolean;
+    /**
+     * The look a feature is drawn with: the default, the layer rule and the style of the
+     * feature put on top of each other.
+     *
+     * The colors of the `style` option and of the style of the feature are the strings they
+     * were given, alpha included; the color of a layer rule is `#rrggbb`, as
+     * {@link evaluateStyleRule} gives it, and a default is `#rrggbb`.
+     *
+     * @returns The look, or `undefined` when there is no feature with this ID
+     */
+    getAppliedStyle(id: string): FeatureStyleResolved | undefined;
+    /**
+     * Joins areas into one feature and returns it; the result replaces the features given.
+     *
+     * @returns The new feature, or `null` when the operation is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist, or
+     *   `invalid-input` when fewer than two areas are given or one of the features is not an
+     *   area
+     */
+    union(ids: readonly string[]): Feature | null;
+    /**
+     * Subtracts other areas from an area and returns the result; the result replaces the area
+     * subtracted from, and the areas subtracted stay.
+     *
+     * @param id - The area to subtract from
+     * @param subtractIds - The areas to subtract
+     * @returns The resulting feature, or `null` when the operation is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist, or
+     *   `invalid-input` when one of the features is not an area
+     */
+    difference(id: string, subtractIds: readonly string[]): Feature | null;
+    /**
+     * Keeps the part where areas overlap and returns it; the result replaces the features given.
+     *
+     * @returns The resulting feature, or `null` when the operation is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist, or
+     *   `invalid-input` when fewer than two areas are given or one of the features is not an
+     *   area
+     */
+    intersection(ids: readonly string[]): Feature | null;
+    /**
+     * Splits an area along a line and returns the features it made.
+     *
+     * @param id - The area to split
+     * @param lineId - The line to split along
+     * @returns The new features, or `null` when the operation is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist, or
+     *   `invalid-input` when the features are not an area and a line
+     */
+    split(id: string, lineId: string): Feature[] | null;
+    /**
+     * Creates the areas around features.
+     *
+     * @param ids - The features to surround
+     * @param options - `distanceMeters` is the distance of the outline from the features, and
+     *   `segments` the number of segments of a full circle, as in the buffer of the geometry
+     *   entry
+     * @returns The new features, or `null` when the operation is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when one of the IDs does not exist, or
+     *   `invalid-input` when the distance is not a finite number
+     */
+    buffer(ids: readonly string[], options: {
+        distanceMeters: number;
+        segments?: number;
+    }): Feature[] | null;
+}

package/dist/api/features.js

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

package/dist/api/groups.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `draw.groups`: the groups of the document
+ */
+import type { Group, GroupFilter, GroupInput, GroupPatch, MoveTarget } from './model.js';
+/**
+ * The groups of the document, with the standard methods of a collection and the verbs that
+ * move them.
+ *
+ * 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 GroupsCollection {
+    /**
+     * Gets a group by ID.
+     *
+     * @returns The group, or `undefined` when there is none with this ID
+     */
+    get(id: string): Group | undefined;
+    /**
+     * Gets groups by ID, in the order of the IDs.
+     *
+     * @returns One entry per ID: the group, or `undefined` when there is none with that ID
+     */
+    getMany(ids: readonly string[]): (Group | undefined)[];
+    /**
+     * Lists the groups in stacking order, from the back.
+     *
+     * @param filter - Keeps only the groups that match every key given
+     */
+    list(filter?: GroupFilter): Group[];
+    /**
+     * Counts the groups.
+     *
+     * @param filter - Counts only the groups that match every key given
+     */
+    count(filter?: GroupFilter): number;
+    /** Whether a group with this ID exists. */
+    has(id: string): boolean;
+    /**
+     * Creates a group of features and returns it as it was stored.
+     *
+     * @returns The new group, or `null` when the document is read-only
+     * @throws `DrawError` with the code `not-found` when one of the features does not exist,
+     *   `invalid-input` when the features are not in the same layer, or `already-exists` when
+     *   its ID is taken
+     */
+    create(input: GroupInput): Group | null;
+    /**
+     * Creates several groups in one transaction: all of them or none.
+     *
+     * @returns The new groups in the order of the inputs, or `null` when the document is
+     *   read-only
+     * @throws `DrawError` as {@link GroupsCollection.create} does, for any of the inputs;
+     *   nothing is created then
+     */
+    createMany(inputs: readonly GroupInput[]): Group[] | null;
+    /**
+     * Changes the keys given in the patch and returns the group after the change.
+     *
+     * @returns The changed group, or `null` when the change is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when there is no group with this ID, or
+     *   `invalid-input` when the patch has the wrong shape
+     */
+    update(id: string, patch: GroupPatch): Group | null;
+    /**
+     * Changes several groups in one transaction: all of them or none.
+     *
+     * @returns The changed groups in the order of the patches, or `null` when the change is
+     *   refused
+     * @throws `DrawError` as {@link GroupsCollection.update} does, for any of the patches;
+     *   nothing changes then
+     */
+    updateMany(patches: readonly {
+        id: string;
+        patch: GroupPatch;
+    }[]): Group[] | null;
+    /**
+     * Deletes a group; its features stay in the layer.
+     *
+     * @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 group with this ID
+     */
+    delete(id: string): boolean;
+    /**
+     * Deletes several groups in one transaction: all of them or none. Their features stay in
+     * their layers.
+     *
+     * @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;
+    /**
+     * Moves a group to another layer, or to another position in its layer.
+     *
+     * @returns True when it moved, false when the move is refused (read-only, a lock)
+     * @throws `DrawError` with the code `not-found` when the group or the target does not
+     *   exist, or `invalid-input` when the target is a group
+     */
+    move(id: string, to: MoveTarget): boolean;
+    /**
+     * Moves several groups in one transaction: all of them or none.
+     *
+     * @returns True when they moved, false when the move is refused
+     * @throws `DrawError` as {@link GroupsCollection.move} does, for any of the groups; nothing
+     *   moves then
+     */
+    moveMany(ids: readonly string[], to: MoveTarget): boolean;
+}

package/dist/api/groups.js

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

package/dist/api/hidden.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `draw.hidden`: what this client hides without changing the document
+ */
+/**
+ * The IDs of the features, groups and layers this client hides. Hiding changes only what this
+ * client draws; the document and its `visible` flags stay as they are.
+ */
+export interface HiddenCollection {
+    /** Whether this client hides the item with this ID. */
+    get(id: string): boolean;
+    /** Lists the IDs this client hides. */
+    list(): readonly string[];
+    /** Counts the IDs this client hides. */
+    count(): number;
+    /** Whether this client hides the item with this ID; the same as {@link HiddenCollection.get}. */
+    has(id: string): boolean;
+    /**
+     * Hides a feature, a group or a layer in this client only; the document does not change.
+     *
+     * @throws `DrawError` with the code `not-found` when the ID is not a feature, a group or a
+     *   layer of the document
+     */
+    add(id: string): void;
+    /**
+     * Hides several items in this client only, all of them or none.
+     *
+     * @throws `DrawError` with the code `not-found` when one of the IDs is not in the document;
+     *   nothing is hidden then
+     */
+    addMany(ids: readonly string[]): void;
+    /**
+     * Shows an item this client hid.
+     *
+     * @returns False when this client did not hide it
+     */
+    remove(id: string): boolean;
+    /**
+     * Shows several items this client hid, all at once.
+     *
+     * @returns False when this client hid none of them
+     */
+    removeMany(ids: readonly string[]): boolean;
+    /** Shows every item this client hid. */
+    clear(): void;
+}

package/dist/api/hidden.js

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