## class: `WyMessenger`, `wy-messenger`

The Weavy Messenger component renders a full featured chat interface for private messaging, chat rooms, or AI agent conversations.

It displays a list of all conversations with possibility to pin, star and mark conversations as read.
Each conversation item displays an avatar, the participants or the room name as title, a line with the latest message.
It also indicates if the conversation is read/unread and if anyone in the conversation is typing.

The list has a search in the top and can open a modal for creating new conversations where the user can search for other people or agents to create private chats or chat rooms.

When a user clicks a conversation item, the conversation is loaded.
The conversation can show rich messages with markdown formatting including code syntax highlight.
Messages can have uploaded images, attached files and cloud files with full browser preview of 100+ formats.
Polls, video meetings, rich link embeds, tags and mentions can be used in messages.
Users can react with predefined emojis to each message.

Read receipts indicate which messages that has been sent and read.
The online presence for users is indicated both in the conversation list as well as in the conversation.

Typing indicators are shown when other users are typing in a conversation.

New messages are indicated as new when received.

For chat rooms, the name and avatar for the chat room can be edited. Members can be added or removed from the chat room.

The editor features markdown preview, including code syntax highlighting.
It has buttons for adding polls, video meetings, images, files and cloud files.
Mentions brings up a user selector.
Drafts are automatically saved for each conversation.

