@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/{import-export → impl/import-export}/native-format.js

@@ -1,6 +1,11 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Import / export of the native format
+ */
+import { getDrawProperty } from '../../../shared/properties.js';
 import { NATIVE_VERSION } from './constants.js';
+import { upgradeNativeData } from './native-upgrade.js';
 import { validateNativeData } from './native-validation.js';
 /** The layer that survives the replacement (it is updated in place when the data has it) */
 const DEFAULT_LAYER_ID = 'default-layer';
@@ -8,9 +13,9 @@ const DEFAULT_LAYER_ID = 'default-layer';
  * Exports the current data in the native format
  */
 export function exportNative(store, options) {
-    let features = store.getAllFeatures();
-    const layers = store.getAllLayers();
-    const groups = store.getAllGroups();
+    let features = store.listFeatures();
+    const layers = store.listLayers();
+    const groups = store.listGroups();
     if (options?.featureIds && options.featureIds.length > 0) {
         const featureIdSet = new Set(options.featureIds);
         features = features.filter((f) => featureIdSet.has(f.id));
@@ -22,11 +27,12 @@ export function exportNative(store, options) {
     // Get only the files that are in use
     const usedFileIds = new Set();
     for (const feature of features) {
-        if (feature.type === 'Image' && feature.properties.imageFileId) {
-            usedFileIds.add(feature.properties.imageFileId);
+        const imageFileId = getDrawProperty(feature, 'imageFileId');
+        if (feature.type === 'Image' && imageFileId) {
+            usedFileIds.add(imageFileId);
         }
     }
-    const files = store.getAllFiles();
+    const files = store.listFiles();
     const filesRecord = {};
     for (const file of files) {
         if (usedFileIds.has(file.id)) {
@@ -49,9 +55,10 @@ export function exportNative(store, options) {
     };
 }
 /**
- * Imports the native format (replaces the existing data)
+ * Reads the native format for a load that replaces the existing data: everything is checked
+ * here, and the writes are left to the transaction of the caller
  */
-export async function loadNative(data, deps) {
+export async function prepareNative(data, deps) {
     const { store } = deps;
     // Validate before applying. Since store.transact does not roll back, if an exception
     // is thrown on invalid data after the existing data has been cleared, the existing data
@@ -62,23 +69,25 @@ export async function loadNative(data, deps) {
     const retainedLayerIds = new Set();
     if (store.getLayer(DEFAULT_LAYER_ID))
         retainedLayerIds.add(DEFAULT_LAYER_ID);
-    const { layers, layerOrder, groups, features, files } = await validateNativeData(data, retainedLayerIds);
+    // Data of an earlier major version is brought to the current one first
+    const upgraded = upgradeNativeData(data);
+    const { layers, layerOrder, groups, features, files } = await validateNativeData(upgraded, retainedLayerIds);
     const featureIds = features.map((f) => f.id);
     // A kept layer the data does not list goes to the back, where it stays when the data does
     // not mention it (every layer must be on the stacking order to be drawn)
     const retainedUnlisted = [...retainedLayerIds].filter((id) => !layerOrder.includes(id));
-    // Import atomically (silent, so a subscriber that records changes leaves it out)
-    store.transact(() => {
+    // The writes, in the transaction of the caller, which makes them one change
+    const write = () => {
         // 1. Clear the existing data
-        const existingFeatures = store.getAllFeatures();
+        const existingFeatures = store.listFeatures();
         for (const feature of existingFeatures) {
             store.deleteFeature(feature.id);
         }
-        const existingGroups = store.getAllGroups();
+        const existingGroups = store.listGroups();
         for (const group of existingGroups) {
             store.deleteGroup(group.id);
         }
-        const existingLayers = store.getAllLayers();
+        const existingLayers = store.listLayers();
         for (const layer of existingLayers) {
             if (layer.id !== DEFAULT_LAYER_ID) {
                 store.deleteLayer(layer.id);
@@ -86,7 +95,7 @@ export async function loadNative(data, deps) {
         }
         // The files belong to the features that were just removed, and the data brings its own
         // (leaving them would also make a file id of the data collide)
-        for (const file of store.getAllFiles()) {
+        for (const file of store.listFiles()) {
             store.deleteFile(file.id);
         }
         // 2. Import the layers
@@ -114,13 +123,14 @@ export async function loadNative(data, deps) {
         //    nothing of the previous document is left on it
         store.setLayerOrder([...retainedUnlisted, ...layerOrder]);
         // 7. Import the metadata
-        if (data.metadata) {
-            store.setMetadata(data.metadata);
+        if (upgraded.metadata) {
+            store.setMetadata(upgraded.metadata);
         }
-    }, 'silent');
-    return {
-        format: 'native',
-        featureIds,
-        replaced: true,
+        return {
+            format: 'native',
+            featureIds,
+            replaced: true,
+        };
     };
+    return { write };
 }

package/dist/api/impl/import-export/native-upgrade.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Upgrades native data of an earlier major version to the version this library writes
+ *
+ * @param data - the data as it was read
+ * @returns the upgraded data, or the data as it is when it is of the current major version,
+ *   of a version without an upgrade, or not an object
+ */
+export declare function upgradeNativeData(data: unknown): unknown;

package/dist/api/impl/import-export/native-upgrade.js

@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Upgrades native data written by an earlier major version to the current one
+ *
+ * Each step takes data of one major version to the next, and the steps run in a chain until
+ * the data reaches the version this library writes. A step only renames and moves fields; it
+ * checks nothing, and leaves a value it does not understand as it is, so that the validation
+ * that follows reports it. Data of a major version without a step is returned as it is, and
+ * the validation rejects its version.
+ */
+import { DRAW_PROPERTY_NAMES, drawPropertyKey } from '../../../shared/properties.js';
+import { geometryFromCoordinates } from '../../../shared/utils/coordinates.js';
+import { NATIVE_VERSION } from './constants.js';
+import { foldLegacyImageStyle } from './legacy-image-style.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether the object has the key as an own property */
+function hasOwnKey(value, key) {
+    return Object.getOwnPropertyDescriptor(value, key) !== undefined;
+}
+/** The major version of a semantic version, or null when it is not one */
+function majorOf(version) {
+    if (typeof version !== 'string')
+        return null;
+    const match = /^(\d+)\.\d+\.\d+(?:[-+].*)?$/.exec(version);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 2.x to 3.0.0: the document model of the 2.0 API
+ *
+ * - a feature holds a GeoJSON `geometry` instead of `coordinates`
+ * - the values of the library in `properties` get the `maplibre-gl-draw:` prefix
+ * - the `order` of a layer becomes `items`
+ * - the size, the rotation and the opacity in the style of an Image move to the prefixed
+ *   `imageWidth`, `imageHeight` and `rotation` in `properties` and to `imageOpacity`
+ * - a group gets the `layerId` of the layer whose items list it (or of its first member, and
+ *   `''` when it has neither)
+ */
+function upgradeFrom2(data) {
+    const layers = Array.isArray(data.layers)
+        ? data.layers.map((layer) => {
+            if (!isRecord(layer) || !('order' in layer) || 'items' in layer)
+                return layer;
+            const { order, ...rest } = layer;
+            return { ...rest, items: order };
+        })
+        : data.layers;
+    const features = Array.isArray(data.features)
+        ? data.features.map((feature) => isRecord(feature) ? upgradeFeature(feature) : feature)
+        : data.features;
+    const layerOfItem = new Map();
+    if (Array.isArray(layers)) {
+        for (const layer of layers) {
+            if (!isRecord(layer) || typeof layer.id !== 'string' || !Array.isArray(layer.items))
+                continue;
+            for (const item of layer.items) {
+                if (typeof item === 'string' && !layerOfItem.has(item))
+                    layerOfItem.set(item, layer.id);
+            }
+        }
+    }
+    const layerOfFeature = new Map();
+    if (Array.isArray(features)) {
+        for (const feature of features) {
+            if (isRecord(feature) && typeof feature.id === 'string') {
+                if (typeof feature.layerId === 'string')
+                    layerOfFeature.set(feature.id, feature.layerId);
+            }
+        }
+    }
+    const groups = Array.isArray(data.groups)
+        ? data.groups.map((group) => {
+            if (!isRecord(group) || 'layerId' in group || typeof group.id !== 'string')
+                return group;
+            const members = Array.isArray(group.featureIds) ? group.featureIds : [];
+            const layerId = layerOfItem.get(group.id) ??
+                members
+                    .map((id) => (typeof id === 'string' ? layerOfFeature.get(id) : undefined))
+                    .find((id) => id !== undefined);
+            // A group that no layer lists and that has no member belongs to no layer
+            return { ...group, layerId: layerId ?? '' };
+        })
+        : data.groups;
+    return { ...data, version: '3.0.0', layers, groups, features };
+}
+/** A feature of version 2 in the shape of version 3 */
+function upgradeFeature(feature) {
+    let result = feature;
+    if ('coordinates' in feature && !('geometry' in feature)) {
+        const { coordinates, ...rest } = feature;
+        const geometry = typeof feature.type === 'string' && Array.isArray(coordinates)
+            ? geometryFromCoordinates(feature.type, coordinates)
+            : // Left for the validation to report
+                { type: undefined, coordinates };
+        result = { ...rest, geometry };
+    }
+    if (isRecord(feature.properties)) {
+        const properties = { ...feature.properties };
+        for (const name of DRAW_PROPERTY_NAMES) {
+            const key = drawPropertyKey(name);
+            if (hasOwnKey(properties, name) && !hasOwnKey(properties, key)) {
+                properties[key] = properties[name];
+                delete properties[name];
+            }
+        }
+        result = { ...result, properties };
+        if (feature.type === 'Image' && isRecord(feature.style)) {
+            const style = { ...feature.style };
+            if (foldLegacyImageStyle(properties, style))
+                result = { ...result, style };
+        }
+    }
+    return result;
+}
+/** The step that takes data of each major version to the next */
+const UPGRADES = new Map([[2, upgradeFrom2]]);
+/**
+ * Upgrades native data of an earlier major version to the version this library writes
+ *
+ * @param data - the data as it was read
+ * @returns the upgraded data, or the data as it is when it is of the current major version,
+ *   of a version without an upgrade, or not an object
+ */
+export function upgradeNativeData(data) {
+    if (!isRecord(data))
+        return data;
+    const current = majorOf(NATIVE_VERSION);
+    let result = data;
+    for (let major = majorOf(result.version); major !== null && major !== current;) {
+        const step = UPGRADES.get(major);
+        if (!step)
+            break;
+        result = step(result);
+        major = majorOf(result.version);
+    }
+    return result;
+}

package/dist/api/{import-export → impl/import-export}/native-validation.d.ts

@@ -6,7 +6,7 @@
  * deleted: a problem throws while the existing data is still intact. The checks follow the
  * native format described in docs/reference/data-format.md.
  */
-import type { Data, Feature, FileData, Group, Layer } from '../../store/types.js';
+import type { Data, Feature, FileData, Group, Layer } from '../../../store/types.js';
 /** Native data that passed validation, with the files normalized */
 export interface ValidatedNativeData {
     layers: Layer[];

package/dist/api/{import-export → impl/import-export}/native-validation.js

@@ -1,11 +1,12 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+import { DrawError } from '../../errors.js';
 import { NATIVE_VERSION } from './constants.js';
 import { normalizeEmbeddedFile } from './embedded-file.js';
-import { describeCoordinateProblem } from './geometry-validation.js';
+import { describeGeometryProblem } from './geometry-validation.js';
 import { sanitizeFeatureStyle } from './style-validation.js';
 function fail(message) {
-    throw new Error(`Invalid native data: ${message}`);
+    throw new DrawError('invalid-input', `Invalid native data: ${message}`);
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -28,8 +29,8 @@ function validateLayer(layer, index) {
     if (typeof layer.opacity !== 'number' || !Number.isFinite(layer.opacity)) {
         fail(`${where} has no finite opacity`);
     }
-    if (!Array.isArray(layer.order) || !layer.order.every((id) => typeof id === 'string')) {
-        fail(`${where} has no order array of strings`);
+    if (!Array.isArray(layer.items) || !layer.items.every((id) => typeof id === 'string')) {
+        fail(`${where} has no items array of strings`);
     }
     if (layer.metadata !== undefined && !isRecord(layer.metadata)) {
         fail(`${where} has a metadata that is not an object`);
@@ -51,6 +52,8 @@ function validateGroup(group, index) {
         fail(`${where} has no boolean visible`);
     if (typeof group.locked !== 'boolean')
         fail(`${where} has no boolean locked`);
+    if (typeof group.layerId !== 'string')
+        fail(`${where} has no string layerId`);
     if (!Array.isArray(group.featureIds) || !group.featureIds.every((id) => typeof id === 'string')) {
         fail(`${where} has no featureIds array of strings`);
     }
@@ -95,9 +98,9 @@ function validateFeature(feature, index, layerIds, groupIds) {
     const where = `feature "${feature.id}"`;
     if (!isNonEmptyString(feature.type))
         fail(`${where} has no string type`);
-    const coordinateProblem = describeCoordinateProblem(feature.type, feature.coordinates);
-    if (coordinateProblem)
-        fail(`${where} has ${coordinateProblem}`);
+    const geometryProblem = describeGeometryProblem(feature.type, feature.geometry);
+    if (geometryProblem)
+        fail(`${where} has ${geometryProblem}`);
     if (typeof feature.layerId !== 'string' || !layerIds.has(feature.layerId)) {
         fail(`${where} refers to a layer that does not exist`);
     }
@@ -115,12 +118,10 @@ function validateFeature(feature, index, layerIds, groupIds) {
     if (typeof feature.locked !== 'boolean')
         fail(`${where} has no boolean locked`);
     // A style key of the wrong type or form is dropped rather than rejecting the file: the
-    // store accepts any value through its API, so the library's own export can carry one
-    if (feature.style === undefined)
-        return feature;
-    const { style: _style, ...rest } = feature;
-    const style = sanitizeFeatureStyle(feature.style);
-    return (style === undefined ? rest : { ...rest, style });
+    // store accepts any value through its API, so the library's own export can carry one. A
+    // feature without a usable style gets the empty style
+    const style = feature.style === undefined ? undefined : sanitizeFeatureStyle(feature.style);
+    return { ...feature, style: style ?? {} };
 }
 async function validateFiles(files) {
     if (files === undefined)
@@ -190,7 +191,7 @@ export async function validateNativeData(data, retainedLayerIds) {
         layerIds.add(layer.id);
     }
     const layerOrder = validateLayerOrder(data.layerOrder, layers);
-    // Feature and group IDs share the entries of layer.order, so they must not collide either
+    // Feature and group IDs share the entries of layer.items, so they must not collide either
     const itemIds = new Set();
     const groups = (data.groups ?? []).map(validateGroup);
     const groupIds = new Set();

package/dist/api/impl/import-export/style-validation.d.ts

@@ -0,0 +1,24 @@
+import type { FeatureStyle } from '../../../store/types.js';
+type Check = (value: unknown) => boolean;
+/** A CSS color */
+export declare const isCssColor: Check;
+/**
+ * Returns the usable part of an imported style
+ *
+ * A key of FeatureStyle whose value fails its check is dropped; every other key is kept.
+ *
+ * @param value The style as read from the file
+ * @returns The style, or undefined when the value is not an object or nothing is left
+ */
+export declare function sanitizeFeatureStyle(value: unknown): FeatureStyle | undefined;
+/**
+ * Describes the first key of a style whose value fails its check
+ *
+ * A key given as `undefined` is not checked (it removes the key in a patch), and a key this
+ * library does not define is not checked either.
+ *
+ * @param value The style
+ * @returns A short description of the problem, or null when there is none
+ */
+export declare function describeStyleProblem(value: unknown): string | null;
+export {};

package/dist/api/impl/import-export/style-validation.js

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Validation of an imported feature style
+ *
+ * A style arrives from a file (the maplibre-gl-draw:style property of GeoJSON, the style of a
+ * native feature, the simplestyle-spec keys) and reaches the renderer, which parses the
+ * colors as CSS colors and uses the numbers as they are. A value of the wrong type or form (a
+ * number or null for a color, a string that is not a CSS color, an opacity of 5) would be
+ * drawn wrong, so each known key is checked here and a key that fails is dropped. Keys this
+ * library does not define are kept unchanged, whatever their value: they belong to the host or
+ * to an extension, which gives features keys of its own and checks their values where it reads
+ * them (values reach the Store through updateFeature and a replaced store as well, without
+ * passing here).
+ */
+import { isColor } from '../../../shared/color.js';
+import { setOwnProperty } from './own-property.js';
+/** A CSS color */
+export const isCssColor = isColor;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isOpacity = (value) => isFiniteNumber(value) && value >= 0 && value <= 1;
+const isNonNegative = (value) => isFiniteNumber(value) && value >= 0;
+const oneOf = (...values) => (value) => typeof value === 'string' && values.includes(value);
+/** The check of every key of FeatureStyle */
+const STYLE_CHECK_TABLE = {
+    fillColor: isCssColor,
+    fillOpacity: isOpacity,
+    strokeColor: isCssColor,
+    strokeWidth: isNonNegative,
+    strokeOpacity: isOpacity,
+    lineStyle: oneOf('solid', 'dashed', 'dotted'),
+    pointRadius: isNonNegative,
+    pointColor: isCssColor,
+    pointShape: oneOf('circle', 'square', 'triangle', 'star'),
+    pointOpacity: isOpacity,
+    pointStrokeColor: isCssColor,
+    pointStrokeWidth: isNonNegative,
+    imageOpacity: isOpacity,
+};
+const STYLE_CHECKS = new Map(Object.entries(STYLE_CHECK_TABLE));
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Returns the usable part of an imported style
+ *
+ * A key of FeatureStyle whose value fails its check is dropped; every other key is kept.
+ *
+ * @param value The style as read from the file
+ * @returns The style, or undefined when the value is not an object or nothing is left
+ */
+export function sanitizeFeatureStyle(value) {
+    if (!isRecord(value))
+        return undefined;
+    const style = {};
+    let kept = 0;
+    for (const [key, entry] of Object.entries(value)) {
+        const check = STYLE_CHECKS.get(key);
+        if (check && !check(entry))
+            continue;
+        setOwnProperty(style, key, entry);
+        kept++;
+    }
+    return kept > 0 ? style : undefined;
+}
+/**
+ * Describes the first key of a style whose value fails its check
+ *
+ * A key given as `undefined` is not checked (it removes the key in a patch), and a key this
+ * library does not define is not checked either.
+ *
+ * @param value The style
+ * @returns A short description of the problem, or null when there is none
+ */
+export function describeStyleProblem(value) {
+    if (!isRecord(value))
+        return 'a style that is not an object';
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        const check = STYLE_CHECKS.get(key);
+        if (check && !check(entry))
+            return `a style whose ${key} is not valid`;
+    }
+    return null;
+}

package/dist/api/impl/import-export/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Types internal to the Import/Export module
+ */
+import type { Feature, FileData, LoadResult } from '../../../store/types.js';
+/**
+ * A load whose source is read, checked and decoded: what is left is to write it, inside the
+ * transaction of the caller. Nothing that can fail is left to `write`, because a transaction
+ * does not roll back.
+ */
+export interface PreparedLoad {
+    /** Writes what was read and returns what was loaded */
+    write(): LoadResult;
+}
+/**
+ * GeoJSON import result (internal use).
+ *
+ * For a feature that contains image data, fileData is returned alongside it.
+ */
+export interface ConvertedFeatureResult {
+    feature: Feature;
+    fileData?: FileData;
+}
+/**
+ * Options for GeoJSON import
+ */
+export interface GeoJSONImportOptions {
+    /**
+     * Whether to expand Multi* geometries into features with a single geometry
+     *
+     * The default is false, which keeps MultiPoint / MultiLineString / MultiPolygon
+     * as Multi features as they are (so properties are not duplicated).
+     * Setting it to true expands them as before, assigning a new ID to each part.
+     */
+    flattenMulti?: boolean;
+    /**
+     * The layer every feature goes into, over the layer a feature names itself with
+     * `maplibre-gl-draw:layerId`. A group of another layer is then dropped from the feature
+     */
+    layerId?: string;
+    /**
+     * Whether the features and the groups of the document are replaced: they are deleted in the
+     * same transaction that writes the features of the file, and the layers stay
+     */
+    replace?: boolean;
+    /**
+     * Whether every feature goes into one layer (the one of `layerId`, else the current one) and
+     * leaves the group it names, because the load puts them all into a new group
+     */
+    oneGroup?: boolean;
+    /** IDs the features must not take, such as those of a layer and a group the load creates */
+    reservedIds?: ReadonlySet<string>;
+}

package/dist/api/impl/import-export/types.js

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