@jupytergis/schema 0.15.0 → 0.16.0-alpha.1

package/lib/grammar/grammarConversions.js

@@ -0,0 +1,137 @@
+/**
+ * Conversions between existing symbology render types and IGrammarSymbologyState.
+ *
+ * Pure schema transforms with no OL or UI dependencies, usable both as a
+ * schema migration step and when the user switches render types in the dialog.
+ */
+import { UUID } from '@lumino/coreutils';
+const DEFAULT_STROKE_WIDTH = 1.25;
+const DEFAULT_FILL = [255, 255, 255, 0.4];
+const DEFAULT_STROKE = [51, 153, 204, 1];
+const DEFAULT_RADIUS = 5;
+const TRANSPARENT = [0, 0, 0, 0];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Wrap a list of rules in a single default IGrammarLayer. */
+function wrapLayer(rules) {
+    return [{ id: UUID.uuid4(), rules }];
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Convert a Single Symbol state to Grammar. */
+export function singleSymbolToGrammar(state) {
+    var _a, _b, _c, _d;
+    const fill = ((_a = state.fillColor) !== null && _a !== void 0 ? _a : DEFAULT_FILL);
+    const stroke = ((_b = state.strokeColor) !== null && _b !== void 0 ? _b : DEFAULT_STROKE);
+    const strokeWidth = (_c = state.strokeWidth) !== null && _c !== void 0 ? _c : DEFAULT_STROKE_WIDTH;
+    const radius = (_d = state.radius) !== null && _d !== void 0 ? _d : DEFAULT_RADIUS;
+    const rule = {
+        id: UUID.uuid4(),
+        mappings: [
+            {
+                scale: { scheme: 'constant_rgba', params: { value: fill } },
+                channels: ['fill-color', 'circle-fill-color'],
+            },
+            {
+                scale: { scheme: 'constant_rgba', params: { value: stroke } },
+                channels: ['stroke-color', 'circle-stroke-color'],
+            },
+            {
+                scale: { scheme: 'constant_num', params: { value: strokeWidth } },
+                channels: ['stroke-width', 'circle-stroke-width'],
+            },
+            {
+                scale: { scheme: 'constant_num', params: { value: radius } },
+                channels: ['circle-radius'],
+            },
+        ],
+    };
+    return { layers: wrapLayer([rule]) };
+}
+/**
+ * Convert a Graduated state to Grammar.
+ * The colorRamp scale stores recipe params; grammarToOLStyle computes
+ * classification breaks from featureValues at render time.
+ */
+export function graduatedToGrammar(state) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const field = state.value;
+    const fallback = ((_a = state.fallbackColor) !== null && _a !== void 0 ? _a : TRANSPARENT);
+    const stroke = ((_b = state.strokeColor) !== null && _b !== void 0 ? _b : DEFAULT_STROKE);
+    const strokeWidth = (_c = state.strokeWidth) !== null && _c !== void 0 ? _c : DEFAULT_STROKE_WIDTH;
+    const radius = (_d = state.radius) !== null && _d !== void 0 ? _d : DEFAULT_RADIUS;
+    const colorStops = (_e = state.stopsOverride) === null || _e === void 0 ? void 0 : _e.filter(s => s.value !== undefined && s.color !== undefined).map(s => ({
+        stop: typeof s.value === 'string' ? parseFloat(s.value) : s.value,
+        color: s.color,
+    }));
+    const colorRampScale = {
+        scheme: 'colorRamp',
+        params: Object.assign(Object.assign(Object.assign({ name: (_f = state.colorRamp) !== null && _f !== void 0 ? _f : 'viridis' }, (state.vmin !== undefined && state.vmax !== undefined
+            ? { domain: [state.vmin, state.vmax] }
+            : {})), { nShades: (_g = state.nClasses) !== null && _g !== void 0 ? _g : 9, mode: (_h = state.mode) !== null && _h !== void 0 ? _h : 'equal interval', reverse: (_j = state.reverseRamp) !== null && _j !== void 0 ? _j : false, fallback }), (colorStops && colorStops.length >= 2 ? { colorStops } : {})),
+    };
+    const fillChannels = state.strokeFollowsFill
+        ? ['fill-color', 'stroke-color', 'circle-fill-color', 'circle-stroke-color']
+        : ['fill-color', 'circle-fill-color'];
+    const mappings = [
+        { scale: colorRampScale, channels: fillChannels },
+    ];
+    if (!state.strokeFollowsFill) {
+        mappings.push({
+            scale: { scheme: 'constant_rgba', params: { value: stroke } },
+            channels: ['stroke-color', 'circle-stroke-color'],
+        });
+    }
+    mappings.push({
+        scale: { scheme: 'constant_num', params: { value: strokeWidth } },
+        channels: ['stroke-width', 'circle-stroke-width'],
+    }, {
+        scale: { scheme: 'constant_num', params: { value: radius } },
+        channels: ['circle-radius'],
+    });
+    const rule = Object.assign(Object.assign({ id: UUID.uuid4() }, (field ? { fields: [field] } : {})), { mappings: mappings });
+    return { layers: wrapLayer([rule]) };
+}
+/**
+ * Convert a Categorized state to Grammar.
+ * The categorical scale stores recipe params; grammarToOLStyle enumerates
+ * unique values from featureValues at render time.
+ */
+export function categorizedToGrammar(state) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const field = state.value;
+    const fallback = ((_a = state.fallbackColor) !== null && _a !== void 0 ? _a : TRANSPARENT);
+    const stroke = ((_b = state.strokeColor) !== null && _b !== void 0 ? _b : DEFAULT_STROKE);
+    const strokeWidth = (_c = state.strokeWidth) !== null && _c !== void 0 ? _c : DEFAULT_STROKE_WIDTH;
+    const radius = (_d = state.radius) !== null && _d !== void 0 ? _d : DEFAULT_RADIUS;
+    const catColorStops = (_e = state.stopsOverride) === null || _e === void 0 ? void 0 : _e.filter(s => s.value !== undefined && s.color !== undefined).map(s => ({ stop: s.value, color: s.color }));
+    const categoricalScale = {
+        scheme: 'categorical',
+        params: Object.assign({ colorRamp: (_f = state.colorRamp) !== null && _f !== void 0 ? _f : 'viridis', nShades: state.nClasses, reverse: (_g = state.reverseRamp) !== null && _g !== void 0 ? _g : false, fallback }, (catColorStops && catColorStops.length > 0
+            ? { colorStops: catColorStops }
+            : {})),
+    };
+    const fillChannels = state.strokeFollowsFill
+        ? ['fill-color', 'stroke-color', 'circle-fill-color', 'circle-stroke-color']
+        : ['fill-color', 'circle-fill-color'];
+    const mappings = [
+        { scale: categoricalScale, channels: fillChannels },
+    ];
+    if (!state.strokeFollowsFill) {
+        mappings.push({
+            scale: { scheme: 'constant_rgba', params: { value: stroke } },
+            channels: ['stroke-color', 'circle-stroke-color'],
+        });
+    }
+    mappings.push({
+        scale: { scheme: 'constant_num', params: { value: strokeWidth } },
+        channels: ['stroke-width', 'circle-stroke-width'],
+    }, {
+        scale: { scheme: 'constant_num', params: { value: radius } },
+        channels: ['circle-radius'],
+    });
+    const rule = Object.assign(Object.assign({ id: UUID.uuid4() }, (field ? { fields: [field] } : {})), { mappings: mappings });
+    return { layers: wrapLayer([rule]) };
+}

