feat!: rebuild version history and customize snapshot actions

docs/package.json

@@ -73,7 +73,7 @@
     "@uppy/xhr-upload": "^3.4.0",
     "@vercel/analytics": "^1.6.1",
     "@y-sweet/react": "^0.6.3",
-    "@y/prosemirror": "^2.0.0-6",
+    "@y/prosemirror": "^2.0.0-12",
     "@y/protocols": "^1.0.6-rc.1",
     "@y/websocket": "^4.0.0-3",
     "@y/y": "^14.0.0-rc.23",
@@ -113,7 +113,8 @@
     "yjs": "^13.6.27",
     "zod": "^4.3.5",
     "@blocknote/xl-typst-exporter": "workspace:*",
-    "@blocknote/xl-typst-compiler": "workspace:*"
+    "@blocknote/xl-typst-compiler": "workspace:*",
+    "y-prosemirror": "^1.3.7"
   },
   "devDependencies": {
     "@blocknote/code-block": "workspace:*",

examples/07-collaboration/10-suggestion-multi-editor/.bnexample.json

@@ -6,7 +6,7 @@
   "dependencies": {
     "@y/protocols": "^1.0.6-rc.1",
     "@y/y": "^14.0.0-rc.23",
-    "@y/prosemirror": "^2.0.0-6",
+    "@y/prosemirror": "^2.0.0-12",
     "@y/websocket": "^4.0.0-rc.2"
   }
 }

examples/07-collaboration/10-suggestion-multi-editor/package.json

