Chat

Its own entry, the editor’s peers

Every message is drawn by the same read-only MarkdownEditor that wrote it, and the composer is a MarkdownEditor too — so the entry needs exactly the optional peers of /editor. An app that already has the editor installs nothing; one that does not installs the Tiptap set, all at one version:

pnpm add @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/markdown \
  @tiptap/extensions @tiptap/extension-list @tiptap/extension-table @tiptap/extension-image \
  @tiptap/extension-mention @tiptap/suggestion @tiptap/extension-paragraph \
  @tiptap/extension-code-block-lowlight lowlight highlight.js

• Why not the main entry. Putting these parts behind @comitor/ui would make every Comitor app install Tiptap. Folding them into /editor would cost no bytes — the package is not bundled — but would mix an input with a whole screen.
• One renderer, not two. A mention written as [@Priya Raman](mention:u1), a table, a checklist, a code block: a message shows them exactly as a task description does, because it is the same schema. A second Markdown renderer for reading is a second place to drift — a mention printed as a raw link, say.
• The editor bundle comes with it — about 234 KB gzipped, the figure on the Markdown Editor page. An assistant panel that opens on demand can load with next/dynamic.

Five parts

Each part draws one thing and holds no conversation state. ChatSteps and ChatSources slot into a ChatMessage; the messages go inside a ChatThread; the composer sits under the thread.

An assistant in Comitor Tasks

Press Enter to send the question already in the box. The agent’s three steps run one after another, the answer arrives two words at a time — a table, a numbered list, two mentions — and the steps fold away once they are all done. Its sources come last: the tasks link inside the app, the OWASP page opens a new tab, and the calendar has no link at all. Press Stop halfway and the timer really stops; the running step turns into a failure that says why. Ask again and a second script answers with a checklist and a code block.

One state at a time

A system line; a person’s reply that the assistant drafted for them, labelled with aiGenerated; an answer whose second step failed — the list stays open, and the failure is written out, not only coloured — with meta and actions under it; and an agent’s answer the app draws itself, with ChatCitation chips in the sentence. Hover or focus a chip for its card. The second chip has no href of its own, so it jumps to its entry in the list below. A ChatMessage needs no thread around it.

The AI-generated label

Every assistant message carries it by default — Comitor’s requirement FR-AI-018 is that text written by a model says so where it is read. It is a small sparkle chip next to the name, with “Generated by AI. Check important details before relying on them.” as its tooltip and as a visually hidden description, so a screen reader hears the warning too.

• On a person’s message, opt in. When the assistant drafts a reply that someone then sends as their own, set aiGenerated on that message — the label follows the text, not the sender.
• Turning it off on an assistant message is aiGenerated={false}. Do that only where the text is not the model’s — a canned notice the app wrote, for instance.
• The wording is the aiGenerated and aiGeneratedHint keys, overridable like every other string.

Following the newest text

The thread watches the size of its column of messages, not its children — streaming text grows a message without adding one, and an image that finishes loading grows it without React knowing. If the reader is within 48px of the end, it scrolls along. If they have scrolled up to reread, it leaves them there and shows a round ↓ button that takes them back and resumes following. Press the button below, then scroll up while the answer streams.

The thread opens at its last message. The scroll area is a tab stop of its own, so a keyboard-only reader can scroll the history with the arrow keys — Chrome makes scrollable regions focusable by itself, Safari does not.

Enter to send

ChatComposer turns on submitOnEnter, a prop that both editors gained in 3.12.0: bare Enter calls onSubmit, Shift+Enter breaks the line. An Enter that sends is easy to get wrong in three places, and each one is handled:

The upload guard is the composer’s, not the prop’s. On a bare MarkdownEditor or RichTextEditor with submitOnEnter, Enter calls onSubmit even while an image uploads — check isUploading() there yourself, as the comment box on the Markdown Editor page does. Without an onSubmit the prop does nothing.

// ChatComposer turns it on for you. Any MarkdownEditor or RichTextEditor can take it too:
const ref = useRef<MarkdownEditorHandle>(null)

<MarkdownEditor
  ref={ref}
  value={draft}
  onChange={setDraft}
  submitOnEnter                 // bare Enter calls onSubmit; Shift+Enter breaks the line
  onSubmit={() => {
    // The editor yields to an open @ or / menu and to an IME composition — but NOT to an upload.
    // ChatComposer checks that itself; a bare editor has to:
    if (!draft.trim() || ref.current?.isUploading()) return
    send(draft)
    ref.current?.clear()
  }}
  mentions={{ items: members }}
/>

Language

The strings live in the chat namespace and follow the nearest ComitorLocaleProvider — English by default, Vietnamese built in (set the language once, at the root). The demo starts in Vietnamese: the label, “Thinking…”, the step summary and statuses, the source count, the placeholder and the name of the Stop button are the provider’s. The messages are the app’s, translated by the app. Switch languages, then press Stop.

• labels on each part is Partial<ChatLabels>, merged key by key: the prop wins, then the nearest provider, then English.
• Three keys are functions — stepsSummary, sources and citation — because a number sits in the middle of the sentence and plurals differ by language. Functions cannot cross from a Server Component into a client one, so a table that overrides them is declared in a client component.
• The provider picks strings; it does not set lang. Keep <html lang> in step with it, as the demo does for its own region.

Read live from comitorMessagesEn.chat and comitorMessagesVi.chat, the function keys called with the arguments shown.

Props

The data types — ChatRole, ChatStepItem, ChatStepStatus, ChatSource and ChatLabels — are exported from the same entry, as types only.

ChatThread

ChatMessage

ChatSteps

ChatSources

ChatCitation

ChatComposer

Known limitations

• Enter never continues a list. In the composer, Enter sends from anywhere outside an open menu — inside a list item too. Shift+Enter is a line break within the same item, so a second bullet has to be typed as a new line starting - .
• A source without an href is a citation target, not a link. Its card is a plain box, and a ChatCitation for it jumps to #chat-source- plus its id. That id is written once per ChatSources, so the same source listed under two answers on one page gives two elements the same id — the chip lands on the first. Give sources ids that are unique on the page.
• system content is plain text. It is not passed through the editor, so Markdown in it is printed as typed.
• A person’s message shows no name or avatar. The bubble is meant for the one person typing; author only names it for a screen reader. A conversation shared among several people is the Chat pattern’s job.
• A few hundred messages. Each one is a read-only editor; a longer history should be paged by the app.

Accessibility

• The thread is a role="log" named “Conversation”, so a screen reader announces what is added to it. While busy it carries aria-busy, and so does the streaming message itself: the reader waits for the finished answer instead of hearing each chunk.
• The scroll area takes focus (tabIndex 0, with the package’s outline on focus-visible), so the history scrolls from the keyboard. The ↓ button that appears after scrolling up is named “Scroll to latest message”.
• Each message is an <article> labelled by its speaker’s name — visible for the assistant, visually hidden for a person. The AI label’s explanation is a visually hidden description, not only a tooltip.
• Every step carries its status in words after its label — “— In progress”, “— Failed” — so the spinner, the tick and the cross are never the only signal. The summary line is a real button that opens and closes the list.
• A source with an href is a real <a href>: it opens with the keyboard, copies and middle-clicks like any link. An external one opens a new tab and says “(opens in a new tab)” to a screen reader. A citation chip is named “Source 2: Decision log”, not “2”, and its hover card also opens on focus.
• The composer is a MarkdownEditor named “Message”, with the editor’s keyboard menus for @ and /. Send and Stop are icon buttons with names. A disabled composer keeps a readable border — it changes background, never opacity.

Related