package/lib/index.d.ts

@@ -1,6 +1,10 @@
 export * from './interfaces';
+export { singleSymbolToGrammar, graduatedToGrammar, categorizedToGrammar, } from './grammar/grammarConversions';
+export type { SymbologyState } from './grammar/grammarConversions';
+export { migrateDocument } from './migrations';
 export * from './model';
 export * from './token';
+export type * from './types';
 export * from './doc';
 export { SCHEMA_VERSION } from './_interface/version';
 export { ProcessingMerge, ProcessingCommandIDs, ProcessingLogicType, } from './processing/ProcessingMerge';

package/lib/index.js

@@ -1,4 +1,6 @@
 export * from './interfaces';
+export { singleSymbolToGrammar, graduatedToGrammar, categorizedToGrammar, } from './grammar/grammarConversions';
+export { migrateDocument } from './migrations';
 export * from './model';
 export * from './token';
 export * from './doc';

package/lib/interfaces.d.ts

@@ -9,9 +9,13 @@ import { JSONObject } from '@lumino/coreutils';
 import { ISignal, Signal } from '@lumino/signaling';
 import { SplitPanel } from '@lumino/widgets';
 import { FeatureLike } from 'ol/Feature';
-import { IJGISContent, IJGISLayer, IJGISLayerGroup, IJGISLayerItem, IJGISLayers, IJGISLayerTree, IJGISOptions, IJGISSource, IJGISSources, IJGISStoryMap, LayerType, SourceType } from './_interface/project/jgis';
-import { IGeoJSONSource, IGeoParquetSource, IGeoTiffSource, IHeatmapLayer, IHillshadeLayer, IImageLayer, IImageSource, IMarkerSource, IRasterDemSource, IRasterLayer, IRasterSource, IShapefileSource, IStacLayer, IStorySegmentLayer, IVectorLayer, IVectorTileLayer, IVectorTileSource, IVideoSource, IWebGlLayer, Modes } from './types';
-export { IGeoJSONSource } from './_interface/project/sources/geoJsonSource';
+import { IJGISContent, IJGISLayer, IJGISLayerGroup, IJGISLayerItem, IJGISLayers, IJGISLayerTree, IJGISOptions, IJGISSource, IJGISSources, IJGISStoryMap, IJGISViewState, LayerType, SourceType } from './_interface/project/jgis';
+import { IGeoJSONSource, IGeoParquetSource, IGeoTiffSource, IHillshadeLayer, IImageLayer, IImageSource, IMarkerSource, IRasterDemSource, IRasterLayer, IRasterSource, IOpenEOTileLayer, IOpenEOTileSource, IShapefileSource, IStacLayer, IStorySegmentLayer, IVectorLayer, IVectorTileLayer, IVectorTileSource, IVideoSource, IGeoTiffLayer, Modes } from './types';
+export type { IGeoJSONSource } from './_interface/project/sources/geoJsonSource';
+export interface IJGISUIState {
+    leftPanelOpen?: boolean;
+    rightPanelOpen?: boolean;
+}
 export interface IJGISStoryMaps {
     [k: string]: IJGISStoryMap;
 }
