Prompts: a trigger character in the editor opens a menu of results, for example @ for people. A result inserts a mention, text (an emoji, a snippet) or a node of the app. See the Prompts guide.

A prompt list has one of two forms:

# The first prompt has the trigger "@", the second has "#".
[people: &MyApp.People.search/1, work: &MyApp.Work.search/1]

# Each trigger given explicitly.
[{"@", :people, &MyApp.People.search/1}, {"#", :work, &MyApp.Work.search/1}]

A trigger is exactly one character that is not white space. The name of a prompt (an atom or a string) is the kind of the mentions that it inserts.

A prompt

A prompt is a search callback, a callback with options, or a keyword list with the callback (:search) or a list of items (:items):

people: &MyApp.People.search/1
people: {&MyApp.People.search/1, label: "People in the workshop"}
people: [search: &MyApp.People.search/1, spaces: true, min_length: 2]
emoji: [items: MyApp.Emoji.items(), insert: :text]

The options:

• :label - the accessible name of the menu, "<name> suggestions" otherwise. A non-empty string of at most 200 characters.
• :spaces - true to let the query have spaces ("Ada Lovelace"). A query ends at two spaces in a row, and cannot start with a space. The default is false: a space closes the menu.
• :min_length - the characters of the query before the first search (0 to the :max_length, default 0). A shorter query shows "Keep typing".
• :max_length - the longest query, 1 to 200 characters (default 64). A longer one closes the menu.
• :insert - what a result inserts: :mention (the default), :text (the item's :text, or its label), or {:node, type}: a node of the editor of that Lexical type, from the item's :attrs.
• :async - true to run the search in a task of the LiveView, so that a slow search does not block it. The LiveView then needs a handle_async/3 clause, see Kotoba.Live.handle_prompt_async/3. The callback of an async prompt takes only the query (arity 1).

Searches

A :search callback gets the query (the text after the trigger) and returns a list of items. A callback with arity 2 also gets the socket, for example to scope the search to the current user:

[people: fn query, socket -> MyApp.People.search(socket.assigns.scope, query) end]

A callback that raises, exits or throws, or that returns anything but a list, fails: search/3 logs a warning with the prompt name, and the editor says "Results did not load". A callback runs in the LiveView process, so a slow one blocks the LiveView while it runs (see :async).

Items

With :items, the editor has the items (at most 500) and filters them as the person types, with no request to the server: each word of the query must start a word of the label or the hint, with no regard to case or accents.

An item is a map with an :id (a string or an integer), a :label (a string) and these optional keys, with atom or string keys, or an {id, label} tuple:

• :hint - a string shown next to the label;
• :text - the text that an insert: :text prompt inserts (the label when there is none);
• :attrs - the attributes of the node that an insert: {:node, type} prompt inserts: a map that encodes to JSON in at most 2048 bytes.

Items that do not have this shape are dropped, and at most 50 results go to the menu. Control characters (such as a tab or a line break) are removed from the id, the label, the hint and the text.

The component Kotoba.Components.kotoba/1 sends the triggers, the names, the options and the items to the editor; the search callbacks stay in the LiveView. Kotoba.Live.handle_prompt/3 runs them.