FE-376: Add a DOCX preview to the entity editor

apps/hash-frontend/folio.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The frontend's `moduleResolution: "node"` ignores package `exports`, so
+ * TypeScript cannot find these folio subpaths' own types. Webpack resolves
+ * them at runtime.
+ */
+
+/** `@stll/folio-react`'s types import this subpath. */
+declare module "@stll/folio-core/ai-edits" {
+  export * from "@stll/folio-core/dist/ai-edits/index";
+}
+
+/** Re-exports `@stll/folio-core`'s English messages. */
+declare module "@stll/folio-react/messages/en" {
+  export * from "@stll/folio-core/dist/i18n/messages/en.gen";
+}

apps/hash-frontend/package.json

@@ -69,6 +69,8 @@
     "@sigma/edge-curve": "patch:@sigma/edge-curve@npm%3A3.0.0-beta.16#~/.yarn/patches/@sigma-edge-curve-npm-3.0.0-beta.16-3d8b985284.patch",
     "@sigma/node-border": "3.0.0",
     "@sigma/node-image": "3.0.0",
+    "@stll/folio-core": "0.60.0",
+    "@stll/folio-react": "0.28.0",
     "@svgr/webpack": "8.1.0",
     "@tanstack/react-table": "8.21.3",
     "@tldraw/editor": "patch:@tldraw/editor@npm%3A2.0.0-alpha.12#~/.yarn/patches/@tldraw-editor-npm-2.0.0-alpha.12-ba59bf001c.patch",
@@ -114,10 +116,13 @@
     "prosemirror-collab": "1.3.0",
     "prosemirror-commands": "1.3.1",
     "prosemirror-dev-tools": "4.3.0",
+    "prosemirror-gapcursor": "1.4.1",
+    "prosemirror-history": "1.5.1",
     "prosemirror-inputrules": "1.2.0",
     "prosemirror-keymap": "1.2.0",
     "prosemirror-model": "1.25.12",
     "prosemirror-state": "1.4.4",
+    "prosemirror-tables": "1.8.5",
     "prosemirror-transform": "1.12.2",
     "prosemirror-view": "1.42.6",
     "react": "19.2.6",
@@ -144,8 +149,12 @@
     "signia-react": "0.1.5",
     "url-regex-safe": "4.0.0",
     "use-font-face-observer": "1.3.0",
+    "use-intl": "4.14.9",
     "uuid": "14.0.0",
     "web-worker": "1.4.1",
