@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/config/feature-style.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Feature rendering style configuration
+ *
+ * Configuration related to rendering features.
+ * The selected state is expressed with a bounding box, so the style of the feature itself is
+ * not changed.
+ */
+import type { Color, PointStyle, StrokeStyle } from '../types/style.js';
+/**
+ * The fill of a polygon (part of {@link PolygonFeatureStyle})
+ */
+export interface FillStyle {
+    /**
+     * The fill color; its alpha is the opacity of the fill
+     *
+     * @defaultValue `#FF0077` at an alpha of 0.25
+     */
+    color: Color;
+}
+/**
+ * How a point is drawn by default (part of {@link FeatureStyleConfig})
+ */
+export interface PointFeatureStyle {
+    /**
+     * The marker
+     *
+     * @defaultValue a 12 px `#FF6633` circle with a 2 px white outline
+     */
+    point: PointStyle;
+}
+/**
+ * How a line is drawn by default (part of {@link FeatureStyleConfig})
+ */
+export interface LineStringFeatureStyle {
+    /**
+     * The line
+     *
+     * @defaultValue `#FF0077`, 2 px, solid
+     */
+    stroke: StrokeStyle;
+}
+/**
+ * How a polygon is drawn by default (part of {@link FeatureStyleConfig})
+ */
+export interface PolygonFeatureStyle {
+    /**
+     * The outline
+     *
+     * @defaultValue `#FF0077`, 2 px, solid
+     */
+    stroke: StrokeStyle;
+    /**
+     * The fill
+     *
+     * @defaultValue `#FF0077` at an alpha of 0.25
+     */
+    fill: FillStyle;
+}
+/**
+ * How the geometry being drawn looks, before it is committed as a feature (part of
+ * {@link FeatureStyleConfig})
+ */
+export interface TentativeStyle {
+    /**
+     * The line through the vertices placed so far
+     *
+     * @defaultValue `#FF0077`, 2 px, solid
+     */
+    stroke: StrokeStyle;
+    /**
+     * The line from the last vertex to the cursor, not yet committed
+     *
+     * @defaultValue `#FF0077`, 2 px, dashed
+     */
+    tentativeStroke: StrokeStyle;
+    /**
+     * The vertices placed so far
+     *
+     * @defaultValue a 10 px white circle with a 2 px `#FF0077` outline
+     */
+    vertex: PointStyle;
+    /**
+     * A vertex the cursor is close to (clicking the first vertex closes a polygon)
+     *
+     * @defaultValue a 14 px `#FFCC00` circle with a 3 px `#FF0077` outline
+     */
+    highlightedVertex: PointStyle;
+    /**
+     * For a Circle: the marker at the center
+     *
+     * @defaultValue a 6 px white circle with a 1 px `#FF2D55` outline
+     */
+    circleCenterMarker: PointStyle;
+    /**
+     * For a Circle: the handle on the edge that sets the radius
+     *
+     * @defaultValue a 10 px white circle with a 1 px `#FF2D55` outline
+     */
+    circleRadiusHandle: PointStyle;
+}
+/**
+ * The default look of the features, and of the geometry being drawn
+ *
+ * A key the style of a feature ({@link FeatureStyle}) leaves unset takes its value from here,
+ * unless the style rule of the layer gives the color. Give the parts to change through the
+ * `style` option of `createMapLibreGLDraw`; the parts left out keep their defaults.
+ *
+ * The selection does not change how a feature is drawn; it is shown by the box and the
+ * handles of {@link SelectionUIConfig}.
+ *
+ * @example
+ * ```ts
+ * const draw = createMapLibreGLDraw(map, {
+ *   style: {
+ *     lineString: {
+ *       stroke: { width: 3, color: [0, 0.33, 1, 1], opacity: 1, lineStyle: 'solid' },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface FeatureStyleConfig {
+    /**
+     * Point and MultiPoint
+     *
+     * @defaultValue a 12 px `#FF6633` circle with a 2 px white outline
+     */
+    point: PointFeatureStyle;
+    /**
+     * LineString, MultiLineString and Freehand
+     *
+     * @defaultValue `#FF0077`, 2 px, solid
+     */
+    lineString: LineStringFeatureStyle;
+    /**
+     * Polygon, MultiPolygon and Circle
+     *
+     * @defaultValue a `#FF0077` 2 px outline and a `#FF0077` fill at an alpha of 0.25
+     */
+    polygon: PolygonFeatureStyle;
+    /**
+     * The geometry being drawn
+     *
+     * @defaultValue `#FF0077` 2 px lines (dashed to the cursor) and 10 px white vertices
+     */
+    tentative: TentativeStyle;
+}
+/**
+ * Default feature rendering style configuration
+ */
+export declare const DEFAULT_FEATURE_STYLE_CONFIG: FeatureStyleConfig;
+/**
+ * Helper function that merges configurations
+ */
+export declare function mergeFeatureStyleConfig(base: FeatureStyleConfig, override: Partial<FeatureStyleConfig>): FeatureStyleConfig;

