# Inbox

> A complete inbox with a conversation list, chat thread and contact panel, or each part on its own.

Build an inbox from [ConversationList](https://docs.polymorfa.com/ui-kit/components/conversation-list),
[MessageList](https://docs.polymorfa.com/ui-kit/components/message-list), [ComposeBox](https://docs.polymorfa.com/ui-kit/components/compose-box)
and [ContactPanel](https://docs.polymorfa.com/ui-kit/components/contact-panel). Choose a component above to
edit its props. The preview keeps the same sample conversation and attachment data
while you change code frameworks.

Attachments in this demo use local Blob URLs. Your app supplies an upload adapter
when creating its composer controller. See [chat controllers](https://docs.polymorfa.com/ui-kit/chat#controllers).

For a preassembled layout, use [Inbox](https://docs.polymorfa.com/ui-kit/components/inbox). The installed
release exposes its composer settings but does not accept a custom upload adapter
through `Inbox`. Use the composed layout above when you need attachment uploads.

**React**

```tsx
"use client";
import { Inbox, PolymorfaProvider } from "@polymorfa/react";

<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
  <div style={{ height: 640 }}>
    <Inbox title="Support" />
  </div>
</PolymorfaProvider>;
```

**Web Components**

```ts
import { definePolymorfa } from "@polymorfa/elements";

definePolymorfa({ tokenEndpoint: "/api/polymorfa/token" });
```

```html
<pmfa-inbox style="height: 640px"></pmfa-inbox>
```

## Data and permissions

By default the inbox reads conversations and messages from your route's
`history` routes, follows live updates from its `events` route, and sends
with the client token. To read from somewhere else, pass any `InboxDataSource`
as `source`. A data source lists conversations, returns a message source for
each conversation, and can optionally load contacts and publish changes.

Controls follow the grant your route returns:

| Control | Permission |
| --- | --- |
| Conversation list and messages | `read_messages` |
| Live updates | `subscribe_events` |
| Composer | `send_message` |
| Contact panel | `read_contact` |
| Call button in the thread header | `voip_place` |

Without `read_messages`, the inbox shows its empty state. Without
`send_message`, the thread is read-only and says so. Each hidden control logs
one warning in development builds, for example
`<Inbox/>: composer hidden; the token lacks "send_message". Add it to allow in mint().`
Production builds log nothing.

`<pmfa-inbox>` with a custom `source` and no client renders every control and
leaves enforcement to your source.

## Compose the inbox

Combine [ConversationList](https://docs.polymorfa.com/ui-kit/components/conversation-list), [MessageList](https://docs.polymorfa.com/ui-kit/components/message-list), [ComposeBox](https://docs.polymorfa.com/ui-kit/components/compose-box) and [ContactPanel](https://docs.polymorfa.com/ui-kit/components/contact-panel) when you need independent control of each piece. A shared conversation controller keeps the list and composer in sync. Supply the composer’s upload adapter to handle attachments.

## Inbox props

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

On narrow screens the inbox shows the list or the thread, with a Back button
to return to the list.

## ConversationList

The inbox's list, usable on its own with an `InboxController`.

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

## ConversationListView

A controlled list for apps that load and change conversations themselves.
Pass the rows and selection directly.

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

Row actions are `pin`, `unpin`, `archive`, `unarchive`, `mark-read` and
`mark-unread`. Supply both `actions` and `onAction` to show them. A failed
action shows an error and keeps the row's previous state. There is no built-in
action transport.

The list has All, Unread, Drafts and Archived filters, sorts pinned rows first,
and supports keyboard navigation with the arrow keys, Home and End.

## ContactPanel

All 7 `ContactPanel` props, with types, defaults and a live preview, are on the [ContactPanel](https://docs.polymorfa.com/ui-kit/components/contact-panel) page.

The contact panel is React only. `<pmfa-inbox>` has the list and the thread.

## pmfa-inbox

| Property | Type | Description |
| --- | --- | --- |
| `client` | `PolymorfaClient` | Defaults to the client from `definePolymorfa()`. |
| `source` | `InboxDataSource` | Replaces the default route-backed source. |
| `controller` | `InboxController` | Drives the inbox from outside. |
| `configuration` | `{ appearance?, locale?, stylesheet? }` | Appearance, text and extra CSS for this element. |

| Event | `detail` | When |
| --- | --- | --- |
| `pmfa-select` | The conversation | A conversation row is selected. |
| `pmfa-render` | | The element finishes rendering. |

## Accessibility

- Conversation rows are buttons. The open row is marked with `aria-current`.
  Arrow keys, Home and End move between rows.
- Unread counts have a text label, such as "3 unread", not color alone.
- The contact panel toggle is labelled "Show contact details" or "Hide contact
  details".
- The composer and message list follow the [chat accessibility
  behavior](https://docs.polymorfa.com/ui-kit/chat#accessibility).

## Related

- [Installation and setup](https://docs.polymorfa.com/ui-kit/setup)
- [Chat](https://docs.polymorfa.com/ui-kit/chat)
- [Calls](https://docs.polymorfa.com/ui-kit/calls)
