@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/shared/utils/color.js

@@ -1,40 +1,20 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
 /**
- * Extracts the RGB values from a HEX color string
+ * Color utilities: the interpolation of the continuous color ramps and the contrast color
  *
- * @param hex - A color string in #RRGGBB or #RGB form
- * @returns { r, g, b }, each value in 0-255
+ * The colors are read with the CSS color parser (`../color.ts`), so any CSS color works.
  */
-function parseHexToRgb(hex) {
-    const cleanHex = hex.replace('#', '');
-    let r;
-    let g;
-    let b;
-    if (cleanHex.length === 3) {
-        // #RGB form
-        r = Number.parseInt(cleanHex[0] + cleanHex[0], 16);
-        g = Number.parseInt(cleanHex[1] + cleanHex[1], 16);
-        b = Number.parseInt(cleanHex[2] + cleanHex[2], 16);
-    }
-    else {
-        // #RRGGBB form
-        r = Number.parseInt(cleanHex.substring(0, 2), 16);
-        g = Number.parseInt(cleanHex.substring(2, 4), 16);
-        b = Number.parseInt(cleanHex.substring(4, 6), 16);
-    }
-    return { r, g, b };
-}
+import { parseColor } from '../color.js';
 /**
- * Converts a HEX color string into an RGBA array
+ * Reads the RGB values of a CSS color (black when it is not a color)
  *
- * @param hex - A color string in #RRGGBB or #RGB form
- * @param opacity - Opacity (0-1)
- * @returns An array in the form [r, g, b, a] (each value in 0-1)
+ * @param color - A CSS color
+ * @returns { r, g, b }, each value in 0-255
  */
