Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

16.5 KB
Raw Blame
import '@xyflow/react/dist/style.css'

import {
    Background,
    BackgroundVariant,
    ControlButton,
    Controls,
    FitViewOptions,
    MiniMap,
    type Node,
    Panel,
    ReactFlow,
    ReactFlowProvider,
    useReactFlow,
    useStore,
    type XYPosition,
} from '@xyflow/react'
import clsx from 'clsx'
import { useValues } from 'kea'
import {
    type KeyboardEvent,
    type MouseEvent,
    ReactNode,
    useCallback,
    useEffect,
    useMemo,
    useRef,
    useState,
} from 'react'

import { IconArchive, IconExpand45, IconRefresh } from '@posthog/icons'

import { themeLogic } from '~/layout/navigation-3000/themeLogic'
import { DataModelingNode } from '~/types'

import { ElkDirection } from './autolayout'
import { LINEAGE_MIN_ZOOM, lineageFitTarget } from './lineageFit'
import { LineageGraphLoading } from './LineageGraphLoading'
import { lineageGraphLogic } from './lineageGraphLogic'
import { LineageEdge, LineageGraphNode } from './lineageHiddenNodes'
import { LINEAGE_NODE_TYPES, LineageNodeCallbacks, LineageNodeState, LineageVariant } from './LineageNode'
import { lineageCone } from './lineageSelection'
import { useNodesMeasured } from './useNodesMeasured'

export type { LineageVariant, LineageNodeState, LineageNodeCallbacks } from './LineageNode'

const EMPTY_NODES: LineageGraphNode[] = []
const EMPTY_EDGES: LineageEdge[] = []
const FOCUSED_NODES_MAX_ZOOM = 2
const CURRENT_NODE_MAX_ZOOM = 1

export interface LineageGraphProps {
    nodes: LineageGraphNode[]
    edges: LineageEdge[]
    /** Highlighted "you are here" node, rendered with a target marker + accent border */
    currentNodeId?: string
    variant?: LineageVariant
    direction?: ElkDirection
    /** Enable zoom/pan. Off by default for inline previews */
    interactive?: boolean
    nodesDraggable?: boolean
    nodePositions?: Record<string, XYPosition>
    onNodeDragStop?: (node: DataModelingNode, position: XYPosition) => void
    onResetNodePositions?: () => void
    fitViewOptions?: FitViewOptions
    focusNodeIds?: Set<string> | null
    searchFocusRequest?: { nodeId: string; requestId: number } | null
    showMinimap?: boolean
    showControls?: boolean
    className?: string
    loading?: boolean
    loadingCenter?: Pick<DataModelingNode, 'name' | 'type'>
    emptyMessage?: string
    /** Per-node visual state (running, dimmed, highlighted), computed by the caller */
    nodeState?: (node: DataModelingNode) => LineageNodeState
    /** Per-node affordances (click, run, edit), wired by the caller to its own logic */
    nodeCallbacks?: (node: DataModelingNode) => LineageNodeCallbacks
    /** Convenience click handler, used when nodeCallbacks is not provided */
    onNodeClick?: (node: DataModelingNode) => void
    /** Dedicated new-tab link shown on each node */
    nodeOpenUrl?: (node: DataModelingNode) => string
    /** Clicking a node highlights its full upstream and downstream lineage */
    selectable?: boolean
    /** Caller-specific chrome (legend, layout toggle) rendered over the canvas */
    panels?: ReactNode
}

