@arcgis/ai-components 5.1.0-next.13 → 5.1.0-next.131

package/dist/components/arcgis-assistant/types.d.ts

@@ -1,29 +1,147 @@
+import type { UXSuggestion } from "../../utils/index.js";
+
+/** An interrupt is a UI mechanism used by an agent to prompt the user for additional input or clarification. */
 export interface Interrupt {
+  /**
+   * The unique identifier of the message associated with the interrupt. This is used to associate the interrupt
+   * with specific messages.
+   */
   id?: string;
+  /**
+   * The type of interrupt, which determines how the assistant will prompt the user for input. The available types are:
+   *
+   * - `boolean-choice`: Presents the user with a yes/no question.
+   * - `multi-select`: Allows the user to select multiple options from a list using a checkbox interface.
+   * - `single-select`: Allows the user to select a single option from a list using a radio button interface.
+   * - `text-input`: Prompts the user to enter free-form text input.
+   *
+   * The assistant will use the specified type to determine how to display the prompt and collect the user's response.
+   * For example, a `boolean-choice` interrupt might be used to confirm an action, while a `text-input`
+   * interrupt could be used to ask for more details about a request.
+   */
   type: "boolean-choice" | "multi-select" | "single-select" | "text-input";
+  /**
+   * The message to display to the user when prompting for input. This should provide clear instructions or questions
+   * related to the interrupt, guiding the user on what information is needed or what action they should take in response
+   * to the prompt.
+   *
+   * For example, if the interrupt type is `boolean-choice`, the message might be "Do you want to proceed with this
+   * action?" If the type is `text-input`, the message could be "Please provide more details about your request."
+   */
   message?: string;
+  /**
+   * The options to present to the user for selection when the interrupt type is `multi-select` or `single-select`.
+   * This should be an array of strings representing the available choices. For `boolean-choice`,
+   * the options are implicitly "Yes" and "No" and do not need to be provided.
+   * For `text-input`, options are not applicable and should be omitted.
+   *
+   * For example, if the interrupt type is `multi-select`, the options might be ["Option 1", "Option 2", "Option 3"].
+   * If the type is `single-select`, the options could be ["Choice A", "Choice B", "Choice C"].
+   */
   options?: string[];
 }
 
+/** A chat message sent by the assistant. */
 export interface AssistantMessage extends ChatMessageBase {
   role: "assistant";
+  /** The content of the assistant's message. This can include text generated by the assistant in response to the user's message. The content is displayed in the chat interface for the user to read and interact with. */
   content?: string;
+  /**
+   * Structured response UI blocks associated with the assistant message. These blocks are rendered as interactive
+   * UI elements separate from the plain text transcript and can be used to display actions, follow-up prompts,
+   * or app-registered custom content.
+   */
+  blocks?: (UXSuggestion & { isPending?: boolean; })[];
+  /**
+   * Log messages related to the assistant's processing of the user's request. This can include information about
+   * the agents or tools it invoked, the parameters generated by the LLM, and any relevant details about how it
+   * arrived at its response. Log messages are primarily intended for debugging and transparency purposes, allowing
+   * developers and users to understand the assistant's behavior and decision-making process.
+   */
   log?: string[];
+  /**
+   * An error message indicating any issues that occurred while the assistant was processing the user's request.
+   * The error message may be displayed in the chat interface to inform the user of the issue and can also be used for
+   * debugging and improving the assistant's performance.
+   */
   error?: string;
+  /**
+   * Feedback provided by the user for this specific assistant message. This allows users to indicate whether the
+   * assistant's response was helpful or not, which the app developer can capture and use to improve the assistant's
+   * performance over time.
+   */
   feedback?: Feedback;
+  /**
+   * Indicates whether the message content is still being streamed from the assistant. This can be used to show loading
+   * indicators or placeholders in the UI until the full content is received.
+   */
+  isStreaming?: boolean;
+  /**
+   * An array of interrupts emitted by the assistant during the processing of the user's request. Each interrupt includes
+   * details about the type of interrupt, the message to display to the user, and any options for user input.
+   */
+  interrupts?: {
+      interrupt: Interrupt;
+      response?: string[] | boolean | string;
+  }[];
 }
 
