Pass RAGOT virtual scroll load context through SPRAG

Forward Ragot VirtualScroller's loadCtx argument into SPRAG chunk callbacks so async virtual-scroll chunks can detect stale loads safely.

Document the current SPRAG-to-Ragot virtual-scroll callback mapping, including measureChunk/buildPlaceholder/onRecycle/onChunkEvicted and horizontal measurement behavior. Add a regression test covering horizontal virtual-scroll codegen with async chunk callbacks and optional Ragot callback hooks.

Author: BleedingXiko

docs/app/content/docs/ragot/decorators.md

@@ -120,7 +120,20 @@ The decorated component must define:
 - `chunk(self, i)` — returns the DOM element for chunk `i`
 - `total(self)` — returns the total item count
 
-Optional methods: `measure`, `placeholder`, `recycle` (required if `pool_size > 0`), `evicted`.
+`chunk` may also accept Ragot's load context as a second argument:
+`chunk(self, i, load_ctx)`. This is useful for async chunks; call
+`load_ctx.is_current()` before committing delayed work.
+
+Optional methods map directly to Ragot `VirtualScroller` callbacks:
+
+| SPRAG method | Ragot option | Use |
+|---|---|---|
+| `measure(self, el, i)` | `measureChunk(el, i)` | Return the rendered chunk size in pixels |
+| `placeholder(self, i, px)` | `buildPlaceholder(i, px)` | Return the placeholder element for an evicted chunk |
+| `recycle(self, el, i)` | `onRecycle(el, i)` | Fully patch a pooled chunk element for its new index |
+| `evicted(self, i)` | `onChunkEvicted(i)` | React after a chunk leaves the active window |
+
+Ragot's default measurement uses the chunk element's height. For horizontal virtual scrolling, define `measure(self, el, i)` and return the chunk width, for example `el.offset_width`.
 
 The scroller handle is available at `self.virtual_scroll` in Python (emitted as `this.virtualScroll` in JS).
 

sprag/__init__.py

@@ -1,6 +1,6 @@
 """Public SPRAG framework surface."""
 
-__version__ = "0.1.13"
+__version__ = "0.1.14"
 
 from .runtime import dom
 from .runtime.app import App

sprag/dev/codegen/components.py

@@ -779,7 +779,7 @@ def _emit_virtual_scroll_setup(cfg: dict, component_class) -> list[str]:
         f"initialChunks: {cfg['initial_chunks']}",
         f"rootMargin: {json.dumps(cfg['root_margin'])}",
         f"axis: {json.dumps(cfg['axis'])}",
-        "renderChunk: (i) => this.chunk(i)",
+        "renderChunk: (i, loadCtx) => this.chunk(i, loadCtx)",
         "totalItems: () => this.total()",
     ]
     if cfg["root"]:

sprag/runtime/browser.py

@@ -114,11 +114,17 @@ def virtual_scroll(
 
     The component must define:
 
-    - ``chunk(self, i)`` — returns the DOM element for chunk ``i``
+    - ``chunk(self, i)`` — returns the DOM element for chunk ``i``. It may
+      also accept Ragot's load context as ``chunk(self, i, load_ctx)`` for
+      async stale-load checks.
     - ``total(self)`` — returns the total item count
 
-    Optional methods: ``measure``, ``placeholder``, ``recycle`` (REQUIRED if
-    ``pool_size > 0``), ``evicted``.
+    Optional methods map to Ragot callbacks: ``measure`` ->
+    ``measureChunk``, ``placeholder`` -> ``buildPlaceholder``, ``recycle`` ->
+    ``onRecycle`` (REQUIRED if ``pool_size > 0``), and ``evicted`` ->
+    ``onChunkEvicted``. Ragot's default measurement is height-based; for
+    horizontal scrollers, define ``measure(self, el, i)`` and return the
+    chunk width.
 
     Decorated components get a public scroller handle at
     ``self.virtual_scroll`` in Python authoring code (emitted as

tests/test_codegen_diagnostics.py

@@ -2,7 +2,7 @@
 import json
 import inspect
 
-from sprag import Component, Module, browser, imports, ui
+from sprag import Component, Module, browser, imports, ui, virtual_scroll
 from sprag.dev.codegen.components import compile_component_artifact, compile_component_class
 from sprag.dev.codegen.modules import compile_module_artifact, compile_module_class
 from sprag.dev.codegen.mappings import JSCodegenError
@@ -99,6 +99,29 @@ def render(self, props=None):
         )
 
 
+@virtual_scroll(chunk=20, axis="horizontal", root=".rail", container_class="rail-inner")
+class VirtualScrollCallbacksComponent(Component):
+    def render(self, props=None):
+        return ui.div(class_="rail")
+
+    def total(self):
+        return 1000
+
+    async def chunk(self, i, load_ctx):
+        if load_ctx and not load_ctx.is_current():
+            return None
+        return ui.div("chunk " + str(i), class_="chunk")
+
+    def measure(self, el, i):
+        return el.offset_width
+
+    def placeholder(self, i, px):
+        return ui.div(class_="placeholder")
+
+    def evicted(self, i):
+        return i
+
+
 class InvalidComponentSubscription(Component):
     def render(self, props=None):
         return ui.button("Subscribe")
@@ -197,6 +220,17 @@ def test_compile_component_supports_set_metadata_helper(self):
         self.assertIn("window.__SPRAG_SET_METADATA__", compiled)
         self.assertIn('this.setMetadata({ "og:title": "Updated OG title" });', compiled)
 
+    def test_compile_component_supports_virtual_scroll_callbacks(self):
+        compiled = compile_component_class(VirtualScrollCallbacksComponent)
+        self.assertIn("VirtualScroller", compiled)
+        self.assertIn('axis: "horizontal"', compiled)
+        self.assertIn("renderChunk: (i, loadCtx) => this.chunk(i, loadCtx)", compiled)
+        self.assertIn("measureChunk: (el, i) => this.measure(el, i)", compiled)
+        self.assertIn("buildPlaceholder: (i, px) => this.placeholder(i, px)", compiled)
+        self.assertIn("onChunkEvicted: (i) => this.evicted(i)", compiled)
+        self.assertIn("async chunk(i, load_ctx)", compiled)
+        self.assertIn("load_ctx.isCurrent()", compiled)
+
     def test_compile_module_artifact_emits_source_map_metadata(self):
         artifact = compile_module_artifact(SupportedModule)
         payload = json.loads(artifact.source_map)