@honua/react 0.0.20-alpha.0

package/map/maplibre-target.d.ts

@@ -0,0 +1,103 @@
+import type { HonuaFeatureServiceSourceSpecification, HonuaLayerSpecification, HonuaMapServiceSourceSpecification, HonuaStyleSpecification } from "../style/specification.js";
+/** Standard MapLibre raster source shape used by migrated tiled services. */
+export interface HonuaMapLibreRasterSourceSpecification {
+    [key: string]: unknown;
+    type: "raster";
+    tiles: string[];
+    tileSize?: number;
+    attribution?: string;
+}
+/** Layer/source pair consumed by {@link createHonuaMapLibreStyle}. */
+export interface HonuaMapLibreLayerDefinition {
+    id: string;
+    sourceId: string;
+    source: HonuaFeatureServiceSourceSpecification | HonuaMapServiceSourceSpecification | HonuaMapLibreRasterSourceSpecification;
+    layer: HonuaLayerSpecification;
+}
+/** Shared options for migrated ArcGIS layer constructors. */
+export interface HonuaMapLibreLayerOptionsBase {
+    id?: string;
+    title?: string;
+    visible?: boolean;
+    opacity?: number;
+    minScale?: number;
+    maxScale?: number;
+    attribution?: string;
+    paint?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+}
+/** Options for an ArcGIS FeatureLayer migrated into a Honua feature-service source. */
+export interface HonuaFeatureServiceLayerOptions extends HonuaMapLibreLayerOptionsBase {
+    url: string;
+    outFields?: string[];
+    definitionExpression?: string;
+    returnGeometry?: boolean;
+    outSR?: number;
+    layerType?: "circle" | "line" | "fill";
+}
+/** Options for an ArcGIS MapImageLayer migrated into a Honua map-service source. */
+export interface HonuaMapServiceLayerOptions extends HonuaMapLibreLayerOptionsBase {
+    url: string;
+    sublayers?: unknown;
+    layers?: string;
+    dpi?: number;
+    format?: "png" | "png24" | "png32" | "jpg" | "gif";
+    transparent?: boolean;
+}
+/** Options for an ArcGIS TileLayer migrated into a MapLibre raster tile source. */
+export interface HonuaTileServiceLayerOptions extends HonuaMapLibreLayerOptionsBase {
+    url: string;
+    tileSize?: number;
+}
+/** Options for an ArcGIS Map migrated into a MapLibre style document. */
+export interface HonuaMapLibreStyleOptions {
+    basemap?: string;
+    layers?: readonly HonuaMapLibreLayerDefinition[];
+    name?: string;
+    center?: [number, number];
+    zoom?: number;
+}
+/** Options for an ArcGIS MapView migrated into MapLibre's `Map` constructor. */
+export interface HonuaMapLibreMapOptions {
+    map?: HonuaStyleSpecification;
+    style?: HonuaStyleSpecification;
+    container?: string | HTMLElement;
+    center?: [number, number];
+    zoom?: number;
+    bearing?: number;
+    pitch?: number;
+}
+/**
+ * Create a Honua feature-service source and a default MapLibre render layer.
+ *
+ * The returned `source` carries the custom `honua-feature-service` type, which
+ * MapLibre's renderer does not understand on its own — adding it to a
+ * `maplibre-gl` `Map` directly is a silent no-op. To render it, run the layer's
+ * source through the MapLibre runtime adapter
+ * (`loadHonuaFeatureServiceGeoJson` / `registerHonuaFeatureServiceSources` from
+ * `@honua/sdk-js/map`), which fetches features via the SDK and produces a
+ * standard `geojson` source. This differs from
+ * {@link createHonuaTileServiceLayer}, which emits a native MapLibre `raster`
+ * source that renders without an adapter.
+ *
+ * @see loadHonuaFeatureServiceGeoJson
+ * @see registerHonuaFeatureServiceSources
+ */
+export declare function createHonuaFeatureServiceLayer(options: HonuaFeatureServiceLayerOptions): HonuaMapLibreLayerDefinition;
+/**
+ * Create a Honua map-service source and a default MapLibre raster layer.
+ */
+export declare function createHonuaMapServiceLayer(options: HonuaMapServiceLayerOptions): HonuaMapLibreLayerDefinition;
+/**
+ * Create a MapLibre raster source and layer for an ArcGIS tiled service.
+ */
+export declare function createHonuaTileServiceLayer(options: HonuaTileServiceLayerOptions): HonuaMapLibreLayerDefinition;
+/**
+ * Create a MapLibre style document from migrated ArcGIS `Map` options.
+ */
+export declare function createHonuaMapLibreStyle(options?: HonuaMapLibreStyleOptions): HonuaStyleSpecification;
+/**
+ * Create the options object passed to `new maplibregl.Map(...)`.
+ */
+export declare function createHonuaMapLibreMapOptions(options: HonuaMapLibreMapOptions): Record<string, unknown>;
+//# sourceMappingURL=maplibre-target.d.ts.map

