@jupytergis/base 0.15.0 → 0.16.0-alpha.1

package/lib/features/layers/symbology/grammarToOLStyle.js

@@ -0,0 +1,487 @@
+/**
+ * Grammar → OL FlatStyle compiler.
+ *
+ * grammarToOLStyle(state) compiles an IGrammarSymbologyState into an OL
+ * FlatStyle object ready to be applied to a VectorLayer or VectorTileLayer.
+ *
+ * Compilation steps:
+ *   1. Expand rules into per-channel entries (guard + expression).
+ *   2. Build a case expression per channel (conditional entries first,
+ *      last unconditional entry as the else branch).
+ *   3. Assemble sub-channels (fill-red/green/blue/alpha) into a composite
+ *      fill-color ['array', r, g, b, a] expression.
+ */
+import { computeCategorizedColorStops, computeGraduatedColorStops, STOP_NULL, STOP_UNDEFINED, } from './styleBuilder';
+// '$density' is the pseudo-field produced by a kde transform (KDE density raster).
+// Encoding rules referencing it are compiled only when a kde transform is present;
+// the actual OL HeatmapLayer instantiation happens outside this compiler.
+export const DENSITY_FIELD = '$density';
+// ---------------------------------------------------------------------------
+// Field expression helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a field name to an OL expression.
+ * $band-N (raster pseudo-fields) → ['band', N]
+ * everything else → ['get', field]
+ */
+function fieldExpr(field) {
+    const m = field.match(/^\$band-(\d+)$/);
+    if (m) {
+        return ['band', parseInt(m[1], 10)];
+    }
+    return ['get', field];
+}
+/** Band pseudo-fields always exist; vector feature properties may not. */
+function fieldAlwaysPresent(field) {
+    return /^\$band-\d+$/.test(field) || field === DENSITY_FIELD;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Compile a Grammar symbology state to an OL FlatStyle object.
+ * Sub-channels (fill-red/green/blue/alpha) are assembled into fill-color.
+ *
+ * @param featureValues  Feature attribute values for the rule field(s).
+ *   Required for categorical and colorRamp scales so the compiler can
+ *   enumerate unique values / compute classification breaks at render time,
+ *   mirroring how buildVectorFlatStyle works.
+ */
+export function grammarToOLStyle(state, featureValues = []) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    // Accumulate per-channel entries from all layers and their rules.
+    // Layers with a kde/cluster preprocess are handled at the renderer level;
+    // this compiler only produces the flat-style for the vector portion.
+    const accumulator = new Map();
+    // Guard: state.layers may be absent on legacy Grammar states that predate
+    // the layers nesting (e.g. stored as { rules: [...] } without a layers wrapper).
+    for (const layer of (_a = state.layers) !== null && _a !== void 0 ? _a : []) {
+        if ((_b = layer.preprocess) === null || _b === void 0 ? void 0 : _b.some(t => t.type === 'kde')) {
+            // KDE layers are compiled separately by the renderer (HeatmapLayer).
+            // Skip flat-style compilation for this layer.
+            continue;
+        }
+        // Layer-level guard: compiled separately then AND-ed with the rule guard.
+        const layerGuard = layer.when && layer.when.length > 0
+            ? compileGuard(layer.when, (_c = layer.whenOp) !== null && _c !== void 0 ? _c : 'all')
+            : undefined;
+        for (const rule of layer.rules) {
+            // For now use the first field; multi-field assembly is handled via
+            // sub-channel mappings (pixel-red/green/blue) or expression scales.
+            const field = (_d = rule.fields) === null || _d === void 0 ? void 0 : _d[0];
+            const ruleGuard = rule.when && rule.when.length > 0
+                ? compileGuard(rule.when, (_e = rule.whenOp) !== null && _e !== void 0 ? _e : 'all')
+                : undefined;
+            const guard = layerGuard && ruleGuard
+                ? ['all', layerGuard, ruleGuard]
+                : (layerGuard !== null && layerGuard !== void 0 ? layerGuard : ruleGuard);
+            for (const mapping of rule.mappings) {
+                for (const channel of mapping.channels) {
+                    if (channel === 'pixel-rgb') {
+                        // Virtual channel: fan out to pixel-red/green/blue so assembleStyle
+                        // can compose them into ['color', r, g, b, a] with a separate alpha.
+                        for (const sub of [
+                            'pixel-red',
+                            'pixel-green',
+                            'pixel-blue',
+                        ]) {
+                            const expr = compileMapping(field, mapping, featureValues, sub);
+                            const entries = (_f = accumulator.get(sub)) !== null && _f !== void 0 ? _f : [];
+                            entries.push({ guard, expr });
+                            accumulator.set(sub, entries);
+                        }
+                    }
+                    else {
+                        // Compile per-channel so sub-channels (pixel-red/green/blue) can each
+                        // extract the correct component from a colorRamp or other color scale.
+                        const expr = compileMapping(field, mapping, featureValues, channel);
+                        const entries = (_g = accumulator.get(channel)) !== null && _g !== void 0 ? _g : [];
+                        entries.push({ guard, expr });
+                        accumulator.set(channel, entries);
+                    }
+                }
+            }
+        }
+    }
+    // Build per-channel OL expressions.
+    const channelExprs = new Map();
+    for (const [channel, entries] of accumulator) {
+        channelExprs.set(channel, buildChannelExpr(entries, channel));
+    }
+    // Assemble into the final style object, handling sub-channel composition.
+    return assembleStyle(channelExprs);
+}
+// ---------------------------------------------------------------------------
+// Feature-value extraction helper
+// ---------------------------------------------------------------------------
+/**
+ * Extract the encoding field column from feature property rows.
+ * colorRamp and categorical scales take a single input field; this returns
+ * all values for that field so the compiler can compute classification breaks.
+ */
+export function extractEncodingFieldValues(state, rows) {
+    var _a, _b, _c;
+    let field;
+    for (const gl of (_a = state.layers) !== null && _a !== void 0 ? _a : []) {
+        for (const rule of (_b = gl.rules) !== null && _b !== void 0 ? _b : []) {
+            const f = (_c = rule.fields) === null || _c === void 0 ? void 0 : _c[0];
+            if (f && !f.startsWith('$')) {
+                field = f;
+                break;
+            }
+        }
+        if (field) {
+            break;
+        }
+    }
+    if (!field) {
+        console.debug('extractEncodingFieldValues: no encoding field found in Grammar state');
+        return [];
+    }
+    return rows.map(r => r[field]).filter(v => v !== null && v !== undefined);
+}
+// ---------------------------------------------------------------------------
+// Channel expression builder
+// ---------------------------------------------------------------------------
+/**
+ * Merge a list of ChannelEntries into a single OL expression.
+ * Conditional entries form case branches; the last unconditional entry wins
+ * as the else branch (transparent/zero if none).
+ */
+function buildChannelExpr(entries, channel) {
+    const conditional = entries.filter(e => e.guard !== undefined);
+    const unconditional = entries.filter(e => e.guard === undefined);
+    const elseExpr = unconditional.length > 0
+        ? unconditional[unconditional.length - 1].expr
+        : channelZero(channel);
+    if (conditional.length === 0) {
+        return elseExpr;
+    }
+    const caseExpr = ['case'];
+    for (const { guard, expr } of conditional) {
+        caseExpr.push(guard, expr);
+    }
+    caseExpr.push(elseExpr);
+    return caseExpr;
+}
+/** Typed zero for channels with no unconditional rule. */
+function channelZero(channel) {
+    const rgbaChannels = new Set([
+        'fill-color',
+        'stroke-color',
+        'circle-fill-color',
+        'circle-stroke-color',
+        'pixel-color',
+    ]);
+    return rgbaChannels.has(channel) ? 'rgba(0,0,0,0)' : 0;
+}
+// ---------------------------------------------------------------------------
+// Sub-channel assembly
+// ---------------------------------------------------------------------------
+const FILL_SUB = ['fill-red', 'fill-green', 'fill-blue'];
+const FILL_ALPHA_SUB = ['fill-alpha'];
+const PIXEL_SUB = ['pixel-red', 'pixel-green', 'pixel-blue'];
+const PIXEL_ALPHA_SUB = ['pixel-alpha'];
+/**
+ * Assemble the final style object.
+ * Sub-channels (fill-red/green/blue/alpha, pixel-red/green/blue/alpha) are
+ * combined into a ['color', r, g, b, a] expression on the parent channel.
+ * Virtual channels (pixel-rgb) are already fanned out before this runs.
+ */
+function assembleStyle(channelExprs) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const style = {};
+    // Collect named channels directly.
+    const skip = new Set([
+        ...FILL_SUB,
+        ...FILL_ALPHA_SUB,
+        ...PIXEL_SUB,
+        ...PIXEL_ALPHA_SUB,
+    ]);
+    for (const [channel, expr] of channelExprs) {
+        if (!skip.has(channel)) {
+            style[channel] = expr;
+        }
+    }
+    // Assemble fill-color from sub-channels if any fill-* sub-channel is present.
+    // ['color', r, g, b, a] is the OL operator that produces ColorType (r/g/b 0-255, a 0-1).
+    if (FILL_SUB.some(c => channelExprs.has(c)) ||
+        FILL_ALPHA_SUB.some(c => channelExprs.has(c))) {
+        const r = (_a = channelExprs.get('fill-red')) !== null && _a !== void 0 ? _a : 0;
+        const g = (_b = channelExprs.get('fill-green')) !== null && _b !== void 0 ? _b : 0;
+        const b = (_c = channelExprs.get('fill-blue')) !== null && _c !== void 0 ? _c : 0;
+        const a = (_d = channelExprs.get('fill-alpha')) !== null && _d !== void 0 ? _d : 1;
+        style['fill-color'] = ['color', r, g, b, a];
+    }
+    // Assemble pixel-color from sub-channels when pixel-R/G/B are present.
+    // pixel-alpha alone does NOT overwrite a direct pixel-color mapping.
+    if (PIXEL_SUB.some(c => channelExprs.has(c))) {
+        const r = (_e = channelExprs.get('pixel-red')) !== null && _e !== void 0 ? _e : 0;
+        const g = (_f = channelExprs.get('pixel-green')) !== null && _f !== void 0 ? _f : 0;
+        const b = (_g = channelExprs.get('pixel-blue')) !== null && _g !== void 0 ? _g : 0;
+        const a = (_h = channelExprs.get('pixel-alpha')) !== null && _h !== void 0 ? _h : 1;
+        style['pixel-color'] = ['color', r, g, b, a];
+    }
+    else if (PIXEL_ALPHA_SUB.some(c => channelExprs.has(c)) &&
+        !channelExprs.has('pixel-color')) {
+        // Alpha-only with no direct pixel-color: compose with black.
+        const a = (_j = channelExprs.get('pixel-alpha')) !== null && _j !== void 0 ? _j : 1;
+        style['pixel-color'] = ['color', 0, 0, 0, a];
+    }
+    return style;
+}
+// ---------------------------------------------------------------------------
+// Guard compilation
+// ---------------------------------------------------------------------------
+function compileGuard(predicates, op = 'all') {
+    const conditions = predicates.map(compilePredicate);
+    return conditions.length === 1 ? conditions[0] : [op, ...conditions];
+}
+function compilePredicate(predicate) {
+    switch (predicate.type) {
+        case 'geometryType':
+            return ['==', ['geometry-type'], predicate.value];
+        case 'hasField':
+            // Band pseudo-fields always exist; for vector features use ['has'].
+            return fieldAlwaysPresent(predicate.field)
+                ? true
+                : ['has', predicate.field];
+        case 'fieldEquals':
+            return ['==', fieldExpr(predicate.field), predicate.value];
+        case 'fieldCompare':
+            return [predicate.op, fieldExpr(predicate.field), predicate.value];
+        case 'between':
+            return [
+                'all',
+                ['>=', fieldExpr(predicate.field), predicate.min],
+                ['<=', fieldExpr(predicate.field), predicate.max],
+            ];
+    }
+}
+// ---------------------------------------------------------------------------
+// Mapping compilation — dispatches by scale scheme
+// ---------------------------------------------------------------------------
+/**
+ * Return the RGBA array index for a sub-channel, or undefined for full-color
+ * channels.  Used to decompose a colorRamp into a single numeric component.
+ */
+function colorComponentIndex(channel) {
+    switch (channel) {
+        case 'fill-red':
+        case 'pixel-red':
+            return 0;
+        case 'fill-green':
+        case 'pixel-green':
+            return 1;
+        case 'fill-blue':
+        case 'pixel-blue':
+            return 2;
+        case 'fill-alpha':
+        case 'pixel-alpha':
+            return 3;
+        default:
+            return undefined;
+    }
+}
+function compileMapping(field, mapping, featureValues, channel) {
+    const { scale } = mapping;
+    switch (scale.scheme) {
+        case 'colorRamp':
+            return field
+                ? compileColorRamp(field, scale, featureValues, channel)
+                : scale.params.fallback;
+        case 'categorical':
+            return field
+                ? compileCategorical(field, scale, featureValues)
+                : scale.params.fallback;
+        case 'expression':
+            // Expression scale is not yet implemented; fall back to channel zero.
+            console.warn('[grammarToOLStyle] expression scale is not yet implemented');
+            return channelZero(mapping.channels[0]);
+        case 'constant_rgba':
+        case 'constant_num':
+            return scale.params.value;
+        case 'scalar':
+            return field ? compileScalar(field, scale) : scale.params.fallback;
+        case 'identity': {
+            if (!field) {
+                return channelZero(mapping.channels[0]);
+            }
+            // Wrap with coalesce so OL's expression type system infers the correct
+            // output type (color vs number). Bare ['get', field] has type 'any'
+            // which OL rejects for typed channels like fill-color.
+            const isColorChannel = mapping.channels.some(ch => [
+                'fill-color',
+                'stroke-color',
+                'circle-fill-color',
+                'circle-stroke-color',
+                'pixel-color',
+            ].includes(ch));
+            const typedFallback = isColorChannel
+                ? [0, 0, 0, 0]
+                : 0;
+            if (fieldAlwaysPresent(field)) {
+                return fieldExpr(field);
+            }
+            return ['coalesce', fieldExpr(field), typedFallback];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scale compilers
+// ---------------------------------------------------------------------------
+/**
+ * colorRamp: numeric field → RGBA color via a named palette + classification.
+ *
+ * Output:
+ *   ['case', ['has', field],
+ *     ['interpolate', ['linear'], ['get', field], stop0, color0, ...],
+ *     fallback]
+ */
+function compileColorRamp(field, scale, featureValues, channel) {
+    const stops = resolveColorStops(scale, featureValues);
+    // Guard: interpolate requires at least 2 stop pairs. Return fallback when
+    // the source is not yet loaded and no explicit domain/colorStops are set.
+    if (stops.length < 2) {
+        const componentIdx = channel !== undefined ? colorComponentIndex(channel) : undefined;
+        return componentIdx !== undefined ? 0 : scale.params.fallback;
+    }
+    const componentIdx = channel !== undefined ? colorComponentIndex(channel) : undefined;
+    const interpolateExpr = [
+        'interpolate',
+        ['linear'],
+        fieldExpr(field),
+    ];
+    if (componentIdx !== undefined) {
+        // Sub-channel scalar interpolation for one color component (R=0,G=1,B=2,A=3).
+        // colormap stops carry [r, g, b, a] with r/g/b in 0-255 and a in 0-1.
+        // Values are passed as-is since assembleStyle uses ['color', r, g, b, a]
+        // which takes r/g/b in 0-255.
+        for (const { stop, color } of stops) {
+            interpolateExpr.push(stop, color[componentIdx]);
+        }
+        if (fieldAlwaysPresent(field)) {
+            return interpolateExpr;
+        }
+        return ['case', ['has', field], interpolateExpr, 0];
+    }
+    // Full color channel: emit the usual RGBA interpolation.
+    for (const { stop, color } of stops) {
+        interpolateExpr.push(stop, color);
+    }
+    if (fieldAlwaysPresent(field)) {
+        return interpolateExpr;
+    }
+    return ['case', ['has', field], interpolateExpr, scale.params.fallback];
+}
+/**
+ * Resolve color stops for a colorRamp scale.
+ * Explicit colorStops (user overrides) take precedence; otherwise classification
+ * breaks are computed from featureValues using computeGraduatedColorStops.
+ */
+function resolveColorStops(scale, featureValues) {
+    var _a, _b;
+    if (scale.params.colorStops && scale.params.colorStops.length >= 2) {
+        return scale.params.colorStops;
+    }
+    const numericValues = featureValues.filter(Number.isFinite);
+    const syntheticState = {
+        nClasses: scale.params.nShades,
+        mode: scale.params.mode,
+        colorRamp: scale.params.name,
+        reverseRamp: scale.params.reverse,
+        vmin: (_a = scale.params.domain) === null || _a === void 0 ? void 0 : _a[0],
+        vmax: (_b = scale.params.domain) === null || _b === void 0 ? void 0 : _b[1],
+    };
+    const computed = computeGraduatedColorStops(syntheticState, numericValues);
+    return computed.map(s => ({
+        stop: s.value,
+        color: s.color,
+    }));
+}
+/**
+ * categorical: nominal field → RGBA color via a named palette.
+ * Unique field values are enumerated from featureValues at render time,
+ * mirroring buildCategorized.
+ *
+ * Output:
+ *   ['case',
+ *     ['==', ['get', field], val0], color0,
+ *     ...,
+ *     fallback]
+ */
+function compileCategorical(field, scale, featureValues) {
+    var _a;
+    let stops;
+    if (scale.params.colorStops && scale.params.colorStops.length > 0) {
+        stops = scale.params.colorStops.map(s => ({
+            value: s.stop,
+            color: s.color,
+        }));
+    }
+    else {
+        const syntheticState = {
+            colorRamp: scale.params.colorRamp,
+            reverseRamp: (_a = scale.params.reverse) !== null && _a !== void 0 ? _a : false,
+        };
+        stops = computeCategorizedColorStops(syntheticState, featureValues);
+    }
+    // Guard: a OL case expression requires at least one condition+value pair
+    // before the else branch. Return fallback directly when stops is empty.
+    if (stops.length === 0) {
+        return scale.params.fallback;
+    }
+    const caseExpr = ['case'];
+    for (const stop of stops) {
+        let condition;
+        if (stop.value === STOP_UNDEFINED) {
+            // Property missing entirely
+            condition = ['!', ['has', field]];
+        }
+        else if (stop.value === STOP_NULL) {
+            // Property exists but value is null
+            condition = [
+                'all',
+                ['has', field],
+                ['==', ['coalesce', fieldExpr(field), '__jgis_ns__'], '__jgis_ns__'],
+            ];
+        }
+        else {
+            condition = [
+                '==',
+                fieldExpr(field),
+                stop.value,
+            ];
+        }
+        caseExpr.push(condition, stop.color);
+    }
+    caseExpr.push(scale.params.fallback);
+    return caseExpr;
+}
+/**
+ * scalar: numeric field → numeric output (radius, width, sub-channel value).
+ *
+ * Output:
+ *   ['case', ['has', field],
+ *     ['interpolate', ['linear'], ['get', field], stop0, out0, ...],
+ *     fallback]
+ */
+function compileScalar(field, scale) {
+    const interpolateExpr = [
+        'interpolate',
+        ['linear'],
+        fieldExpr(field),
+    ];
+    if (scale.params.scalarStops && scale.params.scalarStops.length >= 2) {
+        for (const { stop, output } of scale.params.scalarStops) {
+            interpolateExpr.push(stop, output);
+        }
+    }
+    else {
+        interpolateExpr.push(scale.params.domain[0], scale.params.range[0], scale.params.domain[1], scale.params.range[1]);
+    }
+    if (fieldAlwaysPresent(field)) {
+        return interpolateExpr;
+    }
+    return ['case', ['has', field], interpolateExpr, scale.params.fallback];
+}

package/lib/{dialogs → features/layers}/symbology/hooks/useGetBandInfo.d.ts

@@ -7,7 +7,7 @@ export interface IBandRow {
         maximum: number;
     };
 }
-declare const useGetBandInfo: (model: IJupyterGISModel, layer: IJGISLayer) => {
+declare const useGetBandInfo: (model: IJupyterGISModel, layer: IJGISLayer | null | undefined) => {
     bandRows: IBandRow[];
     setBandRows: import("react").Dispatch<import("react").SetStateAction<IBandRow[]>>;
     loading: boolean;

package/lib/{dialogs → features/layers}/symbology/hooks/useGetBandInfo.js

@@ -1,6 +1,6 @@
 import { fromUrl, fromBlob } from 'geotiff';
 import { useEffect, useState } from 'react';
-import { loadFile } from "../../../tools";
+import { loadFile } from "../../../../tools";
 const useGetBandInfo = (model, layer) => {
     const [bandRows, setBandRows] = useState([]);
     const [loading, setLoading] = useState(false);

package/lib/{dialogs → features/layers}/symbology/hooks/useGetProperties.js

@@ -1,6 +1,6 @@
 // import { GeoJSONFeature } from 'geojson';
 import { useEffect, useState } from 'react';
-import { loadFile } from "../../../tools";
+import { loadFile } from "../../../../tools";
 async function getGeoJsonProperties({ source, model, }) {
     const result = {};
     const data = await (async () => {

package/lib/{dialogs → features/layers}/symbology/hooks/useGetSymbology.js

@@ -54,11 +54,13 @@ export const useGetSymbology = ({ layerId, model, }) => {
         };
         // initial load
         fetchSymbology();
-        model.sharedModel.awareness.on('change', () => {
+        const handleLayersChanged = () => {
             fetchSymbology();
-        });
+        };
+        model.sharedLayersChanged.connect(handleLayersChanged);
         return () => {
             disposed = true;
+            model.sharedLayersChanged.disconnect(handleLayersChanged);
         };
     }, [layerId, model]);
     return { symbology, isLoading, error };

package/lib/features/layers/symbology/styleBuilder.d.ts

@@ -0,0 +1,24 @@
+import { IVectorLayer } from '@jupytergis/schema';
+import { FlatStyle } from 'ol/style/flat';
+import { DEFAULT_STROKE_WIDTH, RgbaColor } from './colorRampUtils';
+export { DEFAULT_STROKE_WIDTH };
+export type SymbologyState = NonNullable<IVectorLayer['symbologyState']>;
+export type GeometryType = 'fill' | 'circle' | 'line';
+/** Default OL flat style used when no Grammar rules produce output. */
+export declare const DEFAULT_FLAT_STYLE: FlatStyle;
+/** Sentinel stop values for missing data. */
+export declare const STOP_NULL = "__null__";
+export declare const STOP_UNDEFINED = "__undefined__";
+/** A computed stop: value → RGBA color. */
+export interface IComputedStop {
+    value: number | string | boolean;
+    color: RgbaColor;
+}
+/**
+ * Compute color stops for Graduated symbology from the config + feature values.
+ */
+export declare function computeGraduatedColorStops(state: SymbologyState, numericValues: number[]): IComputedStop[];
+/**
+ * Compute color stops for Categorized symbology from the config + feature values.
+ */
+export declare function computeCategorizedColorStops(state: SymbologyState, featureValues: unknown[]): IComputedStop[];