@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/README.ja.md

@@ -93,12 +93,15 @@ GeoParquet や Arrow の表は、点、線、多角形が行ごとに混ざっ
 決められ、クリックすると属性を読めます
 ([大量のデータ](docs/guides/large-data.ja.md))。
 
-### 書き出しと読み込み
-
-独自形式で書き出すと、レイヤー、グループ、スタイル、画像まで含めて
-保存でき、読み込めば同じ状態に戻ります。GeoJSON で書き出せば、ほかの
-ツールと地物をやり取りできます。地物を保存するストアは差し替えられ、
-変更はすべてイベントで通知されます
+### 保存と読み込み
+
+文書を独自形式で書き出すと、レイヤー、グループ、スタイル、画像まで
+含めて保存でき、読み込めば同じ状態に戻ります。GeoJSON で書き出せば、
+ほかのツールと地物をやり取りできます。地物は GeoJSON の図形と
+GeoJSON の properties を持つので、ファイルはコードで読む地物と同じ形に
+なります。
+変更は取引ごとに 1 つのイベントで、出どころを添えて届きます。文書を
+保存するストアは差し替えられます
 ([保存と読み込み](docs/guides/save-load.ja.md))。
 
 ### 閲覧専用
@@ -108,7 +111,9 @@ GeoParquet や Arrow の表は、点、線、多角形が行ごとに混ざっ
 
 ### 拡張
 
-プラグイン、独自のモード、独自の地物型を足して拡張できます
+プラグイン、独自のモード、独自の描き方を持つ地物の型、重ね描き、
+吸着の候補やハンドルの提供者を足せます。どの種類も同じ方法で足し、
+足したときに返る関数で外します
 ([プラグイン](docs/guides/plugins.ja.md)、
 [独自の型](docs/guides/custom-types.ja.md))。
 
@@ -132,12 +137,12 @@ GeoParquet や Arrow の表は、点、線、多角形が行ごとに混ざっ
 - [閲覧専用][ex-read-only]
   - 閲覧専用モード、操作のロック、ロックしたレイヤー
 - [プラグイン][ex-plugin]
-  - フックと独自のモードを持つプラグイン
+  - イベント、API、独自のモードを持つプラグイン
 - [独自の地物型][ex-custom-feature-type]
-  - 独自のレンダラーと当たり判定を持つ地物型
+  - 独自の描き方、当たり判定、範囲選択を持つ地物の型
 - [データセット][ex-large-data]
   - 5 万のマス目の色分けと、見えている範囲の点の取り寄せ
-- [100 万の点][ex-columnar-worker]
+- [100 万の点][ex-table-worker]
   - Worker で読み込む 100 万の点
 
 ## インストール
@@ -156,7 +161,7 @@ maplibre-gl (`~6.11.1`) を使います。まだ入っていなければ、npm 7
 import * as maplibregl from 'maplibre-gl';
 import 'maplibre-gl/dist/maplibre-gl.css';
 import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
-import { createMapLibreGLDraw } from '@sakuzu/maplibre-gl-draw';
+import { createDraw } from '@sakuzu/maplibre-gl-draw';
 
 // maplibre-gl v6 はページごとに 1 回 worker の URL を要する (これは Vite の例)
 maplibregl.setWorkerUrl(workerUrl);
@@ -168,7 +173,7 @@ const map = new maplibregl.Map({
   zoom: 12,
 });
 
-const draw = createMapLibreGLDraw(map);
+const draw = createDraw(map);
 
 // 自分のボタンで描き始める。クリックで頂点を足し、最初の頂点のクリックか
 // Enter で確定する
@@ -176,20 +181,35 @@ document.querySelector('#polygon')?.addEventListener('click', () => {
   draw.setMode('draw_polygon');
 });
 
