@tylertech/forge-ai-react 0.4.1 → 0.5.0

package/dist/ForgeAiChatbot.d.ts

@@ -0,0 +1,144 @@
+import React from "react";
+import { ForgeAiChatbot as ForgeAiChatbotElement } from "@tylertech/forge-ai/ai-chatbot";
+
+export type { ForgeAiChatbotElement };
+
+export interface ForgeAiChatbotProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  showExpandButton?: boolean;
+
+  /** undefined */
+  showMinimizeButton?: boolean;
+
+  /** undefined */
+  expanded?: boolean;
+
+  /** undefined */
+  enableReactions?: boolean;
+
+  /** undefined */
+  fileUpload?: ForgeAiChatbotElement["fileUpload"];
+
+  /** undefined */
+  voiceInput?: ForgeAiChatbotElement["voiceInput"];
+
+  /** undefined */
+  placeholder?: ForgeAiChatbotElement["placeholder"];
+
+  /** undefined */
+  minimizeIcon?: ForgeAiChatbotElement["minimizeIcon"];
+
+  /** The title text to display in the header (default: 'AI Assistant') */
+  titleText?: ForgeAiChatbotElement["titleText"];
+
+  /** Controls the heading level for the title content (default: 2) */
+  headingLevel?: ForgeAiChatbotElement["headingLevel"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** Fired when adapter connects */
+  onForgeAiChatbotConnected?: (event: CustomEvent<CustomEvent<void>>) => void;
+
+  /** Fired when adapter disconnects */
+  onForgeAiChatbotDisconnected?: (
+    event: CustomEvent<CustomEvent<void>>,
+  ) => void;
+
+  /** Fired when user sends a message */
+  onForgeAiChatbotMessageSent?: (
+    event: CustomEvent<CustomEvent<ForgeAiChatbotMessageEventData>>,
+  ) => void;
+
+  /** Fired when assistant message is complete */
+  onForgeAiChatbotMessageReceived?: (
+    event: CustomEvent<CustomEvent<ForgeAiChatbotMessageEventData>>,
+  ) => void;
+
+  /** Fired when a tool needs to be executed */
+  onForgeAiChatbotToolCall?: (
+    event: CustomEvent<CustomEvent<ForgeAiChatbotToolCallEventData>>,
+  ) => void;
+
+  /** Fired when an error occurs */
+  onForgeAiChatbotError?: (
+    event: CustomEvent<CustomEvent<ForgeAiChatbotErrorEventData>>,
+  ) => void;
+
+  /** Fired when header expand button is clicked */
+  onForgeAiChatbotExpand?: (event: CustomEvent<CustomEvent<void>>) => void;
+
+  /** Fired when header minimize button is clicked */
+  onForgeAiChatbotMinimize?: (event: CustomEvent<CustomEvent<void>>) => void;
+
+  /** Fired when header clear option is selected (cancelable, prevents clearMessages() if default prevented) */
+  onForgeAiChatbotClear?: (event: CustomEvent<CustomEvent<void>>) => void;
+
+  /** Fired when header info option is selected */
+  onForgeAiChatbotInfo?: (event: CustomEvent<CustomEvent<void>>) => void;
+}
+
+/**
+ * A complete, self-contained AI chatbot component that implements the AG-UI protocol using an adapter pattern.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **forge-ai-chatbot-connected** - Fired when adapter connects
+ * - **forge-ai-chatbot-disconnected** - Fired when adapter disconnects
+ * - **forge-ai-chatbot-message-sent** - Fired when user sends a message
+ * - **forge-ai-chatbot-message-received** - Fired when assistant message is complete
+ * - **forge-ai-chatbot-tool-call** - Fired when a tool needs to be executed
+ * - **forge-ai-chatbot-error** - Fired when an error occurs
+ * - **forge-ai-chatbot-expand** - Fired when header expand button is clicked
+ * - **forge-ai-chatbot-minimize** - Fired when header minimize button is clicked
+ * - **forge-ai-chatbot-clear** - Fired when header clear option is selected (cancelable, prevents clearMessages() if default prevented)
+ * - **forge-ai-chatbot-info** - Fired when header info option is selected
+ *
+ * ### **Methods:**
+ *  - **clearMessages(): _void_** - Clears all messages from the chat history.
+ * - **getMessages(): __** - Gets the current message history.
+ * - **setMessages(messages: _ChatMessage[]_): _void_** - Sets the message history. Useful for restoring conversation state.
+ * - **sendMessage(content: _string_, files: _File[]_): _Promise<void>_** - Programmatically sends a message as the user.
+ * - **abort(): _void_** - Aborts the current streaming response.
+ * - **scrollToBottom({ behavior }: _{ behavior?: ScrollBehavior }_): _Promise<void>_** - Scrolls the chat interface to the bottom.
+ * - **getThreadState(): __** - Gets the complete serializable thread state including threadId and messages.
+ * - **setThreadState(state: _ThreadState_): _void_** - Restores thread state from a serialized ThreadState object.
+ *
+ * ### **Slots:**
+ *  - **header** - Slot for custom header content
+ * - **empty-state** - Slot for custom empty state content (overrides default suggestions)
+ */
+export const ForgeAiChatbot: React.ForwardRefExoticComponent<ForgeAiChatbotProps>;

