codemirror-languageserver 1.18.1 → 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/)
 
@@ -14,54 +14,229 @@ https://user-images.githubusercontent.com/348107/120141150-c6bb9180-c1fd-11eb-8a
 - 📚 Hover Documentation
 - 🩺 Diagnostics
 - 🔍 Go to Definition, Declaration, and Type Definition
+- 🔦 Document Highlight
+- 🎨 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';
 
-const transport = new WebSocketTransport(serverUri);
-
-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({
-        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,
-            // ...
         ],
     }),
 });
 ```
 
-### Using with Initialization Options
+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` for non-WebSocket connections:
+
+```js
+import { languageServerWithTransport } from 'codemirror-languageserver';
+
+const ls = languageServerWithTransport({
+    transport: myCustomTransport,
+    rootUri: 'file:///',
+    documentUri: `file:///${filename}`,
+    languageId: 'cpp',
+});
+```
+
+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;
+}
+```
 
-The plugin includes built-in TypeScript definitions for popular language servers:
+You can import `Transport` and `WebSocketTransport` from the package.
+
+## 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,
+.cm-lsp-highlight-read { background-color: rgba(255, 255, 0, 0.2); }
+.cm-lsp-highlight-write { background-color: rgba(255, 165, 0, 0.3); }
+```
 
--   `PyrightInitializationOptions` - Python (Pyright)
--   `RustAnalyzerInitializationOptions` - Rust (rust-analyzer)
--   `TypeScriptInitializationOptions` - TypeScript/JavaScript
--   `ESLintInitializationOptions` - ESLint
--   `ClangdInitializationOptions` - C/C++ (Clangd)
--   `GoplsInitializationOptions` - Go (Gopls)
+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](https://codemirror.net/docs/ref/#view.Command) — bind them to keys:
+
+```js
+import { keymap } from '@codemirror/view';
+import { formatDocument, formatSelection } from 'codemirror-languageserver';
+
+const formattingKeymap = keymap.of([
+    { key: 'Shift-Alt-f', run: formatDocument },
+    { key: 'Ctrl-k Ctrl-f', run: formatSelection },
+]);
+```
+
+### Formatting Options
+
+Configure formatting with the `formattingOptions` facet. By default, `tabSize` is read from the editor state.
+
+```js
+import { formattingOptions } from 'codemirror-languageserver';
+
+// In extensions:
+formattingOptions.of({
+    tabSize: 2,
+    insertSpaces: true,
+    trimTrailingWhitespace: true,
+    insertFinalNewline: true,
+    trimFinalNewlines: true,
+})
+```
+
+## Rename Symbol
+
+`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';
+
+const renameKeymap = keymap.of([
+    { key: 'F2', run: renameSymbol },
+]);
+```
+
+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;
+}
+```
+
+## Server Capabilities
+
+Use the `onCapabilities` callback to react when the server finishes initializing — e.g. to show or hide toolbar buttons:
+
+```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
 
@@ -69,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

@@ -0,0 +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

@@ -0,0 +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

@@ -1,5 +1,9 @@
 export { LanguageServerClient, languageServerPlugin, SynchronizationMethod, } from './plugin';
+export { WebSocketTransport } from './jsonrpc';
+export type { Transport } from './jsonrpc';
 export { jumpToDefinition, jumpToDefinitionPos, jumpToDefinitionKeymap, } from './definition';
+export { formatDocument, formatSelection, formattingOptions, } from './formatting';
+export { renameSymbol } from './rename';
 export { PyrightInitializationOptions, RustAnalyzerInitializationOptions, TypeScriptInitializationOptions, ESLintInitializationOptions, ClangdInitializationOptions, GoplsInitializationOptions, } from './initialization';
 import { LanguageServerClient, SynchronizationMethod } from './plugin';
 import type { LanguageServerClientOptions, LanguageServerBaseOptions } from './plugin';
@@ -12,5 +16,16 @@ interface LanguageServerWebsocketOptions<InitializationOptions = unknown> extend
     serverUri: `ws://${string}` | `wss://${string}`;
     initializationOptions?: InitializationOptions;
 }
-export declare function languageServer<InitializationOptions = unknown>(options: LanguageServerWebsocketOptions<InitializationOptions>): import("@codemirror/state").Extension[];
-export declare function languageServerWithTransport<InitializationOptions = unknown>(options: LanguageServerOptions<InitializationOptions>): import("@codemirror/state").Extension[];
+/**
+ * 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>)[];