add support for raw Y.js fragments to the collaboration extension

docs/src/demos/Examples/MultipleEditors/index.vue

@@ -70,7 +70,7 @@ export default {
         Text,
         Collaboration.configure({
           document: ydoc,
-          fragment: 'title',
+          field: 'title',
         }),
       ],
     })
@@ -84,7 +84,7 @@ export default {
         CustomTaskItem,
         Collaboration.configure({
           document: ydoc,
-          fragment: 'tasks',
+          field: 'tasks',
         }),
       ],
     })
@@ -96,7 +96,7 @@ export default {
         Text,
         Collaboration.configure({
           document: ydoc,
-          fragment: 'description',
+          field: 'description',
         }),
       ],
     })
@@ -112,17 +112,23 @@ export default {
 </script>
 
 <style lang="scss">
-ul[data-type="taskList"] {
-  list-style: none;
-  padding: 0;
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
 
-  li {
-    display: flex;
-    align-items: center;
+  ul[data-type="taskList"] {
+    list-style: none;
+    padding: 0;
 
-    > input {
-      flex: 0 0 auto;
-      margin-right: 0.5rem;
+    li {
+      display: flex;
+      align-items: center;
+
+      > input {
+        flex: 0 0 auto;
+        margin-right: 0.5rem;
+      }
     }
   }
 }
@@ -137,7 +143,7 @@ ul[data-type="taskList"] {
 
 .form__item {
   margin: 0 0 1rem;
-  padding: 1rem;
+  padding: 0.75rem 1rem;
   border-radius: 5px;
   border: 1px solid #e9ecef;
 

docs/src/docPages/api/extensions/collaboration.md

@@ -20,10 +20,11 @@ yarn add @tiptap/extension-collaboration yjs y-websocket
 ```
 
 ## Settings
-| Option   | Type     | Default   | Description                                                                               |
-| -------- | -------- | --------- | ----------------------------------------------------------------------------------------- |
-| document | `Object` | `null`    | An initialized Y.js document.                                                             |
-| fragment | `String` | `default` | Name of the Y.js fragment, can be changed to sync multiple fields with one Y.js document. |
+| Option   | Type     | Default     | Description                                                                             |
+| -------- | -------- | ----------- | --------------------------------------------------------------------------------------- |
+| document | `Object` | `null`      | An initialized Y.js document.                                                           |
+| field    | `String` | `'default'` | Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document. |
+| fragment | `Object` | `null`      | A raw Y.js fragment, can be used instead of `document` and `field`.                     |
 
 ## Commands
 | Command | Parameters | Description           |

docs/src/docPages/guide/collaborative-editing.md

@@ -236,13 +236,22 @@ And if you’d like to sync multiple fields with one Y.js document, just pass di
 // a tiptap instance for the field
 Collaboration.configure({
   document: ydoc,
-  fragment: 'title',
+  field: 'title',
 })
 
 // and another instance for the summary, both in the same Y.js document
 Collaboration.configure({
   document: ydoc,
-  fragment: 'summary',
+  field: 'summary',
+})
+```
+
+If your setup is somehow more complex, for example with nested fragments, you can pass a raw Y.js fragment too. `document` and `field` will be ignored then.
+
+```js
+// a raw Y.js fragment
+Collaboration.configure({
+  fragment: ydoc.getXmlFragment('custom'),
 })
 ```
 

packages/extension-collaboration/src/collaboration.ts

@@ -12,9 +12,13 @@ export interface CollaborationOptions {
    */
   document: any,
   /**
-   * A string to determine the fragment that should be used.
+   * Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document.
    */
-  fragment: string,
+  field: string,
+  /**
+   * A raw Y.js fragment, can be used instead of `document` and `field`.
+   */
+  fragment: any,
 }
 
 export const Collaboration = Extension.create({
@@ -22,7 +26,8 @@ export const Collaboration = Extension.create({
 
   defaultOptions: <CollaborationOptions>{
     document: null,
-    fragment: 'default',
+    field: 'default',
+    fragment: null,
   },
 
   addCommands() {
@@ -55,12 +60,12 @@ export const Collaboration = Extension.create({
   },
 
   addProseMirrorPlugins() {
+    const fragment = this.options.fragment
+      ? this.options.fragment
+      : this.options.document.getXmlFragment(this.options.field)
+
     return [
-      ySyncPlugin(
-        this.options.document.getXmlFragment(
-          this.options.fragment,
-        ),
-      ),
+      ySyncPlugin(fragment),
       yUndoPlugin(),
     ]
   },