package/dist/ForgeAiChatbot.js

@@ -0,0 +1,92 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "@tylertech/forge-ai/ai-chatbot";
+import { useEventListener } from "./react-utils.js";
+
+export const ForgeAiChatbot = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    showExpandButton,
+    showMinimizeButton,
+    expanded,
+    enableReactions,
+    fileUpload,
+    voiceInput,
+    placeholder,
+    minimizeIcon,
+    titleText,
+    headingLevel,
+    ...filteredProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-connected",
+    props.onForgeAiChatbotConnected,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-disconnected",
+    props.onForgeAiChatbotDisconnected,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-message-sent",
+    props.onForgeAiChatbotMessageSent,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-message-received",
+    props.onForgeAiChatbotMessageReceived,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-tool-call",
+    props.onForgeAiChatbotToolCall,
+  );
+  useEventListener(ref, "forge-ai-chatbot-error", props.onForgeAiChatbotError);
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-expand",
+    props.onForgeAiChatbotExpand,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-chatbot-minimize",
+    props.onForgeAiChatbotMinimize,
+  );
+  useEventListener(ref, "forge-ai-chatbot-clear", props.onForgeAiChatbotClear);
+  useEventListener(ref, "forge-ai-chatbot-info", props.onForgeAiChatbotInfo);
+
+  return React.createElement(
+    "forge-ai-chatbot",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      "file-upload": props.fileUpload || props["file-upload"],
+      "voice-input": props.voiceInput || props["voice-input"],
+      placeholder: props.placeholder,
+      "minimize-icon": props.minimizeIcon || props["minimize-icon"],
+      "title-text": props.titleText || props["title-text"],
+      "heading-level": props.headingLevel || props["heading-level"],
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      "show-expand-button": props.showExpandButton ? true : undefined,
+      "show-minimize-button": props.showMinimizeButton ? true : undefined,
+      expanded: props.expanded ? true : undefined,
+      "enable-reactions": props.enableReactions ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/ForgeAiChatbotToolCall.d.ts

@@ -0,0 +1,57 @@
+import React from "react";
+import {
+  ForgeAiChatbotToolCall as ForgeAiChatbotToolCallElement,
+  CustomEvent,
+} from "@tylertech/forge-ai/ai-chatbot";
+
+export type { ForgeAiChatbotToolCallElement, CustomEvent };
+
+export interface ForgeAiChatbotToolCallProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** undefined */
+  onForgeAiMessageThreadScrollRequest?: (event: CustomEvent) => void;
+}
+
+/**
+ *
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **forge-ai-message-thread-scroll-request**
+ */
+export const ForgeAiChatbotToolCall: React.ForwardRefExoticComponent<ForgeAiChatbotToolCallProps>;

