Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

5.8 KB
Raw Blame
/*
 *  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import { type IArtifactGraphEntity } from '@/interfaces/database/dataset';
import { cn } from '@/lib/utils';
import escape from 'lodash/escape';
import { memo, useCallback, useEffect, useMemo, useRef } from 'react';
import { useTranslation } from 'react-i18next';
import ForceGraph2D, { type ForceGraphMethods } from 'react-force-graph-2d';
import {
  getNodeColor as defaultGetNodeColor,
  getNodeRadius as defaultGetNodeRadius,
  MinNodeRadius,
} from './node-style';
import {
  type ArtifactForceGraphProps,
  type ArtifactGraphLink,
  type ArtifactGraphNode,
} from './types';
import { useArtifactGraphData } from './use-artifact-graph-data';
import { useCenterGravity } from './use-center-gravity';
import { useContainerDimensions } from './use-container-dimensions';
import { useGraphHighlight } from './use-graph-highlight';
import { defaultMapNodeToValue } from './utils';

const defaultGetNodeId = (node: IArtifactGraphEntity) => node.slug;
/** Returns the entity description as the default plain-text tooltip. */
const defaultGetNodeLabel = (node: IArtifactGraphEntity) =>
  node.description ?? '';

const nodeCanvasObjectMode = () => 'after' as const;

/**
 * Renders an interactive force graph with configurable node styles and labels.
 * Escapes tooltip text and coordinates zoom-to-fit, hover and pinned-node
 * highlighting, and mapped node-click callbacks.
 */
function ArtifactForceGraph<TNodeValue = IArtifactGraphEntity>({
  data,
  show = true,
  onNodeClick,
  mapNodeToValue = defaultMapNodeToValue as (
    node: IArtifactGraphEntity,
  ) => TNodeValue,
  getNodeId = defaultGetNodeId,
  getNodeColor = defaultGetNodeColor,
  getNodeLabel = defaultGetNodeLabel,
  getNodeRadius = defaultGetNodeRadius,
  highlightNodeId,
  totalEntities,
  returnedEntities,
}: ArtifactForceGraphProps<TNodeValue>) {
  const { t } = useTranslation();
  const containerRef = useRef<HTMLDivElement>(null);
  const fgRef = useRef<ForceGraphMethods<ArtifactGraphNode> | undefined>(
    undefined,
  );
  const hasFittedRef = useRef(false);
  const dimensions = useContainerDimensions(containerRef, show);
  const hasDimensions = dimensions.width > 0 && dimensions.height > 0;

  const graphData = useArtifactGraphData({
    data,
    getNodeId,
    getNodeColor,
    getNodeRadius,
  });

  // Resolve the controlled id back to a node object reference (highlighting relies on the node's __neighbors/__links)
  const pinnedNode = useMemo(
    () =>
      highlightNodeId
        ? ((graphData.nodes.find((node) => node.id === highlightNodeId) ??
            null) as ArtifactGraphNode | null)
        : null,
    [graphData, highlightNodeId],
  );

  const {
    handleNodeHover,
    getNodeColor: nodeColor,
    getLinkColor,
    getLinkWidth,
    paintNode,
  } = useGraphHighlight(containerRef, pinnedNode);

  useEffect(() => {
    hasFittedRef.current = false;
  }, [graphData]);

  useCenterGravity(fgRef, hasDimensions);

  const handleEngineStop = useCallback(() => {
    if (!hasFittedRef.current && fgRef.current) {
      fgRef.current.zoomToFit(400);
      hasFittedRef.current = true;
    }
  }, []);

  const handleNodeClick = useCallback(
    (node: IArtifactGraphEntity) => {
      onNodeClick?.(mapNodeToValue(node));
    },
    [onNodeClick, mapNodeToValue],
  );

  const nodeVal = useCallback(
    (node: ArtifactGraphNode) => node.__radius ?? MinNodeRadius,
    [],
  );

  /** Escapes plain-text node labels for ForceGraph's HTML tooltip renderer. */
  const getEscapedNodeLabel = useCallback(
    (node: ArtifactGraphNode) => escape(getNodeLabel(node)),
    [getNodeLabel],
  );

  // Empty label hides the tooltip, so relations without a type show nothing
  const getLinkLabel = useCallback(
    (link: ArtifactGraphLink) => link.type ?? '',
    [],
  );

  return (
    <div
      ref={containerRef}
      className={cn('relative flex-1 min-h-0 h-full', !show && 'hidden')}
    >
      {hasDimensions && (
        <ForceGraph2D
          ref={fgRef}
          width={dimensions.width}
          height={dimensions.height}
          graphData={graphData}
          nodeRelSize={1}
          nodeColor={nodeColor}
          nodeVal={nodeVal}
          cooldownTicks={100}
          nodeLabel={getEscapedNodeLabel}
          autoPauseRedraw={false}
          onEngineStop={handleEngineStop}
          onNodeClick={handleNodeClick}
          onNodeHover={handleNodeHover}
          nodeCanvasObject={paintNode}
          nodeCanvasObjectMode={nodeCanvasObjectMode}
          linkColor={getLinkColor}
          linkWidth={getLinkWidth}
          linkLabel={getLinkLabel}
        />
      )}
      {totalEntities !== undefined && returnedEntities !== undefined && (
        <div className="absolute top-2 right-2 z-10 rounded-md border border-border-button bg-bg-card px-2 py-1 text-xs text-text-secondary">
          {t('knowledgeCompilation.graphEntityCount', {
            returned: returnedEntities,
            total: totalEntities,
          })}
        </div>
      )}
    </div>
  );
}

const MemoizedArtifactForceGraph = memo(ArtifactForceGraph) as <
  TNodeValue = IArtifactGraphEntity,
>(
  props: ArtifactForceGraphProps<TNodeValue>,
) => React.ReactElement;

export { MemoizedArtifactForceGraph as ArtifactForceGraph };
export default MemoizedArtifactForceGraph;