reflex-xyflow 0.0.1__py3-none-any.whl

reflex_xyflow/__init__.py

@@ -0,0 +1,147 @@
+"""reflex-xyflow: a Reflex custom component wrapping ``@xyflow/react``.
+
+Import the factory functions to build node-based UIs in pure Python::
+
+    import reflex as rx
+    import reflex_xyflow as xyflow
+
+    def index():
+        return rx.box(
+            xyflow.react_flow(
+                xyflow.background(),
+                xyflow.controls(),
+                xyflow.mini_map(),
+                nodes=State.nodes,
+                edges=State.edges,
+                on_nodes_change=State.on_nodes_change,
+                on_connect=State.on_connect,
+                fit_view=True,
+            ),
+            width="100vw",
+            height="100vh",
+        )
+"""
+
+from __future__ import annotations
+
+from ._base import XYFLOW_NPM_PACKAGE, XYFLOW_NPM_VERSION
+from .components import (
+    Background,
+    Controls,
+    Handle,
+    MiniMap,
+    NodeResizer,
+    NodeToolbar,
+    Panel,
+    background,
+    controls,
+    handle,
+    mini_map,
+    node_resizer,
+    node_toolbar,
+    panel,
+)
+from .custom import XYFlowCustomTypes, custom_types, js_component
+from .enums import (
+    BackgroundVariant,
+    ColorMode,
+    ConnectionLineType,
+    ConnectionMode,
+    HandleType,
+    MarkerType,
+    PanOnScrollMode,
+    Position,
+    SelectionMode,
+)
+from .flow import (
+    ReactFlow,
+    ReactFlowProvider,
+    react_flow,
+    react_flow_provider,
+)
+from .imperative import (
+    XYFlowController,
+    download_image,
+    fit_view,
+    flow_controller,
+    get_edges,
+    get_nodes,
+    get_viewport,
+    set_center,
+    set_viewport,
+    zoom_in,
+    zoom_out,
+)
+from .utils import (
+    add_edge,
+    apply_edge_changes,
+    apply_node_changes,
+    deserialize_graph,
+    layout_nodes,
+    reconnect_edge,
+    serialize_graph,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # version / package metadata
+    "__version__",
+    "XYFLOW_NPM_PACKAGE",
+    "XYFLOW_NPM_VERSION",
+    # core flow
+    "ReactFlow",
+    "ReactFlowProvider",
+    "react_flow",
+    "react_flow_provider",
+    # components (classes)
+    "Background",
+    "Controls",
+    "MiniMap",
+    "Panel",
+    "Handle",
+    "NodeResizer",
+    "NodeToolbar",
+    # components (factories)
+    "background",
+    "controls",
+    "mini_map",
+    "panel",
+    "handle",
+    "node_resizer",
+    "node_toolbar",
+    # enums
+    "Position",
+    "HandleType",
+    "BackgroundVariant",
+    "ConnectionMode",
+    "ConnectionLineType",
+    "MarkerType",
+    "PanOnScrollMode",
+    "SelectionMode",
+    "ColorMode",
+    # utils
+    "apply_node_changes",
+    "apply_edge_changes",
+    "add_edge",
+    "reconnect_edge",
+    "serialize_graph",
+    "deserialize_graph",
+    "layout_nodes",
+    # imperative useReactFlow API
+    "XYFlowController",
+    "flow_controller",
+    "fit_view",
+    "zoom_in",
+    "zoom_out",
+    "set_viewport",
+    "set_center",
+    "get_nodes",
+    "get_edges",
+    "get_viewport",
+    "download_image",
+    # custom node/edge types
+    "js_component",
+    "custom_types",
+    "XYFlowCustomTypes",
+]

reflex_xyflow/_base.py

