@arcgis/ai-components 5.1.0-next.9 → 5.1.0-next.91

package/dist/components/arcgis-assistant-message-block/customElement.js

@@ -0,0 +1,29 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as o } from "../../chunks/runtime.js";
+import { css as i, html as p } from "lit";
+import { LitElement as n } from "@arcgis/lumina";
+const l = i`:host{display:block}`;
+class a extends n {
+  static {
+    this.properties = { block: 0 };
+  }
+  static {
+    this.styles = l;
+  }
+  _renderSuggestedPrompts(s) {
+    if (s.type !== "suggested-prompts")
+      return null;
+    const t = s.data?.prompts, e = Array.isArray(t) ? t.filter((r) => typeof r == "string") : [];
+    return e.length ? p`<arcgis-assistant-suggested-prompts .prompts=${e}></arcgis-assistant-suggested-prompts>` : null;
+  }
+  _renderBlock(s) {
+    return s.type === "suggested-prompts" ? this._renderSuggestedPrompts(s) : null;
+  }
+  render() {
+    return this.block ? this._renderBlock(this.block) : null;
+  }
+}
+o("arcgis-assistant-message-block", a);
+export {
+  a as ArcgisAssistantMessageBlock
+};

package/dist/components/arcgis-assistant-message-block/index.js

@@ -0,0 +1,2 @@
+import "../arcgis-assistant-suggested-prompts/index.js";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-feedback/customElement.d.ts

@@ -0,0 +1,23 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { AssistantMessage } from "../arcgis-assistant/types.js";
+import type { T9nMeta } from "@arcgis/lumina/controllers";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageFeedback extends LitElement {
+  /** @internal */
+  protected _messages: {
+      thumbsUpLabel: string;
+      thumbsDownLabel: string;
+  } & T9nMeta<{
+      thumbsUpLabel: string;
+      thumbsDownLabel: string;
+  }>;
+  /** @default false */
+  accessor feedbackEnabled: boolean;
+  accessor message: AssistantMessage | undefined;
+  readonly arcgisFeedback: import("@arcgis/lumina").TargetedEvent<this, AssistantMessage>;
+  readonly "@eventTypes": {
+    arcgisFeedback: ArcgisAssistantMessageFeedback["arcgisFeedback"]["detail"];
+  };
+}

package/dist/components/arcgis-assistant-message-feedback/customElement.js

@@ -0,0 +1,36 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as s } from "../../chunks/runtime.js";
+import { css as i, html as e } from "lit";
+import { LitElement as a, createEvent as c } from "@arcgis/lumina";
+import { u as n } from "../../chunks/useT9n.js";
+const o = i`.actions{display:flex;flex-direction:row;gap:var(--calcite-spacing-xs)}`;
+class r extends a {
+  constructor() {
+    super(...arguments), this._messages = n({ blocking: !0 }), this.feedbackEnabled = !1, this.arcgisFeedback = c();
+  }
+  static {
+    this.properties = { feedbackEnabled: 5, message: 0 };
+  }
+  static {
+    this.styles = o;
+  }
+  _handleFeedback(t) {
+    this.message && (this.message.feedback = this.message.feedback?.positive === t ? void 0 : { positive: t }, this.arcgisFeedback.emit(this.message), this.requestUpdate());
+  }
+  _getFeedback() {
+    return this.message?.feedback?.positive;
+  }
+  _renderThumbsUpButton() {
+    return e`<calcite-action id=action-thumbs-up icon=thumbs-up scale=s .active=${this._getFeedback() === !0} @click=${() => this._handleFeedback(!0)} text></calcite-action><calcite-tooltip reference-element=action-thumbs-up overlay-positioning=fixed placement=bottom><span>${this._messages.thumbsUpLabel}</span></calcite-tooltip>`;
+  }
+  _renderThumbsDownButton() {
+    return e`<calcite-action id=action-thumbs-down icon=thumbs-down scale=s .active=${this._getFeedback() === !1} @click=${() => this._handleFeedback(!1)} text></calcite-action><calcite-tooltip reference-element=action-thumbs-down overlay-positioning=fixed placement=bottom><span>${this._messages.thumbsDownLabel}</span></calcite-tooltip>`;
+  }
+  render() {
+    return this.feedbackEnabled && !this.message?.error ? e`<div class="actions">${this._renderThumbsUpButton()}${this._renderThumbsDownButton()}</div>` : null;
+  }
+}
+s("arcgis-assistant-message-feedback", r);
+export {
+  r as ArcgisAssistantMessageFeedback
+};