package/map/maplibre-target.d.ts.map

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

package/map/maplibre-target.js

@@ -0,0 +1,164 @@
+import { stripQueryAndFragment, trimTrailingSlashes } from "../core/path-utils.js";
+/**
+ * Create a Honua feature-service source and a default MapLibre render layer.
+ *
+ * The returned `source` carries the custom `honua-feature-service` type, which
+ * MapLibre's renderer does not understand on its own — adding it to a
+ * `maplibre-gl` `Map` directly is a silent no-op. To render it, run the layer's
+ * source through the MapLibre runtime adapter
+ * (`loadHonuaFeatureServiceGeoJson` / `registerHonuaFeatureServiceSources` from
+ * `@honua/sdk-js/map`), which fetches features via the SDK and produces a
+ * standard `geojson` source. This differs from
+ * {@link createHonuaTileServiceLayer}, which emits a native MapLibre `raster`
+ * source that renders without an adapter.
+ *
+ * @see loadHonuaFeatureServiceGeoJson
+ * @see registerHonuaFeatureServiceSources
+ */
+export function createHonuaFeatureServiceLayer(options) {
+    const sourceId = normalizeLayerId(options.id, options.title, options.url, "feature-service");
+    const layerType = options.layerType ?? "circle";
+    const source = {
+        type: "honua-feature-service",
+        url: options.url,
+        ...(options.attribution ? { attribution: options.attribution } : {}),
+        ...(options.definitionExpression ? { definitionExpression: options.definitionExpression } : {}),
+        ...(options.outFields ? { outFields: [...options.outFields] } : {}),
+        ...(options.returnGeometry !== undefined ? { returnGeometry: options.returnGeometry } : {}),
+        ...(options.outSR !== undefined ? { outSR: options.outSR } : {}),
+    };
+    return {
+        id: sourceId,
+        sourceId,
+        source,
+        layer: buildLayer(sourceId, layerType, options),
+    };
+}
+/**
+ * Create a Honua map-service source and a default MapLibre raster layer.
+ */
+export function createHonuaMapServiceLayer(options) {
+    const sourceId = normalizeLayerId(options.id, options.title, options.url, "map-service");
+    const source = {
+        type: "honua-map-service",
+        url: options.url,
+        ...(options.attribution ? { attribution: options.attribution } : {}),
+        ...(options.layers ? { layers: options.layers } : {}),
+        ...(options.dpi !== undefined ? { dpi: options.dpi } : {}),
+        ...(options.format ? { format: options.format } : {}),
+        ...(options.transparent !== undefined ? { transparent: options.transparent } : {}),
+    };
+    return {
+        id: sourceId,
+        sourceId,
+        source,
+        layer: buildLayer(sourceId, "raster", options),
+    };
+}
+/**
+ * Create a MapLibre raster source and layer for an ArcGIS tiled service.
+ */
+export function createHonuaTileServiceLayer(options) {
+    const sourceId = normalizeLayerId(options.id, options.title, options.url, "tile-service");
+    const baseUrl = trimTrailingSlashes(options.url);
+    const source = {
+        type: "raster",
+        tiles: [`${baseUrl}/tile/{z}/{y}/{x}`],
+        tileSize: options.tileSize ?? 256,
+        ...(options.attribution ? { attribution: options.attribution } : {}),
+    };
+    return {
+        id: sourceId,
+        sourceId,
+        source,
+        layer: buildLayer(sourceId, "raster", options),
+    };
+}
+/**
+ * Create a MapLibre style document from migrated ArcGIS `Map` options.
+ */
+export function createHonuaMapLibreStyle(options = {}) {
+    const sources = {};
+    const layers = [];
+    for (const layer of options.layers ?? []) {
+        sources[layer.sourceId] = layer.source;
+        layers.push(layer.layer);
+    }
+    return {
+        version: 8,
+        ...(options.name ? { name: options.name } : {}),
+        ...(options.center ? { center: options.center } : {}),
+        ...(options.zoom !== undefined ? { zoom: options.zoom } : {}),
+        metadata: options.basemap ? { "honua:arcgis-basemap": options.basemap } : undefined,
+        sources,
+        layers,
+    };
+}
+/**
+ * Create the options object passed to `new maplibregl.Map(...)`.
+ */
+export function createHonuaMapLibreMapOptions(options) {
+    const style = options.style ?? options.map ?? createHonuaMapLibreStyle();
+    return {
+        style,
+        ...(options.container !== undefined ? { container: options.container } : {}),
+        ...(options.center ? { center: options.center } : {}),
+        ...(options.zoom !== undefined ? { zoom: options.zoom } : {}),
+        ...(options.bearing !== undefined ? { bearing: options.bearing } : {}),
+        ...(options.pitch !== undefined ? { pitch: options.pitch } : {}),
+    };
+}
+function buildLayer(sourceId, type, options) {
+    return {
+        id: `${sourceId}-${type}`,
+        source: sourceId,
+        type,
+        ...(options.visible === false ? { layout: { ...(options.layout ?? {}), visibility: "none" } } : {}),
+        ...(options.visible !== false && options.layout ? { layout: options.layout } : {}),
+        ...(options.paint || options.opacity !== undefined ? { paint: buildPaint(type, options) } : {}),
+        ...(options.minScale !== undefined ? { minzoom: scaleToZoom(options.minScale) } : {}),
+        ...(options.maxScale !== undefined ? { maxzoom: scaleToZoom(options.maxScale) } : {}),
+        metadata: {
+            ...(options.title ? { title: options.title } : {}),
+            ...(options.id ? { "honua:source-id": options.id } : {}),
+        },
+    };
+}
+function buildPaint(type, options) {
+    const paint = { ...(options.paint ?? {}) };
+    if (options.opacity === undefined) {
+        return paint;
+    }
+    if (type === "circle")
+        paint["circle-opacity"] = options.opacity;
+    if (type === "line")
+        paint["line-opacity"] = options.opacity;
+    if (type === "fill")
+        paint["fill-opacity"] = options.opacity;
+    if (type === "raster")
+        paint["raster-opacity"] = options.opacity;
+    return paint;
+}
+function normalizeLayerId(id, title, url, fallback) {
+    return sanitizeId(id ?? title ?? lastUrlSegment(url) ?? fallback);
+}
+function lastUrlSegment(url) {
+    const trimmed = trimTrailingSlashes(stripQueryAndFragment(url));
+    const segment = trimmed.slice(trimmed.lastIndexOf("/") + 1);
+    return segment || undefined;
+}
+function sanitizeId(value) {
+    const id = value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^A-Za-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    return id || "layer";
+}
+function scaleToZoom(scale) {
+    if (!Number.isFinite(scale) || scale <= 0) {
+        return 0;
+    }
+    return Math.max(0, Math.log2(591657550.5 / scale));
+}

