@dschz/solid-flow 0.1.3 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Sanchez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://assets.solidjs.com/banner?project=solid-flow&type=Ecosystem&background=tiles" alt="@dschz/solid-flow banner" />
 </p>
 
-# @dschz/solid-flow
+# Solid Flow
 
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![npm](https://img.shields.io/npm/v/@dschz/solid-flow?color=blue)](https://www.npmjs.com/package/@dschz/solid-flow)
@@ -15,10 +15,9 @@
 
 ## Current Unsupported Features:
 
-- `onlyRenderVisibleElements` prop: the ability to only render visible elements on screen.
-  - Note: The prop is defined as part of `SolidFlow` but it is a no-op. During development and benchmarking, it was revealed that use of it degraded rendering performance due to the amount of work done to actually achieve the outcome of the feature. We need to innovate on the implementation to make the performance comparable (ideally better) to the normal performance of rendering all the nodes/edges on screen. As such it is a no-op prop for now.
-- Custom MiniMap nodes: the ability to render custom node visuals in the minimap
-- Edge Reconnect Anchors: the ability to re-connect already connected edges
+- [onlyRenderVisibleElements](https://github.com/dsnchz/solid-flow/issues/15): render only visible elements.
+- [Custom MiniMap Nodes](https://github.com/dsnchz/solid-flow/issues/12): define custom minimap jsx node elements.
+- [Edge Reconnect Anchors](https://github.com/dsnchz/solid-flow/issues/13): the ability to re-connect already connected edges.
 
 ## Key Features
 
@@ -38,6 +37,9 @@ The easiest way to get the latest version of Solid Flow is to install it via npm
 
 ```sh
 npm install @dschz/solid-flow
+pnpm install @dschz/solid-flow
+yarn install @dschz/solid-flow
+bun install @dschz/solid-flow
 ```
 
 ## Quick Start
@@ -47,6 +49,7 @@ This is a basic example to get you started. For more advanced examples and full
 ```tsx
 import {
   SolidFlow,
+  SolidFlowProvider,
   Controls,
   Background,
   MiniMap,
@@ -54,10 +57,24 @@ import {
   type EdgeConnection,
   createEdgeStore,
   createNodeStore,
+  type Viewport,
 } from "@dschz/solid-flow";
 import "@dschz/solid-flow/styles"; // Required styles
 
-export default function Flow() {
+import { createStore, produce } from "solid-js/store";
+
+export default function Page() {
+  return (
+    <SolidFlowProvider>
+      <Flow />
+    </SolidFlowProvider>
+  )
+}
+
+function Flow() {
+  // Can invoke useSolidFlow due to parent Page + SolidFlowProvider wrapper. Contains all helper APIs
+  const { .. } = useSolidFlow();
+
   // Use createNodeStore and createEdgeStore for reactive state management
   const [nodes, setNodes] = createNodeStore([
     {
@@ -85,6 +102,16 @@ export default function Flow() {
     { id: "e2-3", source: "2", target: "3" },
   ]);
 
+  const [viewport, setViewport] = createStore<Viewport>({
+    x: 100,
+    y: 100,
+    zoom: 5,
+  });
+
+  const updateViewport = () => {
+    setViewport("x", (prev) => prev + 10);
+  };
+
   const onConnect = (connection: EdgeConnection) => {
     /**
      * Solid Flow updates the node/edge stores internally. The user-land edge store will have the connection inserted by the time onConnect fires so we can just go ahead and update the state of it
@@ -101,6 +128,9 @@ export default function Flow() {
     <SolidFlow nodes={nodes} edges={edges} onConnect={onConnect} fitView>
       <Controls />
       <MiniMap />
+      <Panel position="top-left">
+        <button onClick={updateViewport}>Update viewport</button>
+      </Panel>
       <Background variant="dots" />
     </SolidFlow>
   );
@@ -196,10 +226,10 @@ import { Handle, type NodeProps } from "@dschz/solid-flow";
 function CustomNode(props: NodeProps<{ label: string }, "custom">) {
   return (
     <div class="custom-node" style={{ padding: "10px", background: "white" }}>
-      <Handle type="target" position="top />
+      <Handle type="target" position="top" />
       <div>{props.data.label}</div>
       <Handle type="source" position="bottom" id="output-a" />
-      <Handle type="source" position="bottom id="output-b" style={{ left: "80%" }} />
+      <Handle type="source" position="bottom" id="output-b" style={{ left: "80%" }} />
     </div>
   );
 }

package/dist/index/index.d.ts

@@ -1,7 +1,7 @@
 import * as solid_js from 'solid-js';
 import { JSX, ParentProps, ParentComponent, Accessor } from 'solid-js';
 import * as _xyflow_system from '@xyflow/system';
-import { NodeProps as NodeProps$1, NodeBase, InternalNodeBase, EdgeBase, EdgePosition, BezierPathOptions, StepPathOptions, SmoothStepPathOptions, DefaultEdgeOptionsBase, OnReconnect, HandleType, FinalConnectionState, PanOnScrollMode as PanOnScrollMode$1, Position as Position$1, FitViewOptionsBase, ResizeControlVariant as ResizeControlVariant$1, ConnectionMode as ConnectionMode$1, SelectionMode as SelectionMode$1, ConnectionLineType as ConnectionLineType$2, OnBeforeDeleteBase, Connection, XYPosition, Handle as Handle$1, PanelPosition, Viewport, OnMove, OnMoveStart, OnMoveEnd, HandleProps as HandleProps$1, MarkerProps as MarkerProps$1, ShouldResize, OnResizeStart, OnResize, OnResizeEnd, ControlPosition, Align, NodeOrigin, SnapGrid, CoordinateExtent, ColorMode, ProOptions, IsValidConnection, OnError, OnConnectStart, OnConnectEnd, OnReconnectStart, OnReconnectEnd, AriaLabelConfig, ConnectionState, NodeConnection, ZoomInOut, ViewportHelperFunctionOptions, SetCenterOptions, Rect, FitBoundsOptions, HandleConnection, UpdateNodeInternals } from '@xyflow/system';
+import { NodeProps as NodeProps$1, NodeBase, InternalNodeBase, EdgeBase, EdgePosition, BezierPathOptions, StepPathOptions, SmoothStepPathOptions, DefaultEdgeOptionsBase, OnReconnect, HandleType, FinalConnectionState, PanOnScrollMode as PanOnScrollMode$1, Position as Position$1, FitViewOptionsBase, ResizeControlVariant as ResizeControlVariant$1, ConnectionMode as ConnectionMode$1, SelectionMode as SelectionMode$1, ConnectionLineType as ConnectionLineType$2, Connection, OnBeforeDeleteBase, XYPosition, Handle as Handle$1, PanelPosition, Viewport, OnMove, OnMoveStart, OnMoveEnd, HandleProps as HandleProps$1, MarkerProps as MarkerProps$1, EdgeToolbarBaseProps, ShouldResize, OnResizeStart, OnResize, OnResizeEnd, ControlPosition, Align, NodeOrigin, SnapGrid, CoordinateExtent, ColorMode, ZIndexMode, ProOptions, OnError, OnConnectStart, OnConnectEnd, OnReconnectStart, OnReconnectEnd, AriaLabelConfig, ColorModeClass, ConnectionState, NodeConnection, ZoomInOut, ViewportHelperFunctionOptions, SetCenterOptions, Rect, FitBoundsOptions, HandleConnection, UpdateNodeInternals } from '@xyflow/system';
 export { Align, AriaLabelConfig, BezierPathOptions, Box, ColorMode, ColorModeClass, Connection, ConnectionLineType, ConnectionMode, ControlLinePosition, ControlPosition, CoordinateExtent, Dimensions, EdgeMarker, EdgeMarkerType, FitBounds, FitBoundsOptions, GetBezierPathParams, GetSmoothStepPathParams, GetStraightPathParams, HandleConnection, IsValidConnection, MarkerType, NodeConnection, NodeOrigin, OnConnect, OnConnectEnd, OnConnectStart, OnConnectStartParams, OnError, OnMove, OnMoveEnd, OnMoveStart, OnReconnect, OnReconnectEnd, OnReconnectStart, OnResize, OnResizeEnd, OnResizeStart, OnSelectionDrag, PanOnScrollMode, PanelPosition, Position, ProOptions, Rect, ResizeControlVariant, ResizeDragEvent, ResizeParams, ResizeParamsWithDirection, SelectionMode, SelectionRect, SetCenter, SetCenterOptions, SetViewport, ShouldResize, SmoothStepPathOptions, SnapGrid, Transform, Viewport, ViewportHelperFunctionOptions, XYPosition, XYZPosition, addEdge, getBezierEdgeCenter, getBezierPath, getConnectedEdges, getEdgeCenter, getIncomers, getNodesBounds, getOutgoers, getSmoothStepPath, getStraightPath, getViewportForBounds } from '@xyflow/system';
 import { Store, SetStoreFunction } from 'solid-js/store';
 
@@ -274,6 +274,7 @@ type OnBeforeEdgeConnect<EdgeType extends Edge = Edge> = (connection: EdgeConnec
 type OnEdgeConnect = (connection: EdgeConnection) => void;
 type OnBeforeReconnect<EdgeType extends Edge = Edge> = (newEdge: EdgeType, oldEdge: EdgeType) => EdgeType | undefined;
 type OnBeforeDelete<NodeType extends Node = Node, EdgeType extends Edge = Edge> = OnBeforeDeleteBase<NodeType, EdgeType>;
+type IsValidConnection<EdgeType extends Edge = Edge> = (edge: EdgeType | Connection) => boolean;
 type OnSelectionChange<NodeType extends Node = Node, EdgeType extends Edge = Edge> = (params: {
     nodes: NodeType[];
     edges: EdgeType[];
@@ -298,6 +299,8 @@ declare const NodeRenderer: <NodeType extends Node = Node>(props: NodeRendererPr
 type PaneProps = PaneEvents & {
     readonly panOnDrag?: boolean | number[];
     readonly selectionOnDrag?: boolean;
+    readonly paneClickDistance?: number;
+    readonly autoPanOnSelection?: boolean;
     readonly onSelectionStart?: (event: PointerEvent) => void;
     readonly onSelectionEnd?: (event: PointerEvent) => void;
 };
@@ -328,8 +331,10 @@ type ZoomProps = {
     readonly zoomOnDoubleClick: boolean;
     readonly zoomOnPinch: boolean;
     readonly panOnScroll: boolean;
+    readonly panOnScrollSpeed: number;
     readonly panOnDrag: boolean | number[];
     readonly paneClickDistance: number;
+    readonly selectionOnDrag?: boolean;
 };
 declare const Zoom: (props: ParentProps<ZoomProps>) => solid_js.JSX.Element;
 
@@ -513,6 +518,19 @@ type ControlsProps = {
 } & Omit<JSX.HTMLAttributes<HTMLDivElement>, "style">;
 declare const Controls: (props: ParentProps<ControlsProps>) => JSX.Element;
 
+type EdgeToolbarProps = EdgeToolbarBaseProps & {
+    /** If `true`, clicking the toolbar selects the edge it belongs to. */
+    readonly selectEdgeOnClick?: boolean;
+} & Omit<JSX.HTMLAttributes<HTMLDivElement>, "style">;
+/**
+ * The `<EdgeToolbar />` component renders a toolbar or tooltip for an edge.
+ * It must be used inside a custom edge component. By default it is only
+ * visible when the edge is selected; pass `isVisible` to control it manually.
+ *
+ * The toolbar does not scale with the viewport so that its content is always legible.
+ */
+declare const EdgeToolbar: (props: ParentProps<EdgeToolbarProps>) => JSX.Element;
+
 type GetMiniMapNodeAttribute<NodeType extends Node> = (node: NodeType) => string;
 type MiniMapProps<NodeType extends Node> = Omit<JSX.HTMLAttributes<HTMLDivElement>, "style"> & {
     /** Background color of minimap */
@@ -819,7 +837,7 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
      * You can pass `null` to use the CSS variable `--xy-edge-stroke` for the marker color.
      * @example "#b1b1b7"
      */
-    readonly defaultMarkerColor?: string;
+    readonly defaultMarkerColor?: string | null;
     /**
      * Controls if all nodes should be draggable
      * @default true
@@ -830,6 +848,11 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
      * @default true
      */
     readonly autoPanOnNodeFocus?: boolean;
+    /**
+     * When `true`, the viewport will pan when a drag selection approaches the edges of the flow container.
+     * @default true
+     */
+    readonly autoPanOnSelection?: boolean;
     /**
      * Controls if all nodes should be connectable to each other
      * @default true
@@ -959,6 +982,14 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
      * @default true
      */
     readonly elevateNodesOnSelect?: boolean;
+    /**
+     * Controls how z-indexes are calculated for nodes and edges.
+     * 'auto' automatically manages z-indexing for selections and sub flows,
+     * 'basic' manages z-indexing for selections only, and
+     * 'manual' does not apply any automatic z-indexing.
+     * @default "basic"
+     */
+    readonly zIndexMode?: ZIndexMode;
     /**
      * Enabling this option will raise the z-index of edges when they are selected,
      * or when the connected nodes are selected.
@@ -1013,7 +1044,7 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
      * before doing so.
      */
     readonly proOptions?: ProOptions;
-    readonly isValidConnection?: IsValidConnection;
+    readonly isValidConnection?: IsValidConnection<EdgeType>;
     /** This event handler is called when the user begins to pan or zoom the viewport */
     readonly onMoveStart?: OnMoveStart;
     /** This event handler is called when the user pans or zooms the viewport */
@@ -1049,7 +1080,7 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
     /** This event gets fired when a user starts to reconnect an edge */
     readonly onReconnectStart?: OnReconnectStart<EdgeType>;
     /** This event gets fired when a user stops reconnecting an edge */
-    readonly onReconnectEnd?: OnReconnectEnd<EdgeType>;
+    readonly onReconnectEnd?: OnReconnectEnd<NodeType, EdgeType>;
     /** This handler gets called when an edge is reconnected. You can use it to modify the edge before the update is applied. */
     readonly onBeforeReconnect?: OnBeforeReconnect<EdgeType>;
     /** A connection is started by clicking on a handle */
@@ -1249,6 +1280,17 @@ type NodesInput<TUserNodeTypes extends NodeTypes> = {
  */
 declare const createNodeStore: <TUserNodeTypes extends NodeTypes = Record<string, never>>(nodes: NodesInput<TUserNodeTypes>[]) => readonly [Store<NodesInput<TUserNodeTypes>[]>, SetStoreFunction<NodesInput<TUserNodeTypes>[]>];
 
+/**
+ * Hook for receiving the current color mode class ('dark' or 'light').
+ *
+ * When the flow's `colorMode` prop is set to `"system"`, this resolves to the
+ * user's current system preference.
+ *
+ * @public
+ * @returns an accessor for the current color mode class
+ */
+declare function useColorMode(): () => ColorModeClass;
+
 /**
  * Hook for receiving the current connection.
  *
@@ -1281,6 +1323,26 @@ declare function useViewport(): () => _xyflow_system.Viewport;
 
 declare function useHandleEdgeSelect(): (id: string) => void;
 
+/**
+ * Hook for seeing if all nodes have been measured.
+ *
+ * Returns `false` until every non-hidden node has been rendered and measured.
+ * Useful for running layouting or fitView logic that depends on node dimensions.
+ *
+ * @public
+ * @returns an accessor that indicates whether the nodes are initialized
+ */
+declare function useNodesInitialized(): () => boolean;
+/**
+ * Hook for seeing if the viewport is initialized.
+ *
+ * Returns `true` once the pan/zoom instance has been created for the flow.
+ *
+ * @public
+ * @returns an accessor that indicates whether the viewport is initialized
+ */
+declare function useViewportInitialized(): () => boolean;
+
 /**
  * Hook to get an internal node by id.
  *
@@ -1579,4 +1641,4 @@ declare function useSolidFlow<NodeType extends Node = Node, EdgeType extends Edg
  */
 declare function useUpdateNodeInternals(): UpdateNodeInternals;
 
-export { Background, type BackgroundProps, type BackgroundVariant, BaseEdge, BezierEdge, BezierEdgeInternal, type BezierEdgeProps, type BuiltInEdge, type BuiltInNode, type BuiltInNodeTypes, type ConnectionData, ConnectionLine, type ConnectionLineComponentProps, ControlButton, Controls, type DefaultEdgeOptions, DefaultNode, type DeleteEvents, type Edge, type EdgeConnection, type EdgeEvents, EdgeLabel, EdgeLabelRenderer, type EdgeProps, EdgeReconnectAnchor, type EdgeReconnectEvents, EdgeRenderer, type EdgeTypes, EdgeWrapper, type FitViewOptions, GroupNode, Handle, InputNode, type InternalNode, type KeyDefinition, type KeyDefinitionObject, type KeyModifier, Marker, MarkerDefinition, MiniMap, type Node, type NodeEvents, type NodeGraph, type NodeProps, NodeRenderer, NodeResizer, NodeSelection, type NodeSelectionEvents, NodeToolbar, type NodeToolbarProps, type NodeTypes, NodeWrapper, type OnBeforeDelete, type OnBeforeEdgeConnect, type OnBeforeReconnect, type OnDelete, type OnEdgeConnect, type OnEdgeCreate, type OnSelectionChange, OutputNode, Pane, type PaneEvents, Panel, ResizeControl, Selection, type ShortcutModifier, type ShortcutModifierDefinition, SmoothStepEdge, SmoothStepEdgeInternal, type SmoothStepEdgeProps, SolidFlow, SolidFlowProvider, StepEdge, StepEdgeInternal, type StepEdgeProps, StraightEdge, StraightEdgeInternal, type StraightEdgeProps, ViewportPortal, Zoom, createEdgeStore, createNodeStore, useConnection, useEdges, useHandleEdgeSelect, useInternalNode, useNodeConnections, useNodes, useNodesData, useSolidFlow, useUpdateNodeInternals, useViewport };
+export { Background, type BackgroundProps, type BackgroundVariant, BaseEdge, BezierEdge, BezierEdgeInternal, type BezierEdgeProps, type BuiltInEdge, type BuiltInNode, type BuiltInNodeTypes, type ConnectionData, ConnectionLine, type ConnectionLineComponentProps, ControlButton, Controls, type DefaultEdgeOptions, DefaultNode, type DeleteEvents, type Edge, type EdgeConnection, type EdgeEvents, EdgeLabel, EdgeLabelRenderer, type EdgeProps, EdgeReconnectAnchor, type EdgeReconnectEvents, EdgeRenderer, EdgeToolbar, type EdgeToolbarProps, type EdgeTypes, EdgeWrapper, type FitViewOptions, GroupNode, Handle, InputNode, type InternalNode, type KeyDefinition, type KeyDefinitionObject, type KeyModifier, Marker, MarkerDefinition, MiniMap, type Node, type NodeEvents, type NodeGraph, type NodeProps, NodeRenderer, NodeResizer, NodeSelection, type NodeSelectionEvents, NodeToolbar, type NodeToolbarProps, type NodeTypes, NodeWrapper, type OnBeforeDelete, type OnBeforeEdgeConnect, type OnBeforeReconnect, type OnDelete, type OnEdgeConnect, type OnEdgeCreate, type OnSelectionChange, OutputNode, Pane, type PaneEvents, Panel, ResizeControl, Selection, type ShortcutModifier, type ShortcutModifierDefinition, SmoothStepEdge, SmoothStepEdgeInternal, type SmoothStepEdgeProps, SolidFlow, SolidFlowProvider, StepEdge, StepEdgeInternal, type StepEdgeProps, StraightEdge, StraightEdgeInternal, type StraightEdgeProps, ViewportPortal, Zoom, createEdgeStore, createNodeStore, useColorMode, useConnection, useEdges, useHandleEdgeSelect, useInternalNode, useNodeConnections, useNodes, useNodesData, useNodesInitialized, useSolidFlow, useUpdateNodeInternals, useViewport, useViewportInitialized };