@honua/app-platform 0.0.20-alpha.0

package/style/specification.d.ts

@@ -0,0 +1,203 @@
+/**
+ * HonuaMapSpec — Honua-specific source type definitions extending MapLibre Style Spec v8.
+ *
+ * Defines three custom source types (`honua-feature-service`, `honua-map-service`,
+ * `honua-ogc-features`) and a `HonuaStyleSpecification` that widens the MapLibre
+ * style's `sources` map to accept them. Standard MapLibre layer types, paint/layout
+ * properties, and expressions are used unchanged.
+ *
+ * These types are standalone (zero dependency on `maplibre-gl` or
+ * `@maplibre/maplibre-gl-style-spec`), but structurally compatible — a
+ * `HonuaStyleSpecification` can be narrowed to `StyleSpecification` by filtering
+ * out Honua sources.
+ *
+ * @module
+ */
+/** Common fields shared by all Honua source specifications. */
+export interface HonuaSourceBase {
+    /** Full URL to the service endpoint. */
+    url: string;
+    /** Attribution string displayed on the map. */
+    attribution?: string;
+}
+/**
+ * A source backed by an Esri-compatible Feature Service layer.
+ *
+ * URL format: `https://host/rest/services/{serviceId}/FeatureServer/{layerId}`
+ */
+export interface HonuaFeatureServiceSourceSpecification extends HonuaSourceBase {
+    type: "honua-feature-service";
+    /** Server-side WHERE clause applied to all queries. */
+    definitionExpression?: string;
+    /** Fields to include in query responses. Defaults to all (`["*"]`). */
+    outFields?: string[];
+    /** Whether queries return geometry. Defaults to `true`. */
+    returnGeometry?: boolean;
+    /** Output spatial reference WKID (e.g. `4326`, `3857`). */
+    outSR?: number;
+}
+/**
+ * A source backed by an Esri-compatible Map Service (dynamic map export).
+ *
+ * URL format: `https://host/rest/services/{serviceId}/MapServer`
+ */
+export interface HonuaMapServiceSourceSpecification extends HonuaSourceBase {
+    type: "honua-map-service";
+    /** Comma-separated layer IDs to include (e.g. `"0,1,3"`). */
+    layers?: string;
+    /** Export DPI. Defaults to `96`. */
+    dpi?: number;
+    /** Image format. */
+    format?: "png" | "png24" | "png32" | "jpg" | "gif";
+    /** Whether the exported image has a transparent background. */
+    transparent?: boolean;
+}
+/**
+ * A source backed by an OGC API Features collection.
+ *
+ * URL format: `https://host/ogc/collections/{collectionId}` or
+ * `https://host/ogc` (with `collectionId` specified separately).
+ */
+export interface HonuaOgcFeaturesSourceSpecification extends HonuaSourceBase {
+    type: "honua-ogc-features";
+    /** The OGC collection identifier. Required if the URL does not include it. */
+    collectionId?: string;
+    /** Coordinate reference system URI (e.g. `"http://www.opengis.net/def/crs/OGC/1.3/CRS84"`). */
+    crs?: string;
+    /** CQL2 filter expression applied server-side. */
+    filter?: string;
+    /** Maximum items per request page. */
+    limit?: number;
+}
+/**
+ * A source backed by a first-party WMS 1.3.0 service.
+ *
+ * URL format: `https://host/rest/services/{serviceId}/MapServer/WMS`.
+ */
+export interface HonuaWmsSourceSpecification extends HonuaSourceBase {
+    type: "honua-wms";
+    /** Service identifier, when not parseable from the URL. */
+    serviceId?: string;
+    /** Comma-separated layer names (the WMS `LAYERS=` value). */
+    layers?: string;
+    /** Comma-separated style names (the WMS `STYLES=` value). */
+    styles?: string;
+    /** Image MIME type. Defaults to `image/png`. */
+    format?: string;
+    /** Whether the rendered image should be transparent. */
+    transparent?: boolean;
+    /** CRS code. Defaults to `EPSG:3857`. */
+    crs?: string;
+}
+/**
+ * A source backed by a first-party WMTS 1.0.0 service.
+ *
+ * URL format: `https://host/rest/services/{serviceId}/MapServer/WMTS`.
+ */
+export interface HonuaWmtsSourceSpecification extends HonuaSourceBase {
+    type: "honua-wmts";
+    /** Service identifier, when not parseable from the URL. */
+    serviceId?: string;
+    /** Layer identifier. */
+    layer?: string;
+    /** Style identifier. Defaults to `default`. */
+    style?: string;
+    /** TileMatrixSet identifier. Defaults to `WebMercatorQuad`. */
+    tileMatrixSet?: string;
+    /** Image MIME type. Defaults to `image/png`. */
+    format?: string;
+}
+/** Union of all Honua custom source types. */
+export type HonuaSourceSpecification = HonuaFeatureServiceSourceSpecification | HonuaMapServiceSourceSpecification | HonuaOgcFeaturesSourceSpecification | HonuaWmsSourceSpecification | HonuaWmtsSourceSpecification;
+/** Minimal layer shape compatible with MapLibre Style Spec v8. */
+export interface HonuaLayerSpecification {
+    id: string;
+    type: string;
+    source?: string;
+    "source-layer"?: string;
+    filter?: unknown;
+    layout?: Record<string, unknown>;
+    paint?: Record<string, unknown>;
+    minzoom?: number;
+    maxzoom?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A MapLibre Style Spec v8 document extended with Honua custom source types.
+ *
+ * Standard MapLibre sources (`vector`, `raster`, `geojson`, etc.) are accepted
+ * alongside Honua sources. Layer definitions use standard MapLibre types.
+ */
+export interface HonuaStyleSpecification {
+    version: 8;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    center?: [number, number];
+    zoom?: number;
+    bearing?: number;
+    pitch?: number;
+    sources: Record<string, HonuaSourceSpecification | {
+        type: string;
+        [key: string]: unknown;
+    }>;
+    layers: HonuaLayerSpecification[];
+    sprite?: string | {
+        id: string;
+        url: string;
+    }[];
+    glyphs?: string;
+    transition?: {
+        duration?: number;
+        delay?: number;
+    };
+}
+/** Test whether a source specification is any Honua custom type. */
+export declare function isHonuaSource(source: {
+    type: string;
+}): source is HonuaSourceSpecification;
+/** Test whether a source is a `honua-feature-service`. */
+export declare function isFeatureServiceSource(source: {
+    type: string;
+}): source is HonuaFeatureServiceSourceSpecification;
+/** Test whether a source is a `honua-map-service`. */
+export declare function isMapServiceSource(source: {
+    type: string;
+}): source is HonuaMapServiceSourceSpecification;
+/** Test whether a source is a `honua-ogc-features`. */
+export declare function isOgcFeaturesSource(source: {
+    type: string;
+}): source is HonuaOgcFeaturesSourceSpecification;
+/** Test whether a source is a `honua-wms`. */
+export declare function isWmsSource(source: {
+    type: string;
+}): source is HonuaWmsSourceSpecification;
+/** Test whether a source is a `honua-wmts`. */
+export declare function isWmtsSource(source: {
+    type: string;
+}): source is HonuaWmtsSourceSpecification;
+/** Parsed components of an OGC Features URL. */
+export interface ParsedOgcFeaturesUrl {
+    baseUrl: string;
+    collectionId: string | undefined;
+}
+/**
+ * Parse an OGC Features URL into baseUrl and optional collectionId.
+ *
+ * Accepts URLs like:
+ * - `https://gis.example.com/ogc/collections/admin-boundaries`
+ * - `https://gis.example.com/ogc` (collectionId provided separately)
+ */
+export declare function parseOgcFeaturesUrl(url: string): ParsedOgcFeaturesUrl;
+/** A validation error found in a HonuaStyleSpecification. */
+export interface StyleValidationError {
+    path: string;
+    message: string;
+}
+/**
+ * Validate a HonuaStyleSpecification for structural correctness.
+ *
+ * Returns an empty array if the style is valid. Does not validate MapLibre
+ * layer/expression semantics — use `@maplibre/maplibre-gl-style-spec` for that.
+ */
+export declare function validateHonuaStyle(style: unknown): StyleValidationError[];
+//# sourceMappingURL=specification.d.ts.map

package/style/specification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../../src/style/specification.ts"],"names":[],"mappings":"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"}

package/style/specification.js

@@ -0,0 +1,178 @@
+/**
+ * HonuaMapSpec — Honua-specific source type definitions extending MapLibre Style Spec v8.
+ *
+ * Defines three custom source types (`honua-feature-service`, `honua-map-service`,
+ * `honua-ogc-features`) and a `HonuaStyleSpecification` that widens the MapLibre
+ * style's `sources` map to accept them. Standard MapLibre layer types, paint/layout
+ * properties, and expressions are used unchanged.
+ *
+ * These types are standalone (zero dependency on `maplibre-gl` or
+ * `@maplibre/maplibre-gl-style-spec`), but structurally compatible — a
+ * `HonuaStyleSpecification` can be narrowed to `StyleSpecification` by filtering
+ * out Honua sources.
+ *
+ * @module
+ */
+// ── Type guards ──────────────────────────────────────────────
+/** Test whether a source specification is any Honua custom type. */
+export function isHonuaSource(source) {
+    return source.type.startsWith("honua-");
+}
+/** Test whether a source is a `honua-feature-service`. */
+export function isFeatureServiceSource(source) {
+    return source.type === "honua-feature-service";
+}
+/** Test whether a source is a `honua-map-service`. */
+export function isMapServiceSource(source) {
+    return source.type === "honua-map-service";
+}
+/** Test whether a source is a `honua-ogc-features`. */
+export function isOgcFeaturesSource(source) {
+    return source.type === "honua-ogc-features";
+}
+/** Test whether a source is a `honua-wms`. */
+export function isWmsSource(source) {
+    return source.type === "honua-wms";
+}
+/** Test whether a source is a `honua-wmts`. */
+export function isWmtsSource(source) {
+    return source.type === "honua-wmts";
+}
+/**
+ * Parse an OGC Features URL into baseUrl and optional collectionId.
+ *
+ * Accepts URLs like:
+ * - `https://gis.example.com/ogc/collections/admin-boundaries`
+ * - `https://gis.example.com/ogc` (collectionId provided separately)
+ */
+export function parseOgcFeaturesUrl(url) {
+    const absoluteUrl = parseAbsoluteHttpUrl(url);
+    const path = absoluteUrl ? absoluteUrl.pathname : stripQueryAndHash(url);
+    const normalizedPath = trimTrailingSlashes(path);
+    // Locate the first `/collections/` segment (case-insensitive) and split the
+    // path into basePath + collectionId. Linear `indexOf` scanning replaces the
+    // prior `/^(.*?)\/collections\/([^/?#]+)(?:\/.*)?$/i` regex, whose lazy
+    // leading `.*?` plus trailing alternation could backtrack super-linearly.
+    const collectionsToken = "/collections/";
+    const markerIndex = normalizedPath.toLowerCase().indexOf(collectionsToken);
+    if (markerIndex >= 0) {
+        const afterMarker = normalizedPath.slice(markerIndex + collectionsToken.length);
+        const nextSlash = afterMarker.indexOf("/");
+        const collectionId = nextSlash >= 0 ? afterMarker.slice(0, nextSlash) : afterMarker;
+        if (collectionId !== "") {
+            const basePath = normalizeCollectionBasePath(normalizedPath.slice(0, markerIndex), normalizedPath);
+            return {
+                baseUrl: joinUrlParts(absoluteUrl?.origin, basePath),
+                collectionId,
+            };
+        }
+    }
+    return {
+        baseUrl: joinUrlParts(absoluteUrl?.origin, normalizedPath),
+        collectionId: undefined,
+    };
+}
+function parseAbsoluteHttpUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+            return parsed;
+        }
+    }
+    catch {
+        // Relative URLs are handled by string parsing below.
+    }
+    return undefined;
+}
+function stripQueryAndHash(url) {
+    const hashIndex = url.indexOf("#");
+    const withoutHash = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+    const queryIndex = withoutHash.indexOf("?");
+    return queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash;
+}
+function trimTrailingSlashes(path) {
+    if (path === "/") {
+        return "/";
+    }
+    // Linear-time trailing-slash trim. Avoids the `/\/+$/` regex, whose
+    // anchored quantifier can backtrack super-linearly on long slash runs.
+    let end = path.length;
+    while (end > 0 && path.charCodeAt(end - 1) === 47 /* '/' */) {
+        end -= 1;
+    }
+    return end === path.length ? path : path.slice(0, end);
+}
+function normalizeCollectionBasePath(basePath, fullPath) {
+    const normalized = trimTrailingSlashes(basePath);
+    if (normalized.length > 0) {
+        return normalized;
+    }
+    return fullPath.startsWith("/") ? "/" : "";
+}
+function joinUrlParts(origin, path) {
+    if (!origin) {
+        return path;
+    }
+    if (path.length === 0 || path === "/") {
+        return origin;
+    }
+    return `${origin}${path.startsWith("/") ? path : `/${path}`}`;
+}
+/**
+ * Validate a HonuaStyleSpecification for structural correctness.
+ *
+ * Returns an empty array if the style is valid. Does not validate MapLibre
+ * layer/expression semantics — use `@maplibre/maplibre-gl-style-spec` for that.
+ */
+export function validateHonuaStyle(style) {
+    const errors = [];
+    if (typeof style !== "object" || style === null) {
+        errors.push({ path: "", message: "Style must be a non-null object" });
+        return errors;
+    }
+    const s = style;
+    if (s.version !== 8) {
+        errors.push({ path: "version", message: "Version must be 8" });
+    }
+    if (typeof s.sources !== "object" || s.sources === null || Array.isArray(s.sources)) {
+        errors.push({ path: "sources", message: "Sources must be a non-null object" });
+    }
+    else {
+        for (const [name, source] of Object.entries(s.sources)) {
+            if (typeof source !== "object" || source === null) {
+                errors.push({ path: `sources.${name}`, message: "Source must be a non-null object" });
+                continue;
+            }
+            const src = source;
+            if (typeof src.type !== "string") {
+                errors.push({ path: `sources.${name}.type`, message: "Source type must be a string" });
+                continue;
+            }
+            if (isHonuaSource(src)) {
+                if (typeof src.url !== "string") {
+                    errors.push({ path: `sources.${name}.url`, message: "Honua source must have a string url" });
+                }
+            }
+        }
+    }
+    if (!Array.isArray(s.layers)) {
+        errors.push({ path: "layers", message: "Layers must be an array" });
+    }
+    else {
+        for (let i = 0; i < s.layers.length; i++) {
+            const layer = s.layers[i];
+            if (typeof layer !== "object" || layer === null) {
+                errors.push({ path: `layers[${i}]`, message: "Layer must be a non-null object" });
+                continue;
+            }
+            const l = layer;
+            if (typeof l.id !== "string") {
+                errors.push({ path: `layers[${i}].id`, message: "Layer must have a string id" });
+            }
+            if (typeof l.type !== "string") {
+                errors.push({ path: `layers[${i}].type`, message: "Layer must have a string type" });
+            }
+        }
+    }
+    return errors;
+}

