feat: AI autocomplete [render preview]

docs/content/docs/features/ai/autocomplete.mdx

@@ -0,0 +1,157 @@
+---
+title: Autocomplete
+description: Add AI-powered autocomplete suggestions to your BlockNote editor
+imageTitle: BlockNote AI Autocomplete
+---
+
+import { TypeTable } from 'fumadocs-ui/components/type-table';
+
+# AI Autocomplete
+
+The AI Autocomplete extension provides real-time, AI-powered text completion suggestions as users type. 
+When enabled, the editor will display inline suggestions that can be accepted with the **Tab** key or dismissed with **Escape**.
+
+## Installation
+
+First, ensure you have the `@blocknote/xl-ai` package installed:
+
+```bash
+npm install @blocknote/xl-ai
+```
+
+## Basic Setup and demo
+
+To enable AI autocomplete in your editor, add the `AIAutoCompleteExtension` to your editor configuration. 
+Here's a the basic code setup and live demo:
+
+<Example name="ai/autocomplete" />
+
+## Configuration
+
+The `AIAutoCompleteExtension` accepts the following options:
+
+<TypeTable
+  type={{
+    provider: {
+      description: 'URL to fetch suggestions from, or a custom provider function.',
+      type: 'string | function',
+      required: true
+    },
+    contextLength: {
+      description: 'Number of characters of context to send to your backend when using a URL provider.',
+      type: 'number',
+      default: '300'
+    },
+    acceptKey: {
+      description: 'Key to accept the current suggestion.',
+      type: 'string',
+      default: '"Tab"'
+    },
+    cancelKey: {
+      description: 'Key to discard suggestions.',
+      type: 'string',
+      default: '"Escape"'
+    },
+    debounceDelay: {
+      description: 'Delay in ms before fetching suggestions.',
+      type: 'number',
+      default: '300'
+    },
+    onlyAtEndOfBlock: {
+      description: 'When true, only fetch suggestions when the cursor is at the end of a block. When false, fetch suggestions at every cursor position (also in the middle of a sentence).',
+      type: 'boolean',
+      default: 'false'
+    }
+  }}
+/>
+
+### Using a Custom Provider
+
+When you provide a URL (`string`) as provider, the extension will use the default provider that fetches suggestions from that URL.
+
+Alternatively, you can provide a custom provider function that should return an array of suggestions at the current cursor position.
+
+## Backend Integration
+
+With BlockNote AI Autocomplete, you have full control over the backend and LLM integration.
+
+The default URL provider sends a `POST` request with the following body:
+
+```json
+{
+  "text": "The last 300 characters of text before the cursor"
+}
+```
+
+It expects a JSON response with an array of suggestion strings:
+
+```json
+{
+  "suggestions": ["completion text", "more text"]
+}
+```
+
+_When multiple suggestions are returned, the first one will be used by default. As the user continues typing, the extension will automatically select alternative matching suggestions (or do a new backend requests if none of the cached suggestions match)._
+
+Here's an example API route using the Vercel AI SDK with Mistral's Codestral model:
+
+<Callout type="info">
+  **Codestral** is a code completion model that excels in speed (for as-you-type suggestions low latency is important). 
+  Even though it's designed for code completion, we can use it for general text completion as well.
+  See the [reference implementation](https://github.com/TypeCellOS/BlockNote/blob/main/packages/xl-ai-server/src/routes/autocomplete.ts) for a complete example.
+</Callout>
+
+```typescript
+// app/api/autocomplete/route.ts
+import { createMistral } from "@ai-sdk/mistral";
+import { generateText } from "ai";
+
+const model = createMistral({
+  apiKey: process.env.MISTRAL_API_KEY,
+})("codestral-latest");
+
+export async function POST(req: Request) {
+  const { text } = await req.json();
+
+  const result = await generateText({
+    model,
+    system: `You are a writing assistant. Predict the most likely next part of the text.
+- Provide up to 3 suggestions separated by newlines
+- Keep suggestions short (max 5 words each)
+- Only return the text to append (no explanations)
+- Add a space before the suggestion if starting a new word`,
+    messages: [
+      {
+        role: "user",
+        content: `Complete the following text: \n${text}[SUGGESTION_HERE]`,
+      },
+    ],
+    abortSignal: req.signal,
+  });
+
+  return Response.json({
+    suggestions: result.text
+      .split("\n")
+      .map((s) => s.trimEnd())
+      .filter((s) => s.trim().length > 0),
+  });
+}
+```
+
+## Programmatic Control
+
+You can also control the autocomplete extension programmatically:
+
+```typescript
+const ext = editor.getExtension(AIAutoCompleteExtension);
+
+// Accept the current suggestion
+ext.acceptAutoCompleteSuggestion();
+
+// Discard suggestions
+ext.discardAutoCompleteSuggestions();
+
+// Manually trigger autocomplete at the current cursor position
+// (useful if you want to configure a custom key to trigger autocomplete)
+ext.triggerAutoComplete();
+```

docs/content/docs/features/ai/meta.json

@@ -4,6 +4,7 @@
     "getting-started",
     "backend-integration",
     "custom-commands",
+    "autocomplete",
     "reference"
   ]
 }

examples/09-ai/01-minimal/README.md

@@ -1,11 +1,11 @@
-# Rich Text editor AI integration
+# Rich Text Editor AI Integration
 
 This example shows the minimal setup to add AI integration to your BlockNote rich text editor.
 
 Select some text and click the AI (stars) button, or type `/ai` anywhere in the editor to access AI functionality.
 
 **Relevant Docs:**
 