@@ -21,8 +21,8 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@y/protocols": "^1.0.6-rc.1",
-    "@y/y": "^14.0.0-rc.23",
-    "@y/prosemirror": "^2.0.0-6",
+    "@y/y": "^14.0.0-rc.26",
+    "@y/prosemirror": "^2.0.0-12",
     "@y/websocket": "^4.0.0-rc.2"
   },
   "devDependencies": {

examples/07-collaboration/10-suggestion-multi-editor/src/App.tsx

@@ -4,8 +4,9 @@ import "@blocknote/mantine/style.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import { useCreateBlockNote } from "@blocknote/react";
 import { Awareness } from "@y/protocols/awareness";
-import { withCollaboration } from "@blocknote/core/y";
+import { SuggestionsExtension, withCollaboration } from "@blocknote/core/y";
 import * as Y from "@y/y";
+import { useEffect } from "react";
 
 const doc = new Y.Doc();
 const provider = {
@@ -25,7 +26,7 @@ provider2.awareness.setLocalStateField("user", {
   color: "#6eeb83",
 });
 
-const attrs = new Y.Attributions();
+const attrs = Y.createContentMap();
 
 // Batch timestamps: reuse the same timestamp for edits from the same user
 // within a 10-second window of inactivity.
@@ -62,7 +63,7 @@ function getBatchedTimestamp(userName: string): number {
 function trackAttributions(
   trackedDoc: Y.Doc,
   userName: string,
-  attributions: Y.Attributions,
+  attributions: Y.ContentMap,
 ) {
   trackedDoc.on(
     "update",
@@ -105,7 +106,9 @@ suggestingProvider.awareness.setLocalStateField("user", {
   name: "Charlie",
   color: "#ffbc42",
 });
-const suggestingRenderer = Y.createDiffRenderer(doc, suggestingDoc, { attrs });
+const suggestingRenderer = Y.createDiffRenderer(doc, suggestingDoc, {
+  attributions: attrs,
+});
 suggestingRenderer.suggestionMode = false;
 
 const suggestionModeDoc = new Y.Doc({ isSuggestionDoc: true });
@@ -117,7 +120,7 @@ suggestionModeProvider.awareness.setLocalStateField("user", {
   color: "#ee6352",
 });
 const suggestionModeRenderer = Y.createDiffRenderer(doc, suggestionModeDoc, {
-  attrs,
+  attributions: attrs,
 });
 suggestionModeRenderer.suggestionMode = true;
 
@@ -151,13 +154,17 @@ setupTwoWaySync(suggestingDoc, suggestionModeDoc);
 function Editor({
   fragment,
   provider,
-  renderer,
+  suggestions,
   userName,
   userColor,
 }: {
-  fragment: Y.Type;
+  fragment: Y.Node;
   provider: { awareness?: Awareness };
-  renderer?: Y.DiffRenderer;
+  suggestions?: {
+    doc: Y.Doc;
+    renderer: Y.DiffRenderer;
+    mode: "view" | "edit";
+  };
   userName: string;
   userColor: string;
 }) {
@@ -166,12 +173,26 @@ function Editor({
       collaboration: {
         fragment,
         provider,
-        renderer,
+        suggestionDoc: suggestions?.doc,
+        renderer: suggestions?.renderer,
         user: { name: userName, color: userColor },
       },
     }),
   );
 
+  useEffect(() => {
+    if (!suggestions) {
+      return;
+    }
+
+    const extension = editor.getExtension(SuggestionsExtension)!;
+    if (suggestions.mode === "edit") {
+      extension.enableSuggestions();
+    } else {
+      extension.viewSuggestions();
+    }
+  }, [editor, suggestions]);
+
   return <BlockNoteView editor={editor} />;
 }
 
@@ -217,19 +238,27 @@ export default function App() {
         <div style={{ flex: 1 }}>
           View Suggestions (Charlie)
           <Editor
-            fragment={suggestingDoc.get("doc")}
+            fragment={doc.get("doc")}
             provider={suggestingProvider}
-            renderer={suggestingRenderer}
+            suggestions={{
+              doc: suggestingDoc,
+              renderer: suggestingRenderer,
+              mode: "view",
+            }}
             userName="Charlie"
             userColor="#ffbc42"
           />
         </div>
         <div style={{ flex: 1 }}>
           Suggestion Mode (Debbie)
           <Editor
-            fragment={suggestionModeDoc.get("doc")}
+            fragment={doc.get("doc")}
             provider={suggestionModeProvider}
-            renderer={suggestionModeRenderer}
+            suggestions={{
+              doc: suggestionModeDoc,
+              renderer: suggestionModeRenderer,
+              mode: "edit",
+            }}
             userName="Debbie"
             userColor="#ee6352"
           />

examples/07-collaboration/11-versioning-yjs13/.bnexample.json

@@ -1,11 +1,12 @@
 {
   "playground": true,
-  "docs": true,
+  "docs": false,
   "author": "yousefed",
   "tags": ["Advanced", "Development", "Collaboration"],
   "dependencies": {
     "y-websocket": "^2.1.0",
     "yjs": "^13.6.27",
-    "lib0": "^0.2.99"
+    "lib0": "^0.2.99",
+    "y-prosemirror": "^1.3.7"
   }
 }

examples/07-collaboration/11-versioning-yjs13/README.md

@@ -1,8 +1,8 @@
-# Local Storage Versioning (yjs v13)
+# Local Storage Versioning (Yjs v13, Experimental)
 
-This example shows how to use the `VersioningExtension` with collaborative editing using `yjs` (v13). Snapshots are stored in localStorage using Yjs state updates.
+This experimental playground example shows how to use the `VersioningExtension` with collaborative editing using Yjs v13. Snapshots are stored in localStorage using Yjs state updates.
 
-**Try it out:** Edit the document, then click the "Version History" button to open the sidebar. From there you can save snapshots, preview older versions, rename them, and restore them.
+The sidebar opens on a document with a few versions already in its history, so you can preview and rename them. Comparison and restore are not supported. The editor is read-only while the sidebar is open: close it to edit the document, then reopen it with the "History" button and press "Save version" to add a version of your own.
 
 **Relevant Docs:**
 

examples/07-collaboration/11-versioning-yjs13/index.html

@@ -5,7 +5,7 @@
       name="viewport"
       content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"
     />
-    <title>Local Storage Versioning (yjs v13)</title>
+    <title>Local Storage Versioning (Yjs v13, Experimental)</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
     </script>

examples/07-collaboration/11-versioning-yjs13/package.json

@@ -22,7 +22,8 @@
     "react-dom": "^19.2.3",
     "y-websocket": "^2.1.0",
     "yjs": "^13.6.27",
-    "lib0": "^0.2.99"
+    "lib0": "^0.2.99",
+    "y-prosemirror": "^1.3.7"
   },
   "devDependencies": {
     "@types/react": "^19.2.3",

examples/07-collaboration/11-versioning-yjs13/src/App.tsx

@@ -2,42 +2,61 @@ import "@blocknote/core/fonts/inter.css";
 import { withCollaboration } from "@blocknote/core/yjs";
 import { VersioningExtension } from "@blocknote/core/extensions";
 import { createYjsVersioningAdapter } from "@blocknote/core/yjs";
-import { localStorageEndpoints } from "./localStorageEndpoints";
 import {
-  BlockNoteViewEditor,
-  useCreateBlockNote,
-  useExtensionState,
-} from "@blocknote/react";
+  hasStoredVersions,
+  localStorageEndpoints,
+  storeVersions,
+} from "./localStorageEndpoints";
+import { BlockNoteViewEditor, useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
+import { useState } from "react";
 
 import * as Y from "yjs";
 import { WebsocketProvider } from "y-websocket";
 import { toBase64, fromBase64 } from "lib0/buffer";
 
-import { VersionHistorySidebar } from "./VersionHistorySidebar";
+import { VersioningSidebar } from "@blocknote/react/versioning";
+import {
+  blocksToUpdate,
+  DAY_MS,
+  LIVE_DOCUMENT,
+  SAMPLE_HISTORY,
+} from "./sampleVersions";
 import "./style.css";
 
 const roomName = "blocknote-versioning-yjs-example";
+const FRAGMENT_NAME = "document-store";
 // localStorage key for the live ("current version") document. Snapshots are
 // persisted separately by `localStorageEndpoints`; this keeps the live doc
 // itself across refreshes since the demo has no server-side persistence.
 const DOC_STORAGE_KEY = "blocknote-versioning-yjs-current-doc";
 const doc = new Y.Doc();
-const fragment = doc.getXmlFragment("document-store");
+const fragment = doc.getXmlFragment(FRAGMENT_NAME);
+
+// Persist the full document state on every change.
+doc.on("update", () => {
+  localStorage.setItem(DOC_STORAGE_KEY, toBase64(Y.encodeStateAsUpdate(doc)));
+});
 
 // Restore the persisted live document before the editor is created, so it
 // adopts the stored content instead of starting empty.
 const persistedDoc = localStorage.getItem(DOC_STORAGE_KEY);
 if (persistedDoc) {
   Y.applyUpdate(doc, fromBase64(persistedDoc));
+} else if (!hasStoredVersions()) {
+  // First visit: seed a few named versions so the history has something to
+  // show, and open on the newest state of the same document.
+  storeVersions(
+    SAMPLE_HISTORY.map((version) => ({
+      name: version.name,
+      createdAt: Date.now() - version.daysAgo * DAY_MS,
+      content: blocksToUpdate(version.blocks, FRAGMENT_NAME),
+    })),
+  );
+  Y.applyUpdate(doc, blocksToUpdate(LIVE_DOCUMENT, FRAGMENT_NAME));
 }
 
-// Persist the full document state on every change.
-doc.on("update", () => {
-  localStorage.setItem(DOC_STORAGE_KEY, toBase64(Y.encodeStateAsUpdate(doc)));
-});
-
 const provider = new WebsocketProvider(
   "wss://demos.yjs.dev/ws",
   roomName,
@@ -59,29 +78,37 @@ export default function App() {
         // automatically, so we add VersioningExtension manually and use
         // createYjsVersioningAdapter to bridge the Yjs v13 preview logic.
         VersioningExtension((editor) => ({
-          ...createYjsVersioningAdapter(editor, { fragment } as any),
+          ...createYjsVersioningAdapter(editor, { fragment }),
           endpoints: localStorageEndpoints,
         })),
       ],
     }),
   );
 
-  const { previewedSnapshotId } = useExtensionState(VersioningExtension, {
-    editor,
-  });
+  const [showSidebar, setShowSidebar] = useState(true);
 
   return (
     <div className="wrapper">
-      <BlockNoteView
-        editor={editor}
-        editable={previewedSnapshotId === undefined}
-        renderEditor={false}
-      >
+      {/* No `editable` prop: the sidebar makes the editor read-only for as long
+          as it's open, and restores it on close. */}
+      <BlockNoteView editor={editor} renderEditor={false}>
         <div className="layout">
           <div className="editor-panel">
             <BlockNoteViewEditor />
+            {!showSidebar && (
+              <button
+                className="show-history-button"
+                onClick={() => setShowSidebar(true)}
+              >
+                History
+              </button>
+            )}
           </div>
-          <VersionHistorySidebar />
+          {showSidebar && (
+            <div className={"sidebar-section"}>
+              <VersioningSidebar onClose={() => setShowSidebar(false)} />
+            </div>
+          )}
         </div>
       </BlockNoteView>
     </div>