package/dist/components/arcgis-assistant-message-feedback/index.js

@@ -0,0 +1,3 @@
+import "@esri/calcite-components/components/calcite-action";
+import "@esri/calcite-components/components/calcite-tooltip";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-footer/customElement.d.ts

@@ -0,0 +1,25 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { AssistantMessage } from "../arcgis-assistant/types.js";
+import type { T9nMeta } from "@arcgis/lumina/controllers";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageFooter extends LitElement {
+  /** @internal */
+  protected _messages: {
+      copyButtonLabel: string;
+      logButtonLabel: string;
+  } & T9nMeta<{
+      copyButtonLabel: string;
+      logButtonLabel: string;
+  }>;
+  /** @default false */
+  accessor copyEnabled: boolean;
+  /** @default false */
+  accessor feedbackEnabled: boolean;
+  /** @default false */
+  accessor logEnabled: boolean;
+  accessor message: AssistantMessage | undefined;
+  /** @default false */
+  accessor readAloudEnabled: boolean;
+}

package/dist/components/arcgis-assistant-message-footer/customElement.js

@@ -0,0 +1,62 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as s } from "../../chunks/runtime.js";
+import { css as a, html as e } from "lit";
+import { watch as o } from "@arcgis/core/core/reactiveUtils.js";
+import { LitElement as i } from "@arcgis/lumina";
+import { createRef as n, ref as r } from "lit/directives/ref.js";
+import { u as l } from "../../chunks/useT9n.js";
+import { log as c } from "@arcgis/toolkit/log";
+const d = a`.container{display:flex;align-items:center;width:100%;justify-content:space-between;gap:var(--calcite-spacing-xs)}.start,.end{display:flex;align-items:center;gap:var(--calcite-spacing-xs)}`;
+class g extends i {
+  constructor() {
+    super(...arguments), this._messages = l({ blocking: !0 }), this._endRef = n(), this._showLog = !1, this.feedbackEnabled = !1, this.logEnabled = !1, this.copyEnabled = !1, this.readAloudEnabled = !1;
+  }
+  static {
+    this.properties = { _showLog: 16, feedbackEnabled: 5, logEnabled: 5, copyEnabled: 5, readAloudEnabled: 5, message: 0 };
+  }
+  static {
+    this.styles = d;
+  }
+  loaded() {
+    this.manager.onLifecycle(() => [
+      o(() => this._showLog, () => this._scrollToEnd())
+    ]);
+  }
+  _scrollToEnd() {
+    requestAnimationFrame(() => {
+      this._endRef.value?.scrollIntoView({ behavior: "smooth", block: "end" });
+    });
+  }
+  _renderCopyButton() {
+    return !this.message?.error && this.copyEnabled ? e`<calcite-action id=action-copy icon=copy-to-clipboard scale=s @click=${async () => {
+      try {
+        const t = this.message?.content?.trim();
+        t && await navigator.clipboard.writeText(t);
+      } catch (t) {
+        c("warn", "assistant-message-footer", "Failed to copy text to clipboard", {
+          once: !0,
+          detail: { error: t }
+        });
+      }
+    }} text></calcite-action><calcite-tooltip reference-element=action-copy overlay-positioning=fixed placement=bottom><span>${this._messages.copyButtonLabel}</span></calcite-tooltip>` : null;
+  }
+  _renderLogButton() {
+    return this.message?.log?.length && this.logEnabled ? e`<calcite-action id=action-log icon=access-string-results scale=s @click=${() => this._showLog = !this._showLog} .text=${this._messages.logButtonLabel} .active=${this._showLog}></calcite-action><calcite-tooltip reference-element=action-log overlay-positioning=fixed placement=bottom><span>${this._messages.logButtonLabel}</span></calcite-tooltip>` : null;
+  }
+  _renderReadAloudButton() {
+    return e`<arcgis-assistant-message-read-aloud .message=${this.message} .readAloudEnabled=${this.readAloudEnabled}></arcgis-assistant-message-read-aloud>`;
+  }
+  _renderLog() {
+    return e`<arcgis-assistant-message-log .log=${this.message?.log} .showLog=${this._showLog} .logEnabled=${this.logEnabled}></arcgis-assistant-message-log>`;
+  }
+  _renderFeedback() {
+    return e`<arcgis-assistant-message-feedback .message=${this.message} .feedbackEnabled=${this.feedbackEnabled}></arcgis-assistant-message-feedback>`;
+  }
+  render() {
+    return e`${this._renderLog()}<div class="container"><div class="start">${this._renderCopyButton()}${this._renderLogButton()}${this._renderReadAloudButton()}<slot name=footer-actions-start></slot></div><div class="end"><slot name=footer-actions-end></slot>${this._renderFeedback()}</div></div><div ${r(this._endRef)}></div>`;
+  }
+}
+s("arcgis-assistant-message-footer", g);
+export {
+  g as ArcgisAssistantMessageFooter
+};

