@tiptap/extension-collaboration-caret 3.0.0-next.7

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+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,18 @@
+# @tiptap/extension-collaboration-caret
+
+[![Version](https://img.shields.io/npm/v/@tiptap/extension-collaboration-caret.svg?label=version)](https://www.npmjs.com/package/@tiptap/extension-collaboration-caret)
+[![Downloads](https://img.shields.io/npm/dm/@tiptap/extension-collaboration-caret.svg)](https://npmcharts.com/compare/tiptap?minimal=true)
+[![License](https://img.shields.io/npm/l/@tiptap/extension-collaboration-caret.svg)](https://www.npmjs.com/package/@tiptap/extension-collaboration-caret)
+[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
+
+## Introduction
+
+Tiptap is a headless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich text WYSIWYG editors, which is already in use at many well-known companies such as _New York Times_, _The Guardian_ or _Atlassian_.
+
+## Official Documentation
+
+Documentation can be found on the [Tiptap website](https://tiptap.dev).
+
+## License
+
+Tiptap is open sourced software licensed under the [MIT license](https://github.com/ueberdosis/tiptap/blob/main/LICENSE.md).

package/dist/index.cjs

@@ -0,0 +1,121 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CollaborationCaret: () => CollaborationCaret,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/collaboration-caret.ts
+var import_core = require("@tiptap/core");
+var import_y_tiptap = require("@tiptap/y-tiptap");
+var awarenessStatesToArray = (states) => {
+  return Array.from(states.entries()).map(([key, value]) => {
+    return {
+      clientId: key,
+      ...value.user
+    };
+  });
+};
+var defaultOnUpdate = () => null;
+var CollaborationCaret = import_core.Extension.create({
+  name: "collaborationCaret",
+  priority: 999,
+  addOptions() {
+    return {
+      provider: null,
+      user: {
+        name: null,
+        color: null
+      },
+      render: (user) => {
+        const cursor = document.createElement("span");
+        cursor.classList.add("collaboration-carets__caret");
+        cursor.setAttribute("style", `border-color: ${user.color}`);
+        const label = document.createElement("div");
+        label.classList.add("collaboration-carets__label");
+        label.setAttribute("style", `background-color: ${user.color}`);
+        label.insertBefore(document.createTextNode(user.name), null);
+        cursor.insertBefore(label, null);
+        return cursor;
+      },
+      selectionRender: import_y_tiptap.defaultSelectionBuilder,
+      onUpdate: defaultOnUpdate
+    };
+  },
+  onCreate() {
+    if (this.options.onUpdate !== defaultOnUpdate) {
+      console.warn(
+        '[tiptap warn]: DEPRECATED: The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret'
+      );
+    }
+    if (!this.options.provider) {
+      throw new Error('The "provider" option is required for the CollaborationCaret extension');
+    }
+  },
+  addStorage() {
+    return {
+      users: []
+    };
+  },
+  addCommands() {
+    return {
+      updateUser: (attributes) => () => {
+        this.options.user = attributes;
+        this.options.provider.awareness.setLocalStateField("user", this.options.user);
+        return true;
+      },
+      user: (attributes) => ({ editor }) => {
+        console.warn(
+          '[tiptap warn]: DEPRECATED: The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret'
+        );
+        return editor.commands.updateUser(attributes);
+      }
+    };
+  },
+  addProseMirrorPlugins() {
+    return [
+      (0, import_y_tiptap.yCursorPlugin)(
+        (() => {
+          this.options.provider.awareness.setLocalStateField("user", this.options.user);
+          this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states);
+          this.options.provider.awareness.on("update", () => {
+            this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states);
+          });
+          return this.options.provider.awareness;
+        })(),
+        {
+          cursorBuilder: this.options.render,
+          selectionBuilder: this.options.selectionRender
+        }
+      )
+    ];
+  }
+});
+
+// src/index.ts
+var index_default = CollaborationCaret;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CollaborationCaret
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/collaboration-caret.ts"],"sourcesContent":["import { CollaborationCaret } from './collaboration-caret.js'\n\nexport * from './collaboration-caret.js'\n\nexport default CollaborationCaret\n","import { Extension } from '@tiptap/core'\nimport type { DecorationAttrs } from '@tiptap/pm/view'\nimport { defaultSelectionBuilder, yCursorPlugin } from '@tiptap/y-tiptap'\n\ntype CollaborationCaretStorage = {\n  users: { clientId: number; [key: string]: any }[]\n}\n\nexport interface CollaborationCaretOptions {\n  /**\n   * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.\n   * @type {HocuspocusProvider | TiptapCloudProvider}\n   * @example new HocuspocusProvider()\n   */\n  provider: any\n\n  /**\n   * The user details object – feel free to add properties to this object as needed\n   * @example { name: 'John Doe', color: '#305500' }\n   */\n  user: Record<string, any>\n\n  /**\n   * A function that returns a DOM element for the cursor.\n   * @param user The user details object\n   * @example\n   * render: user => {\n   *  const cursor = document.createElement('span')\n   *  cursor.classList.add('collaboration-carets__caret')\n   *  cursor.setAttribute('style', `border-color: ${user.color}`)\n   *\n   *  const label = document.createElement('div')\n   *  label.classList.add('collaboration-carets__label')\n   *  label.setAttribute('style', `background-color: ${user.color}`)\n   *  label.insertBefore(document.createTextNode(user.name), null)\n   *\n   *  cursor.insertBefore(label, null)\n   *  return cursor\n   * }\n   */\n  render(user: Record<string, any>): HTMLElement\n\n  /**\n   * A function that returns a ProseMirror DecorationAttrs object for the selection.\n   * @param user The user details object\n   * @example\n   * selectionRender: user => {\n   * return {\n   *  nodeName: 'span',\n   *  class: 'collaboration-carets__selection',\n   *  style: `background-color: ${user.color}`,\n   *  'data-user': user.name,\n   * }\n   */\n  selectionRender(user: Record<string, any>): DecorationAttrs\n\n  /**\n   * @deprecated The \"onUpdate\" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret\n   */\n  onUpdate: (users: { clientId: number; [key: string]: any }[]) => null\n}\n\ndeclare module '@tiptap/core' {\n  interface Commands<ReturnType> {\n    collaborationCaret: {\n      /**\n       * Update details of the current user\n       * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })\n       */\n      updateUser: (attributes: Record<string, any>) => ReturnType\n      /**\n       * Update details of the current user\n       *\n       * @deprecated The \"user\" command is deprecated. Please use \"updateUser\" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret\n       */\n      user: (attributes: Record<string, any>) => ReturnType\n    }\n  }\n\n  interface Storage {\n    collaborationCaret: CollaborationCaretStorage\n  }\n}\n\nconst awarenessStatesToArray = (states: Map<number, Record<string, any>>) => {\n  return Array.from(states.entries()).map(([key, value]) => {\n    return {\n      clientId: key,\n      ...value.user,\n    }\n  })\n}\n\nconst defaultOnUpdate = () => null\n\n/**\n * This extension allows you to add collaboration carets to your editor.\n * @see https://tiptap.dev/api/extensions/collaboration-caret\n */\nexport const CollaborationCaret = Extension.create<CollaborationCaretOptions, CollaborationCaretStorage>({\n  name: 'collaborationCaret',\n\n  priority: 999,\n\n  addOptions() {\n    return {\n      provider: null,\n      user: {\n        name: null,\n        color: null,\n      },\n      render: user => {\n        const cursor = document.createElement('span')\n\n        cursor.classList.add('collaboration-carets__caret')\n        cursor.setAttribute('style', `border-color: ${user.color}`)\n\n        const label = document.createElement('div')\n\n        label.classList.add('collaboration-carets__label')\n        label.setAttribute('style', `background-color: ${user.color}`)\n        label.insertBefore(document.createTextNode(user.name), null)\n        cursor.insertBefore(label, null)\n\n        return cursor\n      },\n      selectionRender: defaultSelectionBuilder,\n      onUpdate: defaultOnUpdate,\n    }\n  },\n\n  onCreate() {\n    if (this.options.onUpdate !== defaultOnUpdate) {\n      console.warn(\n        '[tiptap warn]: DEPRECATED: The \"onUpdate\" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',\n      )\n    }\n    if (!this.options.provider) {\n      throw new Error('The \"provider\" option is required for the CollaborationCaret extension')\n    }\n  },\n\n  addStorage() {\n    return {\n      users: [],\n    }\n  },\n\n  addCommands() {\n    return {\n      updateUser: attributes => () => {\n        this.options.user = attributes\n\n        this.options.provider.awareness.setLocalStateField('user', this.options.user)\n\n        return true\n      },\n      user:\n        attributes =>\n        ({ editor }) => {\n          console.warn(\n            '[tiptap warn]: DEPRECATED: The \"user\" command is deprecated. Please use \"updateUser\" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',\n          )\n\n          return editor.commands.updateUser(attributes)\n        },\n    }\n  },\n\n  addProseMirrorPlugins() {\n    return [\n      yCursorPlugin(\n        (() => {\n          this.options.provider.awareness.setLocalStateField('user', this.options.user)\n\n          this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)\n\n          this.options.provider.awareness.on('update', () => {\n            this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)\n          })\n\n          return this.options.provider.awareness\n        })(),\n        {\n          cursorBuilder: this.options.render,\n          selectionBuilder: this.options.selectionRender,\n        },\n      ),\n    ]\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA0B;AAE1B,sBAAuD;AAkFvD,IAAM,yBAAyB,CAAC,WAA6C;AAC3E,SAAO,MAAM,KAAK,OAAO,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM;AACxD,WAAO;AAAA,MACL,UAAU;AAAA,MACV,GAAG,MAAM;AAAA,IACX;AAAA,EACF,CAAC;AACH;AAEA,IAAM,kBAAkB,MAAM;AAMvB,IAAM,qBAAqB,sBAAU,OAA6D;AAAA,EACvG,MAAM;AAAA,EAEN,UAAU;AAAA,EAEV,aAAa;AACX,WAAO;AAAA,MACL,UAAU;AAAA,MACV,MAAM;AAAA,QACJ,MAAM;AAAA,QACN,OAAO;AAAA,MACT;AAAA,MACA,QAAQ,UAAQ;AACd,cAAM,SAAS,SAAS,cAAc,MAAM;AAE5C,eAAO,UAAU,IAAI,6BAA6B;AAClD,eAAO,aAAa,SAAS,iBAAiB,KAAK,KAAK,EAAE;AAE1D,cAAM,QAAQ,SAAS,cAAc,KAAK;AAE1C,cAAM,UAAU,IAAI,6BAA6B;AACjD,cAAM,aAAa,SAAS,qBAAqB,KAAK,KAAK,EAAE;AAC7D,cAAM,aAAa,SAAS,eAAe,KAAK,IAAI,GAAG,IAAI;AAC3D,eAAO,aAAa,OAAO,IAAI;AAE/B,eAAO;AAAA,MACT;AAAA,MACA,iBAAiB;AAAA,MACjB,UAAU;AAAA,IACZ;AAAA,EACF;AAAA,EAEA,WAAW;AACT,QAAI,KAAK,QAAQ,aAAa,iBAAiB;AAC7C,cAAQ;AAAA,QACN;AAAA,MACF;AAAA,IACF;AACA,QAAI,CAAC,KAAK,QAAQ,UAAU;AAC1B,YAAM,IAAI,MAAM,wEAAwE;AAAA,IAC1F;AAAA,EACF;AAAA,EAEA,aAAa;AACX,WAAO;AAAA,MACL,OAAO,CAAC;AAAA,IACV;AAAA,EACF;AAAA,EAEA,cAAc;AACZ,WAAO;AAAA,MACL,YAAY,gBAAc,MAAM;AAC9B,aAAK,QAAQ,OAAO;AAEpB,aAAK,QAAQ,SAAS,UAAU,mBAAmB,QAAQ,KAAK,QAAQ,IAAI;AAE5E,eAAO;AAAA,MACT;AAAA,MACA,MACE,gBACA,CAAC,EAAE,OAAO,MAAM;AACd,gBAAQ;AAAA,UACN;AAAA,QACF;AAEA,eAAO,OAAO,SAAS,WAAW,UAAU;AAAA,MAC9C;AAAA,IACJ;AAAA,EACF;AAAA,EAEA,wBAAwB;AACtB,WAAO;AAAA,UACL;AAAA,SACG,MAAM;AACL,eAAK,QAAQ,SAAS,UAAU,mBAAmB,QAAQ,KAAK,QAAQ,IAAI;AAE5E,eAAK,QAAQ,QAAQ,uBAAuB,KAAK,QAAQ,SAAS,UAAU,MAAM;AAElF,eAAK,QAAQ,SAAS,UAAU,GAAG,UAAU,MAAM;AACjD,iBAAK,QAAQ,QAAQ,uBAAuB,KAAK,QAAQ,SAAS,UAAU,MAAM;AAAA,UACpF,CAAC;AAED,iBAAO,KAAK,QAAQ,SAAS;AAAA,QAC/B,GAAG;AAAA,QACH;AAAA,UACE,eAAe,KAAK,QAAQ;AAAA,UAC5B,kBAAkB,KAAK,QAAQ;AAAA,QACjC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF,CAAC;;;AD1LD,IAAO,gBAAQ;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,88 @@
+import { Extension } from '@tiptap/core';
+import { DecorationAttrs } from '@tiptap/pm/view';
+
+type CollaborationCaretStorage = {
+    users: {
+        clientId: number;
+        [key: string]: any;
+    }[];
+};
+interface CollaborationCaretOptions {
+    /**
+     * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.
+     * @type {HocuspocusProvider | TiptapCloudProvider}
+     * @example new HocuspocusProvider()
+     */
+    provider: any;
+    /**
+     * The user details object – feel free to add properties to this object as needed
+     * @example { name: 'John Doe', color: '#305500' }
+     */
+    user: Record<string, any>;
+    /**
+     * A function that returns a DOM element for the cursor.
+     * @param user The user details object
+     * @example
+     * render: user => {
+     *  const cursor = document.createElement('span')
+     *  cursor.classList.add('collaboration-carets__caret')
+     *  cursor.setAttribute('style', `border-color: ${user.color}`)
+     *
+     *  const label = document.createElement('div')
+     *  label.classList.add('collaboration-carets__label')
+     *  label.setAttribute('style', `background-color: ${user.color}`)
+     *  label.insertBefore(document.createTextNode(user.name), null)
+     *
+     *  cursor.insertBefore(label, null)
+     *  return cursor
+     * }
+     */
+    render(user: Record<string, any>): HTMLElement;
+    /**
+     * A function that returns a ProseMirror DecorationAttrs object for the selection.
+     * @param user The user details object
+     * @example
+     * selectionRender: user => {
+     * return {
+     *  nodeName: 'span',
+     *  class: 'collaboration-carets__selection',
+     *  style: `background-color: ${user.color}`,
+     *  'data-user': user.name,
+     * }
+     */
+    selectionRender(user: Record<string, any>): DecorationAttrs;
+    /**
+     * @deprecated The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+     */
+    onUpdate: (users: {
+        clientId: number;
+        [key: string]: any;
+    }[]) => null;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        collaborationCaret: {
+            /**
+             * Update details of the current user
+             * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })
+             */
+            updateUser: (attributes: Record<string, any>) => ReturnType;
+            /**
+             * Update details of the current user
+             *
+             * @deprecated The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+             */
+            user: (attributes: Record<string, any>) => ReturnType;
+        };
+    }
+    interface Storage {
+        collaborationCaret: CollaborationCaretStorage;
+    }
+}
+/**
+ * This extension allows you to add collaboration carets to your editor.
+ * @see https://tiptap.dev/api/extensions/collaboration-caret
+ */
+declare const CollaborationCaret: Extension<CollaborationCaretOptions, CollaborationCaretStorage>;
+
+export { CollaborationCaret, type CollaborationCaretOptions, CollaborationCaret as default };

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { Extension } from '@tiptap/core';
+import { DecorationAttrs } from '@tiptap/pm/view';
+
+type CollaborationCaretStorage = {
+    users: {
+        clientId: number;
+        [key: string]: any;
+    }[];
+};
+interface CollaborationCaretOptions {
+    /**
+     * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.
+     * @type {HocuspocusProvider | TiptapCloudProvider}
+     * @example new HocuspocusProvider()
+     */
+    provider: any;
+    /**
+     * The user details object – feel free to add properties to this object as needed
+     * @example { name: 'John Doe', color: '#305500' }
+     */
+    user: Record<string, any>;
+    /**
+     * A function that returns a DOM element for the cursor.
+     * @param user The user details object
+     * @example
+     * render: user => {
+     *  const cursor = document.createElement('span')
+     *  cursor.classList.add('collaboration-carets__caret')
+     *  cursor.setAttribute('style', `border-color: ${user.color}`)
+     *
+     *  const label = document.createElement('div')
+     *  label.classList.add('collaboration-carets__label')
+     *  label.setAttribute('style', `background-color: ${user.color}`)
+     *  label.insertBefore(document.createTextNode(user.name), null)
+     *
+     *  cursor.insertBefore(label, null)
+     *  return cursor
+     * }
+     */
+    render(user: Record<string, any>): HTMLElement;
+    /**
+     * A function that returns a ProseMirror DecorationAttrs object for the selection.
+     * @param user The user details object
+     * @example
+     * selectionRender: user => {
+     * return {
+     *  nodeName: 'span',
+     *  class: 'collaboration-carets__selection',
+     *  style: `background-color: ${user.color}`,
+     *  'data-user': user.name,
+     * }
+     */
+    selectionRender(user: Record<string, any>): DecorationAttrs;
+    /**
+     * @deprecated The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+     */
+    onUpdate: (users: {
+        clientId: number;
+        [key: string]: any;
+    }[]) => null;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        collaborationCaret: {
+            /**
+             * Update details of the current user
+             * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })
+             */
+            updateUser: (attributes: Record<string, any>) => ReturnType;
+            /**
+             * Update details of the current user
+             *
+             * @deprecated The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+             */
+            user: (attributes: Record<string, any>) => ReturnType;
+        };
+    }
+    interface Storage {
+        collaborationCaret: CollaborationCaretStorage;
+    }
+}
+/**
+ * This extension allows you to add collaboration carets to your editor.
+ * @see https://tiptap.dev/api/extensions/collaboration-caret
+ */
+declare const CollaborationCaret: Extension<CollaborationCaretOptions, CollaborationCaretStorage>;
+
+export { CollaborationCaret, type CollaborationCaretOptions, CollaborationCaret as default };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/collaboration-caret.ts
+import { Extension } from "@tiptap/core";
+import { defaultSelectionBuilder, yCursorPlugin } from "@tiptap/y-tiptap";
+var awarenessStatesToArray = (states) => {
+  return Array.from(states.entries()).map(([key, value]) => {
+    return {
+      clientId: key,
+      ...value.user
+    };
+  });
+};
+var defaultOnUpdate = () => null;
+var CollaborationCaret = Extension.create({
+  name: "collaborationCaret",
+  priority: 999,
+  addOptions() {
+    return {
+      provider: null,
+      user: {
+        name: null,
+        color: null
+      },
+      render: (user) => {
+        const cursor = document.createElement("span");
+        cursor.classList.add("collaboration-carets__caret");
+        cursor.setAttribute("style", `border-color: ${user.color}`);
+        const label = document.createElement("div");
+        label.classList.add("collaboration-carets__label");
+        label.setAttribute("style", `background-color: ${user.color}`);
+        label.insertBefore(document.createTextNode(user.name), null);
+        cursor.insertBefore(label, null);
+        return cursor;
+      },
+      selectionRender: defaultSelectionBuilder,
+      onUpdate: defaultOnUpdate
+    };
+  },
+  onCreate() {
+    if (this.options.onUpdate !== defaultOnUpdate) {
+      console.warn(
+        '[tiptap warn]: DEPRECATED: The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret'
+      );
+    }
+    if (!this.options.provider) {
+      throw new Error('The "provider" option is required for the CollaborationCaret extension');
+    }
+  },
+  addStorage() {
+    return {
+      users: []
+    };
+  },
+  addCommands() {
+    return {
+      updateUser: (attributes) => () => {
+        this.options.user = attributes;
+        this.options.provider.awareness.setLocalStateField("user", this.options.user);
+        return true;
+      },
+      user: (attributes) => ({ editor }) => {
+        console.warn(
+          '[tiptap warn]: DEPRECATED: The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret'
+        );
+        return editor.commands.updateUser(attributes);
+      }
+    };
+  },
+  addProseMirrorPlugins() {
+    return [
+      yCursorPlugin(
+        (() => {
+          this.options.provider.awareness.setLocalStateField("user", this.options.user);
+          this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states);
+          this.options.provider.awareness.on("update", () => {
+            this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states);
+          });
+          return this.options.provider.awareness;
+        })(),
+        {
+          cursorBuilder: this.options.render,
+          selectionBuilder: this.options.selectionRender
+        }
+      )
+    ];
+  }
+});
+
+// src/index.ts
+var index_default = CollaborationCaret;
+export {
+  CollaborationCaret,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/collaboration-caret.ts","../src/index.ts"],"sourcesContent":["import { Extension } from '@tiptap/core'\nimport type { DecorationAttrs } from '@tiptap/pm/view'\nimport { defaultSelectionBuilder, yCursorPlugin } from '@tiptap/y-tiptap'\n\ntype CollaborationCaretStorage = {\n  users: { clientId: number; [key: string]: any }[]\n}\n\nexport interface CollaborationCaretOptions {\n  /**\n   * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.\n   * @type {HocuspocusProvider | TiptapCloudProvider}\n   * @example new HocuspocusProvider()\n   */\n  provider: any\n\n  /**\n   * The user details object – feel free to add properties to this object as needed\n   * @example { name: 'John Doe', color: '#305500' }\n   */\n  user: Record<string, any>\n\n  /**\n   * A function that returns a DOM element for the cursor.\n   * @param user The user details object\n   * @example\n   * render: user => {\n   *  const cursor = document.createElement('span')\n   *  cursor.classList.add('collaboration-carets__caret')\n   *  cursor.setAttribute('style', `border-color: ${user.color}`)\n   *\n   *  const label = document.createElement('div')\n   *  label.classList.add('collaboration-carets__label')\n   *  label.setAttribute('style', `background-color: ${user.color}`)\n   *  label.insertBefore(document.createTextNode(user.name), null)\n   *\n   *  cursor.insertBefore(label, null)\n   *  return cursor\n   * }\n   */\n  render(user: Record<string, any>): HTMLElement\n\n  /**\n   * A function that returns a ProseMirror DecorationAttrs object for the selection.\n   * @param user The user details object\n   * @example\n   * selectionRender: user => {\n   * return {\n   *  nodeName: 'span',\n   *  class: 'collaboration-carets__selection',\n   *  style: `background-color: ${user.color}`,\n   *  'data-user': user.name,\n   * }\n   */\n  selectionRender(user: Record<string, any>): DecorationAttrs\n\n  /**\n   * @deprecated The \"onUpdate\" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret\n   */\n  onUpdate: (users: { clientId: number; [key: string]: any }[]) => null\n}\n\ndeclare module '@tiptap/core' {\n  interface Commands<ReturnType> {\n    collaborationCaret: {\n      /**\n       * Update details of the current user\n       * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })\n       */\n      updateUser: (attributes: Record<string, any>) => ReturnType\n      /**\n       * Update details of the current user\n       *\n       * @deprecated The \"user\" command is deprecated. Please use \"updateUser\" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret\n       */\n      user: (attributes: Record<string, any>) => ReturnType\n    }\n  }\n\n  interface Storage {\n    collaborationCaret: CollaborationCaretStorage\n  }\n}\n\nconst awarenessStatesToArray = (states: Map<number, Record<string, any>>) => {\n  return Array.from(states.entries()).map(([key, value]) => {\n    return {\n      clientId: key,\n      ...value.user,\n    }\n  })\n}\n\nconst defaultOnUpdate = () => null\n\n/**\n * This extension allows you to add collaboration carets to your editor.\n * @see https://tiptap.dev/api/extensions/collaboration-caret\n */\nexport const CollaborationCaret = Extension.create<CollaborationCaretOptions, CollaborationCaretStorage>({\n  name: 'collaborationCaret',\n\n  priority: 999,\n\n  addOptions() {\n    return {\n      provider: null,\n      user: {\n        name: null,\n        color: null,\n      },\n      render: user => {\n        const cursor = document.createElement('span')\n\n        cursor.classList.add('collaboration-carets__caret')\n        cursor.setAttribute('style', `border-color: ${user.color}`)\n\n        const label = document.createElement('div')\n\n        label.classList.add('collaboration-carets__label')\n        label.setAttribute('style', `background-color: ${user.color}`)\n        label.insertBefore(document.createTextNode(user.name), null)\n        cursor.insertBefore(label, null)\n\n        return cursor\n      },\n      selectionRender: defaultSelectionBuilder,\n      onUpdate: defaultOnUpdate,\n    }\n  },\n\n  onCreate() {\n    if (this.options.onUpdate !== defaultOnUpdate) {\n      console.warn(\n        '[tiptap warn]: DEPRECATED: The \"onUpdate\" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',\n      )\n    }\n    if (!this.options.provider) {\n      throw new Error('The \"provider\" option is required for the CollaborationCaret extension')\n    }\n  },\n\n  addStorage() {\n    return {\n      users: [],\n    }\n  },\n\n  addCommands() {\n    return {\n      updateUser: attributes => () => {\n        this.options.user = attributes\n\n        this.options.provider.awareness.setLocalStateField('user', this.options.user)\n\n        return true\n      },\n      user:\n        attributes =>\n        ({ editor }) => {\n          console.warn(\n            '[tiptap warn]: DEPRECATED: The \"user\" command is deprecated. Please use \"updateUser\" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',\n          )\n\n          return editor.commands.updateUser(attributes)\n        },\n    }\n  },\n\n  addProseMirrorPlugins() {\n    return [\n      yCursorPlugin(\n        (() => {\n          this.options.provider.awareness.setLocalStateField('user', this.options.user)\n\n          this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)\n\n          this.options.provider.awareness.on('update', () => {\n            this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)\n          })\n\n          return this.options.provider.awareness\n        })(),\n        {\n          cursorBuilder: this.options.render,\n          selectionBuilder: this.options.selectionRender,\n        },\n      ),\n    ]\n  },\n})\n","import { CollaborationCaret } from './collaboration-caret.js'\n\nexport * from './collaboration-caret.js'\n\nexport default CollaborationCaret\n"],"mappings":";AAAA,SAAS,iBAAiB;AAE1B,SAAS,yBAAyB,qBAAqB;AAkFvD,IAAM,yBAAyB,CAAC,WAA6C;AAC3E,SAAO,MAAM,KAAK,OAAO,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM;AACxD,WAAO;AAAA,MACL,UAAU;AAAA,MACV,GAAG,MAAM;AAAA,IACX;AAAA,EACF,CAAC;AACH;AAEA,IAAM,kBAAkB,MAAM;AAMvB,IAAM,qBAAqB,UAAU,OAA6D;AAAA,EACvG,MAAM;AAAA,EAEN,UAAU;AAAA,EAEV,aAAa;AACX,WAAO;AAAA,MACL,UAAU;AAAA,MACV,MAAM;AAAA,QACJ,MAAM;AAAA,QACN,OAAO;AAAA,MACT;AAAA,MACA,QAAQ,UAAQ;AACd,cAAM,SAAS,SAAS,cAAc,MAAM;AAE5C,eAAO,UAAU,IAAI,6BAA6B;AAClD,eAAO,aAAa,SAAS,iBAAiB,KAAK,KAAK,EAAE;AAE1D,cAAM,QAAQ,SAAS,cAAc,KAAK;AAE1C,cAAM,UAAU,IAAI,6BAA6B;AACjD,cAAM,aAAa,SAAS,qBAAqB,KAAK,KAAK,EAAE;AAC7D,cAAM,aAAa,SAAS,eAAe,KAAK,IAAI,GAAG,IAAI;AAC3D,eAAO,aAAa,OAAO,IAAI;AAE/B,eAAO;AAAA,MACT;AAAA,MACA,iBAAiB;AAAA,MACjB,UAAU;AAAA,IACZ;AAAA,EACF;AAAA,EAEA,WAAW;AACT,QAAI,KAAK,QAAQ,aAAa,iBAAiB;AAC7C,cAAQ;AAAA,QACN;AAAA,MACF;AAAA,IACF;AACA,QAAI,CAAC,KAAK,QAAQ,UAAU;AAC1B,YAAM,IAAI,MAAM,wEAAwE;AAAA,IAC1F;AAAA,EACF;AAAA,EAEA,aAAa;AACX,WAAO;AAAA,MACL,OAAO,CAAC;AAAA,IACV;AAAA,EACF;AAAA,EAEA,cAAc;AACZ,WAAO;AAAA,MACL,YAAY,gBAAc,MAAM;AAC9B,aAAK,QAAQ,OAAO;AAEpB,aAAK,QAAQ,SAAS,UAAU,mBAAmB,QAAQ,KAAK,QAAQ,IAAI;AAE5E,eAAO;AAAA,MACT;AAAA,MACA,MACE,gBACA,CAAC,EAAE,OAAO,MAAM;AACd,gBAAQ;AAAA,UACN;AAAA,QACF;AAEA,eAAO,OAAO,SAAS,WAAW,UAAU;AAAA,MAC9C;AAAA,IACJ;AAAA,EACF;AAAA,EAEA,wBAAwB;AACtB,WAAO;AAAA,MACL;AAAA,SACG,MAAM;AACL,eAAK,QAAQ,SAAS,UAAU,mBAAmB,QAAQ,KAAK,QAAQ,IAAI;AAE5E,eAAK,QAAQ,QAAQ,uBAAuB,KAAK,QAAQ,SAAS,UAAU,MAAM;AAElF,eAAK,QAAQ,SAAS,UAAU,GAAG,UAAU,MAAM;AACjD,iBAAK,QAAQ,QAAQ,uBAAuB,KAAK,QAAQ,SAAS,UAAU,MAAM;AAAA,UACpF,CAAC;AAED,iBAAO,KAAK,QAAQ,SAAS;AAAA,QAC/B,GAAG;AAAA,QACH;AAAA,UACE,eAAe,KAAK,QAAQ;AAAA,UAC5B,kBAAkB,KAAK,QAAQ;AAAA,QACjC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF,CAAC;;;AC1LD,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tiptap/extension-collaboration-caret",
+  "description": "collaboration caret extension for tiptap",
+  "version": "3.0.0-next.7",
+  "homepage": "https://tiptap.dev",
+  "keywords": [
+    "tiptap",
+    "tiptap extension"
+  ],
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/ueberdosis"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "devDependencies": {
+    "@tiptap/core": "^3.0.0-next.7",
+    "@tiptap/pm": "^3.0.0-next.7",
+    "@tiptap/y-tiptap": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^3.0.0-next.3",
+    "@tiptap/pm": "^3.0.0-next.3",
+    "@tiptap/y-tiptap": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ueberdosis/tiptap",
+    "directory": "packages/extension-collaboration-caret"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "prettier ./src/ --check && eslint --cache --quiet --no-error-on-unmatched-pattern ./src/"
+  }
+}

package/src/collaboration-caret.ts

@@ -0,0 +1,191 @@
+import { Extension } from '@tiptap/core'
+import type { DecorationAttrs } from '@tiptap/pm/view'
+import { defaultSelectionBuilder, yCursorPlugin } from '@tiptap/y-tiptap'
+
+type CollaborationCaretStorage = {
+  users: { clientId: number; [key: string]: any }[]
+}
+
+export interface CollaborationCaretOptions {
+  /**
+   * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.
+   * @type {HocuspocusProvider | TiptapCloudProvider}
+   * @example new HocuspocusProvider()
+   */
+  provider: any
+
+  /**
+   * The user details object – feel free to add properties to this object as needed
+   * @example { name: 'John Doe', color: '#305500' }
+   */
+  user: Record<string, any>
+
+  /**
+   * A function that returns a DOM element for the cursor.
+   * @param user The user details object
+   * @example
+   * render: user => {
+   *  const cursor = document.createElement('span')
+   *  cursor.classList.add('collaboration-carets__caret')
+   *  cursor.setAttribute('style', `border-color: ${user.color}`)
+   *
+   *  const label = document.createElement('div')
+   *  label.classList.add('collaboration-carets__label')
+   *  label.setAttribute('style', `background-color: ${user.color}`)
+   *  label.insertBefore(document.createTextNode(user.name), null)
+   *
+   *  cursor.insertBefore(label, null)
+   *  return cursor
+   * }
+   */
+  render(user: Record<string, any>): HTMLElement
+
+  /**
+   * A function that returns a ProseMirror DecorationAttrs object for the selection.
+   * @param user The user details object
+   * @example
+   * selectionRender: user => {
+   * return {
+   *  nodeName: 'span',
+   *  class: 'collaboration-carets__selection',
+   *  style: `background-color: ${user.color}`,
+   *  'data-user': user.name,
+   * }
+   */
+  selectionRender(user: Record<string, any>): DecorationAttrs
+
+  /**
+   * @deprecated The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+   */
+  onUpdate: (users: { clientId: number; [key: string]: any }[]) => null
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    collaborationCaret: {
+      /**
+       * Update details of the current user
+       * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })
+       */
+      updateUser: (attributes: Record<string, any>) => ReturnType
+      /**
+       * Update details of the current user
+       *
+       * @deprecated The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+       */
+      user: (attributes: Record<string, any>) => ReturnType
+    }
+  }
+
+  interface Storage {
+    collaborationCaret: CollaborationCaretStorage
+  }
+}
+
+const awarenessStatesToArray = (states: Map<number, Record<string, any>>) => {
+  return Array.from(states.entries()).map(([key, value]) => {
+    return {
+      clientId: key,
+      ...value.user,
+    }
+  })
+}
+
+const defaultOnUpdate = () => null
+
+/**
+ * This extension allows you to add collaboration carets to your editor.
+ * @see https://tiptap.dev/api/extensions/collaboration-caret
+ */
+export const CollaborationCaret = Extension.create<CollaborationCaretOptions, CollaborationCaretStorage>({
+  name: 'collaborationCaret',
+
+  priority: 999,
+
+  addOptions() {
+    return {
+      provider: null,
+      user: {
+        name: null,
+        color: null,
+      },
+      render: user => {
+        const cursor = document.createElement('span')
+
+        cursor.classList.add('collaboration-carets__caret')
+        cursor.setAttribute('style', `border-color: ${user.color}`)
+
+        const label = document.createElement('div')
+
+        label.classList.add('collaboration-carets__label')
+        label.setAttribute('style', `background-color: ${user.color}`)
+        label.insertBefore(document.createTextNode(user.name), null)
+        cursor.insertBefore(label, null)
+
+        return cursor
+      },
+      selectionRender: defaultSelectionBuilder,
+      onUpdate: defaultOnUpdate,
+    }
+  },
+
+  onCreate() {
+    if (this.options.onUpdate !== defaultOnUpdate) {
+      console.warn(
+        '[tiptap warn]: DEPRECATED: The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',
+      )
+    }
+    if (!this.options.provider) {
+      throw new Error('The "provider" option is required for the CollaborationCaret extension')
+    }
+  },
+
+  addStorage() {
+    return {
+      users: [],
+    }
+  },
+
+  addCommands() {
+    return {
+      updateUser: attributes => () => {
+        this.options.user = attributes
+
+        this.options.provider.awareness.setLocalStateField('user', this.options.user)
+
+        return true
+      },
+      user:
+        attributes =>
+        ({ editor }) => {
+          console.warn(
+            '[tiptap warn]: DEPRECATED: The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',
+          )
+
+          return editor.commands.updateUser(attributes)
+        },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      yCursorPlugin(
+        (() => {
+          this.options.provider.awareness.setLocalStateField('user', this.options.user)
+
+          this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)
+
+          this.options.provider.awareness.on('update', () => {
+            this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)
+          })
+
+          return this.options.provider.awareness
+        })(),
+        {
+          cursorBuilder: this.options.render,
+          selectionBuilder: this.options.selectionRender,
+        },
+      ),
+    ]
+  },
+})

package/src/index.ts

@@ -0,0 +1,5 @@
+import { CollaborationCaret } from './collaboration-caret.js'
+
+export * from './collaboration-caret.js'
+
+export default CollaborationCaret