Add an API to add local data to tracks

docs/getting_started.rst

@@ -502,6 +502,63 @@ light-weight HiGlass server in a *background thread*. This temporary
 server is only started if a local tileset is used and will only persist
 for the duration of the Python session.
 
+Local Data with Plugin Tracks
+"""""""""""""""""""""""""""""
+
+For regular or plugin tracks that support local data, you can use the ``local_data()`` method
+to provide tileset info and tile data directly without needing a server. This is
+particularly useful for small datasets or custom visualizations.
+
+.. code-block:: python
+
+    from typing import Literal, ClassVar
+    import higlass as hg
+
+    class LabelledPointsTrack(hg.PluginTrack):
+        type: Literal["labelled-points-track"] = "labelled-points-track"
+        plugin_url: ClassVar[str] = (
+            "https://unpkg.com/higlass-labelled-points-track@0.5.1/"
+            "dist/higlass-labelled-points-track.min.js"
+        )
+
+    # Create track with local data
+    track = LabelledPointsTrack().local_data(
+        tsinfo={
+            "zoom_step": 1,
+            "tile_size": 256,
+            "max_zoom": 0,
+            "min_pos": [-180, -180],
+            "max_pos": [180, 180],
+            "max_data_length": 134217728,
+            "max_width": 360
+        },
+        data=[
+            {
+                "x": -122.29340351667594,
+                "y": -40.90076029033937,
+                "size": 10,
+                "data": "Fraxinus o. 'Raywood'",
+                "uid": "Eq71PfMlR0aqHd2zSlDclA"
+            },
+            {
+                "x": -122.18808936055962,
+                "y": -40.805069480744535,
+                "size": 20,
+                "data": "Acer rubrum",
+                "uid": "DYKKOHNuRBmEPdTip0pyDw"
+            },
+            {
+                "x": -122.23773953309676,
+                "y": -40.885281196424444,
+                "size": 1,
+                "data": "Other",
+                "uid": "b04PPSR6Ti28MJPpzXpAuA"
+            },
+        ]
+    )
+
+    hg.view(track)
+
 Cooler Files
 """"""""""""
 

src/higlass/__init__.py

@@ -31,6 +31,7 @@
 )
 from higlass.server import HiGlassServer
 from higlass.tilesets import (
+    LocalDataTileset,
     Tileset,
     bed2ddb,
     beddb,

src/higlass/tilesets.py

@@ -11,6 +11,7 @@
 from higlass._utils import TrackType, datatype_default_track
 
 __all__ = [
+    "LocalDataTileset",
     "Tileset",
     "bed2ddb",
     "bigwig",
@@ -71,6 +72,59 @@ def remote(
     return RemoteTileset(uid, server, name)
 
 
+@dataclass
+class LocalDataTileset:
+    """A tileset that serves data locally without a server.
+
+    Parameters
+    ----------
+    tsinfo : dict
+        Tileset info dict (must include ``min_pos`` and ``max_pos``).
+    data : list
+        Tile data for the tileset.
+    """
+
+    tsinfo: dict
+    data: list
+
+    def __post_init__(self):
+        min_pos = self.tsinfo.get("min_pos", [])
+        max_pos = self.tsinfo.get("max_pos", [])
+
+        if len(min_pos) != len(max_pos):
+            raise ValueError("min_pos and max_pos must have equal lengths")
+
+        if len(min_pos) == 2:
+            self._tile_key = "x.0.0.0"
+        elif len(min_pos) == 1:
+            self._tile_key = "x.0.0"
+        else:
+            raise ValueError("min_pos must be a one or two element array")
+
+    def track(self, type_: TrackType, **kwargs) -> higlass.api.Track:
+        """Create a HiGlass track with local data embedded.
+
+        Parameters
+        ----------
+        type_ : TrackType
+            The track type to create.
+        **kwargs : dict
+            Additional top-level track properties.
+
+        Returns
+        -------
+        higlass.api.Track
+            A track with the ``data`` section populated for local-tiles.
+        """
+        trk = higlass.api.track(type_=type_, **kwargs)
+        trk.data = {
+            "type": "local-tiles",
+            "tilesetInfo": {"x": self.tsinfo},
+            "tiles": {self._tile_key: self.data},
+        }
+        return trk
+
+
 class Tileset(abc.ABC):
     """Base class for defining custom tilesets in `higlass`.
 