+/**
+ * A chat message from the user or the assistant. Messages include all relevant information such as content,
+ * logs, errors, and feedback.
+ */
 export type ChatMessage = AssistantMessage | UserMessage;
 
-export interface Feedback {
-  positive: boolean;
-}
+/** Detail payload emitted when a suggested prompt is selected. */
+export type AssistantPromptSelectDetail = {
+  /** The selected suggested prompt value. */
+  prompt: string;
+};
+
+/** Detail payload emitted by the assistant slottable request event. */
+export type AssistantSlottableRequestDetail = {
+  /** The request name describing the slot being requested. */
+  name: AssistantSlottableRequestName;
+  /** The slot name consumers should target when appending light DOM content. */
+  slotName: string;
+  /** Data describing the current slot request. */
+  data?: AssistantSlottableRequestData;
+};
 
+/** The base interface for chat messages exchanged between the user and the assistant. */
 export interface ChatMessageBase {
+  /**
+   * The unique identifier for the message. This is used to associate messages with interrupts and feedback.
+   * If not provided, a unique ID will be generated automatically.
+   */
   id: string;
 }
 
+/** A chat message sent by the user. */
 export interface UserMessage extends ChatMessageBase {
   role: "user";
+  /**
+   * The content of the user's message. This is the text input provided by the user in the chat interface.
+   * This content is sent to the assistant and its agents for processing and generating responses.
+   */
   content: string;
-}
+}
+
+/** Feedback provided by the user for a specific message. */
+export interface Feedback {
+  /** Indicates whether the feedback is positive or negative. */
+  positive: boolean;
+}
+
+/** Data emitted with an assistant slottable request. */
+export type AssistantSlottableRequestData = {
+  /** The assistant message associated with the slot request. */
+  message: AssistantMessage;
+  /** The block associated with the slot request, when requesting block content. */
+  block?: UXSuggestion;
+  /** Zero-based index of the block associated with the slot request. */
+  index?: number;
+};
+
+/** Supported assistant slottable request names. */
+export type AssistantSlottableRequestName = "block" | "message";

package/dist/components/arcgis-assistant-agent/customElement.d.ts

@@ -1,15 +1,21 @@
 /// <reference path="../../index.d.ts" />
-import type { AgentRegistration } from "@arcgis/ai-orchestrator";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { AgentRegistration } from "../../utils/index.js";
 
 /**
- * The Assistant Agent component is a generic wrapper for adding custom AI agents into the ArcGIS Assistant component. To define
+ * The Assistant Agent component is a generic wrapper for registering custom agents to the [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/) component. To define
  * a custom agent, you must be familiar with [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview). Custom agents must
  * include a StateGraph that defines the agent's graph and subgraphs.
  *
- * > Building custom agents can only be done using modern JavaScript/TypeScript tooling and cannot be done directly in HTML using
+ * Building custom agents can only be done using modern JavaScript/TypeScript tooling and cannot be done directly in HTML using
  * CDN imports. Therefore, you must use a package manager like npm or yarn to install the required dependencies. Please refer to the
- * Creating Custom Agents guide for more instructions.
+ * [Custom Agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/) for more instructions on how to create a custom agent.
+ *
+ * Use the [utils](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/) module for helper functions and types related to building custom agents, including the `AgentRegistration`
+ * type and functions for making LLM calls, managing agent state, and setting up human-in-the-loop workflows.
+ *
+ * > We recommend that developers building custom agents have experience working with LLMs and generative AI, and have a good
+ * understanding of the limitations of these technologies when building applications for end users.
  *
  * This is an unrendered component that must be added as a child of the `arcgis-assistant` component in either HTML or JavaScript.
  *
@@ -42,6 +48,12 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
  * @beta
  * @see [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/)
  * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
+ * @see [AgentRegistration](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#AgentRegistration)
+ * @see [invokeStructuredPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeStructuredPrompt)
+ * @see [invokeToolPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeToolPrompt)
+ * @see [invokeTextPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeTextPrompt)
  */
 export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> extends LitElement {
   /**
@@ -49,13 +61,15 @@ export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> e
    * This must include a StateGraph definition (defined using
    * [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview)).
    *
-   * This is an agent defined in the client and can be invoked by the assistant within the browser to perform specific tasks
+   * This is an agent defined in the client and can be invoked by the assistant from the browser to perform specific tasks
    * using functions defined in the client.
    *
-   * See the Creating Custom Agents guide for more instructions.
+   * See the [Custom Agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/) for more instructions
+   * and links to samples demonstrating how to create custom agents.
    *
    * @required
    * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+   * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
    * @example
    * ```js
    * // An example graph that updates a component property and replies with a confirmation message
@@ -111,17 +125,17 @@ export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> e
    */
   accessor agent: AgentRegistration;
   /**
-   * If the agent requires context, it can be provided via this property and accessed in the
+   * If the agent requires context provided by the application or user, it can be provided via this property and accessed in the
    * agent's graph nodes.
    *
    * @example
    * ```js
    * assistantAgent.context = {
    *   myData: {
-   *    // custom context data for the agent
+   *    // data required for the custom agent
    *   },
    * };
    * ```
    */
-  accessor context: TContext | undefined;
+  accessor context: TContext | (() => Promise<TContext | undefined> | TContext | undefined) | undefined;
 }

