Lexical for Rust
A native Rust port of Lexical's model and headless
packages. Your app builds an editor from extensions, as in JS, and runs
updates, commands and listeners on it; the app draws the document and
feeds it input, as a browser does for contenteditable.
It's a port of the JS packages and behaves the same: the same documents give the same editor state and the same JSON, byte for byte, in the legacy and compact forms. Conformance vectors generated from upstream JS check it, and the playgrounds' sessions are replayed in JS.
[!NOTE] Before 1.0, minor versions may change the API.
Install
Rust 1.88 or later. The crate is lexical-ui, used as lexical_ui; the
core is always built, and each upstream package is an opt-in
feature.
Quick start
use build_editor_from_extensions;
use history_extension;
use rich_text_extension;
use ;
// Rich text and undo, as JS's `buildEditorFromExtensions`.
let editor =
build_editor_from_extensions?;
// `$` functions drop the `$`, and work inside `update` and `read`.
editor.update?;
let text = editor.read?;
// The same JSON as JS, byte for byte (`true` for the compact form).
let json = editor.get_editor_state.to_json.to_string;
editor.set_editor_state?;
API at a glance
The API reference documents every item, and names the JS function each one ports.
| Concept | API | Notes |
|---|---|---|
| Editor | extension::build_editor_from_extensions(...)?, define_extension, config_extension |
create_editor(CreateEditorArgs) without extensions |
| Updates and reads | editor.update(|| ..., options)?, editor.read(|| ...)?, get_root(), get_selection() |
$getRoot() is get_root() |
| Nodes | NodeRef: append, remove, split_text, toggle_format, ... |
Resolves the latest version on every call |
| Commands | create_command, register_command, dispatch_command |
JS's COMMAND_PRIORITY_* |
| Listeners | register_update_listener, register_text_content_listener, register_mutation_listener |
Return an Unregister |
| Transforms | register_node_transform |
|
| JSON | get_editor_state().to_json(compact), parse_editor_state(&str)? |
The crate's own json, not serde |
| Custom nodes | impl LexicalNode, registered in the editor's nodes |
ElementData, TextData for the base classes |
| Node state | create_state, get_state, set_state |
|
| The app's view | set_root_element, on_selection_change, on_key_down, on_before_input |
The app lays out and hit-tests |
Features
The default build is the core, with no dependencies. Each feature ports the upstream package of the same name, and enables the features it needs:
| Feature | Adds |
|---|---|
extension |
The extension API and its model-level extensions, with each other feature's extensions |
rich-text, plain-text |
register_rich_text, register_plain_text, headings and quotes |
history, selection, utils, clipboard, text |
The upstream packages of the same name |
list, link, mark, hashtag, overflow, decorator-block |
Their nodes and commands |
autolink |
Auto-linking, on the regex crate: the one feature with a dependency |
code, code-highlight |
Code blocks, and highlighting over a Tokenizer the app supplies |
markdown |
Import, export and shortcuts |
html |
A DOM of its own, HTML export and import |
a11y, menu, auto-embed, file, devtools |
Announcements, typeahead menus, auto-embed, .lexical files, the tree view |
Differences from JS
- No
$prefix, and snake case:$getRoot()isget_root(). JS's invariants return aLexicalErrorwith the same message. - One thread. An
Editoris neitherSendnorSync. - No editing UI. The app draws the document, lays it out and moves the
caret, and sends Lexical its input as commands; the playgrounds show how.
With the
htmlfeature, the crate has a DOM of its own. - Code highlighting runs over the app's
Tokenizer; Prism's grammars aren't ported. - Offsets are UTF-16 code units, as in JS.
PARITY.md maps each part of the JS packages to its Rust name, and lists what isn't ported and the documented exceptions.
Compatibility
| lexical-ui | Conforms to upstream Lexical |
|---|---|
| 0.1.0+ | 0.53.0 |
Each release's section in
CHANGELOG.md
names the upstream version, as does lexical_ui::UPSTREAM_VERSION.
Documentation
- Lexical's docs
- API reference on docs.rs
- Coming from JS
- The design and the changelog
- Desktop playgrounds on one shared core
(
apps/lexical-playground-core):lexical-playground-gpuiandlexical-playground-rune
Contributing
This directory is published from wevm/lexical
(rust/), a fork of meta/lexical; send
changes there. From rust/ in that repository:
License
MIT, like Lexical.