function LineageGraphContent(props: LineageGraphProps): JSX.Element {
    const { fitView, getNodesBounds, setNodes, viewportInitialized } = useReactFlow()
    const viewportWidth = useStore((state) => state.width)
    const viewportHeight = useStore((state) => state.height)
    const nodesMeasured = useNodesMeasured()
    const { isDarkModeOn } = useValues(themeLogic)
    const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null)
    const { currentNodeId, nodeState, nodeCallbacks, onNodeClick, nodeOpenUrl, searchFocusRequest } = props
    const focusNodeIds = useMemo(
        () => props.focusNodeIds ?? (currentNodeId ? new Set([currentNodeId]) : null),
        [props.focusNodeIds, currentNodeId]
    )
    const { layout } = useValues(
        lineageGraphLogic({
            nodes: props.loading ? EMPTY_NODES : props.nodes,
            edges: props.loading ? EMPTY_EDGES : props.edges,
            variant: props.variant ?? 'full',
            direction: props.direction ?? 'RIGHT',
        })
    )
    const fittedLayout = useRef<typeof layout>(null)
    const fittedFocus = useRef<{ focusNodeIds: Set<string>; layout: typeof layout } | null>(null)
    const fittedSearchRequest = useRef<{ requestId: number; layout: typeof layout } | null>(null)
    const lastNodeDrag = useRef<{ nodeId: string; stoppedAt: number } | null>(null)
    const resetRequested = useRef(false)

    const fitNodes = useCallback(
        (nodes: Node[], options: FitViewOptions = {}): void => {
            const padding = typeof options.padding === 'number' ? options.padding : 0.2
            const viewport = { width: viewportWidth, height: viewportHeight }
            const target = lineageFitTarget(nodes, getNodesBounds(nodes), viewport, padding)
            void fitView({ ...options, padding, nodes: target.nodes, maxZoom: target.maxZoom ?? options.maxZoom })
        },
        [fitView, getNodesBounds, viewportWidth, viewportHeight]
    )
    const selectedLineage = useMemo(
        () => (props.selectable && selectedNodeId ? lineageCone(props.edges, selectedNodeId) : null),
        [props.edges, props.selectable, selectedNodeId]
    )

    useEffect(() => {
        if (selectedNodeId && !props.nodes.some((node) => node.id === selectedNodeId)) {
            setSelectedNodeId(null)
        }
    }, [props.nodes, selectedNodeId])

    // Decorating on every render would hand react-flow new node objects, which drops the sizes it
    // measured — so the fit below would keep waiting and the edges would keep being redrawn.
    const decoratedNodes = useMemo(
        () =>
            layout?.nodes.map((rfNode) => {
                const node = rfNode.data.node as DataModelingNode
                const baseCallbacks = nodeCallbacks?.(node) ?? {
                    onClick: onNodeClick ? () => onNodeClick(node) : undefined,
                }
                const callbacks = props.selectable
                    ? { ...baseCallbacks, onClick: () => setSelectedNodeId(node.id) }
                    : baseCallbacks
                const onClick = callbacks.onClick
                const callerState = nodeState?.(node)
                return {
                    ...rfNode,
                    position: props.nodePositions?.[node.id] ?? rfNode.position,
                    data: {
                        ...rfNode.data,
                        draggable: props.nodesDraggable,
                        openUrl: nodeOpenUrl?.(node),
                        selectable: props.selectable,
                        state: {
                            isCurrent: node.id === currentNodeId,
                            ...callerState,
                            isSelected: callerState?.isSelected || selectedNodeId === node.id,
                            isDimmed: selectedLineage ? !selectedLineage.nodeIds.has(node.id) : callerState?.isDimmed,
                        },
                        callbacks: {
                            ...callbacks,
                            onClick: onClick
                                ? (event: MouseEvent | KeyboardEvent) => {
                                      const lastDrag = lastNodeDrag.current
                                      const isDragClick =
                                          event.detail > 0 &&
                                          lastDrag?.nodeId === node.id &&
                                          Date.now() - lastDrag.stoppedAt <= 200
                                      if (!isDragClick) {
                                          onClick(event)
                                      }
                                  }
                                : undefined,
                        },
                    },
                }
            }) ?? [],
        [
            currentNodeId,
            layout,
            nodeCallbacks,
            nodeOpenUrl,
            nodeState,
            onNodeClick,
            props.nodePositions,
            props.nodesDraggable,
            props.selectable,
            selectedLineage,
            selectedNodeId,
        ]
    )

    const decoratedEdges = useMemo(
        () =>
            selectedLineage && layout
                ? layout.edges.map((edge) =>
                      selectedLineage.edgeIds.has(edge.id)
                          ? { ...edge, zIndex: 1, style: { ...edge.style, stroke: 'var(--link)', strokeWidth: 2 } }
                          : { ...edge, style: { ...edge.style, opacity: 0.15 } }
                  )
                : layout?.edges,
        [layout, selectedLineage]
    )

    const resetPositionsApplied = useStore(
        (state) =>
            !resetRequested.current ||
            decoratedNodes.every((node) => {
                const renderedNode = state.nodeLookup.get(node.id)
                return renderedNode?.position.x === node.position.x && renderedNode.position.y === node.position.y
            })
    )

    useEffect(() => {
        setNodes((currentNodes) => {
            if (currentNodes === decoratedNodes) {
                return currentNodes
            }
            const currentNodesById = new Map(currentNodes.map((node) => [node.id, node]))
            return decoratedNodes.map((node) => {
                const currentNode = currentNodesById.get(node.id)
                const measuredNode = currentNode?.measured ? { ...node, measured: currentNode.measured } : node
                return currentNode?.dragging
                    ? { ...measuredNode, position: currentNode.position, dragging: true }
                    : measuredNode
            })
        })
    }, [decoratedNodes, setNodes])

    const resetLayout = (): void => {
        resetRequested.current = true
        props.onResetNodePositions?.()
    }

    useEffect(() => {
        if (!resetRequested.current || Object.keys(props.nodePositions ?? {}).length > 0 || !resetPositionsApplied) {
            return
        }
        resetRequested.current = false
        fitNodes(decoratedNodes, { padding: props.fitViewOptions?.padding ?? 0.2, duration: 400 })
    }, [decoratedNodes, fitNodes, props.fitViewOptions?.padding, props.nodePositions, resetPositionsApplied])

    useEffect(() => {
        if (!viewportInitialized || !nodesMeasured || !layout || props.loading || fittedLayout.current === layout) {
            return
        }
        fittedLayout.current = layout
        if (focusNodeIds || searchFocusRequest) {
            return
        }
        fitNodes(decoratedNodes, {
            ...props.fitViewOptions,
            padding: props.fitViewOptions?.padding ?? 0.2,
            duration: 400,
        })
    }, [
        fitNodes,
        focusNodeIds,
        decoratedNodes,
        layout,
        nodesMeasured,
        props.fitViewOptions,
        props.loading,
        searchFocusRequest,
        viewportInitialized,
    ])

    useEffect(() => {
        if (!focusNodeIds) {
            fittedFocus.current = null
            return
        }
        if (!viewportInitialized || !nodesMeasured || !layout || props.loading) {
            return
        }
        if (fittedFocus.current?.focusNodeIds === focusNodeIds && fittedFocus.current.layout === layout) {
            return
        }
        // An empty focusNodeIds means the search was cleared, so fit the whole graph again rather
        // than leave the viewport where the last selector zoomed it.
        const nodes =
            focusNodeIds.size > 0 ? decoratedNodes.filter((node) => focusNodeIds.has(node.id)) : decoratedNodes
        if (nodes.length > 0) {
            fittedFocus.current = { focusNodeIds, layout }
            const focusedNodesMaxZoom = props.focusNodeIds ? FOCUSED_NODES_MAX_ZOOM : CURRENT_NODE_MAX_ZOOM
            fitNodes(nodes, {
                padding: 0.2,
                duration: 400,
                maxZoom: focusNodeIds.size > 0 ? focusedNodesMaxZoom : undefined,
            })
        }
    }, [
        decoratedNodes,
        fitNodes,
        viewportInitialized,
        nodesMeasured,
        focusNodeIds,
        layout,
        props.focusNodeIds,
        props.loading,
    ])

    useEffect(() => {
        if (!searchFocusRequest) {
            fittedSearchRequest.current = null
            return
        }
        if (!viewportInitialized || !nodesMeasured || !layout || props.loading) {
            return
        }
        if (
            fittedSearchRequest.current?.requestId === searchFocusRequest.requestId &&
            fittedSearchRequest.current.layout === layout
        ) {
            return
        }
        const node = decoratedNodes.find((renderedNode) => renderedNode.id === searchFocusRequest.nodeId)
        if (node) {
            fittedSearchRequest.current = { requestId: searchFocusRequest.requestId, layout }
            void fitView({ nodes: [node], padding: 0.2, duration: 400, maxZoom: 2 })
        }
    }, [decoratedNodes, fitView, viewportInitialized, nodesMeasured, searchFocusRequest, layout, props.loading])

    if (props.loading || !layout) {
        const center = props.loadingCenter ?? props.nodes.find((node) => node.id === currentNodeId)
        return (
            <LineageGraphLoading
                center={center}
                direction={props.direction ?? 'RIGHT'}
                fitViewOptions={props.fitViewOptions}
                variant={props.variant ?? 'full'}
            />
        )
    }

    return (
        <ReactFlow
            className={clsx('@container/lineage', props.className)}
            colorMode={isDarkModeOn ? 'dark' : 'light'}
            defaultNodes={decoratedNodes}
            edges={decoratedEdges}
            onPaneClick={props.selectable ? () => setSelectedNodeId(null) : undefined}
            nodeTypes={LINEAGE_NODE_TYPES}
            nodesDraggable={props.nodesDraggable ?? false}
            onNodeDragStop={(_, node) => {
                lastNodeDrag.current = { nodeId: node.id, stoppedAt: Date.now() }
                props.onNodeDragStop?.(node.data.node as DataModelingNode, node.position)
            }}
            nodesConnectable={false}
            elementsSelectable={false}
            // The card inside each node is the focus target and carries the key handler. A focusable
            // wrapper would add a second tab stop per node that only selects and never navigates.
            nodesFocusable={false}
            minZoom={LINEAGE_MIN_ZOOM}
            maxZoom={2}
            zoomOnScroll={props.interactive ?? false}
            panOnScroll={props.interactive ?? false}
            zoomOnPinch={props.interactive ?? false}
            zoomOnDoubleClick={props.interactive ?? false}
            proOptions={{ hideAttribution: true }}
        >
            <Background variant={BackgroundVariant.Dots} gap={20} size={1} />
            {props.showControls && (
                <Controls showInteractive={false} showFitView={false} position="bottom-left">
                    <ControlButton
                        aria-label="Fit view"
                        title="Fit view"
                        onClick={() => fitNodes(decoratedNodes, props.fitViewOptions)}
                    >
                        <IconExpand45 aria-hidden="true" />
                    </ControlButton>
                    {props.nodesDraggable && props.onResetNodePositions && (
                        <ControlButton
                            aria-label="Reset layout"
                            title="Reset layout"
                            onClick={resetLayout}
                            data-attr="models-lineage-reset-layout"
                        >
                            <IconRefresh aria-hidden="true" />
                        </ControlButton>
                    )}
                </Controls>
            )}
            {props.showMinimap && (
                <MiniMap
                    zoomable
                    pannable
                    position="bottom-right"
                    nodeStrokeWidth={2}
                    className="hidden border rounded shadow-sm @min-[48rem]/lineage:block"
                />
            )}
            {props.panels && <Panel position="top-right">{props.panels}</Panel>}
        </ReactFlow>
    )
}

export function LineageGraph(props: LineageGraphProps): JSX.Element {
    if (!props.loading && props.nodes.length === 0) {
        return (
            <div className="flex flex-col w-full h-full items-center justify-center p-4">
                <IconArchive className="text-5xl mb-2 text-tertiary" />
                <p className="text-sm text-center text-balance text-tertiary">
                    {props.emptyMessage ?? 'No tables or views found'}
                </p>
            </div>
        )
    }
    return (
        <ReactFlowProvider>
            <LineageGraphContent {...props} />
        </ReactFlowProvider>
    )
}