package/dist/components/arcgis-assistant-message-footer/index.js

@@ -0,0 +1,6 @@
+import "@esri/calcite-components/components/calcite-action";
+import "@esri/calcite-components/components/calcite-tooltip";
+import "../arcgis-assistant-message-read-aloud/index.js";
+import "../arcgis-assistant-message-log/index.js";
+import "../arcgis-assistant-message-feedback/index.js";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-loading/customElement.d.ts

@@ -0,0 +1,10 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageLoading extends LitElement {
+  /** @default false */
+  accessor loading: boolean;
+  /** @default "" */
+  accessor loadingMessage: string;
+}

package/dist/components/arcgis-assistant-message-loading/customElement.js

@@ -0,0 +1,23 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as a } from "../../chunks/runtime.js";
+import { css as e, html as s } from "lit";
+import { LitElement as i } from "@arcgis/lumina";
+const t = e`:host{display:contents}.icon{padding:var(--calcite-spacing-sm);border-radius:var(--calcite-spacing-xl);background:var(--calcite-color-brand);color:var(--calcite-color-foreground-1)}.loading-container{display:flex;flex-direction:column;gap:var(--calcite-spacing-sm);padding:0 var(--calcite-spacing-sm)}.loading{display:flex;align-items:center;gap:var(--calcite-spacing-sm)}.text{font-style:italic;word-wrap:break-word;word-break:break-all;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:1;line-clamp:1;-webkit-box-orient:vertical}.skeleton-block{display:flex;flex-direction:column;gap:var(--calcite-spacing-sm);width:100%}.skeleton-text{display:block;height:.95em;border-radius:var(--calcite-border-radius);background:linear-gradient(90deg,color-mix(in srgb,var(--calcite-color-foreground-2) 65%,transparent),color-mix(in srgb,var(--calcite-color-foreground-3) 85%,transparent),color-mix(in srgb,var(--calcite-color-foreground-2) 65%,transparent));background-size:200% 100%;animation:assistant-message-loading-shimmer 1.2s ease-in-out infinite;width:85%}.skeleton-text:last-child{width:70%}@keyframes assistant-message-loading-shimmer{0%{background-position:-150% 0}to{background-position:150% 0}}@media(prefers-reduced-motion){.skeleton-text{animation:none}}`;
+class o extends i {
+  constructor() {
+    super(...arguments), this.loading = !1, this.loadingMessage = "";
+  }
+  static {
+    this.properties = { loading: 5, loadingMessage: 1 };
+  }
+  static {
+    this.styles = t;
+  }
+  render() {
+    return this.loading ? s`<arcgis-assistant-message footer-disabled><slot name=icon slot=icon><calcite-icon class="icon" icon=effects scale=s></calcite-icon></slot><slot name=content slot=content><div class="loading-container"><div class="loading"><calcite-loader label=loading inline></calcite-loader><div class="text">${this.loadingMessage}</div></div><div class="skeleton-block"><span class="skeleton-text"></span><span class="skeleton-text"></span></div></div></slot></arcgis-assistant-message>` : null;
+  }
+}
+a("arcgis-assistant-message-loading", o);
+export {
+  o as ArcgisAssistantMessageLoading
+};

