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

package/src/components/Tooltip/Tooltip.tsx

@@ -8,14 +8,37 @@ import { DefaultTooltip } from './style'
 import { TooltipPosition } from './types'
 
 interface Props extends WithChildren, WithStyle {
+  /**
+   * The content of the tooltip. Can be either a string or a Rect Element.
+   */
   content: React.ReactNode,
+  /**
+   * Where to position the tooltip relative to the element that triggered it.
+   */
   position?: TooltipPosition,
+  /**
+   * A tooltip can be triggered either by hovering an element or by clicking it.
+   * @default 'hover'
+   */
   triggeredBy?: 'click' | 'hover',
+  /**
+   * If true, no style is applied to the tooltip, letting you customize it however you want to.
+   */
   custom?: boolean,
+  /**
+   * Function to run whenever the tooltip is shown.
+   */
   onShow?: () => void,
+  /**
+   * Function to run whenever the tooltip is hidden.
+   */
   onHide?: () => void,
 }
 
+/**
+ * Shows a tooltip for its children. This tooltip element is always reused and placed at a root level in order to not be cut out by
+ * hidden overflows in the children and its ascendants.
+ */
 export const Tooltip = forwardRef<HTMLDivElement, Props>((
   { content, custom, position, triggeredBy = 'hover', onHide, onShow, children, className, style },
   ref,

package/src/components/Tooltip/TooltipAPI.ts

@@ -2,13 +2,24 @@ import { delay } from '@stack-spot/portal-components'
 import { animationTimeMS } from './style'
 import { ShowOptions } from './types'
 
+// the maximum amount of pixels a tooltip can get close to the screen edges.
 const MARGIN_TO_CORNERS_PX = 10
 
 function isRelative(element: HTMLElement) {
   return ['relative', 'absolute', 'fixed'].includes(element.computedStyleMap().get('position')?.toString() ?? '')
 }
 
+/**
+ * Allows interaction with the tooltip element.
+ * 
+ * This places the tooltip element at the correct place, shows it, hides it and manages its contents.
+ * 
+ * This also takes into account the screen edges, making adjustments to the tooltip position if it would overflow the screen.
+ */
 export class TooltipAPI {
+  /**
+   * A reference to the tooltip element in the HTML tree.
+   */
   tooltipRef: React.RefObject<HTMLDivElement>
   private setContent: React.Dispatch<React.SetStateAction<React.ReactNode>>
   private hideTimeoutId: number | undefined
@@ -28,6 +39,9 @@ export class TooltipAPI {
     }
   }
 
+  /**
+   * Shows the tooltip with `content`. Its position is based on `position` and the position of the element referred by `anchor`.
+   */
   async show({ content, anchor, position = 'bottom', hideOnClickOutside }: ShowOptions) {
     window.clearTimeout(this.hideTimeoutId)
     this.hideTimeoutId = undefined
@@ -75,6 +89,9 @@ export class TooltipAPI {
     }
   }
 
+  /**
+   * Hides the tooltip. After the animation, the content is removed.
+   */
   hide(): void {
     if (!this.tooltipRef.current) return
     this.tooltipRef.current.classList.remove('visible')

package/src/components/Tooltip/types.ts

@@ -8,8 +8,21 @@ export interface BoxPosition {
 }
 
 export interface ShowOptions {
+  /**
+   * The content of the tooltip. Can be either a string or a React Element.
+   */
   content: React.ReactNode,
+  /**
+   * The anchor to the tooltip. This is part of what defines the position where the tooltip will appear.
+   */
   anchor: HTMLElement,
+  /**
+   * The position relative to the element referred by `anchor`.
+   * @default bottom
+   */
   position?: TooltipPosition,
+  /**
+   * Whether or not to hide the tooltip when a click is detected outside of it.
+   */
   hideOnClickOutside?: boolean,
 }

package/src/components/form/DescribedCheckboxGroup.tsx

@@ -5,6 +5,10 @@ import { Accordion } from '../Accordion'
 import { RadioCheckBox } from './styled'
 import { CheckProps } from './types'
 
+/**
+ * Renders a checkbox group where each option has a label and a description.
+ * The description in placed under the label and checkbox as an accordion.
+ */
 export function DescribedCheckboxGroup<T>(
   { keygen, onChange, options, renderDescription, renderLabel, optionClassName, optionStyle, value, className, style }: CheckProps<T>,
 ) {

package/src/components/form/DescribedRadioGroup.tsx

@@ -5,6 +5,10 @@ import { Accordion } from '../Accordion'
 import { RadioCheckBox } from './styled'
 import { RadioProps } from './types'
 
+/**
+ * Renders a radio button group where each option has a label and a description.
+ * The description in placed under the label and radio button as an accordion.
+ */
 export function DescribedRadioGroup<T>(
   { keygen, onChange, options, renderDescription, renderLabel, optionClassName, optionStyle, value, className, style }: RadioProps<T>,
 ) {

package/src/components/form/types.ts

@@ -1,21 +1,55 @@
 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 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,
   
 }
 
 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,4 +1,3 @@
-/* eslint-disable react-hooks/rules-of-hooks */
 import { useContext, useEffect, useState } from 'react'
 import { ChatEntry } from '../state/ChatEntry'
 import { ChatProperties, ChatState, MessageInterceptor } from '../state/ChatState'
@@ -9,6 +8,9 @@ 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
@@ -25,11 +27,19 @@ 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)
 }
 
+/**
+ * Watches the tabs of a ChatState. The value is updated whenever a tab is added, removed or selected.
+ */
 export function useChatTabs(): { chats: ChatState[], active: string } {
   const widget = useWidget()
   const [tabs, setTabs] = useState<{ chats: ChatState[], active: string }>({
@@ -40,6 +50,13 @@ export function useChatTabs(): { chats: ChatState[], active: string } {
   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)
@@ -47,21 +64,44 @@ export function useChat(chatId: string): ChatState {
   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)
 }
 
+/**
+ * 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,17 +112,32 @@ 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)
 }
 
+/**
+ * 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
 }
 
+/**
+ * This will create a new chat if none exists.
+ * @param interceptors the interceptors to add to the new chat.
+ */
 export function useFirstChat(interceptors: MessageInterceptor[]) {
   const widget = useWidget()
   const tabs = widget.chatTabs

package/src/features.ts

@@ -1,13 +1,41 @@
 export interface MessageInputFeatures {
+  /**
+   * Enables stack selection.
+   * @default true
+   */
   stack?: boolean,
+  /**
+   * Enables workspace selection.
+   * @default true
+   */
   workspace?: boolean,
+  /**
+   * Enables knowledge source selection.
+   * @default true
+   */
   knowledgeSource?: boolean,
+  /**
+   * Enables agent selection.
+   * @default true
+   */
   agent?: boolean,
+  /**
+   * Enables quick commands.
+   * @default true
+   */
   quickCommands?: boolean,
+  /**
+   * Enables the editor.
+   * @default true
+   */
   editor?: boolean,
 }
 
 export interface AIWidgetFeatures extends MessageInputFeatures {
+  /**
+   * Enables the chat history.
+   * @default true
+   */
   chatHistory?: boolean,
 }
 
@@ -18,4 +46,5 @@ export const defaultFeatures: AIWidgetFeatures = {
   agent: true,
   chatHistory: true,
   editor: true,
+  quickCommands: true,
 }

package/src/right-panel/DefaultPanel.tsx

@@ -3,9 +3,7 @@ import { Times } from '@citric/icons'
 import { IconButton } from '@citric/ui'
 import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
 import { styled } from 'styled-components'
-import { AutoFocus } from '../components/AutoFocus'
 import { WithChildren } from '../types'
-import { panelAnimationTime } from './constants'
 
 interface Props extends WithChildren {
   title: React.ReactNode,
@@ -42,22 +40,23 @@ const PanelBox = styled.div`
   }
 ` 
 
+/**
+ * Default layout for a right panel.
+ */
 export const DefaultPanel = ({ description, onClose, title, children }: Props) => {
   const t = useTranslate(dictionary)
 
   return (
     <PanelBox>
-      <AutoFocus delay={panelAnimationTime}>
-        <header>
-          <div className="title">
-            {typeof title === 'string' ? <Text appearance="h5">{title}</Text> : title}
-            {typeof description === 'string' ? <Text colorScheme="light.700">{description}</Text> : description}
-          </div>
-          <IconButton title={t.close} aria-label={t.close} onClick={onClose}>
-            <Times />
-          </IconButton>
-        </header>
-      </AutoFocus>
+      <header>
+        <div className="title">
+          {typeof title === 'string' ? <Text appearance="h5">{title}</Text> : title}
+          {typeof description === 'string' ? <Text colorScheme="light.700">{description}</Text> : description}
+        </div>
+        <IconButton title={t.close} aria-label={t.close} onClick={onClose}>
+          <Times />
+        </IconButton>
+      </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/hooks.tsx

@@ -9,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

package/src/state/ChatEntry.ts

@@ -3,10 +3,16 @@ import { pull } from 'lodash'
 import { LabeledWithImage } from './types'
 
 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,
 }
@@ -26,23 +32,61 @@ export interface KnowledgeSource {
 }
 
 export interface TextChatEntry {
+  /**
+   * "text" for simple unformatted paragraphs. "md" for markdown.
+   */
   type: 'text' | 'md',
+  /**
+   * 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 knowledge sources used to create the message.
+   */
   knowledgeSources?: KnowledgeSource[],
+  /**
+   * The date and time of the message. ISO string.
+   */
   updated?: string,
+  /**
+   * The agent who wrote the message. Undefined for the default agent or if the agentType is "user".
+   */
   agent?: LabeledWithImage,
+  /**
+   * 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,
 }
 
 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,13 +94,18 @@ 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
   }
 
+  /**
+   * Utility function to create a user entry.
+   * @param content the message's content.
+   * @param isMd whether or not this should be rendered as markdown.
+   * @returns a new ChatEntry.
+   */
   static createUserEntry(content: string, isMd = false) {
     return new ChatEntry({
       agentType: 'user',
@@ -66,6 +115,10 @@ export class ChatEntry {
     })
   }
 
+  /**
+   * 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: '' })
   }
@@ -79,6 +132,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 () => {