@@ -0,0 +1,29 @@
+"""Base component for the reflex-xyflow wrapper.
+
+All wrapped React Flow components inherit from :class:`XYFlowBase`, which pins
+the ``@xyflow/react`` npm dependency and injects the required stylesheet once
+per page.
+"""
+
+from __future__ import annotations
+
+import reflex as rx
+
+# Pin the wrapped npm package version. Bump this together with the Python
+# package version when adopting a new React Flow release.
+XYFLOW_NPM_PACKAGE = "@xyflow/react"
+XYFLOW_NPM_VERSION = "12.8.6"
+
+
+class XYFlowBase(rx.Component):
+    """Base class for every component wrapped from ``@xyflow/react``."""
+
+    # The npm dependency installed into the compiled frontend.
+    library = f"{XYFLOW_NPM_PACKAGE}@{XYFLOW_NPM_VERSION}"
+
+    # React Flow is a default export-less ESM module: every public component is
+    # a named export, so ``is_default`` stays False (the Reflex default).
+
+    def add_custom_code(self) -> list[str]:
+        """Import the React Flow base stylesheet exactly once per page."""
+        return ['import "@xyflow/react/dist/style.css";']

reflex_xyflow/components.py

@@ -0,0 +1,141 @@
+"""Supporting React Flow components: Background, Controls, MiniMap, Panel,
+Handle, NodeResizer and NodeToolbar.
+
+All of these are named exports of ``@xyflow/react`` (v12), so they share the
+:class:`XYFlowBase` base and only declare the props we surface to Python.
+"""
+
+from typing import Any
+
+import reflex as rx
+from reflex.vars import Var
+
+from ._base import XYFlowBase
+
+
+# -- Event-handler argument specs --------------------------------------------
+def _no_args_spec() -> tuple:
+    return ()
+
+
+def _interactive_spec(is_interactive: Var[bool]) -> tuple[Var[bool]]:
+    return (is_interactive,)
+
+
+def _resize_spec(event: Var, params: Var[dict]) -> tuple[Var[dict]]:
+    """NodeResizer resize handlers: forward the ``{x, y, width, height}`` params."""
+    return (params,)
+
+
+class Background(XYFlowBase):
+    """Renders the dotted / lined / cross background pattern of the canvas."""
+
+    tag = "Background"
+
+    variant: Var[str]  # "dots" | "lines" | "cross"
+    color: Var[str]
+    bg_color: Var[str]
+    gap: Var[int]
+    size: Var[float]
+    offset: Var[float]
+    line_width: Var[float]
+    # Multiple backgrounds may be layered; an id keeps their patterns distinct.
+    id: Var[str]
+
+
+class Controls(XYFlowBase):
+    """Zoom in / out, fit-view and interactivity-lock control panel."""
+
+    tag = "Controls"
+
+    show_zoom: Var[bool]
+    show_fit_view: Var[bool]
+    show_interactive: Var[bool]
+    fit_view_options: Var[dict[str, Any]]
+    position: Var[str]
+    orientation: Var[str]  # "horizontal" | "vertical"
+
+    on_zoom_in: rx.EventHandler[_no_args_spec]
+    on_zoom_out: rx.EventHandler[_no_args_spec]
+    on_fit_view: rx.EventHandler[_no_args_spec]
+    on_interactive_change: rx.EventHandler[_interactive_spec]
+
+
+class MiniMap(XYFlowBase):
+    """Overview map of the whole graph."""
+
+    tag = "MiniMap"
+
+    pannable: Var[bool]
+    zoomable: Var[bool]
+    node_color: Var[str]
+    node_stroke_color: Var[str]
+    node_border_radius: Var[int]
+    node_stroke_width: Var[float]
+    mask_color: Var[str]
+    mask_stroke_color: Var[str]
+    position: Var[str]
+    aria_label: Var[str]
+
+
+class Panel(XYFlowBase):
+    """Absolutely-positioned overlay (e.g. for toolbars/buttons on the canvas)."""
+
+    tag = "Panel"
+
+    position: Var[str]  # "top-left" | "top-right" | "bottom-left" ...
+
+
+class Handle(XYFlowBase):
+    """Connection point rendered inside a custom node component."""
+
+    tag = "Handle"
+
+    type: Var[str]  # "source" | "target"
+    position: Var[str]  # "top" | "right" | "bottom" | "left"
+    id: Var[str]
+    is_connectable: Var[bool]
+    is_connectable_start: Var[bool]
+    is_connectable_end: Var[bool]
+
+
+class NodeResizer(XYFlowBase):
+    """Adds resize handles around a custom node."""
+
+    tag = "NodeResizer"
+
+    color: Var[str]
+    handle_class_name: Var[str]
+    line_class_name: Var[str]
+    is_visible: Var[bool]
+    min_width: Var[int]
+    min_height: Var[int]
+    max_width: Var[int]
+    max_height: Var[int]
+    keep_aspect_ratio: Var[bool]
+
+    on_resize_start: rx.EventHandler[_resize_spec]
+    on_resize: rx.EventHandler[_resize_spec]
+    on_resize_end: rx.EventHandler[_resize_spec]
+
+
+class NodeToolbar(XYFlowBase):
+    """Floating toolbar attached to a node (shown on selection by default)."""
+
+    tag = "NodeToolbar"
+
+    node_id: Var[str]
+    is_visible: Var[bool]
+    position: Var[str]
+    offset: Var[float]
+    align: Var[str]  # "center" | "start" | "end"
+
+
+# Convenience factory aliases -------------------------------------------------
+background = Background.create
+controls = Controls.create
+mini_map = MiniMap.create
+panel = Panel.create
+handle = Handle.create
+node_resizer = NodeResizer.create
+node_toolbar = NodeToolbar.create

