chore(core): update composable jsdocs

docs/.gitignore

@@ -7,3 +7,4 @@ src/changelog
 src/typedocs
 src/public/*.mjs
 src/.vitepress/cache
+src/.vitepress/.temp

packages/core/src/composables/useConnection.ts

@@ -3,6 +3,7 @@ import { useVueFlow } from './useVueFlow'
 /**
  * Composable for accessing the currently ongoing connection.
  *
+ * @public
  * @returns current connection: startHandle, endHandle, status, position
  */
 export function useConnection() {

packages/core/src/composables/useDrag.ts

@@ -30,6 +30,12 @@ interface UseDragParams {
   id?: string
 }
 
+/**
+ * Composable that provides drag behavior for nodes
+ *
+ * @internal
+ * @param params
+ */
 export function useDrag(params: UseDragParams) {
   const {
     vueFlowRef,

packages/core/src/composables/useEdge.ts

@@ -5,12 +5,13 @@ import { EdgeId, EdgeRef } from '../context'
 import { useVueFlow } from './useVueFlow'
 
 /**
- * This composable provides access to an edge object and it's dom element
+ * Composable that provides access to an edge object and it's dom element
  *
  * If no edge id is provided, the edge id is injected from context
  *
  * If you do not provide an id, this composable has to be called in a child of your custom edge component, or it will throw
  *
+ * @public
  * @param id - The id of the edge to access
  * @returns the edge id, the edge and the edge dom element
  */

packages/core/src/composables/useEdgeHooks.ts

@@ -15,6 +15,11 @@ function createEdgeHooks() {
   }
 }
 
+/**
+ * Composable for handling edge events
+ *
+ * @internal
+ */
 export function useEdgeHooks(edge: GraphEdge, emits: VueFlowStore['emits']): { emit: EdgeEventsEmit; on: EdgeEventsOn } {
   const edgeHooks = createEdgeHooks()
 

packages/core/src/composables/useGetPointerPosition.ts

@@ -2,7 +2,9 @@ import type { UseDragEvent } from './useDrag'
 import { useVueFlow } from './useVueFlow'
 
 /**
- * This composable is for *internal* use only.
+ * Composable that returns a function to get the pointer position
+ *
+ * @internal
  */
 export function useGetPointerPosition() {
   const { viewport, snapGrid, snapToGrid } = useVueFlow()

packages/core/src/composables/useHandle.ts

@@ -17,7 +17,7 @@ import {
 } from '../utils'
 import { useVueFlow } from './useVueFlow'
 
-interface UseHandleProps {
+export interface UseHandleProps {
   handleId: MaybeRefOrGetter<string | null>
   nodeId: MaybeRefOrGetter<string>
   type: MaybeRefOrGetter<HandleType>
@@ -35,6 +35,8 @@ function alwaysValid() {
  * This composable provides listeners for handle events
  *
  * Generally it's recommended to use the `<Handle />` component instead of this composable.
+ *
+ * @public
  */
 export function useHandle({
   handleId,

packages/core/src/composables/useHandleConnections.ts

@@ -7,7 +7,7 @@ import { areConnectionMapsEqual, handleConnectionChange } from '../utils'
 import { useNodeId } from './useNodeId'
 import { useVueFlow } from './useVueFlow'
 
-interface UseHandleConnectionsParams {
+export interface UseHandleConnectionsParams {
   type: MaybeRefOrGetter<HandleType>
   id?: MaybeRefOrGetter<string | null>
   nodeId?: MaybeRefOrGetter<string | null>
@@ -18,22 +18,19 @@ interface UseHandleConnectionsParams {
 /**
  * Composable that returns existing connections of a handle
  *
- * @param UseHandleConnectionsParams
- * @param UseHandleConnectionsParams.type - handle type `source` or `target`
- * @param UseHandleConnectionsParams.nodeId - node id - if not provided, the node id from the `useNodeId` (meaning, the context-based injection) is used
- * @param UseHandleConnectionsParams.id - the handle id (this is required if the node has multiple handles of the same type)
- * @param UseHandleConnectionsParams.onConnect - gets called when a connection is created
- * @param UseHandleConnectionsParams.onDisconnect - gets called when a connection is removed
+ * @public
+ * @param params
+ * @param params.type - handle type `source` or `target`
+ * @param params.nodeId - node id - if not provided, the node id from the `useNodeId` (meaning, the context-based injection) is used
+ * @param params.id - the handle id (this is required if the node has multiple handles of the same type)
+ * @param params.onConnect - gets called when a connection is created
+ * @param params.onDisconnect - gets called when a connection is removed
  *
  * @returns An array of connections
  */
-export function useHandleConnections({
-  type,
-  id,
-  nodeId,
-  onConnect,
-  onDisconnect,
-}: UseHandleConnectionsParams): ComputedRef<Connection[]> {
+export function useHandleConnections(params: UseHandleConnectionsParams): ComputedRef<Connection[]> {
+  const { type, id, nodeId, onConnect, onDisconnect } = params
+
   const { connectionLookup } = useVueFlow()
 
   const _nodeId = useNodeId()

packages/core/src/composables/useKeyPress.ts

@@ -66,6 +66,8 @@ function useKeyOrCode(code: string, keysToWatch: string | string[]) {
 /**
  * Reactive key press state
  *
+ * todo: make this public?
+ * @internal
  * @param keyFilter - Can be a boolean, a string or an array of strings. If it's a boolean, it will always return that value. If it's a string, it will return true if the key is pressed. If it's an array of strings, it will return true if any of the keys are pressed, or a combination is pressed (e.g. ['ctrl+a', 'ctrl+b'])
  * @param onChange - Callback function that will be called when the key state changes
  */

packages/core/src/composables/useNode.ts

@@ -6,12 +6,13 @@ import { useVueFlow } from './useVueFlow'
 import { useNodeId } from './useNodeId'
 
 /**
- * This composable provides access to a node object, parent node object, connected edges and it's dom element
+ * Composable that provides access to a node object, parent node object, connected edges and it's dom element
  *
  * If no node id is provided, the node id is injected from context
  *
  * If you do not provide an id, this composable has to be called in a child of your custom node component, or it will throw
  *
+ * @public
  * @param id - The id of the node to access
  * @returns the node id, the node, the node dom element, it's parent and connected edges
  */

packages/core/src/composables/useNodeHooks.ts

@@ -15,6 +15,11 @@ function createNodeHooks() {
   }
 }
 
+/**
+ * Composable for handling node events
+ *
+ * @internal
+ */
 export function useNodeHooks(node: GraphNode, emits: VueFlowStore['emits']): { emit: NodeEventsEmit; on: NodeEventsOn } {
   const nodeHooks = createNodeHooks()
 

packages/core/src/composables/useNodeId.ts

@@ -6,6 +6,7 @@ import { NodeId } from '../context'
  *
  * It should be used inside a (custom-)node components ctx as the id is provided by the internal `NodeWrapper` component.
  *
+ * @public
  * @returns the current node id
  */
 export function useNodeId() {

packages/core/src/composables/useNodesData.ts

@@ -10,6 +10,7 @@ type NodeData<NodeType extends Node = GraphNode> = NonNullable<NodeType['data']>
 /**
  * Composable for receiving data of one or multiple nodes
  *
+ * @public
  * @param nodeId - The id (or ids) of the node to get the data from
  * @param guard - Optional guard function to narrow down the node type
  * @returns An array of data objects

packages/core/src/composables/useNodesInitialized.ts

@@ -5,6 +5,17 @@ export interface UseNodesInitializedOptions {
   includeHiddenNodes?: boolean
 }
 
+/**
+ * Composable for getting the initialized state of all nodes.
+ *
+ * When a new node is added to the graph, it is not immediately initialized.
+ * That's because the node's bounds are not yet known.
+ * This composable will return false and then true when all nodes are initialized, i.e. when their bounds are known.
+ *
+ * @public
+ * @param options - Options
+ * @returns boolean indicating whether all nodes are initialized
+ */
 export function useNodesInitialized(options: UseNodesInitializedOptions = { includeHiddenNodes: false }) {
   const { nodes } = useVueFlow()
 

packages/core/src/composables/useOnInitHandler.ts

@@ -1,6 +1,11 @@
 import { watch } from 'vue'
 import { useVueFlow } from './useVueFlow'
 
+/**
+ * Composable that handles the initialization of the viewport.
+ *
+ * @internal
+ */
 export function useOnInitHandler() {
   const vfInstance = useVueFlow()
 

packages/core/src/composables/useResizeHandler.ts

@@ -4,6 +4,12 @@ import { ErrorCode, VueFlowError, getDimensions } from '../utils'
 import { useVueFlow } from './useVueFlow'
 import { useWindow } from './useWindow'
 
+/**
+ * Composable that handles the resize of the viewport.
+ *
+ * @internal
+ * @param viewportEl
+ */
 export function useResizeHandler(viewportEl: Ref<HTMLDivElement | null>): void {
   const window = useWindow()
 

packages/core/src/composables/useUpdateNodePositions.ts

@@ -2,6 +2,11 @@ import type { NodeDragItem, XYPosition } from '../types'
 import { calcNextPosition } from '../utils'
 import { useVueFlow } from './useVueFlow'
 
+/**
+ * Composable for updating the position of nodes.
+ *
+ * @internal
+ */
 export function useUpdateNodePositions() {
   const { getSelectedNodes, nodeExtent, updateNodePositions, findNode, snapGrid, snapToGrid, nodesDraggable, emits } =
     useVueFlow()

packages/core/src/composables/useViewport.ts

@@ -34,6 +34,13 @@ const initialViewportHelper: ViewportHelper = {
   viewportInitialized: false,
 }
 
+/**
+ * Composable that provides viewport helper functions.
+ *
+ * @internal
+ * @param state
+ * @param getters
+ */
 export function useViewport(state: State, getters: ComputedGetters) {
   const { getNodes } = getters
 

packages/core/src/composables/useVisibleNodeIds.ts

@@ -0,0 +1,12 @@
+/**
+ * Composable for getting the visible node ids from the store.
+ *
+ * @internal
+ * @param onlyRenderVisible
+ * @returns array with visible node ids
+ */
+export function useVisibleNodeIds(onlyRenderVisible: boolean) {
+  const nodeIds = useStore(useCallback(selector(onlyRenderVisible), [onlyRenderVisible]), shallow)
+
+  return nodeIds
+}

packages/core/src/composables/useVueFlow.ts

@@ -94,6 +94,7 @@ type Scope = (EffectScope & { vueFlowId: string }) | undefined
  *
  * If no store instance is found in context, a new store instance is created and registered in storage
  *
+ * @public
  * @returns a vue flow store instance
  */
 export function useVueFlow(options?: FlowProps): VueFlowStore {

packages/core/src/composables/useWatchProps.ts

@@ -5,6 +5,14 @@ import { toRef, watchPausable } from '@vueuse/core'
 import type { Connection, FlowProps, VueFlowStore } from '../types'
 import { isDef } from '../utils'
 
+/**
+ * Watches props and updates the store accordingly
+ *
+ * @internal
+ * @param models
+ * @param props
+ * @param store
+ */
 export function useWatchProps(
   models: ToRefs<Pick<FlowProps, 'nodes' | 'edges' | 'modelValue'>>,
   props: FlowProps,

packages/core/src/composables/useWindow.ts

@@ -1,5 +1,10 @@
 type UseWindow = Window & typeof globalThis & { chrome?: any }
 
+/**
+ * Returns the window object
+ *
+ * @internal
+ */
 export function useWindow(): UseWindow {
   if (typeof window !== 'undefined') {
     return window as UseWindow

packages/core/src/types/flow.ts

@@ -20,6 +20,7 @@ import type { ValidConnectionFunc } from './handle'
 import type { EdgeChange, NodeChange } from './changes'
 import type { VueFlowStore } from './store'
 
+// todo: should be object type
 export type ElementData = any
 
 /** A flow element (after parsing into state)  */