Add explore() function and GISDocument.sidecar() method

docs/environment-docs.yml

@@ -25,3 +25,4 @@ dependencies:
       # See: https://github.com/geojupyter/jupytergis/issues/585
       - ../python/jupytergis_core
       - ../python/jupytergis_lab
+      - ../python/jupytergis

docs/user_guide/python_api.md

@@ -34,9 +34,15 @@ doc
 
 Once the document is opened/created, you can start creating GIS layers.
 
-## `GISDocument` API Reference
+## `explore`
 
 ```{eval-rst}
-.. autoclass:: jupytergis_lab.GISDocument
+.. autofunction:: jupytergis.explore
+```
+
+## `GISDocument`
+
+```{eval-rst}
+.. autoclass:: jupytergis.GISDocument
     :members:
 ```

examples/explore.ipynb

@@ -0,0 +1,111 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c3f4096f-cbd3-43e8-a986-520681f03581",
+   "metadata": {},
+   "source": [
+    "# ESPM 157 - Intro to Spatial Data\n",
+    "\n",
+    "<https://espm-157.carlboettiger.info/spatial-1>\n",
+    "\n",
+    "Install dependencies:\n",
+    "\n",
+    "```bash\n",
+    "micromamba install geopandas ibis-duckdb\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b76ae1f0-334e-41c0-9533-407c879b4ad6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ibis\n",
+    "\n",
+    "con = ibis.duckdb.connect()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "837aa4e0-5eeb-48c1-97ce-3f8706503911",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "redlines = con.read_geo(\n",
+    "    \"/vsicurl/https://dsl.richmond.edu/panorama/redlining/static/mappinginequality.gpkg\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4d3319fa-b3b4-4931-b073-98b649e41b65",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "city = redlines.filter(redlines.city == \"New Haven\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34f7f4d6-28d6-4716-8e03-ac32c6ae3bb7",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "city_gdf = city.head().execute()\n",
+    "city_gdf.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d37a610a-1444-43a3-900f-dfe16a890ab9",
+   "metadata": {},
+   "source": [
+    "## OK, but what about spatial context?\n",
+    "\n",
+    "I want to explore this data more interactively."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e68aaac-dfc0-42d8-a3b9-05fce59524b2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from jupytergis import explore\n",
+    "\n",
+    "# Open a new exploration window\n",
+    "explore(city_gdf, layer_name=\"New Haven\", basemap=\"dark\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

packages/base/src/panelview/components/layers.tsx

@@ -171,6 +171,7 @@ function LayersBodyComponent(props: IBodyProps): JSX.Element {
     model?.sharedModel.layersChanged.connect(updateLayers);
     model?.sharedModel.layerTreeChanged.connect(updateLayers);
 
+    updateLayers();
     return () => {
       model?.sharedModel.layersChanged.disconnect(updateLayers);
       model?.sharedModel.layerTreeChanged.disconnect(updateLayers);

python/jupytergis/jupytergis/__init__.py

@@ -1,3 +1,3 @@
 __version__ = "0.4.4"
 
-from jupytergis_lab import GISDocument  # noqa
+from jupytergis_lab import GISDocument, explore  # noqa

python/jupytergis_lab/jupytergis_lab/__init__.py

@@ -9,6 +9,7 @@
     __version__ = "dev"
 
 from .notebook import GISDocument  # noqa
+from .explore import explore
 
 
 def _jupyter_labextension_paths():

python/jupytergis_lab/jupytergis_lab/explore.py

@@ -0,0 +1,75 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, Optional
+
+from jupytergis_lab import GISDocument
+
+
+@dataclass
+class Basemap:
+    name: str
+    url: str
+
+
+BasemapChoice = Literal["light", "dark", "topo"]
+_basemaps: dict[BasemapChoice, list[Basemap]] = {
+    "light": [
+        Basemap(
+            name="ArcGIS dark basemap",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+        Basemap(
+            name="ArcGIS dark basemap reference",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+    ],
+    "dark": [
+        Basemap(
+            name="ArcGIS light basemap",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Base/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+        Basemap(
+            name="ArcGIS light basemap reference",
+            url="https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Reference/MapServer/tile/{z}/{y}/{x}.pbf",
+        ),
+    ],
+    "topo": [
+        Basemap(
+            name="USGS topographic basemap",
+            url="https://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}",
+        ),
+    ],
+}
+
+
+def explore(
+    data: str | Path | Any,
+    *,
+    layer_name: Optional[str] = "Exploration layer",
+    basemap: BasemapChoice = "topo",
+) -> GISDocument:
+    """Run a JupyterGIS data interaction interface alongside a Notebook.
+
+    :param data: A GeoDataFrame or path to a GeoJSON file.
+
+    :raises FileNotFoundError: Received a file path that doesn't exist.
+    :raises NotImplementedError: Received an input value that isn't supported yet.
+    :raises TypeError: Received an object type that isn't supported.
+    :raises ValueError: Received an input value that isn't supported.
+    """
+    doc = GISDocument()
+
+    for basemap_obj in _basemaps[basemap]:
+        doc.add_raster_layer(basemap_obj.url, name=basemap_obj.name)
+
+    doc.add_layer(data, name=layer_name)
+
+    # TODO: Zoom to layer. Currently not exposed in Python API.
+
+    doc.sidecar(title="JupyterGIS explorer")
+
+    # TODO: should we return `doc`? It enables the exploration environment more usable,
+    # but by default, `explore(...)` would display a widget in the notebook _and_ open a
+    # sidecar for the same widget. The user would need to append a semicolon to disable
+    # that behavior. We can't disable that behavior from within this function to the
+    # best of my knowlwedge.