Skip to content

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

20.5 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 { Authorization } from '@/constants/authorization';
import { useGetKnowledgeSearchParams } from '@/hooks/route-hook';
import { useGetPipelineResultSearchParams } from '@/pages/dataflow-result/hooks';
import api, { restAPIv1 } from '@/utils/api';
import { getAuthorization } from '@/utils/authorization-util';
import jsPreviewExcel from '@js-preview/excel';
import { useDebounceFn, useSize } from 'ahooks';
import axios from 'axios';
import JSZip from 'jszip';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import * as XLSX from 'xlsx';

// ZIP file header bytes "PK"
const ZIP_HEADER_0 = 0x50;
const ZIP_HEADER_1 = 0x4b;

export const isZipLikeBlob = async (blob: Blob): Promise<boolean> => {
  try {
    const headerSlice = blob.slice(0, 4);
    const buf = await headerSlice.arrayBuffer();
    const bytes = new Uint8Array(buf);
    return (
      bytes.length >= 2 &&
      bytes[0] === ZIP_HEADER_0 &&
      bytes[1] === ZIP_HEADER_1
    );
  } catch (e) {
    console.error('Failed to inspect blob header', e);
    return false;
  }
};

export const useDocumentResizeObserver = () => {
  const [containerWidth, setContainerWidth] = useState<number>();
  const [containerRef, setContainerRef] = useState<HTMLElement | null>(null);
  const size = useSize(containerRef);

  const onResize = useCallback((width?: number) => {
    if (width) {
      setContainerWidth(width);
    }
  }, []);

  useEffect(() => {
    onResize(size?.width);
  }, [size?.width, onResize]);

  return { containerWidth, setContainerRef };
};

function highlightPattern(text: string, pattern: string, pageNumber: number) {
  if (pageNumber === 2) {
    return `<mark>${text}</mark>`;
  }
  if (text.trim() !== '' && pattern.match(text)) {
    // return pattern.replace(text, (value) => `<mark>${value}</mark>`);
    return `<mark>${text}</mark>`;
  }
  return text.replace(pattern, (value) => `<mark>${value}</mark>`);
}

export const useHighlightText = (searchText: string = '') => {
  const textRenderer = useCallback(
    (textItem: any) => {
      return highlightPattern(textItem.str, searchText, textItem.pageNumber);
    },
    [searchText],
  );

  return textRenderer;
};

export const useGetDocumentUrl = (isAgent: boolean) => {
  const { documentId } = useGetKnowledgeSearchParams();
  const { createdBy, documentId: id } = useGetPipelineResultSearchParams();

  const url = useMemo(() => {
    if (isAgent) {
      return api.downloadFile + `?id=${id}&created_by=${createdBy}`;
    }
    return `${restAPIv1}/documents/${documentId}/preview`;
  }, [createdBy, documentId, id, isAgent]);

  return url;
};

export const useFetchDocument = () => {
  const fetchDocument = useCallback(async (api: string) => {
    const ret = await axios.get(api, {
      headers: {
        [Authorization]: getAuthorization(),
      },
      responseType: 'arraybuffer',
    });
    return ret;
  }, []);

  return { fetchDocument };
};

/**
 * WPS spreadsheets embed images in cells via the proprietary DISPIMG formula
 * (stored in xl/cellimages.xml). @js-preview/excel cannot evaluate this
 * formula and crashes with "Cannot read properties of undefined (reading
 * 'render')". This function strips DISPIMG formulas from worksheet XML,
 * replacing them with a text placeholder so the rest of the sheet renders.
 */
async function stripWpsDispImg(data: ArrayBuffer): Promise<ArrayBuffer> {
  const zip = await JSZip.loadAsync(data);

  const worksheetPaths = Object.keys(zip.files).filter((path) =>
    /^xl\/worksheets\/sheet\d+\.xml$/.test(path),
  );

  let modified = false;
  for (const path of worksheetPaths) {
    const file = zip.file(path);
    if (!file) continue;
    const xml = await file.async('string');
    if (!xml.includes('DISPIMG')) continue;

    modified = true;
    let cleaned = xml;
    // Remove <f> formula tags that reference DISPIMG
    cleaned = cleaned.replace(/<f\b[^>]*>[\s\S]*?DISPIMG[\s\S]*?<\/f>/g, '');
    // Replace cached <v> values that reference DISPIMG with a placeholder
    cleaned = cleaned.replace(/<v>[^<]*DISPIMG[^<]*<\/v>/g, '<v>[图片]</v>');
    zip.file(path, cleaned);
  }

  if (!modified) return data;
  return zip.generateAsync({
    type: 'arraybuffer',
    compression: 'DEFLATE',
  });
}

