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

package/src/components/form/types.ts

@@ -1,21 +1,65 @@
 import { WithStyle } from '@stack-spot/portal-theme'
 
 interface RadioCheckProps<T> extends WithStyle {
+  /**
+   * The options available.
+   */
   options: T[],
+  /**
+   * A function that renders an option as a label. This can either return a string or a React Element.
+   */
   renderLabel: (option: T) => React.ReactNode,
+  /**
+   * A function that renders an option as a description. This can either return a string or a React Element.
+   */
   renderDescription: (option: T) => React.ReactNode,
+  /**
+   * A function that renders a element before the content
+   */
+  renderBeforeElement?: (option: T) => React.ReactNode,
+  /**
+   * A function that renders a element after the content
+   */
+  renderAfterElement?: (option: T) => React.ReactNode,
+  /**
+   * A function that gives a custom className to the rendered option.
+   */
   optionClassName?: (option: T) => string | undefined,
+  /**
+   * A function that gives a custom style to the rendered option.
+   */
   optionStyle?: (option: T) => React.CSSProperties | undefined,
+  /**
+   * A function that generates a unique id for the option.
+   */
   keygen: (option: T) => React.Key,
-  
+  /**
+   * An object containing favorite items and related operations.
+   */
 }
 
 export interface RadioProps<T> extends RadioCheckProps<T> {
+  /**
+   * The current value of the radio group. This is one of the options.
+   * 
+   * Comparisons use the same-value-zero algorithm (`===`).
+   */
   value: T | undefined,
+  /**
+   * A function to call whenever the value changes.
+   */
   onChange: (option: T) => void,
 }
 
 export interface CheckProps<T> extends RadioCheckProps<T> {
+  /**
+   * The current value of the checkbox group. This is sub-array of the array of options.
+   * 
+   * Comparisons use the same-value-zero algorithm (`===`).
+   */
   value: T[],
+  /**
+   * A function to call whenever the value changes.
+   */
   onChange: (option: T[]) => void,
 }

package/src/context/AIWidgetProvider.tsx

@@ -3,4 +3,23 @@ import { WidgetState } from '../state/WidgetState'
 
 export const AIWidgetContext = createContext<WidgetState | undefined>(undefined)
 
+/**
+ * Creates a new context for the AI Chat Widget.
+ * 
+ * This is not required, but makes it much easier to control the chat and is the only way to have multiple instances of the chat model in
+ * the same application.
+ * 
+ * To control the chat widget in any component descendant from the `AIWidgetProvider`, you can call the hook `useWidget()`.
+ * 
+ * Example:
+ * ```
+ * const widget = useMemo(() => new WidgetState(), [])
+ * 
+ * return (
+ *   <AIWidgetProvider value={widget}>
+ *     {children}
+ *   </AIWidgetProvider>
+ * ```
+ *
+ */
 export const AIWidgetProvider = AIWidgetContext.Provider

package/src/context/hooks.ts

@@ -1,14 +1,16 @@
-/* eslint-disable react-hooks/rules-of-hooks */
+import { last } from 'lodash'
 import { useContext, useEffect, useState } from 'react'
 import { ChatEntry } from '../state/ChatEntry'
-import { ChatProperties, ChatState, MessageInterceptor } from '../state/ChatState'
+import { ChatProperties, ChatState } from '../state/ChatState'
 import { ObservableState } from '../state/ObservableState'
 import { WidgetProperties, WidgetState } from '../state/WidgetState'
-import { createNewChat } from '../utils/chat'
 import { AIWidgetContext } from './AIWidgetProvider'
 
 let globalWidgetState: WidgetState | undefined
 
