@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/store/store.d.ts

@@ -3,86 +3,54 @@
  *
  * All of the state lives in one place (Single Source of Truth), split along one line:
  *
- *   - DocumentStore: the document (features, layers, groups, the stacking order, files and
- *     metadata). It is the part a host may replace (`Options.store`) to keep the document
- *     elsewhere, and it knows nothing about the user interface.
- *   - UiState: the local state of this client (selection, editing, tentative geometry, box
- *     selection, drag, vertex selection, mode, read-only, interaction lock, local
- *     visibility). core owns it; it is never part of the document.
+ *   - StoreContract: the document (features, layers, groups, the stacking order, files and
+ *     metadata) and the state of this client that the public `Store` holds (selection,
+ *     editing, vertex selection, mode, read-only, interaction lock, local visibility). It is
+ *     what a host may replace (`Options.store`), and core reads and writes it only through the
+ *     methods of the public `Store`.
+ *   - The state only the drawing reads (the geometry being drawn, the box selection, the drag,
+ *     the vertices that follow along). core owns it around whatever holds the rest.
  *
- * Store joins the two for core: it reads and writes the document through the DocumentStore,
- * holds the UiState, gates the writes while read-only, keeps the UiState in step with
- * deletions, and delivers both kinds of change in one notification. StoreView is the part of
+ * Store joins the two for core: it reads and writes the contract, holds the drawing state,
+ * gates the writes while read-only, keeps the state of this client in step with deletions,
+ * and delivers every change of a transaction in one notification. StoreView is the part of
  * it the host sees (`draw.getStore()`): reads, subscription and transactions, no writes.
+ *
+ * DocumentStore is the document half the in-memory contract store is built on.
  */
