alighasami/xyflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(types): add tsdocs

Browse Source
This commit is contained in:
moklick
2025-02-11 17:57:21 +01:00
parent 7b0f96f017
commit 381ed2a5bf
34 changed files with 264 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
packages/react/src/additional-components/Background/types.ts
View File

@@ -1,11 +1,20 @@
import { CSSProperties } from 'react';
/**
* The three variants are exported as an enum for convenience. You can either import
* the enum and use it like `BackgroundVariant.Lines` or you can use the raw string
* value directly.
* @public
*/
export enum BackgroundVariant {
Lines = 'lines',
Dots = 'dots',
Cross = 'cross',
}
/**
* @expand
*/
export type BackgroundProps = {
id?: string;
/** Color of the pattern */

2
packages/react/src/additional-components/Controls/ControlButton.tsx
View File

@@ -4,7 +4,7 @@ import type { ControlButtonProps } from './types';
/**
* You can add buttons to the control panel by using the `<ControlButton />` component
*and pass it as a child to the [`<Controls />`](/api-reference/components/controls) component.
* and pass it as a child to the [`<Controls />`](/api-reference/components/controls) component.
*
* @public
* @example

5
packages/react/src/additional-components/Controls/Controls.tsx
View File

@@ -127,7 +127,7 @@ ControlsComponent.displayName = 'Controls';
/**
* The `<Controls />` component renders a small panel that contains convenient
*buttons to zoom in, zoom out, fit the view, and lock the viewport.
* buttons to zoom in, zoom out, fit the view, and lock the viewport.
*
* @public
* @example
@@ -143,8 +143,7 @@ ControlsComponent.displayName = 'Controls';
*}
*```
*
* @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button)
*component
* @remarks To extend or customise the controls, you can use the [`<ControlButton />`](/api-reference/components/control-button) component
*
*/
export const Controls = memo(ControlsComponent);

16
packages/react/src/additional-components/MiniMap/MiniMap.tsx
View File

@@ -113,16 +113,16 @@ function MiniMapComponent<NodeType extends Node = Node>({
const onSvgClick = onClick
? (event: MouseEvent) => {
const [x, y] = minimapInstance.current?.pointer(event) || [0, 0];
onClick(event, { x, y });
}
const [x, y] = minimapInstance.current?.pointer(event) || [0, 0];
onClick(event, { x, y });
}
: undefined;
const onSvgNodeClick = onNodeClick
? useCallback((event: MouseEvent, nodeId: string) => {
const node = store.getState().nodeLookup.get(nodeId)!;
onNodeClick(event, node);
}, [])
const node = store.getState().nodeLookup.get(nodeId)!;
onNodeClick(event, node);
}, [])
: undefined;
return (
@@ -180,8 +180,8 @@ MiniMapComponent.displayName = 'MiniMap';
/**
* The `<MiniMap />` component can be used to render an overview of your flow. It
*renders each node as an SVG element and visualizes where the current viewport is
*in relation to the rest of the flow.
* renders each node as an SVG element and visualizes where the current viewport is
* in relation to the rest of the flow.
*
* @public
* @example

5
packages/react/src/additional-components/MiniMap/types.ts
View File

@@ -58,6 +58,11 @@ export type MiniMapNodes<NodeType extends Node = Node> = Pick<
onClick?: (event: MouseEvent, nodeId: string) => void;
};
/**
* The props that are passed to the MiniMapNode component
*
* @public
*/
export type MiniMapNodeProps = {
id: string;
x: number;

2
packages/react/src/additional-components/NodeResizer/NodeResizer.tsx
View File

@@ -5,7 +5,7 @@ import type { NodeResizerProps } from './types';
/**
* The `<NodeResizer />` component can be used to add a resize functionality to your
*nodes. It renders draggable controls around the node to resize in all directions.
* nodes. It renders draggable controls around the node to resize in all directions.
* @public
*
* @example

7
packages/react/src/additional-components/NodeToolbar/NodeToolbar.tsx
View File

@@ -40,7 +40,7 @@ const storeSelector = (state: ReactFlowState) => ({
/**
* This component can render a toolbar or tooltip to one side of a custom node. This
*toolbar doesn't scale with the viewport so that the content is always visible.
* toolbar doesn't scale with the viewport so that the content is always visible.
*
* @public
* @example
@@ -70,9 +70,8 @@ const storeSelector = (state: ReactFlowState) => ({
*export default memo(CustomNode);
*```
* @remarks By default, the toolbar is only visible when a node is selected. If multiple
*nodes are selected it will not be visible to prevent overlapping toolbars or
*clutter. You can override this behavior by setting the `isVisible` prop to
*`true`.
* nodes are selected it will not be visible to prevent overlapping toolbars or
* clutter. You can override this behavior by setting the `isVisible` prop to `true`.
*/
export function NodeToolbar({
nodeId,

13
packages/react/src/components/EdgeLabelRenderer/index.tsx
View File

@@ -8,10 +8,9 @@ const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__e
/**
* Edges are SVG-based. If you want to render more complex labels you can use the
*`<EdgeLabelRenderer />` component to access a div based renderer. This component
*is a portal that renders the label in a `<div />` that is positioned on top of
*the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer)
*example.
* `<EdgeLabelRenderer />` component to access a div based renderer. This component
* is a portal that renders the label in a `<div />` that is positioned on top of
* the edges. You can see an example usage of the component in the [edge label renderer](/examples/edges/edge-label-renderer) example.
* @public
*
* @example
@@ -43,9 +42,9 @@ const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__e
*};
*```
*
*@remarks The `<EdgeLabelRenderer />` has no pointer events by default. If you want to
*add mouse interactions you need to set the style `pointerEvents: all` and add
*the `nopan` class on the label or the element you want to interact with.
* @remarks The `<EdgeLabelRenderer />` has no pointer events by default. If you want to
* add mouse interactions you need to set the style `pointerEvents: all` and add
* the `nopan` class on the label or the element you want to interact with.
*/
export function EdgeLabelRenderer({ children }: { children: ReactNode }) {
const edgeLabelRenderer = useStore(selector);

10
packages/react/src/components/Edges/BaseEdge.tsx
View File

@@ -6,8 +6,8 @@ import type { BaseEdgeProps } from '../../types';
/**
* The `<BaseEdge />` component gets used internally for all the edges. It can be
*used inside a custom edge and handles the invisible helper edge and the edge label
*for you.
* used inside a custom edge and handles the invisible helper edge and the edge label
* for you.
*
* @public
* @example
@@ -27,9 +27,9 @@ import type { BaseEdgeProps } from '../../types';
*```
*
* @remarks If you want to use an edge marker with the [`<BaseEdge />`](/api-reference/components/base-edge) component,
*you can pass the `markerStart` or `markerEnd` props passed to your custom edge
*through to the [`<BaseEdge />`](/api-reference/components/base-edge) component. You can see all the props
*passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
* you can pass the `markerStart` or `markerEnd` props passed to your custom edge
* through to the [`<BaseEdge />`](/api-reference/components/base-edge) component.
* You can see all the props passed to a custom edge by looking at the [`EdgeProps`](/api-reference/types/edge-props) type.
*/
export function BaseEdge({
path,

2
packages/react/src/components/Edges/EdgeText.tsx
View File

@@ -75,7 +75,7 @@ EdgeTextComponent.displayName = 'EdgeText';
/**
* You can use the `<EdgeText />` component as a helper component to display text
*within your custom edges.
* within your custom edges.
*
*@public
*

4
packages/react/src/components/Edges/SimpleBezierEdge.tsx
View File

@@ -31,8 +31,8 @@ function getControl({ pos, x1, y1, x2, y2 }: GetControlParams): [number, number]
/**
* The `getSimpleBezierPath` util returns everything you need to render a simple
*bezier edge between two nodes.
* @public
* bezier edge between two nodes.
* @public
*/
export function getSimpleBezierPath({
sourceX,

2
packages/react/src/components/Handle/index.tsx
View File

@@ -251,7 +251,7 @@ function HandleComponent(
/**
* The `<Handle />` component is used in your [custom nodes](/learn/customization/custom-nodes)
*to define connection points.
* to define connection points.
*
*@public
*

6
packages/react/src/components/Panel/index.tsx
View File

@@ -6,9 +6,9 @@ import { useStore } from '../../hooks/useStore';
import type { ReactFlowState } from '../../types';
/**
* The `<Panel />` component helps you position content above the viewport. It is
*used internally by the [`<MiniMap />`](/api-reference/components/minimap) and [`<Controls />`](/api-reference/components/controls)
*components.
* The `<Panel />` component helps you position content above the viewport.
* It is used internally by the [`<MiniMap />`](/api-reference/components/minimap)
* and [`<Controls />`](/api-reference/components/controls) components.
*
* @public
*

15
packages/react/src/components/ReactFlowProvider/index.tsx
View File

@@ -20,11 +20,10 @@ export type ReactFlowProviderProps = {
};
/**
* The `<ReactFlowProvider />` component is a
*[context provider](https://react.dev/learn/passing-data-deeply-with-context#) that
*makes it possible to access a flow's internal state outside of the
*[`<ReactFlow />`](/api-reference/react-flow) component. Many of the hooks we
*provide rely on this component to work.
* The `<ReactFlowProvider />` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context#)
* that makes it possible to access a flow's internal state outside of the
* [`<ReactFlow />`](/api-reference/react-flow) component. Many of the hooks we
* provide rely on this component to work.
* @public
*
* @example
@@ -50,9 +49,9 @@ export type ReactFlowProviderProps = {
*```
*
* @remarks If you're using a router and want your flow's state to persist across routes,
*it's vital that you place the `<ReactFlowProvider />` component _outside_ of
*your router. If you have multiple flows on the same page you will need to use a separate
*`<ReactFlowProvider />` for each flow.
* it's vital that you place the `<ReactFlowProvider />` component _outside_ of
* your router. If you have multiple flows on the same page you will need to use a separate
* `<ReactFlowProvider />` for each flow.
*/
export function ReactFlowProvider({
initialNodes: nodes,

7
packages/react/src/components/ViewportPortal/index.tsx
View File

@@ -7,9 +7,10 @@ import type { ReactFlowState } from '../../types';
const selector = (s: ReactFlowState) => s.domNode?.querySelector('.react-flow__viewport-portal');
/**
* The `<ViewportPortal />` component can be used to add components to the same viewport of the flow where nodes and edges are rendered.
*This is useful when you want to render your own components that are adhere to the same coordinate system as the nodes & edges and are also
*affected by zooming and panning
* The `<ViewportPortal />` component can be used to add components to the same viewport
* of the flow where nodes and edges are rendered. This is useful when you want to render
* your own components that are adhere to the same coordinate system as the nodes & edges
* and are also affected by zooming and panning
* @public
* @example
*

4
packages/react/src/container/ReactFlow/index.tsx
View File

@@ -302,8 +302,8 @@ function ReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
}
/**
* The `<ReactFlow />` component is the heart of your React Flow application. It
*renders your nodes and edges and handles user interaction
* The `<ReactFlow />` component is the heart of your React Flow application.
* It renders your nodes and edges and handles user interaction
*
* @public
*

4
packages/react/src/contexts/NodeIdContext.ts
View File

@@ -6,8 +6,8 @@ export const Consumer = NodeIdContext.Consumer;
/**
* You can use this hook to get the id of the node it is used inside. It is useful
*if you need the node's id deeper in the render tree but don't want to manually
*drill down the id as a prop.
* if you need the node's id deeper in the render tree but don't want to manually
* drill down the id as a prop.
*
* @public
* @returns id of the node

6
packages/react/src/hooks/useConnection.ts
View File

@@ -25,9 +25,9 @@ function getSelector<NodeType extends Node = Node, SelectorReturn = ConnectionSt
}
/**
* The `useConnection` hook returns the current connection when there is an active
*connection interaction. If no connection interaction is active, it returns null
*for every property. A typical use case for this hook is to colorize handles
*based on a certain condition (e.g. if the connection is valid or not).
* connection interaction. If no connection interaction is active, it returns null
* for every property. A typical use case for this hook is to colorize handles
* based on a certain condition (e.g. if the connection is valid or not).
*
* @public
* @example

2
packages/react/src/hooks/useEdges.ts
View File

@@ -7,7 +7,7 @@ const edgesSelector = (state: ReactFlowState) => state.edges;
/**
* This hook returns an array of the current edges. Components that use this hook
*will re-render **whenever any edge changes**.
* will re-render **whenever any edge changes**.
*
* @public
* @returns An array of edges

6
packages/react/src/hooks/useInternalNode.ts
View File

@@ -5,9 +5,9 @@ import { useStore } from './useStore';
import type { InternalNode, Node } from '../types';
/**
* This hook returns the internal representation of a specific node. Components that use this hook
*will re-render **whenever the node changes**, including when a node is selected
*or moved.
* This hook returns the internal representation of a specific node.
* Components that use this hook will re-render **whenever the node changes**,
* including when a node is selected or moved.
*
* @public
* @param id - id of the node

2
packages/react/src/hooks/useKeyPress.ts
View File

@@ -14,7 +14,7 @@ const defaultDoc = typeof document !== 'undefined' ? document : null;
/**
* This hook lets you listen for specific key codes and tells you whether they are
*currently pressed or not.
* currently pressed or not.
*
* @public
* @param param.keyCode - The key code (string or array of strings) to use

4
packages/react/src/hooks/useNodes.ts
View File

@@ -7,8 +7,8 @@ const nodesSelector = (state: ReactFlowState) => state.nodes;
/**
* This hook returns an array of the current nodes. Components that use this hook
*will re-render **whenever any node changes**, including when a node is selected
*or moved.
* will re-render **whenever any node changes**, including when a node is selected
* or moved.
*
* @public
* @returns An array of nodes

22
packages/react/src/hooks/useNodesEdgesState.ts
View File

@@ -5,8 +5,8 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
/**
* This hook makes it easy to prototype a controlled flow where you manage the
*state of nodes and edges outside the `ReactFlowInstance`. You can think of it
*like React's `useState` hook with an additional helper callback.
* state of nodes and edges outside the `ReactFlowInstance`. You can think of it
* like React's `useState` hook with an additional helper callback.
*
* @public
* @param initialNodes
@@ -34,10 +34,10 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
*}
*```
*
*@remarks This hook was created to make prototyping easier and our documentation
*examples clearer. Although it is OK to use this hook in production, in
*practice you may want to use a more sophisticated state management solution
*like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
* @remarks This hook was created to make prototyping easier and our documentation
* examples clearer. Although it is OK to use this hook in production, in
* practice you may want to use a more sophisticated state management solution
* like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
*
*/
export function useNodesState<NodeType extends Node>(
@@ -54,8 +54,8 @@ export function useNodesState<NodeType extends Node>(
/**
* This hook makes it easy to prototype a controlled flow where you manage the
*state of nodes and edges outside the `ReactFlowInstance`. You can think of it
*like React's `useState` hook with an additional helper callback.
* state of nodes and edges outside the `ReactFlowInstance`. You can think of it
* like React's `useState` hook with an additional helper callback.
*
* @public
* @param initialEdges
@@ -84,9 +84,9 @@ export function useNodesState<NodeType extends Node>(
*```
*
* @remarks This hook was created to make prototyping easier and our documentation
*examples clearer. Although it is OK to use this hook in production, in
*practice you may want to use a more sophisticated state management solution
*like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
* examples clearer. Although it is OK to use this hook in production, in
* practice you may want to use a more sophisticated state management solution
* like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
*
*/
export function useEdgesState<EdgeType extends Edge = Edge>(

12
packages/react/src/hooks/useStore.ts
View File

@@ -10,8 +10,8 @@ const zustandErrorMessage = errorMessages['error001']();
/**
* This hook can be used to subscribe to internal state changes of the React Flow
*component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
*state management library, so you should check out their docs for more details.
* component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
* state management library, so you should check out their docs for more details.
*
* @public
* @param selector
@@ -24,8 +24,8 @@ const zustandErrorMessage = errorMessages['error001']();
* ```
*
* @remarks This hook should only be used if there is no other way to access the internal
*state. For many of the common use cases, there are dedicated hooks available
*such as {@link useReactFlow}, {@link useViewport}, etc.
* state. For many of the common use cases, there are dedicated hooks available
* such as {@link useReactFlow}, {@link useViewport}, etc.
*/
function useStore<StateSlice = unknown>(
selector: (state: ReactFlowState) => StateSlice,
@@ -51,8 +51,8 @@ function useStore<StateSlice = unknown>(
* ```
*
* @remarks This hook should only be used if there is no other way to access the internal
*state. For many of the common use cases, there are dedicated hooks available
*such as {@link useReactFlow}, {@link useViewport}, etc.
* state. For many of the common use cases, there are dedicated hooks available
* such as {@link useReactFlow}, {@link useViewport}, etc.
*/
function useStoreApi<NodeType extends Node = Node, EdgeType extends Edge = Edge>() {
const store = useContext(StoreContext) as UseBoundStoreWithEqualityFn<

23
packages/react/src/types/edges.ts
View File

@@ -19,6 +19,9 @@ import type {
import { EdgeTypes, InternalNode, Node } from '.';
/**
* @inline
*/
export type EdgeLabelOptions = {
label?: string | ReactNode;
labelStyle?: CSSProperties;
@@ -29,7 +32,8 @@ export type EdgeLabelOptions = {
};
/**
* The Edge type is mainly used for the `edges` that get passed to the ReactFlow component
* An `Edge` is the complete description with everything React Flow needs
*to know in order to render it.
* @public
*/
export type Edge<
@@ -91,6 +95,12 @@ export type EdgeWrapperProps<EdgeType extends Edge = Edge> = {
disableKeyboardA11y?: boolean;
};
/**
* Many properties on an [`Edge`](/api-reference/types/edge) are optional. When a new edge is created,
*the properties that are not provided will be filled in with the default values
*passed to the `defaultEdgeOptions` prop of the [`<ReactFlow />`](/api-reference/react-flow#defaultedgeoptions)
*component.
*/
export type DefaultEdgeOptions = DefaultEdgeOptionsBase<Edge>;
export type EdgeTextProps = SVGAttributes<SVGElement> &
@@ -100,8 +110,10 @@ export type EdgeTextProps = SVGAttributes<SVGElement> &
};
/**
* Custom edge component props
* When you implement a custom edge it is wrapped in a component that enables some
*basic functionality. The `EdgeProps` type is the props that are passed to this.
* @public
* @expand
*/
export type EdgeProps<EdgeType extends Edge = Edge> = Pick<
EdgeType,
@@ -185,6 +197,13 @@ export type SimpleBezierEdgeProps = EdgeComponentProps;
export type OnReconnect<EdgeType extends Edge = Edge> = (oldEdge: EdgeType, newConnection: Connection) => void;
/**
* If you want to render a custom component for connection lines, you can set the
*`connectionLineComponent` prop on the [`<ReactFlow />`](/api-reference/react-flow#connection-connectionLineComponent)
*component. The `ConnectionLineComponentProps` are passed to your custom component.
*
* @public
*/
export type ConnectionLineComponentProps<NodeType extends Node = Node> = {
connectionLineStyle?: CSSProperties;
connectionLineType: ConnectionLineType;

11
packages/react/src/types/general.ts
View File

@@ -64,12 +64,23 @@ export type OnSelectionChangeParams = {
export type OnSelectionChangeFunc = (params: OnSelectionChangeParams) => void;
export type FitViewParams<NodeType extends Node = Node> = FitViewParamsBase<NodeType>;
/**
* When calling [`fitView`](/api-reference/types/react-flow-instance#fitview) these options
* can be used to customize the behaviour. For example, the `duration` option can be used to
* transform the viewport smoothly over a given amount of time.
*
* @public
*/
export type FitViewOptions<NodeType extends Node = Node> = FitViewOptionsBase<NodeType>;
export type FitView = (fitViewOptions?: FitViewOptions) => Promise<boolean>;
export type OnInit<NodeType extends Node = Node, EdgeType extends Edge = Edge> = (
reactFlowInstance: ReactFlowInstance<NodeType, EdgeType>
) => void;
/**
* @inline
*/
export type ViewportHelperFunctions = {
/**
* Zooms viewport in by 1.2.

8
packages/react/src/types/instance.ts
View File

@@ -217,6 +217,14 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
}) => NodeConnection[];
};
/**
* The `ReactFlowInstance` provides a collection of methods to query and manipulate
*the internal state of your flow. You can get an instance by using the
*[`useReactFlow`](/api-reference/hooks/use-react-flow) hook or attaching a listener to the
*[`onInit`](/api-reference/react-flow#event-oninit) event.
*
* @public
*/
export type ReactFlowInstance<NodeType extends Node = Node, EdgeType extends Edge = Edge> = GeneralHelpers<
NodeType,
EdgeType

38
packages/react/src/types/nodes.ts
View File

@@ -4,7 +4,9 @@ import type { CoordinateExtent, NodeBase, OnError, NodeProps as NodePropsBase, I
import { NodeTypes } from './general';
/**
* The node data structure that gets used for the nodes prop.
* The `Node` type represents everything React Flow needs to know about a given node.
* Many of these properties can be manipulated both by React Flow or by you, but
* some such as `width` and `height` should be considered read-only.
* @public
*/
export type Node<
@@ -18,9 +20,10 @@ export type Node<
};
/**
* The node data structure that gets used for internal nodes.
* There are some data structures added under node.internal
* that are needed for tracking some properties
* The `InternalNode` type is identical to the base [`Node`](/api-references/types/node)
* type but is extended with some additional properties used internall by React
* Flow. Some functions and callbacks that return nodes may return an `InternalNode`.
*
* @public
*/
export type InternalNode<NodeType extends Node = Node> = InternalNodeBase<NodeType>;
@@ -60,4 +63,31 @@ export type BuiltInNode =
| Node<{ label: string }, 'input' | 'output' | 'default'>
| Node<Record<string, never>, 'group'>;
/**
* When you implement a [custom node](/learn/customization/custom-nodes) it is
* wrapped in a component that enables basic functionality like selection and
* dragging. Your custom node receives `NodeProps` as props.
*
* @public
* @example
* ```tsx
*import { useState } from 'react';
*import { NodeProps, Node } from '@xyflow/react';
*
*export type CounterNode = Node<{ initialCount?: number }, 'counter'>;
*
*export default function CounterNode(props: NodeProps<CounterNode>) {
* const [count, setCount] = useState(props.data?.initialCount ?? 0);
*
* return (
* <div>
* <p>Count: {count}</p>
* <button className="nodrag" onClick={() => setCount(count + 1)}>
* Increment
* </button>
* </div>
* );
*}
*```
*/
export type NodeProps<NodeType extends Node = Node> = NodePropsBase<NodeType>;

14
packages/react/src/utils/general.ts
View File

@@ -4,9 +4,10 @@ import { isNodeBase, isEdgeBase } from '@xyflow/system';
import type { Edge, Node } from '../types';
/**
* Test whether an object is useable as an [`Node`](/api-reference/types/node). In TypeScript
*this is a type guard that will narrow the type of whatever you pass in to
*[`Node`](/api-reference/types/node) if it returns `true`.
* Test whether an object is useable as an [`Node`](/api-reference/types/node).
* In TypeScript this is a type guard that will narrow the type of whatever you pass in to
* [`Node`](/api-reference/types/node) if it returns `true`.
*
* @public
* @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Node if it returns true
* @param element - The element to test
@@ -25,9 +26,10 @@ export const isNode = <NodeType extends Node = Node>(element: unknown): element
isNodeBase<NodeType>(element);
/**
* Test whether an object is useable as an [`Edge`](/api-reference/types/edge). In TypeScript
*this is a type guard that will narrow the type of whatever you pass in to
*[`Edge`](/api-reference/types/edge) if it returns `true`.
* Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
* In TypeScript this is a type guard that will narrow the type of whatever you pass in to
* [`Edge`](/api-reference/types/edge) if it returns `true`.
*
* @public
* @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Edge if it returns true
* @param element - The element to test

4
packages/svelte/src/lib/types/edges.ts
View File

@@ -11,7 +11,9 @@ import type {
import type { Node } from '$lib/types';
/**
* The Edge type is mainly used for the `edges` that get passed to the SvelteFlow component.
* An `Edge` is the complete description with everything React Flow needs
*to know in order to render it.
* @public
*/
export type Edge<
EdgeData extends Record<string, unknown> = Record<string, unknown>,

6
packages/system/src/types/edges.ts
View File

@@ -103,6 +103,12 @@ export type EdgeMarker = {
export type EdgeMarkerType = string | EdgeMarker;
/**
* Edges may optionally have a marker on either end. The MarkerType type enumerates
* the options available to you when configuring a given marker.
*
* @public
*/
export enum MarkerType {
Arrow = 'arrow',
ArrowClosed = 'arrowclosed',

58
packages/system/src/types/general.ts
View File

@@ -28,8 +28,8 @@ export type FitBounds = (bounds: Rect, options?: FitBoundsOptions) => Promise<bo
/**
* The `Connection` type is the basic minimal description of an [`Edge`](/api-reference/types/edge)
*between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
*a `Connection` to an [`Edge`](/api-reference/types/edge).
* between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
* a `Connection` to an [`Edge`](/api-reference/types/edge).
*
* @public
*/
@@ -40,15 +40,28 @@ export type Connection = {
targetHandle: string | null;
};
// TODO: remove in next version
/**
* The `HandleConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
*/
export type HandleConnection = Connection & {
edgeId: string;
};
/**
* The `NodeConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
*
*/
export type NodeConnection = Connection & {
edgeId: string;
};
/**
* The `ConnectionMode` is used to set the mode of connection between nodes.
* The `Strict` mode is the default one and only allows source to target edges.
* `Loose` mode allows source to source and target to target edges as well.
*
* @public
*/
export enum ConnectionMode {
Strict = 'strict',
Loose = 'loose',
@@ -66,6 +79,9 @@ export type OnConnectEnd = (event: MouseEvent | TouchEvent, connectionState: Fin
export type IsValidConnection = (edge: EdgeBase | Connection) => boolean;
/**
* @inline
*/
export type FitViewParamsBase<NodeType extends NodeBase> = {
nodes: Map<string, InternalNodeBase<NodeType>>;
width: number;
@@ -75,6 +91,9 @@ export type FitViewParamsBase<NodeType extends NodeBase> = {
maxZoom: number;
};
/**
* @inline
*/
export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
padding?: number;
includeHiddenNodes?: boolean;
@@ -84,6 +103,17 @@ export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
nodes?: (NodeType | { id: string })[];
};
/**
* Internally, React Flow maintains a coordinate system that is independent of the
* rest of the page. The `Viewport` type tells you where in that system your flow
* is currently being display at and how zoomed in or out it is.
*
* @public
* @remarks A `Transform` has the same properties as the viewport, but they represent
* different things. Make sure you don't get them muddled up or things will start
* to look weird!
*
*/
export type Viewport = {
x: number;
y: number;
@@ -94,12 +124,23 @@ export type KeyCode = string | Array<string>;
export type SnapGrid = [number, number];
/**
* This enum is used to set the different modes of panning the viewport when the
* user scrolls. The `Free` mode allows the user to pan in any direction by scrolling
* with a device like a trackpad. The `Vertical` and `Horizontal` modes restrict
* scroll panning to only the vertical or horizontal axis, respectively.
*
* @public
*/
export enum PanOnScrollMode {
Free = 'free',
Vertical = 'vertical',
Horizontal = 'horizontal',
}
/**
* @inline
*/
export type ViewportHelperFunctionOptions = {
duration?: number;
};
@@ -120,6 +161,14 @@ export type D3ZoomHandler = (this: Element, event: any, d: unknown) => void;
export type UpdateNodeInternals = (nodeId: string | string[]) => void;
/**
* This type is mostly used to help position things on top of the flow viewport. For
* example both the [`<MiniMap />`](/api-reference/components/minimap) and
* [`<Controls />`](/api-reference/components/controls) components take a `position`
* prop of this type.
*
* @public
*/
export type PanelPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
export type ProOptions = {
@@ -183,7 +232,8 @@ export type ConnectionInProgress<NodeType extends InternalNodeBase = InternalNod
};
/**
* The `ConnectionState` type bundles all information about an ongoing connection. It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
* The `ConnectionState` type bundles all information about an ongoing connection.
* It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
*
* @public
*/

17
packages/system/src/types/nodes.ts
View File

@@ -4,6 +4,7 @@ import { Optional } from '../utils/types';
/**
* Framework independent node data structure.
*
* @inline
* @typeParam NodeData - type of the node data
* @typeParam NodeType - type of the node
*/
@@ -80,7 +81,7 @@ export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType &
z: number;
/**
* Holds a reference to the original node object provided by the user.
* Used as an optimization to avoid certain operations.
* Used as an optimization to avoid certain operations.
*/
userNode: NodeType;
handleBounds?: NodeHandleBounds;
@@ -89,7 +90,7 @@ export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType &
};
/**
* The node data structure that gets used for the nodes prop.
* The node data structure that gets used for the custom nodes props.
*
* @public
*/
@@ -141,10 +142,22 @@ export type NodeDragItem = {
expandParent?: boolean;
};
/**
* The origin of a Node determines how it is placed relative to its own coordinates.
* `[0, 0]` places it at the top left corner, `[0.5, 0.5]` right in the center and
* `[1, 1]` at the bottom right of its position.
*
* @public
*/
export type NodeOrigin = [number, number];
export type OnSelectionDrag = (event: MouseEvent, nodes: NodeBase[]) => void;
/**
* Type for the handles of a node
*
* @public
*/
export type NodeHandle = Omit<Optional<Handle, 'width' | 'height'>, 'nodeId'>;
export type Align = 'center' | 'start' | 'end';

18
packages/system/src/types/utils.ts
View File

@@ -1,3 +1,10 @@
/**
* While [`PanelPosition`](/api-reference/types/panel-position) can be used to place a
* component in the corners of a container, the `Position` enum is less precise and used
* primarily in relation to edges and handles.
*
* @public
*/
export enum Position {
Left = 'left',
Top = 'top',
@@ -12,6 +19,11 @@ export const oppositePosition = {
[Position.Bottom]: Position.Top,
};
/**
* All positions are stored in an object with x and y coordinates.
*
* @public
*/
export type XYPosition = {
x: number;
y: number;
@@ -35,12 +47,12 @@ export type Transform = [number, number, number];
/**
* A coordinate extent represents two points in a coordinate system: one in the top
*left corner and one in the bottom right corner. It is used to represent the
*bounds of nodes in the flow or the bounds of the viewport.
* left corner and one in the bottom right corner. It is used to represent the
* bounds of nodes in the flow or the bounds of the viewport.
*
* @public
*
* @remarks Props that expect a `CoordinateExtent` usually default to `[[-∞, -∞], [+∞, +∞]]`
*to represent an unbounded extent.
* to represent an unbounded extent.
*/
export type CoordinateExtent = [[number, number], [number, number]];