Support inline GeoJSON styles in notebook bridge (#1619)

* fix: support inline GeoJSON styles in notebooks

* fix: skip empty notebook style updates

* Address review feedback

- Extract the empty-style guard in `addGeoJsonLayer` into a documented
  `styleParamPatch` helper (`scripting/style-params.ts`), so the rule that a
  `{}` payload writes nothing is testable on its own. The scripting module
  itself pulls in the plugin/map stack (and its CSS) and cannot be imported
  under `node --test`.
- Add `tests/scripting-style-params.test.ts`: covers the patch helper and
  replays what the handler does against the real store — the style merges onto
  the new layer, and a style-less call still costs exactly one undo step.
- docs/notebook.md: flag that the fire-and-forget client returns no layer id,
  so the `layer_id`-taking calls in the snippet need one from the blocking
  widget client.

* Address Claude review feedback

- Give the in-app Pyodide console's `add_geojson` the same `**style` kwargs as
  the notebook client, so one-call styling behaves identically across both
  Python entry points (flagged in the review summary as an inconsistency).

* Document the console's inline add_geojson styles

- Update the Python console user guide for the `**style` kwargs added to
  `console_api.add_geojson` in c3c5b22.

Author: giswqs

apps/geolibre-desktop/src/lib/pyodide/console_api.py

@@ -187,13 +187,15 @@ def get_layer(self, layer_id):
                 return layer
         raise ValueError(f"No layer with id {layer_id!r}")
 
-    def add_geojson(self, data, name="GeoJSON"):
+    def add_geojson(self, data, name="GeoJSON", **style):
         """Add a GeoJSON layer from a dict / geometry / ``__geo_interface__``.
 
+        Style overrides (e.g. ``fillColor="#facc15"``) are applied to the new
+        layer in the same call, matching the notebook client's ``add_geojson``.
         Returns the new layer id. For a remote URL use :meth:`load_geojson`.
         """
         fc = _coerce_featurecollection(data)
-        return _js.addGeoJsonLayer(_to_js({"name": name, "geojson": fc}))
+        return _js.addGeoJsonLayer(_to_js({"name": name, "geojson": fc, "style": style}))
 
     async def load_geojson(self, url, name="GeoJSON"):
         """Fetch a GeoJSON URL and add it as a layer (async). Returns the id."""

apps/geolibre-desktop/src/lib/scripting/scriptingApi.ts

@@ -12,6 +12,7 @@ import type { Feature, FeatureCollection } from "geojson";
 import type { MapController } from "@geolibre/map";
 import { beginProcessingRun } from "../processing-history";
 import { captureMapImage } from "../print-layout-export";
+import { styleParamPatch } from "./style-params";
 
 // The scripting command surface, shared by every programmatic entry point: the
 // Jupyter widget's postMessage bridge (useCommandBridge) and the in-app Python
@@ -129,7 +130,12 @@ export function createScriptingHandlers(deps: ScriptingDeps): ScriptingHandlers
     addGeoJsonLayer: (params) => {
       const name = String(params.name ?? "GeoJSON");
       const geojson = params.geojson as FeatureCollection;
-      return useAppStore.getState().addGeoJsonLayer(name, geojson);
+      const layerId = useAppStore.getState().addGeoJsonLayer(name, geojson);
+      const style = styleParamPatch(params.style);
+      if (style) {
+        useAppStore.getState().setLayerStyle(layerId, style);
+      }
+      return layerId;
     },
     removeLayer: (params) => {
       useAppStore.getState().removeLayer(requireLayerId(params));

apps/geolibre-desktop/src/lib/scripting/style-params.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize a `style` command param into a layer-style patch.
+ *
+ * The Python notebook client collects style kwargs with `**style`, so it always
+ * sends a `style` object — `{}` when the caller passed none. Applying an empty
+ * patch would still call `setLayerStyle`, which rebuilds the layer object and
+ * pushes a no-op undo entry, so a plain `add_geojson(gdf, name=…)` would cost
+ * two undo steps instead of one. Returning `null` for anything that isn't a
+ * non-empty plain object lets callers skip the store write entirely.
+ *
+ * @param value - The raw `style` param, from an untrusted command payload.
+ * @returns The patch to merge, or `null` when there is nothing to apply.
+ */
+export function styleParamPatch(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const style = value as Record<string, unknown>;
+  return Object.keys(style).length > 0 ? style : null;
+}

backend/geolibre_server/notebook_client.py

@@ -361,17 +361,23 @@ def set_basemap(self, url: str) -> None:
 
     # -- layers ---------------------------------------------------------------
 
-    def add_geojson(self, data: Any, name: str = "GeoJSON") -> None:
+    def add_geojson(self, data: Any, name: str = "GeoJSON", **style: Any) -> None:
         """Add a GeoJSON layer.
 
         Args:
             data: A FeatureCollection/Feature/geometry dict, a JSON string, or
                 any object with ``__geo_interface__`` (e.g. a GeoDataFrame).
             name: Layer display name.
+            **style: Style overrides applied when the layer is created (e.g.
+                ``fillColor="#facc15"`` or ``strokeColor="#d97706"``).
         """
         _send(
             "addGeoJsonLayer",
-            {"name": name, "geojson": _to_featurecollection(data)},
+            {
+                "name": name,
+                "geojson": _to_featurecollection(data),
+                "style": dict(style),
+            },
         )
 
     def add_marker(
@@ -391,8 +397,8 @@ def add_markers(self, points: Iterable[Any], *, name: str = "Markers") -> None:
             {"name": name, "geojson": _points_to_featurecollection(points)},
         )
 
-    # add_circle_markers is an alias today (styling is applied via set_style or
-    # the Style panel); kept for parity with the geolibre package's vocabulary.
+    # add_circle_markers is an alias today; kept for parity with the geolibre
+    # package's vocabulary.
     add_circle_markers = add_markers
 
     def remove_layer(self, layer_id: str) -> None:

backend/geolibre_server/tests/test_notebook_client.py

@@ -178,6 +178,22 @@ def test_add_geojson_wraps_a_bare_geometry(relay, displays):
     params = json.loads(relay.calls[0].data)["params"]
     assert params["name"] == "Pin"
     assert params["geojson"]["features"][0]["geometry"]["coordinates"] == [1, 2]
+    assert params["style"] == {}
+
+
+def test_add_geojson_sends_inline_style_overrides(relay, displays):
+    notebook_client.HostMap().add_geojson(
+        {"type": "FeatureCollection", "features": []},
+        name="Major Cities",
+        fillColor="#facc15",
+        strokeColor="#d97706",
+    )
+
+    params = json.loads(relay.calls[0].data)["params"]
+    assert params["style"] == {
+        "fillColor": "#facc15",
+        "strokeColor": "#d97706",
+    }
 
 
 def test_add_markers_builds_a_point_collection(relay, displays):

docs/notebook.md

@@ -28,9 +28,17 @@ import geolibre
 
 m = geolibre.connect()          # or geolibre.Map()
 m.fly_to(-122.4, 37.8, zoom=11) # animate the live map in the left pane
-m.add_geojson(gdf, name="My layer")   # GeoDataFrame, dict, or JSON string
+m.add_geojson(
+    gdf,
+    name="My layer",
+    fillColor="#facc15",
+    strokeColor="#d97706",
+)  # GeoDataFrame, dict, or JSON string
 m.fit_bounds([-123, 37, -122, 38])
 m.set_basemap("https://…/style.json")
+
+# Layer-targeted calls take a layer id. This client is fire-and-forget, so
+# `add_geojson` does not hand one back — see the note below.
 m.set_visibility(layer_id, False)
 m.remove_layer(layer_id)
 ```
@@ -43,6 +51,9 @@ client source: `backend/geolibre_server/notebook_client.py`.
 
 > Read-back queries (e.g. `get_center`) are not exposed by this fire-and-forget
 > client; they need the blocking request/reply path the `geolibre` widget uses.
+> Layer ids come from the same path: this client's `add_geojson` returns
+> `None`, while the widget's ([`geolibre` package](python.md)) returns the new
+> layer's id — which is what the id-taking calls above expect.
 
 ## Driving the map from an external client (VS Code, …)
 

docs/user-guide/python-console.md

@@ -63,7 +63,9 @@ define in a script is immediately usable in the console, and vice-versa.
 ```python
 # Add data (a GeoJSON dict, a geometry, or anything with __geo_interface__)
 layer_id = geolibre.add_geojson(
-    {"type": "Point", "coordinates": [-122.4, 37.8]}, name="Pin"
+    {"type": "Point", "coordinates": [-122.4, 37.8]},
+    name="Pin",
+    fillColor="#facc15",  # style overrides are applied in the same call
 )
 
 # Style, toggle, and inspect layers
@@ -121,7 +123,7 @@ is available this way.
 | `fit_bounds([w, s, e, n])` | Fit the camera to a bounding box. |
 | `set_basemap(url)` | Set the basemap style (an http(s) or root-relative URL). |
 | `identify(lng, lat, layer_id=None)` | Query rendered features at a point (like a click). |
-| `add_geojson(data, name=)` | Add a layer from a GeoJSON dict / geometry / `__geo_interface__`; returns the layer id. |
+| `add_geojson(data, name=, **style)` | Add a layer from a GeoJSON dict / geometry / `__geo_interface__`, with optional inline style overrides; returns the layer id. |
 | `await load_geojson(url, name=)` | Fetch a GeoJSON URL and add it; returns the layer id. |
 | `layers` | List of [`Layer`](#layer) objects, in draw order. |
 | `get_layer(layer_id)` | The `Layer` with that id (raises if absent). |

tests/scripting-style-params.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import { useAppStore } from "@geolibre/core";
+import { styleParamPatch } from "../apps/geolibre-desktop/src/lib/scripting/style-params";
+
+// The notebook client's `add_geojson(gdf, **style)` always sends a `style`
+// object, so the scripting handler's `addGeoJsonLayer` decides — via
+// `styleParamPatch` — whether that payload is worth a store write at all. The
+// handler module itself pulls in the whole plugin/map stack (and its CSS), so
+// these tests exercise the decision helper directly and then replay what the
+// handler does with it against the real store.
+
+const FC = {
+  type: "FeatureCollection" as const,
+  features: [
+    {
+      type: "Feature" as const,
+      properties: {},
+      geometry: { type: "Point" as const, coordinates: [0, 0] },
+    },
+  ],
+};
+
+describe("styleParamPatch", () => {
+  it("keeps a non-empty style object", () => {
+    const style = { fillColor: "#facc15", strokeWidth: 2 };
+    assert.deepEqual(styleParamPatch(style), style);
+  });
+
+  it("rejects an empty object, so a style-less call writes nothing", () => {
+    assert.equal(styleParamPatch({}), null);
+  });
+
+  it("rejects missing and non-object payloads", () => {
+    assert.equal(styleParamPatch(undefined), null);
+    assert.equal(styleParamPatch(null), null);
+    assert.equal(styleParamPatch("fillColor"), null);
+    assert.equal(styleParamPatch(["fillColor"]), null);
+  });
+});
+
+describe("addGeoJsonLayer command styling", () => {
+  beforeEach(() => {
+    useAppStore.getState().newProject({ name: "Scripting" });
+    useAppStore.temporal.getState().clear();
+  });
+
+  it("merges an inline style into the new layer", () => {
+    const layerId = useAppStore.getState().addGeoJsonLayer("Styled", FC);
+    const style = styleParamPatch({ fillColor: "#facc15", strokeColor: "#d97706" });
+    assert.ok(style);
+    useAppStore.getState().setLayerStyle(layerId, style);
+
+    const layer = useAppStore.getState().layers.find((item) => item.id === layerId);
+    assert.equal(layer?.style?.fillColor, "#facc15");
+    assert.equal(layer?.style?.strokeColor, "#d97706");
+  });
+
+  it("costs a single undo step when no style kwargs were passed", () => {
+    const layerId = useAppStore.getState().addGeoJsonLayer("Plain", FC);
+    const style = styleParamPatch({});
+    if (style) useAppStore.getState().setLayerStyle(layerId, style);
+
+    assert.equal(useAppStore.temporal.getState().pastStates.length, 1);
+    useAppStore.temporal.getState().undo();
+    assert.equal(
+      useAppStore.getState().layers.find((item) => item.id === layerId),
+      undefined,
+    );
+  });
+});