src/higlass/widget.js

@@ -1,4 +1,4 @@
-import * as hglib from "https://esm.sh/higlass@1.13?deps=react@17,react-dom@17,pixi.js@6";
+import * as hglib from "https://esm.sh/higlass@2.2.1?deps=react@17,react-dom@17,pixi.js@6";
 import { v4 } from "https://esm.sh/@lukeed/uuid@2.0.1";
 
 /** @import { AnyModel } from "@anywidget/types" */
@@ -275,7 +275,10 @@ function addEventListenersTo(el) {
   });
 
   // prevent wheel events from scrolling the page while allowing HiGlass zoom
-  el.addEventListener("wheel", (event) => event.stopPropagation(), {
+  el.addEventListener("wheel", (event) => {
+    event.stopPropagation();
+    event.preventDefault();
+  }, {
     signal: controller.signal,
     passive: false,
   });
@@ -309,22 +312,30 @@ export default {
     model.on("msg:custom", (msg) => {
       msg = JSON.parse(msg);
       let [fn, ...args] = msg;
-      api[fn](...args);
+      /** @type {any} */ (api)[fn](...args);
     });
 
     if (viewconf.views.length === 1) {
-      api.on("location", (/** @type {GenomicLocation} */ loc) => {
-        model.set("location", locationToCoordinates(loc));
-        model.save_changes();
-      }, viewconf.views[0].uid);
+      /** @type {any} */ (api).on(
+        "location",
+        (/** @type {GenomicLocation} */ loc) => {
+          model.set("location", locationToCoordinates(loc));
+          model.save_changes();
+        },
+        viewconf.views[0].uid,
+      );
     } else {
       viewconf.views.forEach((view, idx) => {
-        api.on("location", (/** @type{GenomicLocation} */ loc) => {
-          let location = model.get("location").slice();
-          location[idx] = locationToCoordinates(loc);
-          model.set("location", location);
-          model.save_changes();
-        }, view.uid);
+        /** @type {any} */ (api).on(
+          "location",
+          (/** @type{GenomicLocation} */ loc) => {
+            let location = model.get("location").slice();
+            location[idx] = locationToCoordinates(loc);
+            model.set("location", location);
+            model.save_changes();
+          },
+          view.uid,
+        );
       });
     }
 

test/test_api.py

@@ -209,6 +209,28 @@ def test_options_mixin():
     assert track.options and track.options["foo"] == "bar"
 
 
+def test_local_data_tileset():
+    tsinfo = {"min_pos": [0, 0], "max_pos": [100, 100]}
+    data = [{"x": 1, "y": 2}]
+
+    tileset = hg.LocalDataTileset(tsinfo, data)
+    other = tileset.track("heatmap")
+    assert other.data.type == "local-tiles"
+    assert other.data.tilesetInfo["x"] == tsinfo
+    assert other.data.tiles["x.0.0.0"] == data
+
+    tsinfo_1d = {"min_pos": [0], "max_pos": [100]}
+    tileset_1d = hg.LocalDataTileset(tsinfo_1d, data)
+    other_1d = tileset_1d.track("heatmap")
+    assert other_1d.data.tiles["x.0.0"] == data
+
+    with pytest.raises(ValueError, match="min_pos and max_pos must have equal lengths"):
+        hg.LocalDataTileset({"min_pos": [0], "max_pos": [0, 0]}, data)
+
+    with pytest.raises(ValueError, match="min_pos must be a one or two element array"):
+        hg.LocalDataTileset({"min_pos": [0, 0, 0], "max_pos": [0, 0, 0]}, data)
+
+
 def test_plugin_track():
     """Test that plugin track attributes are maintained after a copy."""
     some_url = "https://some_url"