package/dist/components/arcgis-assistant-agent/customElement.js

@@ -1,19 +1,19 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
 import { c as t } from "../../chunks/runtime.js";
 import { LitElement as s } from "@arcgis/lumina";
-import { i as e } from "../../chunks/utils.js";
-class i extends s {
+import { i as e, a as i } from "../../chunks/utils2.js";
+class n extends s {
   static {
     this.properties = { agent: 0, context: 0 };
   }
-  getContext() {
-    return this.context;
+  async getContext() {
+    return e(this.context) ? await this.context() : this.context;
   }
   load() {
-    e(this);
+    i(this);
   }
 }
-t("arcgis-assistant-agent", i);
+t("arcgis-assistant-agent", n);
 export {
-  i as ArcgisAssistantAgent
+  n as ArcgisAssistantAgent
 };

package/dist/components/arcgis-assistant-chat/customElement.d.ts

@@ -1,20 +1,17 @@
 /// <reference path="../../index.d.ts" />
 import type Collection from "@arcgis/core/core/Collection.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
-import type { ChatMessage } from "../arcgis-assistant/types.js";
+import type { ChatMessage, Interrupt } from "../arcgis-assistant/types.js";
 
-/** @internal */
+/**
+ * Wraps and renders the conversation area. Use it as the container for message list content.
+ * Offers chat-level layout structure for message starter, message list, and loading regions.
+ *
+ * @internal
+ */
 export abstract class ArcgisAssistantChat extends LitElement {
-  /** @default false */
-  accessor copyEnabled: boolean;
-  /** @default false */
-  accessor feedbackEnabled: boolean;
+  accessor interrupt: Interrupt | null;
   /** @default false */
   accessor loading: boolean;
-  /** @default "" */
-  accessor loadingMessage: string;
-  /** @default false */
-  accessor logEnabled: boolean;
   accessor messages: Collection<ChatMessage>;
-  accessor user: string | undefined;
 }

package/dist/components/arcgis-assistant-chat/customElement.js

@@ -1,17 +1,17 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as t } from "../../chunks/runtime.js";
-import { css as e, html as s } from "lit";
+import { c as s } from "../../chunks/runtime.js";
+import { css as e, html as t } from "lit";
 import { LitElement as i } from "@arcgis/lumina";
-import { createRef as o, ref as l } from "lit/directives/ref.js";
-import n from "@arcgis/core/core/Collection.js";
-import { watch as c } from "@arcgis/core/core/reactiveUtils.js";
-const r = e`.assistant-chat__messages-container{display:flex;flex:1;flex-direction:column}.assistant-chat__messages-list{padding:var(--calcite-spacing-lg);display:flex;flex-direction:column;gap:var(--calcite-spacing-md);flex:1 1 auto;min-height:0;justify-content:flex-end;overflow:auto}`;
-class d extends i {
+import { createRef as a, ref as o } from "lit/directives/ref.js";
+import l from "@arcgis/core/core/Collection.js";
+import { watch as n } from "@arcgis/core/core/reactiveUtils.js";
+const r = e`.messages-container{display:flex;flex:1;flex-direction:column;line-height:var(--calcite-font-line-height-relative-snug)}.messages-list{padding:var(--calcite-spacing-lg);display:flex;flex-direction:column;gap:var(--calcite-spacing-xxl);flex:1 1 auto;min-height:0;justify-content:flex-end;overflow:auto}`;
+class c extends i {
   constructor() {
-    super(...arguments), this.#s = o(), this.feedbackEnabled = !1, this.logEnabled = !1, this.copyEnabled = !1, this.loading = !1, this.loadingMessage = "", this.messages = new n([]);
+    super(...arguments), this.#s = a(), this.loading = !1, this.messages = new l([]), this.interrupt = null;
   }
   static {
-    this.properties = { feedbackEnabled: 5, logEnabled: 5, copyEnabled: 5, loading: 5, loadingMessage: 1, user: 1, messages: 0 };
+    this.properties = { loading: 5, messages: 0, interrupt: 0 };
   }
   static {
     this.styles = r;
@@ -23,9 +23,9 @@ class d extends i {
   loaded() {
     this.manager.onLifecycle(() => [
       this.messages.on("change", () => {
-        this.requestUpdate(), this._scrollToEnd();
+        this._scrollToEnd();
       }),
-      c(() => this.loading, () => {
+      n(() => [this.loading, this.interrupt], () => {
         this._scrollToEnd();
       })
     ]);
@@ -36,10 +36,10 @@ class d extends i {
     });
   }
   render() {
-    return s`<div class="assistant-chat__messages-container"><div class="assistant-chat__messages-list"><slot></slot>${this.messages.map((a) => s`<arcgis-assistant-chat-card .message=${a} .user=${this.user} .feedbackEnabled=${this.feedbackEnabled} .logEnabled=${this.logEnabled} .copyEnabled=${this.copyEnabled}><slot name=chat-card-footer-actions-start slot=footer-actions-start></slot><slot name=chat-card-footer-actions-end slot=footer-actions-end></slot></arcgis-assistant-chat-card>`)}${this.loading ? s`<arcgis-assistant-chat-card .loading=${this.loading} .loadingMessage=${this.loadingMessage} .message=${{ id: "loading", role: "assistant", content: this.loadingMessage }}></arcgis-assistant-chat-card>` : null}</div><div ${l(this.#s)}></div></div>`;
+    return t`<div class="messages-container"><div class="messages-list"><slot name=message-starter></slot><slot name=messages></slot><slot name=message-loading></slot></div><div ${o(this.#s)}></div></div>`;
   }
 }
-t("arcgis-assistant-chat", d);
+s("arcgis-assistant-chat", c);
 export {
-  d as ArcgisAssistantChat
+  c as ArcgisAssistantChat
 };

package/dist/components/arcgis-assistant-chat/index.js

@@ -1,2 +1 @@
-import "../arcgis-assistant-chat-card/index.js";
 export * from "./customElement.js";

package/dist/components/arcgis-assistant-chat-entry/customElement.d.ts

@@ -4,20 +4,20 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ChatMessage } from "../arcgis-assistant/types.js";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
-/** @internal */
+/**
+ * Provides the input bar and submit or cancel behavior. Use it to collect prompts and emit submit events.
+ * Offers keyboard submit/history behavior, entry action slots, and optional voice-input integration.
+ *
+ * @slot [entry-actions-start] - Slot for adding actions to the start of the entry area.
+ * @slot [entry-actions-end] - Slot for adding actions to the end of the entry area.
+ */
 export abstract class ArcgisAssistantChatEntry extends LitElement {
   /** @internal */
-  protected _messages: {
-      entryPlaceholder: string;
-      stopButtonLabel: string;
-      askButtonLabel: string;
-  } & T9nMeta<{
-      entryPlaceholder: string;
-      stopButtonLabel: string;
-      askButtonLabel: string;
-  }>;
+  protected _messages: { entryPlaceholder: string; } & T9nMeta<{ entryPlaceholder: string; }>;
   /** @default false */
   accessor awaitingResponse: boolean;
+  /** @default false */
+  accessor disabled: boolean;
   accessor entryPlaceholder: string | undefined;
   /** @default "" */
   accessor inputValue: string;
@@ -25,6 +25,9 @@ export abstract class ArcgisAssistantChatEntry extends LitElement {
   accessor keyboardShortcutsDisabled: boolean;
   accessor messages: Collection<ChatMessage>;
   accessor status: "error" | "ready" | "working" | undefined;
+  /** @default false */
+  accessor voiceInputEnabled: boolean;
+  submitMessage(): Promise<void>;
   readonly arcgisCancel: import("@arcgis/lumina").TargetedEvent<this, void>;
   readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string>;
   readonly "@eventTypes": {

package/dist/components/arcgis-assistant-chat-entry/customElement.js

@@ -1,66 +1,85 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as u } from "../../chunks/runtime.js";
-import { css as h, html as l } from "lit";
-import { LitElement as d, createEvent as c, nothing as p } from "@arcgis/lumina";
-import { createRef as f, ref as g } from "lit/directives/ref.js";
-import { watch as m } from "@arcgis/core/core/reactiveUtils.js";
-import { u as y } from "../../chunks/useT9n.js";
-import _ from "@arcgis/core/core/Collection.js";
-const v = h`.assistant-chat-entry__input-container{display:flex;flex-direction:column}.assistant-chat-entry__footer-start{display:flex;gap:var(--calcite-spacing-md);flex-wrap:wrap;align-items:center}.assistant-chat-entry__footer-end{display:flex;gap:var(--calcite-spacing-md);align-items:center}.assistant-chat-entry__status-indicator{width:9px;height:9px;border-radius:100%;background-color:var(--calcite-color-status-success)}.assistant-chat-entry__status-indicator[data-status=working]{background-color:var(--calcite-color-status-warning)}.assistant-chat-entry__status-indicator[data-status=error]{background-color:var(--calcite-color-status-danger)}.assistant-chat-entry__status-text{text-transform:capitalize}`;
-class w extends d {
+import { c as d } from "../../chunks/runtime.js";
+import { css as p, html as c } from "lit";
+import { LitElement as f, createEvent as l, safeClassMap as g } from "@arcgis/lumina";
+import { createRef as u, ref as h } from "lit/directives/ref.js";
+import { u as m } from "../../chunks/useT9n.js";
+import y from "@arcgis/core/core/Collection.js";
+import { classes as v } from "@arcgis/toolkit/dom";
+const b = p`:host{--calcite-text-area-border-color: var(--calcite-color-border-1);--calcite-text-area-divider-color: var(--calcite-color-border-1);--calcite-text-area-corner-radius: var(--calcite-border-radius)}.input-container{display:flex;flex-direction:column}.footer-start{display:flex;gap:var(--calcite-spacing-md);flex-wrap:wrap;align-items:center}.footer-end{display:flex;gap:var(--calcite-spacing-md);align-items:center}.status-indicator{width:9px;height:9px;border-radius:100%;background-color:var(--calcite-color-status-success)}.status-indicator[data-status=working]{background-color:var(--calcite-color-status-warning)}.status-indicator[data-status=error]{background-color:var(--calcite-color-status-danger)}.status-text{text-transform:capitalize}.focused{--calcite-text-area-shadow: var(--calcite-shadow-sm)}`;
+class w extends f {
   constructor() {
-    super(...arguments), this.#s = f(), this.#t = -1, this.#e = "", this._messages = y({ blocking: !0 }), this.keyboardShortcutsDisabled = !1, this.awaitingResponse = !1, this.inputValue = "", this.messages = new _([]), this.arcgisCancel = c(), this.arcgisSubmit = c();
+    super(...arguments), this.#s = u(), this.#i = u(), this.#t = -1, this.#e = "", this.#a = (t) => {
+      t.stopPropagation();
+      const s = t.detail;
+      this._setDraftValue(s.value), s.focusInput && this.#s.value && this.#s.value.setFocus();
+    }, this.#r = (t) => {
+      const s = t.target.value ?? "";
+      this.inputValue = s, this.#e = s;
+    }, this._messages = m({ blocking: !0 }), this._inFocus = !1, this.keyboardShortcutsDisabled = !1, this.awaitingResponse = !1, this.inputValue = "", this.voiceInputEnabled = !1, this.messages = new y([]), this.disabled = !1, this.arcgisCancel = l(), this.arcgisSubmit = l();
   }
   static {
-    this.properties = { _userMessages: 16, keyboardShortcutsDisabled: 5, entryPlaceholder: 1, awaitingResponse: 5, inputValue: 1, status: 1, messages: 0 };
+    this.properties = { _inFocus: 16, _userMessages: 16, keyboardShortcutsDisabled: 5, entryPlaceholder: 1, awaitingResponse: 5, inputValue: 1, status: 1, voiceInputEnabled: 5, messages: 0, disabled: 5 };
   }
   static {
-    this.styles = v;
+    this.styles = b;
   }
   #s;
+  #i;
   #t;
   #e;
+  #a;
+  #r;
   get _userMessages() {
     return this.messages.toArray().filter((t) => t.role === "user").map(({ content: t }) => t);
   }
-  loaded() {
-    this.manager.onLifecycle(() => [
-      m(() => this.inputValue, (t) => {
-        this.#s.value && (this.#s.value.value = t);
-      }, { initial: !0 })
-    ]);
-  }
-  async _submitMessage() {
+  async submitMessage() {
     if (this.awaitingResponse) {
       this.arcgisCancel.emit();
       return;
     }
-    const t = this.#s.value?.value.trim();
-    t && (this.arcgisSubmit.emit(t), this.#t = -1, this.#e = "", this.#s.value && (this.#s.value.value = "", await this.#s.value.setFocus()));
+    const t = this.inputValue.trim();
+    t && (this.arcgisSubmit.emit(t), this.inputValue = "", this.#t = -1, this.#e = "", this.#i.value?.clearDraftSession(), this.#s.value && await this.#s.value.setFocus());
+  }
+  loaded() {
+    this.manager.onLifecycle(() => (this.el.addEventListener("arcgisVoiceInputDraftChange", this.#a), {
+      remove: () => {
+        this.el.removeEventListener("arcgisVoiceInputDraftChange", this.#a);
+      }
+    }));
   }
-  async _navigateHistory(t, i) {
-    const s = this.#s.value;
-    if (!s)
+  async _navigateHistory(t, s) {
+    const a = this.#s.value;
+    if (!a)
       return;
     const e = this._userMessages;
     if (e.length === 0)
       return;
-    const r = s.value ?? "", n = s.shadowRoot?.querySelector("textarea"), a = n?.selectionStart, o = n?.selectionEnd;
-    if (!(a == null || o == null) && !(a !== o || t === "up" && a !== 0 || t === "down" && a !== r.length)) {
+    const r = a.value ?? "", o = a.shadowRoot?.querySelector("textarea"), i = o?.selectionStart, n = o?.selectionEnd;
+    if (!(i == null || n == null) && !(i !== n || t === "up" && i !== 0 || t === "down" && i !== r.length)) {
       if (t === "up") {
-        this.#t === -1 ? (this.#e = r, this.#t = e.length - 1) : this.#t = Math.max(0, this.#t - 1), s.value = e[this.#t] ?? "", i.preventDefault();
+        this.#t === -1 ? (this.#e = r, this.#t = e.length - 1) : this.#t = Math.max(0, this.#t - 1), this.inputValue = e[this.#t] ?? "", s.preventDefault();
         return;
       }
-      this.#t !== -1 && (this.#t < e.length - 1 ? (this.#t += 1, s.value = e[this.#t] ?? "") : (this.#t = -1, s.value = this.#e), i.preventDefault());
+      this.#t !== -1 && (this.#t < e.length - 1 ? (this.#t += 1, this.inputValue = e[this.#t] ?? "") : (this.#t = -1, this.inputValue = this.#e), s.preventDefault());
     }
   }
+  _setDraftValue(t) {
+    this.inputValue = t, this.#t = -1, this.#e = t;
+  }
+  _onFocusIn() {
+    this._inFocus = !0;
+  }
+  _onFocusOut() {
+    this._inFocus = !1;
+  }
   render() {
-    return l`<div class="assistant-chat-entry__input-container"><calcite-text-area .value=${this.#s.value?.value} .placeholder=${this.entryPlaceholder ?? this._messages.entryPlaceholder} resize=vertical @keydown=${async (t) => {
-      t.altKey || t.ctrlKey || t.metaKey || t.shiftKey || this.keyboardShortcutsDisabled || (t.key === "Enter" ? (t.preventDefault(), await this._submitMessage()) : t.key === "ArrowUp" ? await this._navigateHistory("up", t) : t.key === "ArrowDown" && await this._navigateHistory("down", t));
-    }} ${g(this.#s)}><div slot=footer-start class="assistant-chat-entry__footer-start"><slot name=entry-actions-start></slot></div><div slot=footer-end class="assistant-chat-entry__footer-end">${this.status ? l`<div id=tooltip-status class="assistant-chat-entry__status-indicator" data-status=${this.status ?? p}></div><calcite-tooltip reference-element=tooltip-status offset-distance=12><span class="assistant-chat-entry__status-text">${this.status}</span></calcite-tooltip>` : null}<calcite-button .iconStart=${this.awaitingResponse ? "circle-stop" : "send"} slot=footer-end round @click=${() => void this._submitMessage()}>${this.awaitingResponse ? this._messages.stopButtonLabel : this._messages.askButtonLabel}</calcite-button></div></calcite-text-area></div>`;
+    return c`<div class="input-container"><calcite-text-area class=${g(v({ focused: this._inFocus }))} .value=${this.inputValue} .placeholder=${this.entryPlaceholder ?? this._messages.entryPlaceholder} resize=vertical @calciteTextAreaInput=${this.#r} .disabled=${this.disabled} @keydown=${async (t) => {
+      t.altKey || t.ctrlKey || t.metaKey || t.shiftKey || this.keyboardShortcutsDisabled || (t.key === "Enter" ? (t.preventDefault(), await this.submitMessage()) : t.key === "ArrowUp" ? await this._navigateHistory("up", t) : t.key === "ArrowDown" && await this._navigateHistory("down", t));
+    }} @focusin=${this._onFocusIn} @focusout=${this._onFocusOut} ${h(this.#s)}><div slot=footer-start class="footer-start"><slot name=entry-actions-start></slot></div><div slot=footer-end class="footer-end">${this.voiceInputEnabled ? c`<arcgis-assistant-speech-input .awaitingResponse=${this.awaitingResponse} .inputValue=${this.inputValue} ${h(this.#i)}></arcgis-assistant-speech-input>` : null}<slot name=entry-actions-end></slot></div></calcite-text-area></div>`;
   }
 }
-u("arcgis-assistant-chat-entry", w);
+d("arcgis-assistant-chat-entry", w);
 export {
   w as ArcgisAssistantChatEntry
 };

package/dist/components/arcgis-assistant-chat-entry/index.js

@@ -1,4 +1,3 @@
 import "@esri/calcite-components/components/calcite-text-area";
-import "@esri/calcite-components/components/calcite-tooltip";
-import "@esri/calcite-components/components/calcite-button";
+import "../arcgis-assistant-speech-input/index.js";
 export * from "./customElement.js";

package/dist/components/arcgis-assistant-data-exploration-agent/customElement.d.ts

@@ -3,14 +3,23 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
 
 /**
- * The Data Exploration Agent component enables the end user to query features, statistics, and spatial proximity
- * of layer within a provided web map. Currently, this is only scoped to querying feature layers within
- * a 2D web map.
+ * The Data Exploration Agent enables the end user to query features, statistics, and spatial proximity
+ * to features in a layer within a web map. Currently, this is only scoped to querying feature layers within
+ * a 2D web map. See the list of capabilities below for more details.
+ *
+ * The data exploration agent is designed to answer questions about the data in the map, and does not have
+ * access to external data sources or the user's location. It also cannot create visualizations in the form of charts,
+ * layer renderers, new maps, or other visual outputs. It can currently only provide answers in text form based on the
+ * data in the map.
+ *
+ * This agent can change the state of the map by filtering features in a layer, but it cannot change the symbology of
+ * features or create new layers or export results of a query to a file or external source.
  *
  * This is an unrendered component that must be added as a child of the `arcgis-assistant` component in either HTML or JavaScript.
  *
  * ```html
- * <arcgis-assistant>
+ * <arcgis-map id="my-map"></arcgis-map>
+ * <arcgis-assistant reference-element="my-map">
  *   <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
  * </arcgis-assistant>
  * ```
@@ -21,14 +30,72 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * assistant.appendChild(dataExplorationAgent);
  * ```
  *
+ * Once added to the assistant, the agent is loaded and ready to receive user messages related to data exploration.
+ *
+ * ### Capabilities
+ *
+ * The data exploration agent provides the following capabilities related to exploring data in the map:
+ *
+ * - **Query features** - Ask about the attributes of features in a layer, including a single feature or a set
+ *   of features.
+ * - **Query statistics** - Ask about statistics related to features in a layer. Statistics that can be queried
+ *   include count, average, minimum, maximum, and sum. This includes asking about the top number of features based on a
+ *   particular attribute.
+ * - **Query spatial proximity** - Ask about the spatial proximity of features in a layer, such as
+ *   the number of features that intersect a polygon, or information about features within a distance of a specified location or feature.
+ *   This currently does not include questions about the closest feature, but this is planned to be included in a future release.
+ * - **Filter features** - Users can ask the agent to show a subset of features that filter by attributes, or spatial
+ *   proximity to other features. This includes asking the agent to show features that intersect a particular area,
+ *   or are within a certain distance of a location or feature.
+ *
+ * ### Example questions
+ *
+ * The following are example questions a user can ask within the bounds of the data exploration agent.
+ * These questions assume a map with layers that include cities, states, and rivers.
+ *
+ * - "What is the city with the largest population?"
+ * - "How does that population compare to the average population of the cities in this map?"
+ * - "How many cities are within 30 miles of the Colorado River?"
+ * - "Show all cities in the state of California."
+ * - "List the top 5 rivers by length."
+ * - "Emphasize the largest river on the map."
+ *
+ * The following are examples of the types of questions that fall outside the bounds of the
+ * data exploration agent and should therefore be avoided:
+ *
+ * - "What is the closest restaurant to me?" (the data exploration agent does not have access to the user's location,
+ * nor can it find the nearest feature from a location)
+ * - "What is the projected growth of Phoenix in the next 10 years?" (the data exploration agent can
+ * only answer questions about the data in the map, not external data or projections)
+ * - "Show me the population of cities in this map on a graph." (the data exploration agent can only
+ * provide answers in text form, not visualizations)
+ *
+ * > Due to the non-deterministic nature of generative AI, there may be inaccuracies or unexpected behavior when using the
+ * out-of-the-box agents.
+ *
  * @since 5.0
  * @beta
  * @see [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/)
+ * @see [Intro to building agentic mapping applications](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-introduction/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
  */
 export abstract class ArcgisAssistantDataExplorationAgent extends LitElement {
   /**
-   * A reference to the map element or its ID string used to resolve the MapView for this agent.
-   * If not provided, the agent will attempt to find the closest parent `arcgis-map` element.
+   * The reference element to the map that provides context for the data exploration agent. Currently,
+   * this is only scoped to `arcgis-map` elements. This provides the data exploration agent with the layers
+   * needed for answering user questions about the data in the map.
+   *
+   * Setting this property is not necessary if you set the reference element on the parent
+   * `arcgis-assistant` component.
+   *
+   * @see [arcgis-assistant.referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#referenceElement)
+   * @example
+   * ```html
+   * <arcgis-map id="my-map"></arcgis-map>
+   * <arcgis-assistant>
+   *   <arcgis-assistant-data-exploration-agent reference-element="my-map"></arcgis-assistant-data-exploration-agent>
+   * </arcgis-assistant>
+   * ```
    */
   accessor referenceElement: ArcgisMap | string | undefined;
 }