## class: `WyMessengerBadge`, `wy-messenger-badge`

Weavy Messenger badge component that renders a realtime badge for the number of unread conversations.
The badge fits well into a button or similar.
The badge is automatically updated when new messages awaits and when messages have been read.

The badge can optionally be configured in *agent mode*, by defining the `agent` property, to only show the count for conversations with a given [AI agent](https://www.weavy.com/docs/learn/integrations/agents).

When the `unread` count property changes, the component fires a `"wy-unread"` event with the updated count.
You can listen to the event to use the unread count for something else, and you can also turn off the component rendering by setting the `badge` property to `"none"`.

\*\* Component layout \*\*

The badge displays as an inline badge, matching normal text per default.
It has a filled background with rounded edge.
The size and font-size is relative to the current font-size where it's placed, defaulting to `0.75em` for the badge `font-size` and `0.3333em` of the badge *font-size* for the `padding`.
The badge is only displayed when there is an unread count of 1 or higher.

> When placing the badge in a `<button>` element, note that buttons initially have a `font-size` of `13.3333px` instead of inheriting font-size from it's parents.

Setting the `badge` property to `"compact"` reduces the padding and size to occupy less visual space.
It can also be set to `"dot"` to remove the text, only indicating that there is unread conversations without any count.

The `badgePosition` property can be changed from `"inline"` to `"top-right"` or any other corner,
to give it absolute positioning over the top-right corner.
The absolute positioning is relative to the closest parent element with set CSS `position`, for instance `relative` positioning.

**Used sub components:**

*   [`<wy-badge>`](./components/ui/wy-badge)

### Examples

<figure class="example"><figcaption>Inline Messenger badge in a text</figcaption>

Display a badge that shows unread count and tracks messages and conversations for the authenticated user.

```html
<div>Messenger <wy-messenger-badge></wy-messenger-badge></div>
```

</figure>

<figure class="example"><figcaption>Filtered Messenger badge using agent mode</figcaption>

Only displays the count for conversations with the built-in `assistant` agent.

```html
<wy-messenger-badge agent="assistant"></wy-messenger-badge>
```

</figure>

<figure class="example"><figcaption>Compact cornered Messenger badge</figcaption>

Displays a *compact* badge in the top-right corner of a button with adjusted font-size.
Note that the badge position is relative to its closest positioned ancestor element, therefore we need to set CSS `position` on the button.

```html
<button style="position: relative; font-size: 1rem;">
<span>Messenger</span>
<wy-messenger-badge badge="compact" badgePosition="top-right"></wy-messenger-badge>
</button>
```

</figure>

### Fields

| Name             | Type                                                                       | Default            | Description                                                                                                            | Inherited From     |
| ---------------- | -------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `badge`          | `"count" \| "compact" \| "dot" \| "none"`                                  | `"count"`          | Display size of the badge.                                                                                             |                    |
| `badgePosition`  | `"inline" \| "top-right" \| "bottom-right" \| "bottom-left" \| "top-left"` | `"inline"`         | Positioning of the badge.                                                                                              |                    |
| `agent`          | `string \| undefined`                                                      |                    | Agent uid filter. When set, unread counts are limited to the agent chat.                                               | WeavyTypeComponent |
| `unread`         | `number`                                                                   |                    | Current unread conversation count.                                                                                     |                    |
| `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 |
| ----------- | ---------------------------------------------------- | ---------- | ------------------------- | -------------- |
| `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-unread` | `WyUnreadEventType` | Fired when the number of unread conversations change. |                |
| `ready`     | `CustomEvent`       | When the component has rendered.                      | WeavyComponent |

### Attributes

| Name             | Field          | Inherited From     |
| ---------------- | -------------- | ------------------ |
| `badge`          | badge          |                    |
| `badgePosition`  | badgePosition  |                    |
| `agent`          | agent          | WeavyTypeComponent |
| `link`           | link           | WeavyTypeComponent |
| `features`       | features       | WeavyTypeComponent |
| `contextualData` | contextualData | WeavyTypeComponent |
| `annotations`    | annotations    | WeavyTypeComponent |
| `enterToSend`    | enterToSend    | WeavyTypeComponent |
| `reactions`      | reactions      | WeavyTypeComponent |

<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 unread count. | 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`                        | `WyMessengerBadge`   | WyMessengerBadge | lib/wy-messenger-badge.ts |         |
| `custom-element-definition` | `wy-messenger-badge` | WyMessengerBadge | lib/wy-messenger-badge.ts |         |
