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

chore(svelte): cleanup tsdoc annotations

Browse Source
This commit is contained in:
moklick
2025-05-06 23:25:18 +02:00
parent ca60c91906
commit bf7594cd3e
10 changed files with 120 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
packages/svelte/src/lib/container/SvelteFlow/types.ts
View File

@@ -50,13 +50,12 @@ export type SvelteFlowProps<
NodeSelectionEvents<NodeType> &
EdgeEvents<EdgeType> &
PaneEvents & {
/** The id of the flow
*
* This is necessary if you want to render multiple flows.
* @optional
/**
* The id of the flow. This is necessary if you want to render multiple flows.
*/
id?: string;
/** An array of nodes to render in a controlled flow.
/**
* An array of nodes to render in a flow.
* @example
* const nodes = $state.raw([
* {
@@ -68,7 +67,8 @@ export type SvelteFlowProps<
* ]);
*/
nodes?: NodeType[];
/** An array of edges to render in a controlled flow.
/**
* An array of edges to render in a flow.
* @example
* const edges = $state.raw([
* {
@@ -79,8 +79,8 @@ export type SvelteFlowProps<
* ]);
*/
edges?: EdgeType[];
/** Custom node types to be available in a flow.
*
/**
* Custom node types to be available in a flow.
* Svelte Flow matches a node's type to a component in the nodeTypes object.
* @example
* import CustomNode from './CustomNode.svelte';
@@ -88,8 +88,8 @@ export type SvelteFlowProps<
* const nodeTypes = { nameOfNodeType: CustomNode };
*/
nodeTypes?: NodeTypes;
/** Custom edge types to be available in a flow.
*
/**
* Custom edge types to be available in a flow.
* Svelte Flow matches an edge's type to a component in the edgeTypes object.
* @example
* import CustomEdge from './CustomEdge.svelte';
@@ -123,7 +123,8 @@ export type SvelteFlowProps<
zoomActivationKey?: KeyDefinition | KeyDefinition[] | null;
/** If set, initial viewport will show all nodes & edges */
fitView?: boolean;
/** Options to be used in combination with fitView
/**
* Options to be used in combination with fitView
* @example
* const fitViewOptions = {
* padding: 0.1,
@@ -135,20 +136,23 @@ export type SvelteFlowProps<
* };
*/
fitViewOptions?: FitViewOptions<NodeType>;
/** Defines nodes relative position to its coordinates
/**
* Defines nodes relative position to its coordinates
* @default [0, 0]
* @example
* [0, 0] // default, top left
* [0.5, 0.5] // center
* [1, 1] // bottom right
*/
nodeOrigin?: NodeOrigin;
/** With a threshold greater than zero you can control the distinction between node drag and click events.
*
/**
* 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;
/** Distance that the mouse can move between mousedown/up that will trigger a click
/**
* Distance that the mouse can move between mousedown/up that will trigger a click
* @default 0
*/
paneClickDistance?: number;
@@ -164,9 +168,10 @@ export type SvelteFlowProps<
* @default 2
*/
maxZoom?: number;
/** Sets the initial position and zoom of the 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.
* @default { zoom: 1, position: { x: 0, y: 0 } }
* @example
* const initialViewport = {
* zoom: 0.5,
@@ -176,12 +181,13 @@ export type SvelteFlowProps<
initialViewport?: Viewport;
/** Custom viewport to be used instead of internal one */
viewport?: Viewport;
/** The radius around a handle where you drop a connection line to create a new edge.
/**
* The radius around a handle where you drop a connection line to create a new edge.
* @default 20
*/
connectionRadius?: number;
/** 'strict' connection mode will only allow you to connect source handles to target handles.
*
/**
* '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'
*/
@@ -192,7 +198,9 @@ export type SvelteFlowProps<
connectionLineStyle?: string;
/** Styles to be applied to the container of the connection line */
connectionLineContainerStyle?: string;
/** 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.
/**
* 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;
@@ -200,7 +208,8 @@ export type SvelteFlowProps<
* Controls if nodes should be automatically selected when being dragged
*/
selectNodesOnDrag?: boolean;
/** Grid all nodes will snap to
/**
* Grid all nodes will snap to
* @example [20, 20]
*/
snapGrid?: SnapGrid;
@@ -208,11 +217,13 @@ export type SvelteFlowProps<
* @example "#b1b1b7"
*/
defaultMarkerColor?: string;
/** Controls if all nodes should be draggable
/**
* Controls if all nodes should be draggable
* @default true
*/
nodesDraggable?: boolean;
/** Controls if all nodes should be connectable to each other
/**
* Controls if all nodes should be connectable to each other
* @default true
*/
nodesConnectable?: boolean;
@@ -232,91 +243,102 @@ export type SvelteFlowProps<
* @default true
*/
edgesFocusable?: boolean;
/** By default the viewport extends infinitely. You can use this prop to set a boundary.
*
/**
* 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.
* @default @default [[-∞, -∞], [+∞, +∞]]
* @example [[-1000, -10000], [1000, 1000]]
*/
translateExtent?: CoordinateExtent;
/** By default the nodes can be placed anywhere. You can use this prop to set a boundary.
*
/**
* By default the nodes can be placed anywhere. 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.
* @default [[-∞, -∞], [+∞, +∞]]
* @example [[-1000, -10000], [1000, 1000]]
*/
nodeExtent?: CoordinateExtent;
/** Disabling this prop will allow the user to scroll the page even when their pointer is over the flow.
/**
* Disabling this prop will allow the user to scroll the page even when their pointer is over the flow.
* @default true
*/
preventScrolling?: boolean;
/** Controls if the viewport should zoom by scrolling inside the container */
/**
* Controls if the viewport should zoom by scrolling inside the container.
* @default true
*/
zoomOnScroll?: boolean;
/** Controls if the viewport should zoom by double clicking somewhere on the flow */
/**
* Controls if the viewport should zoom by double clicking somewhere on the flow
* @default true
*/
zoomOnDoubleClick?: boolean;
/** Controls if the viewport should zoom by pinching on a touch screen */
/**
* Controls if the viewport should zoom by pinching on a touch screen
* @default true
*/
zoomOnPinch?: boolean;
/** Controls if the viewport should pan by scrolling inside the container
*
/**
* Controls if the viewport should pan by scrolling inside the container
* Can be limited to a specific direction with panOnScrollMode
* @default false
*/
panOnScroll?: boolean;
/** This prop is used to limit the direction of panning when panOnScroll is enabled.
*
/**
* 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;
/** Enableing this prop allows users to pan the viewport by clicking and dragging.
*
/**
* 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.
* @default true
* @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[];
/** Select multiple elements with a selection box, without pressing down selectionKey */
/**
* Select multiple elements with a selection box, without pressing down selectionKey.
* @default false
*/
selectionOnDrag?: boolean;
/** You can enable this optimisation to instruct Svelte Flow to only render nodes and edges that would be visible in the viewport.
*
/**
* 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;
/** You can enable this prop to automatically pan the viewport while making a new connection.
/**
* You can enable this prop to automatically pan the viewport while making a new connection.
* @default true
*/
autoPanOnConnect?: boolean;
/** You can enable this prop to automatically pan the viewport while dragging a node.
/**
* You can enable this prop to automatically pan the viewport while dragging a node.
* @default true
*/
autoPanOnNodeDrag?: boolean;
/** Set position of the attribution
/**
* 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.
*
/**
* 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;
/** Defaults to be applied to all new edges that are added to the flow.
*
/**
* 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,
* markerStart: EdgeMarker.ArrowClosed,
* markerEnd: EdgeMarker.ArrowClosed,
* zIndex: 12,
* ariaLabel: 'custom aria label'
* animated: true
* }
*/
defaultEdgeOptions?: DefaultEdgeOptions;
@@ -324,7 +346,8 @@ export type SvelteFlowProps<
width?: number;
/** Sets a fixed height for the flow */
height?: number;
/** Controls color scheme used for styling the flow
/**
* Controls color scheme used for styling the flow
* @default 'system'
* @example 'system' | 'light' | 'dark'
*/
@@ -341,13 +364,6 @@ export type SvelteFlowProps<
* @example ConnectionLineType.Straight | ConnectionLineType.Default | ConnectionLineType.Step | ConnectionLineType.SmoothStep | ConnectionLineType.Bezier
*/
connectionLineType?: ConnectionLineType;
/** 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
*/
/** Enabling this option will raise the z-index of nodes when they are selected.
* @default true
*/
@@ -385,15 +401,14 @@ export type SvelteFlowProps<
* @default "nopan"
*/
noPanClass?: string;
/** Toggles ability to make connections via clicking the handles */
clickConnect?: boolean;
/**
* 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.
*/
/** Toggles ability to make connections via clicking the handles */
clickConnect?: boolean;
isValidConnection?: IsValidConnection;
/** This event handler is called when the user begins to pan or zoom the viewport */
onmovestart?: OnMoveStart;
@@ -401,8 +416,8 @@ export type SvelteFlowProps<
onmove?: OnMove;
/** This event handler is called when the user stops panning or zooming the viewport */
onmoveend?: OnMoveEnd;
/** Ocassionally something may happen that causes Svelte Flow to throw an error.
*
/**
* 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.
*/

2
packages/svelte/src/lib/hooks/useConnection.svelte.ts
View File

@@ -6,7 +6,7 @@ import type { ConnectionState } from '@xyflow/system';
* Hook for receiving the current connection.
*
* @public
* @returns current connection as a readable store
* @returns Current connection as a signal
*/
export function useConnection(): { current: ConnectionState } {
const { connection } = $derived(useStore());

3
packages/svelte/src/lib/hooks/useInitialized.svelte.ts
View File

@@ -2,7 +2,8 @@ import { useStore } from '$lib/store';
/**
* Hook for seeing if nodes are initialized
* @returns - reactive nodesInitialized
* @returns A boolean that indicates if nodes are initialized
* @public
*/
export function useNodesInitialized() {
const { nodesInitialized } = $derived(useStore());

2
packages/svelte/src/lib/hooks/useInternalNode.svelte.ts
View File

@@ -6,7 +6,7 @@ import type { InternalNode } from '$lib/types';
*
* @public
* @param id - the node id
* @returns a readable with an internal node or undefined
* @returns An internal node or undefined
*/
export function useInternalNode(id: string): { current: InternalNode | undefined } {
const { nodeLookup, nodes } = $derived(useStore());

2
packages/svelte/src/lib/hooks/useNodeConnections.svelte.ts
View File

@@ -28,7 +28,7 @@ const initialConnections: NodeConnection[] = [];
* @param param.handleId - filter by handle id (this is only needed if the node has multiple handles of the same type)
* @param param.onConnect - gets called when a connection is established
* @param param.onDisconnect - gets called when a connection is removed
* @returns an array with connections
* @returns An array with connections
*/
export function useNodeConnections({
id,

2
packages/svelte/src/lib/hooks/useNodesData.svelte.ts
View File

@@ -8,7 +8,7 @@ import { useStore } from '$lib/store';
*
* @public
* @param nodeId - The id (or ids) of the node to get the data from
* @returns A readable store with an array of data objects
* @returns An array of data objects
*/
export function useNodesData<NodeType extends Node = Node>(
nodeId: string

6
packages/svelte/src/lib/hooks/useNodesEdgesViewport.svelte.ts
View File

@@ -6,7 +6,7 @@ import type { Viewport } from '@xyflow/system';
* Hook for getting the current nodes from the store.
*
* @public
* @returns reactive signal of the current edges
* @returns A reactive signal of the current nodes
*/
export function useNodes() {
const store = $derived(useStore());
@@ -30,7 +30,7 @@ export function useNodes() {
* Hook for getting the current edges from the store.
*
* @public
* @returns reactive signal of the current edges
* @returns A reactive signal of the current edges
*/
export function useEdges() {
const store = $derived(useStore());
@@ -54,7 +54,7 @@ export function useEdges() {
* Hook for getting the current viewport from the store.
*
* @public
* @returns reactive signal of the current viewport
* @returns A reactive signal of the current viewport
*/
export function useViewport() {
const store = $derived(useStore());

5
packages/svelte/src/lib/hooks/useSvelteFlow.svelte.ts
View File

@@ -26,11 +26,10 @@ import { derivedWarning } from './derivedWarning.svelte';
import { untrack } from 'svelte';
/**
* Hook for accessing the ReactFlow instance.
* Hook for accessing the SvelteFlow instance.
*
* @public
*
* @returns helper functions
* @returns A set of helper functions
*/
export function useSvelteFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): {
/**

8
packages/svelte/src/lib/hooks/useUpdateNodeInternals.svelte.ts
View File

@@ -2,10 +2,14 @@ import { useStore } from '$lib/store';
import { getContext } from 'svelte';
/**
* Hook for updating node internals.
* When you programmatically add or remove handles to a node or update a node's
* handle position, you need to let Svelte Flow know about it using this hook. This
* will update the internal dimensions of the node and properly reposition handles
* on the canvas if necessary.
*
* @public
* @returns function for updating node internals
* @returns A function for telling Svelte Flow to update the internal state of one or more nodes
* that you have changed programmatically.
*/
export function useUpdateNodeInternals(): (nodeId?: string | string[]) => void {
const { domNode, updateNodeInternals } = $derived(useStore());

16
packages/svelte/src/lib/types/events.ts
View File

@@ -28,29 +28,45 @@ export type NodeTargetEventWithPointer<T = PointerEvent, NodeType extends Node =
}) => void;
export type NodeEvents<NodeType extends Node = Node> = {
/** This event handler is called when a user clicks on a node. */
onnodeclick?: NodeEventWithPointer<MouseEvent | TouchEvent, NodeType>;
/** This event handler is called when a user right-clicks on a node. */
onnodecontextmenu?: NodeEventWithPointer<MouseEvent, NodeType>;
/** This event handler is called when a user drags a node. */
onnodedrag?: NodeTargetEventWithPointer<MouseEvent | TouchEvent, NodeType>;
/** This event handler is called when a user starts to drag a node. */
onnodedragstart?: NodeTargetEventWithPointer<MouseEvent | TouchEvent, NodeType>;
/** This event handler is called when a user stops dragging a node. */
onnodedragstop?: NodeTargetEventWithPointer<MouseEvent | TouchEvent, NodeType>;
/** This event handler is called when the pointer of a user enters a node. */
onnodepointerenter?: NodeEventWithPointer<PointerEvent, NodeType>;
/** This event handler is called when the pointer of a user leaves a node. */
onnodepointerleave?: NodeEventWithPointer<PointerEvent, NodeType>;
/** This event handler is called when the pointer of a user moves over a node. */
onnodepointermove?: NodeEventWithPointer<PointerEvent, NodeType>;
};
export type NodeSelectionEvents<NodeType extends Node = Node> = {
/** This event handler is called when a user right-clicks the selection box. */
onselectioncontextmenu?: NodesEventWithPointer<MouseEvent, NodeType>;
/** This event handler is called when a user clicks the selection box. */
onselectionclick?: NodesEventWithPointer<MouseEvent, NodeType>;
};
export type PaneEvents = {
/** This event handler is called when a user clicks the pane. */
onpaneclick?: ({ event }: { event: MouseEvent }) => void;
/** This event handler is called when a user right-clicks the pane. */
onpanecontextmenu?: ({ event }: { event: MouseEvent }) => void;
};
export type EdgeEvents<EdgeType extends Edge = Edge> = {
/** This event handler is called when a user clicks an edge. */
onedgeclick?: ({ edge, event }: { edge: EdgeType; event: MouseEvent }) => void;
/** This event handler is called when a user right-clicks an edge. */
onedgecontextmenu?: ({ edge, event }: { edge: EdgeType; event: MouseEvent }) => void;
/** This event handler is called when the pointer of a user enters an edge. */
onedgepointerenter?: ({ edge, event }: { edge: EdgeType; event: PointerEvent }) => void;
/** This event handler is called when the pointer of a user enters an edge. */
onedgepointerleave?: ({ edge, event }: { edge: EdgeType; event: PointerEvent }) => void;
};