package/dist/components/arcgis-assistant-message-loading/index.js

@@ -0,0 +1,4 @@
+import "../arcgis-assistant-message/index.js";
+import "@esri/calcite-components/components/calcite-icon";
+import "@esri/calcite-components/components/calcite-loader";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-log/customElement.d.ts

@@ -0,0 +1,11 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageLog extends LitElement {
+  accessor log: string[] | undefined;
+  /** @default false */
+  accessor logEnabled: boolean;
+  /** @default false */
+  accessor showLog: boolean;
+}

package/dist/components/arcgis-assistant-message-log/customElement.js

@@ -0,0 +1,29 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as i } from "../../chunks/runtime.js";
+import { css as o, html as a } from "lit";
+import { LitElement as e } from "@arcgis/lumina";
+import { unsafeHTML as c } from "lit/directives/unsafe-html.js";
+import { p as r } from "../../chunks/converterUtils.js";
+const n = o`.container{border-radius:var(--calcite-border-radius);margin-bottom:var(--calcite-spacing-md)}.block{margin:0;background-color:var(--calcite-color-foreground-1);width:100%;max-height:300px;overflow:auto}.entry{margin-left:var(--calcite-spacing-sm);padding:var(--calcite-spacing-xxs) var(--calcite-spacing-lg);border-left:1px solid var(--calcite-color-border-1)}`;
+class l extends e {
+  constructor() {
+    super(...arguments), this.logEnabled = !1, this.showLog = !1;
+  }
+  static {
+    this.properties = { logEnabled: 5, showLog: 5, log: 0 };
+  }
+  static {
+    this.styles = n;
+  }
+  render() {
+    return this.log?.length && this.showLog && this.logEnabled ? a`<div class="container"><div class="block"><calcite-accordion appearance=transparent icon-position=start icon-type=chevron scale=s>${this.log.map((s) => {
+      const t = s.includes(`
+`) || s.length > 70;
+      return a`<calcite-accordion-item .heading=${t ? `${s.substring(0, 70)}...` : s} .expanded=${t}><div class="entry">${t ? c(r(s)) : null}</div></calcite-accordion-item>`;
+    })}</calcite-accordion></div></div>` : null;
+  }
+}
+i("arcgis-assistant-message-log", l);
+export {
+  l as ArcgisAssistantMessageLog
+};

package/dist/components/arcgis-assistant-message-log/index.js

@@ -0,0 +1,3 @@
+import "@esri/calcite-components/components/calcite-accordion";
+import "@esri/calcite-components/components/calcite-accordion-item";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-read-aloud/customElement.d.ts

@@ -0,0 +1,19 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { AssistantMessage } from "../arcgis-assistant/types.js";
+import type { T9nMeta } from "@arcgis/lumina/controllers";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageReadAloud extends LitElement {
+  /** @internal */
+  protected _messages: {
+      readAloudButtonLabel: string;
+      stopReadingButtonLabel: string;
+  } & T9nMeta<{
+      readAloudButtonLabel: string;
+      stopReadingButtonLabel: string;
+  }>;
+  accessor message: AssistantMessage | undefined;
+  /** @default false */
+  accessor readAloudEnabled: boolean;
+}

package/dist/components/arcgis-assistant-message-read-aloud/customElement.js

