@zwishing/emap 0.1.0

package/dist/ui/box-select-control.d.ts

@@ -0,0 +1,67 @@
+import type { Control } from './control';
+import type { Emap } from '../map/map';
+/** Visual style for the rubber-band rectangle. */
+export interface BoxSelectStyle {
+    /** Stroke color. Default `'#0078ff'`. */
+    stroke?: string;
+    /** Stroke width in CSS pixels. Default `1.5`. */
+    strokeWidth?: number;
+    /** Fill color. Default `'rgba(0, 120, 255, 0.1)'`. */
+    fill?: string;
+}
+export interface BoxSelectControlOptions {
+    /**
+     * Restrict the selection to a subset of layer ids. When omitted, every
+     * visible layer participates (matching `queryFeatures` default).
+     */
+    layers?: string[];
+    /** Visual style of the rubber-band rectangle. */
+    style?: BoxSelectStyle;
+    /**
+     * Pixel diagonal threshold below which the drag is treated as no-op.
+     * Default `4`.
+     */
+    dragThreshold?: number;
+}
+/**
+ * Shift+drag rubber-band feature selection. Reuses
+ * `Emap.queryFeatures(bbox)` for hit-testing and `Emap.select` for
+ * selection state management.
+ *
+ * Modifier-key conventions (layered on top of shift):
+ * - shift only → mode `'replace'`
+ * - shift + ctrl/meta → mode `'add'`
+ * - shift + alt → mode `'toggle'`
+ *
+ * Tiny drags (< `dragThreshold` px diagonal) cancel without selecting.
+ *
+ * Coordinates with `DragPanHandler`: the handler now skips shift-modified
+ * mousedowns, leaving shift+drag for this control.
+ */
+export declare class BoxSelectControl implements Control {
+    private _options;
+    private _dragThreshold;
+    private _enabled;
+    private _map;
+    private _container;
+    private _overlay;
+    private _canvasContainer;
+    private _startPx;
+    private _onMouseDownBound;
+    private _onMouseMoveBound;
+    private _onMouseUpBound;
+    constructor(options?: BoxSelectControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    /** Disable the control — shift+drag becomes a no-op until re-enabled. */
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+    private _onMouseDown;
+    private _onMouseMove;
+    private _onMouseUp;
+    private _cancelDrag;
+    private _cleanupDrag;
+    private _eventToContainerPx;
+    private _modeFromEvent;
+}

package/dist/ui/control.d.ts

@@ -0,0 +1,6 @@
+import { Emap } from '../map/map';
+export interface Control {
+    onAdd(map: Emap): HTMLElement;
+    onRemove(map?: Emap): void;
+}
+export type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

package/dist/ui/draw-feature-control.d.ts

@@ -0,0 +1,82 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+export type DrawGeometryType = 'polygon' | 'polyline' | 'point';
+export interface DrawFeatureControlOptions {
+    /** Target source ID where new features will be added */
+    source: string;
+    /** Target layer name within the source (optional, defaults to first matching geometry layer) */
+    sourceLayer?: string;
+    /** Geometry type to draw */
+    type: DrawGeometryType;
+    /** Pixel threshold for vertex snapping (default: 10) */
+    snapThreshold?: number;
+    /**
+     * Sources to snap against. Defaults to `[options.source]` so the existing
+     * single-source behaviour is preserved when omitted. Pass `['a', 'b']` to
+     * also snap onto another source (e.g. drawing in source A while tracing
+     * along reference data in source B).
+     */
+    snapSources?: string[];
+    /** Enable vertex snap (default `true`). */
+    snapToVertex?: boolean;
+    /**
+     * Enable edge snap — perpendicular projection onto an arc segment
+     * (default `true`). Disable to restrict snap to existing vertices only.
+     */
+    snapToEdge?: boolean;
+    /** CSS color for the drawing line (default: '#0078ff') */
+    drawColor?: string;
+    /**
+     * Button icon. A `string` is rendered as text via `textContent` (safe;
+     * covers unicode glyphs like the defaults below). Pass a `Node` to render
+     * a pre-built DOM element such as an `<svg>` — caller is responsible for
+     * its own escaping.
+     */
+    icon?: string | Node;
+}
+export declare class DrawFeatureControl implements Control {
+    private _options;
+    private _map;
+    private _container;
+    private _btn;
+    private _active;
+    private _vertices;
+    private _cursorCoord;
+    private _snapCoord;
+    private _snapKind;
+    private _snapThreshold;
+    private _onMouseMoveBound;
+    private _onClickBound;
+    private _onDblClickBound;
+    private _onKeyDownBound;
+    private _onMoveHandlerBound;
+    constructor(options: DrawFeatureControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    private _toggle;
+    private _activate;
+    private _deactivate;
+    /** Deactivate UI without firing setEditMode (used when another mode takes over) */
+    private _deactivateQuiet;
+    private _clearDrawState;
+    private _onMapMove;
+    private _onMouseMove;
+    private _onClick;
+    private _onDblClick;
+    private _onKeyDown;
+    private _findSnapTarget;
+    private _commitFeature;
+    private _resolveTargetLayer;
+    private _appendArc;
+    private _updateDrawState;
+}
+/**
+ * Closest point on segment `[a, b]` to point `p`, all in 2-D pixel space.
+ * Parameter `t = ((p-a)·(b-a)) / |b-a|²` is clamped to `[0, 1]` so the
+ * returned point is always on the segment (not its infinite line). For a
+ * zero-length segment, returns endpoint `a` and `dist(p, a)`.
+ */
+export declare function projectPointOnSegment(p: [number, number], a: [number, number], b: [number, number]): {
+    point: [number, number];
+    dist: number;
+};

package/dist/ui/edit-toolbar.d.ts

@@ -0,0 +1,27 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+export interface EditToolbarOptions {
+    /** Source ID for draw tools. If not provided, draw buttons are not shown. */
+    drawSource?: string;
+    /** Source layer name for draw tools (optional, defaults to first matching layer). */
+    drawSourceLayer?: string;
+}
+/**
+ * EditToolbar wraps editing controls (vertex edit + draw tools) in a styled toolbar.
+ *
+ * Usage:
+ *   // Vertex edit only (backward compatible)
+ *   map.addControl(new EditToolbar(), 'top-left');
+ *
+ *   // With draw tools
+ *   map.addControl(new EditToolbar({ drawSource: 'my-source' }), 'top-left');
+ */
+export declare class EditToolbar implements Control {
+    private _container;
+    private _vertexEditControl;
+    private _drawControls;
+    private _options;
+    constructor(options?: EditToolbarOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+}

package/dist/ui/history-control.d.ts

@@ -0,0 +1,29 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+export interface HistoryControlOptions {
+    /** Tooltip text for the undo button. Default: "Undo (Ctrl+Z)". */
+    undoTitle?: string;
+    /** Tooltip text for the redo button. Default: "Redo (Ctrl+Shift+Z)". */
+    redoTitle?: string;
+    /** Optional class to add to the control container. */
+    className?: string;
+}
+/**
+ * Two-button Undo / Redo control.
+ *
+ * Buttons are enabled / disabled based on the map's `historychange` event so
+ * they always reflect `canUndo()` / `canRedo()` without polling.
+ */
+export declare class HistoryControl implements Control {
+    private _map;
+    private _container;
+    private _undoBtn;
+    private _redoBtn;
+    private _options;
+    private _onHistoryChange;
+    constructor(options?: HistoryControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    private _setEnabled;
+    private _createButton;
+}

package/dist/ui/lasso-select-control.d.ts

@@ -0,0 +1,96 @@
+import type { Control } from './control';
+import type { Emap } from '../map/map';
+/** Visual style for the rubber-band lasso path. */
+export interface LassoSelectStyle {
+    /** Stroke color. Default `'#0078ff'`. */
+    stroke?: string;
+    /** Stroke width in CSS pixels. Default `1.5`. */
+    strokeWidth?: number;
+    /** Fill color of the closed shape preview. Default `'rgba(0, 120, 255, 0.1)'`. */
+    fill?: string;
+    /** SVG `stroke-dasharray` value. Default `'4 3'` (subtly dashed). */
+    strokeDasharray?: string;
+}
+export interface LassoSelectControlOptions {
+    /**
+     * Restrict the selection to a subset of layer ids. When omitted, every
+     * visible layer participates (matching `queryFeatures` default).
+     */
+    layers?: string[];
+    /** Visual style of the lasso polyline. */
+    style?: LassoSelectStyle;
+    /**
+     * Pixel diagonal threshold below which the drag is treated as no-op.
+     * Default `4`.
+     */
+    dragThreshold?: number;
+    /**
+     * Select features that intersect the lasso boundary or interior, not only
+     * features fully contained by it. Default `true`, matching box-select.
+     */
+    includeIntersecting?: boolean;
+}
+/**
+ * Shift+drag free-form polygon feature selection. Sibling of
+ * `BoxSelectControl` — same activation gesture, same modifier conventions,
+ * different shape.
+ *
+ * The lasso path is recorded in pixel coordinates as the user drags. On
+ * release, the closed polygon is used to test each candidate feature's
+ * geometry; survivors are passed to `Emap.select`.
+ *
+ * Modifier-key conventions (layered on top of shift):
+ * - shift only → mode `'replace'`
+ * - shift + ctrl/meta → mode `'add'`
+ * - shift + alt → mode `'toggle'`
+ *
+ * Coexistence with `BoxSelectControl`: both consume shift+drag. Pick one,
+ * or install both and switch between them at runtime via `enable()` /
+ * `disable()`.
+ *
+ * Hit-test semantics: by default, features are selected when their geometry
+ * intersects or is contained by the lasso, matching box-select's inclusive
+ * feel. Set `includeIntersecting: false` for strict containment.
+ */
+export declare class LassoSelectControl implements Control {
+    private _options;
+    private _dragThreshold;
+    private _enabled;
+    private _map;
+    private _container;
+    private _svg;
+    private _polyline;
+    private _canvasContainer;
+    /** Drag state — pixel-space path. null when not dragging. */
+    private _path;
+    private _onMouseDownBound;
+    private _onMouseMoveBound;
+    private _onMouseUpBound;
+    constructor(options?: LassoSelectControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    /** Disable the control — shift+drag becomes a no-op until re-enabled. */
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+    private _onMouseDown;
+    private _onMouseMove;
+    private _onMouseUp;
+    private _cancelDrag;
+    private _cleanupDrag;
+    private _eventToContainerPx;
+}
+/**
+ * Even-odd ray-cast point-in-polygon test. The `polygon` may be open or
+ * closed (last point == first point) — we don't require either form,
+ * because we wrap via `j = (i - 1 + n) % n` modulo arithmetic. Self-
+ * intersecting polygons follow standard even-odd semantics (which usually
+ * matches the user's drawn intent).
+ */
+export declare function pointInPolygon(point: [number, number], polygon: Array<[number, number]>): boolean;
+export declare function featureMatchesLasso(map: Emap, ref: {
+    source: string;
+    layer: string;
+    id: number;
+    geometryType?: string;
+}, lasso: Array<[number, number]>, includeIntersecting: boolean): boolean;

package/dist/ui/navigation-control.d.ts

@@ -0,0 +1,16 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+export interface NavigationOptions {
+    showZoom?: boolean;
+    showHome?: boolean;
+    className?: string;
+}
+export declare class NavigationControl implements Control {
+    private _map;
+    private _container;
+    private _options;
+    constructor(options?: NavigationOptions);
+    onAdd(map: Emap): HTMLElement;
+    private _createButton;
+    onRemove(): void;
+}

package/dist/ui/simplify-control.d.ts

@@ -0,0 +1,40 @@
+import { Control } from './control';
+import type { Emap } from '../map/map';
+import type { SimplifyMethod } from '../map/types';
+export interface SimplifyControlOptions {
+    /** Source ID to simplify. Required. */
+    source: string;
+    /** Optional layer name — when omitted, the whole source dataset is simplified. */
+    target?: string;
+    /** Initial slider value, 0–100. Default 10 (= keep 10% of vertices). */
+    initialPercentage?: number;
+    /** Initial method. Default 'weighted'. */
+    initialMethod?: SimplifyMethod;
+    /** Button tooltip override. */
+    title?: string;
+}
+export declare class SimplifyControl implements Control {
+    private _opts;
+    private _map;
+    private _container;
+    private _btn;
+    private _popup;
+    private _percentageInput;
+    private _percentageLabel;
+    private _methodSel;
+    private _keepShapes;
+    private _planar;
+    private _applyBtn;
+    private _statusEl;
+    private _onDocClick;
+    private _onDocKey;
+    constructor(opts: SimplifyControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    private _buildPopup;
+    private _togglePopup;
+    private _setupDocListeners;
+    private _teardownDocListeners;
+    private _setStatus;
+    private _apply;
+}

package/dist/ui/status-control.d.ts

@@ -0,0 +1,23 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+export interface StatusOptions {
+    showMousePos?: boolean;
+    showEPSG?: boolean;
+    alignment?: 'left' | 'right' | 'center';
+    className?: string;
+}
+export declare class StatusControl implements Control {
+    private _map;
+    private _container;
+    private _options;
+    private _mousePosEl;
+    private _epsgEl;
+    private _onMouseMoveBound;
+    private _onUpdateEPSGBound;
+    private _rafPending;
+    constructor(options?: StatusOptions);
+    onAdd(map: Emap): HTMLElement;
+    private _onMouseMove;
+    private _updateEPSG;
+    onRemove(): void;
+}

package/dist/ui/vertex-edit-control.d.ts

@@ -0,0 +1,111 @@
+import { Control } from './control';
+import { Emap } from '../map/map';
+/** Options for VertexEditControl */
+export interface VertexEditControlOptions {
+    /**
+     * Fill color for polygon shapes in vertex edit mode.
+     * Any CSS color string. Set to null to disable fill.
+     * @default 'rgba(0,0,0,0.15)'
+     */
+    polygonFillColor?: string | null;
+}
+/**
+ * VertexEditControl enables interactive vertex editing with topology awareness.
+ * When a shared node is dragged, ALL coincident vertices move together.
+ *
+ * Uses MapshaperAdapter.findNearestVertices to discover topologically-shared
+ * vertices, and snapVerticesToPoint to move them all simultaneously.
+ *
+ * @example
+ *   map.addControl(new VertexEditControl(), 'top-left');
+ *   // With custom polygon fill:
+ *   map.addControl(new VertexEditControl({ polygonFillColor: 'rgba(100,150,255,0.2)' }), 'top-left');
+ */
+export declare class VertexEditControl implements Control {
+    private _map;
+    private _container;
+    private _btn;
+    private _active;
+    private _polygonFillColor;
+    private _hoveredFeature;
+    private _hoverVertexCoords;
+    private _hoverVertexIds;
+    private _hoverType;
+    private _hoverInsertionId;
+    private _dragging;
+    /** Shapes of neighboring polygons sharing the hovered arc (for shared-edge highlight) */
+    private _neighborShapes;
+    /** Coordinate of the dragged node before mouse-down, captured for VertexMoveCommand. */
+    private _dragFromCoords;
+    private _onMouseMoveBound;
+    private _onMouseDownBound;
+    private _onMouseUpBound;
+    private _onMoveHandlerBound;
+    private _onContextMenuBound;
+    constructor(options?: VertexEditControlOptions);
+    onAdd(map: Emap): HTMLElement;
+    onRemove(): void;
+    private _toggle;
+    private _activate;
+    private _deactivate;
+    /** Redraw on map move/zoom (vertices stay fixed to geography) */
+    private _onMapMove;
+    /**
+     * Right-click handler: show a context menu to delete the hovered vertex.
+     * Guard rules (same as mapshaper):
+     *   - Must be hovering a vertex (not an interpolated edge point)
+     *   - Not currently dragging
+     *   - Vertex must NOT be an arc endpoint (deleting an endpoint breaks topology)
+     */
+    private _onContextMenu;
+    /** Delete the currently hovered vertex from the arc collection */
+    private _deleteHoveredVertex;
+    /**
+     * Re-initialize the source's DisplayArcs after an arc-mutating edit so that
+     * the simplified LOD copy reflects the new vertex layout.
+     */
+    private _refreshSourceDisplayArcs;
+    /**
+     * Bump the dataset's `editVersion` after a live in-place arc mutation.
+     * The spatial-index cache in `feature-query` keys on `editVersion`, so
+     * this is what tells the next `queryFeatures` call that bboxes may
+     * have changed and the index must rebuild. Cheap (a number
+     * increment); only the next query pays the actual rebuild cost.
+     *
+     * The matching command's `do()/undo()` also bump, but those run on
+     * undo / redo — not on initial commit, since `pushCommand` skips
+     * `do()` per the memento contract.
+     */
+    private _bumpSourceEditVersion;
+    /**
+     * Show a minimal context menu at (x, y) in viewport coords.
+     * Auto-dismissed when user clicks anywhere else.
+     */
+    private _showContextMenu;
+    private _onMouseMove;
+    /**
+     * Use MapshaperAdapter.findNearestVertices to discover ALL vertex indices
+     * that share the same topological node (identical coordinates across all arcs).
+     */
+    private _findNearestVertices;
+    /**
+     * Find the closest point along any segment edge (not just vertices).
+     * Uses mapshaper's forEachSegmentInShape + findClosestPointOnSeg.
+     * Called as fallback when no existing vertex is within hover threshold.
+     */
+    private _findInterpolatedPoint;
+    /**
+     * Find all shapes (polygons) in the source that share any arc with the hovered vertex/edge.
+     * Handles two cases:
+     *   - Vertex hover: hoverVertexIds → arcIds via findArcIdFromVertexId
+     *   - Edge hover (interpolated): hoverInsertionId - 1 → arcId via findArcIdFromVertexId
+     * Only runs when geometry is polygon. Populates _neighborShapes.
+     */
+    private _findNeighborShapes;
+    /** Update the edit vertex state on the map so render() draws vertex dots (and polygon fill) */
+    private _updateEditState;
+    private _onMouseDown;
+    private _pushVertexInsertCommand;
+    private _handleDrag;
+    private _onMouseUp;
+}

package/dist/validation/builtin/topology.d.ts

@@ -0,0 +1,19 @@
+import type { Validator, ValidationIssue } from '../validator';
+export interface TopologyValidatorOptions {
+    /**
+     * Limit the validator to these source ids. If omitted, runs over
+     * every registered source. Useful when a workflow has a "scratchpad"
+     * source where intersections are temporarily expected.
+     */
+    sources?: string[];
+    /** Tolerance forwarded to `findSegmentIntersections`. */
+    tolerance?: number;
+    /** Severity of reported issues. Defaults to `'error'`. */
+    severity?: ValidationIssue['severity'];
+}
+/**
+ * Construct a `Validator` that scans listed sources for arc
+ * self-intersections after every commit. Failures appear in the
+ * `validationfailed` event payload as one issue per offending source.
+ */
+export declare function topologyValidator(opts?: TopologyValidatorOptions): Validator;

package/dist/validation/registry.d.ts

@@ -0,0 +1,23 @@
+import type { Validator, ValidatorPhase, ValidatorResult, ValidationChange } from './validator';
+import type { EmapHostInternal } from '../map/emap-host';
+export declare class ValidatorRegistry {
+    private _all;
+    /** Number of currently registered validators (across all phases). */
+    get size(): number;
+    /**
+     * Register a validator. Returns an unregister callback — call it to
+     * remove this exact validator (idempotent).
+     */
+    register(v: Validator): () => void;
+    /** Remove every registered validator. */
+    unregisterAll(): void;
+    /**
+     * Run every validator whose `phase` matches `phase`, in parallel.
+     * Validator throws are converted to `severity: 'error'` issues so the
+     * caller's hook chain stays predictable.
+     *
+     * Returns the per-validator results in registration order. Callers
+     * typically filter `.report.ok === false` to surface failures.
+     */
+    runFor(phase: ValidatorPhase, host: EmapHostInternal, change: ValidationChange): Promise<ValidatorResult[]>;
+}

package/dist/validation/validator.d.ts

@@ -0,0 +1,47 @@
+import type { FeatureRef } from '../map/types';
+import type { EmapHostInternal } from '../map/emap-host';
+/**
+ * Phase at which a validator runs. Currently only `'after-commit'` is
+ * supported — runs after `historychange` fires. Reserved here as a
+ * union so future phases (`'before-commit'` for pre-flight rejection,
+ * `'on-load'` for source-import validation) can be added without a
+ * breaking signature change.
+ */
+export type ValidatorPhase = 'after-commit';
+/** One issue surfaced by a validator run. */
+export interface ValidationIssue {
+    severity: 'error' | 'warning';
+    message: string;
+    /** Optional reference to the offending feature (UI can highlight it). */
+    ref?: FeatureRef;
+}
+/** Result of a single validator run. */
+export interface ValidationReport {
+    /** `true` iff `issues` is empty OR contains only warnings. */
+    ok: boolean;
+    issues: ValidationIssue[];
+}
+/**
+ * Information passed to validators about the change that triggered the
+ * run. Lets a validator scope its work — e.g. only re-check the source
+ * that was just modified.
+ */
+export interface ValidationChange {
+    /** Label of the command that just committed (matches history.label). */
+    label: string;
+}
+/**
+ * A pluggable validator. Construct via `engine.validators.register(...)`.
+ * The `name` is opaque to the engine but is included in the
+ * `validationfailed` event payload so apps can route by source.
+ */
+export interface Validator {
+    name: string;
+    phase: ValidatorPhase;
+    run(host: EmapHostInternal, change: ValidationChange): Promise<ValidationReport>;
+}
+/** Per-validator outcome bundled into the `validationfailed` event. */
+export interface ValidatorResult {
+    validator: string;
+    report: ValidationReport;
+}