@adecore/editor

A code editor for the DOM. It draws a DocumentModel with a layout of its own, renders only the rows in view, and takes keys, the mouse, the clipboard and input methods through one hidden textarea. It knows no language server: a host hands it markers, hints, colors and rows of its own, and @adecore/editor-react does that for an LSP language service.

import { createSmartEditorEngine } from '@adecore/editor';

const engine = createSmartEditorEngine({ tokenizer: shikiTokenizers(getHighlighter) });
const editor = engine.mount(element, { text, language: 'typescript', theme: 'github-light' });

import { EditorFrame } from '../shared/editor-frame.tsx';
import { SAMPLE, useEditor } from '../shared/editor.ts';

const OPTIONS = { text: SAMPLE, language: 'typescript', theme: 'demo', foldOutline: 'always' } as const;

/* Type, fold a block in the gutter, add a caret with Alt and click, or undo with Mod+Z. */
export default function EditorDemo() {
    const { host } = useEditor(OPTIONS);

    return <EditorFrame host={host} />;
}

The demos on these pages color TypeScript with a small tokenizer of their own instead of Shiki; see Theme and syntax.

What is in it

• Getting started: install, the styles, mounting, the engine options and tearing down.
• Options and keymaps: every mount option with its setter, the smart keys, and one key table for the editor, menus and hints.
• Text and events: positions, replacing text, edits as one undo step, selections, change events and tracked ranges.
• Decorations: problem markers, inlay hints, highlights, semantic colors, change marks and gutter buttons.
• Rows and widgets: rows of the host's own DOM between lines, code that is not in the document, line highlights, line actions and code vision.
• Agents: attribution bars, the carets of agents and ghost text.
• Find and folding: the matcher behind a find bar, folds that persist and the blocks of sticky scroll.
• Theme and syntax: CSS tokens, Shiki and a tokenizer of your own.
• Testing: a real editor on a page without a browser, and a fake one.

Entry points

Import	What it holds
@adecore/editor	createSmartEditorEngine, the Editor contract and its types, DEFAULT_SMART_KEYS, AGENT_COLORS, shikiTokenizers, shikiScopeColors
@adecore/editor/editor.css	The styles of the editor
@adecore/editor/shiki	The Shiki adapters plus loadGrammar and documentLanguageOf
@adecore/editor/keymap	KEYMAP, KEYMAP_IDS, resolveKeymap, chordOf, parseChord
@adecore/editor/fake	FakeEditor and FakeEditorEngine, for tests of host code
@adecore/editor/testing	mountEditor and the helpers behind it, on a LinkeDOM page

Limits

• The editor has no bidirectional text layout. Right-to-left text is drawn left to right.
• The textarea carries the text around the caret and an aria-label from the label option for assistive technology. Nothing has been tested with a screen reader beyond that.
• A line longer than 20,000 characters is not colored.
• Every edit rebuilds the list of rows, which is linear in the number of lines.
• Folding ranges and the marks of a selection's other occurrences are skipped in a document over 2 million characters.
• Search and folding read the whole document synchronously, and a regular expression has no time limit; see the limits of the model.
• Wrapped lines break at spaces, or inside a word that does not fit, and continue at the line's indentation plus two columns.
• Documentation comments are drawn as text, not rendered.

The package is FSL-1.1-MIT.