The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
/**
* Plugin custom editors (`[[contributes.customEditors]]`): a file matching
* the declared patterns opens in a tab whose content the plugin renders from
* the file's document. The tab joins the document shared by every editor of
* the file (`attachDocument`), so:
*
* - the plugin edits the document (versioned `apply-edits`), and a text tab
* of the same file shows the change at once — and the other way round;
* - Undo / Redo work on the document's one history: the text tab's when one
* is open, else this tab's own;
* - unsaved changes, Save, and the close prompts are the document's.
*/
import { history } from "@codemirror/commands";
import { EditorState } from "@codemirror/state";
import { EditorView } from "@codemirror/view";
import { useEffect, useMemo, useState } from "react";
import { attachDocument, type DocumentAttachment } from "@/editor/api";
import { tx } from "@/platform/i18n";
import { EmptyState, Spinner } from "@/ui";
import {
editorService,
notifyEditorDocumentChanged,
type EditorDocumentLifecycle,
type EditorInput,
} from "@/workbench/contributions";
import { PluginView } from "./PluginView";
import { WebView, type DocumentState, type FrameDocument } from "./WebView";
import styles from "./PluginView.module.css";
export const CUSTOM_EDITOR_KIND = "pluginEditor";
export interface CustomEditorData {
pluginId: string;
editorId: string;
title: string;
/** A web page of the package (`web`) rather than content the code renders. */
web?: boolean;
}
export interface CustomEditorDecl {
id: string;
title: string;
patterns: string[];
priority: "default" | "option";
/** `tab`: its own tab; `split` / `preview`: beside the text editor, starting in that layout. */
layout?: "tab" | "split" | "preview";
web?: string;
}
export function customEditorInput(pluginId: string, decl: CustomEditorDecl, path: string): EditorInput {
const data: CustomEditorData = { pluginId, editorId: decl.id, title: decl.title, web: !!decl.web };
return { kind: CUSTOM_EDITOR_KIND, key: `${CUSTOM_EDITOR_KIND}:${pluginId}/${decl.id}:${path}`, path, data };
}
/** File name glob (`*`, `?`, `[abc]`, `{a,b}`), case-insensitive. */
export function matchesPattern(pattern: string, name: string): boolean {
let re = "";
for (let i = 0; i < pattern.length; i++) {
const c = pattern[i]!;
if (c === "*") re += "[^/]*";
else if (c === "?") re += "[^/]";
else if (c === "{") {
const end = pattern.indexOf("}", i);
if (end < 0) re += "\\{";
else {
re += `(?:${pattern
.slice(i + 1, end)
.split(",")
.map((p) => p.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*"))
.join("|")})`;
i = end;
}
} else if (c === "[") {
const end = pattern.indexOf("]", i);
if (end < 0) re += "\\[";
else {
re += pattern.slice(i, end + 1);
i = end;
}
} else re += c.replace(/[.+^$()|\\]/g, "\\$&");
}
return new RegExp(`^${re}$`, "i").test(name);
}
export function basename(path: string): string {
return path.split(/[\\/]/).pop() ?? path;
}
// --- sessions: one per document shown by a custom editor (splits share it) -----------
interface Session {
attachment: DocumentAttachment;
/** Holds this tab's undo history and receives the document's changes. */
view: EditorView;
revision: number;
listeners: Set<(revision: number) => void>;
/** The document as web frames see it. */
frameDocument: FrameDocument;
cancelTimer: () => void;
}
const sessions = new Map<string, Promise<Session>>();
/** Edits settle in the backend before the plugin renders the table again. */
const RENDER_DELAY_MS = 120;
function session(key: string, path: string): Promise<Session> {
let s = sessions.get(key);
if (!s) {
s = attachDocument(path).then((attachment) => {
const listeners = new Set<(revision: number) => void>();
const frameListeners = new Set<(state: DocumentState) => void>();
let timer: ReturnType<typeof setTimeout> | null = null;
// Bumped by every change: what frames' versioned edits are checked against.
let version = 0;
// Set while a frame's edit is applied: its changes (arriving synchronously) aren't echoed back.
let framing = false;
const changed = (byFrame: boolean) => {
version++;
notifyEditorDocumentChanged();
if (!byFrame && frameListeners.size) {
const state = { version, text: view.state.doc.toString() };
for (const l of frameListeners) l(state);
}
if (timer) clearTimeout(timer);
timer = setTimeout(() => {
timer = null;
void attachment.synced().then(() => {
state.revision++;
for (const l of listeners) l(state.revision);
});
}, RENDER_DELAY_MS);
};
const view = new EditorView({
state: EditorState.create({
doc: attachment.text(),
extensions: [
attachment.extension,
history(),
EditorView.updateListener.of((u) => u.docChanged && changed(framing)),
],
}),
});
const frameDocument: FrameDocument = {
read: () => ({ version, text: view.state.doc.toString(), readOnly: attachment.readOnly, name: basename(path) }),
edit: (at, changes) => {
if (at !== version) throw new Error("stale");
// One edit of the document's history: Undo in the text editor (or this tab) reverts it.
framing = true;
try {
attachment.edit([...changes], "input.plugin");
} finally {
framing = false;
}
return version;
},
subscribe: (listener) => {
frameListeners.add(listener);
return () => frameListeners.delete(listener);
},
};
const state: Session = {
attachment,
view,
revision: 0,
listeners,
frameDocument,
cancelTimer: () => timer && clearTimeout(timer),
};
return state;
});
sessions.set(key, s);
s.catch(() => sessions.delete(key));
}
return s;
}
async function closeSession(key: string) {
const s = sessions.get(key);
sessions.delete(key);
if (!s) return;
const state = await s;
settled.delete(key);
state.cancelTimer();
state.attachment.release();
state.view.destroy();
}
async function withSession<T>(input: EditorInput, f: (s: Session) => T | Promise<T>): Promise<T | undefined> {
const s = sessions.get(input.key);
return s ? f(await s) : undefined;
}
const settled = new Map<string, Session>();
/** Lifecycle of the tabs' document (dirty mark, Save, close prompts, Undo). */
export const customEditorDocument: EditorDocumentLifecycle = {
isDirty: (input) => settled.get(input.key)?.attachment.dirty() ?? false,
flush: async (input) => {
await withSession(input, (s) => s.attachment.synced());
},
save: async (input) => {
await withSession(input, (s) => s.attachment.save());
},
prepareClose: async (input) => {
await withSession(input, (s) => s.attachment.synced());
},
cancelClose: () => {},
discard: async () => {
// The document's unsaved changes go when it closes (`close` releases it).
},
close: (input) => closeSession(input.key),
undo: async (input) => {
await withSession(input, (s) => void s.attachment.undo());
},
redo: async (input) => {
await withSession(input, (s) => void s.attachment.redo());
},
};
type SessionState = { session: Session; revision: number } | { error: string } | null;
/** The session `key` of `path`, kept for as long as the component shows it. */
function useSession(key: string, path: string, release: boolean): SessionState {
const [state, setState] = useState<SessionState>(null);
useEffect(() => {
let live = true;
let off = () => {};
session(key, path).then(
(s) => {
if (!live) return;
settled.set(key, s);
const listener = (revision: number) => setState({ session: s, revision });
s.listeners.add(listener);
off = () => s.listeners.delete(listener);
setState({ session: s, revision: s.revision });
},
(e: unknown) => live && setState({ error: e instanceof Error ? e.message : String(e) }),
);
return () => {
live = false;
off();
// A tab's session lives until the tab closes (its lifecycle); a preview's until it unmounts.
if (release) void closeSession(key);
};
}, [key, path, release]);
return state;
}
function SessionBody({
state,
pluginId,
editorId,
web,
label,
path,
}: {
state: Exclude<SessionState, null | { error: string }>;
pluginId: string;
editorId: string;
web: boolean;
label: string;
path: string;
}) {
const { session: s, revision } = state;
if (web)
return (
<WebView pluginId={pluginId} view={editorId} label={label} document={s.frameDocument} doc={s.attachment.doc} />
);
return (
<PluginView
pluginId={pluginId}
view={editorId}
doc={s.attachment.doc}
revision={revision}
label={label}
key={path}
/>
);
}
export function CustomEditor({ input }: { input: EditorInput }) {
const data = input.data as CustomEditorData;
const state = useSession(input.key, input.path ?? "", false);
if (!state)
return (
<div className={styles.empty}>
<Spinner label={tx("Loading")} />
</div>
);
if ("error" in state)
return (
<EmptyState className={styles.empty} title={tx`Cannot open ${basename(input.path ?? "")}`}>
{state.error}
</EmptyState>
);
return (
<div className={styles.view}>
<SessionBody
state={state}
pluginId={data.pluginId}
editorId={data.editorId}
web={!!data.web}
label={tx`${data.title}: ${basename(input.path ?? "")}`}
path={input.path ?? ""}
/>
<div className={styles.status}>
<button
type="button"
className={styles.textButton}
onClick={() => input.path && void editorService().openFile(input.path, { asText: true })}
>
{tx("Open as Text")}
</button>
</div>
</div>
);
}
/**
* A custom editor beside the text editor (`layout = "split"` / `"preview"`):
* the same document, so each follows the other's edits.
*/
export function CustomEditorPreview({
pluginId,
decl,
path,
}: {
pluginId: string;
decl: CustomEditorDecl;
path: string;
}) {
const key = useMemo(() => `pluginPreview:${pluginId}/${decl.id}:${path}`, [pluginId, decl.id, path]);
const state = useSession(key, path, true);
const label = tx`${decl.title}: ${basename(path)}`;
if (!state)
return (
<div className={styles.empty}>
<Spinner label={tx("Loading")} />
</div>
);
if ("error" in state)
return (
<EmptyState className={styles.empty} title={tx`Cannot open ${basename(path)}`}>
{state.error}
</EmptyState>
);
return (
<div className={styles.view}>
<SessionBody state={state} pluginId={pluginId} editorId={decl.id} web={!!decl.web} label={label} path={path} />
</div>
);
}