/**
 * ExcelJS (used internally by @js-preview/excel) fails to parse workbooks
 * whose root <workbook> element carries an XML namespace prefix (e.g.
 * <x:workbook> instead of <workbook>). This is common in files exported by
 * WPS Office or older Excel versions. The workbook-xform parser only sets
 * its model when the closing tag name is exactly "workbook", so a prefixed
 * root element leaves the model undefined and crashes with
 * "Cannot read properties of undefined (reading 'sheets')".
 *
 * When such a prefix is detected, re-serialize the file with SheetJS (which
 * always emits a standard, prefix-free xlsx) so ExcelJS can parse it.
 */
async function normalizeXlsxForExcelJS(
  data: ArrayBuffer,
): Promise<ArrayBuffer> {
  try {
    const zip = await JSZip.loadAsync(data);
    const workbookFile = zip.file('xl/workbook.xml');
    if (!workbookFile) return data;

    const xml = await workbookFile.async('string');
    // Detect a namespace prefix on the root <workbook> element, e.g. <x:workbook>
    if (!/<\w+:workbook[\s>]/.test(xml)) return data;

    const workbook = XLSX.read(data, { type: 'array' });
    return XLSX.write(workbook, {
      bookType: 'xlsx',
      type: 'array',
    }) as ArrayBuffer;
  } catch {
    // Not a valid ZIP, SheetJS can't parse, etc. - let the previewer
    // handle the original data and surface its own error.
    return data;
  }
}

/**
 * x-spreadsheet (used internally by @js-preview/excel) throws
 * "Worksheet name ... cannot include any of the following characters:
 * * ? : \ / [ ]" when a sheet name contains any of those characters. Files
 * generated programmatically (not through Excel/WPS UI) can carry such names
 * (e.g. "Visible:Data"), crashing the whole preview. Replace the illegal
 * characters with underscores in xl/workbook.xml so the previewer renders.
 */
async function sanitizeSheetNames(data: ArrayBuffer): Promise<ArrayBuffer> {
  const zip = await JSZip.loadAsync(data);
  const workbookFile = zip.file('xl/workbook.xml');
  if (!workbookFile) return data;

  const xml = await workbookFile.async('string');
  const cleaned = xml.replace(
    /(<sheet\b[^>]*\bname=")([^"]*)(")/g,
    (_match, prefix: string, name: string, suffix: string) =>
      prefix + name.replace(/[:\\/?*[\]]/g, '_') + suffix,
  );
  if (cleaned === xml) return data;

  zip.file('xl/workbook.xml', cleaned);
  return zip.generateAsync({
    type: 'arraybuffer',
    compression: 'DEFLATE',
  });
}

/** x-spreadsheet Data instance used by @js-preview/excel (not a plain object). */
type XsData = {
  styles: Record<string, unknown>[];
  rows: {
    setCell: (
      ri: number,
      ci: number,
      cell: { style?: number; text?: string },
      type?: 'all' | 'text' | 'format',
    ) => void;
    getCellOrNew: (ri: number, ci: number) => { style?: number; text?: string };
    getHeight?: (ri: number) => number;
    len?: number;
  };
  cols?: { len?: number };
  scroll?: { x: number; y: number };
};

type XsScrollbar = {
  move: (offset: { top?: number; left?: number }) => unknown;
};

type XsInstance = {
  datas: XsData[];
  reRender?: () => void;
  sheet: {
    resetData: (data: XsData) => void;
    data?: XsData & { row?: { height?: number } };
    reload?: () => void;
    table?: { render?: () => void };
    verticalScrollbar?: XsScrollbar;
    horizontalScrollbar?: XsScrollbar;
  };
  bottombar?: {
    items: HTMLElement[];
    clickSwap2?: (el: HTMLElement) => void;
  };
};