@@ -22,6 +26,7 @@ export type JgisCoordinates = {
 export interface IViewPortState {
     coordinates: JgisCoordinates;
     zoom: number;
+    extent: [number, number, number, number];
 }
 export type Pointer = {
     coordinates: {
@@ -59,6 +64,22 @@ export interface ISelection {
     type: SelectionType;
     parent?: string;
 }
+export interface IIdentifiedFeature {
+    _id?: string;
+    _fromDrawTool?: boolean;
+    geometry?: unknown;
+    _geometry?: unknown;
+    [key: string]: unknown;
+}
+export interface IIdentifiedFeatureEntry {
+    feature: IIdentifiedFeature;
+    floaterOpen?: boolean;
+}
+export type IIdentifiedFeatures = IIdentifiedFeatureEntry[];
+export interface IIdentifiedFeaturesAwarenessState {
+    value?: IIdentifiedFeatures;
+    emitter?: string | null;
+}
 export interface IJupyterGISClientState {
     selected: {
         value?: {
@@ -66,6 +87,9 @@ export interface IJupyterGISClientState {
         };
         emitter?: string | null;
     };
+    lastAddedLayer?: {
+        layerId?: string;
+    };
     selectedPropField?: {
         id: string | null;
         value: any;
@@ -79,25 +103,42 @@ export interface IJupyterGISClientState {
         value?: Pointer;
         emitter?: string | null;
     };
-    identifiedFeatures: {
-        value?: any;
-        emitter?: string | null;
-    };
+    identifiedFeatures: IIdentifiedFeaturesAwarenessState;
     user: User.IIdentity;
     remoteUser?: number;
     toolbarForm?: IDict;
     isTemporalControllerActive: boolean;
 }
+export declare const AWARENESS_STATE_FIELDS: {
+    readonly selected: "selected";
+    readonly pointer: "pointer";
+    readonly viewportState: "viewportState";
+    readonly identifiedFeatures: "identifiedFeatures";
+    readonly remoteUser: "remoteUser";
+    readonly isTemporalControllerActive: "isTemporalControllerActive";
+    readonly lastAddedLayer: "lastAddedLayer";
+};
+export type AwarenessFieldKey = (typeof AWARENESS_STATE_FIELDS)[keyof typeof AWARENESS_STATE_FIELDS];
+export declare const AWARENESS_FIELD_KEYS: AwarenessFieldKey[];
+export interface IAwarenessFieldChange<T = any> {
+    clientId: number;
+    field: AwarenessFieldKey;
+    previousValue: T | undefined;
+    currentValue: T | undefined;
+    fullState: IJupyterGISClientState | undefined;
+    isLocalClient: boolean;
+}
 export interface IJupyterGISDoc extends YDocument<IJupyterGISDocChange> {
     options: IJGISOptions;
     layers: IJGISLayers;
     sources: IJGISSources;
     stories: IJGISStoryMaps;
     layerTree: IJGISLayerTree;
+    viewState: IJGISViewState;
     metadata: any;
     readonly editable: boolean;
     readonly toJGISEndpoint?: string;
-    getSource(): JSONObject;
+    getSource(): string;
     setSource(value: JSONObject | string): void;
     layerExists(id: string): boolean;
     getLayer(id: string): IJGISLayer | undefined;
@@ -143,15 +184,34 @@ export interface IJupyterGISDocChange extends DocumentChange {
     optionChange?: MapChange;
     stateChange?: StateChange<any>[];
 }
+export interface IViewState {
+    [id: string]: {
+        extent: number[];
+        zoom: number;
+        projection?: string;
+        layerId?: string;
+        layerName?: string;
+    };
+}
+export interface IStorySegmentRef {
+    storySegmentId: string;
+    storyId: string;
+}
 export interface IJupyterGISModel extends DocumentRegistry.IModel {
     isDisposed: boolean;
     sharedModel: IJupyterGISDoc;
     geolocation: JgisCoordinates;
     localState: IJupyterGISClientState | null;
+    viewState?: IViewState;
     annotationModel?: IAnnotationModel;
     currentMode: Modes;
     themeChanged: Signal<IJupyterGISModel, IChangedArgs<string, string | null, string>>;
-    clientStateChanged: ISignal<IJupyterGISModel, Map<number, IJupyterGISClientState>>;
+    selectedChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['selected']>>;
+    pointerChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['pointer']>>;
+    viewportStateChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['viewportState']>>;
+    identifiedFeaturesChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['identifiedFeatures']>>;
+    remoteUserChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['remoteUser']>>;
+    temporalControllerActiveChanged: ISignal<IJupyterGISModel, IAwarenessFieldChange<IJupyterGISClientState['isTemporalControllerActive']>>;
     sharedOptionsChanged: ISignal<IJupyterGISDoc, MapChange>;
     sharedLayersChanged: ISignal<IJupyterGISDoc, IJGISLayerDocChange>;
     sharedLayerTreeChanged: ISignal<IJupyterGISDoc, IJGISLayerTreeDocChange>;
@@ -164,6 +224,7 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
     flyToGeometrySignal: Signal<IJupyterGISModel, any>;
     highlightFeatureSignal: Signal<IJupyterGISModel, any>;
     updateBboxSignal: Signal<IJupyterGISModel, any>;
+    editingVectorLayerChanged: ISignal<IJupyterGISModel, boolean>;
     contentsManager: Contents.IManager | undefined;
     filePath: string;
     pathChanged: ISignal<IJupyterGISModel, string>;
@@ -176,11 +237,14 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
         features: FeatureLike[];
     }) => void;
     getSettings(): Promise<ISettingRegistry.ISettings>;
+    settingsReady: Promise<void>;
     settingsChanged: ISignal<IJupyterGISModel, string>;
     jgisSettings: IJupyterGISSettings;
     getContent(): IJGISContent;
+    getViewState(): IViewState;
     getLayers(): IJGISLayers;
     getLayer(id: string): IJGISLayer | undefined;
+    getExtent(id: string): number[] | undefined;
     getLayerOrSource(id: string): IJGISLayer | IJGISSource | undefined;
     getSources(): IJGISSources;
     getSource(id: string): IJGISSource | undefined;
@@ -189,6 +253,7 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
     };
     getLayerTree(): IJGISLayerTree;
     addLayer(id: string, layer: IJGISLayer, groupName?: string, position?: number): void;
+    updateLayerViewState(id: string, view: IViewState[string]): void;
     removeLayer(id: string): void;
     removeSource(id: string): void;
     getOptions(): IJGISOptions;
@@ -207,6 +272,7 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
     selected: {
         [key: string]: ISelection;
     } | undefined;
+    syncLastAddedLayer(layerId: string): void;
     setEditingItem(type: SelectionType, itemId: string): void;
     clearEditingItem(): void;
     readonly editing: {
@@ -218,13 +284,16 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
         itemId: string;
     } | null>;
     syncPointer(pointer?: Pointer, emitter?: string): void;
-    syncIdentifiedFeatures(features: IDict<any>, emitter?: string): void;
+    syncIdentifiedFeatures(features: IIdentifiedFeatures, emitter?: string): void;
     setUserToFollow(userId?: number): void;
     getClientId(): number;
     addMetadata(key: string, value: string): void;
     removeMetadata(key: string): void;
     centerOnPosition(id: string): void;
     toggleMode(mode: Modes): void;
+    editingVectorLayer: boolean;
+    updateEditingVectorLayer(): void;
+    checkIfIsADrawVectorLayer(layer: IJGISLayer): boolean;
     isTemporalControllerActive: boolean;
     toggleTemporalController(): void;
     addFeatureAsMs(id: string, selectedFeature: string): void;
@@ -237,15 +306,13 @@ export interface IJupyterGISModel extends DocumentRegistry.IModel {
     getCurrentSegmentIndex(): number;
     setCurrentSegmentIndex(index: number): void;
     currentSegmentIndexChanged: ISignal<IJupyterGISModel, number>;
-    addStorySegment(): {
-        storySegmentId: string;
-        storyId: string;
-    } | null;
-    segmentAdded: ISignal<IJupyterGISModel, {
-        storySegmentId: string;
-        storyId: string;
-    }>;
+    addStorySegment(viewState?: IViewState[string]): IStorySegmentRef | null;
+    createStorySegmentFromLayer(layerId: string): IStorySegmentRef | null;
+    segmentAdded: ISignal<IJupyterGISModel, IStorySegmentRef>;
     isSpectaMode(): boolean;
+    setUIState(value: Partial<IJGISUIState>): void;
+    getUIState(): IJGISUIState;
+    uiStateChanged: ISignal<IJupyterGISModel, IJGISUIState>;
 }
 export interface IUserData {
     userId: number;
@@ -303,9 +370,9 @@ export type ILayerGalleryEntry = {
     name: string;
     thumbnail: string;
     layerType: LayerType;
-    layerParameters: IHeatmapLayer | IHillshadeLayer | IImageLayer | IRasterLayer | IStacLayer | IStorySegmentLayer | IVectorLayer | IVectorTileLayer | IWebGlLayer;
+    layerParameters: IHillshadeLayer | IImageLayer | IRasterLayer | IStacLayer | IStorySegmentLayer | IVectorLayer | IVectorTileLayer | IGeoTiffLayer | IOpenEOTileLayer;
     sourceType: SourceType;
-    sourceParameters: IGeoJSONSource | IGeoParquetSource | IGeoTiffSource | IImageSource | IMarkerSource | IRasterDemSource | IRasterSource | IShapefileSource | IVectorTileSource | IVideoSource;
+    sourceParameters: IGeoJSONSource | IGeoParquetSource | IGeoTiffSource | IImageSource | IMarkerSource | IRasterDemSource | IRasterSource | IShapefileSource | IVectorTileSource | IVideoSource | IOpenEOTileSource;
     provider: string;
     description: string;
 };
@@ -354,4 +421,5 @@ export interface IJupyterGISSettings {
     identifyDisabled?: boolean;
     storyMapsDisabled: boolean;
     zoomButtonsEnabled?: boolean;
+    useServerGdalProcessing?: boolean | null;
 }

package/lib/interfaces.js

@@ -1 +1,10 @@
-export {};
+export const AWARENESS_STATE_FIELDS = {
+    selected: 'selected',
+    pointer: 'pointer',
+    viewportState: 'viewportState',
+    identifiedFeatures: 'identifiedFeatures',
+    remoteUser: 'remoteUser',
+    isTemporalControllerActive: 'isTemporalControllerActive',
+    lastAddedLayer: 'lastAddedLayer',
+};
+export const AWARENESS_FIELD_KEYS = Object.values(AWARENESS_STATE_FIELDS);

package/lib/migrations/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JupyterGIS document migration runner.
+ *
+ * Each step in STEPS is a { from, to, migrate } record where `migrate` takes
+ * a parsed document object and returns a new object. Steps must be listed in
+ * order and form a contiguous chain.
+ */
+/**
+ * Apply all necessary migration steps to bring *doc* up to *toVersion*.
+ *
+ * @param doc - Parsed jGIS document object.
+ * @param toVersion - Target schema version. Defaults to the current
+ *   SCHEMA_VERSION if omitted.
+ * @throws If the document's version is newer than the current schema version.
+ */
+export declare function migrateDocument(doc: Record<string, any>, toVersion?: string): Record<string, any>;

package/lib/migrations/index.js

@@ -0,0 +1,52 @@
+/**
+ * JupyterGIS document migration runner.
+ *
+ * Each step in STEPS is a { from, to, migrate } record where `migrate` takes
+ * a parsed document object and returns a new object. Steps must be listed in
+ * order and form a contiguous chain.
+ */
+import { migrate as migrateV0_5ToV0_6 } from './v0_5_to_v0_6';
+import { SCHEMA_VERSION } from '../_interface/version';
+const STEPS = [
+    { from: '0.5.0', to: '0.6.0', migrate: migrateV0_5ToV0_6 },
+];
+/**
+ * Apply all necessary migration steps to bring *doc* up to *toVersion*.
+ *
+ * @param doc - Parsed jGIS document object.
+ * @param toVersion - Target schema version. Defaults to the current
+ *   SCHEMA_VERSION if omitted.
+ * @throws If the document's version is newer than the current schema version.
+ */
+export function migrateDocument(doc, toVersion) {
+    var _a;
+    const target = toVersion !== null && toVersion !== void 0 ? toVersion : SCHEMA_VERSION;
+    const fileVersion = (_a = doc.schemaVersion) !== null && _a !== void 0 ? _a : '0.5.0';
+    if (_compareVersions(fileVersion, SCHEMA_VERSION) > 0) {
+        throw new Error(`Cannot load file with schema version ${fileVersion} (current: ${SCHEMA_VERSION})`);
+    }
+    let current = fileVersion;
+    let result = Object.assign({}, doc);
+    for (const step of STEPS) {
+        if (_compareVersions(current, step.to) < 0 &&
+            _compareVersions(step.to, target) <= 0) {
+            result = step.migrate(result);
+            result.schemaVersion = step.to;
+            current = step.to;
+        }
+    }
+    return result;
+}
+/** Simple semver comparison: returns negative, 0, or positive. */
+function _compareVersions(a, b) {
+    var _a, _b;
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const diff = ((_a = pa[i]) !== null && _a !== void 0 ? _a : 0) - ((_b = pb[i]) !== null && _b !== void 0 ? _b : 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}

package/lib/migrations/v0_5_to_v0_6.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Migration from schema version 0.5.0 to 0.6.0.
+ *
+ * Converts legacy representations to Grammar symbologyState in one pass:
+ *  - parameters.color (flat OL FlatStyle keys) → Grammar directly
+ *  - parameters.symbologyState with old render types → Grammar
+ *  - HeatmapLayer color array → symbologyState.gradient
+ *  - WebGlLayer type → GeoTiffLayer
+ *  - layer.filters → grammar layer-level when + whenOp (filters removed)
+ */
+export declare function migrate(doc: Record<string, any>): Record<string, any>;

package/lib/migrations/v0_5_to_v0_6.js

@@ -0,0 +1,154 @@
+/**
+ * Migration from schema version 0.5.0 to 0.6.0.
+ *
+ * Converts legacy representations to Grammar symbologyState in one pass:
+ *  - parameters.color (flat OL FlatStyle keys) → Grammar directly
+ *  - parameters.symbologyState with old render types → Grammar
+ *  - HeatmapLayer color array → symbologyState.gradient
+ *  - WebGlLayer type → GeoTiffLayer
+ *  - layer.filters → grammar layer-level when + whenOp (filters removed)
+ */
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { categorizedToGrammar, graduatedToGrammar, singleSymbolToGrammar, } from '../grammar/grammarConversions';
+export function migrate(doc) {
+    var _a, _b;
+    const layers = Object.assign({}, doc.layers);
+    for (const [id, layer] of Object.entries(layers)) {
+        const newType = layer.type === 'WebGlLayer' ? 'GeoTiffLayer' : layer.type;
+        const params = layer === null || layer === void 0 ? void 0 : layer.parameters;
+        if (!params) {
+            if (newType !== layer.type) {
+                layers[id] = Object.assign(Object.assign({}, layer), { type: newType });
+            }
+            continue;
+        }
+        const newParams = Object.assign({}, params);
+        if (layer.type === 'VectorLayer' || layer.type === 'VectorTileLayer') {
+            const color = newParams.color;
+            if (color && typeof color === 'object' && !Array.isArray(color)) {
+                // Flat OL color dict → Grammar (skip intermediate symbologyState format)
+                newParams.symbologyState = singleSymbolToGrammar(_colorToState(color));
+                delete newParams.color;
+            }
+            else {
+                // Handle files that already carry old-style symbologyState (defensive)
+                const state = newParams.symbologyState;
+                if ((state === null || state === void 0 ? void 0 : state.renderType) && state.renderType !== 'Grammar') {
+                    switch (state.renderType) {
+                        case 'Single Symbol':
+                            newParams.symbologyState = singleSymbolToGrammar(state);
+                            break;
+                        case 'Graduated':
+                            newParams.symbologyState = graduatedToGrammar(state);
+                            break;
+                        case 'Categorized':
+                            newParams.symbologyState = categorizedToGrammar(state);
+                            break;
+                    }
+                }
+            }
+        }
+        else if (layer.type === 'HeatmapLayer') {
+            if (Array.isArray(newParams.color)) {
+                const state = (_a = newParams.symbologyState) !== null && _a !== void 0 ? _a : { renderType: 'Heatmap' };
+                if (!state.gradient) {
+                    newParams.symbologyState = Object.assign(Object.assign({}, state), { gradient: newParams.color });
+                }
+                delete newParams.color;
+            }
+        }
+        // Convert legacy layer.filters → grammar layer-level when + whenOp.
+        const filters = layer.filters;
+        if ((_b = filters === null || filters === void 0 ? void 0 : filters.appliedFilters) === null || _b === void 0 ? void 0 : _b.length) {
+            const logicalOp = filters.logicalOp === 'any' ? 'any' : 'all';
+            const predicates = [];
+            for (const item of filters.appliedFilters) {
+                if (item.operator === 'between') {
+                    if (item.betweenMin !== undefined && item.betweenMax !== undefined) {
+                        predicates.push({
+                            type: 'between',
+                            field: item.feature,
+                            min: item.betweenMin,
+                            max: item.betweenMax,
+                        });
+                    }
+                }
+                else if (item.operator === '==') {
+                    predicates.push({
+                        type: 'fieldEquals',
+                        field: item.feature,
+                        value: item.value,
+                    });
+                }
+                else {
+                    predicates.push({
+                        type: 'fieldCompare',
+                        field: item.feature,
+                        op: item.operator,
+                        value: item.value,
+                    });
+                }
+            }
+            if (predicates.length) {
+                const symbologyState = newParams.symbologyState;
+                if (Array.isArray(symbologyState === null || symbologyState === void 0 ? void 0 : symbologyState.layers) &&
+                    symbologyState.layers.length > 0) {
+                    newParams.symbologyState = Object.assign(Object.assign({}, symbologyState), { layers: symbologyState.layers.map((gl) => {
+                            var _a, _b;
+                            return (Object.assign(Object.assign({}, gl), { when: [...((_a = gl.when) !== null && _a !== void 0 ? _a : []), ...predicates], whenOp: (_b = gl.whenOp) !== null && _b !== void 0 ? _b : logicalOp }));
+                        }) });
+                }
+            }
+        }
+        const _c = Object.assign(Object.assign({}, layer), { type: newType }), { filters: _ } = _c, layerWithoutFilters = __rest(_c, ["filters"]);
+        layers[id] = Object.assign(Object.assign({}, layerWithoutFilters), { parameters: newParams });
+    }
+    return Object.assign(Object.assign({}, doc), { layers });
+}
+/** Build a SymbologyState from a flat OL color dict. */
+function _colorToState(color) {
+    var _a;
+    const state = { renderType: 'Single Symbol' };
+    const fill = _firstSolidColor(color['fill-color'], color['circle-fill-color']);
+    if (fill) {
+        state.fillColor = fill;
+    }
+    const stroke = _firstSolidColor(color['stroke-color'], color['circle-stroke-color']);
+    if (stroke) {
+        state.strokeColor = stroke;
+    }
+    const sw = (_a = color['stroke-width']) !== null && _a !== void 0 ? _a : color['circle-stroke-width'];
+    if (typeof sw === 'number') {
+        state.strokeWidth = sw;
+    }
+    const r = color['circle-radius'];
+    if (typeof r === 'number') {
+        state.radius = r;
+    }
+    return state;
+}
+function _firstSolidColor(...candidates) {
+    for (const c of candidates) {
+        if (Array.isArray(c) && c.length >= 3 && typeof c[0] === 'number') {
+            const [r = 0, g = 0, b = 0, a = 1] = c;
+            return [r, g, b, a];
+        }
+        if (typeof c === 'string') {
+            const m = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(c);
+            if (m) {
+                return [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16), 1];
+            }
+        }
+    }
+    return undefined;
+}