-- [Getting Stared with BlockNote AI](/docs/features/ai/getting-started)
+- [Getting Started with BlockNote AI](/docs/features/ai/getting-started)
 - [Changing the Formatting Toolbar](/docs/react/components/formatting-toolbar)
 - [Changing Slash Menu Items](/docs/react/components/suggestion-menus)

examples/09-ai/01-minimal/index.html

@@ -2,7 +2,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Rich Text editor AI integration</title>
+    <title>Rich Text Editor AI Integration</title>
     <script>
       <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
     </script>

examples/09-ai/01-minimal/src/App.tsx

@@ -22,7 +22,6 @@ import { en as aiEn } from "@blocknote/xl-ai/locales";
 import "@blocknote/xl-ai/style.css";
 
 import { DefaultChatTransport } from "ai";
-import { useEffect } from "react";
 import { getEnv } from "./getEnv";
 
 const BASE_URL =

examples/09-ai/08-autocomplete/.bnexample.json

@@ -0,0 +1,11 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "yousefed",
+  "tags": ["AI", "autocomplete"],
+  "dependencies": {
+    "@blocknote/xl-ai": "latest",
+    "@mantine/core": "^8.3.4",
+    "ai": "^5.0.102"
+  }
+}

examples/09-ai/08-autocomplete/README.md

@@ -0,0 +1,10 @@
+# AI Autocomplete
+
+This example demonstrates the AI autocomplete feature in BlockNote. As you type, the editor will automatically suggest completions using AI.
+
+Press **Tab** to accept a suggestion or **Escape** to dismiss it.
+
+**Relevant Docs:**
+
+- [AI Autocomplete](/docs/features/ai/autocomplete)
+- [AI Getting Started](/docs/features/ai/getting-started)

examples/09-ai/08-autocomplete/index.html

@@ -0,0 +1,14 @@
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI Autocomplete</title>
+    <script>
+      <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

examples/09-ai/08-autocomplete/main.tsx

@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./src/App.jsx";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

examples/09-ai/08-autocomplete/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@blocknote/example-ai-autocomplete",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "type": "module",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build:prod": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@blocknote/ariakit": "latest",
+    "@blocknote/core": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/shadcn": "latest",
+    "@mantine/core": "^8.3.4",
+    "@mantine/hooks": "^8.3.4",
+    "@mantine/utils": "^6.0.22",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@blocknote/xl-ai": "latest",
+    "ai": "^5.0.102"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "@vitejs/plugin-react": "^4.7.0",
+    "vite": "^5.4.20"
+  }
+}

examples/09-ai/08-autocomplete/src/App.tsx

@@ -0,0 +1,65 @@
+import "@blocknote/core/fonts/inter.css";
+import { en } from "@blocknote/core/locales";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import { useCreateBlockNote } from "@blocknote/react";
+import {
+  AIAutoCompleteExtension
+} from "@blocknote/xl-ai";
+import { en as aiEn } from "@blocknote/xl-ai/locales";
+import "@blocknote/xl-ai/style.css";
+
+import { getEnv } from "./getEnv";
+
+const BASE_URL =
+  getEnv("BLOCKNOTE_AI_SERVER_BASE_URL") || "https://localhost:3000/ai";
+
+export default function App() {
+  // Creates a new editor instance with AI autocomplete enabled
+  const editor = useCreateBlockNote({
+    dictionary: {
+      ...en,
+      ai: aiEn,
+    },
+    // Register the AI Autocomplete extension
+    extensions: [
+      AIAutoCompleteExtension({
+        provider: `${BASE_URL}/autocomplete/generateText`,
+      }),
+    ],
+    // We set some initial content for demo purposes
+    initialContent: [
+      {
+        type: "heading",
+        props: {
+          level: 1,
+        },
+        content: "AI Autocomplete Demo",
+      },
+      {
+        type: "paragraph",
+        content:
+          "Start typing and the AI will suggest completions based on the current context. When suggestions appear, you can press Tab to accept the suggestion.",
+      },
+      {
+        type: "paragraph",
+        content:
+          "For example, type at the end of this sentence. Open source software is: ",
+      },
+      {
+        type: "paragraph",
+        content: "",
+      },
+    ],
+  });
+
+  // Renders the editor instance using a React component.
+  return (
+    <div>
+      <BlockNoteView
+        editor={editor}
+        style={{ paddingBottom: "300px" }}
+      />
+    </div>
+  );
+}

examples/09-ai/08-autocomplete/src/getEnv.ts

@@ -0,0 +1,20 @@
+// helper function to get env variables across next / vite
+// only needed so this example works in BlockNote demos and docs
+export function getEnv(key: string) {
+  const env = (import.meta as any).env
+    ? {
+        BLOCKNOTE_AI_SERVER_API_KEY: (import.meta as any).env
+          .VITE_BLOCKNOTE_AI_SERVER_API_KEY,
+        BLOCKNOTE_AI_SERVER_BASE_URL: (import.meta as any).env
+          .VITE_BLOCKNOTE_AI_SERVER_BASE_URL,
+      }
+    : {
+        BLOCKNOTE_AI_SERVER_API_KEY:
+          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_API_KEY,
+        BLOCKNOTE_AI_SERVER_BASE_URL:
+          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_BASE_URL,
+      };
+
+  const value = env[key as keyof typeof env];
+  return value;
+}