dify/web/app/components/workflow/hooks/use-helpline.ts

import type { Node } from '../types'
import { useCallback } from 'react'
import { useStoreApi } from 'reactflow'
import { useWorkflowStore } from '../store'
import { BlockEnum, isTriggerNode } from '../types'

// Entry node (Start/Trigger) wrapper offsets
// The EntryNodeContainer adds a wrapper with status indicator above the actual node
// These offsets ensure alignment happens on the inner node, not the wrapper
const ENTRY_NODE_WRAPPER_OFFSET = {
  x: 0, // No horizontal padding on wrapper (px-0)
  y: 21, // Actual measured: pt-0.5 (2px) + status bar height (~19px)
} as const

type HelpLineNodeCollections = {
  showHorizontalHelpLineNodes: Node[]
  showVerticalHelpLineNodes: Node[]
}

type NodeAlignPosition = {
  x: number
  y: number
}

const ALIGN_THRESHOLD = 5

const getEntryNodeDimension = (node: Node, dimension: 'width' | 'height') => {
  const offset = dimension === 'width' ? ENTRY_NODE_WRAPPER_OFFSET.x : ENTRY_NODE_WRAPPER_OFFSET.y

  return (node[dimension] ?? 0) - offset
}

const getAlignedNodes = ({
  nodes,
  node,
  nodeAlignPos,
  axis,
  getNodeAlignPosition,
}: {
  nodes: Node[]
  node: Node
  nodeAlignPos: NodeAlignPosition
  axis: 'x' | 'y'
  getNodeAlignPosition: (node: Node) => NodeAlignPosition
}) => {
  return nodes
    .filter((candidate) => {
      if (candidate.id === node.id) return false
      if (candidate.data.isInIteration || candidate.data.isInLoop) return false

      const candidateAlignPos = getNodeAlignPosition(candidate)
      const diff = Math.ceil(candidateAlignPos[axis]) - Math.ceil(nodeAlignPos[axis])
      return diff < ALIGN_THRESHOLD && diff > -ALIGN_THRESHOLD
    })
    .sort((a, b) => {
      const aPos = getNodeAlignPosition(a)
      const bPos = getNodeAlignPosition(b)
      return aPos.x - bPos.x
    })
}

const buildHorizontalHelpLine = ({
  alignedNodes,
  node,
  nodeAlignPos,
  getNodeAlignPosition,
  isEntryNode,
}: {
  alignedNodes: Node[]
  node: Node
  nodeAlignPos: NodeAlignPosition
  getNodeAlignPosition: (node: Node) => NodeAlignPosition
  isEntryNode: (node: Node) => boolean
}) => {
  if (!alignedNodes.length) return undefined

  const first = alignedNodes[0]
  const last = alignedNodes[alignedNodes.length - 1]
  const firstPos = getNodeAlignPosition(first!)
  const lastPos = getNodeAlignPosition(last!)
  const helpLine = {
    top: firstPos.y,
    left: firstPos.x,
    width:
      lastPos.x +
      (isEntryNode(last!) ? getEntryNodeDimension(last!, 'width') : (last!.width ?? 0)) -
      firstPos.x,
  }

  if (nodeAlignPos.x < firstPos.x) {
    helpLine.left = nodeAlignPos.x
    helpLine.width =
      firstPos.x +
      (isEntryNode(first!) ? getEntryNodeDimension(first!, 'width') : (first!.width ?? 0)) -
      nodeAlignPos.x
  }

  if (nodeAlignPos.x > lastPos.x)
    helpLine.width =
      nodeAlignPos.x +
      (isEntryNode(node) ? getEntryNodeDimension(node, 'width') : (node.width ?? 0)) -
      firstPos.x

  return helpLine
}