The Messenger can optionally be configured in *agent mode*, by defining the `agent` property, to only show conversations with a given [AI agent](https://www.weavy.com/docs/learn/integrations/agents).
In agent mode, the create conversation button instantly creates a new conversation with the agent when clicked, instead of opening a create conversation modal.

> Complement this with the [`<wy-notification-toasts>`](./wy-notification-toasts) component to also get realtime *in-app notifications* or *browser notifications* when new messages arrive.

\*\* Component layout \*\*

The layout depends on the width of its container, which has a breakpoint at `768px`.

*   In narrow layouts, the conversation list and chat will be stacked and clicking on a conversation in the list will navigate to the chat.
*   In wider layouts, the component has a side-by-side layout with the conversation list on the left hand side and the chat window on the right hand side.

The component is [block-level](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content) with pre-defined CSS styling to adapt to flex- and grid-layouts as well as traditional flow-layouts.
It's usually recommended to use a proper flex-layout for the container you are placing the component in for a smooth layout integration.

The content within the components is per default aligned to the edges of it's own *box* and designed to not be placed next to a edge or border.
It's recommended to adjust the layout with your default padding. Setting the `--wy-padding-outer` to your default padding will allow the component to still fill the are where it's placed,
but with proper padding within the scrollable area of the component.
If you want to make the component go all the way to the edges without padding or any outermost roundness instead,
set `--wy-padding-outer: 0;` and `--wy-border-radius-outer: 0;` to make the component fit nicely with the edge.

You can add additional styling using *CSS Custom Properties* and *CSS Shadow Parts* and further customization using *slots*.

**Used sub components:**

*   [`<wy-badge>`](./components/ui/wy-badge)
*   [`<wy-button>`](./components/ui/wy-button)
*   [`<wy-container>`](./components/ui/wy-container)
*   [`<wy-conversation>`](./components/wy-conversation)
*   [`<wy-conversation-header>`](./components/wy-conversation-header)
*   [`<wy-conversation-list>`](./components/wy-conversation-list)
*   [`<wy-conversation-new>`](./components/wy-conversation-new)
*   [`<wy-context-data-progress>`](./components/wy-context-data)
*   [`<wy-empty>`](./components/wy-empty)
*   [`<wy-icon>`](./components/ui/wy-icon)

### Examples

<figure class="example"><figcaption>Standard Messenger</figcaption>

A messenger placed in a container using a flex layout.

```html
<div style="display: flex; height: 100%;">
<wy-messenger></wy-messenger>
</div>
```

</figure>

<figure class="example"><figcaption>Agent Messenger</figcaption>

Messenger in *agent mode* only using the built-in "assistant" agent. Using optional `contextualData` to connect content from the page with the agent.

```html
<div id="my-content">Lorem ipsum</div>
<wy-messenger agent="assistant"></wy-messenger>
<script>
const myContent = document.querySelector("#my-content");
const messenger = document.querySelector("wy-messenger");
messenger.contextualData = myContent.innerHTML;
</script>
```

</figure>

<figure class="example"><figcaption>Messenger adapting to edges</figcaption>

Messenger that adapts to fit nicely with the edges of a panel.

```html
<style>
.messenger-panel {
display: flex;
height: 100%;
width: 32rem;
border: 1px solid gray;
--wy-padding-outer: 0;
--wy-border-radius-outer: 0;
}
</style>
<div class="messenger-panel">
<wy-messenger></wy-messenger>
</div>
```

</figure>

### Fields

| Name             | Type                          | Default            | Description                                                                                                            | Inherited From     |
| ---------------- | ----------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `agent`          | `string \| undefined`         |                    | Agent uid filter. When set, conversations are limited to the agent chat.                                               | WeavyTypeComponent |
| `unread`         | `number`                      |                    | Current unread conversation count.                                                                                     |                    |
| `instructions`   | `string \| undefined`         |                    | Optional agent instructions appended to submitted messages.                                                            |                    |
| `placeholder`    | `string \| undefined`         |                    | Placeholder text for the message editor.                                                                               |                    |
| `conversationId` | `number \| null \| undefined` | `null`             | Active conversation id.                                                                                                |                    |
| `link`           | `LinkType \| undefined`       |                    | Any provided link that should be loaded, shown and highlighted.                                                        | WeavyTypeComponent |
| `features`       | `string \| undefined`         |                    | Config for enabling/disabling specific features in the weavy component.&#xA;Prefix a feature with minus to disable it. | WeavyTypeComponent |
| `contextualData` | `string \| undefined`         |                    | Contextual data for agents to reference. Provide descriptive data for optimal results.&#xA;&#xA;### Examples           | WeavyTypeComponent |
| `annotations`    | `AnnotationsAppearanceType`   | `"buttons-inline"` | Appearance of annotations.                                                                                             | WeavyTypeComponent |
| `enterToSend`    | `EnterToSend`                 | `"auto"`           | Enter-to-send keymap in the editor. \`"modifier"\` is \`Enter\` combined with \`Ctrl\` or \`Cmd\`.                     | WeavyTypeComponent |
| `reactions`      | `string`                      | `"😍 😎 😉 😜 👍"` | A space separated string of available reaction emojis in unicode.                                                      | WeavyTypeComponent |
| `weavy`          | `WeavyType \| undefined`      |                    | The consumed weavy context.                                                                                            | WeavyComponent     |
| `contextId`      | `ContextIdType`               |                    | Contextual guid that is unique for the client context.                                                                 | WeavyComponent     |
| `user`           | `UserType \| undefined`       |                    | The current user.                                                                                                      | WeavyComponent     |

### Methods

| Name                 | Description                                                                                   | Parameters                | Return                    | Inherited From |
| -------------------- | --------------------------------------------------------------------------------------------- | ------------------------- | ------------------------- | -------------- |
| `createConversation` | Creates a new conversation.&#xA;&#xA;When in agent mode, a conversation is created instantly. | `members: MemberIdType[]` |                           |                |
| `selectMembers`      | Opens the select member dialog to let the user select members for creating a conversation.    |                           |                           |                |
| `whenUser`           | Resolves when current user data is available.                                                 |                           | `Promise<UserType>`       | WeavyComponent |
| `whenWeavy`          | Resolves when a weavy context is available.                                                   |                           | `Promise<WeavyType>`      | WeavyComponent |
| `whenReady`          | Resolves when the component has rendered first time.                                          |                           | `Promise<WeavyComponent>` | WeavyComponent |

### Events

| Name               | Type                      | Description                                                                         | Inherited From |
| ------------------ | ------------------------- | ----------------------------------------------------------------------------------- | -------------- |
| `wy-action`        | `WyActionEventType`       | Emitted when a conversation is created or an action is performed on a conversation. |                |
| `wy-preview-open`  | `WyPreviewOpenEventType`  | Fired when a preview overlay is about to open.                                      |                |
| `wy-preview-close` | `WyPreviewCloseEventType` | Fired when a preview overlay is closed.                                             |                |
| `wy-unread`        | `WyUnreadEventType`       | Emitted when the number of unread notifications change.                             |                |
| `ready`            | `CustomEvent`             | When the component has rendered.                                                    | WeavyComponent |

### Attributes

| Name             | Field          | Inherited From     |
| ---------------- | -------------- | ------------------ |
| `agent`          | agent          | WeavyTypeComponent |
| `instructions`   | instructions   |                    |
| `placeholder`    | placeholder    |                    |
| `conversationId` | conversationId |                    |
| `link`           | link           | WeavyTypeComponent |
| `features`       | features       | WeavyTypeComponent |
| `contextualData` | contextualData | WeavyTypeComponent |
| `annotations`    | annotations    | WeavyTypeComponent |
| `enterToSend`    | enterToSend    | WeavyTypeComponent |
| `reactions`      | reactions      | WeavyTypeComponent |

### CSS Parts

| Name                             | Description                                                |
| -------------------------------- | ---------------------------------------------------------- |
| `wy-messenger-layout`            | Main messenger layout.                                     |
| `wy-scroll-y`                    | Scrollable surface used by list and conversation sections. |
| `wy-messenger-conversation-list` | Container for the conversation list.                       |
| `wy-messenger-conversation`      | Container for the active conversation.                     |
| `wy-close-conversation`          | Wrapper around the close button and unread badge.          |

### Slots

| Name               | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `header`           | Header content rendered above the conversation list. |
| `actions`          | Action buttons for the conversation list toolbar.    |
| `conversation-new` | Custom content for the new-conversation action.      |

<details><summary>Private API</summary>

### Fields

| Name                         | Privacy   | Type                                                               | Default                                                                                                                   | Description                                        | Inherited From     |
| ---------------------------- | --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------ |
| `componentTypes`             | protected | `AppTypeGuid[]`                                                    | `[AppTypeGuid.ChatRoom, AppTypeGuid.PrivateChat]`                                                                         | Conversation types included in the messenger list. | WeavyTypeComponent |
| `visibilityElement`          | protected | `Element \| undefined`                                             |                                                                                                                           | Element to match visibility on.                    | WeavyTypeComponent |
| `#data`                      | private   | `ContextDataType[] \| undefined`                                   |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#annotations`               | private   | `WeavyComponentSettingProps["annotations"] \| undefined`           |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#enterToSend`               | private   | `EnterToSend \| undefined`                                         |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#reactions`                 | private   | `WeavyComponentSettingProps["reactions"] \| undefined`             |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#resolveContextDataBlobs`   | private   | `(blobs: ContextDataBlobsType) => void \| undefined`               |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenContextDataBlobs`      | private   |                                                                    | `new Promise<ContextDataBlobsType>((r) => { this.#resolveContextDataBlobs = r; })`                                        |                                                    | WeavyTypeComponent |
| `#resolveComponentFeatures`  | private   | `(componentFeatures: ComponentFeaturePolicy) => void \| undefined` |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenComponentFeatures`     | private   |                                                                    | `new Promise<ComponentFeaturePolicy>((r) => { this.#resolveComponentFeatures = r; })`                                     |                                                    | WeavyTypeComponent |
| `#resolveLink`               | private   | `(link: LinkType) => void \| undefined`                            |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenLink`                  | private   |                                                                    | `new Promise<LinkType>((r) => { this.#resolveLink = r; })`                                                                |                                                    | WeavyTypeComponent |
| `#resolveSettings`           | private   | `(settings: WeavyComponentSettingsType) => void \| undefined`      |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenSettings`              | private   |                                                                    | `new Promise<WeavyComponentSettingsType>((r) => { this.#resolveSettings = r; })`                                          |                                                    | WeavyTypeComponent |
| `#contextDataRefs`           | private   | `Map<ContextDataType, DataRefType>`                                | `new Map()`                                                                                                               |                                                    | WeavyTypeComponent |
| `#uploadContextDataMutation` | private   |                                                                    | `new MutationController<BlobType, Error, MutateFileProps, FileMutationContextType>(this)`                                 |                                                    | WeavyTypeComponent |
| `#mutatingContextData`       | private   |                                                                    | `new MutationStateController< BlobType \| FileType \| EmbedType, Error, MutateFileProps, FileMutationContextType >(this)` |                                                    | WeavyTypeComponent |
| `#resolveContextId`          | private   | `(contextId: ContextIdType) => void \| undefined`                  |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenContextId`             | private   |                                                                    | `new Promise<ContextIdType>((r) => { this.#resolveContextId = r; })`                                                      |                                                    | WeavyComponent     |
| `#resolveUser`               | private   | `(user: UserType) => void \| undefined`                            |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenUser`                  | private   |                                                                    | `new Promise<UserType>((r) => { this.#resolveUser = r; })`                                                                |                                                    | WeavyComponent     |
| `#resolveWeavy`              | private   | `(weavy: WeavyType) => void \| undefined`                          |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenWeavy`                 | private   |                                                                    | `new Promise<WeavyType>((r) => { this.#resolveWeavy = r; })`                                                              |                                                    | WeavyComponent     |
| `#resolveReady`              | private   | `(component: WeavyComponent) => void \| undefined`                 |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenReady`                 | private   |                                                                    | `new Promise<WeavyComponent>((r) => { this.#resolveReady = r; })`                                                         |                                                    | WeavyComponent     |
| `#userQuery`                 | private   |                                                                    | `new QueryController<UserType>(this)`                                                                                     |                                                    | WeavyComponent     |

</details>

<hr/>

## Exports

| Kind                        | Name           | Declaration | Module              | Package |
| --------------------------- | -------------- | ----------- | ------------------- | ------- |
| `js`                        | `WyMessenger`  | WyMessenger | lib/wy-messenger.ts |         |
| `custom-element-definition` | `wy-messenger` | WyMessenger | lib/wy-messenger.ts |         |