package/dist/shared/config/feature-style.js

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Default feature rendering style configuration
+ */
+export const DEFAULT_FEATURE_STYLE_CONFIG = {
+    point: {
+        point: {
+            shape: 'circle',
+            size: 12,
+            fillColor: [1.0, 0.4, 0.2, 1.0],
+            fillOpacity: 1.0,
+            strokeColor: [1.0, 1.0, 1.0, 1.0],
+            strokeWidth: 2,
+            strokeOpacity: 1.0,
+        },
+    },
+    lineString: {
+        stroke: {
+            width: 2,
+            color: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            opacity: 1.0,
+            lineStyle: 'solid',
+        },
+    },
+    polygon: {
+        stroke: {
+            width: 2,
+            color: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            opacity: 1.0,
+            lineStyle: 'solid',
+        },
+        fill: {
+            color: [1.0, 0.0, 0.467, 0.25], // #FF0077, 25% opacity
+        },
+    },
+    tentative: {
+        stroke: {
+            width: 2,
+            color: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            opacity: 1.0,
+            lineStyle: 'solid',
+        },
+        tentativeStroke: {
+            width: 2,
+            color: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            opacity: 1.0,
+            lineStyle: 'dashed',
+        },
+        vertex: {
+            shape: 'circle',
+            size: 10,
+            fillColor: [1.0, 1.0, 1.0, 1.0],
+            fillOpacity: 1.0,
+            strokeColor: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            strokeWidth: 2,
+            strokeOpacity: 1.0,
+        },
+        highlightedVertex: {
+            shape: 'circle',
+            size: 14,
+            fillColor: [1.0, 0.8, 0.0, 1.0], // yellow
+            fillOpacity: 1.0,
+            strokeColor: [1.0, 0.0, 0.467, 1.0], // #FF0077
+            strokeWidth: 3,
+            strokeOpacity: 1.0,
+        },
+        // For Circle: center marker
+        // Specification: a 6px diameter circle, white fill, pink border (#FF2D55), 1px wide
+        circleCenterMarker: {
+            shape: 'circle',
+            size: 6,
+            fillColor: [1.0, 1.0, 1.0, 1.0], // white
+            fillOpacity: 1.0,
+            strokeColor: [1.0, 0.176, 0.333, 1.0], // #FF2D55
+            strokeWidth: 1,
+            strokeOpacity: 1.0,
+        },
+        // For Circle: radius handle
+        // Specification: a 10px diameter circle, white fill, pink border (#FF2D55), 1px wide
+        circleRadiusHandle: {
+            shape: 'circle',
+            size: 10,
+            fillColor: [1.0, 1.0, 1.0, 1.0], // white
+            fillOpacity: 1.0,
+            strokeColor: [1.0, 0.176, 0.333, 1.0], // #FF2D55
+            strokeWidth: 1,
+            strokeOpacity: 1.0,
+        },
+    },
+};
+/**
+ * Helper function that merges configurations
+ */
+export function mergeFeatureStyleConfig(base, override) {
+    return {
+        point: {
+            ...base.point,
+            ...override.point,
+            point: {
+                ...base.point.point,
+                ...override.point?.point,
+            },
+        },
+        lineString: {
+            ...base.lineString,
+            ...override.lineString,
+            stroke: {
+                ...base.lineString.stroke,
+                ...override.lineString?.stroke,
+            },
+        },
+        polygon: {
+            ...base.polygon,
+            ...override.polygon,
+            stroke: {
+                ...base.polygon.stroke,
+                ...override.polygon?.stroke,
+            },
+            fill: {
+                ...base.polygon.fill,
+                ...override.polygon?.fill,
+            },
+        },
+        tentative: {
+            ...base.tentative,
+            ...override.tentative,
+            stroke: {
+                ...base.tentative.stroke,
+                ...override.tentative?.stroke,
+            },
+            tentativeStroke: {
+                ...base.tentative.tentativeStroke,
+                ...override.tentative?.tentativeStroke,
+            },
+            vertex: {
+                ...base.tentative.vertex,
+                ...override.tentative?.vertex,
+            },
+            highlightedVertex: {
+                ...base.tentative.highlightedVertex,
+                ...override.tentative?.highlightedVertex,
+            },
+            circleCenterMarker: {
+                ...base.tentative.circleCenterMarker,
+                ...override.tentative?.circleCenterMarker,
+            },
+            circleRadiusHandle: {
+                ...base.tentative.circleRadiusHandle,
+                ...override.tentative?.circleRadiusHandle,
+            },
+        },
+    };
+}