@@ -0,0 +1,104 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as u } from "../../chunks/runtime.js";
+import { css as p, html as h } from "lit";
+import { watch as m } from "@arcgis/core/core/reactiveUtils.js";
+import { LitElement as _ } from "@arcgis/lumina";
+import { u as g } from "../../chunks/useT9n.js";
+import f from "@arcgis/core/core/Accessor.js";
+import { property as d, subclass as y } from "@arcgis/core/core/accessorSupport/decorators.js";
+const A = p``;
+var C = Object.defineProperty, S = Object.getOwnPropertyDescriptor, c = (e, s, n, i) => {
+  for (var r = i > 1 ? void 0 : i ? S(s, n) : s, t = e.length - 1, a; t >= 0; t--)
+    (a = e[t]) && (r = (i ? a(s, n, r) : a(r)) || r);
+  return i && r && C(s, n, r), r;
+};
+function l() {
+  return typeof window > "u" ? null : window;
+}
+let o = class extends f {
+  constructor() {
+    super(...arguments), this._utterance = null, this.state = "idle", this.supported = o.isSupported();
+  }
+  destroy() {
+    this.stop(), super.destroy();
+  }
+  start(e) {
+    const s = e.trim(), n = l(), i = n?.SpeechSynthesisUtterance, r = n?.speechSynthesis;
+    if (this._set("supported", o.isSupported(n)), !s || !i || !r)
+      return;
+    this.stop();
+    const t = new i(s);
+    t.rate = 0.9, t.pitch = 1.1, t.volume = 1, t.onend = () => {
+      this._utterance === t && this._reset();
+    }, t.onerror = () => {
+      this._utterance === t && this._reset();
+    };
+    try {
+      r.speak(t), this._utterance = t, this._set("state", "playing");
+    } catch {
+      t.onend = null, t.onerror = null, this._reset();
+    }
+  }
+  stop() {
+    const e = l(), s = e?.speechSynthesis;
+    if (this._set("supported", o.isSupported(e)), s)
+      try {
+        (s.speaking || s.pending) && s.cancel();
+      } catch {
+      }
+    this._reset();
+  }
+  toggle(e) {
+    if (this.state === "playing") {
+      this.stop();
+      return;
+    }
+    this.start(e);
+  }
+  static isSupported(e = l()) {
+    return !!e?.speechSynthesis && typeof e.SpeechSynthesisUtterance == "function";
+  }
+  _reset() {
+    this._utterance && (this._utterance.onend = null, this._utterance.onerror = null), this._utterance = null, this._set("state", "idle");
+  }
+};
+c([
+  d({ readOnly: !0 })
+], o.prototype, "state", 2);
+c([
+  d({ readOnly: !0 })
+], o.prototype, "supported", 2);
+o = c([
+  y("ReadAloudController")
+], o);
+class w extends _ {
+  constructor() {
+    super(...arguments), this._messages = g({ blocking: !0 }), this._readAloudController = new o(), this.readAloudEnabled = !1;
+  }
+  static {
+    this.properties = { readAloudEnabled: 5, message: 0 };
+  }
+  static {
+    this.styles = A;
+  }
+  loaded() {
+    this.manager.onLifecycle(() => [
+      m(() => this._readAloudController.state, () => this.requestUpdate(), { initial: !0 }),
+      {
+        remove: () => {
+          this._readAloudController.stop();
+        }
+      }
+    ]);
+  }
+  _toggleReadAloud() {
+    this._readAloudController.toggle(this.message?.content ?? "");
+  }
+  render() {
+    return this.readAloudEnabled && !this.message?.error && this.message?.content?.trim() && this._readAloudController.supported ? h`<calcite-action id=action-read-aloud .icon=${this._readAloudController.state === "playing" ? "sound-off" : "sound"} scale=s .active=${this._readAloudController.state === "playing"} @click=${() => this._toggleReadAloud()} text></calcite-action><calcite-tooltip reference-element=action-read-aloud overlay-positioning=fixed placement=bottom><span>${this._readAloudController.state === "playing" ? this._messages.stopReadingButtonLabel : this._messages.readAloudButtonLabel}</span></calcite-tooltip>` : null;
+  }
+}
+u("arcgis-assistant-message-read-aloud", w);
+export {
+  w as ArcgisAssistantMessageReadAloud
+};

