refactor: migrate from XState to Zustand for state management

DEVELOP.md

@@ -67,8 +67,6 @@ All models on the TypeScript side are combined into a single entry point, which
 
 Anywidget and its dependency ipywidgets handles the serialization from Python into JS, automatically keeping each side in sync.
 
-State management is implemented using [XState](https://stately.ai/docs/xstate). The app is instrumented with [Stately Inspector](https://stately.ai/docs/inspector), and the use of the [VS Code extension](https://stately.ai/docs/xstate-vscode-extension) is highly recommended.
-
 ## Publishing
 
 Push a new tag to the main branch of the format `v*`. A new version will be published to PyPI automatically.

package.json

@@ -11,7 +11,6 @@
     "@geoarrow/deck.gl-layers": "^0.4.0-beta.6",
     "@geoarrow/geoarrow-js": "^0.3.2",
     "@nextui-org/react": "^2.4.8",
-    "@xstate/react": "^6.0.0",
     "apache-arrow": "^21.1.0",
     "esbuild-sass-plugin": "^3.3.1",
     "framer-motion": "^12.23.19",
@@ -25,7 +24,7 @@
     "react-map-gl": "^8.1.0",
     "threads": "1.7.0",
     "uuid": "^13.0.0",
-    "xstate": "^5.22.0"
+    "zustand": "^5.0.2"
   },
   "type": "module",
   "devDependencies": {

src/index.tsx

@@ -1,13 +1,15 @@
 import { createRender, useModel, useModelState } from "@anywidget/react";
 import type { Initialize, Render } from "@anywidget/types";
 import { MapViewState, PickingInfo } from "@deck.gl/core";
+import { PolygonLayer, PolygonLayerProps } from "@deck.gl/layers";
 import { DeckGLRef } from "@deck.gl/react";
+import { GeoArrowPickingInfo } from "@geoarrow/deck.gl-layers";
 import type { IWidgetManager } from "@jupyter-widgets/base";
 import { NextUIProvider } from "@nextui-org/react";
 import debounce from "lodash.debounce";
 import throttle from "lodash.throttle";
 import * as React from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { v4 as uuidv4 } from "uuid";
 
 import { flyTo } from "./actions/fly-to.js";
@@ -27,38 +29,83 @@ import {
   OverlayRendererProps,
 } from "./renderers/types.js";
 import SidePanel from "./sidepanel/index";
-import { useViewStateDebounced } from "./state";
+import { useStore, useViewStateDebounced } from "./state";
 import Toolbar from "./toolbar.js";
 import { getTooltip } from "./tooltip/index.js";
 import { Message } from "./types.js";
 import { isDefined, isGlobeView, sanitizeViewState } from "./util.js";
-import { MachineContext, MachineProvider } from "./xstate";
-import * as selectors from "./xstate/selectors";
 
 import "maplibre-gl/dist/maplibre-gl.css";
 import "./globals.css";
 
 await initParquetWasm();
 
 function App() {
-  const actorRef = MachineContext.useActorRef();
-  const isDrawingBBoxSelection = MachineContext.useSelector(
-    selectors.isDrawingBBoxSelection,
-  );
-  const isOnMapHoverEventEnabled = MachineContext.useSelector(
-    selectors.isOnMapHoverEventEnabled,
-  );
+  // =========================================================================
+  // Client-Side State (Zustand)
+  // UI-only state that never syncs with Python
+  // See: src/state/store.ts
+  // =========================================================================
 
-  const highlightedFeature = MachineContext.useSelector(
-    (s) => s.context.highlightedFeature,
+  // Feature highlighting
+  const highlightedFeature = useStore((state) => state.highlightedFeature);
+  const setHighlightedFeature = useStore(
+    (state) => state.setHighlightedFeature,
   );
 
-  const bboxSelectPolygonLayer = MachineContext.useSelector(
-    selectors.getBboxSelectPolygonLayer,
-  );
-  const bboxSelectBounds = MachineContext.useSelector(
-    selectors.getBboxSelectBounds,
-  );
+  // Bounding box selection
+  const isDrawingBbox = useStore((state) => state.isDrawingBbox);
+  const bboxSelectStart = useStore((state) => state.bboxSelectStart);
+  const bboxSelectEnd = useStore((state) => state.bboxSelectEnd);
+  const setBboxStart = useStore((state) => state.setBboxStart);
+  const setBboxEnd = useStore((state) => state.setBboxEnd);
+  const setBboxHover = useStore((state) => state.setBboxHover);
+
+  const isOnMapHoverEventEnabled =
+    isDrawingBbox && bboxSelectStart !== undefined;
+
+  const bboxSelectBounds = useMemo(() => {
+    if (bboxSelectStart && bboxSelectEnd) {
+      const [x0, y0] = bboxSelectStart;
+      const [x1, y1] = bboxSelectEnd;
+      return [
+        Math.min(x0, x1),
+        Math.min(y0, y1),
+        Math.max(x0, x1),
+        Math.max(y0, y1),
+      ];
+    }
+    return null;
+  }, [bboxSelectStart, bboxSelectEnd]);
+
+  const bboxSelectPolygonLayer = useMemo(() => {
+    if (bboxSelectStart && bboxSelectEnd) {
+      const bboxProps: PolygonLayerProps = {
+        id: "bbox-select-polygon",
+        data: [
+          [
+            [bboxSelectStart[0], bboxSelectStart[1]],
+            [bboxSelectEnd[0], bboxSelectStart[1]],
+            [bboxSelectEnd[0], bboxSelectEnd[1]],
+            [bboxSelectStart[0], bboxSelectEnd[1]],
+          ],
+        ],
+        getPolygon: (d) => d,
+        getFillColor: [0, 0, 0, 50],
+        getLineColor: [0, 0, 0, 130],
+        stroked: true,
+        getLineWidth: 2,
+        lineWidthUnits: "pixels",
+      };
+      if (isDrawingBbox) {
+        bboxProps.getFillColor = [255, 255, 0, 120];
+        bboxProps.getLineColor = [211, 211, 38, 200];
+        bboxProps.getLineWidth = 2;
+      }
+      return new PolygonLayer(bboxProps);
+    }
+    return null;
+  }, [bboxSelectStart, bboxSelectEnd, isDrawingBbox]);
 
   const [justClicked, setJustClicked] = useState<boolean>(false);
 
@@ -73,15 +120,24 @@ function App() {
 
   const model = useModel();
 
+  // ============================================================================
+  // Python-Synced State (Backbone models)
+  // ============================================================================
+  // State that bidirectionally syncs with Python via Jupyter widgets
+  // See: src/state/python-sync.ts
+
+  // Map configuration
   const [basemapModelId] = useModelState<string | null>("basemap");
   const [mapHeight] = useModelState<string>("height");
-  const [showTooltip] = useModelState<boolean>("show_tooltip");
-  const [showSidePanel] = useModelState<boolean>("show_side_panel");
-  const [pickingRadius] = useModelState<number>("picking_radius");
   const [useDevicePixels] = useModelState<number | boolean>(
     "use_device_pixels",
   );
   const [parameters] = useModelState<object>("parameters");
+
+  // UI settings
+  const [showTooltip] = useModelState<boolean>("show_tooltip");
+  const [showSidePanel] = useModelState<boolean>("show_side_panel");
+  const [pickingRadius] = useModelState<number>("picking_radius");
   const [customAttribution] = useModelState<string>("custom_attribution");
   const [mapId] = useState(uuidv4());
   const [childLayerIds] = useModelState<string[]>("layers");
@@ -138,7 +194,7 @@ function App() {
     model.widget_manager as IWidgetManager,
     updateStateCallback,
     bboxSelectBounds,
-    isDrawingBBoxSelection,
+    isDrawingBbox,
     setSelectedBounds,
   );
 
@@ -148,36 +204,52 @@ function App() {
     updateStateCallback,
   );
 
-  const onMapClickHandler = useCallback((info: PickingInfo) => {
-    // We added this flag to prevent the hover event from firing after a
-    // click event.
-    if (typeof info.coordinate !== "undefined") {
-      if (model.get("_has_click_handlers")) {
-        model.send({ kind: "on-click", coordinate: info.coordinate });
+  const onMapClickHandler = useCallback(
+    (info: PickingInfo) => {
+      // We added this flag to prevent the hover event from firing after a
+      // click event.
+      if (typeof info.coordinate !== "undefined") {
+        if (model.get("_has_click_handlers")) {
+          model.send({ kind: "on-click", coordinate: info.coordinate });
+        }
+      }
+      setJustClicked(true);
+
+      const clickedObject = info.object;
+      if (typeof clickedObject !== "undefined") {
+        setHighlightedFeature(info as GeoArrowPickingInfo);
+      } else {
+        setHighlightedFeature(undefined);
       }
-    }
-    setJustClicked(true);
-    actorRef.send({
-      type: "Map click event",
-      data: info,
-    });
-    setTimeout(() => {
-      setJustClicked(false);
-    }, 100);
-  }, []);
+
+      if (isDrawingBbox && info.coordinate) {
+        if (bboxSelectStart === undefined) {
+          setBboxStart(info.coordinate);
+        } else {
+          setBboxEnd(info.coordinate);
+        }
+      }
+
+      setTimeout(() => {
+        setJustClicked(false);
+      }, 100);
+    },
+    [
+      setHighlightedFeature,
+      isDrawingBbox,
+      bboxSelectStart,
+      setBboxStart,
+      setBboxEnd,
+    ],
+  );
 
   const onMapHoverHandler = useCallback(
-    throttle(
-      (info: PickingInfo) =>
-        isOnMapHoverEventEnabled &&
-        !justClicked &&
-        actorRef.send({
-          type: "Map hover event",
-          data: info,
-        }),
-      100,
-    ),
-    [isOnMapHoverEventEnabled, justClicked],
+    throttle((info: PickingInfo) => {
+      if (isOnMapHoverEventEnabled && !justClicked && info.coordinate) {
+        setBboxHover(info.coordinate);
+      }
+    }, 100),
+    [isOnMapHoverEventEnabled, justClicked, setBboxHover],
   );
 
   const mapRenderProps: MapRendererProps = {
@@ -189,7 +261,7 @@ function App() {
       ? layers.concat(bboxSelectPolygonLayer)
       : layers,
     getTooltip: (showTooltip && getTooltip) || undefined,
-    getCursor: () => (isDrawingBBoxSelection ? "crosshair" : "grab"),
+    getCursor: () => (isDrawingBbox ? "crosshair" : "grab"),
     pickingRadius: pickingRadius,
     onClick: onMapClickHandler,
     onHover: onMapHoverHandler,
@@ -243,7 +315,7 @@ function App() {
         {showSidePanel && highlightedFeature && (
           <SidePanel
             info={highlightedFeature}
-            onClose={() => actorRef.send({ type: "Close side panel" })}
+            onClose={() => setHighlightedFeature(undefined)}
           />
         )}
         <div className="bg-transparent h-full w-full relative">
@@ -261,9 +333,7 @@ function App() {
 
 const WrappedApp = () => (
   <NextUIProvider>
-    <MachineProvider>
-      <App />
-    </MachineProvider>
+    <App />
   </NextUIProvider>
 );