package/dist/shared/config/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config module
+ *
+ * Exports configuration-related types and constants.
+ */
+export type { HandleType } from './constants.js';
+export { CURSOR_STYLES, HANDLE_POSITIONS, INTERNAL_PROPERTIES, MOUSE_STATE, } from './constants.js';
+export type { FeatureStyleConfig, FillStyle, LineStringFeatureStyle, PointFeatureStyle, PolygonFeatureStyle, TentativeStyle, } from './feature-style.js';
+export { DEFAULT_FEATURE_STYLE_CONFIG, mergeFeatureStyleConfig } from './feature-style.js';
+export type { BoxSelectionStyleConfig, RenderingConfig, } from './rendering.js';
+export { DEFAULT_BOX_SELECTION_STYLE_CONFIG, DEFAULT_RENDERING_CONFIG, mergeRenderingConfig, } from './rendering.js';
+export type { BoundingBoxStyle, CenterMarkerStyle, MidpointHandleStyle, RadiusHandleStyle, RadiusLineStyle, ResizeHandleStyle, RotateHandleStyle, SelectionUIConfig, VertexHandleStyle, } from './selection.js';
+export { DEFAULT_SELECTION_CONFIG, DRAGGING_STYLE_MODIFIERS, HOVER_STYLE_MODIFIERS, mergeSelectionUIConfig, } from './selection.js';
+export type { TopologyConfig } from './topology.js';
+export { DEFAULT_TOPOLOGY_CONFIG, mergeTopologyConfig } from './topology.js';
+export type { TraceConfig, TraceOptions } from './trace.js';
+export { DEFAULT_TRACE_CONFIG, mergeTraceConfig } from './trace.js';

package/dist/shared/config/index.js

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { CURSOR_STYLES, HANDLE_POSITIONS, INTERNAL_PROPERTIES, MOUSE_STATE, } from './constants.js';
+export { DEFAULT_FEATURE_STYLE_CONFIG, mergeFeatureStyleConfig } from './feature-style.js';
+export { DEFAULT_BOX_SELECTION_STYLE_CONFIG, DEFAULT_RENDERING_CONFIG, mergeRenderingConfig, } from './rendering.js';
+export { DEFAULT_SELECTION_CONFIG, DRAGGING_STYLE_MODIFIERS, HOVER_STYLE_MODIFIERS, mergeSelectionUIConfig, } from './selection.js';
+export { DEFAULT_TOPOLOGY_CONFIG, mergeTopologyConfig } from './topology.js';
+export { DEFAULT_TRACE_CONFIG, mergeTraceConfig } from './trace.js';