/** Locate inside @js-preview/excel: switch sheet, paint range via Data API, scroll. */
export function applyExcelSourceLocate(
  previewer: ReturnType<typeof jsPreviewExcel.init>,
  positions: number[][],
) {
  const xs = (previewer as { xs?: XsInstance }).xs;
  if (!xs?.datas?.length) return;
  const ranges = positions.flatMap((pos) => {
    if (
      !Array.isArray(pos) ||
      pos.length < 5 ||
      !pos.slice(0, 5).every((v) => Number.isInteger(v) && v > 0)
    )
      return [];
    const sheetIdx = pos[0] - 1;
    const data = xs.datas[sheetIdx];
    if (!data?.styles || !data.rows?.setCell) return [];
    const r1 = pos[1] - 1;
    const r2 = Math.min(pos[2] - 1, (data.rows.len ?? Infinity) - 1);
    const c1 = pos[3] - 1;
    const c2 = Math.min(pos[4] - 1, (data.cols?.len ?? Infinity) - 1);
    if (r2 < r1 || c2 < c1) return [];
    return [{ sheetIdx, data, r1, r2, c1, c2 }];
  });
  const first = ranges[0];
  if (!first) return;
  const { sheetIdx, data, r1 } = first;

  // The spreadsheet canvas is always rendered on a light sheet background
  // regardless of app theme, so the locate highlight must use fixed light
  // colors rather than theme tokens (which resolve to near-white text in dark
  // mode and become invisible). Matches the yellow used by the PDF highlighter.
  const stylesBySheet = new Map<XsData, Map<string, number>>();
  for (const range of ranges) {
    let styles = stylesBySheet.get(range.data);
    if (!styles) {
      styles = new Map();
      stylesBySheet.set(range.data, styles);
    }
    for (let r = range.r1; r <= range.r2; r++) {
      for (let c = range.c1; c <= range.c2; c++) {
        const cell = range.data.rows.getCellOrNew(r, c);
        const original = range.data.styles[cell.style ?? -1] ?? {};
        if (original.bgcolor === '#ffe58f' && original.color === '#1a1a1a')
          continue;
        const highlight = { ...original, bgcolor: '#ffe58f', color: '#1a1a1a' };
        const key = JSON.stringify(highlight);
        let styleIdx = styles.get(key);
        if (styleIdx === undefined) {
          styleIdx = range.data.styles.push(highlight) - 1;
          styles.set(key, styleIdx);
        }
        range.data.rows.setCell(r, c, { style: styleIdx }, 'format');
      }
    }
  }

  // clickSwap2 must run even when the target sheet is already on screen: it is
  // the library's only hook that redraws images embedded in the sheet, and the
  // reRender/render/reload calls below each clear the canvas first.
  const tab = xs.bottombar?.items?.[sheetIdx];
  if (tab && typeof xs.bottombar?.clickSwap2 === 'function') {
    xs.bottombar.clickSwap2(tab);
  } else {
    xs.sheet.resetData(data);
  }

  const rowHeight =
    data.rows.getHeight?.(0) || xs.sheet.data?.row?.height || 24;
  let y = 0;
  for (let r = 0; r < r1; r++) {
    y += data.rows.getHeight?.(r) ?? rowHeight;
  }

  // Drive the scroll through the library scrollbar: setting data.scroll and
  // re-rendering directly moves the canvas but leaves the scrollbar thumb at
  // the top, so the user has to scroll down before they can scroll back up.
  // move() sets the native scroll element, whose scroll event updates
  // data.scroll and re-renders the table, keeping both in sync.
  const vScrollbar = xs.sheet.verticalScrollbar;
  if (vScrollbar?.move) {
    xs.sheet.horizontalScrollbar?.move?.({ left: 0 });
    vScrollbar.move({ top: y > 0 ? y - 1 : 0 });
    return;
  }

  data.scroll = { ...(data.scroll || { x: 0, y: 0 }), x: 0, y };
  if (xs.sheet.data && xs.sheet.data !== data) {
    xs.sheet.data.scroll = {
      ...(xs.sheet.data.scroll || { x: 0, y: 0 }),
      x: 0,
      y,
    };
  }
  xs.reRender?.();
  xs.sheet.table?.render?.();
  xs.sheet.reload?.();
}

