## class: `WyChat`, `wy-chat`

Weavy chat component to render a single contextual conversation.

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.

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.

Each chat component requires an app identifier (`uid`), which automatically creates a [corresponding app](https://www.weavy.com/docs/concepts#app) on your Weavy environment when the component is first initialized.
It's also recommended to specify a readable `name` of the chat, to get better readable notifications from the app.

> It's often useful to base the `uid` on something that identifies the location where the component is rendered.
> Typically you would use something like a product id, page id or path.

> 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 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 height grows with the content per default. Content is automatically loaded during scrolling when the last content becomes visible (aka infinite scrolling).
If placed in a flex- or grid-layout or if an explicit height is set, the component becomes scrollable.

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-conversation>`](./components/wy-conversation)
*   [`<wy-buttons>`](./components/ui/wy-button)
*   [`<wy-context-data-progress>`](./components/wy-context-data)

### Examples

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

Displays a conversation, placed in a container using a flex layout which the component adapts to. Authenticated users with access to the component will be added as members in the conversation.

Specifying the app identifier (`uid`) is required, and automatically creates a [corresponding app](https://www.weavy.com/docs/concepts#app) on your Weavy environment when the component is first initialized.
It's recommended to specify a readable `name` of the chat app, to get better readable notifications from the app.

```html
<div style="display: flex; height: 100%;">
<wy-chat uid="test-chat" name="Test chat"></wy-chat>
</div>
```

</figure>

<figure class="example"><figcaption>Chat with instructions and contextual data</figcaption>

Any agents added to the chat using the [Web API](https://www.weavy.com/docs/reference/api) gets much more useful if they know about the data and content on your page. You can update this anytime you like to keep it up-to-date. Here we provide data from the DOM to the agent using the `contextualData` property.

```html
<div id="my-sample-content">
<h1>ACME</h1>
<ul>
<li>Wile E. Coyote</li>
<li>Daffy Duck</li>
<li>Porky Pig</li>
</ul>
</div>

<wy-chat uid="test-chat" name="Test chat"></wy-chat>

<script>
const myContent = document.querySelector("#my-sample-content");
const chat = document.querySelector("wy-chat");
chat.contextualData = myContent.innerHTML;
</script>
```

</figure>

### Fields

| Name             | Type                                    | Default            | Description                                                                                                                                             | Inherited From     |
| ---------------- | --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `instructions`   | `string \| undefined`                   |                    | Optional agent instructions appended to submitted messages.                                                                                             |                    |
| `placeholder`    | `string \| undefined`                   |                    | Placeholder text for the message editor.                                                                                                                |                    |
| `app`            | `AppType \| undefined`                  |                    | The current app data.                                                                                                                                   | WeavyAppComponent  |
| `apps`           | `AppListType \| undefined`              |                    | A list of data for all the apps specified by the \`uid\` property.                                                                                      | WeavyAppComponent  |
| `link`           | `LinkType \| undefined`                 |                    | Any provided link that should be loaded, shown and highlighted.                                                                                         | WeavyTypeComponent |
| `generateUid`    | `string \| null \| undefined`           |                    | Sets the uid property to a single uid with automatically appended user and agent name (where applicable).                                               | WeavyAppComponent  |
| `uid`            |                                         |                    | One or multiple unique app identifiers or app id:s. When a single uid is provided, the app gets automatically created on the server upon first request. | WeavyAppComponent  |
| `uids`           |                                         |                    | An array of parsed uids from the \`uid\` property.                                                                                                      | WeavyAppComponent  |
| `currentUid`     | `string \| number \| null \| undefined` | `undefined`        | The currently selected app uid when multiple \`uid\` is provided. Defaults to the first uid from the \`uid\` property.                                  | WeavyAppComponent  |
| `name`           | `string \| undefined`                   |                    | Optional display name for the app (used in notifications etc.)                                                                                          | WeavyAppComponent  |
| `features`       | `string \| undefined`                   |                    | Config for enabling/disabling specific features in the weavy component.&#xA;Prefix a feature with minus to disable it.                                  | WeavyTypeComponent |
| `agent`          | `string \| undefined`                   |                    | The configured uid of the agent for the weavy component.                                                                                                | 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    |
| ----------- |   | -------------------- | ------------------------- | ----------------- |
| `reset`     | Sets the component to it's initial state and resets the app state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                      |                           | WeavyAppComponent |
| `subscribe` | Subscribes or unsubscribes to notification updates from the app. Check \`.app.is\_subscribed\` to see current state.&#xA;&#xA;### Examples&#xA;&#xA;\<figure class="example">\<figcaption>Toggle app subscription\</figcaption>&#xA;&#xA;\`\`\`js&#xA;// Wait for app data&#xA;await myWeavyComponent.whenApp();&#xA;&#xA;// Get current app subscription state&#xA;const isSubscribed = myWeavyComponent.app.is\_subscribed;&#xA;&#xA;// Toggle the app subscription state&#xA;myWeavyComponent.subscribe(!isSubscribed);&#xA;\`\`\`&#xA;&#xA;\</figure> | `subscribe: boolean` | `Promise<void>`           | WeavyAppComponent |
| `whenApp`   | Resolves when app data is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                      | `Promise<AppType>`        | WeavyAppComponent |
| `whenApps`  | Resolves when multiple apps is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                      | `Promise<AppType[]>`      | WeavyAppComponent |
| `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-app`           | `WyAppEventType`          | Fired whenever the app property changes.         |                |
| `wy-action`        | `WyActionEventType`       | Emitted when an action is performed on an embed. |                |
| `wy-preview-open`  | `WyPreviewOpenEventType`  | Fired when a preview overlay is about to open.   |                |
| `wy-preview-close` | `WyPreviewCloseEventType` | Fired when a preview overlay is closed.          |                |
| `ready`            | `CustomEvent`             | When the component has rendered.                 | WeavyComponent |

### Attributes

| Name             | Field          | Inherited From     |
| ---------------- | -------------- | ------------------ |
| `instructions`   | instructions   |                    |
| `placeholder`    | placeholder    |                    |
| `link`           | link           | WeavyTypeComponent |
| `generateUid`    | generateUid    | WeavyAppComponent  |
| `uid`            | uid            | WeavyAppComponent  |
| `currentUid`     | currentUid     | WeavyAppComponent  |
| `name`           | name           | WeavyAppComponent  |
| `features`       | features       | WeavyTypeComponent |
| `agent`          | agent          | WeavyTypeComponent |
| `contextualData` | contextualData | WeavyTypeComponent |
| `annotations`    | annotations    | WeavyTypeComponent |
| `enterToSend`    | enterToSend    | WeavyTypeComponent |
| `reactions`      | reactions      | WeavyTypeComponent |

### Slots

| Name      | Description                               |
| --------- | ----------------------------------------- |
| `actions` | Floating buttons placed in the top right. |

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

### Fields

| Name                         | Privacy   | Type                                                               | Default                                                                                                                   | Description                             | Inherited From     |
| ---------------------------- | --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------ |
| `appType`                    | protected | `AppTypeGuid \| UnknownAppType`                                    |                                                                                                                           | Any app type for the weavy component.   | WeavyAppComponent  |
| `#uid`                       | private   | `string \| number \| null \| undefined`                            |                                                                                                                           |                                         | WeavyAppComponent  |
| `#uids`                      | private   | `Array<string \| number>`                                          | `[]`                                                                                                                      |                                         | WeavyAppComponent  |
| `_initialAppName`            | private   | `string \| undefined`                                              |                                                                                                                           |                                         | WeavyAppComponent  |
| `_appName`                   | private   | `string \| undefined`                                              |                                                                                                                           |                                         | WeavyAppComponent  |
| `appSubscribeMutation`       | private   |                                                                    | `new MutationController< void, Error, MutateAppSubscribeProps, MutateAppSubscribeContextType >(this)`                     |                                         | WeavyAppComponent  |
| `#resolveApp`                | private   | `(app: AppType) => void \| undefined`                              |                                                                                                                           |                                         | WeavyAppComponent  |
| `#whenApp`                   | private   |                                                                    | `new Promise<AppType>((r) => { this.#resolveApp = r; })`                                                                  |                                         | WeavyAppComponent  |
| `#resolveApps`               | private   | `(apps: AppListType) => void \| undefined`                         |                                                                                                                           |                                         | WeavyAppComponent  |
| `#whenApps`                  | private   |                                                                    | `new Promise<AppListType>((r) => { this.#resolveApps = r; })`                                                             |                                         | WeavyAppComponent  |
| `#appQuery`                  | private   |                                                                    | `new QueryController<AppType>(this)`                                                                                      |                                         | WeavyAppComponent  |
| `#multipleAppsQueryMap`      | private   |                                                                    | `new Map<string \| number, QueryController<AppType>>()`                                                                   |                                         | WeavyAppComponent  |
| `#appsQuery`                 | private   |                                                                    |                                                                                                                           |                                         | WeavyAppComponent  |
| `visibilityElement`          | protected | `Element \| undefined`                                             |                                                                                                                           | Element to match visibility on.         | WeavyTypeComponent |
| `componentTypes`             | protected | `AppTypeGuid[]`                                                    |                                                                                                                           | Any app types handled by the component. | 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`                        | `WyChat`  | WyChat      | lib/wy-chat.ts |         |
| `custom-element-definition` | `wy-chat` | WyChat      | lib/wy-chat.ts |         |