package/dist/shared/config/rendering.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Rendering configuration
+ *
+ * Makes the default style of the box selection UI configurable.
+ */
+import type { Color } from '../types/style.js';
+/**
+ * How the rectangle of a box selection (a Shift-drag in the select mode) looks (part of
+ * {@link RenderingConfig})
+ */
+export interface BoxSelectionStyleConfig {
+    /**
+     * The fill; its alpha is the opacity of the fill
+     *
+     * @defaultValue `#FF0099` at an alpha of 0.2
+     */
+    fillColor: Color;
+    /**
+     * The color of the outline
+     *
+     * @defaultValue `#FF0099`
+     */
+    strokeColor: Color;
+    /**
+     * The width of the outline in CSS pixels
+     *
+     * @defaultValue `2`
+     */
+    strokeWidth: number;
+    /**
+     * The opacity of the outline, from 0 to 1
+     *
+     * @defaultValue `1`
+     */
+    strokeOpacity: number;
+    /**
+     * The dash pattern of the outline in CSS pixels, `[dash, gap]`
+     *
+     * @defaultValue `[6, 4]`
+     */
+    dashArray: [number, number];
+}
+/**
+ * Rendering settings: the look of the box selection and two switches of the renderer
+ *
+ * Give the settings to change through the `renderingStyle` option of `createMapLibreGLDraw`;
+ * the ones left out keep their defaults.
+ */
+export interface RenderingConfig {
+    /**
+     * The rectangle of a box selection
+     *
+     * @defaultValue a `#FF0099` 2 px outline dashed 6 px / 4 px, filled at an alpha of 0.2
+     */
+    boxSelectionStyle: BoxSelectionStyleConfig;
+    /**
+     * Retained-mode rendering of Store features
+     *
+     * When true (the default), Store features are drawn from retained batches prepared per
+     * layer. Features that stay still are no longer rebuilt every frame.
+     * Setting it to false goes back to the previous immediate-mode rendering (an escape hatch).
+     *
+     * The rendering result (including z-order) is the same either way.
+     *
+     * @defaultValue `true`
+     */
+    storeRetained?: boolean;
+    /**
+     * Whether work that does not fit in one frame is spread over the following frames
+     *
+     * When true (the default), the renderer keeps every frame short while the picture fills in
+     * over a few frames, much like tiles arriving:
+     *
+     * - the retained batches of the datasets are built within a time budget per frame, the
+     *   chunks in view first (the ones left over appear in the next frames)
+     * - polygons of a dataset with more than 10,000 vertices are triangulated in slices across
+     *   frames; their fill appears when the triangulation ends (the outline appears at once)
+     * - the tile index of the terrain drape is built within a time budget per frame
+     *
+     * Set it to false to draw frames that are complete: everything above is done in the frame
+     * that needs it, however long that frame takes. It is meant for a map that draws a frame to
+     * read the picture back (printing, thumbnails, exports), not for an interactive map. While
+     * the camera moves, the rebuilds that wait for the camera to stop still wait (a capture is
+     * taken with the camera still).
+     *
+     * A complete frame is not yet a complete picture: the map's tiles and the DEM arrive
+     * asynchronously. Wait for the map's `idle`, then for
+     * {@link MapLibreGLDraw.hasPendingWork} to return false, which also covers the work that no
+     * setting can make synchronous (the responses of a provider, an overlay renderer that
+     * prepares resources over several frames).
+     *
+     * @defaultValue `true`
+     */
+    timeSlicing?: boolean;
+}
+/**
+ * Default style configuration for the box selection UI
+ */
+export declare const DEFAULT_BOX_SELECTION_STYLE_CONFIG: BoxSelectionStyleConfig;
+/**
+ * Default rendering configuration
+ */
+export declare const DEFAULT_RENDERING_CONFIG: RenderingConfig;
+/**
+ * Helper function that merges configurations
+ */
+export declare function mergeRenderingConfig(base: RenderingConfig, override: Partial<RenderingConfig>): RenderingConfig;