package/dist/components/arcgis-assistant-message-read-aloud/index.js

@@ -0,0 +1,3 @@
+import "@esri/calcite-components/components/calcite-action";
+import "@esri/calcite-components/components/calcite-tooltip";
+export * from "./customElement.js";

package/dist/components/arcgis-assistant-message-text/customElement.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+
+/** @internal */
+export abstract class ArcgisAssistantMessageText extends LitElement {
+  accessor content: string | undefined;
+}

package/dist/components/arcgis-assistant-message-text/customElement.js

@@ -0,0 +1,22 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as t } from "../../chunks/runtime.js";
+import { css as e, html as c } from "lit";
+import { LitElement as a } from "@arcgis/lumina";
+import { unsafeHTML as o } from "lit/directives/unsafe-html.js";
+import { p as r } from "../../chunks/converterUtils.js";
+const i = e`.container{color:var(--calcite-color-text-1)}.content>*{margin:0}.content>*+*{margin-block-start:var(--calcite-spacing-sm)}.content :is(ol,ul){padding-inline-start:var(--calcite-spacing-lg)}.content>calcite-table{display:block;max-width:100%}.content pre{background-color:var(--calcite-color-foreground-1);padding:var(--calcite-spacing-sm);border-radius:var(--calcite-border-radius);color:var(--calcite-color-text-1);direction:ltr;max-width:100%;overflow:auto}.content pre code{display:block;white-space:pre;font-family:var(--calcite-code-family)}`;
+class s extends a {
+  static {
+    this.properties = { content: 1 };
+  }
+  static {
+    this.styles = i;
+  }
+  render() {
+    return c`<div class="container"><div class="content">${o(r(this.content))}</div></div>`;
+  }
+}
+t("arcgis-assistant-message-text", s);
+export {
+  s as ArcgisAssistantMessageText
+};

package/dist/components/arcgis-assistant-message-text/index.js

@@ -0,0 +1 @@
+export * from "./customElement.js";

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

@@ -3,14 +3,14 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
 
 /**
- * The Navigation Agent component enables the end user to navigate to different areas of a web map.
- * It allows you to type in a place name, address, or layer title to navigate to the desired location.
- * Currently, this is only scoped to navigation within a 2D map view.
+ * The Navigation Agent enables the end user to navigate to different areas of a web map. See the list
+ * of capabilities below for more details.
  *
  * 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-navigation-agent></arcgis-assistant-navigation-agent>
  * </arcgis-assistant>
  * ```
@@ -21,14 +21,61 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * assistant.appendChild(navigationAgent);
  * ```
  *
+ * Once added to the assistant, the agent is loaded and ready to receive user messages related to navigation.
+ *
+ * ### Capabilities
+ *
+ * The navigation agent provides the following capabilities related to map navigation:
+ *
+ * - **Geocoding** - Navigate to an address using Esri's World Geocoding Service.
+ * - **Go to extent** - Navigate to the extent of a bookmark in the map, the home extent of the web map,
+ *   or the extent of a layer.
+ * - **Go to features** - Navigate to a specified feature or set of features.
+ * - **Go to viewpoint** - Navigate to a specified viewpoint, which can include center, zoom, and/or
+ *   rotation.
+ *
+ * ### Example questions
+ *
+ * The following are example questions a user can ask within the bounds of the navigation agent:
+ *
+ * - "Go to the Golden Gate Bridge"
+ * - "Zoom to a 1 to 24,000 scale"
+ * - "Zoom in"
+ * - "Go to the parks layer"
+ *
+ * The following are examples of the types of questions that fall outside the bounds of the
+ * navigation agent and should therefore be avoided:
+ *
+ * - "Rotate the map 45 degrees" (this capability is not currently supported but may be in the future)
+ * - "Make this map 3D and tilt the view to a 45 degree angle" (3D navigation is currently not supported)
+ * - "Where am I?" (the navigation agent does not have access to the user's location)
+ *
+ * > 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 ArcgisAssistantNavigationAgent 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 navigation agent. Currently,
+   * this is only scoped to `arcgis-map` elements. This shows the navigation agent which map on which to
+   * perform navigation actions. This is required for the navigation agent to function properly.
+   *
+   * 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-navigation-agent reference-element="my-map"></arcgis-assistant-navigation-agent>
+   * </arcgis-assistant>
+   * ```
    */
   accessor referenceElement: ArcgisMap | string | undefined;
 }

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

