Skip to main content

lexical_ui/
lib.rs

1//! A Rust port of [Lexical](https://lexical.dev)'s model and headless
2//! packages, at parity with the JS implementation: the same documents give
3//! the same editor state and the same JSON, byte for byte, in the legacy and
4//! compact forms. Parity is checked against the conformance vectors that
5//! `packages/lexical-conformance` records from the JS packages (see
6//! `rust/PARITY.md`).
7//!
8//! The internals mirror the upstream sources file by file. JS's `$`
9//! functions drop the `$` and take snake case: `$getRoot()` is
10//! [`get_root()`], and like JS they only work inside [`Editor::update`],
11//! [`Editor::read`] or [`EditorState::read`]. A node is read and changed
12//! through a [`NodeRef`], which resolves the latest version on every call,
13//! as JS node methods do. Text offsets are UTF-16 code units, as in JS.
14//!
15//! ```
16//! use lexical_ui::{create_editor, get_root, CreateEditorArgs, UpdateOptions};
17//!
18//! let editor = create_editor(CreateEditorArgs::default());
19//! let state = editor
20//!     .parse_editor_state(r#"{"root":{"type":"root","children":[{"type":"paragraph","children":[{"type":"text","text":"Hi"}]}]}}"#)
21//!     .unwrap();
22//! assert_eq!(state.read(|| get_root().get_text_content()), "Hi");
23//! assert_eq!(
24//!     state.to_json(true).to_string(),
25//!     r#"{"root":{"type":"root","children":[{"type":"paragraph","children":[{"type":"text","text":"Hi"}]}]}}"#,
26//! );
27//!
28//! // An update: split the text and bold the second half.
29//! editor.set_editor_state(&state, None).unwrap();
30//! editor
31//!     .update(
32//!         || {
33//!             let text = get_root().get_first_descendant().unwrap();
34//!             let parts = text.split_text(&[1])?;
35//!             parts[1].toggle_format("bold");
36//!             Ok(())
37//!         },
38//!         UpdateOptions { discrete: true, ..UpdateOptions::default() },
39//!     )
40//!     .unwrap();
41//! assert_eq!(
42//!     editor.get_editor_state().to_json(true).to_string(),
43//!     r#"{"root":{"type":"root","children":[{"type":"paragraph","children":[{"type":"text","text":"H"},{"type":"text","format":1,"text":"i"}]}]}}"#,
44//! );
45//! ```
46
47#[cfg(feature = "a11y")]
48pub mod a11y;
49#[cfg(feature = "auto-embed")]
50pub mod auto_embed;
51mod caret;
52mod caret_tree;
53mod caret_utils;
54#[cfg(feature = "clipboard")]
55pub mod clipboard;
56#[cfg(feature = "code")]
57pub mod code;
58mod commands;
59pub mod constants;
60#[cfg(feature = "decorator-block")]
61pub mod decorator_block;
62#[cfg(feature = "devtools")]
63pub mod devtools;
64#[cfg(feature = "html")]
65pub mod dom;
66mod editor;
67mod editor_state;
68mod environment;
69mod error;
70mod events;
71#[cfg(feature = "extension")]
72pub mod extension;
73#[cfg(feature = "extension")]
74mod extension_core;
75#[cfg(feature = "file")]
76pub mod file;
77mod gc;
78mod generated_json;
79#[cfg(feature = "hashtag")]
80pub mod hashtag;
81pub mod headless;
82#[cfg(feature = "history")]
83pub mod history;
84#[cfg(feature = "html")]
85pub mod html;
86pub mod json;
87mod keyboard_shortcuts;
88#[cfg(feature = "html")]
89pub mod lexical_dom;
90mod lexical_selection;
91mod lexical_utils;
92#[cfg(feature = "link")]
93pub mod link;
94#[cfg(feature = "list")]
95pub mod list;
96#[cfg(feature = "mark")]
97pub mod mark;
98#[cfg(feature = "markdown")]
99pub mod markdown;
100#[cfg(feature = "menu")]
101pub mod menu;
102mod merge_register;
103mod node;
104mod node_state;
105pub mod nodes;
106mod normalization;
107mod ordered;
108#[cfg(feature = "overflow")]
109pub mod overflow;
110#[cfg(feature = "plain-text")]
111pub mod plain_text;
112mod reconciler;
113mod ref_counted_registry;
114#[cfg(feature = "rich-text")]
115pub mod rich_text;
116pub mod schema;
117#[cfg(feature = "selection")]
118pub mod selection;
119mod selection_deletion;
120mod selection_editing;
121mod selection_format;
122mod selection_insert_nodes;
123mod selection_insert_text;
124mod serialized_export;
125mod set_dom_style;
126mod slot;
127mod structure;
128#[cfg(feature = "table")]
129pub mod table;
130#[cfg(feature = "text")]
131pub mod text;
132mod updates;
133pub mod utf16;
134#[cfg(feature = "utils")]
135pub mod utils;
136mod warnings;
137
138#[cfg(test)]
139mod upstream_tests;
140
141pub use caret::{
142    CaretDirection, CaretKind, CaretRange, ChildCaret, CommonAncestorAcrossSlotsResult,
143    CommonAncestorResult, NodeCaret, PointCaret, RootMode, SiblingCaret, TextOffset,
144    TextPointCaret, TextPointCaretSlice, compare_point_caret_next,
145    compare_point_caret_next_across_slots, extend_caret_to_range, flip_direction,
146    get_adjacent_child_caret, get_caret_in_direction, get_caret_range, get_child_caret,
147    get_child_caret_or_self, get_collapsed_caret_range, get_common_ancestor,
148    get_common_ancestor_across_slots, get_common_ancestor_result_branch_order, get_sibling_caret,
149    get_text_node_offset, get_text_point_caret, get_text_point_caret_slice, make_stepwise_iterator,
150};
151pub use caret_utils::{
152    SliceMode, SplitAtPointCaretNextOptions, caret_from_point, caret_range_from_selection,
153    get_adjacent_sibling_or_parent_sibling_caret, get_caret_range_in_direction,
154    get_child_caret_at_index, get_text_point_caret_slice_for_node,
155    insert_node_to_nearest_root_at_caret, is_extendable_text_point_caret, normalize_caret,
156    remove_text_from_caret_range, rewind_sibling_caret, set_point_from_caret,
157    set_selection_from_caret_range, split_at_point_caret_next, split_text_point_caret,
158    update_range_selection_from_caret_range,
159};
160pub use commands::{
161    BEFORE_INPUT_COMMAND, BLUR_COMMAND, CAN_REDO_COMMAND, CAN_UNDO_COMMAND, CLEAR_EDITOR_COMMAND,
162    CLEAR_HISTORY_COMMAND, CLICK_COMMAND, COMPOSITION_END_COMMAND, COMPOSITION_START_COMMAND,
163    CONTROLLED_TEXT_INSERTION_COMMAND, COPY_COMMAND, CUT_COMMAND, DELETE_CHARACTER_COMMAND,
164    DELETE_LINE_COMMAND, DELETE_WORD_COMMAND, DRAGEND_COMMAND, DRAGOVER_COMMAND, DRAGSTART_COMMAND,
165    DROP_COMMAND, FOCUS_COMMAND, FORMAT_ELEMENT_COMMAND, FORMAT_TEXT_COMMAND,
166    INDENT_CONTENT_COMMAND, INPUT_COMMAND, INSERT_LINE_BREAK_COMMAND, INSERT_PARAGRAPH_COMMAND,
167    INSERT_TAB_COMMAND, InsertClipboardNodesPayload, KEY_ARROW_DOWN_COMMAND,
168    KEY_ARROW_LEFT_COMMAND, KEY_ARROW_RIGHT_COMMAND, KEY_ARROW_UP_COMMAND, KEY_BACKSPACE_COMMAND,
169    KEY_DELETE_COMMAND, KEY_DOWN_COMMAND, KEY_ENTER_COMMAND, KEY_ESCAPE_COMMAND,
170    KEY_MODIFIER_COMMAND, KEY_SPACE_COMMAND, KEY_TAB_COMMAND, MOVE_TO_END, MOVE_TO_START,
171    OUTDENT_CONTENT_COMMAND, PASTE_COMMAND, REDO_COMMAND, REMOVE_TEXT_COMMAND, SELECT_ALL_COMMAND,
172    SELECTION_CHANGE_COMMAND, SELECTION_INSERT_CLIPBOARD_NODES_COMMAND, SET_TEXT_FORMAT_COMMAND,
173    UNDO_COMMAND,
174};
175pub use editor::{
176    COLLABORATION_TAG, COMMAND_PRIORITY_BEFORE_CRITICAL, COMMAND_PRIORITY_BEFORE_EDITOR,
177    COMMAND_PRIORITY_BEFORE_HIGH, COMMAND_PRIORITY_BEFORE_LOW, COMMAND_PRIORITY_BEFORE_NORMAL,
178    COMMAND_PRIORITY_CRITICAL, COMMAND_PRIORITY_EDITOR, COMMAND_PRIORITY_HIGH,
179    COMMAND_PRIORITY_LOW, COMMAND_PRIORITY_NORMAL, COMPOSITION_END_TAG, COMPOSITION_START_TAG,
180    CUT_TAG, CreateEditorArgs, DEFER_COMPOSITION_MERGE_TAG, Editor, EditorConfig,
181    EditorFocusOptions, EditorReadMode, FOCUS_TAG, HISTORIC_TAG, HISTORY_MERGE_TAG,
182    HISTORY_PUSH_TAG, LexicalCommand, LexicalNodeReplacement, ListenerCleanup, MutatedNodes,
183    MutationListenerOptions, MutationListenerPayload, NodeClass, NodeMutation, NodeMutations,
184    NodeReplace, PASTE_TAG, RootElement, RootElementRef, SKIP_COLLAB_TAG, SKIP_DOM_SELECTION_TAG,
185    SKIP_SCROLL_INTO_VIEW_TAG, SKIP_SELECTION_FOCUS_TAG, Transform, Unregister,
186    UpdateListenerPayload, UpdateOptions, WarningHandler, add_update_tag, create_command,
187    create_editor, get_editor, has_update_tag,
188};
189pub use editor_state::EditorState;
190pub use environment::{is_apple, with_is_apple};
191pub use error::{LexicalError, LexicalWarning};
192pub use events::{
193    ClipboardEvent, ClipboardOrKeyboardEvent, CompositionEvent, DataTransfer, DataTransferFile,
194    DragEvent, Event, FocusEvent, InputEvent, KeyboardEvent, MouseEvent, PasteCommandType,
195    on_before_input, on_composition_end, on_composition_start, on_key_down, on_selection_change,
196};
197#[cfg(feature = "extension")]
198pub use extension_core::{
199    AbortController, AbortSignal, AnyLexicalExtension, AnyLexicalExtensionArgument,
200    ExtensionBuildFn, ExtensionBuildState, ExtensionConfigBase, ExtensionInitFn,
201    ExtensionInitState, ExtensionMergeConfigFn, ExtensionRegisterFn, ExtensionRegisterState,
202    InitialEditorConfig, InitialEditorStateFn, InitialEditorStateType, LexicalExtension,
203    LexicalExtensionDependency, NormalizedPeerDependency, config_extension,
204    declare_peer_dependency, define_extension, safe_cast, shallow_merge_config,
205};
206pub use headless::create_headless_editor;
207pub use keyboard_shortcuts::{
208    CompiledKeyboardShortcuts, KeyboardShortcut, KeyboardShortcutMatch, ShortcutDisabledFn,
209    ShortcutDispatchFn, compile_keyboard_shortcuts, control_or_alt, control_or_meta,
210};
211pub use lexical_selection::{
212    NodeSelection, Point, PointType, RangeSelection, Selection, SelectionRef, Which,
213    clamp_range_selection_to_slot_frame, create_node_selection, create_range_selection,
214    get_point_slot_frame, get_selection, is_same_frame, set_selection,
215};
216pub use lexical_utils::{
217    ControlOrOther, KeyboardEventModifierMask, KeyboardEventModifiers, ModifierExpectation,
218    TypeToNodeMap, apply_node_replacement, clone_with_properties, clone_with_properties_ephemeral,
219    copy_node, copy_node_with, create, get_adjacent_node, get_cached_type_to_node_map,
220    get_composition_key, get_node_by_key, get_registered_subtype_map, get_root, get_text_direction,
221    is_backspace, is_delete, is_escape, is_exact_shortcut_match, is_modifier, is_modifier_match,
222    is_root_or_shadow_root, is_select_all, is_token_or_segmented, keyboard_event_mask_for_platform,
223    nodes_of_type, reset_random_key, set_composition_key, split_node,
224};
225pub use merge_register::merge_register;
226pub use node::{LexicalNode, NodeBase, NodeClone, NodeKey, NodeRef};
227pub use node_state::{
228    AnyStateConfig, RequiredNodeStateConfig, StateConfig, StateIsEqual, StateValue,
229    StateValueConfig, create_state, create_state_with, get_state, get_state_change,
230    get_state_direct, set_state, set_state_with,
231};
232pub use nodes::element::{Direction, ElementData};
233pub use nodes::paragraph::create_paragraph_node;
234pub use nodes::text::{TextData, create_text_node, toggle_text_format_type};
235pub use reconciler::Decorators;
236pub use ref_counted_registry::{RefCountedRegistry, create_ref_counted_registry};
237pub use selection_deletion::{
238    SelectionAlter, SelectionGranularity, SelectionMovement, is_block_fully_selected,
239    is_block_fully_selected_by_caret_range,
240};
241pub use selection_insert_nodes::{insert_nodes, select_all, select_all_in};
242pub use serialized_export::{export_node_json, is_compact_export, with_compact_export};
243pub use set_dom_style::{StyleObject, get_style_object_from_css, js_trim};
244#[cfg(feature = "html")]
245pub use set_dom_style::{set_dom_style_from_css, set_dom_style_object};
246pub use slot::{
247    get_declared_slots, get_selection_slot_frame, get_slot, get_slot_frame, get_slot_host,
248    get_slot_name_within_host, get_slot_names, is_slot_child, is_slot_host, remove_slot, set_slot,
249};
250pub use structure::{
251    DeclaredBy, DeclaredNodeStructure, LiftsFromStructure, MergeAdjacentConfig,
252    MergeAdjacentDeclaration, MergeAdjacentEntry, NodeChildEntry, NodeChildrenConfig, NodeClassRef,
253    NodeConfigLink, StaticNodeConfig, get_declared_node_structure, internal_is_inline_content,
254    internal_is_node_structure_enforced, internal_normalize_node_structure,
255    internal_register_node_structure, is_block_container, iter_static_node_config_chain,
256};
257pub use updates::{on_update, parse_serialized_node};
258pub use warnings::with_warning_handler;
259
260/// The upstream Lexical release this port conforms to. The conformance
261/// vectors (`meta.json`) name the same one, so an upstream sync can't move
262/// one without the other.
263pub const UPSTREAM_VERSION: &str = "0.53.0";