package/map/webmap-maplibre.d.ts

@@ -0,0 +1,60 @@
+/**
+ * WebMap JSON → MapLibre style derivation for the `honua-maplibre`
+ * migration target.
+ *
+ * This module is a thin orchestrator on top of `src/webmap/parseWebMap`
+ * (which already converts basemap, operational layers, renderers, popups,
+ * labels, and extents) plus a structured-gap classifier that records the
+ * unsupported constructs the migration punch list cares about:
+ *
+ *   - Arcade expressions (popupInfo.expressionInfos, label Arcade)
+ *   - Unknown / unsupported renderer types (heatmap, dotDensity, …)
+ *   - 3D / Scene references (ground, viewingMode, SceneServiceLayer, …)
+ *   - Dashboard / ExperienceBuilder / custom-widget host shells
+ *
+ * The function is pure: callers supply the WebMap JSON, no network or
+ * disk I/O is performed.
+ *
+ * @module
+ */
+import type { HonuaStyleSpecification } from "../style/specification.js";
+import type { WebMapJson } from "../webmap/types.js";
+/** Stable taxonomy for the gaps the punch list expects callers to handle. */
+export type WebMapMapLibreGapKind = "arcade-expression" | "unsupported-renderer" | "scene-3d" | "dashboard-reference" | "experience-builder-reference" | "custom-widget-reference" | "unsupported-symbol" | "unsupported-layer-type" | "unsupported-feature-collection" | "unsupported-webmap-version" | "other";
+/** A single unsupported construct discovered while deriving the style. */
+export interface WebMapMapLibreManualGap {
+    kind: WebMapMapLibreGapKind;
+    /** Human-readable explanation surfaced in reports / TODO annotations. */
+    reason: string;
+    /** Path within the WebMap JSON (e.g. `operationalLayers[2].popupInfo`). */
+    path?: string;
+    /** Operational layer id, when the gap is attributable to a specific layer. */
+    layerId?: string;
+    /** The offending Arcade expression text, when applicable. */
+    expression?: string;
+    /** Extra context (renderer type, scene layer URL, widget name, …). */
+    context?: Record<string, unknown>;
+}
+export interface WebMapJsonToMapLibreStyleOptions {
+    /** Whether to include the basemap in the derived style. Defaults to true. */
+    includeBasemap?: boolean;
+}
+export interface WebMapJsonToMapLibreStyleResult {
+    /** A MapLibre-shaped style document suitable for `map.setStyle(...)`. */
+    style: HonuaStyleSpecification;
+    /** Structured gap entries — one per unsupported construct. */
+    manualGaps: WebMapMapLibreManualGap[];
+}
+/**
+ * Derive a MapLibre style document from an ArcGIS WebMap JSON payload.
+ *
+ * Reuses the entire `src/webmap/*` conversion pipeline (`convertBasemap`,
+ * `convertOperationalLayer`, `convertRenderer`, `convertPopupInfo`,
+ * `convertLabelingInfo`, `convertExtent`) via `parseWebMap`. The
+ * `parseWebMap` warnings are then mapped onto the structured `manualGaps`
+ * taxonomy, and additional gaps are appended for Dashboard /
+ * ExperienceBuilder / custom-widget shell properties that the WebMap
+ * converter itself doesn't model.
+ */
+export declare function webmapJsonToMapLibreStyle(webmap: WebMapJson, options?: WebMapJsonToMapLibreStyleOptions): WebMapJsonToMapLibreStyleResult;
+//# sourceMappingURL=webmap-maplibre.d.ts.map