reflex_xyflow/custom.py

@@ -0,0 +1,124 @@
+"""Custom node & edge type registration (Phase 3).
+
+React Flow renders custom nodes/edges by mapping a *type* string to a React
+component via the ``nodeTypes`` / ``edgeTypes`` props. Those values must be
+component *functions*, not strings. Authoring full JSX renderers in Python is a
+documented non-goal, so this module ships:
+
+* :func:`js_component` — wrap a JS identifier as a raw Var so it compiles to a
+  bare reference (``BadgeNode``) instead of a string (``"BadgeNode"``);
+* :func:`custom_types` — a headless component that injects two ready-made JS
+  templates whose content is driven by each element's Python ``data``:
+
+  - ``BadgeNode`` — a pill node with left/right :class:`Handle`s rendering
+    ``data.label``;
+  - ``ButtonEdge`` — a custom edge using ``getBezierPath`` + ``BaseEdge`` with
+    an ``EdgeLabelRenderer`` label from ``data.label``.
+
+Register them on the flow::
+
+    xyflow.react_flow(
+        xyflow.custom_types(),
+        node_types={"badge": xyflow.js_component("BadgeNode")},
+        edge_types={"button": xyflow.js_component("ButtonEdge")},
+        nodes=[{"id": "1", "type": "badge", "data": {"label": "Hi"}, ...}],
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+from reflex.vars import Var
+
+
+def js_component(name: str) -> Var:
+    """Reference a JS component by name as a raw Var (unquoted identifier)."""
+    return Var(_js_expr=name, _var_type=Any)
+
+
+# JSX templates injected into the page module. They are transformed by the
+# frontend bundler (the page is a .jsx file). Content comes from each element's
+# ``data`` so Python state drives what they show.
+_CUSTOM_TYPES_CODE = """
+function BadgeNode({ data, selected }) {
+  return (
+    <div
+      className="xyflow-badge-node"
+      style={{
+        padding: "10px 18px",
+        borderRadius: "9999px",
+        border: "2px solid " + (selected ? "#ec4899" : "#6366f1"),
+        background: "var(--xyflow-badge-bg, #ffffff)",
+        color: "var(--xyflow-badge-fg, #1f2937)",
+        fontSize: "12px",
+        fontWeight: 600,
+        boxShadow: "0 1px 3px rgba(0,0,0,0.12)",
+      }}
+    >
+      <Handle type="target" position={Position.Left} />
+      {data?.label ?? ""}
+      <Handle type="source" position={Position.Right} />
+    </div>
+  );
+}
+
+function ButtonEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, markerEnd, style, data }) {
+  const [edgePath, labelX, labelY] = getBezierPath({
+    sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition,
+  });
+  return (
+    <>
+      <BaseEdge id={id} path={edgePath} markerEnd={markerEnd} style={style} />
+      <EdgeLabelRenderer>
+        <div
+          className="nodrag nopan"
+          style={{
+            position: "absolute",
+            transform: "translate(-50%, -50%) translate(" + labelX + "px," + labelY + "px)",
+            pointerEvents: "all",
+            background: "#ffffff",
+            border: "1px solid #6366f1",
+            borderRadius: "6px",
+            padding: "2px 6px",
+            fontSize: "11px",
+            fontWeight: 600,
+          }}
+        >
+          {data?.label ?? "edge"}
+        </div>
+      </EdgeLabelRenderer>
+    </>
+  );
+}
+""".strip()
+
+
+class XYFlowCustomTypes(rx.Component):
+    """Headless component that defines the bundled custom node/edge templates.
+
+    Place it once inside (or alongside) a flow; it renders nothing and only
+    injects the ``BadgeNode`` / ``ButtonEdge`` JS definitions and the React Flow
+    helpers they import.
+    """
+
+    tag = "XYFlowCustomTypes"
+    library = None  # local component defined in custom code
+
+    def add_imports(self) -> dict[str, list[str]]:
+        return {
+            "@xyflow/react": [
+                "Handle",
+                "Position",
+                "BaseEdge",
+                "EdgeLabelRenderer",
+                "getBezierPath",
+            ],
+        }
+
+    def add_custom_code(self) -> list[str]:
+        return [_CUSTOM_TYPES_CODE + "\n\nfunction XYFlowCustomTypes() { return null; }"]
+
+
+custom_types = XYFlowCustomTypes.create

reflex_xyflow/enums.py

@@ -0,0 +1,76 @@
+"""String enums mirroring the ``@xyflow/react`` literal-union props.
+
+These are plain ``str`` enums so they serialize transparently to the JS values
+React Flow expects (``"top"``, ``"dots"``, ``"smoothstep"`` ...).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Position(str, Enum):
+    """Handle / toolbar placement on a node."""
+
+    TOP = "top"
+    RIGHT = "right"
+    BOTTOM = "bottom"
+    LEFT = "left"
+
+
+class HandleType(str, Enum):
+    """Whether a handle starts (source) or receives (target) a connection."""
+
+    SOURCE = "source"
+    TARGET = "target"
+
+
+class BackgroundVariant(str, Enum):
+    """Pattern rendered by the :class:`Background` component."""
+
+    DOTS = "dots"
+    LINES = "lines"
+    CROSS = "cross"
+
+
+class ConnectionMode(str, Enum):
+    """Strictness of which handles may be connected together."""
+
+    STRICT = "strict"
+    LOOSE = "loose"
+
+
+class ConnectionLineType(str, Enum):
+    """Shape of the line drawn while creating a connection."""
+
+    BEZIER = "default"
+    STRAIGHT = "straight"
+    STEP = "step"
+    SMOOTHSTEP = "smoothstep"
+    SIMPLEBEZIER = "simplebezier"
+
+
+class MarkerType(str, Enum):
+    """Arrow head style for edge markers."""
+
+    ARROW = "arrow"
+    ARROWCLOSED = "arrowclosed"
+
+
+class PanOnScrollMode(str, Enum):
+    FREE = "free"
+    VERTICAL = "vertical"
+    HORIZONTAL = "horizontal"
+
+
+class SelectionMode(str, Enum):
+    PARTIAL = "partial"
+    FULL = "full"
+
+
+class ColorMode(str, Enum):
+    """Built-in theming mode for React Flow 12."""
+
+    LIGHT = "light"
+    DARK = "dark"
+    SYSTEM = "system"