Skip to main content

lexical_ui/
auto_embed.rs

1//! `@lexical/react`'s auto-embed without React (the `auto-embed` feature):
2//! `LexicalAutoEmbedPluginUtils.ts` ([`EmbedMatchResult`], [`EmbedConfig`],
3//! [`URL_MATCHER`](url_matcher), [`INSERT_EMBED_COMMAND`],
4//! [`AutoEmbedOption`]) and the logic of `LexicalAutoEmbedPlugin.tsx`
5//! ([`register_auto_embed`]): a pasted link that an embed config recognizes
6//! (a video, a post) opens a node menu at it that offers to replace it with
7//! the embed. React keeps the match in component state and renders
8//! `LexicalNodeMenuPlugin`; here [`register_auto_embed`] keeps it and
9//! drives a [`NodeMenu`], which the app's view draws.
10//!
11//! `parseUrl` may return a promise in JS, which the plugin awaits; here an
12//! [`EmbedConfig`] answers synchronously ([`EmbedConfig::parse_url`]) or
13//! later, through the [`ParseUrlDone`] that
14//! [`EmbedConfig::parse_url_async`] is given. A synchronous answer opens
15//! the menu in the paste's mutation listener, where JS's
16//! `await Promise.resolve(result)` opens it a microtask later
17//! (rust/PARITY.md).
18
19use crate::lexical_selection::get_selection;
20use crate::link::is_link_node;
21use crate::menu::{MenuOption, MenuSelectOption, NodeMenu};
22use crate::merge_register::merge_register;
23use crate::updates::on_update;
24use crate::{
25    COMMAND_PRIORITY_BEFORE_EDITOR, COMMAND_PRIORITY_EDITOR, Editor, EditorReadMode,
26    LexicalCommand, LexicalError, MutationListenerOptions, NodeKey, NodeMutation, NodeRef,
27    PASTE_COMMAND, PASTE_TAG, PasteCommandType, Unregister, UpdateOptions, get_node_by_key,
28};
29use std::any::Any;
30use std::cell::{Cell, RefCell};
31use std::rc::Rc;
32
33/// `EmbedMatchResult`: the matched `url`, the `id` of the embedded
34/// resource, and optional provider `data`.
35#[derive(Clone)]
36pub struct EmbedMatchResult {
37    pub url: String,
38    pub id: String,
39    pub data: Option<Rc<dyn Any>>,
40}
41
42/// `EmbedConfig`: a kind of embed, with its `type`, `parseUrl`, which
43/// decides whether a URL is one and extracts its data, and `insertNode`,
44/// which inserts its node. A config implements `parse_url`, or
45/// `parse_url_async` when it answers later (JS's `parseUrl` returning a
46/// promise).
47pub trait EmbedConfig {
48    /// `type`.
49    fn embed_type(&self) -> &str;
50    /// `parseUrl(text)`, answered now. `None` unless implemented.
51    fn parse_url(&self, _text: &str) -> Option<EmbedMatchResult> {
52        None
53    }
54    /// `parseUrl(text)` returning a promise: the config resolves `done`
55    /// with the result when it has one, now or later; dropping it is a
56    /// rejected promise, which ends the check. By default, resolves it
57    /// with [`parse_url`](Self::parse_url).
58    fn parse_url_async(&self, text: &str, done: ParseUrlDone) {
59        done.resolve(self.parse_url(text));
60    }
61    /// `insertNode(editor, result)`, in an update.
62    fn insert_node(&self, editor: &Editor, result: &EmbedMatchResult) -> Result<(), LexicalError>;
63}
64
65/// What settles a [`EmbedConfig::parse_url_async`], as the promise JS's
66/// `parseUrl` returns does: [`resolve`](Self::resolve) it with the result,
67/// or drop it to reject. Only the latest paste's check opens the menu, so
68/// a parse that resolves after a newer paste is ignored, as is one whose
69/// link was removed or given another URL meanwhile.
70pub struct ParseUrlDone(Option<Box<dyn FnOnce(Option<EmbedMatchResult>)>>);
71
72impl ParseUrlDone {
73    /// The promise resolved with `result`.
74    pub fn resolve(mut self, result: Option<EmbedMatchResult>) {
75        if let Some(resolve) = self.0.take() {
76            resolve(result);
77        }
78    }
79}
80
81/// `INSERT_EMBED_COMMAND`: starts inserting the embed whose config has the
82/// payload as its `type`.
83pub const INSERT_EMBED_COMMAND: LexicalCommand<String> =
84    LexicalCommand::constant(u64::MAX - 30, "INSERT_EMBED_COMMAND");
85
86/// `AutoEmbedOption`: an item of the embed menu, its key its title, with
87/// what choosing it does.
88pub struct AutoEmbedOption {
89    pub title: String,
90    /// `onSelect(targetNode)`.
91    pub on_select: Rc<dyn Fn(Option<NodeRef>) -> Result<(), LexicalError>>,
92}
93
94impl MenuOption for AutoEmbedOption {
95    fn key(&self) -> &str {
96        &self.title
97    }
98    fn title(&self) -> Option<&str> {
99        Some(&self.title)
100    }
101}
102
103fn is_word(unit: u16) -> bool {
104    matches!(unit, 0x30..=0x39 | 0x41..=0x5A | 0x61..=0x7A | 0x5F)
105}
106
107/// `[-a-zA-Z0-9@:%._+~#=]`.
108fn is_host_unit(unit: u16) -> bool {
109    is_word(unit) && unit != 0x5F || b"-@:%._+~#=".iter().any(|&c| u16::from(c) == unit)
110}
111
112/// `[a-zA-Z0-9()]`.
113fn is_tld_unit(unit: u16) -> bool {
114    is_word(unit) && unit != 0x5F || unit == u16::from(b'(') || unit == u16::from(b')')
115}
116
117/// `[-a-zA-Z0-9()@:%_+.~#?&//=]`.
118fn is_path_unit(unit: u16) -> bool {
119    is_word(unit) || b"-()@:%+.~#?&/=".iter().any(|&c| u16::from(c) == unit)
120}
121
122/// The match of `URL_MATCHER` at `start`, its end, as `exec` finds it.
123fn match_url_at(units: &[u16], start: usize) -> Option<usize> {
124    let has = |at: usize, text: &str| {
125        text.encode_utf16()
126            .enumerate()
127            .all(|(i, u)| units.get(at + i) == Some(&u))
128    };
129    // `((https?:\/\/(www\.)?)|(www\.))`, each alternative's ends in the order
130    // the backtracking tries them.
131    let mut prefixes = Vec::new();
132    if has(start, "http") {
133        let scheme = if has(start + 4, "s") {
134            start + 5
135        } else {
136            start + 4
137        };
138        if has(scheme, "://") {
139            let after = scheme + 3;
140            if has(after, "www.") {
141                prefixes.push(after + 4);
142            }
143            prefixes.push(after);
144        }
145    }
146    if has(start, "www.") {
147        prefixes.push(start + 4);
148    }
149    prefixes.into_iter().find_map(|prefix| {
150        // `[-a-zA-Z0-9@:%._+~#=]{1,256}`, longest first.
151        let host_max = units[prefix..]
152            .iter()
153            .take(256)
154            .take_while(|&&u| is_host_unit(u))
155            .count();
156        (1..=host_max).rev().find_map(|host| {
157            let dot = prefix + host;
158            if units.get(dot) != Some(&u16::from(b'.')) {
159                return None;
160            }
161            // `\.[a-zA-Z0-9()]{1,6}\b`, longest first.
162            let tld_max = units[dot + 1..]
163                .iter()
164                .take(6)
165                .take_while(|&&u| is_tld_unit(u))
166                .count();
167            (1..=tld_max).rev().find_map(|tld| {
168                let end = dot + 1 + tld;
169                let before = is_word(units[end - 1]);
170                let after = units.get(end).is_some_and(|&u| is_word(u));
171                (before != after).then(|| {
172                    // `([-a-zA-Z0-9()@:%_+.~#?&//=]*)`.
173                    end + units[end..]
174                        .iter()
175                        .take_while(|&&u| is_path_unit(u))
176                        .count()
177                })
178            })
179        })
180    })
181}
182
183/// `URL_MATCHER.exec(text)`: the UTF-16 index and the text of the first
184/// match of
185/// `((https?:\/\/(www\.)?)|(www\.))[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)`,
186/// a general-purpose URL expression for a `parseUrl`, matched by hand as JS
187/// matches it.
188pub fn url_matcher(text: &str) -> Option<(usize, String)> {
189    let units: Vec<u16> = text.encode_utf16().collect();
190    (0..units.len()).find_map(|start| {
191        match_url_at(&units, start).map(|end| (start, String::from_utf16_lossy(&units[start..end])))
192    })
193}
194
195/// `/^\S+$/.test(text)`: whether a paste is one token, which JS's `\s`
196/// (Unicode's white space, less U+0085 and U+180E, and U+FEFF) does not
197/// split.
198pub fn is_single_token(text: &str) -> bool {
199    !text.is_empty()
200        && !text
201            .chars()
202            .any(crate::selection_deletion::is_js_whitespace)
203}
204
205/// `getMenuOptions(activeEmbedConfig, embedFn, dismissFn)`.
206pub type GetMenuOptions =
207    Rc<dyn Fn(&Rc<dyn EmbedConfig>, Rc<dyn Fn()>, Rc<dyn Fn()>) -> Vec<Rc<AutoEmbedOption>>>;
208
209/// `onOpenEmbedModalForConfig(embedConfig)`.
210pub type OpenEmbedModalForConfig = Rc<dyn Fn(&Rc<dyn EmbedConfig>)>;
211
212/// `$disableMenuFor(node)`.
213pub type DisableMenuFor = Rc<dyn Fn(&NodeRef) -> bool>;
214
215/// `registerAutoEmbed`'s arguments: `LexicalAutoEmbedPlugin`'s props
216/// besides the view's.
217pub struct AutoEmbedConfig {
218    /// `embedConfigs`: when several match a URL, the last wins.
219    pub embed_configs: Vec<Rc<dyn EmbedConfig>>,
220    /// `getMenuOptions(activeEmbedConfig, embedFn, dismissFn)`: the menu's
221    /// options for a match; `embedFn` replaces the link with the embed,
222    /// `dismissFn` closes the menu.
223    pub get_menu_options: GetMenuOptions,
224    /// `onOpenEmbedModalForConfig`: handles `INSERT_EMBED_COMMAND` for a
225    /// config's type.
226    pub on_open_embed_modal_for_config: Option<OpenEmbedModalForConfig>,
227    /// `$disableMenuFor`: no menu for a link where it returns true.
228    pub disable_menu_for: Option<DisableMenuFor>,
229    /// `menuCommandPriority`: the priority of the menu's keyboard commands
230    /// (`COMMAND_PRIORITY_LOW` in JS's default).
231    pub menu_command_priority: i8,
232}
233
234/// `EmbedMatch`.
235#[derive(Clone)]
236struct EmbedMatch {
237    embed_config: Rc<dyn EmbedConfig>,
238    key: NodeKey,
239    result: EmbedMatchResult,
240    url: String,
241}
242
243/// The plugin's state: its config, the current match, and the menu.
244struct AutoEmbedState {
245    editor: Editor,
246    config: AutoEmbedConfig,
247    menu: NodeMenu<AutoEmbedOption>,
248    embed_match: RefCell<Option<EmbedMatch>>,
249    is_single_token_paste: Cell<bool>,
250    latest_check: Cell<u64>,
251}
252
253/// `$getCurrentLink(key, url)`: the link `key`, while it is attached and
254/// its URL is still `url`.
255fn get_current_link(key: &str, url: &str) -> Option<NodeRef> {
256    get_node_by_key(key).filter(|link| {
257        is_link_node(link) && link.is_attached() && link.get_url().as_deref() == Some(url)
258    })
259}
260
261impl AutoEmbedState {
262    /// `$isMenuDisabledForNode(linkNode, $disableMenuFor)`.
263    fn is_menu_disabled_for_node(&self, link: &NodeRef) -> bool {
264        self.config
265            .disable_menu_for
266            .as_ref()
267            .is_some_and(|f| f(link))
268    }
269
270    /// `reset()`: `setEmbedMatch(null)`.
271    fn reset(self: &Rc<Self>) {
272        if self.embed_match.borrow_mut().take().is_some() {
273            self.render();
274        }
275    }
276
277    /// What the component renders for the match: a node menu at its link
278    /// with `getMenuOptions`' options, or nothing.
279    fn render(self: &Rc<Self>) {
280        let embed_match = self.embed_match.borrow().clone();
281        match embed_match {
282            None => {
283                self.menu.set_node_key(None);
284                self.menu.menu().set_options(Vec::new());
285            }
286            Some(embed_match) => {
287                let (embed, dismiss) = (Rc::downgrade(self), Rc::downgrade(self));
288                let options = (self.config.get_menu_options)(
289                    &embed_match.embed_config,
290                    Rc::new(move || {
291                        if let Some(state) = embed.upgrade() {
292                            state.embed_link_via_active_embed_config();
293                        }
294                    }),
295                    Rc::new(move || {
296                        if let Some(state) = dismiss.upgrade() {
297                            state.reset();
298                        }
299                    }),
300                );
301                self.menu.set_node_key(Some(embed_match.key));
302                self.menu.menu().set_options(options);
303            }
304        }
305    }
306
307    /// `checkIfLinkNodeIsEmbeddable(key)`.
308    fn check_if_link_node_is_embeddable(self: &Rc<Self>, key: &str) {
309        let check = self.latest_check.get() + 1;
310        self.latest_check.set(check);
311        let url = self.editor.get_editor_state().read(|| {
312            let link = get_node_by_key(key).filter(is_link_node)?;
313            if self.is_menu_disabled_for_node(&link) {
314                return None;
315            }
316            link.get_url()
317        });
318        let Some(url) = url else { return };
319        // The last config that matches wins, so they are tried from the end.
320        self.try_embed_config(self.config.embed_configs.len(), check, key.to_owned(), url);
321    }
322
323    /// The loop of `checkIfLinkNodeIsEmbeddable` from the config before
324    /// `index`, each `parseUrl` awaited before the next.
325    fn try_embed_config(self: &Rc<Self>, index: usize, check: u64, key: NodeKey, url: String) {
326        let Some(index) = index.checked_sub(1) else {
327            return;
328        };
329        let embed_config = self.config.embed_configs[index].clone();
330        let state = Rc::downgrade(self);
331        let (parsed_config, parsed_url) = (embed_config.clone(), url.clone());
332        embed_config.parse_url_async(
333            &url,
334            ParseUrlDone(Some(Box::new(move |result| {
335                let Some(state) = state.upgrade() else { return };
336                if check != state.latest_check.get() {
337                    return;
338                }
339                let Some(result) = result else {
340                    state.try_embed_config(index, check, key, parsed_url);
341                    return;
342                };
343                // Edits made while parseUrl was pending may not be committed
344                // yet, and the link may have moved into a disabled location.
345                let embeddable = state
346                    .editor
347                    .read_with_mode(EditorReadMode::Pending, || {
348                        get_current_link(&key, &parsed_url)
349                            .is_some_and(|link| !state.is_menu_disabled_for_node(&link))
350                    })
351                    .unwrap_or(false);
352                if embeddable {
353                    *state.embed_match.borrow_mut() = Some(EmbedMatch {
354                        embed_config: parsed_config,
355                        key,
356                        result,
357                        url: parsed_url,
358                    });
359                    state.render();
360                }
361            }))),
362        );
363    }
364
365    /// `embedLinkViaActiveEmbedConfig()`: in an update, the config inserts
366    /// its node, then the link is removed (unless it was removed or its URL
367    /// changed meanwhile).
368    fn embed_link_via_active_embed_config(&self) {
369        let Some(EmbedMatch {
370            embed_config,
371            key,
372            result,
373            url,
374        }) = self.embed_match.borrow().clone()
375        else {
376            return;
377        };
378        let editor = self.editor.clone();
379        let outcome = self.editor.update(
380            move || {
381                let Some(link) = get_current_link(&key, &url) else {
382                    return Ok(());
383                };
384                if get_selection().is_none() {
385                    link.select_end()?;
386                }
387                embed_config.insert_node(&editor, &result)?;
388                if link.is_attached() {
389                    link.remove(false)?;
390                }
391                Ok(())
392            },
393            UpdateOptions::default(),
394        );
395        // JS's `editor.update` reports an error to `onError`, which throws.
396        let _ = outcome;
397    }
398}
399
400/// `LexicalAutoEmbedPlugin`'s logic: watches the links (`LinkNode`,
401/// `AutoLinkNode`) that a paste of one token creates, and when one of
402/// `embed_configs` parses the URL, opens the returned menu at the link with
403/// `get_menu_options`' options; choosing one runs its `on_select` with the
404/// link. The match is cleared when the link changes again or the menu
405/// closes. `on_open_embed_modal_for_config` handles `INSERT_EMBED_COMMAND`.
406/// Returns the menu and what unregisters it; fails when the editor doesn't
407/// register the link nodes.
408pub fn register_auto_embed(
409    editor: &Editor,
410    config: AutoEmbedConfig,
411) -> Result<(NodeMenu<AutoEmbedOption>, Unregister), LexicalError> {
412    let on_select_option: MenuSelectOption<AutoEmbedOption> =
413        Rc::new(|option, target_node, close_menu, _| {
414            (option.on_select)(target_node)?;
415            close_menu();
416            Ok(())
417        });
418    let menu_command_priority = config.menu_command_priority;
419    let state = Rc::new(AutoEmbedState {
420        editor: editor.clone(),
421        config,
422        menu: NodeMenu::new(editor, on_select_option, menu_command_priority),
423        embed_match: RefCell::new(None),
424        is_single_token_paste: Cell::new(false),
425        latest_check: Cell::new(0),
426    });
427    // `onClose={reset}`.
428    let closing = Rc::downgrade(&state);
429    *state.menu.menu().callbacks().on_close.borrow_mut() = Some(Rc::new(move || {
430        if let Some(state) = closing.upgrade() {
431            state.reset();
432        }
433    }));
434    let pasting = Rc::downgrade(&state);
435    let mut unregisters = vec![editor.register_command(
436        &PASTE_COMMAND,
437        move |payload, _| {
438            let Some(state) = pasting.upgrade() else {
439                return Ok(false);
440            };
441            let is_single_token_paste = match payload {
442                PasteCommandType::Clipboard(event) => event
443                    .clipboard_data
444                    .as_ref()
445                    .is_some_and(|data| is_single_token(&data.get_data("text/plain"))),
446                PasteCommandType::Input(_) | PasteCommandType::Keyboard(_) => false,
447            };
448            state.is_single_token_paste.set(is_single_token_paste);
449            if is_single_token_paste {
450                let state = Rc::downgrade(&state);
451                on_update(move || {
452                    if let Some(state) = state.upgrade() {
453                        state.is_single_token_paste.set(false);
454                    }
455                });
456            }
457            Ok(false)
458        },
459        COMMAND_PRIORITY_BEFORE_EDITOR,
460    )];
461    for node_type in ["link", "autolink"] {
462        let listening = Rc::downgrade(&state);
463        unregisters.push(editor.register_mutation_listener(
464            node_type,
465            move |mutations, payload| {
466                let Some(state) = listening.upgrade() else {
467                    return;
468                };
469                for (key, mutation) in mutations {
470                    let node_key = state.embed_match.borrow().as_ref().map(|m| m.key.clone());
471                    if *mutation == NodeMutation::Created
472                        && payload.update_tags.iter().any(|t| t == PASTE_TAG)
473                        && state.is_single_token_paste.get()
474                    {
475                        state.check_if_link_node_is_embeddable(key);
476                    } else if node_key.as_ref() == Some(key) {
477                        state.reset();
478                    }
479                }
480            },
481            MutationListenerOptions {
482                skip_initialization: true,
483            },
484        )?);
485    }
486    if state.config.on_open_embed_modal_for_config.is_some() {
487        let opening = Rc::downgrade(&state);
488        unregisters.push(editor.register_command(
489            &INSERT_EMBED_COMMAND,
490            move |embed_config_type, _| {
491                let Some(state) = opening.upgrade() else {
492                    return Ok(false);
493                };
494                let Some(embed_config) = state
495                    .config
496                    .embed_configs
497                    .iter()
498                    .find(|c| c.embed_type() == embed_config_type)
499                else {
500                    return Ok(false);
501                };
502                if let Some(open) = &state.config.on_open_embed_modal_for_config {
503                    open(embed_config);
504                }
505                Ok(true)
506            },
507            COMMAND_PRIORITY_EDITOR,
508        ));
509    }
510    let menu = state.menu.clone();
511    let unregister = merge_register(unregisters);
512    Ok((
513        menu,
514        Box::new(move || {
515            unregister();
516            state.reset();
517        }),
518    ))
519}