export const useFetchExcel = (filePath: string, positions?: number[][]) => {
  const [status, setStatus] = useState(true);
  const { fetchDocument } = useFetchDocument();
  const [containerEl, setContainerEl] = useState<HTMLDivElement | null>(null);
  const size = useSize(containerEl);

  const previewerRef = useRef<ReturnType<typeof jsPreviewExcel.init> | null>(
    null,
  );
  // Cache the fetched ArrayBuffer so we don't re-fetch on every resize.
  const dataRef = useRef<ArrayBuffer | null>(null);
  const [dataReady, setDataReady] = useState(false);
  const positionsRef = useRef(positions);
  positionsRef.current = positions;
  const locateKey = JSON.stringify(positions ?? []);
  const locateTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);

  // @js-preview/excel reads the container's width/height at init time and
  // exposes no public resize method, so the only way to make the spreadsheet
  // track container size changes is to destroy + re-init the previewer.
  const renderPreview = useCallback(async () => {
    if (!containerEl || !dataRef.current) return;

    if (locateTimerRef.current != null) {
      clearTimeout(locateTimerRef.current);
      locateTimerRef.current = null;
    }
    if (previewerRef.current) {
      previewerRef.current.destroy();
      previewerRef.current = null;
    }

    const previewer = jsPreviewExcel.init(containerEl);
    previewerRef.current = previewer;

    try {
      await previewer.preview(dataRef.current);
      const currentPositions = positionsRef.current;
      if (currentPositions?.length) {
        // bottombar tabs are created during loadData; apply after paint.
        const run = () => {
          if (previewerRef.current !== previewer) return;
          applyExcelSourceLocate(previewer, currentPositions);
        };
        requestAnimationFrame(() => {
          run();
          locateTimerRef.current = setTimeout(run, 50);
        });
      }
      setStatus(true);
    } catch (e) {
      // oxlint-disable-next-line no-console
      console.warn('failed', e);
      // Defer destroy() so the library's pending setTimeout(0) callback
      // (scheduled by xs.loadData during its error handling) can access
      // workbookDataSource before we null it out. Destroying immediately
      // triggers a secondary "Cannot read properties of null (reading
      // '_worksheets')" error.
      previewerRef.current = null;
      setTimeout(() => {
        previewer.destroy();
      }, 0);
      setStatus(false);
    }
  }, [containerEl]);

  // Leading edge renders immediately on first data/size, trailing edge
  // collapses rapid resize bursts into a single re-render.
  const { run: debouncedRender } = useDebounceFn(renderPreview, {
    wait: 150,
    leading: true,
    trailing: true,
  });

  // Fetch the file once per url. On url change, drop cached data and the
  // existing previewer so the next render starts from a clean state.
  useEffect(() => {
    if (!filePath) return;

    setDataReady(false);
    setStatus(true);
    if (previewerRef.current) {
      previewerRef.current.destroy();
      previewerRef.current = null;
    }
    dataRef.current = null;

    let cancelled = false;
    (async () => {
      try {
        const jsonFile = await fetchDocument(filePath);
        if (cancelled) return;
        try {
          let data = jsonFile.data;
          data = await normalizeXlsxForExcelJS(data);
          data = await stripWpsDispImg(data);
          data = await sanitizeSheetNames(data);
          dataRef.current = data;
        } catch {
          // Not a valid ZIP or preprocessing failed — use original data
          dataRef.current = jsonFile.data;
        }
        setDataReady(true);
      } catch (e) {
        if (!cancelled) {
          // oxlint-disable-next-line no-console
          console.warn('failed to fetch', e);
          setStatus(false);
        }
      }
    })();
    return () => {
      cancelled = true;
    };
  }, [filePath, fetchDocument]);

  // Initial render + debounced re-render on container resize / locate target change.
  useEffect(() => {
    if (!dataReady || !containerEl) return;
    debouncedRender();
  }, [
    dataReady,
    containerEl,
    size?.width,
    size?.height,
    locateKey,
    debouncedRender,
  ]);

  // Tear down the previewer on unmount.
  useEffect(() => {
    return () => {
      if (locateTimerRef.current != null) {
        clearTimeout(locateTimerRef.current);
        locateTimerRef.current = null;
      }
      if (previewerRef.current) {
        previewerRef.current.destroy();
        previewerRef.current = null;
      }
    };
  }, []);

  return { status, containerRef: setContainerEl };
};