const buildVerticalHelpLine = ({
  alignedNodes,
  node,
  nodeAlignPos,
  getNodeAlignPosition,
  isEntryNode,
}: {
  alignedNodes: Node[]
  node: Node
  nodeAlignPos: NodeAlignPosition
  getNodeAlignPosition: (node: Node) => NodeAlignPosition
  isEntryNode: (node: Node) => boolean
}) => {
  if (!alignedNodes.length) return undefined

  const first = alignedNodes[0]
  const last = alignedNodes[alignedNodes.length - 1]
  const firstPos = getNodeAlignPosition(first!)
  const lastPos = getNodeAlignPosition(last!)
  const helpLine = {
    top: firstPos.y,
    left: firstPos.x,
    height:
      lastPos.y +
      (isEntryNode(last!) ? getEntryNodeDimension(last!, 'height') : (last!.height ?? 0)) -
      firstPos.y,
  }

  if (nodeAlignPos.y < firstPos.y) {
    helpLine.top = nodeAlignPos.y
    helpLine.height =
      firstPos.y +
      (isEntryNode(first!) ? getEntryNodeDimension(first!, 'height') : (first!.height ?? 0)) -
      nodeAlignPos.y
  }

  if (nodeAlignPos.y > lastPos.y)
    helpLine.height =
      nodeAlignPos.y +
      (isEntryNode(node) ? getEntryNodeDimension(node, 'height') : (node.height ?? 0)) -
      firstPos.y

  return helpLine
}

export const useHelpline = () => {
  const store = useStoreApi()
  const workflowStore = useWorkflowStore()

  // Check if a node is an entry node (Start or Trigger)
  const isEntryNode = useCallback((node: Node): boolean => {
    return isTriggerNode(node.data.type as any) || node.data.type === BlockEnum.Start
  }, [])

  // Get the actual alignment position of a node (accounting for wrapper offset)
  const getNodeAlignPosition = useCallback(
    (node: Node) => {
      if (isEntryNode(node)) {
        return {
          x: node.position.x + ENTRY_NODE_WRAPPER_OFFSET.x,
          y: node.position.y + ENTRY_NODE_WRAPPER_OFFSET.y,
        }
      }
      return {
        x: node.position.x,
        y: node.position.y,
      }
    },
    [isEntryNode],
  )

  const handleSetHelpline = useCallback(
    (node: Node) => {
      const { getNodes } = store.getState()
      const nodes = getNodes()
      const { setHelpLineHorizontal, setHelpLineVertical } = workflowStore.getState()

      if (node.data.isInIteration) {
        return {
          showHorizontalHelpLineNodes: [],
          showVerticalHelpLineNodes: [],
        }
      }

      if (node.data.isInLoop) {
        return {
          showHorizontalHelpLineNodes: [],
          showVerticalHelpLineNodes: [],
        }
      }

      // Get the actual alignment position for the dragging node
      const nodeAlignPos = getNodeAlignPosition(node)

      const showHorizontalHelpLineNodes = getAlignedNodes({
        nodes,
        node,
        nodeAlignPos,
        axis: 'y',
        getNodeAlignPosition,
      })
      const showVerticalHelpLineNodes = getAlignedNodes({
        nodes,
        node,
        nodeAlignPos,
        axis: 'x',
        getNodeAlignPosition,
      })

      setHelpLineHorizontal(
        buildHorizontalHelpLine({
          alignedNodes: showHorizontalHelpLineNodes,
          node,
          nodeAlignPos,
          getNodeAlignPosition,
          isEntryNode,
        }),
      )
      setHelpLineVertical(
        buildVerticalHelpLine({
          alignedNodes: showVerticalHelpLineNodes,
          node,
          nodeAlignPos,
          getNodeAlignPosition,
          isEntryNode,
        }),
      )

      return {
        showHorizontalHelpLineNodes,
        showVerticalHelpLineNodes,
      } satisfies HelpLineNodeCollections
    },
    [store, workflowStore, getNodeAlignPosition, isEntryNode],
  )

  return {
    handleSetHelpline,
  }
}