From b478fc6852a19f087007bc4e602777cf7b7e66d5 Mon Sep 17 00:00:00 2001 From: peterkogo Date: Tue, 16 Jan 2024 17:41:55 +0100 Subject: [PATCH] added typedocs for ReactFlowProps --- packages/react/src/types/component-props.ts | 331 +++++++++++++++++- .../src/lib/container/SvelteFlow/types.ts | 4 +- 2 files changed, 332 insertions(+), 3 deletions(-) diff --git a/packages/react/src/types/component-props.ts b/packages/react/src/types/component-props.ts index bdb6e529..6b11c734 100644 --- a/packages/react/src/types/component-props.ts +++ b/packages/react/src/types/component-props.ts @@ -51,118 +51,447 @@ import type { * @public */ export type ReactFlowProps = Omit, 'onError'> & { + /** An array of nodes to render in a controlled flow. + * @example + * const nodes = [ + * { + * id: 'node-1', + * type: 'input', + * data: { label: 'Node 1' }, + * position: { x: 250, y: 50 } + * } + * ]; + */ nodes?: Node[]; + /** An array of edges to render in a controlled flow. + * @example + * const edges = [ + * { + * id: 'edge-1-2', + * source: 'node-1', + * target: 'node-2', + * } + * ]; + */ edges?: Edge[]; + /** The initial nodes to render in an uncontrolled flow. */ defaultNodes?: Node[]; + /** The initial edges to render in an uncontrolled flow. */ defaultEdges?: Edge[]; + /** Defaults to be applied to all new edges that are added to the flow. + * + * Properties on a new edge will override these defaults if they exist. + * @example + * const defaultEdgeOptions = { + * type: 'customEdgeType', + * animated: true, + * interactionWidth: 10, + * data: { label: 'custom label' }, + * hidden: false, + * deletable: true, + * selected: false, + * focusable: true, + * markerStart: EdgeMarker.ArrowClosed, + * markerEnd: EdgeMarker.ArrowClosed, + * zIndex: 12, + * ariaLabel: 'custom aria label' + * } + */ defaultEdgeOptions?: DefaultEdgeOptions; + /** This event handler is called when a user clicks on a node */ onNodeClick?: NodeMouseHandler; + /** This event handler is called when a user double clicks on a node */ onNodeDoubleClick?: NodeMouseHandler; + /** This event handler is called when mouse of a user enters a node */ onNodeMouseEnter?: NodeMouseHandler; + /** This event handler is called when mouse of a user moves over a node */ onNodeMouseMove?: NodeMouseHandler; + /** This event handler is called when mouse of a user leaves a node */ onNodeMouseLeave?: NodeMouseHandler; + /** This event handler is called when a user right clicks on a node */ onNodeContextMenu?: NodeMouseHandler; + /** This event handler is called when a user starts to drag a node */ onNodeDragStart?: NodeDragHandler; + /** This event handler is called when a user drags a node */ onNodeDrag?: NodeDragHandler; + /** This event handler is called when a user stops dragging a node */ onNodeDragStop?: NodeDragHandler; + /** This event handler is called when a user clicks on an edge */ onEdgeClick?: (event: ReactMouseEvent, edge: Edge) => void; - onEdgeUpdate?: OnEdgeUpdateFunc; + /** This event handler is called when a user right clicks on an edge */ onEdgeContextMenu?: EdgeMouseHandler; + /** This event handler is called when mouse of a user enters an edge */ onEdgeMouseEnter?: EdgeMouseHandler; + /** This event handler is called when mouse of a user moves over an edge */ onEdgeMouseMove?: EdgeMouseHandler; + /** This event handler is called when mouse of a user leaves an edge */ onEdgeMouseLeave?: EdgeMouseHandler; + /** This event handler is called when a user double clicks on an edge */ onEdgeDoubleClick?: EdgeMouseHandler; onEdgeUpdateStart?: (event: ReactMouseEvent, edge: Edge, handleType: HandleType) => void; onEdgeUpdateEnd?: (event: MouseEvent | TouchEvent, edge: Edge, handleType: HandleType) => void; + onEdgeUpdate?: OnEdgeUpdateFunc; + /** This event handler is called when a Node is updated + * @example // Use NodesState hook to create edges and get onNodesChange handler + * import ReactFlow, { useNodesState } from '@xyflow/react'; + * const [edges, setNodes, onNodesChange] = useNodesState(initialNodes); + * + * return () + * @example // Use helper function to update edge + * import ReactFlow, { applyNodeChanges } from '@xyflow/react'; + * + * const onNodeChange = useCallback( + * (changes) => setNode((eds) => applyNodeChanges(changes, eds)), + * [], + * ); + * + * return () + */ onNodesChange?: OnNodesChange; + /** This event handler is called when a Edge is updated + * @example // Use EdgesState hook to create edges and get onEdgesChange handler + * import ReactFlow, { useEdgesState } from '@xyflow/react'; + * const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges); + * + * return () + * @example // Use helper function to update edge + * import ReactFlow, { applyEdgeChanges } from '@xyflow/react'; + * + * const onEdgesChange = useCallback( + * (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)), + * [], + * ); + * + * return () + */ onEdgesChange?: OnEdgesChange; + /** This event handler gets called when a Node is deleted */ onNodesDelete?: OnNodesDelete; + /** This event handler gets called when a Edge is deleted */ onEdgesDelete?: OnEdgesDelete; + /** This event handler gets called when a Node or Edge is deleted */ onDelete?: OnDelete; + /** This event handler gets called when a user starts to drag a selection box */ onSelectionDragStart?: SelectionDragHandler; + /** This event handler gets called when a user drags a selection box */ onSelectionDrag?: SelectionDragHandler; + /** This event handler gets called when a user stops dragging a selection box */ onSelectionDragStop?: SelectionDragHandler; onSelectionStart?: (event: ReactMouseEvent) => void; onSelectionEnd?: (event: ReactMouseEvent) => void; onSelectionContextMenu?: (event: ReactMouseEvent, nodes: Node[]) => void; + /** When a connection line is completed and two nodes are connected by the user, this event fires with the new connection. + * + * You can use the addEdge utility to convert the connection to a complete edge. + * @example // Use helper function to update edges onConnect + * import ReactFlow, { addEdge } from '@xyflow/react'; + * + * const onConnect = useCallback( + * (params) => setEdges((eds) => addEdge(params, eds)), + * [], + * ); + * + * return () + */ onConnect?: OnConnect; + /** This event handler gets called when a user starts to drag a connection line */ onConnectStart?: OnConnectStart; + /** This event handler gets called when a user stops dragging a connection line */ onConnectEnd?: OnConnectEnd; onClickConnectStart?: OnConnectStart; onClickConnectEnd?: OnConnectEnd; + /** This event handler gets called when a flow has finished initializing */ onInit?: OnInit; + /** This event handler is called while the user is either panning or zooming the viewport. */ onMove?: OnMove; + /** This event handler gets called when a user starts to pan or zoom the viewport */ onMoveStart?: OnMoveStart; + /** This event handler gets called when a user stops panning or zooming the viewport */ onMoveEnd?: OnMoveEnd; + /** This event handler gets called when a user changes group of selected elements in the flow */ onSelectionChange?: OnSelectionChangeFunc; + /** This event handler gets called when user scroll inside the pane */ onPaneScroll?: (event?: WheelEvent) => void; + /** This event handler gets called when user clicks inside the pane */ onPaneClick?: (event: ReactMouseEvent) => void; + /** This event handler gets called when user right clicks inside the pane */ onPaneContextMenu?: (event: ReactMouseEvent | MouseEvent) => void; + /** This event handler gets called when mouse enters the pane */ onPaneMouseEnter?: (event: ReactMouseEvent) => void; + /** This event handler gets called when mouse moves over the pane */ onPaneMouseMove?: (event: ReactMouseEvent) => void; + /** This event handler gets called when mouse leaves the pane */ onPaneMouseLeave?: (event: ReactMouseEvent) => void; + /** This handler gets called before the user deletes nodes or edges and provides a way to abort the deletion by returning false. */ onBeforeDelete?: OnBeforeDelete; + /** Custom node types to be available in a flow. + * + * React Flow matches a node's type to a component in the nodeTypes object. + * @example + * import CustomNode from './CustomNode'; + * + * const nodeTypes = { nameOfNodeType: CustomNode }; + */ nodeTypes?: NodeTypes; + /** Custom edge types to be available in a flow. + * + * React Flow matches an edge's type to a component in the edgeTypes object. + * @example + * import CustomEdge from './CustomEdge'; + * + * const edgeTypes = { nameOfEdgeType: CustomEdge }; + */ edgeTypes?: EdgeTypes; + /** nThe type of edge path to use for connection lines. + * + * Although created edges can be of any type, React Flow needs to know what type of path to render for the connection line before the edge is created! + */ connectionLineType?: ConnectionLineType; + /** Styles to be applied to the connection line */ connectionLineStyle?: CSSProperties; + /** React Component to be used as a connection line */ connectionLineComponent?: ConnectionLineComponent; + /** Styles to be applied to the container of the connection line */ connectionLineContainerStyle?: CSSProperties; + /** 'strict' connection mode will only allow you to connect source handles to target handles. + * + * 'loose' connection mode will allow you to connect handles of any type to one another. + * @default 'strict' + */ connectionMode?: ConnectionMode; + /** Pressing down this key deletes all selected nodes & edges. + * @default 'Backspace' + */ deleteKeyCode?: KeyCode | null; + /** If a key is set, you can pan the viewport while that key is held down even if panOnScroll is set to false. + * + * By setting this prop to null you can disable this functionality. + * @default 'Space' + */ selectionKeyCode?: KeyCode | null; + /** Select multiple elements with a selection box, without pressing down selectionKey */ selectionOnDrag?: boolean; + /** When set to "partial", when the user creates a selection box by click and dragging nodes that are only partially in the box are still selected. + * @default 'full' + */ selectionMode?: SelectionMode; + /** If a key is set, you can pan the viewport while that key is held down even if panOnScroll is set to false. + * + * By setting this prop to null you can disable this functionality. + * @default 'Space' + */ panActivationKeyCode?: KeyCode | null; + /** Pressing down this key you can select multiple elements by clicking. + * @default 'Meta' for macOS, "Ctrl" for other systems + */ multiSelectionKeyCode?: KeyCode | null; + /**If a key is set, you can zoom the viewport while that key is held down even if panOnScroll is set to false. + * + * By setting this prop to null you can disable this functionality. + * @default 'Meta' for macOS, "Ctrl" for other systems + * */ zoomActivationKeyCode?: KeyCode | null; + /** Set this prop to make the flow snap to the grid */ snapToGrid?: boolean; + /** Grid all nodes will snap to + * @example [20, 20] + */ snapGrid?: SnapGrid; + /** You can enable this optimisation to instruct Svelte Flow to only render nodes and edges that would be visible in the viewport. + * + * This might improve performance when you have a large number of nodes and edges but also adds an overhead. + * @default false + */ onlyRenderVisibleElements?: boolean; + /** Controls if all nodes should be draggable + * @default true + */ nodesDraggable?: boolean; + /** Controls if all nodes should be connectable to each other + * @default true + */ nodesConnectable?: boolean; + /** Controls if all nodes should be focusable + * @default true + */ nodesFocusable?: boolean; + /** Defines nodes relative position to its coordinates + * @example + * [0, 0] // default, top left + * [0.5, 0.5] // center + * [1, 1] // bottom right + */ nodeOrigin?: NodeOrigin; + /** Controls if all edges should be focusable + * @default true + */ edgesFocusable?: boolean; + /** Controls if all edges should be updateable + * @default true + */ edgesUpdatable?: boolean; + /** Controls if all elements should (nodes & edges) be selectable + * @default true + */ elementsSelectable?: boolean; selectNodesOnDrag?: boolean; + /** Enableing this prop allows users to pan the viewport by clicking and dragging. + * + * You can also set this prop to an array of numbers to limit which mouse buttons can activate panning. + * @example [0, 2] // allows panning with the left and right mouse buttons + * [0, 1, 2, 3, 4] // allows panning with all mouse buttons + */ panOnDrag?: boolean | number[]; + /** Minimum zoom level + * @default 0.1 + */ minZoom?: number; + /** Maximum zoom level + * @default 1 + */ maxZoom?: number; + /** Controlled viewport to be used instead of internal one */ viewport?: Viewport; + /** Sets the initial position and zoom of the viewport. + * + * If a default viewport is provided but fitView is enabled, the default viewport will be ignored. + * @example + * const initialViewport = { + * zoom: 0.5, + * position: { x: 0, y: 0 } + * }; + */ defaultViewport?: Viewport; + onViewportChange?: (viewport: Viewport) => void; + /** By default the viewport extends infinitely. You can use this prop to set a boundary. + * + * The first pair of coordinates is the top left boundary and the second pair is the bottom right. + * @example [[-1000, -10000], [1000, 1000]] + */ translateExtent?: CoordinateExtent; + /** Disabling this prop will allow the user to scroll the page even when their pointer is over the flow. + * @default true + */ preventScrolling?: boolean; + /** By default nodes can be placed on an infinite flow. You can use this prop to set a boundary. + * + * The first pair of coordinates is the top left boundary and the second pair is the bottom right. + * @example [[-1000, -10000], [1000, 1000]] + */ nodeExtent?: CoordinateExtent; + /** Color of edge markers + * @example "#b1b1b7" + */ defaultMarkerColor?: string; + /** Controls if the viewport should zoom by scrolling inside the container */ zoomOnScroll?: boolean; + /** Controls if the viewport should zoom by pinching on a touch screen */ zoomOnPinch?: boolean; + /** Controls if the viewport should pan by scrolling inside the container + * + * Can be limited to a specific direction with panOnScrollMode + */ panOnScroll?: boolean; + /** Controls how fast viewport should be panned on scroll. + * + * Use togther with panOnScroll prop. + */ panOnScrollSpeed?: number; + /** This prop is used to limit the direction of panning when panOnScroll is enabled. + * + * The "free" option allows panning in any direction. + * @default "free" + * @example "horizontal" | "vertical" + */ panOnScrollMode?: PanOnScrollMode; + /** Controls if the viewport should zoom by double clicking somewhere on the flow */ zoomOnDoubleClick?: boolean; edgeUpdaterRadius?: number; noDragClassName?: string; noWheelClassName?: string; noPanClassName?: string; + /** If set, initial viewport will show all nodes & edges */ fitView?: boolean; + /** Options to be used in combination with fitView + * @example + * const fitViewOptions = { + * padding: 0.1, + * includeHiddenNodes: false, + * minZoom: 0.1, + * maxZoom: 1, + * duration: 200, + * nodes: [{id: 'node-1'}, {id: 'node-2'}], // nodes to fit + * }; + */ fitViewOptions?: FitViewOptions; + /**The connectOnClick option lets you click or tap on a source handle to start a connection + * and then click on a target handle to complete the connection. + * + * If you set this option to false, users will need to drag the connection line to the target + * handle to create a connection. + */ connectOnClick?: boolean; + /** Set position of the attribution + * @default 'bottom-right' + * @example 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' + */ attributionPosition?: PanelPosition; + /** By default, we render a small attribution in the corner of your flows that links back to the project. + * + * Anyone is free to remove this attribution whether they're a Pro subscriber or not + * but we ask that you take a quick look at our {@link https://reactflow.dev/learn/troubleshooting/remove-attribution | removing attribution guide} + * before doing so. + */ proOptions?: ProOptions; + /** Enabling this option will raise the z-index of nodes when they are selected. + * @default true + */ elevateNodesOnSelect?: boolean; + /** Enabling this option will raise the z-index of edges when they are selected. + * @default true + */ elevateEdgesOnSelect?: boolean; disableKeyboardA11y?: boolean; + /** You can enable this prop to automatically pan the viewport while dragging a node. + * @default true + */ autoPanOnNodeDrag?: boolean; + /** You can enable this prop to automatically pan the viewport while dragging a node. + * @default true + */ autoPanOnConnect?: boolean; + /** You can enable this prop to automatically pan the viewport while making a new connection. + * @default true + */ connectionRadius?: number; + /** Ocassionally something may happen that causes Svelte Flow to throw an error. + * + * Instead of exploding your application, we log a message to the console and then call this event handler. + * You might use it for additional logging or to show a message to the user. + */ onError?: OnError; + /** This callback can be used to validate a new connection + * + * If you return false, the edge will not be added to your flow. + * If you have custom connection logic its preferred to use this callback over the isValidConnection prop on the handle component for performance reasons. + * @default (connection: Connection) => true + */ isValidConnection?: IsValidConnection; + /** With a threshold greater than zero you can control the distinction between node drag and click events. + * + * If threshold equals 1, you need to drag the node 1 pixel before a drag event is fired. + * @default 1 + */ nodeDragThreshold?: number; + /** Sets a fixed width for the flow */ width?: number; + /** Sets a fixed height for the flow */ height?: number; + /** Controls color scheme used for styling the flow + * @default 'system' + * @example 'system' | 'light' | 'dark' + */ colorMode?: ColorMode; }; diff --git a/packages/svelte/src/lib/container/SvelteFlow/types.ts b/packages/svelte/src/lib/container/SvelteFlow/types.ts index 00b1b87d..3fde2d89 100644 --- a/packages/svelte/src/lib/container/SvelteFlow/types.ts +++ b/packages/svelte/src/lib/container/SvelteFlow/types.ts @@ -78,7 +78,7 @@ export type SvelteFlowProps = DOMAttributes & { * @example * import CustomEdge from './CustomEdge.svelte'; * - * const edgeypes = { nameOfEdgeType: CustomEdge }; + * const edgeTypes = { nameOfEdgeType: CustomEdge }; */ edgeTypes?: EdgeTypes; /** Pressing down this key you can select multiple elements with a selection box. @@ -292,7 +292,7 @@ export type SvelteFlowProps = DOMAttributes & { * @example ConnectionLineType.Straight | ConnectionLineType.Default | ConnectionLineType.Step | ConnectionLineType.SmoothStep | ConnectionLineType.Bezier */ connectionLineType?: ConnectionLineType; - /**This callback can be used to validate a new connection + /** This callback can be used to validate a new connection * * If you return false, the edge will not be added to your flow. * If you have custom connection logic its preferred to use this callback over the isValidConnection prop on the handle component for performance reasons.