reflex-gravityui-graph 0.1.0__py3-none-any.whl

reflex_gravityui_graph/__init__.py

@@ -0,0 +1,93 @@
+"""reflex-gravityui-graph: a Reflex wrapper for @gravity-ui/graph.
+
+Public API::
+
+    from reflex_gravityui_graph import graph_canvas, GravityGraph
+
+    # DDD value objects for building graph data:
+    from reflex_gravityui_graph import Block, Connection, Anchor, EAnchorType, GraphData
+
+    # Example/recipe helpers (reproduce the upstream Storybook stories):
+    from reflex_gravityui_graph import (
+        one_block, two_connected_blocks, colored_connections, block_with_anchors,
+        generate_layered_blocks, grouped_graph, default_settings, THEMES,
+    )
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from .domain import (
+    DEFAULT_BLOCK_HEIGHT,
+    DEFAULT_BLOCK_IS,
+    DEFAULT_BLOCK_WIDTH,
+    Anchor,
+    Block,
+    Connection,
+    EAnchorType,
+    GraphData,
+)
+from .recipes import (
+    DARK_THEME,
+    LIGHT_THEME,
+    THEMES,
+    block_with_anchors,
+    colored_connections,
+    default_settings,
+    generate_layered_blocks,
+    grouped_graph,
+    one_block,
+    two_connected_blocks,
+)
+
+# The component layer (``graph.py``) imports Reflex. We expose it lazily via
+# PEP 562 ``__getattr__`` so the pure-Python domain/recipe API stays importable
+# and unit-testable without Reflex installed (NFR5). Reflex is only imported
+# when one of these symbols is actually accessed.
+_LAZY_COMPONENT_EXPORTS = {"GravityGraph", "graph_canvas", "GRAVITY_GRAPH_VERSION"}
+
+if TYPE_CHECKING:  # pragma: no cover - typing/IDE only
+    from .graph import (  # noqa: F401
+        GRAVITY_GRAPH_VERSION,
+        GravityGraph,
+        graph_canvas,
+    )
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily resolve the Reflex-dependent component exports (PEP 562)."""
+    if name in _LAZY_COMPONENT_EXPORTS:
+        from . import graph
+
+        return getattr(graph, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Component
+    "GravityGraph",
+    "graph_canvas",
+    "GRAVITY_GRAPH_VERSION",
+    # Domain
+    "Anchor",
+    "Block",
+    "Connection",
+    "EAnchorType",
+    "GraphData",
+    "DEFAULT_BLOCK_IS",
+    "DEFAULT_BLOCK_WIDTH",
+    "DEFAULT_BLOCK_HEIGHT",
+    # Recipes
+    "default_settings",
+    "one_block",
+    "two_connected_blocks",
+    "colored_connections",
+    "block_with_anchors",
+    "generate_layered_blocks",
+    "grouped_graph",
+    "THEMES",
+    "LIGHT_THEME",
+    "DARK_THEME",
+    "__version__",
+]

reflex_gravityui_graph/domain.py

