merge main into branch

.github/workflows/build.yml

@@ -31,7 +31,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
 
       - name: Load cached dependencies
-        uses: actions/cache@v3.3.2
+        uses: actions/cache@v4.0.2
         id: cache
         with:
           path: |
@@ -140,7 +140,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
 
       - name: Load cached dependencies
-        uses: actions/cache@v3.3.2
+        uses: actions/cache@v4.0.2
         id: cache
         with:
           path: |

CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.2.5](https://github.com/ueberdosis/tiptap/compare/v2.2.4...v2.2.5) (2024-04-05)
+
+
+### Bug Fixes
+
+* Disallow only whitespace between markdown shortcuts delimiters ([#4866](https://github.com/ueberdosis/tiptap/issues/4866)) ([aa029fe](https://github.com/ueberdosis/tiptap/commit/aa029fe2242aeadc38555b2832df6ae1614c7d1d))
+* **extension-link:** Avoid auto-linking partial text for invalid TLDs ([#4865](https://github.com/ueberdosis/tiptap/issues/4865)) ([4474d05](https://github.com/ueberdosis/tiptap/commit/4474d056daf9280ebb10b31f98bb000e953132e5))
+
+
+
+
+
+## [2.2.4](https://github.com/ueberdosis/tiptap/compare/v2.2.3...v2.2.4) (2024-02-23)
+
+
+### Bug Fixes
+
+* mark nocookie youtube url as valid when parsing html ([#4883](https://github.com/ueberdosis/tiptap/issues/4883)) ([099e10d](https://github.com/ueberdosis/tiptap/commit/099e10df923d851dd866354e9abca331d995b65c))
+* typecheck drag and clipboard events for testing environments ([bbee9a3](https://github.com/ueberdosis/tiptap/commit/bbee9a3c3090fa40bf366591682b42a3f6ec5f91))
+
+
+
+
+
+## [2.2.3](https://github.com/ueberdosis/tiptap/compare/v2.2.2...v2.2.3) (2024-02-15)
+
+
+### Bug Fixes
+
+* fix test path ([21aa96d](https://github.com/ueberdosis/tiptap/commit/21aa96dee8deab1f439b7f655b8ed266a516a4cd))
+
+
+
+
+
 ## [2.2.2](https://github.com/ueberdosis/tiptap/compare/v2.2.1...v2.2.2) (2024-02-07)
 
 

demos/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.2.5](https://github.com/ueberdosis/tiptap/compare/v2.2.4...v2.2.5) (2024-04-05)
+
+**Note:** Version bump only for package tiptap-demos
+
+
+
+
+
+## [2.2.4](https://github.com/ueberdosis/tiptap/compare/v2.2.3...v2.2.4) (2024-02-23)
+
+**Note:** Version bump only for package tiptap-demos
+
+
+
+
+
+## [2.2.3](https://github.com/ueberdosis/tiptap/compare/v2.2.2...v2.2.3) (2024-02-15)
+
+
+### Bug Fixes
+
+* fix test path ([21aa96d](https://github.com/ueberdosis/tiptap/commit/21aa96dee8deab1f439b7f655b8ed266a516a4cd))
+
+
+
+
+
 ## [2.2.2](https://github.com/ueberdosis/tiptap/compare/v2.2.1...v2.2.2) (2024-02-07)
 
 **Note:** Version bump only for package tiptap-demos

demos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiptap-demos",
-  "version": "2.2.2",
+  "version": "2.2.5",
   "private": true,
   "scripts": {
     "start": "vite --host",

docs/api/marks/strike.md

@@ -59,7 +59,7 @@ editor.commands.unsetStrike()
 ## Keyboard shortcuts
 | Command        | Windows/Linux                   | macOS                       |
 | -------------- | ------------------------------- | --------------------------- |
-| toggleStrike() | `Control` `Shift` `X` | `Cmd` `Shift` `X` |
+| toggleStrike() | `Control` `Shift` `S` | `Cmd` `Shift` `S` |
 
 ## Source code
 [packages/extension-strike/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-strike/)

docs/api/nodes/mention.md

@@ -67,6 +67,16 @@ Mention.configure({
   }
 })
 ```
+
+### deleteTriggerWithBackspace
+Toggle whether the suggestion character(s) should also be deleted on deletion of a mention node. Default is `false`.
+
+```js
+Mention.configure({
+  deleteTriggerWithBackspace: true
+})
+```
+
 ### suggestion
 [Read more](/api/utilities/suggestion)
 

docs/api/utilities/suggestion.md

@@ -59,7 +59,7 @@ Default: `() => ({})`
 ### findSuggestionMatch
 Optional param to replace the built-in regex matching of editor content that triggers a suggestion.
 See [the
-source](https://github.com/estrattonbailey/tiptap/blob/develop/packages/suggestion/src/findSuggestionMatch.ts#L18)
+source](https://github.com/ueberdosis/tiptap/blob/main/packages/suggestion/src/findSuggestionMatch.ts#L18)
 for more detail.
 
 Default: `findSuggestionMatch(config: Trigger): SuggestionMatch`

docs/collaboration/authenticate.md

@@ -0,0 +1,156 @@
+---
+tableOfContents: true
+---
+
+# Authentication and authorization in Collaboration
+
+## Authentication in Collaboration
+
+After setting up a collaborative editor in the installation guide, it's crucial to address authentication for longer-term use. The temporary JWT provided by Collaboration is only suitable for brief testing sessions.
+
+### **Understanding JWT**
+
+JWT, or JSON Web Token, is a compact, URL-safe means of representing claims to be transferred between two parties. The information in a JWT is digitally signed using a cryptographic algorithm to ensure that the claims cannot be altered after the token is issued. This digital signature makes the JWT a reliable vehicle for secure information exchange in web applications, providing a method to authenticate and exchange information.
+
+### **Creating static JWT for testing**
+
+For testing purposes, you might not want to set up a complete backend system to generate JWTs. In such cases, using online tools like http://jwtbuilder.jamiekurtz.com/ can be a quick workaround. These tools allow you to create a JWT by inputting the necessary payload and signing it with a secret key.
+
+When using these tools, ensure that the "Key" field is replaced with the secret key from your [Collaboration settings](https://collab.tiptap.dev/apps/settings) page. You don’t need to change any other information.
+
+Remember, this approach is only recommended for testing due to security risks associated with exposing your secret key.
+
+### **Generating JWTs for production environments**
+
+For production-level applications, generating JWTs on the server side is a necessity to maintain security. Exposing your secret key in client-side code would compromise the security of your application. Here’s an enhanced example using NodeJS for creating JWTs server-side:
+
+```bash
+npm install jsonwebtoken
+```
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken'
+
+const payload = {
+  // The payload contains claims like the user ID, which can be used to identify the user and their permissions.
+  userId: 'user123'
+}
+
+// The 'sign' method creates the JWT, with the payload and your secret key as inputs.
+const jwt = jsonwebtoken.sign(payload, 'your_secret_key_here')
+// The resulting JWT is used for authentication in API requests, ensuring secure access.
+// Important: Never expose your secret key in client-side code!
+```
+
+This JWT should be incorporated into API requests within the **`token`** field of your authentication provider, safeguarding user sessions and data access.
+
+To fully integrate JWT into your application, consider setting up a dedicated server or API endpoint, such as **`GET /getCollabToken`**. This endpoint would dynamically generate JWTs based on a secret stored securely on the server and user-specific information, like document access permissions.
+
+This setup not only enhances security but also provides a scalable solution for managing user sessions and permissions in your collaborative application.
+
+Ensure the secret key is stored as an environment variable on the server, or define it directly in the server code. Avoid sending it from the client side.
+
+A full server / API example is available [here](https://github.com/ueberdosis/tiptap-collab-replit/tree/main/src).
+
+## **Authorization in Collaboration**
+
+Setting up the right access controls is important for keeping your documents secure and workflows smooth in Tiptap Collaboration.
+
+This part of the guide walks you through how to use JSON Web Tokens (JWTs) to fine-tune who gets to see and edit what. Whether you need to give someone full access, restrict them to certain documents, or block access entirely, we've got you covered with minimalistic examples.
+
+### Allowing Full Access to Every Document
+
+Omitting the `allowedDocumentNames` property from the JWT payload grants the user access to all documents. This is useful for users who need unrestricted access.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+### **Limiting Access to Specific Documents**
+
+To restrict a user's access to specific documents, include those document names in the `allowedDocumentNames` array within the JWT payload. This ensures the user can only access the listed documents.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: ['user-specific-document-1', 'user-specific-document-2'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+
+```
+
+### Blocking Access to All Documents
+
+To prohibit a user from accessing any documents, provide an empty array for `allowedDocumentNames` in the JWT payload. This effectively blocks access to all documents.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: [],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+## Setting Read-Only Access
+
+The `readonlyDocumentNames` property in your JWT setup plays a crucial role when you need to allow users to view documents without the ability to edit them. This feature is particularly useful in scenarios where you want to share information with team members for review or reference purposes but need to maintain the integrity of the original document.
+
+By specifying document names in the `readonlyDocumentNames` array, you grant users read-only access to those documents. Users can open and read the documents, but any attempts to modify the content will be restricted. This ensures that sensitive or critical information remains unchanged while still being accessible for necessary personnel.
+
+In this example, we grant read-only access to two documents, `annual-report-2024` and `policy-document-v3`. Users with this JWT can view these documents but cannot make any edits.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  readonlyDocumentNames: ['annual-report-2024', 'policy-document-v3'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+Incorporating the `readonlyDocumentNames` property into your JWT strategy enhances document security by ensuring that only authorized edits are made, preserving the integrity of your critical documents.
+
+## Utilizing Wildcards for Flexible Document Access
+
+Wildcards in JWTs offer a dynamic way to manage document access, allowing for broader permissions within specific criteria without listing each document individually. This method is particularly useful in scenarios where documents are grouped by certain attributes, such as projects, teams, or roles.
+
+### Managing Project-Specific Documents
+
+For teams working on multiple projects, it's essential to ensure that members have access only to the documents relevant to their current projects. By using project identifiers with wildcards, you can streamline access management.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: ['project-alpha/*', 'project-beta/*'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+In this example, users will have access to all documents under 'project-alpha' and 'project-beta', making it easier to manage permissions as new documents are added to these projects.
+
+### Facilitating Role-Based Access Control
+
+Role-based access control (RBAC) is a common requirement in many systems, where access needs to be granted based on the user's role within the organization. Wildcards allow for easy mapping of roles to document access patterns.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: ['editors/*', 'contributors/*'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+Here, users assigned as 'editors' or 'contributors' can access documents prefixed with their respective roles. This setup simplifies the process of updating access rights as roles change or new roles are added.

docs/collaboration/awareness.md

@@ -0,0 +1,68 @@
+# What is Awareness in Collaboration
+
+Awareness in Tiptap Collaboration, powered by Yjs, is helping you share real-time info on users' activities within a collaborative space. This can include details like user presence, cursor positions, and custom user states.
+
+At its core, awareness utilizes its own Conflict-Free Replicated Data Type (CRDT) to ensure that this shared meta-information remains consistent and immediate across all users, without maintaining a historical record of these states.
+
+You can read more about Awareness in the [Yjs documentation on awareness](https://docs.yjs.dev/getting-started/adding-awareness).
+
+### Understanding provider events for awareness
+
+Awareness updates trigger specific [provider events](https://tiptap.dev/docs/editor/collaboration/events) to develop interactive features based on user actions and presence:
+
+- `awarenessUpdate`: This event signals that a user is active. It triggers without actual state changes, serving as a 'heartbeat' to inform others the user is in the document.
+- `awarenessChange`: This event alerts you to any additions, updates, or deletions in the awareness state, reflecting both your local changes and those from remote users.
+
+These events serve as hooks for integrating custom Awareness features.
+
+## Integrating Basic Awareness
+
+With your [collaborative environment](https://tiptap.dev/docs/editor/collaboration/install) set up, you're all set to integrate Awareness, which is natively supported by the Collaboration Provider.
+
+To kick things off, update the Awareness state with any relevant information. For this guide, we'll use a user's name, cursor color, and mouse position as examples.
+
+### Setting the awareness field
+
+Let's assign a name, color, and mouse position to the user. This is just an example; feel free to use any data relevant to your application.
+```typescript
+// Set the awareness field for the current user
+provider.setAwarenessField("user", {
+  // Share any information you like
+  name: "Kevin James",
+  color: "#ffcc00",
+});
+```
+
+### Listening for changes
+
+Set up an event listener to track changes in the Awareness states across all connected users:
+
+```typescript
+// Listen for updates to the states of all users
+provider.on("awarenessChange", ({ states }) => {
+  console.log(states);
+});
+```
+You can now view these updates in your browser's console as you move on to the next step.
+
+### Tracking mouse movement
+
+Next, we'll add an event listener to our app to track mouse movements and update the awareness' information accordingly.
+
+```typescript
+document.addEventListener("mousemove", (event) => {
+  // Share any information you like
+  provider.setAwarenessField("user", {
+    name: "Kevin James",
+    color: "#ffcc00",
+    mouseX: event.clientX,
+    mouseY: event.clientY,
+  });
+});
+```
+
+Check your browser's console to see the stream of events as users move their mice.
+
+### Next Steps
+
+With basic Awareness in place, consider enhancing your setup with the [Collaboration Cursor](https://tiptap.dev/docs/editor/api/extensions/collaboration-cursor) extension. This extension adds cursor positions, text selections, and personalized details (such as names and colors) of all participating users to your editor.