package/map/webmap-maplibre.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmap-maplibre.d.ts","sourceRoot":"","sources":["../../../src/map/webmap-maplibre.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB,GAC7B,mBAAmB,GACnB,sBAAsB,GACtB,UAAU,GACV,qBAAqB,GACrB,8BAA8B,GAC9B,yBAAyB,GACzB,oBAAoB,GACpB,wBAAwB,GACxB,gCAAgC,GAChC,4BAA4B,GAC5B,OAAO,CAAC;AAEZ,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gCAAgC;IAC/C,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B;IAC9C,yEAAyE;IACzE,KAAK,EAAE,uBAAuB,CAAC;IAC/B,8DAA8D;IAC9D,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,gCAAqC,GAC7C,+BAA+B,CAyBjC"}

package/map/webmap-maplibre.js

@@ -0,0 +1,212 @@
+/**
+ * WebMap JSON → MapLibre style derivation for the `honua-maplibre`
+ * migration target.
+ *
+ * This module is a thin orchestrator on top of `src/webmap/parseWebMap`
+ * (which already converts basemap, operational layers, renderers, popups,
+ * labels, and extents) plus a structured-gap classifier that records the
+ * unsupported constructs the migration punch list cares about:
+ *
+ *   - Arcade expressions (popupInfo.expressionInfos, label Arcade)
+ *   - Unknown / unsupported renderer types (heatmap, dotDensity, …)
+ *   - 3D / Scene references (ground, viewingMode, SceneServiceLayer, …)
+ *   - Dashboard / ExperienceBuilder / custom-widget host shells
+ *
+ * The function is pure: callers supply the WebMap JSON, no network or
+ * disk I/O is performed.
+ *
+ * @module
+ */
+import { parseWebMap } from "../webmap/parse.js";
+/**
+ * Derive a MapLibre style document from an ArcGIS WebMap JSON payload.
+ *
+ * Reuses the entire `src/webmap/*` conversion pipeline (`convertBasemap`,
+ * `convertOperationalLayer`, `convertRenderer`, `convertPopupInfo`,
+ * `convertLabelingInfo`, `convertExtent`) via `parseWebMap`. The
+ * `parseWebMap` warnings are then mapped onto the structured `manualGaps`
+ * taxonomy, and additional gaps are appended for Dashboard /
+ * ExperienceBuilder / custom-widget shell properties that the WebMap
+ * converter itself doesn't model.
+ */
+export function webmapJsonToMapLibreStyle(webmap, options = {}) {
+    const parsed = parseWebMap(webmap, {
+        includeBasemap: options.includeBasemap !== false,
+    });
+    const manualGaps = [];
+    for (const warning of parsed.warnings) {
+        const gap = classifyWarning(warning, webmap);
+        if (gap) {
+            manualGaps.push(gap);
+        }
+    }
+    // Detect Dashboard / ExperienceBuilder / custom-widget shells that
+    // `parseWebMap` does not model. These appear at the top of WebMap-
+    // adjacent application documents (Dashboards, Experience Builder
+    // configs, web-app items) and on the WebMap when authored by those
+    // apps. We never raise the renderer/popup conversion result over
+    // them — we only record a gap so the caller can replan that surface.
+    detectShellGaps(webmap, manualGaps);
+    return {
+        style: parsed.style,
+        manualGaps,
+    };
+}
+// ── Internals ───────────────────────────────────────────────────────────
+function classifyWarning(warning, webmap) {
+    const layerId = resolveLayerIdFromPath(warning.path, webmap);
+    const base = {
+        path: warning.path,
+        ...(layerId ? { layerId } : {}),
+        ...(warning.context ? { context: warning.context } : {}),
+    };
+    switch (warning.code) {
+        case "unsupported-arcade-expression":
+        case "complex-arcade":
+        case "complex-label-expression": {
+            const expression = pickStringContext(warning.context, ["expression", "value"]);
+            return {
+                kind: "arcade-expression",
+                reason: warning.message,
+                ...(expression ? { expression } : {}),
+                ...base,
+            };
+        }
+        case "unsupported-renderer": {
+            return {
+                kind: "unsupported-renderer",
+                reason: warning.message,
+                ...base,
+            };
+        }
+        case "unsupported-3d-property": {
+            return {
+                kind: "scene-3d",
+                reason: warning.message,
+                ...base,
+            };
+        }
+        case "unsupported-symbol":
+            return { kind: "unsupported-symbol", reason: warning.message, ...base };
+        case "unsupported-layer-type":
+            return { kind: "unsupported-layer-type", reason: warning.message, ...base };
+        case "unsupported-feature-collection":
+            return { kind: "unsupported-feature-collection", reason: warning.message, ...base };
+        case "unsupported-webmap-version":
+            return { kind: "unsupported-webmap-version", reason: warning.message, ...base };
+        // Warnings the punch list does not (yet) treat as a manual gap:
+        // `sprite-required` (picture marker needs a sprite — degrades but
+        // doesn't block), `missing-field` (classBreaks misuse — caller's
+        // data error, not a target gap), `unknown-property` (forward-compat
+        // pass-through), `unsupported-viewpoint-geometry` (rare and
+        // recoverable). We deliberately do not invent gap entries for
+        // those; they remain in `parseWebMap` warnings for diagnostics.
+        case "sprite-required":
+        case "missing-field":
+        case "unknown-property":
+        case "unsupported-viewpoint-geometry":
+            return undefined;
+        default:
+            return {
+                kind: "other",
+                reason: warning.message,
+                ...base,
+            };
+    }
+}
+/**
+ * Inspect the WebMap document for shell properties belonging to
+ * Dashboards, Experience Builder, or generic custom-widget hosts.
+ *
+ * The WebMap JSON spec doesn't model these directly — they appear on
+ * application documents that wrap a WebMap — but they often leak into
+ * WebMap payloads exported from those products. Recording a gap lets
+ * the migration report flag them instead of silently dropping them.
+ */
+function detectShellGaps(webmap, gaps) {
+    // Dashboard authoring metadata.
+    if (hasOwn(webmap, "dashboard") || isDashboardItemType(webmap)) {
+        gaps.push({
+            kind: "dashboard-reference",
+            reason: "WebMap payload carries Dashboard application properties; Dashboard widgets do not map to a MapLibre style and require manual reauthoring.",
+            path: hasOwn(webmap, "dashboard") ? "dashboard" : "type",
+        });
+    }
+    // Experience Builder authoring metadata.
+    if (hasOwn(webmap, "experience") || hasOwn(webmap, "experienceBuilder") || isExperienceBuilderItemType(webmap)) {
+        gaps.push({
+            kind: "experience-builder-reference",
+            reason: "WebMap payload carries Experience Builder application properties; Experience Builder pages do not map to a MapLibre style and require manual reauthoring.",
+            path: hasOwn(webmap, "experience")
+                ? "experience"
+                : hasOwn(webmap, "experienceBuilder")
+                    ? "experienceBuilder"
+                    : "type",
+        });
+    }
+    // Generic custom-widget host shells. We do NOT treat the built-in 2D
+    // widget set (Home, Compass, Zoom, …) as a gap — those have parity
+    // shims in src/esri-compat. Only widget hosts that carry a free-form
+    // `widgets`/`widgetsOnScreen` payload, which is what custom widgets
+    // and 3rd-party plugins ride on, get flagged.
+    const appProps = webmap.applicationProperties;
+    if (appProps && typeof appProps === "object") {
+        const viewing = appProps.viewing;
+        if (viewing && typeof viewing === "object" && hasOwn(viewing, "widgetsOnScreen")) {
+            gaps.push({
+                kind: "custom-widget-reference",
+                reason: "WebMap.applicationProperties.viewing.widgetsOnScreen references custom widgets that must be ported individually to MapLibre/Honua controls.",
+                path: "applicationProperties.viewing.widgetsOnScreen",
+            });
+        }
+    }
+    const customWidgets = webmap.widgets;
+    if (Array.isArray(customWidgets) && customWidgets.length > 0) {
+        gaps.push({
+            kind: "custom-widget-reference",
+            reason: "WebMap.widgets array references custom widgets that require manual MapLibre/Honua reimplementation.",
+            path: "widgets",
+            context: { count: customWidgets.length },
+        });
+    }
+}
+function isDashboardItemType(webmap) {
+    const value = webmap.type;
+    return typeof value === "string" && /dashboard/i.test(value);
+}
+function isExperienceBuilderItemType(webmap) {
+    const value = webmap.type;
+    return typeof value === "string" && /experience\s*builder|web\s*experience/i.test(value);
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function pickStringContext(context, keys) {
+    if (!context)
+        return undefined;
+    for (const key of keys) {
+        const value = context[key];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Best-effort `layerId` extraction from a warning path such as
+ * `operationalLayers[2].layerDefinition.drawingInfo.renderer`. Falls
+ * back to the synthesized `operational-<index>` id used by
+ * `convertOperationalLayer` when no explicit id is present.
+ */
+function resolveLayerIdFromPath(path, webmap) {
+    const match = path.match(/operationalLayers\[(\d+)\]/);
+    if (!match)
+        return undefined;
+    const index = Number.parseInt(match[1], 10);
+    if (!Number.isFinite(index))
+        return undefined;
+    const layer = webmap.operationalLayers?.[index];
+    if (!layer)
+        return `operational-${index}`;
+    return layer.id ?? `operational-${index}`;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@honua/react",
+  "version": "0.0.20-alpha.0",
+  "description": "React bindings for the Honua SDK: provider, hooks, and map components",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./react/index.js",
+  "types": "./react/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./react/index.d.ts",
+      "default": "./react/index.js"
+    }
+  },
+  "dependencies": {
+    "@maplibre/maplibre-gl-style-spec": "^24.7.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "maplibre-gl": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "maplibre-gl": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/react/context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * React contexts for `@honua/react`. Kept in a value-only module (no JSX, no
+ * `window` access) so it is safe to import during server-side rendering.
+ *
+ * @module
+ */
+import type { HonuaClient } from "../core/client.js";
+import type { HonuaMapRuntime, MaplibreMap } from "../runtime/index.js";
+import type { HonuaQueryCache } from "./query-cache.js";
+/** Value carried by {@link HonuaContext}: the active client and its query cache. */
+export interface HonuaContextValue {
+    readonly client: HonuaClient;
+    readonly cache: HonuaQueryCache;
+}
+/**
+ * Root context populated by {@link HonuaProvider}. `null` when a hook is used
+ * outside a provider — hooks throw a descriptive error in that case.
+ */
+export declare const HonuaContext: import("react").Context<HonuaContextValue | null>;
+/** Value carried by {@link HonuaMapContext}: the runtime owned by a `HonuaMap`. */
+export interface HonuaMapContextValue {
+    /** `null` until `HonuaMap` has finished loading its `MapPackage`. */
+    readonly runtime: HonuaMapRuntime | null;
+    /** The underlying MapLibre map instance, or `null` before it exists. */
+    readonly map: MaplibreMap | null;
+}
+/**
+ * Context provided by {@link HonuaMap} to its `HonuaLayer` / `HonuaPopup`
+ * children (and consumers of {@link useMapRuntime}).
+ */
+export declare const HonuaMapContext: import("react").Context<HonuaMapContextValue | null>;
+//# sourceMappingURL=context.d.ts.map

package/react/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/react/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAG1E,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,sDAAmD,CAAC"}

package/react/context.js

@@ -0,0 +1,19 @@
+/**
+ * React contexts for `@honua/react`. Kept in a value-only module (no JSX, no
+ * `window` access) so it is safe to import during server-side rendering.
+ *
+ * @module
+ */
+import { createContext } from "react";
+/**
+ * Root context populated by {@link HonuaProvider}. `null` when a hook is used
+ * outside a provider — hooks throw a descriptive error in that case.
+ */
+export const HonuaContext = createContext(null);
+HonuaContext.displayName = "HonuaContext";
+/**
+ * Context provided by {@link HonuaMap} to its `HonuaLayer` / `HonuaPopup`
+ * children (and consumers of {@link useMapRuntime}).
+ */
+export const HonuaMapContext = createContext(null);
+HonuaMapContext.displayName = "HonuaMapContext";