@@ -0,0 +1,210 @@
+"""Domain value objects for @gravity-ui/graph entities (DDD).
+
+These are framework-agnostic, immutable Python value objects that capture the
+upstream entity shapes (``TBlock``, ``TConnection``, ``TAnchor``) and validate
+their invariants in Python, so a misconfigured graph fails fast with a clear
+message instead of silently rendering broken on Canvas. Each value object knows
+how to serialize itself to the exact camelCase dict the library expects.
+
+Typical use::
+
+    from reflex_gravityui_graph import Block, Connection, Anchor, EAnchorType
+
+    a = Block(id="a", x=0, y=0, name="A",
+              anchors=[Anchor(id="out", block_id="a", type=EAnchorType.OUT)])
+    b = Block(id="b", x=300, y=200, name="B",
+              anchors=[Anchor(id="in", block_id="b", type=EAnchorType.IN)])
+    edge = Connection(source_block_id="a", source_anchor_id="out",
+                      target_block_id="b", target_anchor_id="in")
+
+    blocks = [a.to_dict(), b.to_dict()]
+    connections = [edge.to_dict()]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Union
+
+BlockId = Union[str, int]
+
+# Default block discriminator. @gravity-ui/graph renders blocks whose ``is`` is
+# not registered in ``settings.blockComponents`` with its built-in canvas block,
+# so this default "just works" without registering a custom component.
+DEFAULT_BLOCK_IS = "block-action"
+
+# Library defaults for block geometry (constants.block.WIDTH / HEIGHT).
+DEFAULT_BLOCK_WIDTH = 200
+DEFAULT_BLOCK_HEIGHT = 160
+
+
+class EAnchorType(str, Enum):
+    """Anchor direction, mirroring the upstream ``EAnchorType`` enum."""
+
+    IN = "IN"
+    OUT = "OUT"
+
+
+@dataclass(frozen=True)
+class Anchor:
+    """A connection point on a block (``TAnchor``).
+
+    ``index`` orders multiple anchors of the same ``type`` on a block (the
+    library auto-positions IN anchors on the left, OUT anchors on the right).
+    """
+
+    id: str
+    block_id: BlockId
+    type: Union[EAnchorType, str] = EAnchorType.OUT
+    index: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("Anchor.id must be a non-empty string")
+        if self.index < 0:
+            raise ValueError(f"Anchor.index must be >= 0, got {self.index}")
+
+    def to_dict(self) -> dict[str, Any]:
+        anchor_type = (
+            self.type.value if isinstance(self.type, EAnchorType) else self.type
+        )
+        return {
+            "id": self.id,
+            "blockId": self.block_id,
+            "type": anchor_type,
+            "index": self.index,
+        }
+
+
+@dataclass(frozen=True)
+class Block:
+    """A graph node (``TBlock``).
+
+    The library requires ``id``, ``is``, ``x``, ``y``, ``width``, ``height`` and
+    ``name``; everything else is optional. ``is_`` maps to the upstream ``is``
+    discriminator (``is`` is a Python keyword, hence the trailing underscore).
+    """
+
+    id: BlockId
+    x: int = 0
+    y: int = 0
+    name: str = ""
+    is_: str = DEFAULT_BLOCK_IS
+    width: int = DEFAULT_BLOCK_WIDTH
+    height: int = DEFAULT_BLOCK_HEIGHT
+    selected: bool = False
+    group: str | None = None
+    anchors: list[Anchor] = field(default_factory=list)
+    meta: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if self.id is None or self.id == "":
+            raise ValueError("Block.id must be a non-empty id")
+        if self.width <= 0 or self.height <= 0:
+            raise ValueError(
+                f"Block {self.id!r} must have positive width/height, "
+                f"got {self.width}x{self.height}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "id": self.id,
+            "is": self.is_,
+            "x": self.x,
+            "y": self.y,
+            "width": self.width,
+            "height": self.height,
+            "name": self.name or str(self.id),
+            "selected": self.selected,
+            "anchors": [a.to_dict() for a in self.anchors],
+        }
+        if self.group is not None:
+            data["group"] = self.group
+        if self.meta is not None:
+            data["meta"] = self.meta
+        return data
+
+
+@dataclass(frozen=True)
+class Connection:
+    """A graph edge (``TConnection``).
+
+    Connect blocks directly (``source_block_id`` -> ``target_block_id``) or via
+    named anchors (``source_anchor_id`` / ``target_anchor_id``). Optional
+    ``label``, ``dashed`` and ``styles`` (e.g. ``{"selectedBackground": ...,
+    "dashes": [6, 4]}``) customize the rendered edge.
+    """
+
+    source_block_id: BlockId
+    target_block_id: BlockId
+    source_anchor_id: str | None = None
+    target_anchor_id: str | None = None
+    id: Union[str, int, None] = None
+    label: str | None = None
+    dashed: bool = False
+    selected: bool = False
+    styles: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if self.source_block_id is None or self.target_block_id is None:
+            raise ValueError(
+                "Connection requires both source_block_id and target_block_id"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "sourceBlockId": self.source_block_id,
+            "targetBlockId": self.target_block_id,
+        }
+        if self.source_anchor_id is not None:
+            data["sourceAnchorId"] = self.source_anchor_id
+        if self.target_anchor_id is not None:
+            data["targetAnchorId"] = self.target_anchor_id
+        if self.id is not None:
+            data["id"] = self.id
+        if self.label is not None:
+            data["label"] = self.label
+        if self.dashed:
+            data["dashed"] = True
+        if self.selected:
+            data["selected"] = True
+        if self.styles is not None:
+            data["styles"] = self.styles
+        return data
+
+
+@dataclass(frozen=True)
+class GraphData:
+    """An aggregate of blocks + connections with validated referential integrity.
+
+    Use it to build a whole graph and emit the two props in one step::
+
+        data = GraphData(blocks=[...], connections=[...])
+        graph_canvas(blocks=data.blocks_payload(), connections=data.connections_payload())
+    """
+
+    blocks: list[Block] = field(default_factory=list)
+    connections: list[Connection] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        ids = [b.id for b in self.blocks]
+        duplicates = {i for i in ids if ids.count(i) > 1}
+        if duplicates:
+            raise ValueError(f"Duplicate block ids: {sorted(map(str, duplicates))}")
+        known = set(ids)
+        for c in self.connections:
+            if c.source_block_id not in known:
+                raise ValueError(
+                    f"Connection source {c.source_block_id!r} is not a known block"
+                )
+            if c.target_block_id not in known:
+                raise ValueError(
+                    f"Connection target {c.target_block_id!r} is not a known block"
+                )
+
+    def blocks_payload(self) -> list[dict[str, Any]]:
+        return [b.to_dict() for b in self.blocks]
+
+    def connections_payload(self) -> list[dict[str, Any]]:
+        return [c.to_dict() for c in self.connections]

reflex_gravityui_graph/graph.py

@@ -0,0 +1,146 @@
+"""A Reflex wrapper around @gravity-ui/graph.
+
+`@gravity-ui/graph` (https://github.com/gravity-ui/graph) is a high-performance
+graph / flowchart / node-editor visualization library. It renders the whole
+graph on Canvas when zoomed out (fast for thousands of nodes) and swaps to
+HTML/React for rich interactions when zoomed in.
+
+The upstream React API is hook + imperative driven (``useGraph`` creates a
+``Graph`` instance, ``setEntities`` pushes nodes/edges, ``start`` runs the render
+loop once attached). Reflex components cannot call React hooks directly, so this
+package ships a small local JSX bridge (``graph_canvas.jsx``) that encapsulates
+that lifecycle and exposes a flat, declarative prop surface. This module is the
+Python side of that bridge.
+
+Public API::
+
+    from reflex_gravityui_graph import graph_canvas
+
+    graph_canvas(
+        blocks=[{"id": "a", "is": "block-action", "x": 0, "y": 0,
+                 "width": 120, "height": 120, "name": "A"}],
+        connections=[],
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+from reflex.components.component import NoSSRComponent
+
+# Pinned npm version for reproducible builds. Bump deliberately.
+GRAVITY_GRAPH_VERSION = "@gravity-ui/graph@1.11.0"
+
+# Copy the local JSX bridge into the compiled frontend's public dir, then import
+# the bridge from there (same mechanism used for other JSX-bridge components).
+_BRIDGE_PATH = rx.asset("./graph_canvas.jsx", shared=True)
+
+
+def _payload_event_spec(payload: rx.Var[dict]) -> tuple[rx.Var[dict]]:
+    """Forward a single serializable payload dict to the event handler."""
+    return (payload,)
+
+
+class GravityGraph(NoSSRComponent):
+    """A @gravity-ui/graph canvas, driven declaratively from Reflex.
+
+    The component is client-only: the engine touches ``window``/Canvas, so it is
+    a ``NoSSRComponent`` (Reflex emits a dynamic, SSR-disabled import). See
+    ``docs/sdd/02-architecture.md``.
+
+    Sizing: ``GraphCanvas`` fills its container, so give the component an
+    explicit height (e.g. ``height="600px"``) or pass ``style``.
+    """
+
+    # Import the local JSX bridge from the frontend public dir.
+    library = f"$/public{_BRIDGE_PATH}"
+
+    # Named export from the bridge.
+    tag = "GravityGraph"
+    is_default = False
+
+    # Ensure the real npm package lands in package.json with a pinned version.
+    lib_dependencies: list[str] = [GRAVITY_GRAPH_VERSION]
+
+    # ------------------------------------------------------------------ #
+    # Data props (plain, JSON-serializable)
+    # ------------------------------------------------------------------ #
+
+    # Blocks (nodes). Each dict uses upstream camelCase keys:
+    # ``id``, ``is``, ``x``, ``y``, ``width``, ``height``, ``name`` and the
+    # optional ``anchors``, ``selected``, ``group``, ``meta``.
+    blocks: rx.Var[list[dict[str, Any]]]
+
+    # Connections (edges). Each dict: ``sourceBlockId`` / ``targetBlockId`` and
+    # optional ``sourceAnchorId`` / ``targetAnchorId`` / ``id`` / ``label`` /
+    # ``styles`` / ``dashed`` / ``selected``.
+    connections: rx.Var[list[dict[str, Any]]]
+
+    # Graph settings (``TGraphSettingsConfig``): ``canDragCamera``,
+    # ``canZoomCamera``, ``canCreateNewConnections``, ``useBezierConnections``,
+    # ``bezierConnectionDirection``, ``showConnectionArrows``,
+    # ``showConnectionLabels``, ``useBlocksAnchors``, ``scaleFontSize``, ...
+    settings: rx.Var[dict[str, Any]]
+
+    # View colors (``RecursivePartial<TGraphColors>``): ``canvas``, ``block``,
+    # ``anchor``, ``connection``, ``selection``, ...
+    colors: rx.Var[dict[str, Any]]
+
+    # View constants (``RecursivePartial<TGraphConstants>``): ``system``,
+    # ``camera``, ``block``, ``connection``, ``text``.
+    constants: rx.Var[dict[str, Any]]
+
+    # Configuration name passed to the underlying graph instance.
+    config_name: rx.Var[str]  # -> configName
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle / camera props
+    # ------------------------------------------------------------------ #
+
+    # Start the render loop automatically once the canvas is attached.
+    auto_start: rx.Var[bool]  # -> autoStart
+
+    # Fit the camera to the graph once attached.
+    zoom_on_start: rx.Var[bool]  # -> zoomOnStart
+
+    # Zoom target: ``"center"``, a rect, or a list of block ids.
+    zoom_target: rx.Var[Any]  # -> zoomTarget
+
+    # Padding (px) used when fitting the camera on start.
+    zoom_padding: rx.Var[int]  # -> zoomPadding
+
+    # Render rich HTML/React block bodies at detailed zoom (default canvas-only).
+    render_html_blocks: rx.Var[bool]  # -> renderHtmlBlocks
+
+    # ------------------------------------------------------------------ #
+    # Events (each forwards one serializable payload dict)
+    # ------------------------------------------------------------------ #
+
+    # ``{"added": [ids], "removed": [ids]}`` when the block selection changes.
+    on_block_selection_change: rx.EventHandler[_payload_event_spec]
+
+    # ``{"sourceBlockId", "targetBlockId", "sourceAnchorId", "targetAnchorId"}``
+    # when a new connection is drawn (requires ``canCreateNewConnections``).
+    on_connection_created: rx.EventHandler[_payload_event_spec]
+
+    # ``{"added": [ids], "removed": [ids]}`` when the connection selection changes.
+    on_connection_selection_change: rx.EventHandler[_payload_event_spec]
+
+    # ``{"x", "y", "scale"}`` whenever the camera pans/zooms.
+    on_camera_change: rx.EventHandler[_payload_event_spec]
+
+    # ``{"blockId", "x", "y"}`` when a block drag finishes.
+    on_block_drag_end: rx.EventHandler[_payload_event_spec]
+
+    # ``{"state"}`` on graph state transitions (e.g. ``"ATTACHED"``).
+    on_state_change: rx.EventHandler[_payload_event_spec]
+
+    # Reflex auto-converts snake_case prop names to camelCase, covering every
+    # prop above. Add entries only for names the heuristic would get wrong.
+    _rename_props: dict[str, str] = {}
+
+
+# Convenience factory: ``graph_canvas(blocks=[...], connections=[...])``.
+graph_canvas = GravityGraph.create

reflex_gravityui_graph/graph.pyi

@@ -0,0 +1,123 @@
+"""Stub file for custom_components/reflex_gravityui_graph/graph.py"""
+
+# ------------------- DO NOT EDIT ----------------------
+# This file was generated by `reflex/utils/pyi_generator.py`!
+# ------------------------------------------------------
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional
+from reflex_components_core.core.breakpoints import Breakpoints
+from reflex_base.event import (
+    EventType,
+    PointerEventInfo,
+)
+from reflex_base.vars.base import Var
+import reflex as rx
+from reflex.components.component import NoSSRComponent
+
+GRAVITY_GRAPH_VERSION = "@gravity-ui/graph@1.11.0"
+_BRIDGE_PATH = rx.asset("./graph_canvas.jsx", shared=True)
+
+class GravityGraph(NoSSRComponent):
+    @classmethod
+    def create(
+        cls,
+        *children,
+        blocks: Var[list[dict[str, Any]]] | list[dict[str, Any]] | None = None,
+        connections: Var[list[dict[str, Any]]] | list[dict[str, Any]] | None = None,
+        settings: Var[dict[str, Any]] | dict[str, Any] | None = None,
+        colors: Var[dict[str, Any]] | dict[str, Any] | None = None,
+        constants: Var[dict[str, Any]] | dict[str, Any] | None = None,
+        config_name: Var[str] | str | None = None,
+        auto_start: Var[bool] | bool | None = None,
+        zoom_on_start: Var[bool] | bool | None = None,
+        zoom_target: Any | Var[Any] | None = None,
+        zoom_padding: Var[int] | int | None = None,
+        render_html_blocks: Var[bool] | bool | None = None,
+        style: Sequence[Mapping[str, Any]]
+        | Mapping[str, Any]
+        | Var[Mapping[str, Any]]
+        | Breakpoints
+        | None = None,
+        key: Any | None = None,
+        id: Any | None = None,
+        ref: Var | None = None,
+        class_name: Any | None = None,
+        custom_attrs: dict[str, Any | Var] | None = None,
+        on_block_drag_end: Optional[EventType[()] | EventType[rx.Var[dict]]] = None,
+        on_block_selection_change: Optional[
+            EventType[()] | EventType[rx.Var[dict]]
+        ] = None,
+        on_blur: Optional[EventType[()]] = None,
+        on_camera_change: Optional[EventType[()] | EventType[rx.Var[dict]]] = None,
+        on_click: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_connection_created: Optional[EventType[()] | EventType[rx.Var[dict]]] = None,
+        on_connection_selection_change: Optional[
+            EventType[()] | EventType[rx.Var[dict]]
+        ] = None,
+        on_context_menu: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_double_click: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_focus: Optional[EventType[()]] = None,
+        on_mount: Optional[EventType[()]] = None,
+        on_mouse_down: Optional[EventType[()]] = None,
+        on_mouse_enter: Optional[EventType[()]] = None,
+        on_mouse_leave: Optional[EventType[()]] = None,
+        on_mouse_move: Optional[EventType[()]] = None,
+        on_mouse_out: Optional[EventType[()]] = None,
+        on_mouse_over: Optional[EventType[()]] = None,
+        on_mouse_up: Optional[EventType[()]] = None,
+        on_scroll: Optional[EventType[()]] = None,
+        on_scroll_end: Optional[EventType[()]] = None,
+        on_state_change: Optional[EventType[()] | EventType[rx.Var[dict]]] = None,
+        on_unmount: Optional[EventType[()]] = None,
+        **props,
+    ) -> "GravityGraph":
+        """Create the component.
+
+        Args:
+            *children: The children of the component.
+            blocks: Blocks (nodes). Each dict uses upstream camelCase keys: ``id``, ``is``, ``x``, ``y``, ``width``, ``height``, ``name`` and the optional ``anchors``, ``selected``, ``group``, ``meta``.
+            connections: Connections (edges). Each dict: ``sourceBlockId`` / ``targetBlockId`` and optional ``sourceAnchorId`` / ``targetAnchorId`` / ``id`` / ``label`` / ``styles`` / ``dashed`` / ``selected``.
+            settings: Graph settings (``TGraphSettingsConfig``): ``canDragCamera``, ``canZoomCamera``, ``canCreateNewConnections``, ``useBezierConnections``, ``bezierConnectionDirection``, ``showConnectionArrows``, ``showConnectionLabels``, ``useBlocksAnchors``, ``scaleFontSize``, ...
+            colors: View colors (``RecursivePartial<TGraphColors>``): ``canvas``, ``block``, ``anchor``, ``connection``, ``selection``, ...
+            constants: View constants (``RecursivePartial<TGraphConstants>``): ``system``, ``camera``, ``block``, ``connection``, ``text``.
+            config_name: Configuration name passed to the underlying graph instance.
+            auto_start: Start the render loop automatically once the canvas is attached.
+            zoom_on_start: Fit the camera to the graph once attached.
+            zoom_target: Zoom target: ``"center"``, a rect, or a list of block ids.
+            zoom_padding: Padding (px) used when fitting the camera on start.
+            render_html_blocks: Render rich HTML/React block bodies at detailed zoom (default canvas-only).
+            style: The style of the component.
+            key: A unique key for the component.
+            id: The id for the component.
+            ref: The Var to pass as the ref to the component.
+            class_name: The class name for the component.
+            custom_attrs: Attributes passed directly to the component.
+            on_focus: Fired when the element (or some element inside of it) receives focus. For example, it is called when the user clicks on a text input.
+            on_blur: Fired when focus has left the element (or left some element inside of it). For example, it is called when the user clicks outside of a focused text input.
+            on_click: Fired when the user clicks on an element. For example, it's called when the user clicks on a button.
+            on_context_menu: Fired when the user right-clicks on an element.
+            on_double_click: Fired when the user double-clicks on an element.
+            on_mouse_down: Fired when the user presses a mouse button on an element.
+            on_mouse_enter: Fired when the mouse pointer enters the element.
+            on_mouse_leave: Fired when the mouse pointer leaves the element.
+            on_mouse_move: Fired when the mouse pointer moves over the element.
+            on_mouse_out: Fired when the mouse pointer moves out of the element.
+            on_mouse_over: Fired when the mouse pointer moves onto the element.
+            on_mouse_up: Fired when the user releases a mouse button on an element.
+            on_scroll: Fired when the user scrolls the element.
+            on_scroll_end: Fired when scrolling ends on the element.
+            on_mount: Fired when the component is mounted to the page.
+            on_unmount: Fired when the component is removed from the page. Only called during navigation, not on page refresh.
+            on_block_selection_change: ``{"added": [ids], "removed": [ids]}`` when the block selection changes.
+            on_connection_created: ``{"sourceBlockId", "targetBlockId", "sourceAnchorId", "targetAnchorId"}`` when a new connection is drawn (requires ``canCreateNewConnections``).
+            on_connection_selection_change: ``{"added": [ids], "removed": [ids]}`` when the connection selection changes.
+            on_camera_change: ``{"x", "y", "scale"}`` whenever the camera pans/zooms.
+            on_block_drag_end: ``{"blockId", "x", "y"}`` when a block drag finishes.
+            on_state_change: ``{"state"}`` on graph state transitions (e.g. ``"ATTACHED"``).
+            **props: The props of the component.
+
+        Returns:
+            The component."""
+        ...
+
+graph_canvas = GravityGraph.create