+    "y-prosemirror": "1.3.7",
+    "y-protocols": "1.0.7",
+    "yjs": "13.6.33",
     "zod": "4.4.3"
   },
   "devDependencies": {

apps/hash-frontend/src/pages/shared/docx-preview.tsx

@@ -0,0 +1,236 @@
+import { Box, CircularProgress, Stack, Typography } from "@mui/material";
+import * as Sentry from "@sentry/nextjs";
+import { useEffect, useEffectEvent, useRef, useState } from "react";
+import { FullScreen, useFullScreenHandle } from "react-full-screen";
+
+import {
+  ArrowDownLeftAndArrowUpRightToCenterIcon,
+  ArrowUpRightAndArrowDownLeftFromCenterIcon,
+  MagnifyingGlassMinusLightIcon,
+  MagnifyingGlassPlusLightIcon,
+} from "@hashintel/design-system";
+
+import { FolioDocument } from "./docx-preview/folio-document";
+import { fetchPresignedFileUrl } from "./fetch-presigned-file-url";
+import { FilePreviewPageNavigation } from "./file-preview-page-navigation";
+import { FilePreviewSearch } from "./file-preview-search";
+import { GrayToBlueIconButton } from "./gray-to-blue-icon-button";
+import { useFilePreviewMaxHeight } from "./use-file-preview-max-height";
+
+import type {
+  DocxDocumentControls,
+  DocxDocumentPages,
+} from "./docx-preview/folio-document";
+
+const zoomStep = 0.2;
+
+type DocxPreviewProps = {
+  /**
+   * Called when the document cannot be shown at all, so the caller can show
+   * the file's icon instead.
+   */
+  onUnavailable: () => void;
+  showSearch: boolean;
+  setShowSearch: (showSearch: boolean) => void;
+  url: string;
+};
+
+export const DocxPreview = ({
+  onUnavailable,
+  showSearch,
+  setShowSearch,
+  url,
+}: DocxPreviewProps) => {
+  const [data, setData] = useState<ArrayBuffer | null>(null);
+  const [pages, setPages] = useState<DocxDocumentPages>({
+    current: 1,
+    total: 0,
+  });
+  const [zoom, setZoom] = useState(1);
+  const [searchHitCount, setSearchHitCount] = useState(0);
+  const [selectedSearchHit, setSelectedSearchHit] = useState<number | null>(
+    null,
+  );
+
+  const controlsRef = useRef<DocxDocumentControls>(null);
+
+  const fullScreenHandle = useFullScreenHandle();
+
+  const height = useFilePreviewMaxHeight(fullScreenHandle.active);
+
+  /**
+   * An error before any page is laid out means the document cannot be shown.
+   * A later one, such as a part folio cannot draw, leaves the pages in place.
+   */
+  const handleError = (error: unknown) => {
+    Sentry.captureException(error);
+    if (!controlsRef.current?.hasPages()) {
+      onUnavailable();
+    }
+  };
+
+  const handleDownloadError = useEffectEvent(handleError);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    setData(null);
+
+    fetchPresignedFileUrl(url)
+      .then((presignedUrl) => fetch(presignedUrl))
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error(
+            `Downloading ${url} failed with HTTP ${response.status}`,
+          );
+        }
+        return response.arrayBuffer();
+      })
+      .then((buffer) => {
+        if (!cancelled) {
+          setData(buffer);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          handleDownloadError(error);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+
+  const selectSearchHit = (index: number | null) => {
+    setSelectedSearchHit(index);
+
+    if (index !== null) {
+      controlsRef.current?.showHit(index);
+    }
+  };
+
+  const search = (text: string, ignoreCase: boolean) => {
+    const hitCount = controlsRef.current?.search(text, ignoreCase) ?? 0;
+    setSearchHitCount(hitCount);
+    selectSearchHit(hitCount > 0 ? 0 : null);
+  };
+
+  return (
+    <FullScreen
+      className="full-height-and-width-for-react-full-screen"
+      handle={fullScreenHandle}
+    >
+      <Box
+        sx={({ palette }) => ({
+          background: palette.blue[10],
+          border: `1px solid ${palette.gray[30]}`,
+          borderRadius: 2,
+          height,
+          overflow: "hidden",
+          position: "relative",
+          width: "100%",
+        })}
+      >
+        {data ? (
+          <Sentry.ErrorBoundary onError={onUnavailable}>
+            <FolioDocument
+              controlsRef={controlsRef}
+              data={data}
+              onError={handleError}
+              onPagesChange={setPages}
+              onZoomChange={setZoom}
+            />
+          </Sentry.ErrorBoundary>
+        ) : (
+          <Stack alignItems="center" justifyContent="center" height="100%">
+            <CircularProgress />
+          </Stack>
+        )}
+        <Box sx={{ position: "absolute", top: 20, left: 20, zIndex: 100 }}>
+          <FilePreviewSearch
+            closeSearch={() => setShowSearch(false)}
+            onSearch={search}
+            onSelectHit={selectSearchHit}
+            selectedIndex={selectedSearchHit}
+            showSearch={showSearch}
+            total={searchHitCount}
+          />
+        </Box>
+        {pages.total > 0 && (
+          <>
+            <Stack
+              direction="row"
+              alignItems="center"
+              gap={1}
+              sx={{
+                background: "rgba(255, 255, 255, 0.9)",
+                borderRadius: "4px",
+                position: "absolute",
+                bottom: 20,
+                left: 20,
+                zIndex: 20,
+              }}
+            >
+              <FilePreviewPageNavigation
+                currentPage={pages.current}
+                onSelectPage={(pageNumber) =>
+                  controlsRef.current?.goToPage(pageNumber)
+                }
+                totalPages={pages.total}
+              />
+            </Stack>
+            <Stack
+              alignItems="center"
+              direction="row"
+              gap={1.5}
+              sx={{
+                position: "absolute",
+                bottom: 20,
+                right: 20,
+                zIndex: 20,
+              }}
+            >
+              <Stack direction="row" alignItems="center" gap={1}>
+                <GrayToBlueIconButton
+                  aria-label="Zoom out"
+                  onClick={() => controlsRef.current?.zoomBy(-zoomStep)}
+                >
+                  <MagnifyingGlassMinusLightIcon />
+                </GrayToBlueIconButton>
+                <GrayToBlueIconButton
+                  aria-label="Zoom in"
+                  onClick={() => controlsRef.current?.zoomBy(zoomStep)}
+                >
+                  <MagnifyingGlassPlusLightIcon />
+                </GrayToBlueIconButton>
+                <Typography
+                  sx={{
+                    fontSize: 12,
+                    color: ({ palette }) => palette.gray[70],
+                  }}
+                >
+                  {Math.round(zoom * 100)}%
+                </Typography>
+              </Stack>
+              <GrayToBlueIconButton
+                aria-label={
+                  fullScreenHandle.active ? "Exit full screen" : "Full screen"
+                }
+                onClick={
+                  fullScreenHandle[fullScreenHandle.active ? "exit" : "enter"]
+                }
+              >
+                {fullScreenHandle.active ? (
+                  <ArrowDownLeftAndArrowUpRightToCenterIcon />
+                ) : (
+                  <ArrowUpRightAndArrowDownLeftFromCenterIcon />
+                )}
+              </GrayToBlueIconButton>
+            </Stack>
+          </>
+        )}
+      </Box>
+    </FullScreen>
+  );
+};

apps/hash-frontend/src/pages/shared/docx-preview/folio-document.tsx

@@ -0,0 +1,97 @@
+import "@stll/folio-react/standalone.css";
+import { Box, CircularProgress } from "@mui/material";
+import { DocxEditor } from "@stll/folio-react";
+import { messages as folioMessages } from "@stll/folio-react/messages/en";
+import clamp from "lodash/clamp";
+import { useImperativeHandle, useRef } from "react";
+import { IntlProvider } from "use-intl";
+
+import { useReportedPages } from "./folio-document/use-reported-pages";
+import { useSearchHits } from "./folio-document/use-search-hits";
+
+import type { DocxDocumentPages } from "./folio-document/use-reported-pages";
+import type { DocxEditorRef } from "@stll/folio-react";
+import type { Ref } from "react";
+
+/**
+ * What `DocxPreview` can ask of the engine that draws the document. Nothing
+ * outside this file depends on the engine itself.
+ */
+export type DocxDocumentControls = {
+  /** Whether the engine shows at least one page. */
+  hasPages: () => boolean;
+  goToPage: (pageNumber: number) => void;
+  zoomBy: (step: number) => void;
+  /** Finds every hit of `text` and returns how many there are. */
+  search: (text: string, ignoreCase: boolean) => number;
+  showHit: (index: number) => void;
+};
+
+export type { DocxDocumentPages };
+
+type FolioDocumentProps = {
+  controlsRef: Ref<DocxDocumentControls>;
+  data: ArrayBuffer;
+  onError: (error: Error) => void;
+  onPagesChange: (pages: DocxDocumentPages) => void;
+  onZoomChange: (zoom: number) => void;
+};
+
+const minZoom = 0.25;
+const maxZoom = 4;
+
+export const FolioDocument = ({
+  controlsRef,
+  data,
+  onError,
+  onPagesChange,
+  onZoomChange,
+}: FolioDocumentProps) => {
+  const editorRef = useRef<DocxEditorRef>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const reportPages = useReportedPages(editorRef, onPagesChange);
+  const { search, showHit } = useSearchHits(editorRef);
+
+  useImperativeHandle(
+    controlsRef,
+    () => ({
+      /**
+       * folio reports one page before it has laid out any, so this looks for
+       * a drawn page instead.
+       */
+      hasPages: () => !!containerRef.current?.querySelector(".layout-page"),
+      goToPage: (pageNumber) => editorRef.current?.scrollToPage(pageNumber),
+      zoomBy: (step) => {
+        const editor = editorRef.current;
+        if (!editor) {
+          return;
+        }
+        editor.setZoom(clamp(editor.getZoom() + step, minZoom, maxZoom));
+        onZoomChange(editor.getZoom());
+      },
+      search,
+      showHit,
+    }),
+    [onZoomChange, search, showHit],
+  );
+
+  return (
+    <IntlProvider locale="en" messages={folioMessages}>
+      <Box ref={containerRef} sx={{ height: "100%" }}>
+        <DocxEditor
+          ref={editorRef}
+          autoOpenReviewSidebar={false}
+          documentBuffer={data}
+          enableWheelZoom={false}
+          keyboardShortcuts="none"
+          loadingIndicator={<CircularProgress />}
+          onError={onError}
+          onScrollTopChange={reportPages}
+          readOnly
+          style={{ height: "100%" }}
+        />
+      </Box>
+    </IntlProvider>
+  );
+};