From fbb3f63134477d5f517d092015e3c4c9f3ea3ab3 Mon Sep 17 00:00:00 2001 From: braks <78412429+bcakmakoglu@users.noreply.github.com> Date: Mon, 5 Feb 2024 21:29:51 +0100 Subject: [PATCH] chore(core): update composable jsdocs --- docs/.gitignore | 1 + .../core/src/composables/useConnection.ts | 1 + packages/core/src/composables/useDrag.ts | 6 +++++ packages/core/src/composables/useEdge.ts | 3 ++- packages/core/src/composables/useEdgeHooks.ts | 5 ++++ .../src/composables/useGetPointerPosition.ts | 4 ++- packages/core/src/composables/useHandle.ts | 4 ++- .../src/composables/useHandleConnections.ts | 25 ++++++++----------- packages/core/src/composables/useKeyPress.ts | 2 ++ packages/core/src/composables/useNode.ts | 3 ++- packages/core/src/composables/useNodeHooks.ts | 5 ++++ packages/core/src/composables/useNodeId.ts | 1 + packages/core/src/composables/useNodesData.ts | 1 + .../src/composables/useNodesInitialized.ts | 11 ++++++++ .../core/src/composables/useOnInitHandler.ts | 5 ++++ .../core/src/composables/useResizeHandler.ts | 6 +++++ .../src/composables/useUpdateNodePositions.ts | 5 ++++ packages/core/src/composables/useViewport.ts | 7 ++++++ .../core/src/composables/useVisibleNodeIds.ts | 12 +++++++++ packages/core/src/composables/useVueFlow.ts | 1 + .../core/src/composables/useWatchProps.ts | 8 ++++++ packages/core/src/composables/useWindow.ts | 5 ++++ packages/core/src/types/flow.ts | 1 + 23 files changed, 104 insertions(+), 18 deletions(-) create mode 100644 packages/core/src/composables/useVisibleNodeIds.ts diff --git a/docs/.gitignore b/docs/.gitignore index a3da8a40..1ce35028 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -7,3 +7,4 @@ src/changelog src/typedocs src/public/*.mjs src/.vitepress/cache +src/.vitepress/.temp diff --git a/packages/core/src/composables/useConnection.ts b/packages/core/src/composables/useConnection.ts index fe816795..03cfb9af 100644 --- a/packages/core/src/composables/useConnection.ts +++ b/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() { diff --git a/packages/core/src/composables/useDrag.ts b/packages/core/src/composables/useDrag.ts index 9f6130d3..9db6bc4a 100644 --- a/packages/core/src/composables/useDrag.ts +++ b/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, diff --git a/packages/core/src/composables/useEdge.ts b/packages/core/src/composables/useEdge.ts index 17387f23..742a76ec 100644 --- a/packages/core/src/composables/useEdge.ts +++ b/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 */ diff --git a/packages/core/src/composables/useEdgeHooks.ts b/packages/core/src/composables/useEdgeHooks.ts index 29c2d791..cd6dd814 100644 --- a/packages/core/src/composables/useEdgeHooks.ts +++ b/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() diff --git a/packages/core/src/composables/useGetPointerPosition.ts b/packages/core/src/composables/useGetPointerPosition.ts index 4b78ea12..7ff500e0 100644 --- a/packages/core/src/composables/useGetPointerPosition.ts +++ b/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() diff --git a/packages/core/src/composables/useHandle.ts b/packages/core/src/composables/useHandle.ts index e509db67..5f302a58 100644 --- a/packages/core/src/composables/useHandle.ts +++ b/packages/core/src/composables/useHandle.ts @@ -17,7 +17,7 @@ import { } from '../utils' import { useVueFlow } from './useVueFlow' -interface UseHandleProps { +export interface UseHandleProps { handleId: MaybeRefOrGetter nodeId: MaybeRefOrGetter type: MaybeRefOrGetter @@ -35,6 +35,8 @@ function alwaysValid() { * This composable provides listeners for handle events * * Generally it's recommended to use the `` component instead of this composable. + * + * @public */ export function useHandle({ handleId, diff --git a/packages/core/src/composables/useHandleConnections.ts b/packages/core/src/composables/useHandleConnections.ts index 91113797..f10cdfa5 100644 --- a/packages/core/src/composables/useHandleConnections.ts +++ b/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 id?: MaybeRefOrGetter nodeId?: MaybeRefOrGetter @@ -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 { +export function useHandleConnections(params: UseHandleConnectionsParams): ComputedRef { + const { type, id, nodeId, onConnect, onDisconnect } = params + const { connectionLookup } = useVueFlow() const _nodeId = useNodeId() diff --git a/packages/core/src/composables/useKeyPress.ts b/packages/core/src/composables/useKeyPress.ts index 4731c4ff..4cdac948 100644 --- a/packages/core/src/composables/useKeyPress.ts +++ b/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 */ diff --git a/packages/core/src/composables/useNode.ts b/packages/core/src/composables/useNode.ts index 40c7aa21..2355a98f 100644 --- a/packages/core/src/composables/useNode.ts +++ b/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 */ diff --git a/packages/core/src/composables/useNodeHooks.ts b/packages/core/src/composables/useNodeHooks.ts index c00a87f2..4ab04762 100644 --- a/packages/core/src/composables/useNodeHooks.ts +++ b/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() diff --git a/packages/core/src/composables/useNodeId.ts b/packages/core/src/composables/useNodeId.ts index d75ae55c..cf454b3b 100644 --- a/packages/core/src/composables/useNodeId.ts +++ b/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() { diff --git a/packages/core/src/composables/useNodesData.ts b/packages/core/src/composables/useNodesData.ts index 79e4b60d..affade0f 100644 --- a/packages/core/src/composables/useNodesData.ts +++ b/packages/core/src/composables/useNodesData.ts @@ -10,6 +10,7 @@ type NodeData = NonNullable /** * 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 diff --git a/packages/core/src/composables/useNodesInitialized.ts b/packages/core/src/composables/useNodesInitialized.ts index cce0fd6c..d03574bd 100644 --- a/packages/core/src/composables/useNodesInitialized.ts +++ b/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() diff --git a/packages/core/src/composables/useOnInitHandler.ts b/packages/core/src/composables/useOnInitHandler.ts index 8fed0f45..142bd252 100644 --- a/packages/core/src/composables/useOnInitHandler.ts +++ b/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() diff --git a/packages/core/src/composables/useResizeHandler.ts b/packages/core/src/composables/useResizeHandler.ts index 8e9defdf..5f5d6faf 100644 --- a/packages/core/src/composables/useResizeHandler.ts +++ b/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): void { const window = useWindow() diff --git a/packages/core/src/composables/useUpdateNodePositions.ts b/packages/core/src/composables/useUpdateNodePositions.ts index 92a71273..ce928e5b 100644 --- a/packages/core/src/composables/useUpdateNodePositions.ts +++ b/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() diff --git a/packages/core/src/composables/useViewport.ts b/packages/core/src/composables/useViewport.ts index b32bfb4f..27ef2818 100644 --- a/packages/core/src/composables/useViewport.ts +++ b/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 diff --git a/packages/core/src/composables/useVisibleNodeIds.ts b/packages/core/src/composables/useVisibleNodeIds.ts new file mode 100644 index 00000000..efd8e62f --- /dev/null +++ b/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 +} diff --git a/packages/core/src/composables/useVueFlow.ts b/packages/core/src/composables/useVueFlow.ts index 8794bab3..0ca6f0fe 100644 --- a/packages/core/src/composables/useVueFlow.ts +++ b/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 { diff --git a/packages/core/src/composables/useWatchProps.ts b/packages/core/src/composables/useWatchProps.ts index 57337f5b..bf95e8e6 100644 --- a/packages/core/src/composables/useWatchProps.ts +++ b/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>, props: FlowProps, diff --git a/packages/core/src/composables/useWindow.ts b/packages/core/src/composables/useWindow.ts index a84cd292..812e140b 100644 --- a/packages/core/src/composables/useWindow.ts +++ b/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 diff --git a/packages/core/src/types/flow.ts b/packages/core/src/types/flow.ts index dac0aaf7..37e8b166 100644 --- a/packages/core/src/types/flow.ts +++ b/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) */