@@ -2,7 +2,7 @@
 import { c as t } from "../../chunks/runtime.js";
 import { LitElement as i } from "@arcgis/lumina";
 import { NavigationAgent as s } from "@arcgis/ai-agents";
-import { r as a, i as e } from "../../chunks/utils.js";
+import { r as a, a as e } from "../../chunks/utils.js";
 class n extends i {
   constructor() {
     super(...arguments), this.agent = s;

package/dist/components/arcgis-assistant-speech-input/customElement.d.ts

@@ -0,0 +1,31 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { VoiceInputDraftChangeDetail, VoiceInputErrorCode, VoiceInputMode, VoiceInputTranscriptDetail, VoiceInputTranscriptionStreamChunkDetail } from "./support/types.js";
+
+/** @internal */
+export abstract class ArcgisAssistantSpeechInput extends LitElement {
+  /** @default false */
+  accessor awaitingResponse: boolean;
+  /** @default "" */
+  accessor inputValue: string;
+  accessor language: string | undefined;
+  /** @default "web-speech" */
+  accessor mode: VoiceInputMode;
+  clearDraftSession(): void;
+  readonly arcgisVoiceInputDraftChange: import("@arcgis/lumina").TargetedEvent<this, VoiceInputDraftChangeDetail>;
+  readonly arcgisVoiceInputError: import("@arcgis/lumina").TargetedEvent<this, { errorCode: VoiceInputErrorCode; }>;
+  readonly arcgisVoiceInputInterimTranscription: import("@arcgis/lumina").TargetedEvent<this, VoiceInputTranscriptDetail>;
+  readonly arcgisVoiceInputStart: import("@arcgis/lumina").TargetedEvent<this, void>;
+  readonly arcgisVoiceInputStop: import("@arcgis/lumina").TargetedEvent<this, void>;
+  readonly arcgisVoiceInputTranscription: import("@arcgis/lumina").TargetedEvent<this, VoiceInputTranscriptDetail>;
+  readonly arcgisVoiceInputTranscriptionStreamChunk: import("@arcgis/lumina").TargetedEvent<this, VoiceInputTranscriptionStreamChunkDetail>;
+  readonly "@eventTypes": {
+    arcgisVoiceInputDraftChange: ArcgisAssistantSpeechInput["arcgisVoiceInputDraftChange"]["detail"];
+    arcgisVoiceInputError: ArcgisAssistantSpeechInput["arcgisVoiceInputError"]["detail"];
+    arcgisVoiceInputInterimTranscription: ArcgisAssistantSpeechInput["arcgisVoiceInputInterimTranscription"]["detail"];
+    arcgisVoiceInputStart: ArcgisAssistantSpeechInput["arcgisVoiceInputStart"]["detail"];
+    arcgisVoiceInputStop: ArcgisAssistantSpeechInput["arcgisVoiceInputStop"]["detail"];
+    arcgisVoiceInputTranscription: ArcgisAssistantSpeechInput["arcgisVoiceInputTranscription"]["detail"];
+    arcgisVoiceInputTranscriptionStreamChunk: ArcgisAssistantSpeechInput["arcgisVoiceInputTranscriptionStreamChunk"]["detail"];
+  };
+}