feat: pages editor sync logic solidified

web/app/[workspaceSlug]/(projects)/projects/(detail)/[projectId]/pages/(detail)/[pageId]/page.tsx

@@ -21,6 +21,7 @@ import { cn } from "@/helpers/common.helper";
 // hooks
 import { usePage, useProjectPages } from "@/hooks/store";
 import { useAppRouter } from "@/hooks/use-app-router";
+import { usePageDescription } from "@/hooks/use-page-description";
 
 const PageDetailsPage = observer(() => {
   // states
@@ -50,6 +51,16 @@ const PageDetailsPage = observer(() => {
     }
   );
 
+  // project-description
+  const { handleDescriptionChange, isDescriptionReady, pageDescriptionYJS, handleSaveDescription } = usePageDescription(
+    {
+      editorRef,
+      page,
+      projectId,
+      workspaceSlug,
+    }
+  );
+
   if ((!page || !id) && !pageDetailsError)
     return (
       <div className="size-full grid place-items-center">
@@ -78,7 +89,7 @@ const PageDetailsPage = observer(() => {
   const handleDuplicatePage = async () => {
     const formData: Partial<TPage> = {
       name: "Copy of " + name,
-      description_html: description_html ?? "<p></p>",
+      description_html: editorRef.current?.getHTML() ?? description_html ?? "<p></p>",
       access,
     };
 
@@ -104,6 +115,7 @@ const PageDetailsPage = observer(() => {
             editorReady={editorReady}
             readOnlyEditorReady={readOnlyEditorReady}
             handleDuplicatePage={handleDuplicatePage}
+            handleSaveDescription={handleSaveDescription}
             markings={markings}
             page={page}
             sidePeekVisible={sidePeekVisible}
@@ -118,6 +130,9 @@ const PageDetailsPage = observer(() => {
             page={page}
             sidePeekVisible={sidePeekVisible}
             updateMarkings={updateMarkings}
+            handleDescriptionChange={handleDescriptionChange}
+            isDescriptionReady={isDescriptionReady}
+            pageDescriptionYJS={pageDescriptionYJS}
           />
           <IssuePeekOverview />
         </div>

web/core/components/pages/editor/editor-body.tsx

@@ -17,7 +17,6 @@ import { PageContentBrowser, PageContentLoader, PageEditorTitle } from "@/compon
 import { cn } from "@/helpers/common.helper";
 // hooks
 import { useMember, useMention, useUser, useWorkspace } from "@/hooks/store";
-import { usePageDescription } from "@/hooks/use-page-description";
 import { usePageFilters } from "@/hooks/use-page-filters";
 // plane web components
 import { IssueEmbedCard } from "@/plane-web/components/pages";
@@ -37,6 +36,9 @@ type Props = {
   handleEditorReady: (value: boolean) => void;
   handleReadOnlyEditorReady: (value: boolean) => void;
   updateMarkings: (description_html: string) => void;
+  handleDescriptionChange: (update: Uint8Array, source?: string | undefined) => void;
+  isDescriptionReady: boolean;
+  pageDescriptionYJS: Uint8Array | undefined;
 };
 
 export const PageEditorBody: React.FC<Props> = observer((props) => {
@@ -49,6 +51,9 @@ export const PageEditorBody: React.FC<Props> = observer((props) => {
     page,
     sidePeekVisible,
     updateMarkings,
+    handleDescriptionChange,
+    isDescriptionReady,
+    pageDescriptionYJS,
   } = props;
   // router
   const { workspaceSlug, projectId } = useParams();
@@ -67,13 +72,7 @@ export const PageEditorBody: React.FC<Props> = observer((props) => {
   const { isContentEditable, updateTitle, setIsSubmitting } = page;
   const projectMemberIds = projectId ? getProjectMemberIds(projectId.toString()) : [];
   const projectMemberDetails = projectMemberIds?.map((id) => getUserDetails(id) as IUserLite);
-  // project-description
-  const { handleDescriptionChange, isDescriptionReady, pageDescriptionYJS } = usePageDescription({
-    editorRef,
-    page,
-    projectId,
-    workspaceSlug,
-  });
+
   // use-mention
   const { mentionHighlights, mentionSuggestions } = useMention({
     workspaceSlug: workspaceSlug?.toString() ?? "",

web/core/components/pages/editor/header/extra-options.tsx

@@ -22,10 +22,11 @@ type Props = {
   handleDuplicatePage: () => void;
   page: IPage;
   readOnlyEditorRef: React.RefObject<EditorReadOnlyRefApi>;
+  handleSaveDescription: (initSyncVectorAsUpdate?: Uint8Array | undefined) => Promise<void>;
 };
 
 export const PageExtraOptions: React.FC<Props> = observer((props) => {
-  const { editorRef, handleDuplicatePage, page, readOnlyEditorRef } = props;
+  const { editorRef, handleDuplicatePage, page, readOnlyEditorRef, handleSaveDescription } = props;
   // states
   const [gptModalOpen, setGptModal] = useState(false);
   // store hooks
@@ -80,6 +81,7 @@ export const PageExtraOptions: React.FC<Props> = observer((props) => {
         editorRef={isContentEditable ? editorRef.current : readOnlyEditorRef.current}
         handleDuplicatePage={handleDuplicatePage}
         page={page}
+        handleSaveDescription={handleSaveDescription}
       />
     </div>
   );

web/core/components/pages/editor/header/mobile-root.tsx

@@ -17,6 +17,7 @@ type Props = {
   setSidePeekVisible: (sidePeekState: boolean) => void;
   editorReady: boolean;
   readOnlyEditorReady: boolean;
+  handleSaveDescription: (initSyncVectorAsUpdate?: Uint8Array | undefined) => Promise<void>;
 };
 
 export const PageEditorMobileHeaderRoot: React.FC<Props> = observer((props) => {
@@ -30,6 +31,7 @@ export const PageEditorMobileHeaderRoot: React.FC<Props> = observer((props) => {
     page,
     sidePeekVisible,
     setSidePeekVisible,
+    handleSaveDescription,
   } = props;
   // derived values
   const { isContentEditable } = page;
@@ -52,6 +54,7 @@ export const PageEditorMobileHeaderRoot: React.FC<Props> = observer((props) => {
         </div>
         <PageExtraOptions
           editorRef={editorRef}
+          handleSaveDescription={handleSaveDescription}
           handleDuplicatePage={handleDuplicatePage}
           page={page}
           readOnlyEditorRef={readOnlyEditorRef}

web/core/components/pages/editor/header/options-dropdown.tsx

@@ -18,10 +18,11 @@ type Props = {
   editorRef: EditorRefApi | EditorReadOnlyRefApi | null;
   handleDuplicatePage: () => void;
   page: IPage;
+  handleSaveDescription: (initSyncVectorAsUpdate?: Uint8Array | undefined) => Promise<void>;
 };
 
 export const PageOptionsDropdown: React.FC<Props> = observer((props) => {
-  const { editorRef, handleDuplicatePage, page } = props;
+  const { editorRef, handleDuplicatePage, page, handleSaveDescription } = props;
   // store values
   const {
     archived_at,
@@ -75,6 +76,11 @@ export const PageOptionsDropdown: React.FC<Props> = observer((props) => {
       })
     );
 
+  const saveDescriptionYJSAndPerformAction = (action: () => void) => async () => {
+    await handleSaveDescription();
+    action();
+  };
+
   // menu items list
   const MENU_ITEMS: {
     key: string;
@@ -116,21 +122,21 @@ export const PageOptionsDropdown: React.FC<Props> = observer((props) => {
     },
     {
       key: "make-a-copy",
-      action: handleDuplicatePage,
+      action: saveDescriptionYJSAndPerformAction(handleDuplicatePage),
       label: "Make a copy",
       icon: Copy,
       shouldRender: canCurrentUserDuplicatePage,
     },
     {
       key: "lock-unlock-page",
-      action: is_locked ? handleUnlockPage : handleLockPage,
+      action: is_locked ? handleUnlockPage : saveDescriptionYJSAndPerformAction(handleLockPage),
       label: is_locked ? "Unlock page" : "Lock page",
       icon: is_locked ? LockOpen : Lock,
       shouldRender: canCurrentUserLockPage,
     },
     {
       key: "archive-restore-page",
-      action: archived_at ? handleRestorePage : handleArchivePage,
+      action: archived_at ? handleRestorePage : saveDescriptionYJSAndPerformAction(handleArchivePage),
       label: archived_at ? "Restore page" : "Archive page",
       icon: archived_at ? ArchiveRestoreIcon : ArchiveIcon,
       shouldRender: canCurrentUserArchivePage,

web/core/components/pages/editor/header/root.tsx

@@ -19,6 +19,7 @@ type Props = {
   setSidePeekVisible: (sidePeekState: boolean) => void;
   editorReady: boolean;
   readOnlyEditorReady: boolean;
+  handleSaveDescription: (initSyncVectorAsUpdate?: Uint8Array | undefined) => Promise<void>;
 };
 
 export const PageEditorHeaderRoot: React.FC<Props> = observer((props) => {
@@ -32,6 +33,7 @@ export const PageEditorHeaderRoot: React.FC<Props> = observer((props) => {
     page,
     sidePeekVisible,
     setSidePeekVisible,
+    handleSaveDescription,
   } = props;
   // derived values
   const { isContentEditable } = page;
@@ -63,12 +65,14 @@ export const PageEditorHeaderRoot: React.FC<Props> = observer((props) => {
         <PageExtraOptions
           editorRef={editorRef}
           handleDuplicatePage={handleDuplicatePage}
+          handleSaveDescription={handleSaveDescription}
           page={page}
           readOnlyEditorRef={readOnlyEditorRef}
         />
       </div>
       <div className="md:hidden">
         <PageEditorMobileHeaderRoot
+          handleSaveDescription={handleSaveDescription}
           editorRef={editorRef}
           readOnlyEditorRef={readOnlyEditorRef}
           editorReady={editorReady}

web/core/hooks/use-auto-save.tsx

@@ -0,0 +1,51 @@
+import { useEffect, useRef } from "react";
+import { debounce } from "lodash"; // You can use lodash or implement your own debounce function
+
+const AUTO_SAVE_TIME = 10000;
+
+const useAutoSave = (handleSaveDescription: () => void) => {
+  const intervalIdRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    intervalIdRef.current = setInterval(handleSaveDescription, AUTO_SAVE_TIME);
+
+    return () => {
+      if (intervalIdRef.current) {
+        clearInterval(intervalIdRef.current);
+      }
+    };
+  }, [handleSaveDescription]);
+
+  useEffect(() => {
+    // debounce the function so that excesive calls to handleSaveDescription don't cause multiple calls to the server
+    const debouncedSave = debounce(() => {
+      handleSaveDescription();
+
+      if (intervalIdRef.current) {
+        // clear the interval after saving manually
+        clearInterval(intervalIdRef.current);
+        // then reset the interval for auto-save to keep working
+        intervalIdRef.current = setInterval(handleSaveDescription, AUTO_SAVE_TIME);
+      }
+    }, 500);
+
+    const handleSave = (e: KeyboardEvent) => {
+      const { ctrlKey, metaKey, key } = e;
+      const cmdClicked = ctrlKey || metaKey;
+
+      if (cmdClicked && key.toLowerCase() === "s") {
+        e.preventDefault();
+        e.stopPropagation();
+        debouncedSave();
+      }
+    };
+
+    window.addEventListener("keydown", handleSave);
+
+    return () => {
+      window.removeEventListener("keydown", handleSave);
+    };
+  }, [handleSaveDescription]);
+};
+
+export default useAutoSave;

web/core/hooks/use-page-description.ts

@@ -1,19 +1,15 @@
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import useSWR from "swr";
-// editor
-import {
-  EditorRefApi,
-  applyUpdates,
-  generateJSONfromHTML,
-  mergeUpdates,
-  proseMirrorJSONToBinaryString,
-} from "@plane/editor";
+
 // hooks
+import { EditorRefApi, generateJSONfromHTML, proseMirrorJSONToBinaryString, applyUpdates } from "@plane/editor";
+import useAutoSave from "@/hooks/use-auto-save";
 import useReloadConfirmations from "@/hooks/use-reload-confirmation";
+
 // services
 import { ProjectPageService } from "@/services/page";
-// store
 import { IPage } from "@/store/pages/page";
+
 const projectPageService = new ProjectPageService();
 
 type Props = {
@@ -23,22 +19,27 @@ type Props = {
   workspaceSlug: string | string[] | undefined;
 };
 
-const AUTO_SAVE_TIME = 10000;
-
 export const usePageDescription = (props: Props) => {
   const { editorRef, page, projectId, workspaceSlug } = props;
-  // states
   const [isDescriptionReady, setIsDescriptionReady] = useState(false);
-  const [descriptionUpdates, setDescriptionUpdates] = useState<Uint8Array[]>([]);
-  // derived values
+  const [localDescriptionYJS, setLocalDescriptionYJS] = useState<Uint8Array>();
   const { isContentEditable, isSubmitting, updateDescription, setIsSubmitting } = page;
+
   const pageDescription = page.description_html;
   const pageId = page.id;
 
-  const { data: descriptionYJS, mutate: mutateDescriptionYJS } = useSWR(
+  const { data: pageDescriptionYJS, mutate: mutateDescriptionYJS } = useSWR(
     workspaceSlug && projectId && pageId ? `PAGE_DESCRIPTION_${workspaceSlug}_${projectId}_${pageId}` : null,
     workspaceSlug && projectId && pageId
-      ? () => projectPageService.fetchDescriptionYJS(workspaceSlug.toString(), projectId.toString(), pageId.toString())
+      ? async () => {
+          const encodedDescription = await projectPageService.fetchDescriptionYJS(
+            workspaceSlug.toString(),
+            projectId.toString(),
+            pageId.toString()
+          );
+          const decodedDescription = new Uint8Array(encodedDescription);
+          return decodedDescription;
+        }
       : null,
     {
       revalidateOnFocus: false,
@@ -46,15 +47,19 @@ export const usePageDescription = (props: Props) => {
       revalidateIfStale: false,
     }
   );
-  // description in Uint8Array format
-  const pageDescriptionYJS = useMemo(
-    () => (descriptionYJS ? new Uint8Array(descriptionYJS) : undefined),
-    [descriptionYJS]
-  );
 
-  // push the new updates to the updates array
-  const handleDescriptionChange = useCallback((updates: Uint8Array) => {
-    setDescriptionUpdates((prev) => [...prev, updates]);
+  // set the merged local doc by the provider to the react local state
+  const handleDescriptionChange = useCallback((update: Uint8Array, source?: string) => {
+    setLocalDescriptionYJS(() => {
+      // handle the initial sync case where indexeddb gives extra update, in
+      // this case we need to save the update to the DB
+      if (source && source === "initialSync") {
+        handleSaveDescription(update);
+      }
+
+      return update;
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   // if description_binary field is empty, convert description_html to yDoc and update the DB
@@ -62,98 +67,87 @@ export const usePageDescription = (props: Props) => {
   useEffect(() => {
     const changeHTMLToBinary = async () => {
       if (!pageDescriptionYJS || !pageDescription) return;
-      if (pageDescriptionYJS.byteLength === 0) {
+      if (pageDescriptionYJS.length === 0) {
         const { contentJSON, editorSchema } = generateJSONfromHTML(pageDescription ?? "<p></p>");
         const yDocBinaryString = proseMirrorJSONToBinaryString(contentJSON, "default", editorSchema);
+
         await updateDescription(yDocBinaryString, pageDescription ?? "<p></p>");
+
         await mutateDescriptionYJS();
+
         setIsDescriptionReady(true);
       } else setIsDescriptionReady(true);
     };
     changeHTMLToBinary();
   }, [mutateDescriptionYJS, pageDescription, pageDescriptionYJS, updateDescription]);
 
-  const handleSaveDescription = useCallback(async () => {
-    if (!isContentEditable) return;
+  const { setShowAlert } = useReloadConfirmations(true);
 
-    const applyUpdatesAndSave = async (latestDescription: any, updates: Uint8Array) => {
-      if (!workspaceSlug || !projectId || !pageId || !latestDescription) return;
-      // convert description to Uint8Array
-      const descriptionArray = new Uint8Array(latestDescription);
-      // apply the updates to the description
-      const combinedBinaryString = applyUpdates(descriptionArray, updates);
-      // get the latest html content
-      const descriptionHTML = editorRef.current?.getHTML() ?? "<p></p>";
-      // make a request to update the descriptions
-      await updateDescription(combinedBinaryString, descriptionHTML).finally(() => setIsSubmitting("saved"));
-    };
-
-    try {
-      setIsSubmitting("submitting");
-      // fetch the latest description
-      const latestDescription = await mutateDescriptionYJS();
-      // return if there are no updates
-      if (descriptionUpdates.length <= 0) {
-        setIsSubmitting("saved");
-        return;
-      }
-      // merge the updates array into one single update
-      const mergedUpdates = mergeUpdates(descriptionUpdates);
-      await applyUpdatesAndSave(latestDescription, mergedUpdates);
-      // reset the updates array to empty
-      setDescriptionUpdates([]);
-    } catch (error) {
-      setIsSubmitting("saved");
-      throw error;
+  useEffect(() => {
+    if (editorRef?.current?.hasUnsyncedChanges() || isSubmitting === "submitting") {
+      setShowAlert(true);
+    } else {
+      setShowAlert(false);
     }
-  }, [
-    descriptionUpdates,
-    editorRef,
-    isContentEditable,
-    mutateDescriptionYJS,
-    pageId,
-    projectId,
-    setIsSubmitting,
-    updateDescription,
-    workspaceSlug,
-  ]);
+  }, [setShowAlert, isSubmitting, editorRef, localDescriptionYJS]);
 
-  // auto-save updates every 10 seconds
-  // handle ctrl/cmd + S to save the description
-  useEffect(() => {
-    const intervalId = setInterval(handleSaveDescription, AUTO_SAVE_TIME);
+  // merge the description from remote to local state and only save if there are local changes
+  const handleSaveDescription = useCallback(
+    async (initSyncVectorAsUpdate?: Uint8Array) => {
+      const update = localDescriptionYJS ?? initSyncVectorAsUpdate;
 
-    const handleSave = (e: KeyboardEvent) => {
-      const { ctrlKey, metaKey, key } = e;
-      const cmdClicked = ctrlKey || metaKey;
+      if (update == null) return;
 
-      if (cmdClicked && key.toLowerCase() === "s") {
-        e.preventDefault();
-        e.stopPropagation();
-        handleSaveDescription();
+      if (!isContentEditable) return;
 
-        // reset interval timer
-        clearInterval(intervalId);
+      const applyUpdatesAndSave = async (latestDescription: Uint8Array, update: Uint8Array | undefined) => {
+        if (!workspaceSlug || !projectId || !pageId || !latestDescription || !update) return;
+
+        if (!editorRef.current?.hasUnsyncedChanges()) {
+          setIsSubmitting("saved");
+          return;
+        }
+
+        const combinedBinaryString = applyUpdates(latestDescription, update);
+        const descriptionHTML = editorRef.current?.getHTML() ?? "<p></p>";
+        await updateDescription(combinedBinaryString, descriptionHTML).finally(() => {
+          editorRef.current?.setSynced();
+          setShowAlert(false);
+          setIsSubmitting("saved");
+        });
+      };
+
+      try {
+        setIsSubmitting("submitting");
+        const latestDescription = await mutateDescriptionYJS();
+        if (latestDescription) {
+          await applyUpdatesAndSave(latestDescription, update);
+        }
+      } catch (error) {
+        setIsSubmitting("saved");
+        throw error;
       }
-    };
-    window.addEventListener("keydown", handleSave);
+    },
+    [
+      localDescriptionYJS,
+      setShowAlert,
+      editorRef,
+      isContentEditable,
+      mutateDescriptionYJS,
+      pageId,
+      projectId,
+      setIsSubmitting,
+      updateDescription,
+      workspaceSlug,
+    ]
+  );
 
-    return () => {
-      clearInterval(intervalId);
-      window.removeEventListener("keydown", handleSave);
-    };
-  }, [handleSaveDescription]);
-
-  // show a confirm dialog if there are any unsaved changes, or saving is going on
-  const { setShowAlert } = useReloadConfirmations(descriptionUpdates.length > 0 || isSubmitting === "submitting");
-  useEffect(() => {
-    if (descriptionUpdates.length > 0 || isSubmitting === "submitting") setShowAlert(true);
-    else setShowAlert(false);
-  }, [descriptionUpdates, isSubmitting, setShowAlert]);
+  useAutoSave(handleSaveDescription);
 
   return {
     handleDescriptionChange,
     isDescriptionReady,
     pageDescriptionYJS,
+    handleSaveDescription,
   };
 };