@stack-spot/ai-chat-widget 1.0.0 → 1.1.0

package/src/state/ChatState.ts

@@ -6,12 +6,33 @@ import { ObservableState } from './ObservableState'
 import { Labeled, LabeledWithImage } from './types'
 
 export interface ChatProperties {
+  /**
+   * The name of the chat.
+   */
   label: string,
+  /**
+   * The current AI agent.
+   */
   agent?: LabeledWithImage & { builtIn: boolean },
+  /**
+   * 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,
+  /**
+   * 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,7 +43,7 @@ export interface ChatProperties {
    */
   codeLanguage?: string,
   /**
-   * The current selection in the editor
+   * The current selection in the editor.
    */
   codeSelection?: string,
 }
@@ -34,28 +55,56 @@ export type MessageInterceptor = (
 ) => boolean | undefined | void | Promise<boolean | undefined | void>
 
 interface Options {
+  /**
+   * The unique identifier for this chat (conversationId).
+   */
   id: string,
+  /**
+   * The initial value for the state of this chat.
+   */
   initial: ChatProperties,
+  /**
+   * 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[],
 }
 
+/**
+ * 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>()
-  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.
+   * Abort signals currently active.
    */
+  private abortions: AbortController[] = []
+
   constructor({ id, initial, entries = [], interceptors = [] }: Options) {
     super(initial)
     this.id = id
@@ -82,6 +131,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 +142,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 () => {

package/src/state/ChatTabsController.ts

@@ -3,6 +3,9 @@ import { ChatState } from './ChatState'
 
 type TabChangeListener = (chats: ChatState[], activeId: string) => void
 
+/**
+ * Controls the chat tabs.
+ */
 export class ChatTabsController {
   private chats: ChatState[] = []
   private activeChatId = ''
@@ -12,12 +15,20 @@ export class ChatTabsController {
     this.listeners.forEach(l => l(this.chats, this.activeChatId))
   }
 
+  /**
+   * 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()
   }
 
+  /**
+   * Removes chats from the tab view.
+   * @param ids the ids of the chats to remove.
+   */
   remove(...ids: string[]) {
     if (this.chats.length <= 1 || !ids.length) return
     const currentActiveIndex = this.chats.findIndex(c => c.id === this.activeChatId)
@@ -29,18 +40,34 @@ export class ChatTabsController {
     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 if of the chat corresponding to the tab that is currently active.
+   */
   getActiveChatId() {
     return this.activeChatId
   }
 
+  /**
+   * @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 +75,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)

package/src/state/WidgetState.ts

@@ -16,6 +16,11 @@ export interface WidgetProperties {
   isMinimized?: boolean,
 }
 
+/**
+ * Holds the full state of the AI Chat Widget.
+ * 
+ * This can be used to fully control the chat widget. This is the model of what gets rendered to the screen.
+ */
 export class WidgetState extends ObservableState<WidgetProperties> {
   readonly chatTabs: ChatTabsController
 

package/src/types.ts

@@ -14,7 +14,17 @@ export interface ButtonAction extends WithStyle {
 }
 
 export interface MinimizedActions {
+  /**
+   * When the chat is minimized, a button to collapse the window is rendered. This function is called whenever this button is clicked.
+   */
   onCollapse?: () => void,
+  /**
+   * If `onCollapse` is clicked, the button to collapse is replaced by a button to expand. This function is called whenever the expand
+   * button is clicked. 
+   */
   onExpand?: () => void,
+  /**
+   * When the chat is minimized, a button to close the window is rendered. This function is called whenever this button is clicked.
+   */
   onClose?: () => void,
 }

package/src/utils/chat.ts

@@ -4,8 +4,14 @@ import { ChatState, MessageInterceptor } from '../state/ChatState'
 import { WidgetState } from '../state/WidgetState'
 import { defaultLanguage } from './programming-languages'
 
+// helps with naming new chats
 let next = 1
 
+/**
+ * Utility for creating a new chat in the chat tabs.
+ * @param widget the widget state.
+ * @param interceptors the interceptors to add the chat.
+ */
 export function createNewChat(widget: WidgetState, interceptors: MessageInterceptor[]) {
   const id = ulid()
   widget.chatTabs.add(new ChatState({ id, initial: { label: `Chat ${next}` }, interceptors }))
@@ -13,6 +19,14 @@ export function createNewChat(widget: WidgetState, interceptors: MessageIntercep
   next++
 }
 
+/**
+ * Builds a conversation context from a ChatState.
+ * 
+ * The conversation context is needed by most backend services.
+ * 
+ * @param state the ChatState to build the context from.
+ * @returns the conversation context ready to be sent to the backend.
+ */
 export function buildConversationContext(state: ChatState): FixedChatRequest['context'] {
   return {
     workspace: state.get('workspace')?.id,

package/src/utils/date.ts

@@ -8,7 +8,17 @@ const fullFormatOptions: Intl.DateTimeFormatOptions = {
   month: 'long',
 }
 
-
+/**
+ * Formats a date to show at the footer of a chat message.
+ * 
+ * @example
+ * - Today, 14:11
+ * - Yesterday, 09:00
+ * - October 26 at 10:53
+ * @param date the Date to format.
+ * @param language the language to use.
+ * @returns the formatted date.
+ */
 export function formatDateForChatMessage(date: Date, language: Language = getLanguage()) {
   const formatted: string[] = []
   const now = new Date()
@@ -21,13 +31,27 @@ export function formatDateForChatMessage(date: Date, language: Language = getLan
   return formatted.join(', ')
 }
 
+/**
+ * Uses the current language to format dates.
+ * @returns an object containing functions for formatting dates.
+ */
 export function useDateFormatter() {
   const language = useLanguage()
   return {
+    /**
+     * @param date the date to format using {@link formatDateForChatMessage}.
+     * @returns the formatted date according to the current language. If the language changes, this result also changes.
+     */
     formatForChatMessage: (date: Date) => formatDateForChatMessage(date, language),
   }
 }
 
+/**
+ * Subtracts `numberOfDays` from `date`.
+ * @param date 
+ * @param numberOfDays 
+ * @returns the resulting Date object.
+ */
 export function subtractDays(date: Date, numberOfDays: number) {
   return new Date(date.getTime() - 24 * numberOfDays * 60 * 60000)
 }

package/src/utils/download.ts

@@ -1,3 +1,8 @@
+/**
+ * Downloads `text` as a file named `filename`.
+ * @param filename the name of the file.
+ * @param text the content of the file.
+ */
 export function download(filename: string, text: string) {
   const element = document.createElement('a')
   element.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(text))

package/src/utils/knowledge-source.ts

@@ -1,6 +1,12 @@
 import { DocumentResponse, SourceKnowledgeSource, SourceProjectFile4, SourceStackAi } from '@stack-spot/portal-network/api/ai'
 import { KnowledgeSource } from '../state/ChatEntry'
 
+/**
+ * A document can come from the backend as something that resembles a JSON, but it is not. This function attempts to solve some issues and
+ * still interpret as a JSON.
+ * @param str the malformed JSON.
+ * @returns the object corresponding to parsed JSON or undefined if it wasn't possible to fix it.
+ */
 function attemptToParseMalFormedJson(str: string) {
   try {
     return JSON.parse(str)
@@ -21,6 +27,11 @@ function attemptToParseMalFormedJson(str: string) {
   }
 }
 
+/**
+ * Extracts the important part of a KS document to show for the user.
+ * @param document the document to parse.
+ * @returns an object containing the programming language of the KS, its code snippet and a textual description.
+ */
 export function extractCodeFromKSDocument(document: DocumentResponse): { language?: string, snippet: string, text?: string } {
   const language = (document?.metadata as any)?.language
   if (language) {
@@ -43,6 +54,11 @@ export function extractCodeFromKSDocument(document: DocumentResponse): { languag
   return typeof document === 'object' ? { language: 'json', snippet: JSON.stringify(document, null, 2) } : { snippet: String(document) }
 }
 
+/**
+ * Extracts all knowledge sources from a mix of sources that can be used to shape an AI agent's answer.
+ * @param sources a list with sources of any kind.
+ * @returns a list of knowledge sources in the format expected by the chat.
+ */
 export function genericSourcesToKnowledgeSources(
   sources: (SourceStackAi | SourceKnowledgeSource | SourceProjectFile4)[] | undefined,
 ): KnowledgeSource[] | undefined {

package/src/utils/string.ts

@@ -1,4 +1,8 @@
-// gets the size of a string removing control characters and spaces
+/**
+ * Gets the size of a string removing control characters and spaces
+ * @param str the string to count.
+ * @returns the count value.
+ */
 export function getSizeOfString(str: string): number {
   // eslint-disable-next-line no-control-regex
   const withoutSpacesAndControls = str.replace(/[\u0000-\u001F\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069\s]/g, '')

package/src/views/Agents.tsx

@@ -82,6 +82,9 @@ export const Agents = () => {
   return null
 }
 
+/**
+ * Renders the Agent selection form in the Right Panel if this is the panel that is currently opened.
+ */
 const AgentsPanel = () => {
   const t = useTranslate(dictionary)
   const chat = useCurrentChat()

package/src/views/Chat/AgentInfo.tsx

@@ -6,6 +6,9 @@ interface Props {
   agent?: LabeledWithImage,
 }
 
+/**
+ * Renders the avatar of an agent in a message.
+ */
 export const AgentInfo = ({ agent }: Props) => (
   <>
     {agent?.image

package/src/views/Chat/ChatMessage.tsx

@@ -1,39 +1,37 @@
 import { Button, IconBox, Text } from '@citric/core'
 import { Copy, Dislike, DislikeFill, Like, LikeFill, TimesCircle } from '@citric/icons'
 import { Avatar, Badge, IconButton } from '@citric/ui'
-import { aiClient } from '@stack-spot/portal-network'
 import { listToClass } from '@stack-spot/portal-theme'
 import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
 import { useCallback, useMemo, useRef, useState } from 'react'
 import { Markdown } from '../../components/Markdown'
 import { useChatEntry, useCurrentChat, useWidget } from '../../context/hooks'
 import { ChatEntry, SerializableAction, TextChatEntry } from '../../state/ChatEntry'
-import { ChatState } from '../../state/ChatState'
-import { buildConversationContext } from '../../utils/chat'
 import { useDateFormatter } from '../../utils/date'
-import { getSizeOfString } from '../../utils/string'
 import { AgentInfo } from './AgentInfo'
 import { useChatScrollToBottomEffect } from './chat-scroll'
+import { onCopyAll, onCopyCode, onLikeOrDislike } from './events'
 
-async function onCopyCode(code: string, messageId: string, chat: ChatState) {
-  try {
-    await aiClient.createEvent.mutate({
-      body: [{
-        type: 'code_copied',
-        code,
-        context: buildConversationContext(chat),
-        size: getSizeOfString(code),
-        generated_at: new Date().getTime(),
-        message_id: messageId,
-      }],
-    })
-  } catch (error) {
-    // eslint-disable-next-line no-console
-    console.warn('Failed to register event: code copied.')
-  }
+interface Props {
+  /**
+   * The ChatEntry to render.
+   */
+  message: ChatEntry,
+  /**
+   * The name of the user currently logged in (will be used if the agent type of the message is "user").
+   */
+  username: string,
+  /**
+   * Whether or not this is the last message in the chat. This is important for disabling action buttons in messages that are no longer
+   * relevant.
+   */
+  isLast: boolean,
 }
 
-export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry, username: string, isLast: boolean }) => {
+/**
+ * Renders a message (ChatEntry) in the chat.
+ */
+export const ChatMessage = ({ message, username, isLast }: Props) => {
   const t = useTranslate(dictionary)
   const [liked, setLiked] = useState<boolean | undefined>()
   const entry = useChatEntry(message)
@@ -64,16 +62,7 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
       if (!entry.messageId || like === liked) return
       setLiked(like)
       try {
-        await aiClient.createEvent.mutate({
-          body: [{
-            feedback: like ? 'LIKE' : 'DISLIKE',
-            message_id: entry.messageId,
-            type: 'user_feedback_provided',
-            code: '',
-            generated_at: Math.floor(new Date().getTime() / 1000),
-            size: 0,
-          }],
-        })
+        await onLikeOrDislike(entry.messageId, like)
       } catch {
         setLiked(liked)
       }
@@ -131,7 +120,7 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
       {shouldShowFooter && <div className="message-footer">
         {entry.agentType === 'bot' && !entry.error && <div className="message-actions">
           {entry.type === 'md' && (
-            <IconButton title={t.copy} aria-label={t.copy} onClick={() => navigator.clipboard.writeText(entry.content)}>
+            <IconButton title={t.copy} aria-label={t.copy} onClick={() => onCopyAll(entry, chat)}>
               <Copy />
             </IconButton>
           )}

package/src/views/Chat/ChatMessages.tsx

@@ -8,6 +8,9 @@ interface Props {
   chatId: string,
 }
 
+/**
+ * Renders all messages of a chat.
+ */
 export const ChatMessages = ({ chatId, username }: Props) => {
   const messages = useChatMessages(chatId)
   const items = useMemo(

package/src/views/Chat/chat-scroll.ts

@@ -2,7 +2,7 @@ import { useEffect, useRef } from 'react'
 
 /**
  * Scrolls the closest chat (upwards in the tree) to its bottom.
- * @param ref the reference element.
+ * @param ref the reference to the element contained the chat we want to scroll.
  * @param deps when the deps changes, the chat is scrolled.
  */
 export function useChatScrollToBottomEffect(ref: React.RefObject<HTMLElement>, deps: any[]) {

package/src/views/Chat/events.ts

@@ -0,0 +1,69 @@
+import { aiClient } from '@stack-spot/portal-network'
+import { TextChatEntry } from '../../state/ChatEntry'
+import { ChatState } from '../../state/ChatState'
+import { buildConversationContext } from '../../utils/chat'
+import { getSizeOfString } from '../../utils/string'
+
+/**
+ * Creates the event of copying a code.
+ * @param code the code copied.
+ * @param messageId the id of the message containing the code.
+ * @param chat the chat state.
+ */
+export async function onCopyCode(code: string, messageId: string, chat: ChatState) {
+  try {
+    await aiClient.createEvent.mutate({
+      body: [{
+        type: 'code_copied',
+        code,
+        context: buildConversationContext(chat),
+        size: getSizeOfString(code),
+        generated_at: new Date().getTime(),
+        message_id: messageId,
+      }],
+    })
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn('Failed to register event: code copied.')
+  }
+}
+
+/**
+ * Creates the event of copying a whole message.
+ * @param entry the message copied.
+ * @param chat the chat state.
+ */
+export function onCopyAll(entry: TextChatEntry, chat: ChatState) {
+  navigator.clipboard.writeText(entry.content)
+  return aiClient.createEvent.mutate({
+    body: [
+      {
+        code: entry.content,
+        size: getSizeOfString(entry.content),
+        generated_at: new Date().getTime(),
+        type: 'copied_all',
+        knowledge_sources: entry.knowledgeSources?.map(ks => ({ slug: ks.slug, type: 'knowledge_source', name: ks.name })),
+        context: buildConversationContext(chat),
+        message_id: entry.messageId,
+      },
+    ],
+  })
+}
+
+/**
+ * Creates an event of like or dislike for a message.
+ * @param messageId the id of the message.
+ * @param like true if it's a like, false if it's a dislike.
+ */
+export function onLikeOrDislike(messageId: string, like: boolean) {
+  return aiClient.createEvent.mutate({
+    body: [{
+      feedback: like ? 'LIKE' : 'DISLIKE',
+      message_id: messageId,
+      type: 'user_feedback_provided',
+      code: '',
+      generated_at: Math.floor(new Date().getTime() / 1000),
+      size: 0,
+    }],
+  })
+}

package/src/views/Chat/index.tsx

@@ -2,9 +2,15 @@ import { useChatTabs } from '../../context/hooks'
 import { ChatMessages } from './ChatMessages'
 
 interface Props {
+  /**
+   * The name of the user currently logged in.
+   */
   username: string,
 }
 
+/**
+ * Renders the chat panel, with all of its messages.
+ */
 export const Chat = ({ username }: Props) => {
   const { active } = useChatTabs()
   return <ChatMessages key={active} chatId={active} username={username} />

package/src/views/ChatHistory/ChatHistoryPanel.tsx

@@ -5,6 +5,9 @@ import { HistoryList } from '../../components/HistoryList'
 import { MessageInterceptor } from '../../state/ChatState'
 import { HistoryItem } from './HistoryItem'
 
+/**
+ * Renders the list of conversations (history).
+ */
 export const ChatHistoryPanel = ({ interceptors }: { interceptors: MessageInterceptor[] }) => {
   const [chats, { fetchNextPage, hasNextPage }] = aiClient.chats.useInfiniteQuery({ size: 40 })
   return (

package/src/views/ChatHistory/HistoryItem.tsx

@@ -18,6 +18,9 @@ import { useHistoryDictionary } from './dictionary'
 import { HistoryItemBox } from './styled'
 import { findStack, findWorkspace, getAllAgents } from './utils'
 
+/**
+ * Renders an item of the list of conversations (history).
+ */
 export const HistoryItem = ({ item, interceptors }: { item: ConversationResponse, interceptors: MessageInterceptor[] }) => {
   const t = useHistoryDictionary()
   const [isLoading, setLoading] = useState(false)

package/src/views/ChatHistory/index.tsx

@@ -6,7 +6,17 @@ import { MessageInterceptor } from '../../state/ChatState'
 import { ChatHistoryPanel } from './ChatHistoryPanel'
 import { useHistoryDictionary } from './dictionary'
 
-export const ChatHistory = ({ interceptors }: { interceptors: MessageInterceptor[] }) => {
+interface Props {
+  /**
+   * The chat interceptors to use when recreating a ChatState from the history.
+   */
+  interceptors: MessageInterceptor[],
+}
+
+/**
+ * Renders the Chat History in the Right Panel if this is the panel that is currently opened.
+ */
+export const ChatHistory = ({ interceptors }: Props) => {
   const t = useHistoryDictionary()
   const panel = useWidgetState('panel')
   const { open } = useRightPanel()