Composer plugins
The four things a composer plugin can do: triggers and candidate panels, toolbar buttons, content nodes and structured send data, plus the host capabilities it needs.
Composer plugins
A composer plugin is an object defined with defineComposerPlugin, of type ComposerPlugin; both are exported from @openmaxai/chat/composer. Every field except id is optional: a plugin takes part in whatever its fields declare. One plugin can do several things; @ mentions, for example, do all four.
| Ability | Field | What it does | mention |
work-reference |
|---|---|---|---|---|
| Trigger and candidate panel | trigger |
Opens candidates after a character is typed and replaces the typed text with the pick | @ |
# |
| Toolbar button | toolbar |
Puts a button on the toolbar or in the + menu |
Yes | Yes |
| Content nodes | nodes |
Inserts a block of content into the composer, such as a mention chip or a work-item chip | mention |
work_reference |
| Structured send data | sendKeys + contributeSend |
Sends structured data alongside the text | mentions |
— |
Each plugin also declares in requiredPorts which host capabilities it needs. id is the plugin's name: it must be unique within a plugin set, and error messages use it to say which plugin is at fault.
Trigger and candidate panel
trigger makes a plugin respond to a trigger character: when the user types it at the start of a line or after whitespace, the SDK hands it and the text typed after it (up to the next whitespace) to the plugin to look up candidates, and opens the plugin's panel next to the caret.
| Field | Description |
|---|---|
chars |
The trigger characters, exactly one character each. Put the full-width form of the same trigger in the same array, as in ["@", "@"] |
search(query, ctx) |
query is the text typed after the trigger. Returns the candidates, synchronously or as a Promise; an empty array opens no panel. ctx has conversationId, readOnly and the host as host |
insert(view, range, candidate) |
Called when a candidate is picked: replaces the trigger and the typed text (range) in one go. view is ProseMirror's EditorView |
Panel |
The candidate panel component; may be React.lazy(...) |
keepPanelOpenWhenEmpty |
Optional. Opens the panel even when search returns an empty array, and lets the panel fill itself. @ uses it to find people outside the conversation in the organization directory |
listbox |
Optional. Declares that Panel renders a role="listbox" with the listboxId it receives and one role="option" per candidate with optionId(index) and aria-selected. The composer then gets aria-controls and aria-activedescendant pointing at the highlighted option while the panel is open, so screen readers follow ArrowUp / ArrowDown. Section titles and status lines must not carry those ids |
Each candidate needs an id that is unique within one result; the other fields are for your panel and insert to interpret.
Props the panel receives:
| Prop | Description |
|---|---|
candidates |
The candidates to show. The rows the panel renders must match it one to one: ArrowUp / ArrowDown and Enter work by index |
query |
The same value that was passed to search |
activeIndex, onActiveIndexChange |
The highlighted row; call the latter on hover |
onSelect |
Call with the row's index when a row is clicked |
host |
The host; read only the capabilities listed in requiredPorts |
setCandidates |
When the panel adds or removes rows (expanding a group, say), pass back the new full list; the highlight follows the id |
registerKeyHandler |
Optional. Register to handle ArrowLeft / ArrowRight; return true when handled. Pass null on unmount |
listboxId, optionId |
Given only when the trigger declares listbox: the id for the listbox element and, for row index, the id for its option element |
ArrowUp, ArrowDown, Enter and Escape are handled by the SDK, and focus stays in the composer. Two plugins declaring the same trigger character throw when the plugin set is assembled; the SDK does not pick one for you.
Toolbar button
toolbar is a list of buttons, laid out on the toolbar in plugin order and, within a plugin, in declaration order. Each button:
| Field | Description |
|---|---|
id |
Button id, unique within a plugin set; also the key used when placing the button |
icon |
Icon component, receives className; may be React.lazy(...) |
titleKey |
Translation key of the tooltip, translated by the host's i18n capability |
menuLabelKey, menuLabel |
Optional. The row text when the button sits in the + menu: menuLabel is ready-made text, menuLabelKey a translation key; without either, titleKey is used |
defaultPlacement |
Optional. "bar" (shown on the toolbar, the default) or "plus-menu" (moved into the + menu) |
disabled |
Optional. When true, still shown in the menu but greyed out |
onActivate(ctx) |
What a click does. ctx.insertText(text) inserts text at the caret; inserting a trigger opens its candidate panel. A button that types a trigger should call ctx.activateTrigger(char) instead: when the caret already sits right after that trigger with nothing typed, it only reopens the candidate panel rather than inserting a second one |
Panel |
Optional. The button's own panel, opened and closed by a click, receives close; may be React.lazy(...). To use host capabilities, the panel calls useChatHost() |
Give at least one of onActivate and Panel; with both, onActivate runs and then the panel opens.
Where a button ends up: a position set for its id in ChatProvider's toolbarPlacement wins, then the plugin's defaultPlacement, then "bar".
When the composer is expanded, buttons on the toolbar move to the bottom bar of the expanded editor, and buttons in the + menu stay there. The buttons, onActivate and Panel are unchanged; a plugin needs nothing extra for the expanded editor. Planned
Content nodes
nodes adds node types to the composer's document, keyed by node name. Each value is a ProseMirror node spec with two extra fields:
| Field | Description |
|---|---|
toText |
What the content turns into as plain text. Used for the sent text and for text copied to the clipboard |
chip |
When true, the content is one unit: the caret skips over it and one backspace deletes it |
Drafts are saved as HTML; a node gets in and out of them through parseDOM / toDOM in its spec. Nodes are inserted by the plugin's own insert or by a button.
A node name must not repeat one of the composer's own nodes (doc, paragraph, text, hard_break) or another plugin's; a repeat throws when the plugin set is assembled.
Structured send data
To send structured data alongside the text, a plugin declares both sendKeys and contributeSend:
contributeSend(doc)reads the composer content at send time and returns an object keyed by field name, orundefinedwhen there is nothing this time. Keys whose value isundefinedare not sent.sendKeyslists in advance the keyscontributeSendreturns.contributeSendwithoutsendKeysis an error, and returning a key that is not listed throws at send time.
The keys become fields of the send request (SendMessageInput) passed to the host's messaging.sendMessage. Which keys can be sent is set by the SDK's forwarding list, which holds mentions; any other key in sendKeys throws when the plugin set is assembled. Two plugins returning the same key throw at send time.
Letting a plugin send fields of its own is not designed yet. Planned
Required capabilities
requiredPorts lists the host capabilities the plugin needs, by ChatHost field name, for example ["workItems"]. A plugin should only read the capabilities listed there, whether through ctx.host in search, the candidate panel's host, or useChatHost() in a button panel.
If the host lacks any of them, ChatProvider does not install the plugin and everything else works as usual.
The capabilities the built-in plugins need are in Built-in plugins.
Declarations are ready values
nodes, trigger, toolbar, sendKeys and requiredPorts must be ready values when the plugin is defined, not functions or Promises; this is checked when the plugin set is assembled, so what a plugin needs and whether it clashes with another is known at startup. Only components may load lazily: trigger.Panel, and a button's icon and Panel.
What throws at assembly
The plugins of one set are checked together when they are assembled. Any of the following throws, and the message names the plugin and the item:
- Two plugins with the same
id. - Two plugins declaring the same node name, or a node name that repeats one of the composer's own nodes.
- Two plugins declaring the same trigger character.
- Two toolbar buttons with the same
id. contributeSendwithoutsendKeys, or a key insendKeysthat the SDK does not pass on.- A declaration field listed above that is a function or a Promise, an empty
chars, or an entry in it that is not exactly one character.
To write your own, see Write a composer plugin.