-draw.on('draw.feature.create', ({ feature }) => {
-  console.log(feature.id, feature.type, feature.coordinates);
+draw.on('feature.created', ({ feature }) => {
+  console.log(feature.id, feature.type, feature.geometry);
 });
 
-// すべての地物を GeoJSON の FeatureCollection (文字列) で得る
+// すべての地物を GeoJSON の FeatureCollection で得る
 document.querySelector('#save')?.addEventListener('click', () => {
-  const { data } = draw.export('geojson');
-  console.log(data);
+  console.log(JSON.stringify(draw.document.toGeoJSON()));
 });
 ```
 
 ページ全体は [examples/basic/](examples/basic/) にあります。
 [はじめかた](docs/getting-started.ja.md) で順を追って説明しています。
 
+## 入口
+
+ほかの入口が要るとき以外は、main の入口から import します。
+
+- `@sakuzu/maplibre-gl-draw` は、描画のインスタンス (`createDraw`)、
+  その地物、レイヤー、グループ、データセット、イベント、設定、拡張の
+  窓口です
+- `@sakuzu/maplibre-gl-draw/geometry` は、地図の要らない図形の計算
+  です。長さや面積を測る、円やバッファーを作る、面を合成して分ける
+  ことができます。Node や Worker でも動きます
+- `@sakuzu/maplibre-gl-draw/table` は、大きな表を Worker で読んで
+  データセットに渡す部品です
+- `@sakuzu/maplibre-gl-draw/webgl` は、独自のシェーダーを書くための
+  部品です。小さい版で変わることがあります。ほかの 3 つはセマンティック
+  バージョニングに従います
+
 ## 動作環境
 
 - maplibre-gl `~6.11.1` で動き、WebGL2 が必要です。
@@ -209,7 +229,7 @@ document.querySelector('#save')?.addEventListener('click', () => {
 ## ドキュメント
 
 [docs/README.ja.md](docs/README.ja.md) に、はじめかた、手引き、
-リファレンス、内部の文書を読む順に並べています。mapbox-gl-draw や
+リファレンス、内部の文書を読む順に並べています。1.0、mapbox-gl-draw、
 terra-draw から移る場合は [移行](docs/guides/migrating.ja.md) を参照して
 ください。
 
@@ -245,4 +265,4 @@ AGPL が製品に合わない場合は、Kasika, Inc. (可視化技研株式会
 [ex-plugin]: https://sakuzu.github.io/maplibre-gl-draw/examples/plugin/
 [ex-custom-feature-type]: https://sakuzu.github.io/maplibre-gl-draw/examples/custom-feature-type/
 [ex-large-data]: https://sakuzu.github.io/maplibre-gl-draw/examples/large-data/
-[ex-columnar-worker]: https://sakuzu.github.io/maplibre-gl-draw/examples/columnar-worker/
+[ex-table-worker]: https://sakuzu.github.io/maplibre-gl-draw/examples/table-worker/

package/README.md

@@ -97,12 +97,15 @@ large file opens. It is styled by the same style rules as drawn
 features, and a click reads its properties
 ([large data](docs/guides/large-data.md)).
 
-### Export and load
-
-Export in the native format to keep layers, groups, styles and images,
-and load it to get the same state back. Export as GeoJSON to exchange
-features with other tools. The store that holds the features can be
-replaced, and every change is reported as an event
+### Save and load
+
+Write the document in the native format to keep layers, groups, styles
+and images, and load it to get the same state back. Write it as GeoJSON
+to exchange features with other tools: a feature holds a GeoJSON
+geometry and GeoJSON properties, so the file has the shape of the
+features you read in code.
+Every change arrives as one event per transaction, with where it came
+from, and the store that holds the document can be replaced
 ([save and load](docs/guides/save-load.md)).
 
 ### Read-only
@@ -112,8 +115,10 @@ drawing ([read-only](docs/guides/read-only.md)).
 
 ### Extending
 
-Extend it with plugins, custom modes and custom feature types
-([plugins](docs/guides/plugins.md),
+Add plugins, modes of your own, feature types with their own drawing,
+overlays, and providers of snapping candidates and handles. Every kind
+is added the same way and removed with the function that adding
+returns ([plugins](docs/guides/plugins.md),
 [custom types](docs/guides/custom-types.md)).
 
 ## Demos
@@ -138,13 +143,13 @@ Try them in the browser, with nothing to install.
 - [Read-only][ex-read-only]
   - The read-only mode, the interaction lock and locked layers
 - [Plugin][ex-plugin]
-  - A plugin with a hook and a mode of its own
+  - A plugin with an event, an API and a mode of its own
 - [Custom feature type][ex-custom-feature-type]
-  - A kind of feature with its own renderer and hit test
+  - A kind of feature with its own drawing, hit test and box selection
 - [Datasets][ex-large-data]
   - 50,000 cells colored by a property, and points fetched for the part
     of the map in view
-- [A million points][ex-columnar-worker]
+- [A million points][ex-table-worker]
   - A million points read in a Worker
 
 ## Installation
@@ -163,7 +168,7 @@ npm 7 and later install it along.
 import * as maplibregl from 'maplibre-gl';
 import 'maplibre-gl/dist/maplibre-gl.css';
 import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
-import { createMapLibreGLDraw } from '@sakuzu/maplibre-gl-draw';
+import { createDraw } from '@sakuzu/maplibre-gl-draw';
 
 // maplibre-gl v6 needs its worker URL once per page (Vite shown here)
 maplibregl.setWorkerUrl(workerUrl);
@@ -175,7 +180,7 @@ const map = new maplibregl.Map({
   zoom: 12,
 });
 
-const draw = createMapLibreGLDraw(map);
+const draw = createDraw(map);
 
 // Your own button starts drawing. Click to add vertices; click the first
 // vertex or press Enter to finish
@@ -183,20 +188,35 @@ document.querySelector('#polygon')?.addEventListener('click', () => {
   draw.setMode('draw_polygon');
 });
 
-draw.on('draw.feature.create', ({ feature }) => {
-  console.log(feature.id, feature.type, feature.coordinates);
+draw.on('feature.created', ({ feature }) => {
+  console.log(feature.id, feature.type, feature.geometry);
 });
 
-// Every feature as a GeoJSON FeatureCollection (a string)
+// Every feature as a GeoJSON FeatureCollection
 document.querySelector('#save')?.addEventListener('click', () => {
-  const { data } = draw.export('geojson');
-  console.log(data);
+  console.log(JSON.stringify(draw.document.toGeoJSON()));
 });
 ```
 
 The complete page is [examples/basic/](examples/basic/), and
 [getting started](docs/getting-started.md) walks through it step by step.
 
+## Entry points
+
+Import from the main entry unless you need one of the others.
+
+- `@sakuzu/maplibre-gl-draw`: the draw instance (`createDraw`), its
+  features, layers, groups and datasets, the events, the options and the
+  extension contract
+- `@sakuzu/maplibre-gl-draw/geometry`: geometry that needs no map:
+  measure lengths and areas, build circles and buffers, combine and split
+  polygons. It also runs in Node and in Workers
+- `@sakuzu/maplibre-gl-draw/table`: read a large table in a Worker and
+  pass it to a dataset
+- `@sakuzu/maplibre-gl-draw/webgl`: the building blocks for writing your
+  own shaders. It may change in a minor release; the other three follow
+  semantic versioning
+
 ## Compatibility
 
 - maplibre-gl `~6.11.1` and WebGL2 are required.
@@ -217,8 +237,8 @@ The complete page is [examples/basic/](examples/basic/), and
 ## Documentation
 
 [docs/README.md](docs/README.md) lists every document in reading order:
-getting started, the guides, the reference and the internals. Coming from
-mapbox-gl-draw or terra-draw? See [migrating](docs/guides/migrating.md).
+getting started, the guides, the reference and the internals. Moving from
+1.0, mapbox-gl-draw or terra-draw? See [migrating](docs/guides/migrating.md).
 
 ## Contributing
 
@@ -252,4 +272,4 @@ The notices of the third-party code this package contains are in
 [ex-plugin]: https://sakuzu.github.io/maplibre-gl-draw/examples/plugin/
 [ex-custom-feature-type]: https://sakuzu.github.io/maplibre-gl-draw/examples/custom-feature-type/
 [ex-large-data]: https://sakuzu.github.io/maplibre-gl-draw/examples/large-data/
-[ex-columnar-worker]: https://sakuzu.github.io/maplibre-gl-draw/examples/columnar-worker/
+[ex-table-worker]: https://sakuzu.github.io/maplibre-gl-draw/examples/table-worker/

package/dist/api/datasets.d.ts

@@ -0,0 +1,258 @@
+/**
+ * `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;
+    /** 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;
+}