# Chat

> Show one conversation with a message list, composer, inline chat window or chat drawer.

The chat components show one conversation. Use them when you already have a
screen for choosing conversations; use [`<Inbox/>`](https://docs.polymorfa.com/ui-kit/inbox) for the
complete list-and-thread layout.

| React | Web Component | Renders |
| --- | --- | --- |
| `MessageList` | `pmfa-message-list` | The message log: bubbles, attachments, reply quotes, date separators and delivery status. |
| `ComposeBox` | `pmfa-compose-box` | The composer: text field, emoji picker, attachments, voice notes and quick replies. |
| `ChatWindow` | `pmfa-chat-window` | An inline thread with a header, message list and composer. No close action. |
| `ChatDrawer` | `pmfa-chat-drawer` | The same thread in a side drawer with a title and close button. |

## Controllers

The components render state from two controllers in `@polymorfa/browser`:

- `ConversationController` loads history, follows live updates and sends
  messages optimistically. It reads from a data source with `load`, `subscribe`
  and `send` methods, which you implement against your own storage or route.
- `MessageComposerController` holds the draft text, attachments and reply
  target. Create its actions with `createConversationComposerActions()`,
  passing the conversation and your upload function, so the list and composer
  share one history. The upload function is yours: it turns the picked file
  into a hosted attachment and reports progress.

```tsx
import {
  ConversationController,
  MessageComposerController,
  createConversationComposerActions,
} from "@polymorfa/browser";
import { ChatWindow, PolymorfaProvider } from "@polymorfa/react";

const conversation = new ConversationController(source);
const composer = new MessageComposerController(
  createConversationComposerActions(conversation, uploadFile),
);
await conversation.load();

<PolymorfaProvider>
  <ChatWindow
    controller={conversation}
    composerController={composer}
    header={<h2>Customer support</h2>}
  />
</PolymorfaProvider>;
```

Create controllers once per conversation, outside render, and dispose them when
the conversation is removed. Each component also accepts a `createController`
factory; controllers it creates are disposed with the component. Controllers
you pass in are never disposed for you.

A failed send keeps its text, attachments and reply target, and the message
shows Retry. Resubmitting an unchanged draft reuses the same client operation
ID, so your send route can treat it as idempotent.

## MessageList

```tsx
<MessageList controller={conversation} onReply={(message) => setReplyTo(message)} />
```

All 8 `MessageList` props, with types, defaults and a live preview, are on the [MessageList](https://docs.polymorfa.com/ui-kit/components/message-list) page.

Consecutive messages from the same side are grouped. "Today", "Yesterday" or a
localized date separates days. Outbound messages show a pending, sent or failed
icon, and a failed message offers Retry. Images render as lazy thumbnails;
other files render as a card with the name, size and a link. Only `https:`,
`http:` and `blob:` URLs become links or images. Selecting a reply quote
scrolls to and focuses the quoted message.

## ComposeBox

```tsx
<ComposeBox
  controller={composer}
  placeholder="Reply to Casey"
  quickReplies={[{ id: "thanks", shortcut: "thanks", text: "Thanks for reaching out!" }]}
/>
```

All 20 `ComposeBox` props, with types, defaults and a live preview, are on the [ComposeBox](https://docs.polymorfa.com/ui-kit/components/compose-box) page.

The toolbar reads, in order: `startActions`, the emoji button, the attach
button, the message field, `endActions`, then the microphone or the send
button. Send replaces the microphone once there is text or an uploaded
attachment. Files can be attached with the button, by pasting or by dropping
them on the composer. Pending files show upload progress, a failed state and a
remove button. A rejected file, such as one over the size limit, shows as the
composer error.

Voice notes record as `audio/webm`, `audio/ogg` or `audio/mp4`, depending on
the browser. While recording, a bar shows the elapsed time, the input level, a
delete button and a send button. The microphone is released when recording ends
or the composer unmounts.

The emoji set is built in and needs no network. Recent emoji are kept in
`localStorage` when it is available.

## ChatWindow

All 13 `ChatWindow` props, with types, defaults and a live preview, are on the [ChatWindow](https://docs.polymorfa.com/ui-kit/components/chat-window) page.

## ChatDrawer

```tsx
<ChatDrawer
  open={open}
  onClose={() => setOpen(false)}
  conversation={conversation}
  composerController={composer}
  title="Casey Rivera"
/>
```

All 17 `ChatDrawer` props, with types, defaults and a live preview, are on the [ChatDrawer](https://docs.polymorfa.com/ui-kit/components/chat-drawer) page.

## Web Components

Register the elements with `definePolymorfaElements()` or `defineChatElements()`,
then assign controllers as properties:

```ts
import {
  ConversationController,
  MessageComposerController,
  createConversationComposerActions,
} from "@polymorfa/browser";
import { defineChatElements } from "@polymorfa/elements";

defineChatElements();

const conversation = new ConversationController(source);
const composer = new MessageComposerController(
  createConversationComposerActions(conversation, uploadFile),
);
const drawer = document.querySelector("pmfa-chat-drawer");
drawer.controller = conversation;
drawer.composerController = composer;
drawer.addEventListener("pmfa-close", () => drawer.remove());
```

```html
<pmfa-chat-drawer heading="Casey Rivera" replyable></pmfa-chat-drawer>

<pmfa-compose-box placeholder="Reply to Casey" voice-notes="false">
  <button slot="end-actions" type="button">Templates</button>
</pmfa-compose-box>
```

### Properties

| Property | Elements | Type | Description |
| --- | --- | --- | --- |
| `controller` | All | Controller | `ConversationController` for the list, window and drawer; `MessageComposerController` for the compose box. |
| `configuration` | All | `{ appearance?, locale?, stylesheet? }` | Appearance, text and extra CSS for this element. |
| `composerController` | `pmfa-chat-window`, `pmfa-chat-drawer` | `MessageComposerController` | Renders the built-in composer. |
| `onReply` | `pmfa-message-list`, `pmfa-chat-window`, `pmfa-chat-drawer` | `(message) => void` | Shows Reply and receives each click. |
| `messageFilter` | `pmfa-message-list`, `pmfa-chat-window`, `pmfa-chat-drawer` | `(message) => boolean` | Hides messages from view. |
| `quickReplies` | `pmfa-compose-box`, `pmfa-chat-window`, `pmfa-chat-drawer` | `QuickReplyOption[]` | Options for the `/` menu. |
| `conversation` | `pmfa-compose-box` | `ConversationController` | Resolves the reply banner. |
| `messages` | `pmfa-compose-box` | `ConversationMessage[]` | Resolves the reply banner without a controller. |
| `open` | `pmfa-chat-drawer` | `boolean` | Shows or hides the drawer. |
| `opener` | `pmfa-chat-drawer` | `HTMLElement` | Receives focus when the drawer closes. |

### Attributes

| Attribute | Elements | Default | Description |
| --- | --- | --- | --- |
| `heading` | `pmfa-chat-window`, `pmfa-chat-drawer` | | Title text. |
| `replyable` | `pmfa-message-list`, `pmfa-chat-window`, `pmfa-chat-drawer` | Off | Shows Reply on every message. |
| `autofocus` | `pmfa-chat-drawer` | Off | Moves focus into a drawer that is already open when it connects. |
| `placeholder` | Composer elements | Locale text | Field placeholder. |
| `attachments` | Composer elements | `true` | `false` hides the attach button, drop and paste. |
| `accept` | Composer elements | | File types for the single file picker. |
| `attachment-kinds` | Composer elements | | Space-separated `image`, `video`, `audio`, `document` for the named picker. |
| `multiple` | Composer elements | `true` | `false` allows one file at a time. |
| `emoji` | Composer elements | `true` | `false` hides the emoji button. |
| `voice-notes` | Composer elements | `true` | `false` hides the microphone. |
| `voice-note-auto-send` | Composer elements | `true` | `false` keeps a finished recording in the composer. |
| `max-rows` | Composer elements | `8` | Rows the field grows to before it scrolls. |

Composer elements are `pmfa-compose-box`, `pmfa-chat-window` and
`pmfa-chat-drawer`. Place your own buttons in the compose box toolbar with
`slot="start-actions"` and `slot="end-actions"`.

### Events

All events bubble and cross the shadow boundary.

| Event | Elements | `detail` | When |
| --- | --- | --- | --- |
| `pmfa-reply` | `pmfa-message-list`, `pmfa-chat-window`, `pmfa-chat-drawer` | The message | Reply is selected. |
| `pmfa-quick-reply` | Composer elements | The option | A quick reply is inserted. |
| `pmfa-close` | `pmfa-chat-drawer` | | The close button or Escape is pressed. |
| `pmfa-state-change` | All | The controller snapshot | The controller's state changes. |
| `pmfa-render` | All | | The element finishes rendering. |

Messages whose object has not changed keep their DOM nodes across updates, and
the composer keeps its text field. Focus, scroll position and the live region
stay in place while the conversation changes.

## Accessibility

- The message list is a log region. Status changes are announced politely.
- Enter sends and Shift+Enter adds a line, except while an input method is
  composing text.
- The quick reply field follows the ARIA combobox pattern: Up and Down move,
  Enter or Tab inserts, and Escape closes the list.
- In the emoji picker, arrow keys move through the grid and Escape closes it
  and returns focus to the button. On screens 600px wide or less it opens as a
  bottom sheet.
- Recording start and stop are announced. A denied microphone shows a
  localized error.
- Every composer button is at least 40px.
- The drawer is a non-modal dialog labelled by its title. When it opens, focus
  moves to the message field (or the close button). When it closes, focus
  returns to the element that had it. Escape closes it only when pressed inside
  the drawer. The chat window has no close action and does not capture Escape.

## Related

- [Inbox](https://docs.polymorfa.com/ui-kit/inbox)
- [Appearance and styling](https://docs.polymorfa.com/ui-kit/appearance)
- [Send messages](https://docs.polymorfa.com/messaging/send)
