@stack-spot/ai-chat-widget 0.11.0 → 1.0.0-dev.1768324407795

package/src/right-panel/hooks.tsx

@@ -1,6 +1,7 @@
 import { useContext, useMemo } from 'react'
 import { DefaultPanel } from './DefaultPanel'
 import { RightPanelContext } from './RightPanelProvider'
+import { panelAnimationTime } from './constants'
 
 interface RightPanelOptions {
   title: React.ReactNode,
@@ -8,11 +9,17 @@ interface RightPanelOptions {
   onClose?: () => void,
 }
 
+/**
+ * @returns teh current content of the right panel
+ */
 export function useRightPanelContent() {
   const { content } = useContext(RightPanelContext)
   return content
 }
 
+/**
+ * Opens, closes or checks the visibility of the right panel.
+ */
 export function useRightPanel() {
   const ctx = useContext(RightPanelContext)
   const { panel, chatWindow, setContent } = ctx
@@ -35,7 +42,7 @@ export function useRightPanel() {
       ctx.onCloseNext.current?.()
       setTimeout(() => {
         setContent(null)
-      }, 300)
+      }, panelAnimationTime)
     }
 
     function isOpen() {

package/src/state/ChatEntry.ts

@@ -1,14 +1,26 @@
-import { ColorPaletteName } from '@stack-spot/portal-theme'
+import { ChatStep, HypothesisPMAgent, OpportunitiesPMAgent, PrfaqPMAgent } from '@stack-spot/portal-network'
+import { ColorPaletteName, ColorSchemeName } from '@stack-spot/portal-theme'
 import { pull } from 'lodash'
-import { LabeledWithImage } from './types'
+import { LabeledAgent } from './types'
+
+export interface ActionDataClick {
+  name?: string,
+  value?: string[],
+}
 
 export interface SerializableAction {
+  /**
+   * The text for the button or anchor.
+   */
   title: string,
+  /**
+   * Links open new tabs with urls, while commands send text commands in the chat as if they were written by the user.
+   */
   type: 'link' | 'command',
   /**
-   * The URL if the action is a link or a chat command otherwise (/command).
+   * The URL if the action is a link. The content of the user message otherwise.
    */
-  exec: string,
+  exec?: string,
 }
 
 export interface ChatAction extends SerializableAction {
@@ -16,6 +28,26 @@ export interface ChatAction extends SerializableAction {
    * @default primary
    */
   appearance?: 'primary' | 'secondary',
+  /**
+   * @default inverse
+   */
+  colorScheme?: ColorSchemeName,
+  /**
+   * @default false
+   */
+  hideWhenNotLast?: boolean,
+  /**
+   * @default false
+   */
+  disabled?: boolean,
+  /**
+   * @default button
+   */
+  buttonType?: 'submit' | 'button',
+  /**
+  * @default lg
+  */
+  size?: 'lg' | 'md' | 'sm',
 }
 
 export interface KnowledgeSource {
@@ -25,24 +57,154 @@ export interface KnowledgeSource {
   documentId: string,
 }
 
+export interface ChatTool {
+  id: string,
+  image?: string,
+  name: string,
+  description: string,
+}
+
+export interface UploadedFile {
+  id: string,
+  name: string,
+  image?: string,
+}
+
 export interface TextChatEntry {
-  type: 'text' | 'md',
+  /**
+   * "text" for simple unformatted paragraphs. "md" for markdown. 
+   * "input-text" for text inputs, 'input-radio' and "input-checkbox" for radio and checkbox inputs,
+   * "input-phone" for phone formatted inputs and "button-list" for a list of buttons in which only one is selected
+   */
+  type: 'text' | 'md' | 'input-text' | 'input-radio' | 'button-list' | 'input-checkbox' | 'input-phone',
+  /**
+   * If the message was typed by the AI agent (bot), the user or the system (not currently in use).
+   */
   agentType: 'bot' | 'user' | 'system',
+  /**
+   * A set of buttons to go after the message.
+   */
   actions?: ChatAction[],
+  /**
+   * The content of the message.
+   */
   content: string,
+  /**
+   * The actual data to send as a message. This is the "content" if not provided.
+   * 
+   * Useful for displaying a text in the chat, via "content", but sending something different to the backend.
+   * 
+   * Serialization: if none of your interceptors return false, this will be converted to a JSON in the last interceptor (sendMessage).
+   * 
+   * Attention: this is ignored by quick commands, which will always use "content".
+   */
+  data?: any,
+  /**
+   * A content that is not shown to the user, it is used only to share data.
+   * 
+   * This is used solely by the onboarding feature (checkboxes and radio button), implemented in the AI Portal. Maybe it shouldn't be
+   * implemented here. This needs a review (fixme).
+   * 
+   * This has been implemented because the message rendered is different than the message we wanted to send to the backend.
+   * 
+   * @deprecated prefer "data" instead.
+   */
+  hiddenContent?: string[],
+  /**
+   * The knowledge sources used to create the message.
+   */
   knowledgeSources?: KnowledgeSource[],
+  /**
+   * The date and time of the message. ISO string.
+   */
   updated?: string,
-  agent?: LabeledWithImage,
+  /**
+   * The agent who wrote the message. Undefined for the agentType is "user".
+   */
+  agent?: LabeledAgent,
+  /**
+   * The unique identifier of the message.
+   */
   messageId?: string,
+  /**
+   * If this is set, only an error message is rendered.
+   */
   error?: string,
+  /**
+   * A series of badges to display before the content.
+   */
   badges?: { color?: ColorPaletteName, label: string }[],
+  /**
+   * Whether or not to show this chat entry as a card.
+   */
   card?: boolean,
+  /**
+   * This entry may contain steps. If so, specify them in this array.
+   */
+  steps?: ChatStep[],
+  /**
+   * If any tool was used to generate the response, its id is returned in this list.
+   */
+  tools?: string[],
+  /**
+  * If opportunities exists in pm agent, its send in this list.
+  */
+  opportunities?: OpportunitiesPMAgent[],
+  /**
+  * If hypothesis exists in pm agent, its send in this list.
+  */
+  hypothesis?: HypothesisPMAgent[],
+  /**
+  * If prfaq exists in pm agent, its send in this object.
+  */
+  prfaq?: PrfaqPMAgent,
+  /*
+   * Options for radio, checkbox or button type.
+   */
+  options?: { color?: ColorSchemeName, label: string, value?: string, hasInput?: boolean }[],
+  /**
+   * Name to be used in input type fields.
+   */
+  name?: string,
+  /**
+   * Whether or not a input field is required.
+   */
+  required?: boolean,
+  /**
+   * The validations of input fields.
+   */
+  validations?: {
+    minLength?: number,
+    maxLength?: number,
+    pattern?: string,
+  },
+  /**
+   * Valid for input types.
+   */
+  initialValue?: string[],
+  /**
+   * If this chat entry contains any uploaded file, these are the files being uploaded along the message.
+   */
+  upload?: UploadedFile[],
+  /**
+   * True if the entry is done streaming, false otherwise. Undefined may be used when streaming info is not available.
+   */
+  done?: boolean,
+  /**
+   * True if, at some point, this entry had a planning stage (related to tools).
+   */
+  hasPlanning?: boolean,
 }
 
 type ChatEntryListener = (value: TextChatEntry) => void
 
+// this id is unique for each message and used for rendering. The `messageId`, which comes from the backend, is not always available and, 
+// therefore, can't be used for this purpose.
 let nextId = 0
 
+/**
+ * A message (entry) in the chat.
+ */
 export class ChatEntry {
   readonly id: number
   private value: TextChatEntry
@@ -50,24 +212,37 @@ export class ChatEntry {
 
   /**
    * @param value the value of the entry.
-   * @param isStreamed whether or not this entry is streamed. Defaults to false.
    */
   constructor(value: TextChatEntry) {
     this.id = nextId++
     this.value = value
   }
 
-  static createUserEntry(content: string, isMd = false) {
+  /**
+   * Utility function to create a user entry.
+   * @param content the message's content.
+   * @param isMd whether or not this should be rendered as markdown.
+   * @param hiddenContent the message's content.
+   * @returns a new ChatEntry.
+   */
+  static createUserEntry(content: string, isMd = false, fieldName?: string, hiddenContent?: string[], data?: any) {
     return new ChatEntry({
       agentType: 'user',
       type: isMd ? 'md' : 'text',
       content,
+      name: fieldName,
+      hiddenContent,
+      data,
       updated: new Date().toISOString(),
     })
   }
 
+  /**
+   * Utility function to create a streamed entry from the AI agent.
+   * @returns a new ChatEntry.
+   */
   static createStreamedBotEntry() {
-    return new ChatEntry({ agentType: 'bot', type: 'md', content: '' })
+    return new ChatEntry({ agentType: 'bot', type: 'md', content: '', done: false })
   }
 
   setValue(value: TextChatEntry) {
@@ -79,6 +254,11 @@ export class ChatEntry {
     return this.value
   }
 
+  /**
+   * Watches the value of this ChatEntry.
+   * @param listener a function to call whenever the value changes.
+   * @returns a function that removes the listener.
+   */
   onChange(listener: ChatEntryListener) {
     this.listeners.push(listener)
     return () => {

package/src/state/ChatState.ts

@@ -1,17 +1,45 @@
 import { dropRight, last, pull } from 'lodash'
 import { ulid } from 'ulid'
 import { AbortedError } from '../AbortedError'
+import { ChatFeatures, getFeaturesWithDefaults } from '../features'
+import { UploadManager } from '../utils/upload/UploadManager'
 import { ChatEntry } from './ChatEntry'
+import { acceptedFileTypes, maxFileSize, maxUploadItems } from './constants'
 import { ObservableState } from './ObservableState'
-import { Labeled, LabeledWithImage } from './types'
+import { Labeled, LabeledAgent } from './types'
 
-export interface ChatProperties {
+export interface ChatPropertiesWithOptionalFeatures {
+  /**
+   * The name of the chat.
+   */
   label: string,
-  agent?: LabeledWithImage & { builtIn: boolean },
+  /**
+   * The current AI agent.
+   */
+  agent?: LabeledAgent,
+  /**
+   * The current workspace.
+   */
   workspace?: Labeled,
+  /**
+   * The current stack.
+   */
   stack?: Labeled,
+  /**
+   * The current knowledge sources.
+   */
   knowledgeSources?: Labeled[],
+  /**
+   * Whether or not the chat is in a loading state.
+   */
   isLoading?: boolean,
+  /**
+   * Whether or not the chat is planning.
+   */
+  isPlaning?: boolean,
+  /**
+   * The value of the next message. This is the value of the text typed in the textarea below the chat.
+   */
   nextMessage?: string,
   /**
    * The current code in the editor.
@@ -22,9 +50,26 @@ export interface ChatProperties {
    */
   codeLanguage?: string,
   /**
-   * The current selection in the editor
+   * The current selection in the editor.
    */
   codeSelection?: string,
+  /**
+   * The features enabled for this chat.
+   * 
+   * If a feature is marked as false, it's disabled, otherwise it's enabled.
+   */
+  features?: Partial<ChatFeatures>,
+  /**
+   * The current LLM (Large Language Model) being used for this chat.
+   */
+  selected_model_id?: string,
+}
+
+export interface ChatProperties extends ChatPropertiesWithOptionalFeatures {
+  /**
+   * The features enabled for this chat.
+   */
+  features: ChatFeatures,
 }
 
 type ChatMessagesListener = (chat: ChatEntry[]) => void
@@ -34,33 +79,73 @@ export type MessageInterceptor = (
 ) => boolean | undefined | void | Promise<boolean | undefined | void>
 
 interface Options {
+  /**
+   * The unique identifier for this chat (conversationId).
+   */
   id: string,
-  initial: ChatProperties,
+  /**
+   * The initial value for the state of this chat.
+   */
+  initial: ChatPropertiesWithOptionalFeatures,
+  /**
+   * The interceptors to use for the messages pushed to this chat.
+   * 
+   * The interceptors are run whenever a new message (chat entry) is added to the chat. They're always run in the order of the array and if
+   * any returns a promise, the promise is awaited before running the next.
+   * 
+   * If an interceptor returns false or resolves to false (if a promise), the execution is interrupted, i.e. the next interceptors are not
+   * run.
+   * 
+   * An interceptor receives three parameters:
+   * 1. the chat entry added;
+   * 2. the chat state;
+   * 3. an AbortSignal that can be aborted by calling `abort()` on the ChatState. Once the signal is aborted, the interceptor must abort all
+   * of its operations.
+   * 
+   * Attention: when multiple messages are added at once, only the last goes through the interceptors. Furthermore, messages created by the
+   * constructor don't go through the interceptors, only messages added via `pushMessage` do.
+   */
   interceptors?: MessageInterceptor[],
+  /**
+   * The content of this chat, i.e. its messages.
+   */
   entries?: ChatEntry[],
+  /**
+   * Whether or not the label for this chat is real (persisted in the backend) or just a mock.
+   * 
+   * This should be true if the label is just a mock.
+   */
+  untitled?: boolean,
 }
 
+/**
+ * A chat. Each chat tab is a different ChatState.
+ */
 export class ChatState extends ObservableState<ChatProperties> {
   readonly id: string
   private entries: ChatEntry[]
   private messagesListeners: ChatMessagesListener[] = []
   private readonly interceptors: MessageInterceptor[]
+  /**
+   * A memory space (map) to be used by interceptors.
+   */
   interceptorMemory = new Map<string, any>()
+  /**
+   * Abort signals currently active.
+   */
   private abortions: AbortController[] = []
-
   /**
-   * @param id the id of the chat.
-   * @param initial the initial state.
-   * @param interceptors a list of interceptors to run whenever a new message (entry) is added to the chat. If an interception function
-   * returns false, the next interceptors are not run. Attention: when multiple messages are added at once, only the last goes through the
-   * interceptors. Furthermore, messages created by the constructor don't go through the interceptors, only messages added via `pushMessage`
-   * do.
+   * Used to manage uploads for this Chat.
    */
-  constructor({ id, initial, entries = [], interceptors = [] }: Options) {
-    super(initial)
+  readonly uploadManager = new UploadManager({ maxSize: maxFileSize, accept: acceptedFileTypes, maxItems: maxUploadItems })
+  untitled: boolean
+
+  constructor({ id, initial, entries = [], interceptors = [], untitled = false }: Options) {
+    super({ ...initial, features: getFeaturesWithDefaults(initial.features) })
     this.id = id
     this.interceptors = interceptors
     this.entries = entries
+    this.untitled = untitled
   }
 
   private runMessagesListeners() {
@@ -82,6 +167,10 @@ export class ChatState extends ObservableState<ChatProperties> {
     pull(this.abortions, abort)
   }
 
+  /**
+   * Adds one or more messages to the chat. Messages are appended to the end of the chat.
+   * @param entries the messages to add.
+   */
   pushMessage(...entries: ChatEntry[]) {
     if (!entries.length) return
     this.entries = [...this.entries, ...entries]
@@ -89,15 +178,27 @@ export class ChatState extends ObservableState<ChatProperties> {
     this.runInterceptors(last(entries)!)
   }
 
+  /**
+   * Removes one or more messages from the end of the chat.
+   * @param quantity the number of messages to remove. Defaults to 1.
+   */
   popMessage(quantity = 1) {
     this.entries = dropRight(this.entries, quantity)
     this.runMessagesListeners()
   }
 
+  /**
+   * @returns the current list of messages.
+   */
   getMessages() {
     return this.entries
   }
 
+  /**
+   * Watches this chat for changes in the list of messages.
+   * @param listener the function to call whenever the list of messages changes.
+   * @returns a function that removes the listener.
+   */
   onChangeMessages(listener: ChatMessagesListener) {
     this.messagesListeners.push(listener)
     return () => {
@@ -128,4 +229,20 @@ export class ChatState extends ObservableState<ChatProperties> {
     this.abortions = []
     return newChat
   }
+
+  /**
+   * Returns a promise that resolves when the chat is no longer loading (isLoading state).
+   * 
+   * If this is called when the chat is not loading, a resolved promise is returned.
+   */
+  whenLoadingEnds(): Promise<void> {
+    return this.get('isLoading') ? new Promise((resolve) => {
+      const removeListener = this.onChange('isLoading', (value) => {
+        if (!value) {
+          resolve()
+          removeListener()
+        }
+      })
+    }) : Promise.resolve()
+  }
 }

package/src/state/ChatTabsController.ts

@@ -1,46 +1,112 @@
-import { last, pull } from 'lodash'
+import { groupBy, last, pull } from 'lodash'
 import { ChatState } from './ChatState'
 
-type TabChangeListener = (chats: ChatState[], activeId: string) => void
+type TabChangeListener = (chats: ChatState[], active: ChatState) => void
 
+/**
+ * Controls the chat tabs.
+ */
 export class ChatTabsController {
   private chats: ChatState[] = []
   private activeChatId = ''
   private listeners: TabChangeListener[] = []
 
   private runListeners() {
-    this.listeners.forEach(l => l(this.chats, this.activeChatId))
+    this.listeners.forEach(l => l(this.chats, this.getActiveChat()))
   }
 
+  /**
+   * Adds new chats to the tab view.
+   * @param chats the chats to add.
+   */
   add(...chats: ChatState[]) {
     if (!chats.length) return
     this.chats = [...this.chats, ...chats]
     this.runListeners()
   }
 
-  remove(...ids: string[]) {
-    if (this.chats.length <= 1 || !ids.length) return
-    const currentActiveIndex = this.chats.findIndex(c => c.id === this.activeChatId)
-    this.chats = this.chats.filter(c => !ids.includes(c.id))
-    if (ids.includes(this.activeChatId)) {
+  /**
+   * If the active chat is deleted, this selects a new chat based on the position of the chat that has been removed.
+   * 
+   * @param previous the previous tabs.
+   * @param deleted the ids of the chats that have been deleted.
+   */
+  private reselect(previous: ChatState[], deleted: string[]) {
+    if (deleted.includes(this.activeChatId)) {
+      const currentActiveIndex = previous.findIndex(c => c.id === this.activeChatId)
       if (currentActiveIndex === -1) this.activeChatId = this.chats[0]?.id
       this.activeChatId = currentActiveIndex < this.chats.length ? this.chats[currentActiveIndex].id : last(this.chats)?.id ?? ''
     }
+  }
+
+  /**
+   * Removes chats from the tab view. This will never remove a chat if this chat is the last one.
+   * 
+   * @param ids the ids of the chats to remove.
+   */
+  remove(...ids: string[]) {
+    ids.splice(this.chats.length - 1, ids.length - this.chats.length)
+    if (!ids.length) return
+    const previous = this.chats
+    this.chats = this.chats.filter(c => !ids.includes(c.id))
+    this.reselect(previous, ids)
     this.runListeners()
   }
 
+  /**
+   * Removes all empty chats. The last chat will be kept if it's empty, but the only chat remaining.
+   * 
+   * @param exceptions ids of chats that shouldn't be removed even if empty.
+   */
+  removeEmptyChats(...exceptions: string[]) {
+    const lastChat = last(this.chats)
+    const previous = this.chats
+    const { true: removed, false: kept = [] } = groupBy(this.chats, c => c.getMessages().length === 0 && !exceptions.includes(c.id))
+    if (removed) {
+      this.chats = kept
+      if (lastChat && this.chats.length === 0) this.chats.push(lastChat)
+      this.reselect(previous, removed.map(c => c.id))
+      this.runListeners()
+    }
+  }
+
+  /**
+   * @param id the id of the chat to retrieve.
+   * @returns a ChatState corresponding to the id.
+   */
   get(id: string) {
     return this.chats.find(c => c.id === id)
   }
 
+  /**
+   * @returns the id of the chat corresponding to the tab that is currently active.
+   */
   getActiveChatId() {
     return this.activeChatId
   }
 
+  /**
+   * @returns the chat corresponding to the tab that is currently active.
+   */
+  getActiveChat() {
+    const chat = this.chats.find(c => c.id === this.activeChatId)
+    if (!chat) throw new Error('Chat state error, the active chat id corresponds to none chat in the tabs.')
+    return chat
+  }
+
+  /**
+   * @returns all chats in tab view.
+   */
   getAll() {
     return this.chats
   }
 
+  /**
+   * Watches for changes in the tab view.
+   * @param listener a function called whenever a tab is added, removed or selected. This function receives the list of chats as the first
+   * parameter and the id of the active chat as the second parameter.
+   * @returns a function to remove the listener.
+   */
   onChange(listener: TabChangeListener) {
     this.listeners.push(listener)
     return () => {
@@ -48,6 +114,10 @@ export class ChatTabsController {
     }
   }
 
+  /**
+   * Changes the chat (tab) that is currently active.
+   * @param id the id of the chat to select.
+   */
   select(id: string) {
     this.activeChatId = id
     this.runListeners()

package/src/state/ObservableState.ts

@@ -6,6 +6,14 @@ type Listeners<T> = {
   [K in keyof T]?: ((value: T[K]) => void)[]
 }
 
+/**
+ * A generic representation of a state that can be observed for changes.
+ * 
+ * Building our own state instead of using React is important because:
+ * 1. We need to be able to control it even outside the react context.
+ * 2. We need performance, we can't have everything re-rendering because something changes. We need to be careful to watch only the
+ * properties we need in a component.
+ */
 export class ObservableState<T> {
   protected state: T
   private listeners: Listeners<T> = {}
@@ -25,6 +33,12 @@ export class ObservableState<T> {
     return this.state[key]
   }
 
+  /**
+   * Watches for changes in the state referred by the provided key.
+   * @param key the key of the state to watch.
+   * @param listener a function called whenever the value of the state referred by `key` changes.
+   * @returns a function to remove the listener.
+   */
   onChange<K extends keyof T>(key: K, listener: (value: T[K]) => void) {
     this.listeners[key] ??= []
     this.listeners[key]!.push(listener)