package/dist/shared/config/rendering.js

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Default style configuration for the box selection UI
+ */
+export const DEFAULT_BOX_SELECTION_STYLE_CONFIG = {
+    fillColor: [1.0, 0.0, 0.6, 0.2],
+    strokeColor: [1.0, 0.0, 0.6, 1.0],
+    strokeWidth: 2,
+    strokeOpacity: 1.0,
+    dashArray: [6, 4],
+};
+/**
+ * Default rendering configuration
+ */
+export const DEFAULT_RENDERING_CONFIG = {
+    boxSelectionStyle: DEFAULT_BOX_SELECTION_STYLE_CONFIG,
+    storeRetained: true,
+    timeSlicing: true,
+};
+/**
+ * Helper function that merges configurations
+ */
+export function mergeRenderingConfig(base, override) {
+    return {
+        boxSelectionStyle: {
+            ...base.boxSelectionStyle,
+            ...override.boxSelectionStyle,
+        },
+        storeRetained: override.storeRetained ?? base.storeRetained,
+        timeSlicing: override.timeSlicing ?? base.timeSlicing,
+    };
+}

package/dist/shared/config/selection-highlight.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How the selection highlight of datasets looks
+ *
+ * Two rendering paths read the same values.
+ *
+ * - Immediate mode (`highlightFeature` in `display/selection.ts`). Draws points, and the
+ *   polygons and lines that do not go through the analysis drape (dashed outlines and so on)
+ * - Analysis drape (`view/terrain/drape/renderer.ts`). Draws the selection highlight for the
+ *   band (z > 11) that draws polygons and lines as pixels of the ground surface
+ *
+ * Putting separate constants in the two places would make the color or the width change when
+ * crossing a band. This single file owns the values.
+ *
+ * This file imports nothing, so that it depends on neither path.
+ */
+/** Base color of the selection highlight (#FF2D55, the same as the selection UI) */
+export declare const SELECTION_HIGHLIGHT_COLOR = "#FF2D55";
+/** Opacity of the polygon fill of the selection highlight */
+export declare const SELECTION_HIGHLIGHT_FILL_OPACITY = 0.25;
+/** Extra line width added by the selection highlight (CSS pixels) */
+export declare const SELECTION_HIGHLIGHT_STROKE_EXTRA = 2;
+/** Extra ring width added to points by the selection highlight (CSS pixels) */
+export declare const SELECTION_HIGHLIGHT_RING_EXTRA = 3;
+/**
+ * Resolves the base color into an RGB triple in the range 0 to 1
+ *
+ * Used to pass it to a shader uniform (the color is a constant, so it is parsed only once).
+ */
+export declare const SELECTION_HIGHLIGHT_RGB: readonly [number, number, number];

package/dist/shared/config/selection-highlight.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * How the selection highlight of datasets looks
+ *
+ * Two rendering paths read the same values.
+ *
+ * - Immediate mode (`highlightFeature` in `display/selection.ts`). Draws points, and the
+ *   polygons and lines that do not go through the analysis drape (dashed outlines and so on)
+ * - Analysis drape (`view/terrain/drape/renderer.ts`). Draws the selection highlight for the
+ *   band (z > 11) that draws polygons and lines as pixels of the ground surface
+ *
+ * Putting separate constants in the two places would make the color or the width change when
+ * crossing a band. This single file owns the values.
+ *
+ * This file imports nothing, so that it depends on neither path.
+ */
+/** Base color of the selection highlight (#FF2D55, the same as the selection UI) */
+export const SELECTION_HIGHLIGHT_COLOR = '#FF2D55';
+/** Opacity of the polygon fill of the selection highlight */
+export const SELECTION_HIGHLIGHT_FILL_OPACITY = 0.25;
+/** Extra line width added by the selection highlight (CSS pixels) */
+export const SELECTION_HIGHLIGHT_STROKE_EXTRA = 2;
+/** Extra ring width added to points by the selection highlight (CSS pixels) */
+export const SELECTION_HIGHLIGHT_RING_EXTRA = 3;
+/**
+ * Resolves the base color into an RGB triple in the range 0 to 1
+ *
+ * Used to pass it to a shader uniform (the color is a constant, so it is parsed only once).
+ */
+export const SELECTION_HIGHLIGHT_RGB = [
+    Number.parseInt(SELECTION_HIGHLIGHT_COLOR.slice(1, 3), 16) / 255,
+    Number.parseInt(SELECTION_HIGHLIGHT_COLOR.slice(3, 5), 16) / 255,
+    Number.parseInt(SELECTION_HIGHLIGHT_COLOR.slice(5, 7), 16) / 255,
+];