chore(svelte): cleanup tsdoc annotations

packages/svelte/src/lib/container/SvelteFlow/types.ts

@@ -50,13 +50,12 @@ export type SvelteFlowProps<
   NodeSelectionEvents<NodeType> &
   EdgeEvents<EdgeType> &
   PaneEvents & {
-    /** The id of the flow
+    /**
-     *
+     * The id of the flow. This is necessary if you want to render multiple flows.
-     * This is necessary if you want to render multiple flows.
-     * @optional
      */
     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,
+     *  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'
      * }
      */
     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.
      */

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());

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());

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());

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,

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<NodeType extends Node = Node>(
   nodeId: string

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());

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 A set of helper functions
- * @returns helper functions
  */
 export function useSvelteFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): {
   /**

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());

packages/svelte/src/lib/types/events.ts

@@ -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;
 };