## class: `WyCopilot`, `wy-copilot`

Weavy copilot component to render single, contextual and personal chats with an AI agent.

It needs to be [configured with an AI agent](https://www.weavy.com/docs/learn/integrations/agent) and can have custom *instructions* and use any *contextual data* you provide (as long as it's a string).
To get started, you can use Weavy's built-in `"assistant"` agent.

The copilot chat is agent-to-user which means each user has their own chat with the agent.
Each time the copilot component is loaded a fresh chat is started.
A fresh conversation can be started at any time by using the `.reset()` method.
The component can optionally be configured with a `uid` to persist the conversation.

> If you specify a `uid` it needs to be unique per *user* and *agent* (if you intend to use several agents).
> For ease-of-use, you can do this automatically by specifying the `generateUid` property instead of the `uid` property.
> It's optional to provide a uid and in many cases not needed.
> When using a uid 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.

Predefined elements with the `suggestion` class can be placed in the `suggestion-list` slot to create text hints for the user on what to do.
When clicked, the suggestion text gets automatically placed in the message editor.

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

### Examples

<figure class="example"><figcaption>Generic AI copilot chat</figcaption>

Displays a chat based AI copilot, placed in a container using a flex layout which the component adapts to.

The `agent` property is required and should correspond to [agent](https://www.weavy.com/docs/learn/integrations/agents) in your environment.
You may switch between agents whenever you like, but remember that the conversation also changes.

Here we use the built-in agent with uid `assistant`.

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

</figure>

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

The copilot gets much more useful if it knows 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-copilot id="my-copilot" agent="assistant"></wy-copilot>

<script>
const copilot = document.querySelector("#my-copilot");
const sampleContent = document.querySelector("#my-sample-content");

copilot.instructions = "Answer in a whacky way with many emojis.";
copilot.data = [sampleContent.innerHTML];
</script>
```

</figure>

<figure class="example"><figcaption>Copilot with a custom button and suggestions</figcaption>

You may use slots to provide custom functionality to the copilot. This example shows a button to reset the conversation and some custom suggestions.

When the suggestions have the `.suggestion` class, they automatically get their text inserted into the editor when clicked.

In this example we use the pre-styled weavy sub components, but you may use any elements or components you like.

```html
<wy-copilot id="my-copilot" agent="assistant">
<wy-button
slot="actions"
kind="icon"
onclick="document.querySelector('#my-copilot').reset()"
>
<wy-icon name="stars"></wy-icon>
</wy-button>

<wy-button slot="suggestion-list" class="suggestion">Summarize this page</wy-button>
<wy-button slot="suggestion-list" class="suggestion">What keywords are used?</wy-button>
</wy-copilot>
```

</figure>

<figure class="example"><figcaption>Preventing child nodes from flashing during load</figcaption>

To prevent child nodes from rendering before the component has loaded you can hide them using CSS.

```css
wy-copilot:not(:defined) { display: none; }
```

</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. Overrides default text.                                                                                        |                    |
| `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    |
| --------------- |   | -------------------- | ------------------------- | ----------------- |
| `setSuggestion` | Sets the editor input to a suggested text. This replaces the text content of the editor. This can be used to create any custom suggestions.                                                                                                                                                                                                                                                                                                                                                                                                               | `text: string`       |                           |                   |
| `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 a conversation or embed. |                |
| `wy-message`       | `WyMessageEventType`      | Fired when a message has been appended to the 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.                         |                |
| `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.         |
| `empty`           | All the content for the empty state.              |
| `header`          | Header for the \`empty\` state.                   |
| `icon`            | Display icon in the \`header\`.                   |
| `suggestions`     | Suggestion content in the \`empty\` state.        |
| `suggestion-list` | Items for the list in the \`suggestion\` content. |
| `footer`          | Footer for the \`empty\` state.                   |

<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`                        | `WyCopilot`  | WyCopilot   | lib/wy-copilot.ts |         |
| `custom-element-definition` | `wy-copilot` | WyCopilot   | lib/wy-copilot.ts |         |
