@tiptap/y-tiptap 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Kevin Jahns <kevin.jahns@protonmail.com>.
+Copyright (c) 2025 Tiptap GmbH.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# y-tiptap
+
+> [Tiptap](http://tiptap.dev/) Binding for [Yjs](https://github.com/yjs/yjs)
+
+This binding maps a Y.XmlFragment to the ProseMirror state.
+
+## Features
+
+* Sync ProseMirror state
+* Shared Cursors
+* Shared Undo / Redo (each client has its own undo-/redo-history)
+* Successfully recovers when concurrents edit result in an invalid document schema
+
+### Example
+
+```js
+import { ySyncPlugin, yCursorPlugin, yUndoPlugin, undo, redo, initProseMirrorDoc } from '@tiptap/y-tiptap'
+import { exampleSetup } from 'prosemirror-example-setup'
+import { keymap } from '@tiptap/pm/keymap'
+..
+
+const type = ydocument.get('prosemirror', Y.XmlFragment)
+const { doc, mapping } = initProseMirrorDoc(type, schema)
+
+const prosemirrorView = new EditorView(document.querySelector('#editor'), {
+  state: EditorState.create({
+    doc,
+    schema,
+    plugins: [
+        ySyncPlugin(type, { mapping }),
+        yCursorPlugin(provider.awareness),
+        yUndoPlugin(),
+        keymap({
+          'Mod-z': undo,
+          'Mod-y': redo,
+          'Mod-Shift-z': redo
+        })
+      ].concat(exampleSetup({ schema }))
+  })
+})
+```
+
+#### Remote Cursors
+
+The shared cursors depend on the Awareness instance that is exported by most providers. The [Awareness protocol](https://github.com/yjs/y-protocols#awareness-protocol) handles non-permanent data like the number of users, their user names, their cursor location, and their colors. You can change the name and color of the user like this:
+
+```js
+example.binding.awareness.setLocalStateField('user', { color: '#008833', name: 'My real name' })
+```
+
+In order to render cursor information you need to embed custom CSS for the user icon. This is a template that you can use for styling cursor information.
+
+```css
+/* this is a rough fix for the first cursor position when the first paragraph is empty */
+.ProseMirror > .ProseMirror-yjs-cursor:first-child {
+  margin-top: 16px;
+}
+.ProseMirror p:first-child, .ProseMirror h1:first-child, .ProseMirror h2:first-child, .ProseMirror h3:first-child, .ProseMirror h4:first-child, .ProseMirror h5:first-child, .ProseMirror h6:first-child {
+  margin-top: 16px
+}
+/* This gives the remote user caret. The colors are automatically overwritten*/
+.ProseMirror-yjs-cursor {
+  position: relative;
+  margin-left: -1px;
+  margin-right: -1px;
+  border-left: 1px solid black;
+  border-right: 1px solid black;
+  border-color: orange;
+  word-break: normal;
+  pointer-events: none;
+}
+/* This renders the username above the caret */
+.ProseMirror-yjs-cursor > div {
+  position: absolute;
+  top: -1.05em;
+  left: -1px;
+  font-size: 13px;
+  background-color: rgb(250, 129, 0);
+  font-family: serif;
+  font-style: normal;
+  font-weight: normal;
+  line-height: normal;
+  user-select: none;
+  color: white;
+  padding-left: 2px;
+  padding-right: 2px;
+  white-space: nowrap;
+}
+```
+
+You can also overwrite the default Widget dom by specifying a cursor builder in the yCursorPlugin
+
+```js
+/**
+ * This function receives the remote users "user" awareness state.
+ */
+export const myCursorBuilder = user => {
+  const cursor = document.createElement('span')
+  cursor.classList.add('ProseMirror-yjs-cursor')
+  cursor.setAttribute('style', `border-color: ${user.color}`)
+  const userDiv = document.createElement('div')
+  userDiv.setAttribute('style', `background-color: ${user.color}`)
+  userDiv.insertBefore(document.createTextNode(user.name), null)
+  cursor.insertBefore(userDiv, null)
+  return cursor
+}
+
+const prosemirrorView = new EditorView(document.querySelector('#editor'), {
+  state: EditorState.create({
+    schema,
+    plugins: [
+        ySyncPlugin(type),
+        yCursorPlugin(provider.awareness, { cursorBuilder: myCursorBuilder }),
+        yUndoPlugin(),
+        keymap({
+          'Mod-z': undo,
+          'Mod-y': redo,
+          'Mod-Shift-z': redo
+        })
+      ].concat(exampleSetup({ schema }))
+  })
+})
+```
+
+#### Utilities
+
+The package includes a number of utility methods for converting back and forth between
+a Y.Doc and Prosemirror compatible data structures. These can be useful for persisting
+to a datastore or for importing existing documents.
+
+> _Note_: Serializing and deserializing to JSON will not store collaboration history
+> steps and as such should not be used as the primary storage. You will still need
+> to store the Y.Doc binary update format.
+
+```js
+import { prosemirrorToYDoc } from '@tiptap/y-tiptap'
+
+// Pass JSON previously output from Prosemirror
+const doc = Node.fromJSON(schema, {
+  type: "doc",
+  content: [...]
+})
+const ydoc = prosemirrorToYDoc(doc)
+```
+
+Because JSON is a common usecase there is an equivalent method that skips the need
+to create a Prosemirror Node.
+
+```js
+import { prosemirrorJSONToYDoc } from '@tiptap/y-tiptap'
+
+// Pass JSON previously output from Prosemirror
+const ydoc = prosemirrorJSONToYDoc(schema, {
+  type: "doc",
+  content: [...]
+})
+```
+
+```js
+import { yDocToProsemirror } from '@tiptap/y-tiptap'
+
+// apply binary updates from elsewhere
+const ydoc = new Y.Doc()
+ydoc.applyUpdate(update)
+
+const node = yDocToProsemirror(schema, ydoc)
+```
+
+Because JSON is a common usecase there is an equivalent method that outputs JSON
+directly, this method does not require the Prosemirror schema.
+
+```js
+import { yDocToProsemirrorJSON } from '@tiptap/y-tiptap'
+
+// apply binary updates from elsewhere
+const ydoc = new Y.Doc()
+ydoc.applyUpdate(update)
+
+const node = yDocToProsemirrorJSON(ydoc)
+```
+
+### Undo/Redo
+
+The package exports `undo` and `redo` commands which can be used in place of
+[prosemirror-history](https://prosemirror.net/docs/ref/#history) by mapping the
+mod-Z/Y keys - see [ProseMirror](https://github.com/yjs/yjs-demos/blob/main/prosemirror/prosemirror.js#L29)
+and [Tiptap](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration/src/collaboration.ts)
+examples.
+
+Undo and redo are be scoped to the local client, so one peer won't undo another's
+changes. See [Y.UndoManager](https://docs.yjs.dev/api/undo-manager) for more details.
+
+Just like prosemirror-history, you can set a transaction's `addToHistory` meta property
+to false to prevent that transaction from being rolled back by undo. This can be helpful for programmatic
+document changes that aren't initiated by the user.
+
+```js
+tr.setMeta("addToHistory", false);
+```
+
+### License
+
+[The MIT License](./LICENSE) ©  Kevin Jahns, Tiptap GmbH

package/dist/src/lib.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Utility method to convert a Prosemirror Doc Node into a Y.Doc.
+ *
+ * This can be used when importing existing content to Y.Doc for the first time,
+ * note that this should not be used to rehydrate a Y.Doc from a database once
+ * collaboration has begun as all history will be lost
+ *
+ * @param {Node} doc
+ * @param {string} xmlFragment
+ * @return {Y.Doc}
+ */
+export function prosemirrorToYDoc(doc: Node, xmlFragment?: string): Y.Doc;
+/**
+ * Utility method to update an empty Y.XmlFragment with content from a Prosemirror Doc Node.
+ *
+ * This can be used when importing existing content to Y.Doc for the first time,
+ * note that this should not be used to rehydrate a Y.Doc from a database once
+ * collaboration has begun as all history will be lost
+ *
+ * Note: The Y.XmlFragment does not need to be part of a Y.Doc document at the time that this
+ * method is called, but it must be added before any other operations are performed on it.
+ *
+ * @param {Node} doc prosemirror document.
+ * @param {Y.XmlFragment} [xmlFragment] If supplied, an xml fragment to be
+ *   populated from the prosemirror state; otherwise a new XmlFragment will be created.
+ * @return {Y.XmlFragment}
+ */
+export function prosemirrorToYXmlFragment(doc: Node, xmlFragment?: Y.XmlFragment): Y.XmlFragment;
+/**
+ * Utility method to convert Prosemirror compatible JSON into a Y.Doc.
+ *
+ * This can be used when importing existing content to Y.Doc for the first time,
+ * note that this should not be used to rehydrate a Y.Doc from a database once
+ * collaboration has begun as all history will be lost
+ *
+ * @param {Schema} schema
+ * @param {any} state
+ * @param {string} xmlFragment
+ * @return {Y.Doc}
+ */
+export function prosemirrorJSONToYDoc(schema: Schema, state: any, xmlFragment?: string): Y.Doc;
+/**
+ * Utility method to convert Prosemirror compatible JSON to a Y.XmlFragment
+ *
+ * This can be used when importing existing content to Y.Doc for the first time,
+ * note that this should not be used to rehydrate a Y.Doc from a database once
+ * collaboration has begun as all history will be lost
+ *
+ * @param {Schema} schema
+ * @param {any} state
+ * @param {Y.XmlFragment} [xmlFragment] If supplied, an xml fragment to be
+ *   populated from the prosemirror state; otherwise a new XmlFragment will be created.
+ * @return {Y.XmlFragment}
+ */
+export function prosemirrorJSONToYXmlFragment(schema: Schema, state: any, xmlFragment?: Y.XmlFragment): Y.XmlFragment;
+/**
+ * @deprecated Use `yXmlFragmentToProseMirrorRootNode` instead
+ *
+ * Utility method to convert a Y.Doc to a Prosemirror Doc node.
+ *
+ * @param {Schema} schema
+ * @param {Y.Doc} ydoc
+ * @return {Node}
+ */
+export function yDocToProsemirror(schema: Schema, ydoc: Y.Doc): Node;
+/**
+ *
+ * @deprecated Use `yXmlFragmentToProseMirrorRootNode` instead
+ *
+ * Utility method to convert a Y.XmlFragment to a Prosemirror Doc node.
+ *
+ * @param {Schema} schema
+ * @param {Y.XmlFragment} xmlFragment
+ * @return {Node}
+ */
+export function yXmlFragmentToProsemirror(schema: Schema, xmlFragment: Y.XmlFragment): Node;
+/**
+ *
+ * @deprecated Use `yXmlFragmentToProseMirrorRootNode` instead
+ *
+ * Utility method to convert a Y.Doc to Prosemirror compatible JSON.
+ *
+ * @param {Y.Doc} ydoc
+ * @param {string} xmlFragment
+ * @return {Record<string, any>}
+ */
+export function yDocToProsemirrorJSON(ydoc: Y.Doc, xmlFragment?: string): Record<string, any>;
+/**
+ * @deprecated Use `yXmlFragmentToProseMirrorRootNode` instead
+ *
+ * Utility method to convert a Y.Doc to Prosemirror compatible JSON.
+ *
+ * @param {Y.XmlFragment} xmlFragment The fragment, which must be part of a Y.Doc.
+ * @return {Record<string, any>}
+ */
+export function yXmlFragmentToProsemirrorJSON(xmlFragment: Y.XmlFragment): Record<string, any>;
+export function setMeta(view: any, key: any, value: any): void;
+export function absolutePositionToRelativePosition(pos: number, type: Y.XmlFragment, mapping: ProsemirrorMapping): any;
+export function relativePositionToAbsolutePosition(y: Y.Doc, documentType: Y.XmlFragment, relPos: any, mapping: ProsemirrorMapping): null | number;
+export function yXmlFragmentToProseMirrorFragment(yXmlFragment: Y.XmlFragment, schema: Schema): Fragment;
+export function yXmlFragmentToProseMirrorRootNode(yXmlFragment: Y.XmlFragment, schema: Schema): Node;
+export function initProseMirrorDoc(yXmlFragment: Y.XmlFragment, schema: Schema): {
+    doc: Node;
+    mapping: ProsemirrorMapping;
+};
+/**
+ * Either a node if type is YXmlElement or an Array of text nodes if YXmlText
+ */
+export type ProsemirrorMapping = Map<Y.AbstractType<any>, Node | Array<Node>>;
+import { Node } from '@tiptap/pm/model';
+import * as Y from 'yjs';
+import { Schema } from '@tiptap/pm/model';
+import { Fragment } from '@tiptap/pm/model';

package/dist/src/plugins/cursor-plugin.d.ts

@@ -0,0 +1,17 @@
+export function defaultAwarenessStateFilter(currentClientId: number, userClientId: number, _user: any): boolean;
+export function defaultCursorBuilder(user: any): HTMLElement;
+export function defaultSelectionBuilder(user: any): import('@tiptap/pm/view').DecorationAttrs;
+export function createDecorations(state: any, awareness: Awareness, awarenessFilter: (arg0: number, arg1: number, arg2: any) => boolean, createCursor: (arg0: {
+    name: string;
+    color: string;
+}) => Element, createSelection: (arg0: {
+    name: string;
+    color: string;
+}) => import('@tiptap/pm/view').DecorationAttrs): any;
+export function yCursorPlugin(awareness: Awareness, { awarenessStateFilter, cursorBuilder, selectionBuilder, getSelection }?: {
+    awarenessStateFilter?: (arg0: any, arg1: any, arg2: any) => boolean;
+    cursorBuilder?: (arg0: any) => HTMLElement;
+    selectionBuilder?: (arg0: any) => import('@tiptap/pm/view').DecorationAttrs;
+    getSelection?: (arg0: any) => any;
+}, cursorStateField?: string): any;
+import { Awareness } from "y-protocols/awareness";

package/dist/src/plugins/keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The unique prosemirror plugin key for syncPlugin
+ *
+ * @public
+ */
+export const ySyncPluginKey: PluginKey<any>;
+/**
+ * The unique prosemirror plugin key for undoPlugin
+ *
+ * @public
+ */
+export const yUndoPluginKey: PluginKey<any>;
+/**
+ * The unique prosemirror plugin key for cursorPlugin
+ *
+ * @public
+ */
+export const yCursorPluginKey: PluginKey<any>;
+import { PluginKey } from '@tiptap/pm/state';

package/dist/src/plugins/sync-plugin.d.ts

@@ -0,0 +1,100 @@
+export const MarkPrefix: "_mark_";
+export function isVisible(item: Y.Item, snapshot?: Y.Snapshot): boolean;
+export function ySyncPlugin(yXmlFragment: Y.XmlFragment, { colors, colorMapping, permanentUserData, onFirstRender, mapping }?: YSyncOpts): any;
+export function getRelativeSelection(pmbinding: any, state: any): {
+    anchor: any;
+    head: any;
+};
+/**
+ * Binding for prosemirror.
+ *
+ * @protected
+ */
+export class ProsemirrorBinding {
+    /**
+     * @param {Y.XmlFragment} yXmlFragment The bind source
+     * @param {ProsemirrorMapping} mapping
+     */
+    constructor(yXmlFragment: Y.XmlFragment, mapping?: ProsemirrorMapping);
+    type: Y.XmlFragment;
+    /**
+     * this will be set once the view is created
+     * @type {any}
+     */
+    prosemirrorView: any;
+    mux: import("lib0/mutex").mutex;
+    mapping: ProsemirrorMapping;
+    _observeFunction: any;
+    /**
+     * @type {Y.Doc}
+     */
+    doc: Y.Doc;
+    /**
+     * current selection as relative positions in the Yjs model
+     */
+    beforeTransactionSelection: {
+        anchor: any;
+        head: any;
+    };
+    beforeAllTransactions: () => void;
+    afterAllTransactions: () => void;
+    _domSelectionInView: boolean;
+    /**
+     * Create a transaction for changing the prosemirror state.
+     *
+     * @returns
+     */
+    get _tr(): any;
+    _isLocalCursorInView(): boolean;
+    _isDomSelectionInView(): boolean;
+    /**
+     * @param {Y.Snapshot} snapshot
+     * @param {Y.Snapshot} prevSnapshot
+     */
+    renderSnapshot(snapshot: Y.Snapshot, prevSnapshot: Y.Snapshot): void;
+    unrenderSnapshot(): void;
+    _forceRerender(): void;
+    /**
+     * @param {Y.Snapshot|Uint8Array} snapshot
+     * @param {Y.Snapshot|Uint8Array} prevSnapshot
+     * @param {Object} pluginState
+     */
+    _renderSnapshot(snapshot: Y.Snapshot | Uint8Array, prevSnapshot: Y.Snapshot | Uint8Array, pluginState: any): void;
+    /**
+     * @param {Array<Y.YEvent<any>>} events
+     * @param {Y.Transaction} transaction
+     */
+    _typeChanged(events: Array<Y.YEvent<any>>, transaction: Y.Transaction): void;
+    _prosemirrorChanged(doc: any): void;
+    /**
+     * View is ready to listen to changes. Register observers.
+     * @param {any} prosemirrorView
+     */
+    initView(prosemirrorView: any): void;
+    destroy(): void;
+}
+export function createNodeFromYElement(el: Y.XmlElement, schema: any, mapping: ProsemirrorMapping, snapshot?: Y.Snapshot, prevSnapshot?: Y.Snapshot, computeYChange?: (arg0: 'removed' | 'added', arg1: Y.ID) => any): PModel.Node | null;
+export function updateYFragment(y: {
+    transact: Function;
+}, yDomFragment: Y.XmlFragment, pNode: any, mapping: ProsemirrorMapping): void;
+/**
+ * Either a node if type is YXmlElement or an Array of text nodes if YXmlText
+ */
+export type ProsemirrorMapping = Map<Y.AbstractType<any>, PModel.Node | Array<PModel.Node>>;
+export type ColorDef = {
+    light: string;
+    dark: string;
+};
+export type YSyncOpts = {
+    colors?: Array<ColorDef>;
+    colorMapping?: Map<string, ColorDef>;
+    permanentUserData?: Y.PermanentUserData | null;
+    mapping?: ProsemirrorMapping;
+    /**
+     * Fired when the content from Yjs is initially rendered to ProseMirror
+     */
+    onFirstRender?: Function;
+};
+export type NormalizedPNodeContent = Array<Array<PModel.Node> | PModel.Node>;
+import * as Y from 'yjs';
+import * as PModel from '@tiptap/pm/model';

package/dist/src/plugins/undo-plugin.d.ts

@@ -0,0 +1,15 @@
+export function undo(state: any): boolean;
+export function redo(state: any): boolean;
+export const defaultProtectedNodes: Set<string>;
+export function defaultDeleteFilter(item: any, protectedNodes: any): boolean;
+export function yUndoPlugin({ protectedNodes, trackedOrigins, undoManager }?: {
+    protectedNodes?: Set<string>;
+    trackedOrigins?: any[];
+    undoManager?: any;
+}): Plugin<{
+    undoManager: any;
+    prevSel: any;
+    hasUndoOps: boolean;
+    hasRedoOps: boolean;
+}>;
+import { Plugin } from '@tiptap/pm/state';

package/dist/src/y-tiptap.d.ts

@@ -0,0 +1,5 @@
+export * from "./plugins/cursor-plugin.js";
+export * from "./plugins/undo-plugin.js";
+export * from "./plugins/keys.js";
+export { ySyncPlugin, isVisible, getRelativeSelection, ProsemirrorBinding, updateYFragment } from "./plugins/sync-plugin.js";
+export { absolutePositionToRelativePosition, relativePositionToAbsolutePosition, setMeta, prosemirrorJSONToYDoc, yDocToProsemirrorJSON, yDocToProsemirror, prosemirrorToYDoc, prosemirrorJSONToYXmlFragment, yXmlFragmentToProsemirrorJSON, yXmlFragmentToProsemirror, prosemirrorToYXmlFragment, yXmlFragmentToProseMirrorRootNode, yXmlFragmentToProseMirrorFragment, initProseMirrorDoc } from "./lib.js";