From bf7594cd3ebf04aa278f5bb4b1f551ee344ee499 Mon Sep 17 00:00:00 2001 From: moklick Date: Tue, 6 May 2025 23:25:18 +0200 Subject: [PATCH] chore(svelte): cleanup tsdoc annotations --- .../src/lib/container/SvelteFlow/types.ts | 159 ++++++++++-------- .../src/lib/hooks/useConnection.svelte.ts | 2 +- .../src/lib/hooks/useInitialized.svelte.ts | 3 +- .../src/lib/hooks/useInternalNode.svelte.ts | 2 +- .../lib/hooks/useNodeConnections.svelte.ts | 2 +- .../src/lib/hooks/useNodesData.svelte.ts | 2 +- .../lib/hooks/useNodesEdgesViewport.svelte.ts | 6 +- .../src/lib/hooks/useSvelteFlow.svelte.ts | 5 +- .../hooks/useUpdateNodeInternals.svelte.ts | 8 +- packages/svelte/src/lib/types/events.ts | 16 ++ 10 files changed, 120 insertions(+), 85 deletions(-) diff --git a/packages/svelte/src/lib/container/SvelteFlow/types.ts b/packages/svelte/src/lib/container/SvelteFlow/types.ts index 042bbc2f..9ec9a37d 100644 --- a/packages/svelte/src/lib/container/SvelteFlow/types.ts +++ b/packages/svelte/src/lib/container/SvelteFlow/types.ts @@ -50,13 +50,12 @@ export type SvelteFlowProps< NodeSelectionEvents & EdgeEvents & 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; - /** 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. */ diff --git a/packages/svelte/src/lib/hooks/useConnection.svelte.ts b/packages/svelte/src/lib/hooks/useConnection.svelte.ts index ed461e45..da3688f4 100644 --- a/packages/svelte/src/lib/hooks/useConnection.svelte.ts +++ b/packages/svelte/src/lib/hooks/useConnection.svelte.ts @@ -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()); diff --git a/packages/svelte/src/lib/hooks/useInitialized.svelte.ts b/packages/svelte/src/lib/hooks/useInitialized.svelte.ts index bff28a6e..931c6cf1 100644 --- a/packages/svelte/src/lib/hooks/useInitialized.svelte.ts +++ b/packages/svelte/src/lib/hooks/useInitialized.svelte.ts @@ -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()); diff --git a/packages/svelte/src/lib/hooks/useInternalNode.svelte.ts b/packages/svelte/src/lib/hooks/useInternalNode.svelte.ts index cad6d9c9..46c1cc04 100644 --- a/packages/svelte/src/lib/hooks/useInternalNode.svelte.ts +++ b/packages/svelte/src/lib/hooks/useInternalNode.svelte.ts @@ -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()); diff --git a/packages/svelte/src/lib/hooks/useNodeConnections.svelte.ts b/packages/svelte/src/lib/hooks/useNodeConnections.svelte.ts index d7bbfdc7..111fc715 100644 --- a/packages/svelte/src/lib/hooks/useNodeConnections.svelte.ts +++ b/packages/svelte/src/lib/hooks/useNodeConnections.svelte.ts @@ -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, diff --git a/packages/svelte/src/lib/hooks/useNodesData.svelte.ts b/packages/svelte/src/lib/hooks/useNodesData.svelte.ts index 84ec39ef..71432ceb 100644 --- a/packages/svelte/src/lib/hooks/useNodesData.svelte.ts +++ b/packages/svelte/src/lib/hooks/useNodesData.svelte.ts @@ -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( nodeId: string diff --git a/packages/svelte/src/lib/hooks/useNodesEdgesViewport.svelte.ts b/packages/svelte/src/lib/hooks/useNodesEdgesViewport.svelte.ts index 41a86a3a..aea6ab84 100644 --- a/packages/svelte/src/lib/hooks/useNodesEdgesViewport.svelte.ts +++ b/packages/svelte/src/lib/hooks/useNodesEdgesViewport.svelte.ts @@ -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()); diff --git a/packages/svelte/src/lib/hooks/useSvelteFlow.svelte.ts b/packages/svelte/src/lib/hooks/useSvelteFlow.svelte.ts index 5528e914..c8d31f77 100644 --- a/packages/svelte/src/lib/hooks/useSvelteFlow.svelte.ts +++ b/packages/svelte/src/lib/hooks/useSvelteFlow.svelte.ts @@ -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(): { /** diff --git a/packages/svelte/src/lib/hooks/useUpdateNodeInternals.svelte.ts b/packages/svelte/src/lib/hooks/useUpdateNodeInternals.svelte.ts index 2c515f22..f6124312 100644 --- a/packages/svelte/src/lib/hooks/useUpdateNodeInternals.svelte.ts +++ b/packages/svelte/src/lib/hooks/useUpdateNodeInternals.svelte.ts @@ -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()); diff --git a/packages/svelte/src/lib/types/events.ts b/packages/svelte/src/lib/types/events.ts index 4d8bf7ee..1c7b147c 100644 --- a/packages/svelte/src/lib/types/events.ts +++ b/packages/svelte/src/lib/types/events.ts @@ -28,29 +28,45 @@ export type NodeTargetEventWithPointer void; export type NodeEvents = { + /** This event handler is called when a user clicks on a node. */ onnodeclick?: NodeEventWithPointer; + /** This event handler is called when a user right-clicks on a node. */ onnodecontextmenu?: NodeEventWithPointer; + /** This event handler is called when a user drags a node. */ onnodedrag?: NodeTargetEventWithPointer; + /** This event handler is called when a user starts to drag a node. */ onnodedragstart?: NodeTargetEventWithPointer; + /** This event handler is called when a user stops dragging a node. */ onnodedragstop?: NodeTargetEventWithPointer; + /** This event handler is called when the pointer of a user enters a node. */ onnodepointerenter?: NodeEventWithPointer; + /** This event handler is called when the pointer of a user leaves a node. */ onnodepointerleave?: NodeEventWithPointer; + /** This event handler is called when the pointer of a user moves over a node. */ onnodepointermove?: NodeEventWithPointer; }; export type NodeSelectionEvents = { + /** This event handler is called when a user right-clicks the selection box. */ onselectioncontextmenu?: NodesEventWithPointer; + /** This event handler is called when a user clicks the selection box. */ onselectionclick?: NodesEventWithPointer; }; 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 = { + /** 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; };