export const useCatchDocumentError = (url: string) => {
  const httpHeaders = useMemo(() => {
    return {
      [Authorization]: getAuthorization(),
    };
  }, []);
  const [error, setError] = useState<string>('');

  const fetchDocument = useCallback(async () => {
    try {
      const { data } = await axios.get(url, { headers: httpHeaders });
      // Only treat as error if response is JSON with an error code
      // Binary data (like PDF) won't have a code property
      if (
        data &&
        typeof data === 'object' &&
        'code' in data &&
        data.code !== 0
      ) {
        setError(data?.message || 'Failed to load document');
      }
    } catch (e) {
      // Network errors or non-2xx responses
      const errMsg = e instanceof Error ? e.message : 'Failed to load document';
      if (errMsg) {
        setError(errMsg);
      }
    }
  }, [url, httpHeaders]);
  useEffect(() => {
    fetchDocument();
  }, [fetchDocument]);

  return error;
};

const ZOOM_STEPS = [25, 50, 75, 100, 125, 150, 175, 200] as const;

const clampZoom = (scale: number, direction: 1 | -1): number => {
  const exactIdx = ZOOM_STEPS.indexOf(scale as (typeof ZOOM_STEPS)[number]);
  let idx: number;

  if (exactIdx >= 0) {
    // Already on a predefined step: move one step in the zoom direction.
    idx = exactIdx + direction;
  } else if (direction > 0) {
    // Between steps and zooming in: snap up to the next higher step. This
    // index is already the target, so it must not be advanced again.
    const next = ZOOM_STEPS.findIndex((v) => v > scale);
    idx = next < 0 ? ZOOM_STEPS.length - 1 : next;
  } else {
    // Between steps and zooming out: snap down to the next lower step.
    let prev = 0;
    for (let i = ZOOM_STEPS.length - 1; i >= 0; i--) {
      if (ZOOM_STEPS[i] < scale) {
        prev = i;
        break;
      }
    }
    idx = prev;
  }

  idx = Math.max(0, Math.min(ZOOM_STEPS.length - 1, idx));
  return ZOOM_STEPS[idx] ?? scale;
};

interface UseDocxPreviewZoomOptions {
  url: string;
  totalPages: number;
  pageWidthPx?: number;
  containerWidth?: number;
  paddingPx?: number;
  enabled?: boolean;
}

interface UseDocxPreviewZoomResult {
  zoomScale: number;
  minZoom: number;
  maxZoom: number;
  handleZoomIn: () => void;
  handleZoomOut: () => void;
  resetZoom: () => void;
}

export const useDocxPreviewZoom = ({
  url,
  totalPages,
  pageWidthPx,
  containerWidth,
  paddingPx = 32,
  enabled = true,
}: UseDocxPreviewZoomOptions): UseDocxPreviewZoomResult => {
  const [zoomScale, setZoomScale] = useState(100);
  const [hasUserZoomed, setHasUserZoomed] = useState(false);
  const [isInitialFitPending, setIsInitialFitPending] = useState(true);

  const resetZoom = useCallback(() => {
    setZoomScale(100);
    setHasUserZoomed(false);
    setIsInitialFitPending(true);
  }, []);

  useEffect(() => {
    resetZoom();
  }, [url, resetZoom]);

  const handleZoomIn = useCallback(() => {
    setHasUserZoomed(true);
    setZoomScale((s) => clampZoom(s, 1));
  }, []);

  const handleZoomOut = useCallback(() => {
    setHasUserZoomed(true);
    setZoomScale((s) => clampZoom(s, -1));
  }, []);

  // Fit the page width to the container on first paint and on resize,
  // unless the user has manually changed the zoom level.
  useEffect(() => {
    if (!enabled || totalPages <= 0 || !containerWidth || !pageWidthPx) {
      return;
    }

    const availableWidth = Math.max(0, containerWidth - paddingPx);
    if (availableWidth <= 0) {
      return;
    }

    const fitScale = Math.floor((availableWidth / pageWidthPx) * 100);
    const clampedFitScale = Math.min(100, fitScale);

    if (isInitialFitPending) {
      setZoomScale(clampedFitScale);
      setIsInitialFitPending(false);
    } else if (!hasUserZoomed) {
      setZoomScale(clampedFitScale);
    }
  }, [
    enabled,
    totalPages,
    containerWidth,
    pageWidthPx,
    paddingPx,
    isInitialFitPending,
    hasUserZoomed,
  ]);

  return {
    zoomScale,
    minZoom: ZOOM_STEPS[0],
    maxZoom: ZOOM_STEPS[ZOOM_STEPS.length - 1],
    handleZoomIn,
    handleZoomOut,
    resetZoom,
  };
};