-import type { BoxSelection, DragState, Feature, FileData, Group, Layer, Metadata, Mode, Selection, SelectionType, StateChanges, TentativeState, UpdateFeatureOptions, UpdateSource, VertexSelection } from './types.js';
+import type { Store as PublicStore } from '../api/extension/store.js';
+import type { BoxSelection, DragState, Feature, FileData, Group, Layer, Metadata, Mode, Selection, SelectionType, StoreChange, TentativeState, UpdateFeatureOptions, UpdateSource, VertexSelection } from './types.js';
 /**
- * The document: the part of the state a host may replace to keep it elsewhere
- *
- * The state of a draw instance is split along one line:
- *
- * | Type | What it is |
- * | --- | --- |
- * | `DocumentStore` | The document: features, layers, groups, the stacking order, files and metadata |
- * | {@link UiState} | The local state of this instance, never part of the document |
- * | {@link Store} | Both behind the read-only gate, for core and plugins |
- * | {@link StoreView} | Reads, `subscribe` and `transact`, from `draw.getStore()` |
- * | {@link MemoryStore} | The in-memory `Store`, the default |
- *
- * A host that keeps the document elsewhere (a database, for example) implements this
- * interface and passes it as the `store` option. Core keeps the
- * local state (the selection, the features being edited, the geometry being drawn, the box
- * selection, the drag, the vertex selection, the mode, read-only, the interaction lock and
- * local visibility) around it. An implementation keeps the following contract.
- *
- * Containment: every feature is listed in exactly one container, in `group.featureIds` of its
- * group when it has `groupId`, otherwise in `layer.order` of its layer. An implementation
- * keeps it on every mutation, so that no stored feature is left out of drawing, hit testing
- * and ordered export.
+ * The Store a host gives with the `store` option: the public `Store`, with the rules core
+ * relies on
  *
- * The stacking order: `getLayerOrder()` is part of the document, saved and held with
- * the rest, and it holds more than layers. An application can place entries of its own in
- * it (the id of a dataset with `order: 'layer-order'`, a separator for
- * the `isExternalEntry` option); what such an entry means is the application's, and the
- * document only keeps its position. The entries are distinct non-empty strings: an
- * implementation drops any other value and keeps a repeated entry at its first position.
- * `createLayer` appends the new layer at the front unless the order already holds its id,
- * and `deleteLayer` takes that layer's id out. No other operation adds or removes entries;
- * an entry that is not a layer stays until the application sets an order without it, even
- * when what it names is gone. A layer that is not on the order is not drawn.
+ * Core programs against the members of the public `Store` only: every read and every write it
+ * makes, the writes of the state of this client included, goes through them. It adds nothing
+ * to them; the state only the drawing reads (the geometry being drawn, the box selection, the
+ * drag, the vertices that follow along) stays with core. The rules an implementation keeps are
+ * written on the public `Store` and `StoreView` (`src/api/extension/store.ts`).
+ */
+export interface StoreContract extends PublicStore {
+}
+/**
+ * The document, in memory: the half the in-memory {@link StoreContract} is built on
  *
- * Returned objects: callers treat every object and array a getter returns as read-only.
- * An implementation must not change an object after it has returned or notified it; a
- * change stores a new object instead (MemoryStore freezes what it returns, so a write
- * into it throws).
+ * An implementation keeps the containment, the stacking order and the returned objects as
+ * {@link StoreContract} describes them.
  *
  * Errors: a write with an argument that cannot apply (an id that does not exist, a
  * `layerId` or `groupId` that names nothing, a duplicate id) throws and stores nothing.
- * Read-only is not the document's concern: core gates the writes before they get here, and
- * changes applied from elsewhere never pass that gate. An implementation
- * that receives changes from elsewhere may ignore, instead of throwing, an update to an
- * id that such a change has already removed (the caller cannot know about the removal
- * yet); the notification then carries nothing for that id.
+ * Read-only is not the document's concern: core gates the writes before they get here.
  *
- * Notifications: `subscribe` delivers the document categories of StateChanges (features,
- * layers, groups, layerReorder, groupReorder, metadata) with their source, and `transact`
- * groups the changes of a function into one notification. Any other category a notification
- * carries is ignored by core. A change applied from elsewhere is notified like a local one,
- * with the source `'remote'`, and core follows it: a deleted item leaves the selection, the
- * vertex selection ends when its feature changed, and the hooks of the plugins fire.
- *
- * @example
- * ```ts
- * // A document kept elsewhere: wrap it in a DocumentStore and hand it to the draw instance
- * const document: DocumentStore = createSyncedDocument(roomId);
- * const draw = createMapLibreGLDraw(map, { store: document });
- * ```
+ * Notifications: `subscribe` delivers the document categories of StoreChange (features,
+ * layers, groups, layerReorder, groupReorder, metadata, files) with their source, and
+ * `transact` groups the changes of a function into one notification.
  */
 export interface DocumentStore {
     /** Returns the feature with this ID, or undefined */
     getFeature(id: string): Feature | undefined;
     /** Every feature, in no particular order */
-    getAllFeatures(): Feature[];
+    listFeatures(): Feature[];
     /**
      * Creates a feature and lists it in its container
      *
@@ -123,17 +91,18 @@ export interface DocumentStore {
      */
     deleteFeature(id: string): void;
     /**
-     * Gets the array of features in display order
+     * Every feature in stacking order
      *
      * Iterates in layer order -> order within the layer -> featureIds order within the
-     * group, skipping what the shared visible flag hides at any of the three levels.
-     * The head of the array is the backmost and the end is the foreground.
+     * group, whatever the visible flags say. A layer that is not on the stacking order is not
+     * drawn, and its features are not listed. The head of the array is the backmost and the
+     * end is the foreground.
      */
-    getOrderedFeatures(): Feature[];
+    listFeaturesInOrder(): Feature[];
     /** Returns the layer with this ID, or undefined */
     getLayer(id: string): Layer | undefined;
     /** Every layer, in no particular order */
-    getAllLayers(): Layer[];
+    listLayers(): Layer[];
     /**
      * Creates a layer and appends it to the stacking order (as the frontmost entry), unless the
      * order already holds its id, which then keeps its position
@@ -164,7 +133,7 @@ export interface DocumentStore {
     /** Returns the group with this ID, or undefined */
     getGroup(id: string): Group | undefined;
     /** Every group, in no particular order */
-    getAllGroups(): Group[];
+    listGroups(): Group[];
     /**
      * Creates a group and sets `groupId` on its existing members, which leave the order of
      * their layer. A group that no layer lists by the end of the operation takes the place of
@@ -183,7 +152,7 @@ export interface DocumentStore {
     /** Returns the file with this ID, or undefined */
     getFile(id: string): FileData | undefined;
     /** Every file */
-    getAllFiles(): FileData[];
+    listFiles(): FileData[];
     /** Deletes a file (the features that refer to it are not changed) */
     deleteFile(id: string): void;
     /** Returns the metadata of the document */
@@ -195,9 +164,9 @@ export interface DocumentStore {
      *
      * @returns The unsubscribe function
      */
-    subscribe(listener: (changes: StateChanges) => void): () => void;
+    subscribe(listener: (changes: StoreChange) => void): () => void;
     /**
-     * Runs fn and notifies its changes together as a single StateChanges
+     * Runs fn and notifies its changes together as a single StoreChange
      *
      * Not atomic: when fn throws, the writes made before the throw stay applied, they are
      * notified, and the exception is rethrown.
@@ -208,11 +177,14 @@ export interface DocumentStore {
     transact<T>(fn: () => T, source?: UpdateSource): T;
 }
 /**
- * The local state of this instance: never part of the document, owned by core
+ * The local state of this instance as core reads and writes it: never part of the document
  *
- * Core keeps it for every draw instance, whatever {@link DocumentStore} holds the document.
- * The host reads it through {@link StoreView} and changes it through the methods of the draw
- * instance (`setMode`, `setSelection`, `setReadOnly` and so on).
+ * The state of this client the public contract names (selection, editing, vertex selection,
+ * mode, read-only, interaction lock, local visibility) is kept by the {@link StoreContract};
+ * the drawing state (the geometry being drawn, the box selection, the drag, the vertices that
+ * follow along) is kept by core. The host reads it through {@link StoreView} and changes it
+ * through the methods of the draw instance (`setMode`, `setSelection`, `setReadOnly` and so
+ * on).
  */
 export interface UiState {
     /** Returns the current selection */
@@ -238,7 +210,7 @@ export interface UiState {
     /** Sets or clears the drag in progress */
     setDragState(state: DragState | null): void;
     /** The selected vertices, or null when no vertex is selected */
-    getSelectedVertices(): VertexSelection | null;
+    getVertexSelection(): VertexSelection | null;
     /** Sets or clears the selected vertices */
     setSelectedVertices(selection: VertexSelection | null): void;
     /**
@@ -268,9 +240,9 @@ export interface UiState {
     /** Turns the interaction lock on or off */
     setInteractionLock(value: boolean): void;
     /** Local visibility: the ids (feature / group / layer) hidden on this client only */
-    isLocallyHidden(id: string): boolean;
+    isHidden(id: string): boolean;
     /** Every ID hidden on this client only */
-    getLocallyHidden(): ReadonlySet<string>;
+    listHidden(): ReadonlySet<string>;
     /** Hides or shows a feature, a group or a layer on this client only */
     setLocallyHidden(id: string, hidden: boolean): void;
 }
@@ -281,41 +253,28 @@ export interface UiState {
  * Writes go through the methods of the draw instance (or, in a plugin, the PluginContext),
  * so a host cannot reach past the checks those methods make. `transact` groups the writes
  * made through them into one notification.
- *
- * @example
- * ```ts
- * const store = draw.getStore();
- * const unsubscribe = store.subscribe((changes) => {
- *   if (changes.features) saveLater(store.getAllFeatures());
- * });
- * // Two writes, one notification
- * store.transact(() => {
- *   draw.updateFeature(a, { visible: false });
- *   draw.updateFeature(b, { visible: false });
- * });
- * ```
  */
 export interface StoreView {
     /** Returns the feature with this ID, or undefined */
     getFeature(id: string): Feature | undefined;
     /** Every feature, in no particular order */
-    getAllFeatures(): Feature[];
-    /** The visible features in drawing order, back to front */
-    getOrderedFeatures(): Feature[];
+    listFeatures(): Feature[];
+    /** Every feature in stacking order, back to front, whatever the visible flags say */
+    listFeaturesInOrder(): Feature[];
     /** Returns the layer with this ID, or undefined */
     getLayer(id: string): Layer | undefined;
     /** Every layer, in no particular order */
-    getAllLayers(): Layer[];
+    listLayers(): Layer[];
     /** The stacking order of the layers, back to front */
     getLayerOrder(): readonly string[];
     /** Returns the group with this ID, or undefined */
     getGroup(id: string): Group | undefined;
     /** Every group, in no particular order */
-    getAllGroups(): Group[];
+    listGroups(): Group[];
     /** Returns the file with this ID, or undefined */
     getFile(id: string): FileData | undefined;
     /** Every file */
-    getAllFiles(): FileData[];
+    listFiles(): FileData[];
     /** Returns the metadata of the document */
     getMetadata(): Metadata;
     /** Returns the current selection */
@@ -329,7 +288,7 @@ export interface StoreView {
     /** The drag in progress, or null */
     getDragState(): DragState | null;
     /** The selected vertices, or null when no vertex is selected */
-    getSelectedVertices(): VertexSelection | null;
+    getVertexSelection(): VertexSelection | null;
     /**
      * The vertices that follow along when shared vertices move together (null except during a
      * drag)
@@ -342,9 +301,9 @@ export interface StoreView {
     /** Whether the interaction lock is on */
     isInteractionLocked(): boolean;
     /** Whether this feature, group or layer is hidden on this client only */
-    isLocallyHidden(id: string): boolean;
+    isHidden(id: string): boolean;
     /** Every ID hidden on this client only */
-    getLocallyHidden(): ReadonlySet<string>;
+    listHidden(): ReadonlySet<string>;
     /**
      * Subscribes to the changes of the document and of the local state
      *
@@ -353,9 +312,9 @@ export interface StoreView {
      *
      * @returns The unsubscribe function
      */
-    subscribe(listener: (changes: StateChanges) => void): () => void;
+    subscribe(listener: (changes: StoreChange) => void): () => void;
     /**
-     * Runs fn and notifies every change it makes as a single StateChanges
+     * Runs fn and notifies every change it makes as a single StoreChange
      *
      * Not atomic: when fn throws, the writes made before the throw stay applied, they are
      * notified, and the exception is rethrown.
@@ -370,7 +329,7 @@ export interface StoreView {
  *
  * Every document write returns true when it was applied and false when it was refused
  * because the Store is read-only (it never throws for that). An argument that cannot apply
- * throws, as in DocumentStore. When a feature, group or layer is deleted (by a write here or
+ * may throw, as in {@link StoreContract}. When a feature, group or layer is deleted (by a write here or
  * by a change applied to the document from elsewhere), its id leaves the selection, the
  * features being edited and the locally hidden set in the same notification. A change that
  * hides a selected item (its visible flag, the one of its group or layer, or local hiding)
@@ -379,7 +338,7 @@ export interface StoreView {
  * document and of the local state of one transaction.
  *
  * A plugin reaches it with `getStore()` of {@link PluginContext}; the host gets the read-only
- * {@link StoreView}. The write methods behave as those of {@link DocumentStore}.
+ * {@link StoreView}. The write methods behave as those of {@link StoreContract}.
  */
 export interface Store extends StoreView, UiState {
     /** Creates a feature (see {@link DocumentStore.createFeature}) */

package/dist/store/types.d.ts

@@ -2,7 +2,7 @@
  * The data model of the Store
  *
  * The types are defined in shared/types/model.ts, below every layer, so that shared/ and
- * display/ can use them without depending on store/. This file re-exports them for the code
+ * dataset/ can use them without depending on store/. This file re-exports them for the code
  * that already imports them from here.
  */
 export type * from '../shared/types/model.js';

package/dist/store/writable-layer.d.ts

@@ -19,7 +19,7 @@ export type WritableLayerCheckStore = LocalHiddenStore;
 /** The minimal interface that resolveWritableLayerId requires. */
 export interface WritableLayerStore extends WritableLayerCheckStore {
     getLayer(id: string): Layer | undefined;
-    getAllLayers(): Layer[];
+    listLayers(): Layer[];
 }
 /**
  * Whether user drawing may write new features into the layer

package/dist/store/writable-layer.js

@@ -4,7 +4,7 @@
  * Whether user drawing may write new features into the layer
  */
 export function isWritableLayer(layer, store) {
-    return layer !== undefined && !layer.locked && layer.visible && !store.isLocallyHidden(layer.id);
+    return layer !== undefined && !layer.locked && layer.visible && !store.isHidden(layer.id);
 }
 /**
  * Resolves the layer that user drawing writes new features into
@@ -16,5 +16,5 @@ export function isWritableLayer(layer, store) {
 export function resolveWritableLayerId(store, preferredId) {
     if (isWritableLayer(store.getLayer(preferredId), store))
         return preferredId;
-    return store.getAllLayers().find((layer) => isWritableLayer(layer, store))?.id ?? '';
+    return store.listLayers().find((layer) => isWritableLayer(layer, store))?.id ?? '';
 }

package/dist/table/builder.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The building of a table from GeoJSON, row by row
+ *
+ * The builder collects the coordinates into growing typed arrays and the offsets in the layout
+ * of GeoArrow, one geometry column per geometry type. At the end the columns become the geometry
+ * of the table: the one column when every row has the same type, or a mixed geometry column
+ * otherwise. The attributes are collected per property name and become typed columns where they
+ * can.
+ *
+ * A pure module (it imports only types), so it runs in a Worker as well.
+ */
+import type { Feature, Geometry } from 'geojson';
+import type { GeometryType, Table } from './types.js';
+/**
+ * Builds a table one row at a time, for readers that stream their rows.
+ *
+ * Create one with {@link createTableBuilder}, call `add` once per row and `finish` once at the
+ * end.
+ */
+export interface TableBuilder {
+    /**
+     * Adds one row.
+     *
+     * A null geometry, or a `GeometryCollection` (which a table cannot hold), gives a row without
+     * a geometry: it keeps its place and its attributes but is neither drawn nor hit.
+     *
+     * @param geometry The GeoJSON geometry of the row; only the first two values of each position
+     *   are kept
+     * @param properties The attributes of the row
+     * @param id The id of the row. Once any row has an id, the rows without one get their row
+     *   number
+     * @throws when the builder was created with a `geometryType` and the geometry has another
+     *   type, or when `finish` was already called
+     */
+    add(geometry: Geometry | null, properties?: Record<string, unknown> | null, id?: string | number): void;
+    /**
+     * Turns the rows added so far into a table; the builder cannot be used afterwards.
+     *
+     * @throws when it was already called
+     */
+    finish(): Table;
+}
+/**
+ * Creates a builder that makes a table from rows added one at a time.
+ *
+ * The coordinates are collected into growing typed arrays in the layout of GeoArrow. When every
+ * row has the same geometry type the table has one geometry column of that type; otherwise it
+ * has a mixed geometry column. An attribute whose values are all numbers (or null) becomes a
+ * `Float64Array` with NaN for null; any other attribute becomes a plain array.
+ *
+ * @param options `geometryType` fixes the geometry type of every row (a geometry of another
+ *   type throws), and gives the type of a table without any geometry. `capacity` is the
+ *   expected number of rows, to size the arrays from the start. `columns` limits the attributes
+ *   that become columns to these names (every one is created, even if no row has it)
+ * @returns A new builder
+ */
+export declare function createTableBuilder(options?: {
+    geometryType?: GeometryType;
+    capacity?: number;
+    columns?: readonly string[];
+}): TableBuilder;
+/**
+ * Makes a table from an array of GeoJSON features.
+ *
+ * It is {@link createTableBuilder} with one `add` per feature: the geometry, the properties and
+ * the id of each feature become a row. Rows of different geometry types give a mixed geometry
+ * column.
+ *
+ * @param features The features, in row order
+ * @param options `columns` limits the properties that become columns to these names
+ * @returns The table
+ *
+ * @example
+ * ```ts
+ * import { tableFromFeatures } from '@sakuzu/maplibre-gl-draw/table';
+ *
+ * const table = tableFromFeatures(collection.features, { columns: ['name', 'visitors'] });
+ * draw.datasets.add({ id: 'places', table });
+ * ```
+ */
+export declare function tableFromFeatures(features: readonly Feature<Geometry | null>[], options?: {
+    columns?: readonly string[];
+}): Table;