Metadata-Version: 2.4
Name: reflex-xyflow
Version: 0.0.1
Summary: A Reflex custom component wrapping xyflow / React Flow (@xyflow/react) for building node-based UIs, flow charts, diagrams and graphs in pure Python.
Author-email: Ernesto Crespo <ecrespo@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/ecrespo/reflex-xyflow
Project-URL: Repository, https://github.com/ecrespo/reflex-xyflow
Project-URL: Documentation, https://github.com/ecrespo/reflex-xyflow#readme
Project-URL: Bug Tracker, https://github.com/ecrespo/reflex-xyflow/issues
Keywords: reflex,reflex-custom-components,xyflow,react-flow,reactflow,node-editor,diagrams,graphs,flowchart
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: reflex>=0.7.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# reflex-xyflow

A [Reflex](https://reflex.dev) custom component that wraps
[xyflow / React Flow](https://github.com/xyflow/xyflow) (`@xyflow/react`, v12),
so you can build node-based UIs — flow charts, diagrams, graphs, pipelines and
no-code editors — in **pure Python**.

> Status: **alpha** (v0.0.1). Core controlled-graph functionality works; see the
> [roadmap](docs/sdd/01-phases.md).

---

## Features

- Controlled graph driven entirely from Reflex server state (`nodes` / `edges`
  as plain dicts).
- Wrapped components: `ReactFlow`, `Background`, `Controls`, `MiniMap`, `Panel`,
  `Handle`, `NodeResizer`, `NodeToolbar`.
- Rich event surface: change / connect / drag / selection / pane / delete
  handlers, forwarded as Python event handlers.
- Pure-Python state reducers (`apply_node_changes`, `apply_edge_changes`,
  `add_edge`) that mirror React Flow's client-side helpers.
- Automatic stylesheet injection and React Flow 12 color modes
  (`light` / `dark` / `system`).

## Installation

Using `uv` (recommended):

```bash
uv pip install reflex-xyflow
```

Using `pip`:

```bash
pip install reflex-xyflow
```

## Quick start

```python
import reflex as rx
import reflex_xyflow as xyflow
from reflex_xyflow import add_edge, apply_node_changes, apply_edge_changes


class State(rx.State):
    nodes: list[dict] = [
        {"id": "1", "type": "input", "data": {"label": "Start"},
         "position": {"x": 250, "y": 25}},
        {"id": "2", "data": {"label": "Middle"}, "position": {"x": 100, "y": 125}},
        {"id": "3", "type": "output", "data": {"label": "End"},
         "position": {"x": 250, "y": 250}},
    ]
    edges: list[dict] = [
        {"id": "e1-2", "source": "1", "target": "2", "animated": True},
        {"id": "e2-3", "source": "2", "target": "3"},
    ]

    @rx.event
    def on_nodes_change(self, changes: list[dict]):
        self.nodes = apply_node_changes(changes, self.nodes)

    @rx.event
    def on_edges_change(self, changes: list[dict]):
        self.edges = apply_edge_changes(changes, self.edges)

    @rx.event
    def on_connect(self, connection: dict):
        self.edges = add_edge(connection, self.edges)


def index() -> rx.Component:
    return rx.box(
        xyflow.react_flow(
            xyflow.background(variant="dots", gap=16),
            xyflow.controls(),
            xyflow.mini_map(zoomable=True, pannable=True),
            nodes=State.nodes,
            edges=State.edges,
            on_nodes_change=State.on_nodes_change,
            on_edges_change=State.on_edges_change,
            on_connect=State.on_connect,
            fit_view=True,
        ),
        width="100vw",
        height="100vh",
    )


app = rx.App()
app.add_page(index)
```

> **Sizing**: `ReactFlow` fills its parent (`width/height: 100%`). Always place
> it inside a sized container (e.g. a `rx.box` with an explicit height).

## Components

| Component | Factory | Purpose |
|-----------|---------|---------|
| `ReactFlow` | `xyflow.react_flow` | The canvas; holds nodes, edges and events. |
| `ReactFlowProvider` | `xyflow.react_flow_provider` | Context for hooks outside the canvas. |
| `Background` | `xyflow.background` | Dots / lines / cross pattern. |
| `Controls` | `xyflow.controls` | Zoom / fit-view / lock controls. |
| `MiniMap` | `xyflow.mini_map` | Overview map. |
| `Panel` | `xyflow.panel` | Positioned overlay for toolbars. |
| `Handle` | `xyflow.handle` | Connection point in a custom node. |
| `NodeResizer` | `xyflow.node_resizer` | Resize handles for a node. |
| `NodeToolbar` | `xyflow.node_toolbar` | Floating toolbar on a node. |

See the [specification](docs/sdd/02-specification.md) for the full prop and
event catalogue, and the [data model](docs/sdd/04-data-model.md) for node/edge
shapes.

## Demo app

A multi-page demo (Overview, Interactive, Backgrounds, Styling) lives in
[`xyflow_demo/`](xyflow_demo/):

```bash
cd xyflow_demo
uv pip install -e ..        # install the component in editable mode
reflex run
```

## Documentation

- [SDD overview](docs/sdd/00-overview.md)
- [Phases & roadmap](docs/sdd/01-phases.md)
- [Specification](docs/sdd/02-specification.md)
- [Architecture](docs/sdd/03-architecture.md)
- [Data model](docs/sdd/04-data-model.md)
- [Implementation plan](docs/sdd/05-implementation-plan.md)
- [Tasks](docs/sdd/06-tasks.md)
- [Publishing guide](docs/PUBLISHING.md)

## Development

This project uses `uv`. Reproduce the Reflex custom-component layout via
`reflex component init` or work directly in this repo:

```bash
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
ruff check .
```

## Acknowledgements

- [xyflow / React Flow](https://github.com/xyflow/xyflow) by the xyflow team
  (MIT).
- [Reflex](https://github.com/reflex-dev/reflex) (Apache-2.0).

## License

Apache-2.0 — see [LICENSE](LICENSE).
