reflex-xy 0.0.1__tar.gz

reflex_xy-0.0.1/.gitignore

@@ -0,0 +1,17 @@
+target/
+.venv/
+smoke/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+node_modules/
+*.egg-info/
+.web/
+**/assets/xy/*.xyf
+# Generated render-client bundles (§33): built by `node js/build.mjs` and
+# force-included into the wheel/sdist by hatch_build.py, never committed.
+python/xy/static/index.js
+python/xy/static/standalone.js
+**/assets/external/

reflex_xy-0.0.1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to **reflex-xy** (the Reflex adapter for xy) are
+documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.0.1] — 2026-07-24
+
+### Added
+- First packaged release line of the adapter: `reflex_xy.chart()` components,
+  `@reflex_xy.figure` state vars with rebuild-from-state recovery,
+  `XYPlugin`/`setup()` app wiring, the `/_xy` socket.io data-plane namespace
+  (binary columns on the app's own websocket), semantic hover/click/select/
+  view events, fixed-data tiers (direct `Chart` + `inline()` tokens), and
+  streaming `append`.
+- The distribution version is derived from `reflex-xy-vX.Y.Z` git tags
+  (uv-dynamic-versioning with `pattern-prefix = "reflex-xy-"`) instead of a
+  number in `pyproject.toml`; canonical pre-release tags (`aN`/`bN`/`rcN`)
+  publish too, and builds between tags are versioned `<next>.devN+<commit>`,
+  which PyPI rejects by design. The adapter and core
+  tag namespaces are mutually invisible by pattern anchoring: this derivation
+  never sees bare `v*` tags, and the core's never sees `reflex-xy-*` ones.
+  Releases publish via the dedicated
+  `.github/workflows/release-reflex-xy.yml` workflow — deliberately separate
+  from the core's cross-compile pipeline, since the adapter is one pure wheel
+  plus one sdist with no build matrix — verified by
+  `scripts/verify_reflex_xy_dist.py`, gated on this changelog, published with
+  PyPI trusted publishing, and validated alongside the other workflows by
+  `make check-ci`. `reflex_xy.__version__` now reports the installed
+  distribution's version (an uninstalled tree reports `0.0.0`).

reflex_xy-0.0.1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: reflex-xy
+Version: 0.0.1
+Summary: Reflex integration for xy: WebGL charts over the app's own websocket
+Project-URL: Repository, https://github.com/reflex-dev/xy
+Project-URL: Changelog, https://github.com/reflex-dev/xy/blob/main/python/reflex-xy/CHANGELOG.md
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: reflex>=0.9.6
+Requires-Dist: xy
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9; extra == 'dev'
+Requires-Dist: uvicorn>=0.23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# reflex-xy
+
+[xy](https://github.com/reflex-dev/xy) figures as first-class
+[Reflex](https://reflex.dev) components: WebGL rendering, million-point
+interactivity, and streaming updates — with chart data riding the app's
+**existing websocket**, not a sidecar API.
+
+## How it works
+
+- **Control plane (Reflex-native).** The only chart state is a token string,
+  minted by a `@reflex_xy.figure` computed var. Semantic events —
+  `on_point_hover(event)`, `on_point_click(event)`, `on_select_end(event)`, and
+  `on_view_change(event)` — arrive as ordinary Reflex
+  event handlers with small JSON payloads.
+- **Data plane (xy-native).** A second socket.io namespace (`/_xy`)
+  multiplexed onto the app's own engine.io websocket ships the spec as JSON
+  and every data column as a binary frame (no JSON numbers, no base64, no
+  extra endpoints to reverse-proxy). Pan/zoom/hover round-trips go straight
+  to the figure kernel and never touch Reflex state.
+- **No figure server.** Figures live in a per-process registry as
+  *rebuildable caches*: the token encodes `(client, state, var)`, so any
+  backend worker can re-run the builder against Reflex state (already
+  distributed via redis in prod) when a reconnect lands on it.
+
+## Usage
+
+```python
+# rxconfig.py
+import reflex as rx
+import reflex_xy
+
+config = rx.Config(app_name="dash", plugins=[reflex_xy.XYPlugin()])
+```
+
+```python
+# dash/dash.py
+import numpy as np
+import reflex as rx
+import xy
+import reflex_xy
+
+
+class Dash(rx.State):
+    points: int = 200_000
+    hovered: dict = {}
+
+    @reflex_xy.figure
+    def chart(self) -> xy.Chart:
+        rng = np.random.default_rng(7)
+        xs = rng.normal(size=self.points)
+        ys = xs * 0.6 + rng.normal(scale=0.6, size=self.points)
+        return xy.scatter_chart(xy.scatter(xs, ys), width="100%", height=460)
+
+    @rx.event
+    def on_hover(self, row: dict):
+        self.hovered = row
+
+
+def index() -> rx.Component:
+    return rx.vstack(
+        reflex_xy.chart(Dash.chart, on_point_hover=Dash.on_hover, height="460px"),
+        rx.text(Dash.hovered.to_string()),
+        width="100%",
+    )
+
+
+app = rx.App()
+```
+
+Change `points` in an event handler and the chart re-publishes itself to
+every subscriber — the token never changes, so nothing re-renders except
+pixels.
+
+Builders can be `async def` (they become reflex `AsyncComputedVar`s, same
+rule as `rx.var`) — await a database, HTTP endpoint, or dataframe store:
+
+```python
+    @reflex_xy.figure
+    async def remote(self) -> xy.Chart:
+        rows = await fetch_rows(self.query)
+        return xy.line_chart(xy.line(rows.t, rows.value))
+```
+
+Streaming: `reflex_xy.append(token, x=[...], y=[...])` from any handler or
+background task pushes an incremental update over the same socket.
+
+## Events and cross-filtering
+
+Live token-backed charts emit versioned, bounded dictionaries with a stable
+token and canonical row IDs. Selection rows can update ordinary State, which
+causes dependent `@reflex_xy.figure` builders to republish without changing
+their tokens or remounting the chart:
+
+```python
+class Dash(rx.State):
+    selected_groups: list[str] = []
+
+    @rx.event
+    def filter_groups(self, event: dict):
+        selection = event["selection"]
+        self.selected_groups = [] if selection["cleared"] else sorted({
+            row["color_category"] for row in selection["rows"]
+        })
+
+def index():
+    return rx.grid(
+        reflex_xy.chart(Dash.groups, on_select_end=Dash.filter_groups),
+        reflex_xy.chart(Dash.filtered_detail),
+    )
+```
+
+## Fixed-data charts
+
+For a chart that doesn't depend on state, skip the state var entirely —
+pass the Chart straight in:
+
+```python
+def index() -> rx.Component:
+    return reflex_xy.chart(
+        xy.line_chart(xy.line(t, np.sin(t)), width="100%", height=220),
+        height="220px",
+    )
+```
+
+That compiles the figure to a content-addressed binary asset at page build
+and renders it with **zero backend involvement** — client-side hover,
+pan/zoom, and density re-bin, same as `Figure.to_html()` exports; works
+under `reflex export`. When a fixed chart still needs kernel round-trips
+(deep drilldown into millions of points), register it once at module scope
+instead:
+
+```python
+cloud = reflex_xy.inline(xy.scatter_chart(xy.scatter(x, y)))  # module scope
+
+def index() -> rx.Component:
+    return reflex_xy.chart(cloud, height="460px")
+```
+
+`inline()` tokens are content-addressed, so every backend worker derives
+the same one — no state, no coordination. The escalation path is:
+direct Chart (static) → `inline()` (fixed data, live kernel) →
+`@reflex_xy.figure` (per-session, state-driven).

reflex_xy-0.0.1/README.md

@@ -0,0 +1,142 @@
+# reflex-xy
+
+[xy](https://github.com/reflex-dev/xy) figures as first-class
+[Reflex](https://reflex.dev) components: WebGL rendering, million-point
+interactivity, and streaming updates — with chart data riding the app's
+**existing websocket**, not a sidecar API.
+
+## How it works
+
+- **Control plane (Reflex-native).** The only chart state is a token string,
+  minted by a `@reflex_xy.figure` computed var. Semantic events —
+  `on_point_hover(event)`, `on_point_click(event)`, `on_select_end(event)`, and
+  `on_view_change(event)` — arrive as ordinary Reflex
+  event handlers with small JSON payloads.
+- **Data plane (xy-native).** A second socket.io namespace (`/_xy`)
+  multiplexed onto the app's own engine.io websocket ships the spec as JSON
+  and every data column as a binary frame (no JSON numbers, no base64, no
+  extra endpoints to reverse-proxy). Pan/zoom/hover round-trips go straight
+  to the figure kernel and never touch Reflex state.
+- **No figure server.** Figures live in a per-process registry as
+  *rebuildable caches*: the token encodes `(client, state, var)`, so any
+  backend worker can re-run the builder against Reflex state (already
+  distributed via redis in prod) when a reconnect lands on it.
+
+## Usage
+
+```python
+# rxconfig.py
+import reflex as rx
+import reflex_xy
+
+config = rx.Config(app_name="dash", plugins=[reflex_xy.XYPlugin()])
+```
+
+```python
+# dash/dash.py
+import numpy as np
+import reflex as rx
+import xy
+import reflex_xy
+
+
+class Dash(rx.State):
+    points: int = 200_000
+    hovered: dict = {}
+
+    @reflex_xy.figure
+    def chart(self) -> xy.Chart:
+        rng = np.random.default_rng(7)
+        xs = rng.normal(size=self.points)
+        ys = xs * 0.6 + rng.normal(scale=0.6, size=self.points)
+        return xy.scatter_chart(xy.scatter(xs, ys), width="100%", height=460)
+
+    @rx.event
+    def on_hover(self, row: dict):
+        self.hovered = row
+
+
+def index() -> rx.Component:
+    return rx.vstack(
+        reflex_xy.chart(Dash.chart, on_point_hover=Dash.on_hover, height="460px"),
+        rx.text(Dash.hovered.to_string()),
+        width="100%",
+    )
+
+
+app = rx.App()
+```
+
+Change `points` in an event handler and the chart re-publishes itself to
+every subscriber — the token never changes, so nothing re-renders except
+pixels.
+
+Builders can be `async def` (they become reflex `AsyncComputedVar`s, same
+rule as `rx.var`) — await a database, HTTP endpoint, or dataframe store:
+
+```python
+    @reflex_xy.figure
+    async def remote(self) -> xy.Chart:
+        rows = await fetch_rows(self.query)
+        return xy.line_chart(xy.line(rows.t, rows.value))
+```
+
+Streaming: `reflex_xy.append(token, x=[...], y=[...])` from any handler or
+background task pushes an incremental update over the same socket.
+
+## Events and cross-filtering
+
+Live token-backed charts emit versioned, bounded dictionaries with a stable
+token and canonical row IDs. Selection rows can update ordinary State, which
+causes dependent `@reflex_xy.figure` builders to republish without changing
+their tokens or remounting the chart:
+
+```python
+class Dash(rx.State):
+    selected_groups: list[str] = []
+
+    @rx.event
+    def filter_groups(self, event: dict):
+        selection = event["selection"]
+        self.selected_groups = [] if selection["cleared"] else sorted({
+            row["color_category"] for row in selection["rows"]
+        })
+
+def index():
+    return rx.grid(
+        reflex_xy.chart(Dash.groups, on_select_end=Dash.filter_groups),
+        reflex_xy.chart(Dash.filtered_detail),
+    )
+```
+
+## Fixed-data charts
+
+For a chart that doesn't depend on state, skip the state var entirely —
+pass the Chart straight in:
+
+```python
+def index() -> rx.Component:
+    return reflex_xy.chart(
+        xy.line_chart(xy.line(t, np.sin(t)), width="100%", height=220),
+        height="220px",
+    )
+```
+
+That compiles the figure to a content-addressed binary asset at page build
+and renders it with **zero backend involvement** — client-side hover,
+pan/zoom, and density re-bin, same as `Figure.to_html()` exports; works
+under `reflex export`. When a fixed chart still needs kernel round-trips
+(deep drilldown into millions of points), register it once at module scope
+instead:
+
+```python
+cloud = reflex_xy.inline(xy.scatter_chart(xy.scatter(x, y)))  # module scope
+
+def index() -> rx.Component:
+    return reflex_xy.chart(cloud, height="460px")
+```
+
+`inline()` tokens are content-addressed, so every backend worker derives
+the same one — no state, no coordination. The escalation path is:
+direct Chart (static) → `inline()` (fixed data, live kernel) →
+`@reflex_xy.figure` (per-session, state-driven).

reflex_xy-0.0.1/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.11"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reflex-xy"
+dynamic = ["version"]
+description = "Reflex integration for xy: WebGL charts over the app's own websocket"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "xy",
+    # Prototype dependency surface. The adapter needs: Component/Var/EventHandler
+    # (reflex-base), plus App/State/state_manager access, which today live in the
+    # full `reflex` distribution. Revisit when the reflex-base split grows a
+    # public state/app surface (spec/design/reflex-integration.md §4).
+    "reflex>=0.9.6",
+]
+
+[project.optional-dependencies]
+# tests/reflex_adapter drives the data plane over a real websocket:
+# uvicorn serves the socket app, aiohttp backs socketio.AsyncClient.
+dev = [
+    "aiohttp>=3.9",
+    "uvicorn>=0.23",
+]
+
+[project.urls]
+Repository = "https://github.com/reflex-dev/xy"
+Changelog = "https://github.com/reflex-dev/xy/blob/main/python/reflex-xy/CHANGELOG.md"
+
+# Same tag-derived versioning policy as the xy core (see the root
+# pyproject.toml for the full rationale), in a tag namespace of its own:
+# the adapter releases from `reflex-xy-vX.Y.Z` tags, cut by
+# .github/workflows/release-reflex-xy.yml. `pattern-prefix` inserts
+# `reflex-xy-` after the default pattern's `^` anchor, which keeps the two
+# release lines disjoint in both directions — this derivation only sees
+# `reflex-xy-v*` tags, while the core's bare-`v` pattern (and the docs-deploy
+# CalVer tags) can never match them.
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+pattern-prefix = "reflex-xy-"
+# Builds off a tagged commit get the bare version; anything else gets
+# `<next>.devN+<commit>`, unpublishable to PyPI on purpose — only a tag can
+# produce an uploadable version.
+bump = true
+# Only reached by a source tree with neither git metadata nor PKG-INFO; such
+# a build still succeeds, at an obviously unreal version rather than a
+# plausible-but-wrong one (unpacked sdists resolve from their own PKG-INFO).
+fallback-version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["reflex_xy"]
+# reflex_xy/assets/XYChart.jsx ships as ordinary package data; the render
+# client is NOT packaged — it links out of the installed xy wheel at
+# app compile time (see reflex_xy/assets/__init__.py), so it can never
+# drift from the kernel that produces its payloads.

reflex_xy-0.0.1/reflex_xy/__init__.py

@@ -0,0 +1,166 @@
+"""reflex-xy: xy figures as first-class Reflex components.
+
+The integration in one paragraph (full design:
+spec/design/reflex-integration.md in the xy repo): chart data rides
+the app's *existing* websocket as a second socket.io namespace — binary
+columns, no JSON numbers, no extra endpoints to proxy. Figures live in a
+per-process registry keyed by tokens; the tokens live in Reflex state. A
+`@reflex_xy.figure` state method is both the chart definition and the
+recovery recipe: any worker can rebuild the figure from state when a
+reconnect lands somewhere new, so there is no central figure store to
+operate.
+
+Quickstart::
+
+    # rxconfig.py
+    config = rx.Config(app_name="dash", plugins=[reflex_xy.XYPlugin()])
+
+    # dash/dash.py
+    import numpy as np
+    import reflex as rx
+    import xy
+    import reflex_xy
+
+    class Dash(rx.State):
+        points: int = 200_000
+
+        @reflex_xy.figure
+        def chart(self) -> xy.Chart:
+            rng = np.random.default_rng(7)
+            xs = rng.normal(size=self.points)
+            ys = xs * 0.6 + rng.normal(scale=0.6, size=self.points)
+            return xy.scatter_chart(xy.scatter(xs, ys), width="100%", height=460)
+
+    def index() -> rx.Component:
+        return reflex_xy.chart(Dash.chart, height="460px")
+
+    app = rx.App()
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from .app import XYPlugin, append, clear_selection, reset_view, select, set_view, setup
+from .component import chart
+from .events import (
+    CanonicalRowIdGroup,
+    DataBounds,
+    Modifiers,
+    PointClickEvent,
+    PointData,
+    PointHoverEvent,
+    ScreenPoint,
+    SelectEndEvent,
+    SelectionPayload,
+    ViewChangeEvent,
+)
+from .namespace import XY_NAMESPACE, XYNamespace
+from .registry import FigureRegistry, _figure_of, registry
+from .selections import resolve_selection
+from .vars import AsyncFigureVar, FigureVar, figure
+
+__all__ = [
+    "XY_NAMESPACE",
+    "AsyncFigureVar",
+    "CanonicalRowIdGroup",
+    "DataBounds",
+    "FigureRegistry",
+    "FigureVar",
+    "Modifiers",
+    "PointClickEvent",
+    "PointData",
+    "PointHoverEvent",
+    "ScreenPoint",
+    "SelectEndEvent",
+    "SelectionPayload",
+    "ViewChangeEvent",
+    "XYNamespace",
+    "XYPlugin",
+    "append",
+    "chart",
+    "clear_selection",
+    "figure",
+    "inline",
+    "register",
+    "registry",
+    "release",
+    "reset_view",
+    "resolve_selection",
+    "select",
+    "set_view",
+    "setup",
+]
+
+
+def __getattr__(name: str) -> str:
+    """Resolve ``__version__`` lazily from the installed distribution.
+
+    The version is not written down in the source tree — it is derived from
+    the latest ``reflex-xy-vX.Y.Z`` git tag at build time (pyproject's
+    uv-dynamic-versioning config) and baked into the wheel's METADATA, so
+    package metadata is the only place that can answer this at runtime. An
+    uninstalled source tree reports the same unreal ``0.0.0`` the build-time
+    fallback uses.
+    """
+    if name == "__version__":
+        from importlib.metadata import PackageNotFoundError
+        from importlib.metadata import version as _distribution_version
+
+        try:
+            value = _distribution_version("reflex-xy")
+        except PackageNotFoundError:
+            value = "0.0.0"
+        globals()["__version__"] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def register(chart_or_figure: Any) -> str:
+    """Imperatively register a chart; returns an opaque token for state.
+
+    Dev-tier API: the figure lives only in this process and cannot be
+    rebuilt after a worker restart or on another node — prefer
+    `@reflex_xy.figure` for anything long-lived (see the module doc).
+    """
+    return registry.register(_figure_of(chart_or_figure))
+
+
+def inline(chart_or_figure: Any) -> str:
+    """Register a fixed, kernel-backed chart at module scope; returns its token.
+
+    For charts whose data never changes but which still want server-side
+    drilldown/picks on the shared websocket. Call at **module scope** so the
+    registration side effect runs in every backend worker (page bodies only
+    run where the frontend compiles)::
+
+        cloud = reflex_xy.inline(xy.scatter_chart(xy.scatter(x, y)))
+
+        def index():
+            return reflex_xy.chart(cloud, height="460px")
+
+    The token is content-addressed — every worker independently derives the
+    same one, so the frontend's baked-in token resolves everywhere without
+    state or rebuild hooks. The entry is pinned (exempt from the TTL sweep):
+    there is no recipe to rebuild it from, so it lives with the process.
+
+    Shared by design: one figure object serves every viewer, so kernel-side
+    drill state is shared too (like N notebook views of one widget). Data
+    depending on who's looking belongs in `@reflex_xy.figure`; data needing
+    no kernel at all can be passed straight to `reflex_xy.chart()` (static
+    payload tier).
+    """
+    fig = _figure_of(chart_or_figure)
+    spec, blob = fig.build_payload()
+    canonical = json.dumps(spec, sort_keys=True, separators=(",", ":")).encode()
+    digest = hashlib.sha256(canonical + blob).hexdigest()[:20]
+    token = f"xyin-{digest}"
+    registry.publish(token, fig, broadcast=False, pinned=True)
+    return token
+
+
+def release(token: str) -> None:
+    """Drop a registered figure (idempotent)."""
+    registry.release(token)