OpenMax
Free Trial

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, or undefined when there is nothing this time. Keys whose value is undefined are not sent.
  • sendKeys lists in advance the keys contributeSend returns. contributeSend without sendKeys is 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.
  • contributeSend without sendKeys, or a key in sendKeys that 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.