package/dist/ForgeAiChatbotToolCall.js

@@ -0,0 +1,36 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "@tylertech/forge-ai/ai-chatbot";
+import { useEventListener } from "./react-utils.js";
+
+export const ForgeAiChatbotToolCall = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+
+  /** Event listeners - run once */
+  useEventListener(
+    ref,
+    "forge-ai-message-thread-scroll-request",
+    props.onForgeAiMessageThreadScrollRequest,
+  );
+
+  return React.createElement(
+    "forge-ai-chatbot-tool-call",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...props,
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/ForgeAiConfirmationPrompt.d.ts

@@ -0,0 +1,74 @@
+import React from "react";
+import { ForgeAiConfirmationPrompt as ForgeAiConfirmationPromptElement } from "@tylertech/forge-ai/ai-confirmation-prompt";
+
+export type { ForgeAiConfirmationPromptElement };
+
+export interface ForgeAiConfirmationPromptProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  text?: ForgeAiConfirmationPromptElement["text"];
+
+  /** undefined */
+  confirmText?: ForgeAiConfirmationPromptElement["confirmText"];
+
+  /** undefined */
+  denyText?: ForgeAiConfirmationPromptElement["denyText"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: any;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** Fired when user confirms the prompt */
+  onForgeAiConfirmationPromptConfirm?: (
+    event: CustomEvent<CustomEvent<void>>,
+  ) => void;
+
+  /** Fired when user denies the prompt */
+  onForgeAiConfirmationPromptDeny?: (
+    event: CustomEvent<CustomEvent<void>>,
+  ) => void;
+}
+
+/**
+ * Displays a confirmation UI for requiring human approval.
+ * ---
+ *
+ *
+ * ### **Events:**
+ *  - **forge-ai-confirmation-prompt-confirm** - Fired when user confirms the prompt
+ * - **forge-ai-confirmation-prompt-deny** - Fired when user denies the prompt
+ */
+export const ForgeAiConfirmationPrompt: React.ForwardRefExoticComponent<ForgeAiConfirmationPromptProps>;

package/dist/ForgeAiConfirmationPrompt.js

@@ -0,0 +1,46 @@
+import React, { forwardRef, useRef, useEffect } from "react";
+import "@tylertech/forge-ai/ai-confirmation-prompt";
+import { useEventListener } from "./react-utils.js";
+
+export const ForgeAiConfirmationPrompt = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const { disabled, text, confirmText, denyText, ...filteredProps } = props;
+
+  /** Event listeners - run once */
+  useEventListener(
+    ref,
+    "forge-ai-confirmation-prompt-confirm",
+    props.onForgeAiConfirmationPromptConfirm,
+  );
+  useEventListener(
+    ref,
+    "forge-ai-confirmation-prompt-deny",
+    props.onForgeAiConfirmationPromptDeny,
+  );
+
+  return React.createElement(
+    "forge-ai-confirmation-prompt",
+    {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      ...filteredProps,
+      text: props.text,
+      "confirm-text": props.confirmText || props["confirm-text"],
+      "deny-text": props.denyText || props["deny-text"],
+      class: props.className,
+      exportparts: props.exportparts,
+      for: props.htmlFor,
+      part: props.part,
+      tabindex: props.tabIndex,
+      disabled: props.disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/ForgeAiDialog.d.ts

@@ -3,22 +3,21 @@ import { ForgeAiDialog as ForgeAiDialogElement } from "@tylertech/forge-ai/ai-di
 
 export type { ForgeAiDialogElement };
 
-export interface ForgeAiDialogProps
-  extends Pick<
-    React.AllHTMLAttributes<HTMLElement>,
-    | "children"
-    | "dir"
-    | "hidden"
-    | "id"
-    | "lang"
-    | "slot"
-    | "style"
-    | "title"
-    | "translate"
-    | "onClick"
-    | "onFocus"
-    | "onBlur"
-  > {
+export interface ForgeAiDialogProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
   /** Indicates whether the dialog is open. */
   open?: boolean;
 

package/dist/ForgeAiDropdownMenu.d.ts

@@ -6,22 +6,21 @@ import {
 
 export type { ForgeAiDropdownMenuElement, CustomEvent };
 
-export interface ForgeAiDropdownMenuProps
-  extends Pick<
-    React.AllHTMLAttributes<HTMLElement>,
-    | "children"
-    | "dir"
-    | "hidden"
-    | "id"
-    | "lang"
-    | "slot"
-    | "style"
-    | "title"
-    | "translate"
-    | "onClick"
-    | "onFocus"
-    | "onBlur"
-  > {
+export interface ForgeAiDropdownMenuProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
   /** Whether the dropdown is open. */
   open?: boolean;
 
@@ -43,6 +42,10 @@ For multi selection: string array
 For none mode: null */
   value?: ForgeAiDropdownMenuElement["value"];
 
+  /** The placement of the popover relative to the trigger button.
+Only applies to root-level menus; submenus always use 'right-start'. */
+  popoverPlacement?: ForgeAiDropdownMenuElement["popoverPlacement"];
+
   /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
   className?: string;
 

package/dist/ForgeAiDropdownMenu.js

@@ -4,8 +4,15 @@ import { useEventListener } from "./react-utils.js";
 
 export const ForgeAiDropdownMenu = forwardRef((props, forwardedRef) => {
   const ref = useRef(null);
-  const { open, disabled, variant, selectionMode, value, ...filteredProps } =
-    props;
+  const {
+    open,
+    disabled,
+    variant,
+    selectionMode,
+    value,
+    popoverPlacement,
+    ...filteredProps
+  } = props;
 
   /** Event listeners - run once */
   useEventListener(
@@ -30,6 +37,7 @@ export const ForgeAiDropdownMenu = forwardRef((props, forwardedRef) => {
       variant: props.variant,
       "selection-mode": props.selectionMode || props["selection-mode"],
       value: props.value,
+      "popover-placement": props.popoverPlacement || props["popover-placement"],
       class: props.className,
       exportparts: props.exportparts,
       for: props.htmlFor,

package/dist/ForgeAiDropdownMenuItem.d.ts

@@ -3,22 +3,21 @@ import { ForgeAiDropdownMenuItem as ForgeAiDropdownMenuItemElement } from "@tyle
 
 export type { ForgeAiDropdownMenuItemElement };
 
-export interface ForgeAiDropdownMenuItemProps
-  extends Pick<
-    React.AllHTMLAttributes<HTMLElement>,
-    | "children"
-    | "dir"
-    | "hidden"
-    | "id"
-    | "lang"
-    | "slot"
-    | "style"
-    | "title"
-    | "translate"
-    | "onClick"
-    | "onFocus"
-    | "onBlur"
-  > {
+export interface ForgeAiDropdownMenuItemProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
   /** Whether this menu item is selected. */
   selected?: boolean;
 

package/dist/ForgeAiDropdownMenuItemGroup.d.ts

@@ -3,22 +3,21 @@ import { ForgeAiDropdownMenuItemGroup as ForgeAiDropdownMenuItemGroupElement } f
 
 export type { ForgeAiDropdownMenuItemGroupElement };
 
-export interface ForgeAiDropdownMenuItemGroupProps
-  extends Pick<
-    React.AllHTMLAttributes<HTMLElement>,
-    | "children"
-    | "dir"
-    | "hidden"
-    | "id"
-    | "lang"
-    | "slot"
-    | "style"
-    | "title"
-    | "translate"
-    | "onClick"
-    | "onFocus"
-    | "onBlur"
-  > {
+export interface ForgeAiDropdownMenuItemGroupProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
   /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
   className?: string;