package/style/wms-wmts-resolvers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared resolvers that turn a `HonuaWmsSourceSpecification` /
+ * `HonuaWmtsSourceSpecification` into a runtime SDK handle. Used by both
+ * `src/style/factory.ts` (`createSources`) and `src/map/honua-map.ts`
+ * (`HonuaMap.getSource`) so the URL-parsing and handle-selection rules
+ * stay identical between the two surfaces.
+ *
+ * @module
+ */
+import type { HonuaClient } from "../core/client.js";
+import { HonuaWms, HonuaWmsLayer } from "../core/wms.js";
+import { HonuaWmts, HonuaWmtsTileset } from "../core/wmts.js";
+import type { HonuaWmsSourceSpecification, HonuaWmtsSourceSpecification } from "./specification.js";
+/**
+ * Extract the service id from a WMS/WMTS endpoint URL. Returns
+ * `undefined` if the URL does not match a known service shape so the
+ * caller can fall back to the spec's explicit `serviceId` (or surface a
+ * typed error).
+ */
+export declare function parseWmsServiceIdFromUrl(url: string): string | undefined;
+/**
+ * Resolve a `honua-wms` source spec to a runtime handle. Returns the
+ * layer-bound `HonuaWmsLayer` only when `spec.layers` parses to exactly
+ * one non-empty layer token, because `HonuaWmsLayer` is a single-layer
+ * handle (its `describe()` resolves one `<Layer>` from the parsed
+ * Capabilities). Multi-layer composites (`LAYERS=a,b`) and
+ * empty / missing values stay on the service-level `HonuaWms` handle so
+ * `map()` / `featureInfo()` can still target the composite.
+ */
+export declare function resolveWmsSpec(client: HonuaClient, spec: HonuaWmsSourceSpecification): HonuaWms | HonuaWmsLayer;
+/**
+ * Resolve a `honua-wmts` source spec to a runtime handle. Returns the
+ * (layer × style × TileMatrixSet) `HonuaWmtsTileset` when the spec
+ * pins a single layer; otherwise returns the service-level `HonuaWmts`
+ * handle.
+ */
+export declare function resolveWmtsSpec(client: HonuaClient, spec: HonuaWmtsSourceSpecification): HonuaWmts | HonuaWmtsTileset;
+//# sourceMappingURL=wms-wmts-resolvers.d.ts.map

