@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/utils/name-generator.js

@@ -0,0 +1,337 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Default mapping of type names
+ */
+const DEFAULT_TYPE_NAMES = {
+    Point: 'Point',
+    LineString: 'LineString',
+    Polygon: 'Polygon',
+    Circle: 'Circle',
+    Freehand: 'Freehand',
+    Image: 'Image',
+};
+/**
+ * Default Layer/Group names
+ */
+const DEFAULT_LAYER_NAME = 'Layer';
+const DEFAULT_GROUP_NAME = 'Group';
+/**
+ * Counter keys of Layer/Group
+ *
+ * They share the same Map / Set as the counter keys of Feature (FeatureType).
+ */
+const LAYER_COUNTER_KEY = 'Layer';
+const GROUP_COUNTER_KEY = 'Group';
+/**
+ * Default formatter
+ */
+function defaultFormatter(typeName, number) {
+    return `${typeName} ${number}`;
+}
+/**
+ * Extracts the number from a name
+ */
+function extractNumberFromName(name, typeName) {
+    // Escape the special characters
+    const escapedTypeName = typeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`^${escapedTypeName}\\s*(\\d+)$`);
+    const match = name.match(regex);
+    return match ? parseInt(match[1], 10) : null;
+}
+/**
+ * Normalizes an AutoNameConfig
+ */
+export function normalizeAutoNameConfig(config) {
+    if (config === undefined || config === true) {
+        return { enabled: true };
+    }
+    if (config === false) {
+        return { enabled: false };
+    }
+    return config;
+}
+/**
+ * AutoNameGenerator
+ *
+ * A class that generates sequential numbers per Feature type.
+ * It accounts for the numbers of existing Features and starts from the next number.
+ * A number that has been used once is not reused even after deletion (it leaves gaps).
+ *
+ * The existing numbers are taken in with a single full scan per type, and after that only the
+ * increments are taken in by subscribing to the Store. Scanning everything on every call would
+ * make the case of generating one at a time, as in a bulk import, O(n^2).
+ *
+ * With this incremental approach, the number of a name that was added and then deleted before
+ * any generation happened is also recorded (with the old approach it could be reused after the
+ * deletion). This is an extension of the "a number used once is not reused" policy, and it can
+ * only work in the direction of increasing the gaps.
+ */
+export class AutoNameGenerator {
+    constructor(store, config = true) {
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Counter that remembers the largest number already generated per type */
+        Object.defineProperty(this, "counters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Counter keys whose full scan is done (Layer/Group go into the same Set) */
+        Object.defineProperty(this, "scannedTypes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        /** Unsubscribe function of the Store subscription (null when not subscribed) */
+        Object.defineProperty(this, "unsubscribe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.store = store;
+        this.config = normalizeAutoNameConfig(config);
+        // When disabled, no name is generated, so there is no need to maintain the counters
+        if (this.config.enabled) {
+            this.unsubscribe = store.subscribe((changes) => {
+                this.observeChanges(changes);
+            });
+        }
+    }
+    /**
+     * Returns whether it is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Unsubscribes from the Store
+     */
+    dispose() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+    }
+    /**
+     * Generates an automatic name for the given type
+     *
+     * @returns The generated name, or undefined when it is disabled
+     */
+    generateName(featureType) {
+        if (!this.config.enabled) {
+            return undefined;
+        }
+        const typeName = this.getTypeName(featureType);
+        const nextNumber = this.findNextNumber(featureType, typeName);
+        const formatter = this.config.formatter ?? defaultFormatter;
+        return formatter(typeName, nextNumber);
+    }
+    /**
+     * Gets the type name
+     */
+    getTypeName(featureType) {
+        // Use a custom type name if there is one
+        if (this.config.typeNames && featureType in this.config.typeNames) {
+            return (this.config.typeNames[featureType] ?? featureType);
+        }
+        // Default type name
+        return DEFAULT_TYPE_NAMES[featureType] ?? featureType;
+    }
+    /**
+     * Gets the next number
+     *
+     * Increments the counter by 1 and returns it. The counter holds the largest existing number
+     * (the first full scan plus the increments after it), so the number of a deleted Feature is
+     * not reused and a gap appears.
+     */
+    findNextNumber(featureType, typeName) {
+        this.scanOnce(featureType, () => this.getMaxNumberFromFeatures(featureType, typeName));
+        const nextNumber = (this.counters.get(featureType) ?? 0) + 1;
+        this.counters.set(featureType, nextNumber);
+        return nextNumber;
+    }
+    /**
+     * Takes in the largest existing number only the first time a generation happens for that
+     * counter key
+     *
+     * From the second time onward the counter is maintained incrementally, so it does not scan.
+     */
+    scanOnce(counterKey, scan) {
+        if (this.scannedTypes.has(counterKey))
+            return;
+        this.scannedTypes.add(counterKey);
+        this.recordNumber(counterKey, scan());
+    }
+    /**
+     * Raises the counter up to number (a smaller value does not lower it)
+     */
+    recordNumber(counterKey, number) {
+        if (number > (this.counters.get(counterKey) ?? 0)) {
+            this.counters.set(counterKey, number);
+        }
+    }
+    /**
+     * Takes in the numbers of names from the changes of the Store
+     *
+     * The path that keeps the cost proportional to the number of changes and avoids scanning
+     * everything on every generation.
+     * Deletions are ignored (because a number used once is not reused).
+     */
+    observeChanges(changes) {
+        for (const feature of changes.features?.created ?? []) {
+            this.observeFeatureName(feature);
+        }
+        for (const { feature } of changes.features?.updated ?? []) {
+            this.observeFeatureName(feature);
+        }
+        const layerTypeName = this.getLayerTypeName();
+        for (const layer of changes.layers?.created ?? []) {
+            this.observeName(LAYER_COUNTER_KEY, layerTypeName, layer.name);
+        }
+        for (const { layer } of changes.layers?.updated ?? []) {
+            this.observeName(LAYER_COUNTER_KEY, layerTypeName, layer.name);
+        }
+        const groupTypeName = this.getGroupTypeName();
+        for (const group of changes.groups?.created ?? []) {
+            this.observeName(GROUP_COUNTER_KEY, groupTypeName, group.name);
+        }
+        for (const { group } of changes.groups?.updated ?? []) {
+            this.observeName(GROUP_COUNTER_KEY, groupTypeName, group.name);
+        }
+    }
+    /**
+     * Takes in the number from the name of a Feature
+     */
+    observeFeatureName(feature) {
+        const name = feature.properties?.name;
+        if (typeof name !== 'string')
+            return;
+        this.observeName(feature.type, this.getTypeName(feature.type), name);
+    }
+    /**
+     * Extracts the number from a name and takes it into the counter
+     */
+    observeName(counterKey, typeName, name) {
+        const number = extractNumberFromName(name, typeName);
+        if (number !== null)
+            this.recordNumber(counterKey, number);
+    }
+    /**
+     * Gets the type name of Layer
+     */
+    getLayerTypeName() {
+        return this.config.typeNames?.Layer ?? DEFAULT_LAYER_NAME;
+    }
+    /**
+     * Gets the type name of Group
+     */
+    getGroupTypeName() {
+        return this.config.typeNames?.Group ?? DEFAULT_GROUP_NAME;
+    }
+    /**
+     * Gets the largest number from the existing Features
+     */
+    getMaxNumberFromFeatures(featureType, typeName) {
+        const features = this.store.getAllFeatures();
+        let maxNumber = 0;
+        for (const feature of features) {
+            // Only features of the same type are considered
+            if (feature.type !== featureType) {
+                continue;
+            }
+            // Get the name property
+            const name = feature.properties?.name;
+            if (typeof name !== 'string') {
+                continue;
+            }
+            // Extract the number
+            const number = extractNumberFromName(name, typeName);
+            if (number !== null && number > maxNumber) {
+                maxNumber = number;
+            }
+        }
+        return maxNumber;
+    }
+    /**
+     * Generates the name of a new Layer
+     *
+     * A layer always has a name, so this never gives up: when naming is disabled it returns the
+     * word of Layer alone, without a number.
+     *
+     * @returns The generated name ("Layer 2"), or the word of Layer when it is disabled
+     */
+    generateLayerName() {
+        const typeName = this.getLayerTypeName();
+        if (!this.config.enabled) {
+            return typeName;
+        }
+        const nextNumber = this.findNextLayerNumber(typeName);
+        const formatter = this.config.formatter ?? defaultFormatter;
+        return formatter(typeName, nextNumber);
+    }
+    /**
+     * Gets the next Layer number
+     */
+    findNextLayerNumber(typeName) {
+        this.scanOnce(LAYER_COUNTER_KEY, () => {
+            let maxNumber = 0;
+            for (const layer of this.store.getAllLayers()) {
+                const number = extractNumberFromName(layer.name, typeName);
+                if (number !== null && number > maxNumber) {
+                    maxNumber = number;
+                }
+            }
+            return maxNumber;
+        });
+        const nextNumber = (this.counters.get(LAYER_COUNTER_KEY) ?? 0) + 1;
+        this.counters.set(LAYER_COUNTER_KEY, nextNumber);
+        return nextNumber;
+    }
+    /**
+     * Generates the name of a new Group
+     *
+     * A group always has a name, so this never gives up: when naming is disabled it returns the
+     * word of Group alone, without a number.
+     *
+     * @returns The generated name ("Group 2"), or the word of Group when it is disabled
+     */
+    generateGroupName() {
+        const typeName = this.getGroupTypeName();
+        if (!this.config.enabled) {
+            return typeName;
+        }
+        const nextNumber = this.findNextGroupNumber(typeName);
+        const formatter = this.config.formatter ?? defaultFormatter;
+        return formatter(typeName, nextNumber);
+    }
+    /**
+     * Gets the next Group number
+     */
+    findNextGroupNumber(typeName) {
+        this.scanOnce(GROUP_COUNTER_KEY, () => {
+            let maxNumber = 0;
+            for (const group of this.store.getAllGroups()) {
+                const number = extractNumberFromName(group.name, typeName);
+                if (number !== null && number > maxNumber) {
+                    maxNumber = number;
+                }
+            }
+            return maxNumber;
+        });
+        const nextNumber = (this.counters.get(GROUP_COUNTER_KEY) ?? 0) + 1;
+        this.counters.set(GROUP_COUNTER_KEY, nextNumber);
+        return nextNumber;
+    }
+}

package/dist/shared/utils/pixel-ratio.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Resolution of the rendering pixel ratio (pixelRatio)
+ *
+ * Line widths, point sizes and glyphs are baked in by converting CSS pixels into physical
+ * pixels, so the ratio of the backing store being drawn into is required. It normally matches
+ * `window.devicePixelRatio`, but it does not match when a maplibre Map is brought up with an
+ * arbitrary `pixelRatio` (such as a temporary instance mounted off-screen for a high-
+ * resolution export). It can therefore be injected through Options, and all references are
+ * collected into this helper.
+ *
+ * There are situations where the ratio itself needs to move at run time (as in the paper
+ * preview, where, while it is shown scaled down on the screen, the dimensions fixed in screen
+ * pixels should shrink by the same ratio), so the injected value accepts three forms: a
+ * number, a function that returns a value each time it is called, and a provider object.
+ * `createPixelRatioSource` is the actual provider, and it multiplies the resolved result by
+ * the rendering scale that can be changed at run time (renderScale).
+ *
+ * ## The two ratios
+ *
+ * renderScale applies only to "dimensions fixed in screen pixels".
+ *
+ * - Dimensions fixed in screen pixels (`resolvePixelRatio`) ... those whose thickness on the
+ *   screen does not change when the zoom changes. Point sizes, the line width of features
+ *   that have no createdZoom, line widths that go through `u_width`, and so on. They do not
+ *   shrink when the camera pulls back, so they have to be shrunk with renderScale in the
+ *   paper preview
+ * - Dimensions that scale with the zoom (`resolveContentPixelRatio`) ... those that the
+ *   shader multiplies by `2^(zoom - createdZoom)`, line widths given in meters, and so on.
+ *   They already shrink by the same ratio when the camera pulls back, so multiplying by
+ *   renderScale shrinks them twice (the 2026-08-10 defect where only the outlines of notes
+ *   thinned down to 1/k² in the paper preview)
+ *
+ * The side that bakes the value in chooses between the two by whether the shader scales that
+ * value with the zoom.
+ */
+/**
+ * Provider of the rendering pixel ratio (read only)
+ *
+ * It makes "the injected value (window when there is none)" and "the factor that can be
+ * changed at run time (renderScale)" readable separately. Handing this out as is to each
+ * renderer as the `PixelRatioInput` makes a change of the factor propagate from the next frame
+ * to every place that reads it directly, and also lets "the ratio without the factor" be taken
+ * from the same single socket.
+ */
+export interface PixelRatioProvider {
+    /** The current rendering pixel ratio (the injected value or window x renderScale) */
+    resolve: () => number;
+    /** The factor of the current rendering pixel ratio (default 1) */
+    getRenderScale: () => number;
+}
+/**
+ * The rendering pixel ratio that can be injected
+ *
+ * Besides a number, a function that returns the current ratio each time it is called and a
+ * provider object can be passed (so that a ratio that changes at run time is followed).
+ */
+export type PixelRatioInput = number | (() => number) | PixelRatioProvider;
+/**
+ * Resolves the rendering pixel ratio (for dimensions fixed in screen pixels; renderScale
+ * included)
+ *
+ * It returns the injected value if there is one, and otherwise reads
+ * `window.devicePixelRatio` on every call. The value at startup is not fixed because the ratio
+ * changes when the window is moved to a display with a different ratio (the behavior when
+ * there is no injection is exactly the same as before).
+ *
+ * @param pixelRatio The injected rendering pixel ratio (when unspecified, at most 0, or not a
+ *   number, it is read from window)
+ */
+export declare function resolvePixelRatio(pixelRatio?: PixelRatioInput): number;
+/**
+ * The rendering pixel ratio for dimensions that scale with the zoom (renderScale is not
+ * applied)
+ *
+ * Used for "dimensions that already scale with the zoom of the camera", such as line widths
+ * that the shader multiplies by `2^(zoom - createdZoom)` and line widths given in meters. When
+ * it is used as in the paper preview, where "the camera pulls back by δ and 2^-δ is passed to
+ * renderScale", applying the factor here would apply the same reduction twice.
+ *
+ * When no provider is passed (a number, a function, or unspecified) there is no notion of a
+ * factor, so it returns the same value as `resolvePixelRatio`.
+ *
+ * @param pixelRatio The injected rendering pixel ratio
+ */
+export declare function resolveContentPixelRatio(pixelRatio?: PixelRatioInput): number;
+/**
+ * Source of the rendering pixel ratio
+ *
+ * The read side (`PixelRatioProvider`) plus a socket for rewriting the factor.
+ * Handing the source itself out to each renderer as the `PixelRatioInput` makes a change from
+ * `setRenderScale` propagate from the next frame to every place that reads it directly.
+ */
+export interface PixelRatioSource extends PixelRatioProvider {
+    /**
+     * Sets the factor of the rendering pixel ratio
+     *
+     * It accepts only finite positive values (anything else is ignored). It returns true only
+     * when the value changed, so the caller can trigger a redraw or a rebuild of the batches
+     * only at that point.
+     */
+    setRenderScale: (scale: number) => boolean;
+}
+/**
+ * Creates a source of the rendering pixel ratio
+ *
+ * @param pixelRatio The injected rendering pixel ratio
+ * @param fallback Read each time when nothing usable was injected: the ratio of the map the
+ *   drawing goes into (`map.getPixelRatio()`), which follows a `pixelRatio` the map was
+ *   created with. When it is omitted or returns nothing usable, window is read
+ */
+export declare function createPixelRatioSource(pixelRatio?: number, fallback?: () => number): PixelRatioSource;

package/dist/shared/utils/pixel-ratio.js

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** Whether it is a provider object */
+function isProvider(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.resolve === 'function');
+}
+/** The ratio of window (1 in environments where it cannot be read) */
+function windowPixelRatio() {
+    return typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+}
+/** Lets only finite positive numbers through */
+function usable(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0;
+}
+/**
+ * Resolves the rendering pixel ratio (for dimensions fixed in screen pixels; renderScale
+ * included)
+ *
+ * It returns the injected value if there is one, and otherwise reads
+ * `window.devicePixelRatio` on every call. The value at startup is not fixed because the ratio
+ * changes when the window is moved to a display with a different ratio (the behavior when
+ * there is no injection is exactly the same as before).
+ *
+ * @param pixelRatio The injected rendering pixel ratio (when unspecified, at most 0, or not a
+ *   number, it is read from window)
+ */
+export function resolvePixelRatio(pixelRatio) {
+    if (isProvider(pixelRatio)) {
+        const resolved = pixelRatio.resolve();
+        return usable(resolved) ? resolved : windowPixelRatio();
+    }
+    const value = typeof pixelRatio === 'function' ? pixelRatio() : pixelRatio;
+    if (usable(value))
+        return value;
+    return windowPixelRatio();
+}
+/**
+ * The rendering pixel ratio for dimensions that scale with the zoom (renderScale is not
+ * applied)
+ *
+ * Used for "dimensions that already scale with the zoom of the camera", such as line widths
+ * that the shader multiplies by `2^(zoom - createdZoom)` and line widths given in meters. When
+ * it is used as in the paper preview, where "the camera pulls back by δ and 2^-δ is passed to
+ * renderScale", applying the factor here would apply the same reduction twice.
+ *
+ * When no provider is passed (a number, a function, or unspecified) there is no notion of a
+ * factor, so it returns the same value as `resolvePixelRatio`.
+ *
+ * @param pixelRatio The injected rendering pixel ratio
+ */
+export function resolveContentPixelRatio(pixelRatio) {
+    if (!isProvider(pixelRatio))
+        return resolvePixelRatio(pixelRatio);
+    const scale = pixelRatio.getRenderScale();
+    const resolved = resolvePixelRatio(pixelRatio);
+    if (!usable(scale))
+        return resolved;
+    return resolved / scale;
+}
+/**
+ * Creates a source of the rendering pixel ratio
+ *
+ * @param pixelRatio The injected rendering pixel ratio
+ * @param fallback Read each time when nothing usable was injected: the ratio of the map the
+ *   drawing goes into (`map.getPixelRatio()`), which follows a `pixelRatio` the map was
+ *   created with. When it is omitted or returns nothing usable, window is read
+ */
+export function createPixelRatioSource(pixelRatio, fallback) {
+    let renderScale = 1;
+    const input = usable(pixelRatio) ? pixelRatio : fallback;
+    return {
+        resolve: () => resolvePixelRatio(input) * renderScale,
+        getRenderScale: () => renderScale,
+        setRenderScale: (scale) => {
+            if (!Number.isFinite(scale) || scale <= 0)
+                return false;
+            if (scale === renderScale)
+                return false;
+            renderScale = scale;
+            return true;
+        },
+    };
+}

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

@@ -0,0 +1,88 @@
+import type { Feature, ImageProperties } from '../types/model.js';
+/**
+ * Gets the zoom at which the feature was created (`properties.createdZoom`)
+ *
+ * The drawing modes record it. Line widths follow the map from that zoom, and an Image is
+ * drawn at its size in pixels at that zoom (see {@link FeatureStyle.strokeWidth}).
+ *
+ * @returns The zoom, or undefined when the feature has none (it then keeps the same width on
+ *   the screen)
+ *
+ * @example
+ * ```ts
+ * const feature = draw.getFeature(id);
+ * const zoom = feature ? getCreatedZoom(feature) : undefined;
+ * ```
+ */
+export declare function getCreatedZoom(feature: Feature): number | undefined;
+/**
+ * Sets the zoom at which a feature was created, in a `properties` object
+ *
+ * Use it on the properties of a {@link FeatureInput} before `addFeature`, so that the new
+ * feature scales with the map from the current zoom like a drawn one.
+ *
+ * @example
+ * ```ts
+ * const properties: Record<string, unknown> = {};
+ * setCreatedZoom(properties, map.getZoom());
+ * draw.addFeature({
+ *   type: 'LineString',
+ *   coordinates: [
+ *     [139.76, 35.68],
+ *     [139.78, 35.69],
+ *   ],
+ *   properties,
+ * });
+ * ```
+ */
+export declare function setCreatedZoom(properties: Record<string, unknown>, zoom: number): void;
+/**
+ * Gets the rotation of the feature in degrees (`properties.rotation`, 0 when unset)
+ */
+export declare function getRotation(feature: Feature): number;
+/**
+ * Sets the rotation in degrees, in a `properties` object (the properties of a
+ * {@link FeatureInput} before `addFeature`, say)
+ */
+export declare function setRotation(properties: Record<string, unknown>, rotation: number): void;
+/**
+ * Gets the scale of the feature (`properties.scale`, 1 when unset), which resizing an Image
+ * changes
+ */
+export declare function getScale(feature: Feature): number;
+/**
+ * Sets the scale of the feature
+ */
+export declare function setScale(properties: Record<string, unknown>, scale: number): void;
+/**
+ * Gets the name of the feature
+ */
+export declare function getFeatureName(feature: Feature): string | undefined;
+/**
+ * Sets the name of the feature
+ */
+export declare function setFeatureName(properties: Record<string, unknown>, name: string): void;
+/**
+ * Gets the description of the feature
+ */
+export declare function getFeatureDescription(feature: Feature): string | undefined;
+/**
+ * Sets the description of the feature
+ */
+export declare function setFeatureDescription(properties: Record<string, unknown>, description: string): void;
+/**
+ * Gets the properties of an Image feature in a type-safe way.
+ *
+ * It validates and extracts each field from feature.properties (Record<string, unknown>).
+ * Use it instead of a dangerous cast such as `as unknown as ImageProperties`.
+ */
+export declare function getImageProperties(feature: Feature): ImageProperties;
+/**
+ * Gets the radius (meters) of a Circle feature. undefined when it is unset or invalid.
+ */
+export declare function getCircleRadius(feature: Feature): number | undefined;
+/**
+ * Gets the angle (degrees) of the radius handle of a Circle feature. The default is 135
+ * (toward the southwest).
+ */
+export declare function getRadiusHandleAngle(feature: Feature): number;