Merge pull request #4714 from baptisteArno/shared-type-yjs

Author: zbeyens

.changeset/odd-dancers-explain.md

@@ -0,0 +1,5 @@
+---
+'@platejs/yjs': minor
+---
+
+Add sharedType option

packages/yjs/README.md

@@ -206,6 +206,72 @@ This lets you create robust setups like:
 
 By default, content will be shown as soon as at least one provider is synced. If `waitForAllProviders` is set to `true`, content will only appear when all configured providers are in sync.
 
+### Using Nested Y.Doc Structures
+
+By default, the plugin uses `ydoc.get('content', Y.XmlText)` for storing editor content. However, you can use the `sharedType` option to work with nested structures from a parent Y.Doc:
+
+```typescript
+import { YjsPlugin } from '@platejs/yjs';
+import * as Y from 'yjs';
+
+// Create a parent document with multiple nested editors
+const parentDoc = new Y.Doc();
+
+// Create nested structures for different editors
+const editorsMap = parentDoc.getMap('editors');
+const mainEditorContent = new Y.XmlText();
+const sidebarEditorContent = new Y.XmlText();
+
+// Store them in the parent doc
+editorsMap.set('main', mainEditorContent);
+editorsMap.set('sidebar', sidebarEditorContent);
+
+// You can also store other data in the parent doc
+const metadata = parentDoc.getMap('metadata');
+metadata.set('title', 'My Document');
+metadata.set('author', 'John Doe');
+metadata.set('createdAt', Date.now());
+
+// Create the main editor with the nested shared type
+const mainEditor = createPlateEditor({
+  plugins: [
+    YjsPlugin.configure({
+      ydoc: parentDoc, // Pass the parent doc for provider sync
+      sharedType: mainEditorContent, // Use the specific nested content
+      providers: [
+        {
+          type: 'webrtc',
+          options: { roomName: 'my-document' },
+        },
+      ],
+    }),
+  ],
+});
+
+// Create a sidebar editor with its own nested shared type
+const sidebarEditor = createPlateEditor({
+  plugins: [
+    YjsPlugin.configure({
+      ydoc: parentDoc, // Same parent doc
+      sharedType: sidebarEditorContent, // Different nested content
+      providers: [], // Don't create new providers, parent is already synced
+    }),
+  ],
+});
+
+// Initialize with initial values - they'll be applied to the correct sharedTypes
+await mainEditor.api.yjs.init({
+  autoConnect: true,
+  value: [{ type: 'p', children: [{ text: 'Main editor content' }] }],
+});
+await sidebarEditor.api.yjs.init({
+  autoConnect: false,
+  value: [{ type: 'p', children: [{ text: 'Sidebar content' }] }],
+});
+```
+
+**Important:** When using a custom `sharedType`, the initial `value` passed to `init()` will be applied directly to that specific `sharedType`, not to the default `ydoc.get('content', Y.XmlText)`. This ensures each editor's initial content goes to the correct location in your nested structure.
+
 ### Cursor Support
 
 Collaborative cursors are enabled by default. You can customize their appearance and behavior:

packages/yjs/src/lib/BaseYjsPlugin.ts

@@ -1,4 +1,4 @@
-import { YjsEditor } from '@slate-yjs/core';
+import { slateNodesToInsertDelta, YjsEditor } from '@slate-yjs/core';
 import {
   type InitOptions,
   type Value,
@@ -42,6 +42,7 @@ export const BaseYjsPlugin = createTSlatePlugin<YjsConfig>({
     localOrigin: null,
     positionStorageOrigin: null,
     providers: [],
+    sharedType: null,
     ydoc: null!,
     onConnect: () => {},
     onDisconnect: () => {},
@@ -196,6 +197,7 @@ export const BaseYjsPlugin = createTSlatePlugin<YjsConfig>({
         _providers,
         awareness,
         providers: providerConfigsOrInstances = [],
+        sharedType: customSharedType,
         ydoc,
       } = options;
 
@@ -221,13 +223,23 @@ export const BaseYjsPlugin = createTSlatePlugin<YjsConfig>({
           initialNodes = editor.api.create.value();
         }
 
-        const initialDelta = await slateToDeterministicYjsState(
-          id ?? editor.id,
-          initialNodes
-        );
-        ydoc.transact(() => {
-          Y.applyUpdate(ydoc, initialDelta);
-        });
+        // Use custom sharedType if provided, otherwise use default 'content'
+        if (customSharedType) {
+          // Apply initial value directly to the custom shared type
+          const delta = slateNodesToInsertDelta(initialNodes);
+          ydoc.transact(() => {
+            customSharedType.applyDelta(delta);
+          });
+        } else {
+          // Use deterministic state for default 'content' key
+          const initialDelta = await slateToDeterministicYjsState(
+            id ?? editor.id,
+            initialNodes
+          );
+          ydoc.transact(() => {
+            Y.applyUpdate(ydoc, initialDelta);
+          });
+        }
       }
 
       // Final providers array that will contain both configured and custom providers

packages/yjs/src/lib/providers/types.ts

@@ -118,6 +118,26 @@ export type YjsConfig = PluginConfig<
      * specified. Passed to `withTCursors`.
      */
     cursors?: WithCursorsOptions | null;
+    /**
+     * Custom shared type to use for the editor content. If provided, this will
+     * be used instead of the default `ydoc.get('content', Y.XmlText)`. This
+     * allows you to use a nested Y.XmlText from a parent Y.Doc structure.
+     *
+     * @example
+     *   ```ts
+     *   const parentDoc = new Y.Doc();
+     *   const editorContent = parentDoc
+     *     .getMap('editors')
+     *     .get('main', Y.XmlText);
+     *
+     *   YjsPlugin.configure({
+     *     ydoc: parentDoc,
+     *     sharedType: editorContent,
+     *     // ...
+     *   });
+     *   ```;
+     */
+    sharedType?: Y.XmlText | null;
     /**
      * Shared Y.Doc instance. If not provided by the user in the initial config,
      * a new one will be created and assigned here by the plugin.

packages/yjs/src/lib/withPlateYjs.ts

@@ -16,11 +16,18 @@ export const withPlateYjs: ExtendEditor<YjsConfig> = ({
     SlateEditor &
     YjsEditorProps;
 
-  const { awareness, cursors, localOrigin, positionStorageOrigin, ydoc } =
-    getOptions();
+  const {
+    awareness,
+    cursors,
+    localOrigin,
+    positionStorageOrigin,
+    sharedType: customSharedType,
+    ydoc,
+  } = getOptions();
 
-  // Get the shared document type from the Y.Doc
-  const sharedType = ydoc!.get('content', Y.XmlText) as Y.XmlText;
+  // Use custom shared type if provided, otherwise get the default from Y.Doc
+  const sharedType =
+    customSharedType ?? (ydoc!.get('content', Y.XmlText) as Y.XmlText);
 
   // Apply core Yjs binding first
   editor = withTYjs(editor, sharedType, {