package/style/wms-wmts-resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wms-wmts-resolvers.d.ts","sourceRoot":"","sources":["../../../src/style/wms-wmts-resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAsB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAWpG;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,2BAA2B,GAAG,QAAQ,GAAG,aAAa,CAmB/G;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,4BAA4B,GAAG,SAAS,GAAG,gBAAgB,CAkBrH"}

package/style/wms-wmts-resolvers.js

@@ -0,0 +1,92 @@
+/**
+ * Shared resolvers that turn a `HonuaWmsSourceSpecification` /
+ * `HonuaWmtsSourceSpecification` into a runtime SDK handle. Used by both
+ * `src/style/factory.ts` (`createSources`) and `src/map/honua-map.ts`
+ * (`HonuaMap.getSource`) so the URL-parsing and handle-selection rules
+ * stay identical between the two surfaces.
+ *
+ * @module
+ */
+import { HonuaWms, HonuaWmsLayer, parseWmsLayerNames } from "../core/wms.js";
+import { HonuaWmts, HonuaWmtsTileset } from "../core/wmts.js";
+/**
+ * Match the canonical Esri MapServer WMS/WMTS endpoint shape
+ * (`/rest/services/<name>/MapServer/{WMS|WMTS}`) and the OGC web-map
+ * shape (`/ogc/services/<name>/{wms|wmts}`) so we can lift the service
+ * id out of the URL when the spec did not carry it explicitly.
+ */
+const HONUA_WMS_WMTS_URL_RE = /\/(?:rest\/services\/([^/?#]+)\/MapServer\/(?:WMS|WMTS)|ogc\/services\/([^/?#]+)\/(?:wms|wmts))/i;
+/**
+ * Extract the service id from a WMS/WMTS endpoint URL. Returns
+ * `undefined` if the URL does not match a known service shape so the
+ * caller can fall back to the spec's explicit `serviceId` (or surface a
+ * typed error).
+ */
+export function parseWmsServiceIdFromUrl(url) {
+    const match = HONUA_WMS_WMTS_URL_RE.exec(url);
+    if (!match)
+        return undefined;
+    const id = match[1] ?? match[2];
+    if (!id)
+        return undefined;
+    try {
+        return decodeURIComponent(id);
+    }
+    catch {
+        return id;
+    }
+}
+/**
+ * Resolve a `honua-wms` source spec to a runtime handle. Returns the
+ * layer-bound `HonuaWmsLayer` only when `spec.layers` parses to exactly
+ * one non-empty layer token, because `HonuaWmsLayer` is a single-layer
+ * handle (its `describe()` resolves one `<Layer>` from the parsed
+ * Capabilities). Multi-layer composites (`LAYERS=a,b`) and
+ * empty / missing values stay on the service-level `HonuaWms` handle so
+ * `map()` / `featureInfo()` can still target the composite.
+ */
+export function resolveWmsSpec(client, spec) {
+    const serviceId = spec.serviceId ?? parseWmsServiceIdFromUrl(spec.url);
+    if (!serviceId) {
+        throw new Error("honua-wms source requires either serviceId or a URL containing the service id");
+    }
+    const root = new HonuaWms({ client, serviceId });
+    const parsedLayers = parseWmsLayerNames(spec.layers);
+    if (parsedLayers.length === 1) {
+        const opts = {
+            client,
+            serviceId,
+            layerName: parsedLayers[0],
+        };
+        if (typeof spec.styles === "string" && spec.styles.length > 0) {
+            opts.defaultStyleId = spec.styles;
+        }
+        return new HonuaWmsLayer(opts);
+    }
+    return root;
+}
+/**
+ * Resolve a `honua-wmts` source spec to a runtime handle. Returns the
+ * (layer × style × TileMatrixSet) `HonuaWmtsTileset` when the spec
+ * pins a single layer; otherwise returns the service-level `HonuaWmts`
+ * handle.
+ */
+export function resolveWmtsSpec(client, spec) {
+    const serviceId = spec.serviceId ?? parseWmsServiceIdFromUrl(spec.url);
+    if (!serviceId) {
+        throw new Error("honua-wmts source requires either serviceId or a URL containing the service id");
+    }
+    const root = new HonuaWmts({ client, serviceId });
+    if (typeof spec.layer === "string" && spec.layer.length > 0) {
+        const style = spec.style ?? "default";
+        const tms = spec.tileMatrixSet ?? "WebMercatorQuad";
+        return new HonuaWmtsTileset({
+            client,
+            serviceId,
+            layerName: spec.layer,
+            styleId: style,
+            tileMatrixSetId: tms,
+        });
+    }
+    return root;
+}

package/web-components/controller.d.ts

@@ -0,0 +1,39 @@
+import type { HonuaLayerSpecification } from "../style/index.js";
+import type { CreateHonuaWebComponentControllerOptions, HonuaControllerStateListener, HonuaEditorModel, HonuaFeatureRecord, HonuaFeatureStateTarget, HonuaFeatureTableModel, HonuaFilterState, HonuaLayerModel, HonuaLegendItem, HonuaMeasureChangeDetail, HonuaMeasureMode, HonuaQueryFeaturesOptions, HonuaSearchOptions, HonuaSearchResult, HonuaSelectionState, HonuaSketchChangeDetail, HonuaSketchMode, HonuaViewportState, HonuaWebComponentController, HonuaWebComponentRuntimeLike, HonuaWebComponentState } from "./types.js";
+export declare class HonuaInMemoryWebComponentController<T = Record<string, unknown>> implements HonuaWebComponentController<T> {
+    #private;
+    constructor(options?: CreateHonuaWebComponentControllerOptions<T> & {
+        runtime?: HonuaWebComponentRuntimeLike<T>;
+    });
+    getState(): HonuaWebComponentState<T>;
+    subscribe(listener: HonuaControllerStateListener<T>): {
+        remove(): void;
+    };
+    setLayerVisibility(layerId: string, visible: boolean): void;
+    setViewport(viewport: HonuaViewportState): void;
+    setFilter(filter: HonuaFilterState): void;
+    selectFeature(selection: HonuaSelectionState<T>): void;
+    clearSelection(): void;
+    setFeatureState(target: HonuaFeatureStateTarget, state: Record<string, unknown>): void;
+    removeFeatureState(target: HonuaFeatureStateTarget, key?: string): void;
+    queryFeatures(sourceId?: string | undefined, options?: HonuaQueryFeaturesOptions): Promise<HonuaFeatureTableModel<T>>;
+    search(query: string, options?: HonuaSearchOptions): Promise<readonly HonuaSearchResult<T>[]>;
+    applyEdit(): Promise<HonuaEditorModel>;
+    updateFeatures(sourceId: string, features: readonly HonuaFeatureRecord<T>[]): void;
+    canMeasure(): boolean;
+    canSketch(): boolean;
+    setMeasureMode(mode: HonuaMeasureMode): Promise<HonuaMeasureChangeDetail>;
+    setSketchMode(mode: HonuaSketchMode): Promise<HonuaSketchChangeDetail<T>>;
+    destroy(): void;
+}
+export declare function createHonuaWebComponentController<T = Record<string, unknown>>(options?: CreateHonuaWebComponentControllerOptions<T>): HonuaWebComponentController<T>;
+export declare function createHonuaWebComponentControllerFromRuntime<T = Record<string, unknown>>(runtime: HonuaWebComponentRuntimeLike<T>, options?: Omit<CreateHonuaWebComponentControllerOptions<T>, "mapPackage" | "layers" | "legend" | "viewport">): HonuaWebComponentController<T>;
+export declare function layersFromMapPackage(layers: readonly HonuaLayerSpecification[]): HonuaLayerModel[];
+export declare function legendFromMapPackage(entries: readonly {
+    label: string;
+    color?: string;
+    iconUrl?: string;
+    minValue?: number;
+    maxValue?: number;
+}[] | undefined, layers: readonly HonuaLayerModel[], styleLayers: readonly HonuaLayerSpecification[]): HonuaLegendItem[];
+//# sourceMappingURL=controller.d.ts.map

package/web-components/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/web-components/controller.ts"],"names":[],"mappings":"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"}