@honua/react 0.1.9-beta.0 → 0.1.10-beta.0

package/style/visual-variables.js

@@ -0,0 +1,183 @@
+import { Expr, eq, exponential, get, interpolate, linear, rgba, switchCase, toNumber, typeOf, zoom, } from "../expr/expression.js";
+/** Apply only explicit bindings; prototype names are valid source fields. */
+export function bindRendererField(field, options) {
+    const bindings = options.fieldMap;
+    return bindings && Object.hasOwn(bindings, field) ? (bindings[field] ?? field) : field;
+}
+/** ArcGIS Web Mercator scale at MapLibre zoom zero: 512 CSS pixels, 96 DPI.
+ * This is projected scale, so latitude does not change it. Ground resolution
+ * differs by cos(latitude); $view.scale is not a ground-distance measurement.
+ */
+export const WEB_MERCATOR_SCALE_AT_ZOOM_ZERO = (2 * Math.PI * 6378137 * 96) / (512 * 0.0254);
+export function webMercatorScaleToZoom(scale) {
+    return Math.log2(WEB_MERCATOR_SCALE_AT_ZOOM_ZERO / scale);
+}
+export function compileVisualVariables(variables, layerType, basePaint, warn, options = {}, outlineWidth = 0, outlinePaint = {}) {
+    const result = { paint: {}, legends: [] };
+    if (variables === undefined)
+        return result;
+    if (!Array.isArray(variables)) {
+        warn.child("visualVariables").warn("unsupported-visual-variable", "Expected a visualVariables array.");
+        return result;
+    }
+    const assigned = new Set();
+    variables.forEach((input, index) => {
+        const at = warn.child(`visualVariables[${index}]`);
+        const reject = (message, property) => (property ? at.child(property) : at).warn("unsupported-visual-variable", message);
+        if (!isRecord(input))
+            return reject("Expected a visual variable object.");
+        const color = input.type === "colorInfo";
+        if (!color && input.type !== "sizeInfo")
+            return reject(`Unsupported visual variable type: ${String(input.type)}. Reauthor this variable.`, "type");
+        for (const key of Object.keys(input)) {
+            if (!KNOWN_PROPERTIES.has(key))
+                return reject(`Unsupported visual variable property '${key}'; this variable was not applied.`, key);
+        }
+        if (color &&
+            ["minDataValue", "maxDataValue", "minSize", "maxSize", "valueUnit"].some((key) => input[key] != null)) {
+            return reject("Size range properties cannot be applied to a colorInfo variable.");
+        }
+        const normalization = ["normalizationField", "normalizationType", "normalizationTotal"].find((key) => input[key] != null);
+        if (normalization) {
+            return reject("Visual variable normalization is unsupported; precompute a numeric field and bind it explicitly.", normalization);
+        }
+        const expression = input.valueExpression ?? input.expression;
+        const scale = !color && (expression === "$view.scale" || expression === "view.scale");
+        if (expression != null && !scale)
+            return reject("Unsupported visual variable expression; bind a numeric field or use $view.scale for sizeInfo.", input.valueExpression !== undefined ? "valueExpression" : "expression");
+        if (input.valueExpression !== undefined &&
+            input.expression !== undefined &&
+            !["$view.scale", "view.scale"].includes(String(input.expression))) {
+            return reject("Conflicting expression and valueExpression properties.", "expression");
+        }
+        if (!scale && (typeof input.field !== "string" || input.field.length === 0))
+            return reject("A numeric field is required.", "field");
+        if (input.valueUnit != null && input.valueUnit !== "unknown")
+            return reject("Real-world size units are unsupported; provide a screen size ramp in points.", "valueUnit");
+        const outline = !color && layerType === "fill" && input.target === "outline";
+        if (input.target != null && !outline)
+            return reject("Only sizeInfo on polygon outlines supports a target.", "target");
+        const property = color
+            ? { circle: "circle-color", line: "line-color", fill: "fill-color" }[layerType]
+            : outline
+                ? "line-width"
+                : { circle: "circle-radius", line: "line-width" }[layerType];
+        if (!property)
+            return reject(`Unsupported ${String(input.type)} combination with ${layerType} symbols.`);
+        if (assigned.has(property))
+            return reject(`Multiple variables target ${property}; only the first supported variable is applied.`);
+        let rawStops = input.stops;
+        const stopPath = (index, property) => input.stops !== undefined
+            ? `stops[${index}].${property}`
+            : `${index === 0 ? "min" : "max"}${property === "value" ? "DataValue" : "Size"}`;
+        if (!color && rawStops === undefined)
+            rawStops = [
+                { value: input.minDataValue, size: input.minSize },
+                { value: input.maxDataValue, size: input.maxSize },
+            ];
+        if (!Array.isArray(rawStops) || rawStops.length < 2)
+            return reject("At least two strictly ascending stops are required.", "stops");
+        const stops = [];
+        for (let i = 0; i < rawStops.length; i++) {
+            const stop = rawStops[i];
+            if (!isRecord(stop) ||
+                !finite(stop.value) ||
+                (scale && stop.value <= 0) ||
+                (i > 0 && stop.value <= stops[i - 1].value))
+                return reject("Stop values must be finite, strictly ascending, and positive for scale.", stopPath(i, "value"));
+            for (const property of Object.keys(stop)) {
+                if (!["value", "label", color ? "color" : "size"].includes(property)) {
+                    return reject(`Unsupported stop property '${property}'; this variable was not applied.`, `stops[${i}].${property}`);
+                }
+            }
+            const label = typeof stop.label === "string" ? stop.label : String(stop.value);
+            if (color) {
+                const c = stop.color;
+                if (!Array.isArray(c) || c.length !== 4 || !c.every((v) => finite(v) && v >= 0 && v <= 255))
+                    return reject("Color stops require RGBA components in [0,255].", `stops[${i}].color`);
+                const css = `rgba(${c[0]},${c[1]},${c[2]},${c[3] / 255})`;
+                stops.push({ value: stop.value, output: rgba(c[0], c[1], c[2], c[3] / 255), label, color: css });
+            }
+            else {
+                if (!finite(stop.size) || stop.size < 0)
+                    return reject("Size stops require a finite nonnegative size in points; nested scale ranges are unsupported.", stopPath(i, "size"));
+                const size = (stop.size * (96 / 72)) / (layerType === "circle" ? 2 : 1);
+                stops.push({ value: stop.value, output: size, label, size });
+            }
+        }
+        const field = typeof input.field === "string" ? bindRendererField(input.field, options) : undefined;
+        const sourceFallback = missingSafeStyle(outline ? outlineWidth : (basePaint[property] ?? (color ? "transparent" : 0)));
+        const fallback = sourceFallback;
+        const ramp = scale
+            ? interpolate(exponential(0.5), zoom(), ...[...stops].reverse().map((s) => [webMercatorScaleToZoom(s.value), s.output]))
+            : switchCase([
+                eq(typeOf(get(field)), "number"),
+                interpolate(linear(), toNumber(get(field)), ...stops.map((s) => [s.value, s.output])),
+            ], new Expr(fallback));
+        if (outline) {
+            result.outline = {
+                paint: {
+                    ...outlinePaint,
+                    "line-color": basePaint["fill-outline-color"] ?? "transparent",
+                    "line-width": ramp.toJSON(),
+                },
+                layout: {},
+            };
+            // A separate line layer replaces MapLibre's fixed one-pixel fill outline.
+            result.paint["fill-outline-color"] = "transparent";
+        }
+        else
+            result.paint[property] = ramp.toJSON();
+        // Symbol alpha is carried by color, never multiplied a second time.
+        if (color && layerType === "fill")
+            result.paint["fill-opacity"] = 1;
+        assigned.add(property);
+        const legendOptions = isRecord(input.legendOptions) ? input.legendOptions : undefined;
+        if (legendOptions?.showLegend !== false)
+            result.legends.push({
+                type: color ? "color" : "size",
+                ...(field ? { field } : {}),
+                ...(typeof legendOptions?.title === "string" ? { title: legendOptions.title } : {}),
+                property,
+                input: scale ? "scale" : "field",
+                stops: stops.map(({ output: _output, ...stop }) => stop),
+                outOfRange: "clamp",
+                missingValue: "base-symbol",
+                missingValueStyle: fallback,
+                ...(!color ? { sizeUnit: "css-pixels" } : {}),
+            });
+    });
+    return result;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// A class-break step requires a number. Missing classification values use its
+// default symbol instead of causing a MapLibre expression evaluation error.
+function missingSafeStyle(style) {
+    return Array.isArray(style) && style[0] === "step"
+        ? ["case", ["==", ["typeof", style[1]], "number"], style, style[2]]
+        : style;
+}
+const KNOWN_PROPERTIES = new Set([
+    "type",
+    "field",
+    "stops",
+    "valueExpression",
+    "expression",
+    "valueExpressionTitle",
+    "legendOptions",
+    "normalizationField",
+    "normalizationType",
+    "normalizationTotal",
+    "target",
+    "valueUnit",
+    "minDataValue",
+    "maxDataValue",
+    "minSize",
+    "maxSize",
+    "authoringInfo",
+]);

package/webmap/convert-layer.d.ts

@@ -7,6 +7,7 @@
  * @module
  */
 import type { HonuaLayerSpecification, HonuaSourceSpecification } from "../style/specification.js";
+import type { RendererConversionOptions } from "../style/visual-variables.js";
 import { type HonuaPopupConfig } from "./convert-popup.js";
 import type { WebMapOperationalLayer } from "./types.js";
 import { type WarningCollector } from "./warnings.js";
@@ -18,5 +19,5 @@ export interface LayerConversionResult {
     layers: HonuaLayerSpecification[];
     popup?: HonuaPopupConfig;
 }
-export declare function convertOperationalLayer(opLayer: WebMapOperationalLayer, index: number, warn: WarningCollector): LayerConversionResult;
+export declare function convertOperationalLayer(opLayer: WebMapOperationalLayer, index: number, warn: WarningCollector, options?: RendererConversionOptions): LayerConversionResult;
 //# sourceMappingURL=convert-layer.d.ts.map

package/webmap/convert-layer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert-layer.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-layer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,uBAAuB,EAEvB,wBAAwB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,KAAK,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7F,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,GACrB,qBAAqB,CAmHvB"}
+{"version":3,"file":"convert-layer.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-layer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,uBAAuB,EAEvB,wBAAwB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAE9E,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,KAAK,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7F,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,yBAA8B,GACtC,qBAAqB,CAkIvB"}

package/webmap/convert-layer.js

@@ -10,7 +10,7 @@ import { convertLabelingInfo } from "./convert-label.js";
 import { convertPopupInfo } from "./convert-popup.js";
 import { convertRenderer } from "./convert-renderer.js";
 import { warnUnknownProperties } from "./warnings.js";
-export function convertOperationalLayer(opLayer, index, warn) {
+export function convertOperationalLayer(opLayer, index, warn, options = {}) {
     const result = { sources: {}, layers: [] };
     const layerWarn = warn.child(`operationalLayers[${index}]`);
     warnUnknownProperties(opLayer, OPERATIONAL_LAYER_PROPERTIES, layerWarn);
@@ -49,7 +49,7 @@ export function convertOperationalLayer(opLayer, index, warn) {
     warnUnknownProperties(opLayer.layerDefinition?.drawingInfo, DRAWING_INFO_PROPERTIES, layerWarn.child("layerDefinition.drawingInfo"));
     // Convert renderer
     const renderer = opLayer.layerDefinition?.drawingInfo?.renderer;
-    const rendererResult = convertRenderer(renderer, layerWarn.child("layerDefinition.drawingInfo.renderer"));
+    const rendererResult = convertRenderer(renderer, layerWarn.child("layerDefinition.drawingInfo.renderer"), options);
     if (rendererResult) {
         const layer = {
             id: layerId,
@@ -80,7 +80,24 @@ export function convertOperationalLayer(opLayer, index, warn) {
         if (opLayer.title) {
             layer.metadata = { ...layer.metadata, title: opLayer.title };
         }
+        if (rendererResult.visualVariableLegends?.length) {
+            layer.metadata = { ...layer.metadata, "honua:visual-variable-legends": rendererResult.visualVariableLegends };
+        }
         result.layers.push(layer);
+        for (const [outlineIndex, extra] of (rendererResult.additionalLayers ?? []).entries()) {
+            const outline = {
+                ...layer,
+                id: `${layerId}-outline-${outlineIndex}`,
+                type: extra.layerType,
+                paint: { ...extra.paint },
+                layout: { ...extra.layout, ...(opLayer.visibility === false ? { visibility: "none" } : {}) },
+            };
+            if (transparency != null && transparency > 0)
+                applyTransparency(outline, transparency);
+            if (opLayer.opacity != null && opLayer.opacity < 1)
+                applyOpacity(outline, opLayer.opacity);
+            result.layers.push(outline);
+        }
     }
     else if (!renderer) {
         // No renderer — create a default layer so the source is referenced
@@ -120,7 +137,7 @@ function applyOpacity(layer, opacity) {
             paint["fill-opacity"] = opacity;
             break;
         case "line":
-            paint["line-opacity"] = opacity;
+            paint["line-opacity"] = (typeof paint["line-opacity"] === "number" ? paint["line-opacity"] : 1) * opacity;
             break;
         case "circle":
             paint["circle-opacity"] = opacity;

package/webmap/convert-renderer.d.ts

@@ -10,14 +10,21 @@
  * @module
  */
 import type { ClassBreaksRenderer, UniqueValueRenderer } from "../style/renderers.js";
+import { type RendererConversionOptions, type VisualVariableLegend } from "../style/visual-variables.js";
 import type { WebMapClassBreaksRenderer, WebMapRenderer, WebMapUniqueValueRenderer } from "./types.js";
 import type { WarningCollector } from "./warnings.js";
 export interface RendererConversionResult {
     layerType: string;
     paint: Record<string, unknown>;
     layout: Record<string, unknown>;
+    additionalLayers?: {
+        layerType: string;
+        paint: Record<string, unknown>;
+        layout: Record<string, unknown>;
+    }[];
+    visualVariableLegends?: VisualVariableLegend[];
 }
-export declare function convertRenderer(renderer: WebMapRenderer | undefined, warn: WarningCollector): RendererConversionResult | undefined;
+export declare function convertRenderer(renderer: WebMapRenderer | undefined, warn: WarningCollector, options?: RendererConversionOptions): RendererConversionResult | undefined;
 /**
  * Build a first-class unique-value renderer object from WebMap renderer
  * JSON. Returns `undefined` when the renderer has no value infos or the
@@ -25,7 +32,7 @@ export declare function convertRenderer(renderer: WebMapRenderer | undefined, wa
  *
  * @experimental
  */
-export declare function uniqueValueRendererFromWebMap(renderer: WebMapUniqueValueRenderer, warn: WarningCollector): UniqueValueRenderer | undefined;
+export declare function uniqueValueRendererFromWebMap(renderer: WebMapUniqueValueRenderer, warn: WarningCollector, options?: RendererConversionOptions): UniqueValueRenderer | undefined;
 /**
  * Build a first-class class-breaks renderer object from WebMap renderer
  * JSON. Returns `undefined` when the renderer has no break infos, no field,
@@ -34,5 +41,5 @@ export declare function uniqueValueRendererFromWebMap(renderer: WebMapUniqueValu
  *
  * @experimental
  */
-export declare function classBreaksRendererFromWebMap(renderer: WebMapClassBreaksRenderer, warn: WarningCollector): ClassBreaksRenderer | undefined;
+export declare function classBreaksRendererFromWebMap(renderer: WebMapClassBreaksRenderer, warn: WarningCollector, options?: RendererConversionOptions): ClassBreaksRenderer | undefined;
 //# sourceMappingURL=convert-renderer.d.ts.map

package/webmap/convert-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert-renderer.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAmC,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGvH,OAAO,KAAK,EAAE,yBAAyB,EAAE,cAAc,EAAgB,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACrH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,IAAI,EAAE,gBAAgB,GACrB,wBAAwB,GAAG,SAAS,CActC;AAmCD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,gBAAgB,GACrB,mBAAmB,GAAG,SAAS,CA6BjC;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,gBAAgB,GACrB,mBAAmB,GAAG,SAAS,CAgCjC"}
+{"version":3,"file":"convert-renderer.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAmC,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvH,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,cAAc,EAAgB,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACrH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC5G,qBAAqB,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAChD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,GAAG,SAAS,CAoBtC;AAwCD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,yBAA8B,GACtC,mBAAmB,GAAG,SAAS,CAgDjC;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,yBAA8B,GACtC,mBAAmB,GAAG,SAAS,CAoDjC"}

package/webmap/convert-renderer.js

@@ -10,41 +10,40 @@
  * @module
  */
 import { classBreaksRenderer, uniqueValueRenderer } from "../style/renderers.js";
-import { convertSymbol } from "./convert-symbol.js";
-export function convertRenderer(renderer, warn) {
+import { bindRendererField, compileVisualVariables, } from "../style/visual-variables.js";
+import { convertSymbol, esriLineStyleToDashArray } from "./convert-symbol.js";
+export function convertRenderer(renderer, warn, options = {}) {
     if (!renderer)
         return undefined;
     switch (renderer.type) {
         case "simple":
-            return convertSimpleRenderer(renderer.symbol, warn);
+            return applyVisualVariables(convertRendererSymbol(renderer.symbol, warn, renderer.visualVariables), renderer, warn, options);
         case "uniqueValue":
-            return convertUniqueValueRenderer(renderer, warn);
+            return convertUniqueValueRenderer(renderer, warn, options);
         case "classBreaks":
-            return convertClassBreaksRenderer(renderer, warn);
+            return convertClassBreaksRenderer(renderer, warn, options);
         default:
             warn.warn("unsupported-renderer", `Unsupported renderer type: ${renderer.type}`, { type: renderer.type });
+            compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
             return undefined;
     }
 }
-function convertSimpleRenderer(symbol, warn) {
-    return convertSymbol(symbol, warn);
-}
-function convertUniqueValueRenderer(renderer, warn) {
+function convertUniqueValueRenderer(renderer, warn, options) {
     const infos = renderer.uniqueValueInfos ?? [];
     if (infos.length === 0) {
-        return convertSymbol(renderer.defaultSymbol, warn);
+        return applyVisualVariables(convertRendererSymbol(renderer.defaultSymbol, warn, renderer.visualVariables), renderer, warn, options);
     }
-    const rendererObject = uniqueValueRendererFromWebMap(renderer, warn);
+    const rendererObject = uniqueValueRendererFromWebMap(renderer, warn, options);
     if (!rendererObject)
         return undefined;
     return compileRendererObject(rendererObject);
 }
-function convertClassBreaksRenderer(renderer, warn) {
+function convertClassBreaksRenderer(renderer, warn, options) {
     const breaks = renderer.classBreakInfos ?? [];
     if (breaks.length === 0) {
-        return convertSymbol(renderer.defaultSymbol, warn);
+        return applyVisualVariables(convertRendererSymbol(renderer.defaultSymbol, warn, renderer.visualVariables), renderer, warn, options);
     }
-    const rendererObject = classBreaksRendererFromWebMap(renderer, warn);
+    const rendererObject = classBreaksRendererFromWebMap(renderer, warn, options);
     if (!rendererObject)
         return undefined;
     return compileRendererObject(rendererObject);
@@ -56,17 +55,22 @@ function convertClassBreaksRenderer(renderer, warn) {
  *
  * @experimental
  */
-export function uniqueValueRendererFromWebMap(renderer, warn) {
+export function uniqueValueRendererFromWebMap(renderer, warn, options = {}) {
+    warnRendererSemantics(renderer, warn);
     const infos = renderer.uniqueValueInfos ?? [];
-    if (infos.length === 0)
+    if (infos.length === 0) {
+        compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
         return undefined;
+    }
     // The first valid symbol determines the layer type.
-    const firstResult = convertSymbol(infos[0].symbol, warn);
-    if (!firstResult)
+    const firstResult = convertRendererSymbol(infos[0].symbol, warn, renderer.visualVariables);
+    if (!firstResult) {
+        compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
         return undefined;
+    }
     const values = [];
     for (const info of infos) {
-        const symbolResult = convertSymbol(info.symbol, warn);
+        const symbolResult = convertRendererSymbol(info.symbol, warn, renderer.visualVariables);
         if (!symbolResult)
             continue;
         values.push({
@@ -75,16 +79,22 @@ export function uniqueValueRendererFromWebMap(renderer, warn) {
             style: { paint: symbolResult.paint, layout: symbolResult.layout },
         });
     }
-    return uniqueValueRenderer({
-        field: renderer.field1 ?? "",
-        ...(renderer.field2 !== undefined ? { field2: renderer.field2 } : {}),
-        ...(renderer.field3 !== undefined ? { field3: renderer.field3 } : {}),
+    const base = uniqueValueRenderer({
+        field: bindRendererField(renderer.field1 ?? "", options),
+        ...(renderer.field2 !== undefined ? { field2: bindRendererField(renderer.field2, options) } : {}),
+        ...(renderer.field3 !== undefined ? { field3: bindRendererField(renderer.field3, options) } : {}),
         ...(renderer.fieldDelimiter !== undefined ? { fieldDelimiter: renderer.fieldDelimiter } : {}),
         values,
         ...(renderer.defaultLabel !== undefined ? { defaultLabel: renderer.defaultLabel } : {}),
-        ...defaultStyleFromSymbol(renderer.defaultSymbol, warn),
+        ...defaultStyleFromSymbol(renderer.defaultSymbol, warn, renderer.visualVariables),
         layerType: firstResult.layerType,
     });
+    if (renderer.visualVariables === undefined)
+        return base;
+    return uniqueValueRenderer({
+        ...base.toJSON(),
+        visualVariableStyle: compileVisualVariables(renderer.visualVariables, firstResult.layerType, base.toMapLibre("polygon")[0].paint, warn, options, ...outlineFromRenderer(renderer, options, warn)),
+    });
 }
 /**
  * Build a first-class class-breaks renderer object from WebMap renderer
@@ -94,21 +104,27 @@ export function uniqueValueRendererFromWebMap(renderer, warn) {
  *
  * @experimental
  */
-export function classBreaksRendererFromWebMap(renderer, warn) {
+export function classBreaksRendererFromWebMap(renderer, warn, options = {}) {
+    warnRendererSemantics(renderer, warn);
     const breaks = renderer.classBreakInfos ?? [];
-    if (breaks.length === 0)
+    if (breaks.length === 0) {
+        compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
         return undefined;
-    const firstResult = convertSymbol(breaks[0].symbol, warn);
-    if (!firstResult)
+    }
+    const firstResult = convertRendererSymbol(breaks[0].symbol, warn, renderer.visualVariables);
+    if (!firstResult) {
+        compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
         return undefined;
+    }
     const field = renderer.field;
     if (!field) {
         warn.warn("missing-field", "classBreaks renderer missing field property");
+        compileVisualVariables(renderer.visualVariables, "unknown", {}, warn, options);
         return undefined;
     }
     const entries = [];
     for (const brk of breaks) {
-        const symbolResult = convertSymbol(brk.symbol, warn);
+        const symbolResult = convertRendererSymbol(brk.symbol, warn, renderer.visualVariables);
         if (!symbolResult)
             continue;
         entries.push({
@@ -118,18 +134,24 @@ export function classBreaksRendererFromWebMap(renderer, warn) {
             style: { paint: symbolResult.paint, layout: symbolResult.layout },
         });
     }
-    return classBreaksRenderer({
-        field,
+    const base = classBreaksRenderer({
+        field: bindRendererField(field, options),
         breaks: entries,
         ...(renderer.defaultLabel !== undefined ? { defaultLabel: renderer.defaultLabel } : {}),
-        ...defaultStyleFromSymbol(renderer.defaultSymbol, warn),
+        ...defaultStyleFromSymbol(renderer.defaultSymbol, warn, renderer.visualVariables),
         layerType: firstResult.layerType,
     });
+    if (renderer.visualVariables === undefined)
+        return base;
+    return classBreaksRenderer({
+        ...base.toJSON(),
+        visualVariableStyle: compileVisualVariables(renderer.visualVariables, firstResult.layerType, base.toMapLibre("polygon")[0].paint, warn, options, ...outlineFromRenderer(renderer, options, warn)),
+    });
 }
-function defaultStyleFromSymbol(defaultSymbol, warn) {
+function defaultStyleFromSymbol(defaultSymbol, warn, variables) {
     if (!defaultSymbol)
         return {};
-    const converted = convertSymbol(defaultSymbol, warn);
+    const converted = convertRendererSymbol(defaultSymbol, warn, variables);
     // A default symbol that fails conversion still overrides the first-entry
     // fallback: every property defaults to "transparent" (legacy behavior).
     return { defaultStyle: converted ? { paint: converted.paint, layout: converted.layout } : {} };
@@ -137,6 +159,138 @@ function defaultStyleFromSymbol(defaultSymbol, warn) {
 function compileRendererObject(renderer) {
     // The descriptor carries the symbol-derived layer type, so the geometry
     // argument is inert here; "polygon" is an arbitrary stand-in.
-    const [fragment] = renderer.toMapLibre("polygon");
-    return { layerType: fragment.type, paint: fragment.paint, layout: fragment.layout };
+    const [fragment, ...additional] = renderer.toMapLibre("polygon");
+    return {
+        layerType: fragment.type,
+        paint: fragment.paint,
+        layout: fragment.layout,
+        ...(additional.length
+            ? { additionalLayers: additional.map((f) => ({ layerType: f.type, paint: f.paint, layout: f.layout })) }
+            : {}),
+        ...(renderer.visualVariableLegends?.().length
+            ? { visualVariableLegends: [...renderer.visualVariableLegends()] }
+            : {}),
+    };
+}
+function applyVisualVariables(base, renderer, warn, options) {
+    const variables = compileVisualVariables(renderer.visualVariables, base?.layerType ?? "unknown", base?.paint ?? {}, warn, options, ...outlineFromRenderer(renderer, options, warn));
+    if (!base)
+        return undefined;
+    const paint = { ...base.paint, ...variables.paint };
+    return {
+        ...base,
+        paint,
+        ...(variables.outline ? { additionalLayers: [{ layerType: "line", ...variables.outline }] } : {}),
+        ...(variables.legends.length ? { visualVariableLegends: variables.legends } : {}),
+    };
+}
+function warnRendererSemantics(renderer, warn) {
+    for (const property of ["valueExpression", "normalizationField", "normalizationType", "normalizationTotal"]) {
+        if (renderer[property] != null && renderer[property] !== "")
+            warn
+                .child(property)
+                .warn("unsupported-renderer-semantics", `Renderer ${property} is unsupported; the base field renderer is a fallback that requires review.`);
+    }
+}
+function convertRendererSymbol(symbol, warn, variables) {
+    const result = convertSymbol(symbol, warn);
+    if (!result || !symbol || !Array.isArray(variables) || variables.length === 0)
+        return result;
+    const colorProperty = { fill: "fill-color", line: "line-color", circle: "circle-color" }[result.layerType];
+    const color = symbol.color;
+    if (colorProperty && Array.isArray(color) && color.length === 4) {
+        result.paint[colorProperty] = `rgba(${color[0]},${color[1]},${color[2]},${Number(color[3]) / 255})`;
+        if (result.layerType === "fill")
+            delete result.paint["fill-opacity"];
+    }
+    for (const property of ["line-width", "circle-radius", "circle-stroke-width"]) {
+        if (typeof result.paint[property] === "number")
+            result.paint[property] = (result.paint[property] * 96) / 72;
+    }
+    const outline = symbol.outline;
+    const outlineColor = outline?.color;
+    if (Array.isArray(outlineColor) && outlineColor.length === 4) {
+        const property = result.layerType === "fill" ? "fill-outline-color" : "circle-stroke-color";
+        result.paint[property] =
+            `rgba(${outlineColor[0]},${outlineColor[1]},${outlineColor[2]},${Number(outlineColor[3]) / 255})`;
+    }
+    return result;
+}
+function outlineFromRenderer(renderer, options, warn) {
+    const variables = renderer.visualVariables;
+    if (!Array.isArray(variables) || !variables.some((v) => v?.type === "sizeInfo" && v?.target === "outline"))
+        return [0, {}];
+    const symbols = renderer.type === "simple"
+        ? [{ symbol: renderer.symbol, path: "symbol" }]
+        : renderer.type === "classBreaks"
+            ? (renderer.classBreakInfos ?? []).map((entry, i) => ({
+                symbol: entry.symbol,
+                path: `classBreakInfos[${i}].symbol`,
+            }))
+            : (renderer.uniqueValueInfos ?? []).map((entry, i) => ({
+                symbol: entry.symbol,
+                path: `uniqueValueInfos[${i}].symbol`,
+            }));
+    if (renderer.defaultSymbol)
+        symbols.push({ symbol: renderer.defaultSymbol, path: "defaultSymbol" });
+    const styles = symbols.map(({ symbol, path }) => ({
+        style: symbol?.outline?.style ?? "esriSLSSolid",
+        path,
+    }));
+    const firstStyle = styles[0]?.style ?? "esriSLSSolid";
+    const paint = {};
+    for (const { style, path } of styles) {
+        if (style !== firstStyle || (style !== "esriSLSSolid" && !esriLineStyleToDashArray(style))) {
+            warn
+                .child(`${path}.outline.style`)
+                .warn("unsupported-renderer-semantics", "Varying or unknown polygon outline dash styles require separate layers; review the converted outline style.");
+        }
+    }
+    if (firstStyle === "esriSLSNull")
+        paint["line-opacity"] = 0;
+    else {
+        const dash = esriLineStyleToDashArray(firstStyle);
+        if (dash)
+            paint["line-dasharray"] = dash;
+    }
+    const width = (symbol) => {
+        const outline = symbol?.outline;
+        return typeof outline?.width === "number" ? (outline.width * 96) / 72 : 0;
+    };
+    if (renderer.type === "simple")
+        return [width(renderer.symbol), paint];
+    if (renderer.type === "classBreaks") {
+        const input = renderer;
+        if (!input.field || !input.classBreakInfos?.length)
+            return [width(input.defaultSymbol), paint];
+        return [
+            classBreaksRenderer({
+                field: bindRendererField(input.field, options),
+                breaks: input.classBreakInfos.map((entry) => ({
+                    min: entry.classMinValue,
+                    max: entry.classMaxValue,
+                    style: { paint: { "line-width": width(entry.symbol) } },
+                })),
+                ...(input.defaultSymbol ? { defaultStyle: { paint: { "line-width": width(input.defaultSymbol) } } } : {}),
+            }).toMapLibre("line")[0].paint["line-width"],
+            paint,
+        ];
+    }
+    const input = renderer;
+    if (!input.uniqueValueInfos?.length)
+        return [width(input.defaultSymbol), paint];
+    return [
+        uniqueValueRenderer({
+            field: bindRendererField(input.field1 ?? "", options),
+            field2: input.field2 ? bindRendererField(input.field2, options) : undefined,
+            field3: input.field3 ? bindRendererField(input.field3, options) : undefined,
+            fieldDelimiter: input.fieldDelimiter,
+            values: input.uniqueValueInfos.map((entry) => ({
+                value: entry.value,
+                style: { paint: { "line-width": width(entry.symbol) } },
+            })),
+            ...(input.defaultSymbol ? { defaultStyle: { paint: { "line-width": width(input.defaultSymbol) } } } : {}),
+        }).toMapLibre("line")[0].paint["line-width"],
+        paint,
+    ];
 }

package/webmap/index.d.ts

@@ -41,4 +41,5 @@ export type { ExtentConversionResult } from "./convert-extent.js";
 export { convertOperationalLayer } from "./convert-layer.js";
 export type { LayerConversionResult } from "./convert-layer.js";
 export type { WebMapJson, WebMapOperationalLayer, WebMapRenderer, WebMapSimpleRenderer, WebMapUniqueValueRenderer, WebMapClassBreaksRenderer, WebMapSymbol, WebMapSimpleFillSymbol, WebMapSimpleLineSymbol, WebMapSimpleMarkerSymbol, WebMapPictureMarkerSymbol, WebMapTextSymbol, WebMapBaseMap, WebMapBaseMapLayer, WebMapPopupInfo, WebMapFieldInfo, WebMapExtent, WebMapPoint, WebMapViewpoint, WebMapViewpointTargetGeometry, WebMapInitialState, WebMapBookmark, WebMapSpatialReference, WebMapLabelClass, WebMapDrawingInfo, WebMapLayerDefinition, EsriColor, } from "./types.js";
+export type { RendererConversionOptions, VisualVariableLegend } from "../style/visual-variables.js";
 //# sourceMappingURL=index.d.ts.map

package/webmap/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/webmap/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,WAAW,EACX,eAAe,EACf,6BAA6B,EAC7B,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,GACV,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/webmap/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,WAAW,EACX,eAAe,EACf,6BAA6B,EAC7B,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/webmap/parse.d.ts

@@ -4,10 +4,11 @@
  * @module
  */
 import type { HonuaStyleSpecification } from "../style/specification.js";
+import type { RendererConversionOptions } from "../style/visual-variables.js";
 import type { HonuaPopupConfig } from "./convert-popup.js";
 import type { WebMapBookmark, WebMapJson } from "./types.js";
 import { type WebMapWarning } from "./warnings.js";
-export interface ParseWebMapOptions {
+export interface ParseWebMapOptions extends RendererConversionOptions {
     /** If true, include basemap layers. Defaults to true. */
     includeBasemap?: boolean;
 }