codemirror-languageserver 1.19.0 → 1.20.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/codemirror-languageserver.svg)](https://www.npmjs.com/package/codemirror-languageserver)
 
-This plugin enables code completion, hover tooltips, and linter functionality by connecting a CodeMirror 6 editor with a language server over WebSocket.
+This plugin connects a [CodeMirror 6](https://codemirror.net/) editor with a [Language Server](https://microsoft.github.io/language-server-protocol/) over WebSocket, providing IDE-like features in the browser.
 
 [How It Works](https://hjr265.me/blog/codemirror-lsp/)
 
@@ -18,61 +18,114 @@ https://user-images.githubusercontent.com/348107/120141150-c6bb9180-c1fd-11eb-8a
 - 🎨 Document Formatting and Range Formatting
 - ✏️ Rename Symbol
 
-## Usage
+## Installation
 
 ```
 npm i codemirror-languageserver
 ```
 
+**Peer dependencies:** This package requires `@codemirror/autocomplete`, `@codemirror/lint`, `@codemirror/state`, and `@codemirror/view` as peer dependencies. If you're using CodeMirror 6, you likely already have these installed.
+
+## Quick Start
+
 ```js
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
 import { languageServer } from 'codemirror-languageserver';
 
-var ls = languageServer({
-    // WebSocket server uri and other client options.
-    serverUri,
+const ls = languageServer({
+    serverUri: 'ws://localhost:8080',
     rootUri: 'file:///',
-
-    // Alternatively, to share the same client across multiple instances of this plugin.
-    client: new LanguageServerClient({
-        transport: new WebSocketTransport(serverUri),
-        rootUri: 'file:///',
-    }),
-
     documentUri: `file:///${filename}`,
     languageId: 'cpp', // As defined at https://microsoft.github.io/language-server-protocol/specification#textDocumentItem.
 });
 
-var view = new EditorView({
+const view = new EditorView({
     state: EditorState.create({
         extensions: [
-            // ...
+            // ... other extensions
             ls,
-            // ...
         ],
     }),
 });
 ```
 
-### Custom Transport
+This sets up all built-in features: completion, hover, diagnostics, go-to-definition, document highlight, and rename support.
+
+## Options
+
+| Option | Type | Description |
+|---|---|---|
+| `serverUri` | `ws://...` or `wss://...` | WebSocket server URI |
+| `rootUri` | `string` | Root URI of the workspace |
+| `workspaceFolders` | `WorkspaceFolder[]` | LSP workspace folders |
+| `documentUri` | `string` | URI of the document being edited |
+| `languageId` | `string` | Language identifier ([spec](https://microsoft.github.io/language-server-protocol/specification#textDocumentItem)) |
+| `initializationOptions` | `object` | Server-specific initialization options |
+| `locale` | `string` | Locale for the LSP session (e.g. `'en'`) |
+| `allowHTMLContent` | `boolean` | Trust raw HTML in hover/completion content (default: `false`) |
+| `synchronizationMethod` | `SynchronizationMethod` | `'full'` or `'incremental'` document sync (default: `'full'`) |
+| `client` | `LanguageServerClient` | Share a client across multiple editor instances |
+| `onCapabilities` | `(capabilities) => void` | Called when server capabilities are available |
+
+## Shared Client
+
+To share the same language server connection across multiple editor instances:
+
+```js
+import { LanguageServerClient, languageServerWithTransport, WebSocketTransport } from 'codemirror-languageserver';
+
+const client = new LanguageServerClient({
+    transport: new WebSocketTransport('ws://localhost:8080'),
+    rootUri: 'file:///',
+});
+
+// Use the same client for multiple editors
+const ls1 = languageServerWithTransport({
+    client,
+    documentUri: 'file:///main.cpp',
+    languageId: 'cpp',
+});
+
+const ls2 = languageServerWithTransport({
+    client,
+    documentUri: 'file:///utils.cpp',
+    languageId: 'cpp',
+});
+```
+
+## Custom Transport
 
-Use `languageServerWithTransport` to provide a custom transport (e.g. for non-WebSocket connections):
+Use `languageServerWithTransport` for non-WebSocket connections:
 
 ```js
 import { languageServerWithTransport } from 'codemirror-languageserver';
 
-var ls = languageServerWithTransport({
-    transport: myCustomTransport, // Must implement the Transport interface
+const ls = languageServerWithTransport({
+    transport: myCustomTransport,
     rootUri: 'file:///',
     documentUri: `file:///${filename}`,
     languageId: 'cpp',
 });
 ```
 
-The `Transport` interface requires `send`, `onMessage`, `onClose`, `onError`, and `close` methods. You can import `Transport` and `WebSocketTransport` from the package.
+The `Transport` interface:
+
+```ts
+interface Transport {
+    send(message: string): void;
+    onMessage(callback: (message: string) => void): void;
+    onClose(callback: () => void): void;
+    onError(callback: (error: Error) => void): void;
+    close(): void;
+}
+```
 
-### Document Highlight
+You can import `Transport` and `WebSocketTransport` from the package.
 
-Document highlights are enabled by default. When the cursor is on a symbol, all occurrences are highlighted. Style them with CSS:
+## Document Highlight
+
+Enabled by default. When the cursor is on a symbol, all occurrences in the document are highlighted. Style with CSS:
 
 ```css
 .cm-lsp-highlight-text,
@@ -80,21 +133,25 @@ Document highlights are enabled by default. When the cursor is on a symbol, all
 .cm-lsp-highlight-write { background-color: rgba(255, 165, 0, 0.3); }
 ```
 
-### Formatting
+The three classes correspond to [DocumentHighlightKind](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#documentHighlightKind): general text occurrences, read accesses, and write accesses.
+
+## Formatting
 
-`formatDocument` and `formatSelection` are CodeMirror commands that you can bind to keys:
+`formatDocument` and `formatSelection` are CodeMirror [commands](https://codemirror.net/docs/ref/#view.Command) — bind them to keys:
 
 ```js
 import { keymap } from '@codemirror/view';
 import { formatDocument, formatSelection } from 'codemirror-languageserver';
 
-keymap.of([
+const formattingKeymap = keymap.of([
     { key: 'Shift-Alt-f', run: formatDocument },
     { key: 'Ctrl-k Ctrl-f', run: formatSelection },
-])
+]);
 ```
 
-To configure formatting options (tab size, spaces vs tabs, etc.), use the `formattingOptions` facet:
+### Formatting Options
+
+Configure formatting with the `formattingOptions` facet. By default, `tabSize` is read from the editor state.
 
 ```js
 import { formattingOptions } from 'codemirror-languageserver';
@@ -105,36 +162,81 @@ formattingOptions.of({
     insertSpaces: true,
     trimTrailingWhitespace: true,
     insertFinalNewline: true,
+    trimFinalNewlines: true,
 })
 ```
 
-By default, `tabSize` is read from the editor state.
+## Rename Symbol
 
-### Rename Symbol
-
-`renameSymbol` is a CodeMirror command that opens a rename prompt at the top of the editor:
+`renameSymbol` is a CodeMirror command that opens a rename prompt at the top of the editor. If the server supports `prepareRename`, the current symbol name is used as the placeholder.
 
 ```js
 import { keymap } from '@codemirror/view';
 import { renameSymbol } from 'codemirror-languageserver';
 
-keymap.of([
+const renameKeymap = keymap.of([
     { key: 'F2', run: renameSymbol },
-])
+]);
 ```
 
-Style the rename panel with CSS using the `cm-lsp-rename-panel` and `cm-lsp-rename-input` classes.
+Style the panel with CSS:
+
+```css
+.cm-lsp-rename-panel {
+    padding: 4px 8px;
+    border-bottom: 1px solid #ddd;
+}
+.cm-lsp-rename-input {
+    font-family: inherit;
+    font-size: inherit;
+}
+```
 
-### Using with Initialization Options
+## Server Capabilities
 
-The plugin includes built-in TypeScript definitions for popular language servers:
+Use the `onCapabilities` callback to react when the server finishes initializing — e.g. to show or hide toolbar buttons:
 
--   `PyrightInitializationOptions` - Python (Pyright)
--   `RustAnalyzerInitializationOptions` - Rust (rust-analyzer)
--   `TypeScriptInitializationOptions` - TypeScript/JavaScript
--   `ESLintInitializationOptions` - ESLint
--   `ClangdInitializationOptions` - C/C++ (Clangd)
--   `GoplsInitializationOptions` - Go (Gopls)
+```js
+languageServer({
+    serverUri: 'ws://localhost:8080',
+    rootUri: 'file:///',
+    documentUri: `file:///${filename}`,
+    languageId: 'cpp',
+    onCapabilities(capabilities) {
+        // capabilities.documentFormattingProvider
+        // capabilities.renameProvider
+        // capabilities.completionProvider
+        // etc.
+        toolbar.update({ capabilities });
+    },
+})
+```
+
+## Initialization Options
+
+The package includes TypeScript definitions for popular language servers:
+
+- `PyrightInitializationOptions` — Python (Pyright)
+- `RustAnalyzerInitializationOptions` — Rust (rust-analyzer)
+- `TypeScriptInitializationOptions` — TypeScript/JavaScript
+- `ESLintInitializationOptions` — ESLint
+- `ClangdInitializationOptions` — C/C++ (Clangd)
+- `GoplsInitializationOptions` — Go (Gopls)
+
+```ts
+import { languageServer } from 'codemirror-languageserver';
+import type { ClangdInitializationOptions } from 'codemirror-languageserver';
+
+const ls = languageServer<ClangdInitializationOptions>({
+    serverUri: 'ws://localhost:8080',
+    rootUri: 'file:///',
+    documentUri: 'file:///main.cpp',
+    languageId: 'cpp',
+    initializationOptions: {
+        // Type-checked options specific to Clangd
+    },
+});
+```
 
 ## Contributing
 
@@ -142,7 +244,7 @@ Contributions are welcome.
 
 ## Real World Uses
 
--   [Toph](https://toph.co): Competitive programming platform. Toph uses Language Server Plugin for CodeMirror 6 with its integrated code editor.
+- [Toph](https://toph.co): Competitive programming platform. Toph uses Language Server Plugin for CodeMirror 6 with its integrated code editor.
 
 ## License
 

package/dist/definition.d.ts

@@ -1,8 +1,20 @@
 import { Command, KeyBinding } from '@codemirror/view';
+/** Command: jump to the definition of the symbol at the cursor. */
 export declare const jumpToDefinition: Command;
+/** Returns a command that jumps to the definition of the symbol at `pos`. */
 export declare const jumpToDefinitionPos: (pos: number) => Command;
+/** Command: jump to the declaration of the symbol at the cursor. */
 export declare const jumpToDeclaration: Command;
+/** Returns a command that jumps to the declaration of the symbol at `pos`. */
 export declare const jumpToDeclarationPos: (pos: number) => Command;
+/** Command: jump to the type definition of the symbol at the cursor. */
 export declare const jumpToTypeDefinition: Command;
+/** Returns a command that jumps to the type definition of the symbol at `pos`. */
 export declare const jumpToTypeDefinitionPos: (pos: number) => Command;
+/**
+ * Default keymap for go-to-definition commands.
+ *
+ * - `F12` — jump to definition
+ * - `Mod-F12` — jump to type definition
+ */
 export declare const jumpToDefinitionKeymap: readonly KeyBinding[];

package/dist/formatting.d.ts

@@ -1,6 +1,14 @@
 import { Facet } from '@codemirror/state';
 import type { EditorView } from '@codemirror/view';
 import type * as LSP from 'vscode-languageserver-protocol';
+/**
+ * Facet for configuring LSP formatting options (tab size, spaces vs tabs, etc.).
+ *
+ * Defaults to `{ tabSize: 4, insertSpaces: true }`. The `tabSize` falls back
+ * to the editor state's `tabSize` if not explicitly set.
+ */
 export declare const formattingOptions: Facet<LSP.FormattingOptions, LSP.FormattingOptions>;
+/** Command: format the entire document using the language server. */
 export declare function formatDocument(view: EditorView): boolean;
+/** Command: format the current selection using the language server. */
 export declare function formatSelection(view: EditorView): boolean;

package/dist/highlight.d.ts

@@ -1,2 +1,8 @@
 import { Extension } from '@codemirror/state';
+/**
+ * Extension that highlights all occurrences of the symbol under the cursor.
+ *
+ * Applies CSS classes `cm-lsp-highlight-text`, `cm-lsp-highlight-read`, and
+ * `cm-lsp-highlight-write` based on the highlight kind returned by the server.
+ */
 export declare const documentHighlight: () => Extension;

package/dist/index.d.ts

@@ -16,5 +16,16 @@ interface LanguageServerWebsocketOptions<InitializationOptions = unknown> extend
     serverUri: `ws://${string}` | `wss://${string}`;
     initializationOptions?: InitializationOptions;
 }
+/**
+ * Creates a set of CodeMirror extensions that connect to a language server over WebSocket.
+ *
+ * Includes completion, hover, diagnostics, go-to-definition, document highlight,
+ * and rename support. This is the main entry point for most use cases.
+ */
 export declare function languageServer<InitializationOptions = unknown>(options: LanguageServerWebsocketOptions<InitializationOptions>): (import("@codemirror/state").Extension | import("@codemirror/state").StateField<string>)[];
+/**
+ * Like {@link languageServer}, but accepts a custom {@link Transport} instead of a WebSocket URI.
+ *
+ * Use this when communicating with the language server over a non-WebSocket channel.
+ */
 export declare function languageServerWithTransport<InitializationOptions = unknown>(options: LanguageServerOptions<InitializationOptions>): (import("@codemirror/state").Extension | import("@codemirror/state").StateField<string>)[];

package/dist/index.js

@@ -5,6 +5,7 @@ import { CompletionItemKind, DiagnosticSeverity, CompletionTriggerKind, Document
 import { marked } from 'marked';
 import { autocompletion as autocompletion$1 } from '@codemirror/autocomplete';
 
+/** A {@link Transport} that communicates over a browser-native WebSocket. */
 class WebSocketTransport {
     constructor(uri) {
         this.connection = new WebSocket(uri);
@@ -164,6 +165,12 @@ Facet.define({
 });
 Facet.define({ combine: useLast });
 Facet.define({ combine: useLast });
+/**
+ * Manages the JSON-RPC connection to a language server.
+ *
+ * Handles initialization, request/response routing, and notification dispatch.
+ * Can be shared across multiple editor instances via the `client` option.
+ */
 class LanguageServerClient {
     constructor(options) {
         this.options = options;
@@ -267,10 +274,12 @@ class LanguageServerClient {
         };
     }
     async initialize() {
+        var _a, _b;
         const { capabilities } = await this.request('initialize', this.getInitializeParams(), timeout * 3);
         this.capabilities = capabilities;
         this.notify('initialized', {});
         this.ready = true;
+        (_b = (_a = this.options).onCapabilities) === null || _b === void 0 ? void 0 : _b.call(_a, capabilities);
     }
     close() {
         this.client.close();
@@ -339,9 +348,12 @@ class LanguageServerClient {
         }
     }
 }
+/** Controls how document changes are sent to the language server. */
 var SynchronizationMethod;
 (function (SynchronizationMethod) {
+    /** Send the full document text on every change. */
     SynchronizationMethod["Full"] = "full";
+    /** Send only the changed ranges. More efficient for large documents. */
     SynchronizationMethod["Incremental"] = "incremental";
 })(SynchronizationMethod || (SynchronizationMethod = {}));
 class LanguageServerPlugin {
@@ -735,15 +747,31 @@ function requestTypeDefinition(view, pos) {
     plugin.requestTypeDefinition(view, offsetToPos(view.state.doc, pos));
     return true;
 }
+/** Command: jump to the definition of the symbol at the cursor. */
 const jumpToDefinition = (view) => requestDefinition(view, view.state.selection.main.head);
+/** Returns a command that jumps to the definition of the symbol at `pos`. */
 const jumpToDefinitionPos = (pos) => (view) => requestDefinition(view, pos);
+/** Command: jump to the type definition of the symbol at the cursor. */
 const jumpToTypeDefinition = (view) => requestTypeDefinition(view, view.state.selection.main.head);
+/** Returns a command that jumps to the type definition of the symbol at `pos`. */
 const jumpToTypeDefinitionPos = (pos) => (view) => requestTypeDefinition(view, pos);
+/**
+ * Default keymap for go-to-definition commands.
+ *
+ * - `F12` — jump to definition
+ * - `Mod-F12` — jump to type definition
+ */
 const jumpToDefinitionKeymap = [
     { key: 'F12', run: jumpToDefinition, preventDefault: true },
     { key: 'Mod-F12', run: jumpToTypeDefinition, preventDefault: true },
 ];
 
+/**
+ * Facet for configuring LSP formatting options (tab size, spaces vs tabs, etc.).
+ *
+ * Defaults to `{ tabSize: 4, insertSpaces: true }`. The `tabSize` falls back
+ * to the editor state's `tabSize` if not explicitly set.
+ */
 const formattingOptions = Facet.define({
     combine(values) {
         return Object.assign({ tabSize: 4, insertSpaces: true }, ...values);
@@ -765,6 +793,7 @@ function applyTextEdits(view, edits) {
     }));
     view.dispatch(view.state.update({ changes }));
 }
+/** Command: format the entire document using the language server. */
 function formatDocument(view) {
     var _a;
     const plugin = view.plugin(languageServerPlugin);
@@ -786,6 +815,7 @@ function formatDocument(view) {
     });
     return true;
 }
+/** Command: format the current selection using the language server. */
 function formatSelection(view) {
     var _a;
     const plugin = view.plugin(languageServerPlugin);
@@ -920,6 +950,12 @@ async function performRename(view, newName) {
         applyWorkspaceEdit(view, result);
     }
 }
+/**
+ * Command: open a rename prompt for the symbol at the cursor.
+ *
+ * Uses `textDocument/prepareRename` to pre-fill the current name if supported
+ * by the server. Press Enter to confirm or Escape to cancel.
+ */
 function renameSymbol(view) {
     var _a;
     const plugin = view.plugin(languageServerPlugin);
@@ -1088,6 +1124,12 @@ const highlightPlugin = ViewPlugin.fromClass(class {
         clearTimeout(this.pending);
     }
 });
+/**
+ * Extension that highlights all occurrences of the symbol under the cursor.
+ *
+ * Applies CSS classes `cm-lsp-highlight-text`, `cm-lsp-highlight-read`, and
+ * `cm-lsp-highlight-write` based on the highlight kind returned by the server.
+ */
 const documentHighlight = () => [
     highlightField,
     highlightPlugin,
@@ -1109,6 +1151,12 @@ const mouseHandler = () => EditorView.domEventHandlers({
     },
 });
 
+/**
+ * Creates a set of CodeMirror extensions that connect to a language server over WebSocket.
+ *
+ * Includes completion, hover, diagnostics, go-to-definition, document highlight,
+ * and rename support. This is the main entry point for most use cases.
+ */
 function languageServer(options) {
     const serverUri = options.serverUri;
     const { serverUri: _, ...optionsWithoutServerUri } = options;
@@ -1117,6 +1165,11 @@ function languageServer(options) {
         transport: new WebSocketTransport(serverUri),
     });
 }
+/**
+ * Like {@link languageServer}, but accepts a custom {@link Transport} instead of a WebSocket URI.
+ *
+ * Use this when communicating with the language server over a non-WebSocket channel.
+ */
 function languageServerWithTransport(options) {
     return [
         languageServerPlugin.of({

package/dist/jsonrpc.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Interface for sending and receiving JSON-RPC messages.
+ *
+ * Implement this to use a custom communication channel (e.g. Web Workers,
+ * MessagePort, or HTTP). See {@link WebSocketTransport} for a reference
+ * implementation.
+ */
 export interface Transport {
     send(message: string): void;
     onMessage(callback: (message: string) => void): void;
@@ -5,6 +12,7 @@ export interface Transport {
     onError(callback: (error: Error) => void): void;
     close(): void;
 }
+/** A {@link Transport} that communicates over a browser-native WebSocket. */
 export declare class WebSocketTransport implements Transport {
     connection: WebSocket;
     constructor(uri: string);

package/dist/plugin.d.ts

@@ -67,8 +67,16 @@ interface LanguageServerClientLocationMethods {
     textDocumentDeclaration(params: LSP.DeclarationParams): LSP.Location | LSP.Location[] | LSP.LocationLink[] | null;
     textDocumentTypeDefinition(params: LSP.TypeDefinitionParams): LSP.Location | LSP.Location[] | LSP.LocationLink[] | null;
 }
+/**
+ * Manages the JSON-RPC connection to a language server.
+ *
+ * Handles initialization, request/response routing, and notification dispatch.
+ * Can be shared across multiple editor instances via the `client` option.
+ */
 export declare class LanguageServerClient<InitializationOptions = unknown> {
+    /** Whether the server has finished initializing. */
     ready: boolean;
+    /** The server's capabilities, available after initialization. */
     capabilities: LSP.ServerCapabilities<any>;
     initializePromise: Promise<void>;
     private rootUri;
@@ -104,8 +112,11 @@ export declare class LanguageServerClient<InitializationOptions = unknown> {
     protected notify<K extends keyof LSPNotifyMap>(method: K, params: LSPNotifyMap[K]): Promise<void>;
     protected processNotification(notification: Notification): void;
 }
+/** Controls how document changes are sent to the language server. */
 export declare enum SynchronizationMethod {
+    /** Send the full document text on every change. */
     Full = "full",
+    /** Send only the changed ranges. More efficient for large documents. */
     Incremental = "incremental"
 }
 export declare class LanguageServerPlugin implements PluginValue {
@@ -181,16 +192,28 @@ export declare const languageServerPlugin: ViewPlugin<LanguageServerPlugin, {
     allowHTMLContent: boolean;
     synchronizationMethod: SynchronizationMethod;
 }>;
+/** Base options shared by all language server configurations. */
 export interface LanguageServerBaseOptions {
+    /** Root URI of the workspace (e.g. `'file:///'`). */
     rootUri: string | null;
+    /** LSP workspace folders, if applicable. */
     workspaceFolders: LSP.WorkspaceFolder[] | null;
+    /** URI of the document being edited (e.g. `'file:///main.cpp'`). */
     documentUri: string;
+    /** Language identifier as defined by the LSP specification. */
     languageId: string;
 }
+/** Options for creating a {@link LanguageServerClient}. */
 export interface LanguageServerClientOptions<InitializationOptions = unknown> extends LanguageServerBaseOptions {
+    /** The transport used to communicate with the language server. */
     transport: Transport;
+    /** Close the transport when the last plugin detaches. */
     autoClose?: boolean;
+    /** Server-specific initialization options. */
     initializationOptions?: InitializationOptions;
+    /** Locale for the LSP session (e.g. `'en'`). Sent in the `initialize` request. */
     locale?: string;
+    /** Called once after initialization with the server's capabilities. */
+    onCapabilities?: (capabilities: LSP.ServerCapabilities) => void;
 }
 export {};

package/dist/rename.d.ts

@@ -1,4 +1,10 @@
 import { StateField } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
+/**
+ * Command: open a rename prompt for the symbol at the cursor.
+ *
+ * Uses `textDocument/prepareRename` to pre-fill the current name if supported
+ * by the server. Press Enter to confirm or Escape to cancel.
+ */
 export declare function renameSymbol(view: EditorView): boolean;
 export declare const renameExtension: () => StateField<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "codemirror-languageserver",
-    "version": "1.19.0",
+    "version": "1.20.0",
     "description": "Language Server Plugin for CodeMirror 6",
     "main": "dist/index.js",
     "type": "module",