-export function hexToColor(hex, opacity = 1) {
-    const { r, g, b } = parseHexToRgb(hex);
-    return [r / 255, g / 255, b / 255, opacity];
+function parseRgb(color) {
+    const [r, g, b] = parseColor(color) ?? [0, 0, 0, 1];
+    return { r: r * 255, g: g * 255, b: b * 255 };
 }
 /**
  * Converts RGB values into a HEX color string
@@ -82,11 +62,11 @@ function linearToSrgb(c) {
  * (https://bottosson.github.io/posts/oklab/). It maps in the order sRGB -> linear sRGB -> LMS
  * -> cube root -> OKLab.
  *
- * @param hex - A color string in #RRGGBB or #RGB form
+ * @param hex - A CSS color
  * @returns { L, a, b } OKLab coordinates
  */
 function hexToOklab(hex) {
-    const rgb = parseHexToRgb(hex);
+    const rgb = parseRgb(hex);
     const r = srgbToLinear(rgb.r);
     const g = srgbToLinear(rgb.g);
     const b = srgbToLinear(rgb.b);
@@ -130,8 +110,8 @@ function oklabToHex(L, a, b) {
  * component by component.
  * The interpolation position is clamped to 0-1.
  *
- * @param from - Color of the start point (#RRGGBB or #RGB)
- * @param to - Color of the end point (#RRGGBB or #RGB)
+ * @param from - Color of the start point (a CSS color)
+ * @param to - Color of the end point (a CSS color)
  * @param t - Interpolation position (0-1)
  * @returns A color string in #RRGGBB form
  */
@@ -141,40 +121,3 @@ export function interpolateHexColor(from, to, t) {
     const b = hexToOklab(to);
     return oklabToHex(a.L + (b.L - a.L) * ratio, a.a + (b.a - a.a) * ratio, a.b + (b.b - a.b) * ratio);
 }
-/**
- * Computes the relative luminance
- *
- * Based on the relative luminance formula of WCAG 2.0.
- * https://www.w3.org/TR/WCAG20/#relativeluminancedef
- *
- * @param hex - A color string in #RRGGBB or #RGB form
- * @returns Relative luminance (0-1)
- */
-export function getLuminance(hex) {
-    const { r, g, b } = parseHexToRgb(hex);
-    // Convert from sRGB into a linear value
-    const toLinear = (c) => {
-        const srgb = c / 255;
-        return srgb <= 0.03928 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
-    };
-    const rLinear = toLinear(r);
-    const gLinear = toLinear(g);
-    const bLinear = toLinear(b);
-    // Computation of the relative luminance
-    return 0.2126 * rLinear + 0.7152 * gLinear + 0.0722 * bLinear;
-}
-/**
- * Gets a contrasting color
- *
- * Returns a highly visible contrasting color based on the luminance of the given color.
- * Returns black for a light color and white for a dark color.
- *
- * @param hex - A color string in #RRGGBB or #RGB form
- * @returns The contrasting color (#000000 or #FFFFFF)
- */
-export function getContrastColor(hex) {
-    const luminance = getLuminance(hex);
-    // A luminance above 0.5 means a light color -> a black outline
-    // A luminance at or below 0.5 means a dark color -> a white outline
-    return luminance > 0.5 ? '#000000' : '#FFFFFF';
-}

package/dist/shared/utils/coordinates.d.ts

@@ -7,7 +7,37 @@
  * same processing to every coordinate at any depth, so the depth-independent recursive
  * traversal is collected here.
  */
+import type { Geometry } from 'geojson';
 import type { Coordinate, FeatureCoordinates, FeatureType } from '../types/model.js';
+/** The kind of a GeoJSON geometry that has coordinates */
+export type GeometryKind = Exclude<Geometry['type'], 'GeometryCollection'>;
+/**
+ * The kind of geometry of a built-in feature type, or undefined for a custom type
+ */
+export declare function builtInGeometryKind(type: FeatureType): GeometryKind | undefined;
+/**
+ * The kind of geometry a feature type holds
+ *
+ * A built-in type has a fixed kind. A custom type is read from its coordinates as they come:
+ * a single position is a Point, a list of positions a LineString, a list of lists a Polygon
+ * and one level deeper a MultiPolygon.
+ */
+export declare function geometryKindOf(type: FeatureType, coordinates: FeatureCoordinates): GeometryKind;
+/**
+ * The GeoJSON geometry of a feature type with the given coordinates (the kind follows
+ * {@link geometryKindOf}; the coordinates are used as they are, not copied)
+ */
+export declare function geometryFromCoordinates(type: FeatureType, coordinates: FeatureCoordinates): Geometry;
+/**
+ * The coordinates of the geometry of a feature, nested as deep as its kind (an empty array
+ * for a GeometryCollection, which has none of its own)
+ */
+export declare function coordinatesOf(feature: {
+    readonly geometry: Geometry;
+}): FeatureCoordinates;
+export declare function coordinatesOf(feature: {
+    readonly geometry: Geometry;
+} | null | undefined): FeatureCoordinates | undefined;
 /**
  * The Multi family of feature types
  */
@@ -34,10 +64,6 @@ export declare function mapCoordinatesDeep<T extends FeatureCoordinates>(coords:
  * Used in the union computation of the bounding box and of hit testing.
  */
 export declare function forEachCoordinateDeep(coords: FeatureCoordinates, visit: (coord: Coordinate) => void): void;
-/**
- * Gets every coordinate as a flat array
- */
-export declare function flattenCoordinatesDeep(coords: FeatureCoordinates): Coordinate[];
 /**
  * Whether the feature type supports vertex editing (vertex handles / midpoint handles)
  *

package/dist/shared/utils/coordinates.js

@@ -1,5 +1,61 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The kind of geometry of each built-in feature type
+ *
+ * A Circle and an Image are held as the Point of their center and their anchor.
+ */
+const BUILT_IN_GEOMETRY_KINDS = new Map([
+    ['Point', 'Point'],
+    ['Circle', 'Point'],
+    ['Image', 'Point'],
+    ['LineString', 'LineString'],
+    ['Freehand', 'LineString'],
+    ['Polygon', 'Polygon'],
+    ['MultiPoint', 'MultiPoint'],
+    ['MultiLineString', 'MultiLineString'],
+    ['MultiPolygon', 'MultiPolygon'],
+]);
+/**
+ * The kind of geometry of a built-in feature type, or undefined for a custom type
+ */
+export function builtInGeometryKind(type) {
+    return BUILT_IN_GEOMETRY_KINDS.get(type);
+}
+/** The kind of geometry of coordinates of each nesting depth, for a custom type */
+const KINDS_BY_DEPTH = ['Point', 'LineString', 'Polygon', 'MultiPolygon'];
+/**
+ * The kind of geometry a feature type holds
+ *
+ * A built-in type has a fixed kind. A custom type is read from its coordinates as they come:
+ * a single position is a Point, a list of positions a LineString, a list of lists a Polygon
+ * and one level deeper a MultiPolygon.
+ */
+export function geometryKindOf(type, coordinates) {
+    const builtIn = BUILT_IN_GEOMETRY_KINDS.get(type);
+    if (builtIn)
+        return builtIn;
+    let depth = 0;
+    let value = coordinates;
+    while (Array.isArray(value) && Array.isArray(value[0])) {
+        depth++;
+        value = value[0];
+    }
+    return KINDS_BY_DEPTH[Math.min(depth, KINDS_BY_DEPTH.length - 1)];
+}
+/**
+ * The GeoJSON geometry of a feature type with the given coordinates (the kind follows
+ * {@link geometryKindOf}; the coordinates are used as they are, not copied)
+ */
+export function geometryFromCoordinates(type, coordinates) {
+    return { type: geometryKindOf(type, coordinates), coordinates };
+}
+export function coordinatesOf(feature) {
+    if (feature == null)
+        return undefined;
+    const { geometry } = feature;
+    return geometry.type === 'GeometryCollection' ? [] : geometry.coordinates;
+}
 /**
  * The Multi family of feature types
  */
@@ -49,16 +105,6 @@ export function forEachCoordinateDeep(coords, visit) {
         }
     }
 }
-/**
- * Gets every coordinate as a flat array
- */
-export function flattenCoordinatesDeep(coords) {
-    const result = [];
-    forEachCoordinateDeep(coords, (coord) => {
-        result.push(coord);
-    });
-    return result;
-}
 /**
  * Whether the feature type supports vertex editing (vertex handles / midpoint handles)
  *

package/dist/shared/utils/event-emitter.d.ts

@@ -1,262 +1 @@
-/**
- * EventEmitter
- *
- * The component that notifies the outside of state changes.
- * Events can be subscribed to in a form such as draw.on('feature.create', ...).
- */
-import type { DatasetClickEventPayload, MapClickEventPayload, RenderSlot, SnapResult } from '../types/events.js';
-import type { Feature, Group, Layer, Metadata, Mode, SelectionType, UpdateSource } from '../types/model.js';
-/**
- * Names of the editing operations of draw.geometry
- */
-export type GeometryOperationName = 'union' | 'subtract' | 'intersect' | 'buffer' | 'split';
-/**
- * Notification emitted when a geometric operation has been applied
- *
- * status expresses the outcome of the operation. 'applied' means that a result feature was
- * created; 'empty' means that the operation itself succeeded but the result had no area (an
- * intersection that does not overlap, a subtraction where everything was taken away, a buffer
- * where every input became empty, a split that did not divide the polygon). When it is
- * 'empty', the inputs are not modified at all and resultIds is empty.
- *
- * The result of the boolean editing operations (union / subtract / intersect) is always a
- * single one, so the length of resultIds is at most 1. A buffer creates a result per input, so
- * there can be several. A split produces two or more results. resultId is the first element of
- * resultIds (null when it is empty), a shorthand for subscribers that only deal with
- * operations producing a single result.
- *
- * The inputIds of a split are in the order [the polygon being cut, the line that cuts] (the
- * line is an input of the operation but remains without being removed).
- */
-export interface GeometryAppliedPayload {
-    /** Name of the operation */
-    operation: GeometryOperationName;
-    /** IDs of the input features (in z order; the last one is in the foreground) */
-    inputIds: string[];
-    /** ID of the result feature. null when the result is empty */
-    resultId: string | null;
-    /** IDs of the result features (in z order). An empty array when the result is empty */
-    resultIds: string[];
-    /** Outcome of the operation */
-    status: 'applied' | 'empty';
-}
-/**
- * Every feature change of one store flush (one transaction, or one mutation outside a
- * transaction)
- *
- * It is emitted once per flush that changes features, after the per-feature events of the
- * same flush, and carries all of them. A subscriber that rebuilds a view on any change
- * subscribes to this instead of the per-feature events, so a bulk load of N features costs
- * one rebuild rather than N.
- */
-export interface FeaturesChangePayload {
-    /** The features created */
-    created: Feature[];
-    /** The features updated, each with the feature before the update */
-    updated: {
-        feature: Feature;
-        previous: Feature;
-    }[];
-    /** The features deleted, as they were when they were deleted */
-    deleted: Feature[];
-    /**
-     * Source of the flush ('local', 'silent' or 'batch' from core, 'remote' from a replaced
-     * store, or a value of a plugin)
-     */
-    source: UpdateSource;
-}
-/**
- * The events of a draw instance by their internal names, with their payloads
- *
- * A plugin subscribes to them with `on` of {@link PluginContext}. They are the events the host
- * receives with `draw.on`, named without the `draw.` prefix: `feature.create` here is
- * `draw.feature.create` there ({@link EventPayloads} describes each one).
- */
-export interface EventMap {
-    /** A feature was created */
-    'feature.create': {
-        feature: Feature;
-    };
-    /** A feature was updated (with the feature before the update) */
-    'feature.update': {
-        feature: Feature;
-        previous: Feature;
-    };
-    /** A feature was deleted */
-    'feature.delete': {
-        feature: Feature;
-    };
-    /** Every feature change of one Store notification, after the per-feature events */
-    'features.change': FeaturesChangePayload;
-    /** The selection changed */
-    'selection.change': {
-        type: SelectionType | null;
-        ids: string[];
-        previousType: SelectionType | null;
-        previousIds: string[];
-    };
-    /** The mode changed */
-    'mode.change': {
-        mode: Mode;
-        previousMode: Mode;
-    };
-    /** A layer was created */
-    'layer.create': {
-        layer: Layer;
-    };
-    /** A layer was updated (with the layer before the update) */
-    'layer.update': {
-        layer: Layer;
-        previous: Layer;
-    };
-    /** A layer was deleted */
-    'layer.delete': {
-        layer: Layer;
-    };
-    /** The stacking order of the layers changed */
-    'layer.reorder': {
-        order: string[];
-        previous: string[];
-    };
-    /** A group was created */
-    'group.create': {
-        group: Group;
-    };
-    /** A group was updated (with the group before the update) */
-    'group.update': {
-        group: Group;
-        previous: Group;
-    };
-    /** A group was deleted */
-    'group.delete': {
-        group: Group;
-    };
-    /** The metadata of the document changed */
-    'metadata.change': {
-        metadata: Metadata;
-        previous: Metadata;
-    };
-    /** The image mode asks the host for an image file, to place at the carried position */
-    'image.request': {
-        coordinate: [number, number];
-        zoom: number;
-        layerId: string;
-    };
-    /** An operation of `draw.geometry` finished */
-    'geometry.applied': GeometryAppliedPayload;
-    /**
-     * Change of the snapping result
-     *
-     * Emitted when the snapping target changes (and, when snapping to an edge whose coordinates
-     * move, when the coordinates change). When snapping is lost, it is emitted once with no
-     * target.
-     */
-    'snap.change': SnapResult;
-    /**
-     * Resolution result of the click interception on datasets
-     *
-     * Emits on one channel whether a click in select mode hit a feature of a dataset
-     * (datasetId / feature are carried) or hit nothing (both are null).
-     * It is not emitted for a click that hit a feature of the Store.
-     */
-    'dataset.click': DatasetClickEventPayload;
-    /**
-     * A dataset was added
-     *
-     * Emitted by `addDataset` once the dataset is listed, so a handler can get it
-     * by its id. A plugin that follows every dataset (to subscribe to its `change`)
-     * subscribes to this and to `dataset.remove`, and lists the datasets that already exist
-     * once when it is installed.
-     */
-    'dataset.add': {
-        datasetId: string;
-    };
-    /**
-     * A dataset was removed
-     *
-     * Emitted by `removeDataset` and by the `remove` of the dataset, once it is no
-     * longer listed. It is not emitted when the draw instance is destroyed. A dataset added
-     * again under the same id is a new object, announced by a new `dataset.add`.
-     */
-    'dataset.remove': {
-        datasetId: string;
-    };
-    /**
-     * The order of the datasets changed
-     *
-     * Emitted by `moveDataset` when it moved a dataset within its side or to
-     * another side. `order` is the ids in display order, from the back to the front (the same
-     * as `getDatasets`). A move that leaves everything where it was emits nothing, and
-     * adding or removing a dataset emits `dataset.add` or `dataset.remove` instead.
-     */
-    'dataset.reorder': {
-        order: string[];
-    };
-    /**
-     * Map click in select mode
-     *
-     * Emits the normalized click as is on one channel, regardless of whether anything was hit
-     * and of what was hit (the coordinates are before snapping). It is for read-only
-     * subscription and does not affect the selection behavior of the modes. It is used by
-     * callers that need "a click anywhere on the map".
-     */
-    'map.click': MapClickEventPayload;
-    /**
-     * Addition or removal of frames (the CustomLayer per interval) and changes of the intervals
-     *
-     * On receiving this, the host re-places the native layers that correspond to the separators
-     * between the frames (it carries the same content as getRenderSlots).
-     */
-    'renderslots.change': {
-        slots: RenderSlot[];
-    };
-    /**
-     * Failure of an asynchronous load that no call returns
-     *
-     * `image`: the image of an Image feature could not be decoded (`featureId`). It is emitted
-     * once per feature and image, the decode is not retried, and the feature is drawn without
-     * its image. The error is the one that was thrown.
-     */
-    'load.error': LoadErrorPayload;
-}
-/**
- * The payload of the load.error event
- */
-export interface LoadErrorPayload {
-    /** Where the load was: the image of an Image feature */
-    source: 'image';
-    /** The Image feature whose image failed */
-    featureId: string;
-    /** What was thrown */
-    error: unknown;
-}
-/**
- * Event listener type
- */
-export type EventListener<K extends keyof EventMap> = (data: EventMap[K]) => void;
-/**
- * EventEmitter interface
- */
-export interface EventEmitter {
-    /**
-     * Registers an event listener
-     */
-    on<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
-    /**
-     * Unregisters an event listener
-     */
-    off<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
-    /**
-     * Emits an event
-     */
-    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
-}
-/**
- * EventEmitter implementation
- */
-export declare class EventEmitterImpl implements EventEmitter {
-    private listeners;
-    on<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
-    off<K extends keyof EventMap>(event: K, listener: EventListener<K>): void;
-    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
-}
+export {};

package/dist/shared/utils/event-emitter.js

@@ -1,7 +1,9 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
 /**
- * EventEmitter implementation
+ * The emitter of the signals of one engine
+ *
+ * @internal
  */
 export class EventEmitterImpl {
     constructor() {
@@ -30,8 +32,7 @@ export class EventEmitterImpl {
             return;
         // Take a snapshot so that listeners being added or removed during emit has no effect,
         // and isolate each one individually so that an exception from a single listener does not
-        // drag in the following listeners or the internal processing of the Core (EventBridge and
-        // so on).
+        // drag in the following listeners or the internal processing of the engine.
         for (const listener of [...set]) {
             try {
                 listener(data);

package/dist/shared/utils/feature-bbox.js

@@ -4,11 +4,11 @@
  * The bounding box of a feature
  *
  * A pure function of the feature (and the tile size for Image). The spatial index of the Store
- * (store/spatial) and the datasets (display/) both use it.
+ * (store/spatial) and the datasets (dataset/) both use it.
  */
 import { circleBoundingBox } from '../../geometry/circle.js';
 import { pixelsToDegreesLat, pixelsToDegreesLng, rotateCoordinateOnSphere } from '../math/index.js';
-import { forEachCoordinateDeep } from './coordinates.js';
+import { coordinatesOf, forEachCoordinateDeep } from './coordinates.js';
 import { getCircleRadius, getCreatedZoom, getImageProperties } from './property.js';
 /**
  * Computes the bounding box of a feature
@@ -16,15 +16,15 @@ import { getCircleRadius, getCreatedZoom, getImageProperties } from './property.
  * For an Image, the size at createdZoom is converted into geographic coordinates
  */
 function computeBoundingBox(feature, tileSize) {
-    const { type, coordinates } = feature;
+    const { type } = feature;
+    const coordinates = coordinatesOf(feature);
     // For an Image
     if (type === 'Image') {
         const coord = coordinates;
         const [lng, lat] = coord;
         const props = getImageProperties(feature);
-        const style = feature.style;
-        const imageWidth = style?.width || props.imageWidth || 100;
-        const imageHeight = style?.height || props.imageHeight || 100;
+        const imageWidth = props.imageWidth || 100;
+        const imageHeight = props.imageHeight || 100;
         const scale = props.scale ?? 1;
         // createdZoom defaults to 14 when missing. getImageProperties().createdZoom returns 0 when
         // missing, so ?? does not work; therefore getCreatedZoom(number|undefined) is used.
@@ -84,7 +84,8 @@ const coordinateBoundingBoxCache = new WeakMap();
  * cache hit it does not traverse and only returns a copy of the value.
  */
 function computeCoordinateBoundingBox(feature) {
-    const { type, coordinates } = feature;
+    const { type } = feature;
+    const coordinates = coordinatesOf(feature);
     if (type === 'Point') {
         const [lng, lat] = coordinates;
         return { minX: lng, minY: lat, maxX: lng, maxY: lat };

package/dist/shared/utils/feature-segments.js

@@ -8,6 +8,7 @@
  * so the listing sits in shared/. It is pure: it reads only the coordinates of the feature.
  */
 import { getSegmentGrid, querySegmentIndicesInBBox, SEGMENT_INDEX_THRESHOLD, } from '../math/segment-grid.js';
+import { coordinatesOf } from './coordinates.js';
 /**
  * Whether the feature type has edges (whether it is a target of edge snapping)
  *
@@ -56,24 +57,24 @@ export function isInBBox(position, bbox) {
 export function forEachPart(feature, visit) {
     switch (feature.type) {
         case 'LineString':
-            visit(feature.coordinates, 0, undefined, false);
+            visit(coordinatesOf(feature), 0, undefined, false);
             break;
         case 'Polygon': {
-            const rings = feature.coordinates;
+            const rings = coordinatesOf(feature);
             for (let ring = 0; ring < rings.length; ring++) {
                 visit(rings[ring], ring, undefined, true);
             }
             break;
         }
         case 'MultiLineString': {
-            const parts = feature.coordinates;
+            const parts = coordinatesOf(feature);
             for (let part = 0; part < parts.length; part++) {
                 visit(parts[part], 0, part, false);
             }
             break;
         }
         case 'MultiPolygon': {
-            const parts = feature.coordinates;
+            const parts = coordinatesOf(feature);
             for (let part = 0; part < parts.length; part++) {
                 const rings = parts[part];
                 for (let ring = 0; ring < rings.length; ring++) {

package/dist/shared/utils/image.d.ts

@@ -28,7 +28,3 @@ export declare function exceedsMaxImageSize(width: number, height: number): bool
  * A large image is resized automatically
  */
 export declare function processImageDataUrl(originalDataUrl: string): Promise<ProcessedImage>;
-/**
- * Tests whether it is an image file
- */
-export declare function isImageFile(file: File): boolean;

package/dist/shared/utils/image.js

@@ -98,9 +98,3 @@ function loadImage(dataUrl) {
         img.src = dataUrl;
     });
 }
-/**
- * Tests whether it is an image file
- */
-export function isImageFile(file) {
-    return file.type.startsWith('image/');
-}