@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/web-components/measurement.js

@@ -0,0 +1,523 @@
+/**
+ * `<honua-measurement>` — the survival-tier distance/area measurement widget
+ * (issue #493).
+ *
+ * Unlike `<honua-measure-control>` (which requires a host-supplied drawing
+ * provider), this element ships a complete, deliberately simple drawing
+ * interaction on top of the map's own pointer events:
+ *
+ * - **click** adds a vertex;
+ * - **double-click** finishes the sketch (the map's double-click zoom is
+ *   suspended while a mode is active when the map exposes the handle);
+ * - **Escape** (or the Cancel button) discards the in-progress sketch.
+ *
+ * Distance and area are computed with the geodesic ops from the public
+ * `@honua/geometry` surface (`length` / `area`), so the widget's numbers match
+ * `geometryEngine` parity math everywhere else in the SDK.
+ *
+ * ## Wiring
+ * - `element.map = map` (any MapLibre `Map`; duck-typed via
+ *   {@link HonuaMeasurementMap}), or
+ * - declaratively via `for="<honua-map id>"` — the element listens for the
+ *   `honua-map-ready` event dispatched by `<honua-map>`.
+ *
+ * When the map exposes style mutation methods (`addSource` / `addLayer`), the
+ * in-progress sketch renders as a line + fill overlay in a
+ * `honua-measurement` GeoJSON source; on plain stubs the overlay is skipped.
+ *
+ * ## Accessibility
+ * Mode buttons are a `role="group"` of toggle buttons with `aria-pressed`;
+ * the live result is announced through a `role="status"` region; Finish /
+ * Cancel buttons provide keyboard-operable equivalents of double-click /
+ * Escape. Theme via the `--honua-ui-*` CSS custom properties.
+ *
+ * @module
+ */
+import { area as geodesicArea, length as geodesicLength } from "../geometry/index.js";
+const globalDom = globalThis;
+const HTMLElementBase = globalDom.HTMLElement ?? class {
+};
+const OVERLAY_SOURCE_ID = "honua-measurement";
+const OVERLAY_LINE_LAYER_ID = "honua-measurement-line";
+const OVERLAY_FILL_LAYER_ID = "honua-measurement-fill";
+export class HonuaMeasurementElement extends HTMLElementBase {
+    static get observedAttributes() {
+        return ["for", "label"];
+    }
+    #map;
+    #mode = "off";
+    #vertices = [];
+    #finished = false;
+    #result;
+    #connected = false;
+    #disposeMapReadyListener;
+    #clickListener;
+    #dblclickListener;
+    #keydownListener;
+    /** The MapLibre map this widget draws on. */
+    get map() {
+        return this.#map;
+    }
+    set map(map) {
+        if (this.#map === map)
+            return;
+        this.#deactivateDrawing();
+        this.#map = map;
+        if (this.#mode !== "off")
+            this.#activateDrawing();
+        this.render();
+    }
+    /** Wires the widget to a MapLibre map. Equivalent to setting `.map`. */
+    connect(map) {
+        this.map = map;
+    }
+    /** The active measure mode. */
+    get mode() {
+        return this.#mode;
+    }
+    /** The current (or last finished) measurement result. */
+    get result() {
+        return this.#result;
+    }
+    /** The in-progress vertex list (`[lng, lat]` positions). */
+    get vertices() {
+        return this.#vertices;
+    }
+    /** Activates a measure mode; `"off"` cancels any in-progress sketch. */
+    setMode(mode) {
+        if (this.#mode === mode)
+            return;
+        this.#deactivateDrawing();
+        this.#mode = mode;
+        this.#vertices = [];
+        this.#finished = false;
+        this.#result = undefined;
+        if (mode !== "off")
+            this.#activateDrawing();
+        this.#dispatchChange();
+        this.render();
+    }
+    /** Adds a vertex programmatically (same as a map click). */
+    addVertex(lngLat) {
+        if (this.#mode === "off")
+            return;
+        if (this.#finished) {
+            this.#vertices = [];
+            this.#finished = false;
+        }
+        this.#vertices = [...this.#vertices, [lngLat[0], lngLat[1]]];
+        this.#recompute();
+        this.#syncOverlay();
+        this.#dispatchChange();
+        this.render();
+    }
+    /** Finishes the in-progress sketch (same as double-click). */
+    finish() {
+        if (this.#mode === "off" || this.#vertices.length === 0 || this.#finished)
+            return;
+        this.#finished = true;
+        this.#recompute();
+        this.#syncOverlay();
+        this.#dispatchChange();
+        this.render();
+    }
+    /** Cancels the in-progress sketch (same as Escape); the mode stays active. */
+    cancel() {
+        if (this.#vertices.length === 0 && !this.#finished)
+            return;
+        this.#vertices = [];
+        this.#finished = false;
+        this.#result = undefined;
+        this.#syncOverlay();
+        this.#dispatchChange();
+        this.render();
+    }
+    attributeChangedCallback(name) {
+        if (name === "for") {
+            this.#resolveMapFromContext();
+            return;
+        }
+        this.render();
+    }
+    connectedCallback() {
+        this.#connected = true;
+        this.#ensureShadowRoot();
+        this.#listenForMapReady();
+        this.#resolveMapFromContext();
+        this.render();
+    }
+    disconnectedCallback() {
+        this.#connected = false;
+        this.#disposeMapReadyListener?.();
+        this.#disposeMapReadyListener = undefined;
+        this.#deactivateDrawing();
+    }
+    // ── drawing interaction ─────────────────────────────────────
+    #activateDrawing() {
+        const map = this.#map;
+        if (!map || this.#clickListener)
+            return;
+        const onClick = (event) => {
+            const lngLat = eventLngLat(event);
+            if (lngLat)
+                this.addVertex(lngLat);
+        };
+        const onDblclick = (event) => {
+            preventMapDefault(event);
+            // The double-click's own click events already appended a duplicate
+            // trailing vertex; drop it before finishing.
+            if (!this.#finished && this.#vertices.length >= 2) {
+                const last = this.#vertices[this.#vertices.length - 1];
+                const previous = this.#vertices[this.#vertices.length - 2];
+                if (last && previous && last[0] === previous[0] && last[1] === previous[1]) {
+                    this.#vertices = this.#vertices.slice(0, -1);
+                }
+            }
+            this.finish();
+        };
+        map.on("click", onClick);
+        map.on("dblclick", onDblclick);
+        map.doubleClickZoom?.disable?.();
+        this.#clickListener = onClick;
+        this.#dblclickListener = onDblclick;
+        if (typeof window !== "undefined" && !this.#keydownListener) {
+            const onKeydown = (event) => {
+                if (event.key === "Escape")
+                    this.cancel();
+            };
+            window.addEventListener("keydown", onKeydown);
+            this.#keydownListener = onKeydown;
+        }
+    }
+    #deactivateDrawing() {
+        const map = this.#map;
+        if (map) {
+            if (this.#clickListener)
+                map.off?.("click", this.#clickListener);
+            if (this.#dblclickListener)
+                map.off?.("dblclick", this.#dblclickListener);
+            map.doubleClickZoom?.enable?.();
+            this.#removeOverlay(map);
+        }
+        this.#clickListener = undefined;
+        this.#dblclickListener = undefined;
+        if (this.#keydownListener && typeof window !== "undefined") {
+            window.removeEventListener("keydown", this.#keydownListener);
+            this.#keydownListener = undefined;
+        }
+    }
+    #recompute() {
+        const mode = this.#mode;
+        const coordinates = this.#vertices;
+        if (mode === "off" || coordinates.length === 0) {
+            this.#result = undefined;
+            return;
+        }
+        const result = { mode, coordinates };
+        try {
+            if (mode === "distance" && coordinates.length >= 2) {
+                this.#result = {
+                    ...result,
+                    distance: geodesicLength({ type: "LineString", coordinates: coordinates.map(toPosition) }, "meters"),
+                };
+                return;
+            }
+            if (mode === "area" && coordinates.length >= 3) {
+                const ring = [...coordinates.map(toPosition), toPosition(coordinates[0])];
+                this.#result = {
+                    ...result,
+                    area: geodesicArea({ type: "Polygon", coordinates: [ring] }),
+                };
+                return;
+            }
+        }
+        catch {
+            // Degenerate geometry (repeated points, collinear ring): report the
+            // vertices without a computed value rather than throwing from an event.
+        }
+        this.#result = result;
+    }
+    // ── map overlay (best-effort; skipped on stubs) ─────────────
+    #syncOverlay() {
+        const map = this.#map;
+        if (!map?.addSource || !map.getSource)
+            return;
+        const data = this.#overlayGeoJson();
+        try {
+            const existing = map.getSource(OVERLAY_SOURCE_ID);
+            if (existing?.setData) {
+                existing.setData(data);
+                return;
+            }
+            map.addSource(OVERLAY_SOURCE_ID, { type: "geojson", data });
+            map.addLayer?.({
+                id: OVERLAY_FILL_LAYER_ID,
+                type: "fill",
+                source: OVERLAY_SOURCE_ID,
+                filter: ["==", ["geometry-type"], "Polygon"],
+                paint: { "fill-color": "#2563eb", "fill-opacity": 0.16 },
+            });
+            map.addLayer?.({
+                id: OVERLAY_LINE_LAYER_ID,
+                type: "line",
+                source: OVERLAY_SOURCE_ID,
+                paint: { "line-color": "#2563eb", "line-width": 2, "line-dasharray": [2, 1] },
+            });
+        }
+        catch {
+            // Overlay rendering is cosmetic; measurement math never depends on it.
+        }
+    }
+    #removeOverlay(map) {
+        try {
+            if (map.getLayer?.(OVERLAY_LINE_LAYER_ID))
+                map.removeLayer?.(OVERLAY_LINE_LAYER_ID);
+            if (map.getLayer?.(OVERLAY_FILL_LAYER_ID))
+                map.removeLayer?.(OVERLAY_FILL_LAYER_ID);
+            if (map.getSource?.(OVERLAY_SOURCE_ID))
+                map.removeSource?.(OVERLAY_SOURCE_ID);
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+    }
+    #overlayGeoJson() {
+        const coordinates = this.#vertices.map(toPosition);
+        const features = [];
+        if (this.#mode === "area" && coordinates.length >= 3) {
+            features.push({
+                type: "Feature",
+                properties: {},
+                geometry: { type: "Polygon", coordinates: [[...coordinates, coordinates[0]]] },
+            });
+        }
+        if (coordinates.length >= 2) {
+            features.push({
+                type: "Feature",
+                properties: {},
+                geometry: { type: "LineString", coordinates },
+            });
+        }
+        return { type: "FeatureCollection", features };
+    }
+    // ── map wiring (matches the `for` + honua-map-ready idiom) ──
+    #listenForMapReady() {
+        if (this.#disposeMapReadyListener)
+            return;
+        const target = this.#rootEventTarget();
+        if (!target)
+            return;
+        const listener = (event) => {
+            const detail = event.detail;
+            if (!detail?.map)
+                return;
+            const forId = this.#attr("for");
+            if (forId && event.target?.id !== forId)
+                return;
+            if (!forId && this.#map)
+                return;
+            this.map = detail.map;
+        };
+        target.addEventListener("honua-map-ready", listener);
+        this.#disposeMapReadyListener = () => target.removeEventListener("honua-map-ready", listener);
+    }
+    #resolveMapFromContext() {
+        if (this.#map)
+            return;
+        const forId = this.#attr("for");
+        if (!forId)
+            return;
+        const root = this.getRootNode?.();
+        const host = root && "getElementById" in root
+            ? root.getElementById(forId)
+            : typeof document !== "undefined"
+                ? document.getElementById(forId)
+                : null;
+        const map = host?.map;
+        if (map)
+            this.map = map;
+    }
+    #rootEventTarget() {
+        const root = this.getRootNode?.();
+        if (root && "addEventListener" in root)
+            return root;
+        return typeof document !== "undefined" ? document : undefined;
+    }
+    // ── rendering ──────────────────────────────────────────────
+    #ensureShadowRoot() {
+        if (!this.shadowRoot && typeof this.attachShadow === "function") {
+            this.attachShadow({ mode: "open" });
+        }
+    }
+    render() {
+        const root = this.shadowRoot;
+        if (!root || !this.#connected)
+            return;
+        const label = this.#attr("label") ?? "Measure";
+        const ready = this.#map !== undefined;
+        const sketchActive = this.#mode !== "off" && this.#vertices.length > 0 && !this.#finished;
+        root.innerHTML = `
+      <style>${structuralStyles()}</style>
+      <section class="panel" part="panel" aria-label="${escapeAttribute(label)}">
+        <div class="bar">
+          <h2>${escapeHtml(label)}</h2>
+          <span class="state">${escapeHtml(ready ? "ready" : "waiting for map")}</span>
+        </div>
+        <div class="segmented" role="group" aria-label="${escapeAttribute(`${label} mode`)}">
+          ${["off", "distance", "area"]
+            .map((mode) => `
+            <button type="button" part="mode" data-measure-mode="${mode}" aria-pressed="${String(this.#mode === mode)}"${ready || mode === "off" ? "" : " disabled"}>${escapeHtml(modeLabel(mode))}</button>
+          `)
+            .join("")}
+        </div>
+        <p class="value" part="value" role="status" aria-live="polite">${escapeHtml(this.#resultText())}</p>
+        <div class="actions">
+          <button type="button" part="finish" data-measure-finish${sketchActive ? "" : " disabled"}>Finish</button>
+          <button type="button" part="cancel" data-measure-cancel${this.#vertices.length > 0 ? "" : " disabled"}>Cancel</button>
+        </div>
+        <p class="hint">${escapeHtml(this.#mode === "off"
+            ? "Pick a mode, then click the map to add vertices."
+            : "Click adds a vertex; double-click or Finish completes; Escape or Cancel discards.")}</p>
+      </section>
+    `;
+        root.querySelectorAll("button[data-measure-mode]").forEach((button) => {
+            button.addEventListener("click", () => {
+                this.setMode((button.dataset.measureMode ?? "off"));
+            });
+        });
+        root.querySelector("button[data-measure-finish]")?.addEventListener("click", () => {
+            this.finish();
+        });
+        root.querySelector("button[data-measure-cancel]")?.addEventListener("click", () => {
+            this.cancel();
+        });
+    }
+    #resultText() {
+        const result = this.#result;
+        if (this.#mode === "off")
+            return "Measurement off.";
+        if (!result || this.#vertices.length === 0) {
+            return this.#mode === "distance" ? "Click the map to start a line." : "Click the map to outline an area.";
+        }
+        if (this.#mode === "distance") {
+            if (result.distance === undefined)
+                return `${this.#vertices.length} vertex — add another to measure.`;
+            return `Distance: ${formatDistance(result.distance)}${this.#finished ? " (finished)" : ""}`;
+        }
+        if (result.area === undefined) {
+            return `${this.#vertices.length} of 3 vertices needed for an area.`;
+        }
+        return `Area: ${formatArea(result.area)}${this.#finished ? " (finished)" : ""}`;
+    }
+    #dispatchChange() {
+        if (!globalDom.CustomEvent || typeof this.dispatchEvent !== "function")
+            return;
+        const detail = {
+            mode: this.#mode,
+            status: this.#map ? "ready" : "idle",
+            ...(this.#result ? { result: this.#result } : {}),
+        };
+        this.dispatchEvent(new globalDom.CustomEvent("honua-measure-change", { bubbles: true, composed: true, detail }));
+    }
+    #attr(name) {
+        return typeof this.getAttribute === "function" ? this.getAttribute(name) : null;
+    }
+}
+/** Registers `<honua-measurement>`; skipped when the tag is already defined. */
+export function defineHonuaMeasurement(registry = globalDom.customElements) {
+    if (!registry)
+        return;
+    if (!registry.get("honua-measurement")) {
+        registry.define("honua-measurement", HonuaMeasurementElement);
+    }
+}
+function toPosition(lngLat) {
+    return [lngLat[0], lngLat[1]];
+}
+function eventLngLat(event) {
+    if (typeof event !== "object" || event === null)
+        return undefined;
+    const lngLat = event.lngLat;
+    if (typeof lngLat?.lng === "number" && typeof lngLat.lat === "number") {
+        return [lngLat.lng, lngLat.lat];
+    }
+    return undefined;
+}
+function preventMapDefault(event) {
+    if (typeof event !== "object" || event === null)
+        return;
+    const preventDefault = event.preventDefault;
+    if (typeof preventDefault === "function")
+        preventDefault.call(event);
+}
+function formatDistance(meters) {
+    if (meters >= 1000)
+        return `${(meters / 1000).toFixed(2)} km`;
+    return `${meters.toFixed(1)} m`;
+}
+function formatArea(squareMeters) {
+    if (squareMeters >= 1_000_000)
+        return `${(squareMeters / 1_000_000).toFixed(2)} km²`;
+    if (squareMeters >= 10_000)
+        return `${(squareMeters / 10_000).toFixed(2)} ha`;
+    return `${squareMeters.toFixed(1)} m²`;
+}
+function modeLabel(mode) {
+    return mode.charAt(0).toUpperCase() + mode.slice(1);
+}
+/** Structural styles themable via the shared `--honua-ui-*` custom properties. */
+function structuralStyles() {
+    return `
+    :host {
+      --honua-ui-bg: #ffffff;
+      --honua-ui-fg: #172033;
+      --honua-ui-muted: #667085;
+      --honua-ui-border: #d0d5dd;
+      --honua-ui-accent: #1d4ed8;
+      --honua-ui-accent-fg: #ffffff;
+      box-sizing: border-box;
+      color: var(--honua-ui-fg);
+      display: block;
+      font: 14px/1.4 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    *, *::before, *::after { box-sizing: inherit; }
+    button {
+      border: 1px solid var(--honua-ui-border);
+      background: var(--honua-ui-bg);
+      border-radius: 6px;
+      color: inherit;
+      cursor: pointer;
+      font: inherit;
+      min-height: 32px;
+      padding: 0 10px;
+    }
+    button:disabled { cursor: not-allowed; opacity: 0.55; }
+    button[aria-pressed="true"] {
+      background: var(--honua-ui-accent);
+      border-color: var(--honua-ui-accent);
+      color: var(--honua-ui-accent-fg);
+    }
+    h2 { font-size: 14px; margin: 0; }
+    .panel {
+      background: var(--honua-ui-bg);
+      border: 1px solid var(--honua-ui-border);
+      border-radius: 8px;
+      display: grid;
+      gap: 10px;
+      min-width: 180px;
+      padding: 10px;
+    }
+    .bar { align-items: center; display: flex; gap: 8px; justify-content: space-between; }
+    .state { color: var(--honua-ui-muted); font-size: 12px; }
+    .segmented { display: grid; gap: 6px; grid-template-columns: repeat(auto-fit, minmax(72px, 1fr)); }
+    .actions { display: flex; gap: 6px; }
+    .value { margin: 0; }
+    .hint { color: var(--honua-ui-muted); font-size: 12px; margin: 0; }
+  `;
+}
+function escapeHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeAttribute(value) {
+    return escapeHtml(value).replace(/'/g, "&#39;");
+}

package/web-components/types.d.ts

@@ -10,6 +10,11 @@ export interface HonuaLayerModel {
     sourceId?: string;
     type?: string;
     visible: boolean;
+    /**
+     * Layer paint opacity in the `[0, 1]` range. `undefined` means the style's
+     * own opacity is untouched (treated as fully opaque by UI controls).
+     */
+    opacity?: number;
     metadata?: Record<string, unknown>;
 }
 export interface HonuaLegendItem {
@@ -149,6 +154,20 @@ export interface HonuaWebComponentController<T = Record<string, unknown>> {
     getState(): HonuaWebComponentState<T>;
     subscribe(listener: HonuaControllerStateListener<T>): HonuaControllerSubscription;
     setLayerVisibility(layerId: string, visible: boolean): void;
+    /**
+     * Sets a layer's paint opacity (clamped to `[0, 1]`). Optional so that
+     * pre-existing controller implementations keep compiling; `<honua-layer-list>`
+     * only renders opacity sliders when the controller implements it.
+     */
+    setLayerOpacity?(layerId: string, opacity: number): void;
+    /**
+     * Reorders a layer: inserts `layerId` before `beforeId` in the layer stack,
+     * or moves it to the end (rendered on top) when `beforeId` is omitted.
+     * Optional so that pre-existing controller implementations keep compiling;
+     * `<honua-layer-list>` only renders reorder affordances when the controller
+     * implements it.
+     */
+    moveLayer?(layerId: string, beforeId?: string): void;
     setViewport(viewport: HonuaViewportState): void;
     setFilter(filter: HonuaFilterState): void;
     selectFeature(selection: HonuaSelectionState<T>): void;
@@ -206,6 +225,10 @@ export interface HonuaWebComponentRuntimeLike<T = Record<string, unknown>> {
     };
     getLegend(): readonly HonuaMapPackageLegendEntry[];
     setLayerVisibility(layerId: string, visible: boolean): void;
+    /** Optional runtime support for writing layer paint opacity. */
+    setLayerOpacity?(layerId: string, opacity: number): void;
+    /** Optional runtime support for reordering layers (MapLibre `beforeId` semantics). */
+    moveLayer?(layerId: string, beforeId?: string): void;
     setViewState(viewport: HonuaViewportState): void;
     readonly dataset?: {
         source(id: string): {
@@ -231,6 +254,21 @@ export interface HonuaLayerVisibilityChangeDetail {
     layerId: string;
     visible: boolean;
 }
+/** Detail of the `honua-layer-opacity-change` event dispatched by `<honua-layer-list>`. */
+export interface HonuaLayerOpacityChangeDetail {
+    layerId: string;
+    /** New opacity in `[0, 1]`. */
+    opacity: number;
+}
+/** Detail of the `honua-layer-order-change` event dispatched by `<honua-layer-list>`. */
+export interface HonuaLayerOrderChangeDetail {
+    /** The layer that was moved. */
+    layerId: string;
+    /** Layer the moved layer was inserted before; absent when moved to the end (top). */
+    beforeId?: string;
+    /** Resulting layer id order (style order: last id renders on top). */
+    order: readonly string[];
+}
 export interface HonuaViewportChangeDetail extends HonuaViewportState {
 }
 export interface HonuaFilterChangeDetail extends HonuaFilterState {
@@ -270,6 +308,53 @@ export interface HonuaSearchDetail<T = Record<string, unknown>> {
     query: string;
     results: readonly HonuaSearchResult<T>[];
 }
+/**
+ * One typeahead suggestion rendered by `<honua-search>` when a geocoding
+ * provider is configured. Structurally compatible with the
+ * `GeocodeSuggestion` shape returned by `HonuaGeocodingClient.suggest`
+ * (`@honua/sdk-js/geocoding`).
+ */
+export interface HonuaSearchGeocodeSuggestion {
+    text: string;
+    magicKey?: string;
+}
+/**
+ * One forward-geocode candidate consumed by `<honua-search>`. Structurally
+ * compatible with the `GeocodeResult` shape returned by
+ * `HonuaGeocodingClient.forwardGeocode` (`@honua/sdk-js/geocoding`).
+ */
+export interface HonuaSearchGeocodeCandidate {
+    address: string;
+    latitude: number;
+    longitude: number;
+    score?: number;
+}
+/**
+ * Duck-typed geocoding provider accepted by the `<honua-search>` `geocoder`
+ * property. A `HonuaGeocodingClient` instance from the stable
+ * `@honua/sdk-js/geocoding` entrypoint satisfies this interface structurally
+ * — the web-component kit never imports the geocoding client itself, proving
+ * the provider seam. Custom providers (other geocoders, offline gazetteers)
+ * only need `forwardGeocode`; `suggest` powers debounced typeahead when
+ * available.
+ */
+export interface HonuaSearchGeocoderLike {
+    suggest?(text: string, options?: {
+        maxSuggestions?: number;
+    }): Promise<readonly HonuaSearchGeocodeSuggestion[]>;
+    forwardGeocode(address: string, options?: {
+        maxResults?: number;
+    }): Promise<readonly HonuaSearchGeocodeCandidate[]>;
+}
+/** Detail of the `honua-geocode-select` event dispatched by `<honua-search>`. */
+export interface HonuaGeocodeSelectDetail {
+    /** The query text that produced the candidate. */
+    query: string;
+    /** The chosen forward-geocode candidate. */
+    candidate: HonuaSearchGeocodeCandidate;
+    /** The viewport applied to the shared controller (center + zoom). */
+    viewport: HonuaViewportState;
+}
 export interface HonuaEditChangeDetail<T = Record<string, unknown>> {
     status: HonuaComponentStatus;
     request?: HonuaEditRequest<T>;
@@ -298,6 +383,30 @@ export interface HonuaLocateChangeDetail {
     message?: string;
 }
 export type HonuaMeasureMode = "off" | "distance" | "area";
+/**
+ * Minimal duck-typed subset of `maplibre-gl.Map` required by
+ * `<honua-measurement>`. Any MapLibre-GL `Map` instance satisfies this
+ * interface, and tests can pass a plain stub (matching the duck-typing
+ * posture of the `@honua/sdk-js/controls` kit and `src/runtime/runtime.ts`).
+ */
+export interface HonuaMeasurementMap {
+    /** Subscribes to map events (`click`, `dblclick`). */
+    on(type: string, listener: (event?: unknown) => void): unknown;
+    /** Unsubscribes a listener registered with `on`. */
+    off?(type: string, listener: (event?: unknown) => void): unknown;
+    /** Optional style access used to render the in-progress sketch overlay. */
+    addSource?(id: string, source: unknown): void;
+    getSource?(id: string): unknown;
+    addLayer?(layer: unknown, beforeId?: string): void;
+    removeLayer?(id: string): void;
+    getLayer?(id: string): unknown;
+    removeSource?(id: string): void;
+    /** Optional double-click-zoom handle disabled while a drawing mode is active. */
+    doubleClickZoom?: {
+        disable?(): void;
+        enable?(): void;
+    };
+}
 /**
  * A drawn measurement geometry plus its computed result.
  *