+/**
+ * Returns the closest instance of a WidgetState (React Context). If no context is available, uses a global instance of the chat widget.
+ */
 export function useWidget(): WidgetState {
   const fromContext = useContext(AIWidgetContext)
   if (fromContext) return fromContext
@@ -16,7 +18,10 @@ export function useWidget(): WidgetState {
   return globalWidgetState
 }
 
-function useObservableState<T, K extends keyof T>(state: ObservableState<T>, key: K): T[K] {
+/**
+ * Watches an ObservableState.
+ */
+export function useObservableState<T, K extends keyof T>(state: ObservableState<T>, key: K): T[K] {
   const [value, setValue] = useState(state.get(key))
   useEffect(() => {
     setValue(state.get(key))
@@ -25,43 +30,80 @@ function useObservableState<T, K extends keyof T>(state: ObservableState<T>, key
   return value
 }
 
+/**
+ * Watches one of the widget states.
+ * @param key the key watch changes for.
+ * @returns the value of the state referred by the key.
+ */
 export function useWidgetState<K extends keyof WidgetProperties>(key: K): WidgetProperties[K] {
   const widget = useWidget()
   return useObservableState(widget, key)
 }
 
-export function useChatTabs(): { chats: ChatState[], active: string } {
+/**
+ * Watches the tabs of a ChatState. The value is updated whenever a tab is added, removed or selected.
+ */
+export function useChatTabs(): { chats: ChatState[], active: ChatState } {
   const widget = useWidget()
-  const [tabs, setTabs] = useState<{ chats: ChatState[], active: string }>({
-    chats: widget.chatTabs.getAll(), 
-    active: widget.chatTabs.getActiveChatId(),
+  const [tabs, setTabs] = useState<{ chats: ChatState[], active: ChatState }>({
+    chats: widget.chatTabs.getAll(),
+    active: widget.chatTabs.getActiveChat(),
   })
   useEffect(() => widget.chatTabs.onChange((chats, active) => setTabs({ chats, active })), [])
   return tabs
 }
 
+/**
+ * Gets a chat according to its identifier (conversation id).
+ * 
+ * An error is thrown if the id doesn't correspond to any chat currently opened.
+ * 
+ * @returns the chat state.
+ */
 export function useChat(chatId: string): ChatState {
   const widget = useWidget()
   const chat = widget.chatTabs.get(chatId)
-  if (!chat) throw new Error(`No chat with id ${chatId} was found. Maybe there are no chats opened, try to call useFirstChat first.`)
+  if (!chat) throw new Error(`No chat with id ${chatId} was found. Maybe there are no chats opened.`)
   return chat
 }
 
+/**
+ * Watches the current chat (selected in the chat tabs.)
+ * 
+ * The value changes whenever a new chat is selected.
+ * 
+ * @returns the currently active chat. 
+ */
 export function useCurrentChat(): ChatState {
-  const { active } = useChatTabs()
-  return useChat(active)
+  return useChatTabs().active
 }
 
+/**
+ * Watches one of the chat states.
+ * @param chatId the id of chat to watch.
+ * @param key the key of the state to watch.
+ * @returns the value of the state referred by the key.
+ */
 export function useChatState<K extends keyof ChatProperties>(chatId: string, key: K): ChatProperties[K] {
   const chat = useChat(chatId)
   return useObservableState(chat, key)
 }
 
+/**
+ * Watches one of the current chat states. This is the same as calling `useChatState` with the id of the current chat.
+ * @param key the key of the state to watch.
+ * @returns the value of the state referred by the key.
+ */
 export function useCurrentChatState<K extends keyof ChatProperties>(key: K): ChatProperties[K] {
   const chat = useCurrentChat()
   return useObservableState(chat, key)
 }
 
+/**
+ * Watches a chat state for changes in the list of messages (chat entries).
+ * @param chatId the id of the chat to watch.
+ * @returns the list of messages in the chat.
+ */
 export function useChatMessages(chatId: string): ChatEntry[] {
   const chat = useChat(chatId)
   const [entries, setEntries] = useState(chat.getMessages())
@@ -72,19 +114,47 @@ export function useChatMessages(chatId: string): ChatEntry[] {
   return entries
 }
 
+/**
+ * Watches the chat state currently active for changes in the list of messages (chat entries). This is the same as calling `useChatMessages`
+ * with the id of the current chat.
+ * @returns the list of messages in the chat.
+ */
 export function useCurrentChatMessages(): ChatEntry[] {
   const { active } = useChatTabs()
-  return useChatMessages(active)
+  return useChatMessages(active.id)
 }
 
+/**
+ * Watches a chat message (chat entry) for changes in its composition. This allows messages to be streamed: each part of the stream will 
+ * change the current value of the entry.
+ * @param entry the message to watch.
+ * @returns the current value of the message.
+ */
 export function useChatEntry(entry: ChatEntry) {
   const [content, setContent] = useState(entry.getValue())
   useEffect(() => entry.onChange(setContent), [])
   return content
 }
 
-export function useFirstChat(interceptors: MessageInterceptor[]) {
-  const widget = useWidget()
-  const tabs = widget.chatTabs
-  if (!tabs.getAll().length) createNewChat(widget, interceptors)
+/*
+ * An efficient hook that returns true when the current chat entry is the last entry and false when it's not.
+ *
+ * For efficiency purposes, this hook assumes that:
+ * - Any change to the list of messages makes it grow.
+ * - Once a message is no longer the last, it will never be the last entry again.
+ * 
+ * @param id: the id of the entry. 
+ **/
+export function useIsLastEntryInCurrentChat(id: number) {
+  const chat = useCurrentChat()
+  const [isLast, setLast] = useState(last(chat.getMessages())?.id === id)
+  useEffect(() => {
+    if (!isLast) return
+    const removeListener = chat.onChangeMessages(() => {
+      setLast(false)
+      removeListener()
+    })
+    return removeListener
+  }, [chat])
+  return isLast
 }

package/src/features.ts

@@ -1,21 +1,95 @@
-export interface MessageInputFeatures {
-  stack?: boolean,
-  workspace?: boolean,
-  knowledgeSource?: boolean,
-  agent?: boolean,
-  quickCommands?: boolean,
-  editor?: boolean,
+export interface ChatFeatures {
+  /**
+   * Enables stack selection.
+   */
+  stack: boolean,
+  /**
+   * Enables workspace selection.
+   */
+  workspace: boolean,
+  /**
+   * Enables knowledge source selection.
+   */
+  knowledgeSource: boolean,
+  /**
+   * Enables agent selection.
+   */
+  agent: boolean,
+  /**
+   * Enables quick commands.
+   */
+  quickCommands: boolean,
+  /**
+   * Enables the editor.
+   */
+  editor: boolean,
+  /**
+   * Enables chat message. Default: true
+   */
+  messageInput: boolean,
+  /**
+   * Enables file uploads.
+   */
+  upload: boolean,
+  /**
+   * Enables the listing of sources when writing a chat response.
+   */
+  showSourcesInResponse: boolean,
+  /**
+   * Enables streaming in chat responses.
+   */
+  streaming: boolean,
+  /**
+  * Enables LLM select.
+  */
+  showLLMSelect: boolean,
 }
 
-export interface AIWidgetFeatures extends MessageInputFeatures {
-  chatHistory?: boolean,
+export type Scope = 'favorite' | 'builtin' | 'personal' | 'shared' | 'workspace' | 'account'
+
+export interface GlobalFeatures {
+  /**
+   * Enables the chat history.
+   */
+  chatHistory: boolean,
+  /**
+   * When selecting a resource, they're separated by scope (account, personal, workspace, etc.).
+   * 
+   * If this is set, only the scopes in this list will be enabled.
+   */
+  scopes?: Scope[],
+  /**
+    * When set, only items(knowledge sources, agents, stacks ai, quick commands) from that workspace will be shown to the user.
+    */
+  workspaceId?: string,
+  /**
+   * when set to false it does not show tab by scope, it shows a single list.
+   */
+  groupResourcesByScope?: boolean,
 }
 
-export const defaultFeatures: AIWidgetFeatures = {
-  stack: true,
-  workspace: true,
-  knowledgeSource: true,
-  agent: true,
-  chatHistory: true,
-  editor: true,
+export type AIWidgetFeatures = ChatFeatures & GlobalFeatures
+
+/**
+ * Receives a partial feature object and returns a full feature object, setting to true any missing property.
+ * @param features the partial features object.
+ * @returns a full features object.
+ */
+export function getFeaturesWithDefaults(features?: Partial<AIWidgetFeatures>): AIWidgetFeatures {
+  return {
+    agent: true,
+    editor: true,
+    knowledgeSource: true,
+    quickCommands: true,
+    stack: true,
+    workspace: true,
+    chatHistory: true,
+    messageInput: true,
+    upload: true,
+    streaming: true,
+    showLLMSelect: true,
+    showSourcesInResponse: true,
+    groupResourcesByScope: true,
+    ...features,
+  }
 }

package/src/hooks/midnight-update-view.ts

@@ -0,0 +1,36 @@
+import { useManualRender } from '@stack-spot/portal-components'
+import { useEffect } from 'react'
+
+/**
+ * Returns the number of milliseconds remaining until the next midnight.
+ */
+function getTimeUntilMidnight() {
+  const now = new Date()
+  const midnight = new Date(now)
+  midnight.setHours(24, 0, 0, 0)
+  return midnight.getTime() - now.getTime()
+}
+
+/**
+ * Hook that triggers a component re-render at midnight every day.
+ */
+export function useMidnightUpdateView() {
+  const { repaint } = useManualRender()
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+
+    const scheduleUpdate = () => {
+      const timeUntilMidnight = getTimeUntilMidnight()
+
+      timer = setTimeout(() => {
+        repaint()
+        scheduleUpdate()
+      }, timeUntilMidnight)
+    }
+
+    scheduleUpdate()
+    
+    return () => { timer && clearTimeout(timer) }
+  }, [])
+}

package/src/images.d.ts

@@ -0,0 +1,5 @@
+declare module '*.png' {
+  const value: string
+  // eslint-disable-next-line import/no-default-export
+  export default value
+}

package/src/index.ts

@@ -1,8 +1,24 @@
+/* Attention: in order for the package "page" to work without linking the lib, we must export types separately, using the "type" keyword */
+
+
+export { createEntryValueFromChatResponse, helperSendMessage } from './chat-interceptors/send-message'
+export { QuickStartButton } from './components/QuickStartButton'
 export { AIWidgetProvider } from './context/AIWidgetProvider'
 export * from './context/hooks'
+export { getFeaturesWithDefaults } from './features'
+export type { AIWidgetFeatures, ChatFeatures } from './features'
 export { StackspotAIWidget } from './StackspotAIWidget'
 export { ChatEntry } from './state/ChatEntry'
+export type { ChatAction, TextChatEntry } from './state/ChatEntry'
 export { ChatState } from './state/ChatState'
+export type { MessageInterceptor } from './state/ChatState'
 export { ChatTabsController } from './state/ChatTabsController'
+export { acceptedFileTypes } from './state/constants'
 export { ObservableState } from './state/ObservableState'
+export type { Labeled, LabeledAgent, LabeledWithImage } from './state/types'
 export { WidgetState } from './state/WidgetState'
+export type { ButtonAction } from './types'
+export { defaultLanguage, languages } from './utils/programming-languages'
+export type { CustomRenderResult } from './views/Chat/ChatMessage'
+export { loadChat } from './views/ChatHistory/utils'
+

package/src/layout.css

@@ -1,29 +1,3 @@
-@font-face {
-  font-family: "San Francisco";
-  font-weight: 400;
-  src: url("https://applesocial.s3.amazonaws.com/assets/styles/fonts/sanfrancisco/sanfranciscodisplay-regular-webfont.woff");
-}
-
-/* Scroll bars */
-
-::-webkit-scrollbar-track {
-  background-color: transparent;
-}
-
-::-webkit-scrollbar {
-  width: 0.25rem;
-  height: 0.5rem;
-  background-color: transparent;
-}
-
-::-webkit-scrollbar-thumb {
-  background-color: var(--light-600);
-}
-
-::-webkit-scrollbar-corner {
-  background-color: transparent; 
-}
-
 /* Classes */
 
 .ai-chat-widget {
@@ -31,7 +5,7 @@
   background-color: var(--light-400);
   border-radius: 4px;
   position: relative;
-  overflow: hidden;
+  overflow: clip;
   width: 100%;
   height: 100%;
 
@@ -53,7 +27,6 @@
     .home-page {
       .title {
         margin-top: 40px;
-        font-size: 18px;
       }
       .subtitle {
         font-size: 14px;
@@ -73,6 +46,11 @@
         display: none;
       }
     }
+    .quick-command-selector {
+      width: auto;
+      left: 10px;
+      right: 10px;
+    }
   }
 }
 
@@ -90,20 +68,40 @@
 }
 
 .chat-container {
+  position: relative;
   padding: 20px;
   max-width: 1200px;
   width: calc(100% - 40px);
   display: flex;
   flex-direction: column;
   flex: 1;
+  .agent-list .agent-card {
+    flex-direction: row;
+    align-items: center;
+    gap: 8px;
+    border-radius: 4px;
+    padding: 10px 8px;
+    img {
+      width: 32px;
+      height: 32px;
+      border-radius: 4px;
+    }
+    h6 {
+      font-weight: 400;
+      font-size: 13px;
+      line-height: 14px;
+    }
+  }
 }
 
 .chat-content {
+  padding-bottom: 16px;
   display: flex;
   flex-direction: column;
   flex: 1;
   flex-basis: 0;
   overflow: auto;
+  padding-right: 12px;
 }
 
 .chat-right-panel {
@@ -119,7 +117,76 @@
   display: flex;
   flex-direction: column;
 
+  code {
+     overflow: auto;
+  }
+  
   &.visible {
     left: 50%;
   }
 }
+
+.chat-modal {
+  position: absolute;
+  top: 90px;
+  bottom: 20px;
+  right: 20px;
+  width: 20%;
+  min-width: 400px;
+  border-radius: 6px;
+  background-color: var(--light-400);
+  border: 1px solid var(--light-600);
+  overflow: auto;
+
+  > header {
+    padding: 14px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 6px;
+  }
+}
+
+/* fixes placeholder description */
+.no-data-placeholder {
+  > div > p {
+    text-align: center;
+  }
+}
+
+.input-phone .react-international-phone-country-selector-button {
+  background-color: var(--light-300);
+  border: 1px solid var(--primary-500);
+  border-right: none;
+}
+
+.input-phone.react-international-phone-input-container .react-international-phone-input {
+  background-color: var(--light-300);
+  border: 1px solid var(--primary-500);
+  border-left: none;
+  color: var(--light-contrastText);
+}
+
+.upload-drag-drop {
+  display: flex;
+  background-color: #00000090;
+  background-color: color-mix(in srgb, var(--light-300) 80%, transparent);
+  position: absolute;
+  width: 99%;
+  height: 99%;
+  top: 0;
+  left: 0;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  border: 1px dashed var(--secondary-500);
+  z-index: 9999;
+  pointer-events: auto;
+  color: var(--light-contrastText)
+}
+
+.menu-citric-hr {
+  hr {
+    margin: 0;
+  }
+}

package/src/regex.ts

@@ -0,0 +1,2 @@
+export const quickCommandRegex = /^\/[\w\d-_]+$/
+export const agentRegex = /^@[\w\d-_]+$/

package/src/right-panel/DefaultPanel.tsx

@@ -1,6 +1,4 @@
-import { Text } from '@citric/core'
-import { Times } from '@citric/icons'
-import { IconButton } from '@citric/ui'
+import { IconButton, Text } from '@stack-spot/citric-react'
 import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
 import { styled } from 'styled-components'
 import { WithChildren } from '../types'
@@ -40,18 +38,20 @@ const PanelBox = styled.div`
   }
 ` 
 
+/**
+ * Default layout for a right panel.
+ */
 export const DefaultPanel = ({ description, onClose, title, children }: Props) => {
   const t = useTranslate(dictionary)
+
   return (
     <PanelBox>
       <header>
         <div className="title">
           {typeof title === 'string' ? <Text appearance="h5">{title}</Text> : title}
-          {typeof description === 'string' ? <Text colorScheme="light.700">{description}</Text> : description}
+          {typeof description === 'string' ? <Text color="light.700">{description}</Text> : description}
         </div>
-        <IconButton title={t.close} aria-label={t.close} onClick={onClose}>
-          <Times />
-        </IconButton>
+        <IconButton icon="Times" title={t.close} aria-label={t.close} onClick={onClose} />
       </header>
       <article>{children}</article>
     </PanelBox>

package/src/right-panel/RightPanel.tsx

@@ -1,5 +1,8 @@
 import { useRightPanelContent } from './hooks'
 
+/**
+ * Renders the content of the right panel.
+ */
 export const RightPanel = () => {
   const content = useRightPanelContent()
   return content

package/src/right-panel/RightPanelProvider.tsx

@@ -1,10 +1,25 @@
 import { createContext, useMemo, useRef, useState } from 'react'
 
 interface ContextValue {
+  /**
+   * The current content of the right panel.
+   */
   content?: React.ReactNode,
+  /**
+   * Sets the current content of the right panel.
+   */
   setContent?: (content: React.ReactNode) => void,
+  /**
+   * A reference to the right panel HTML Element.
+   */
   panel?: React.RefObject<HTMLDivElement>,
+  /**
+   * A reference to the chat window at the left of the right panel.
+   */
   chatWindow?: React.RefObject<HTMLDivElement>,
+  /**
+   * A function to run when the right panel is closed for the next time.
+   */
   onCloseNext: React.MutableRefObject<(() => void) | undefined>,
 }
 

package/src/right-panel/constants.ts

@@ -0,0 +1 @@
+export const panelAnimationTime = 300