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

package/src/components/TabManager.tsx

@@ -41,7 +41,9 @@ interface Props<T, Key extends React.Key> {
   renderLabel: (tab: T) => React.ReactElement,
 }
 
+// The size of extra buttons placed after the tabs.
 const EXTRA_BTN_SIZE = 24
+// The margin of extra buttons placed after the tabs.
 const EXTRA_BTN_MARGIN = 8
 
 const Tabs = styled.nav<{ $numberOfExtraButtons: number }>`
@@ -161,6 +163,12 @@ const Tabs = styled.nav<{ $numberOfExtraButtons: number }>`
   }
 `
 
+/**
+ * Renders and manages a list of tabs. With this, tabs can be selected and removed. Furthermore, extra buttons can be placed after all tabs,
+ * e.g. a button to add more tabs.
+ * 
+ * Used for the chat tabs.
+ */
 export function TabManager<T, Key extends React.Key>(
   { active, tabs, keygen, onRemove, onSelect, renderLabel, buttons = [] }: Props<T, Key>,
 ) {

package/src/components/Tooltip/Tooltip.tsx

@@ -1,36 +1,78 @@
+/* eslint-disable react/display-name */
 import { Text } from '@citric/core'
 import { WithStyle } from '@stack-spot/portal-theme'
+import { forwardRef } from 'react'
 import { WithChildren } from '../../types'
 import { useTooltip } from './context'
 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,
 }
 
-export const Tooltip = ({ content, custom, position, triggeredBy = 'hover', children, className, style }: Props) => {
+/**
+ * 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,
+) => {
   const api = useTooltip()
 
-  function show(e: React.MouseEvent<HTMLDivElement, MouseEvent>, hideOnClickOutside?: boolean) {
-    api.show({
+  async function show(e: React.UIEvent, hideOnClickOutside?: boolean) {
+    await api.show({
       content: custom ? content : <DefaultTooltip><Text appearance="microtext1">{content}</Text></DefaultTooltip>,
       anchor: e.target as HTMLElement,
       position,
       hideOnClickOutside,
     })
+    onShow?.()
   }
+
+  function hide() {
+    api.hide()
+    onHide?.()
+  }
+
   return (
     <div
-      {...(triggeredBy === 'hover' ? { onMouseEnter: show, onMouseLeave: () => api.hide() } : { onClick: (e) => show(e, true) })}
+      {...(triggeredBy === 'hover'
+        ? { onMouseEnter: show, onMouseLeave: hide }
+        : { onClick: (e) => show(e, true), onKeyDown: (e) => e.key === 'Enter' && show(e, true) }
+      )}
       className={className}
       style={style}
       tabIndex={triggeredBy === 'click' ? 0 : undefined}
+      role={triggeredBy === 'click' ? 'button' : undefined}
+      ref={ref}
     >
       {children}
     </div>
   )
-}
+})

package/src/components/Tooltip/TooltipAPI.ts

@@ -1,14 +1,26 @@
+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 {
-  private tooltipRef: React.RefObject<HTMLDivElement>
+  /**
+   * 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
   private clickListener: ((e: MouseEvent) => void) | undefined
@@ -27,54 +39,59 @@ export class TooltipAPI {
     }
   }
 
-  show({ content, anchor, position = 'bottom', hideOnClickOutside }: ShowOptions): void {
+  /**
+   * 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
     if (this.clickListener) document.removeEventListener('click', this.clickListener)
     this.setContent(content)
-    setTimeout(() => {
-      if (!this.tooltipRef.current) return
-      const anchorRect = anchor.getClientRects()[0]
-      this.tooltipRef.current.classList.add('visible')
-      const tooltipWidth = this.tooltipRef.current.clientWidth
-      const tooltipHeight = this.tooltipRef.current.clientHeight
-      let top = 0
-      let left = 0
-      if (position === 'left' || position === 'right') {
-        top = anchorRect.top + anchorRect.height / 2 - tooltipHeight / 2
-        if (position === 'left') left = anchorRect.left - tooltipWidth
-        else left = anchorRect.left + anchorRect.width
-      } else {
-        left = anchorRect.left + anchorRect.width / 2 - tooltipWidth / 2
-        if (position === 'top') top = anchorRect.top - tooltipHeight
-        else top = anchorRect.top + anchorRect.height
-      }
-      // takes the parent the tooltip is positioned relative to into consideration
-      this.computeRelativeTo()
-      const relativeRect = this.relativeTo?.getClientRects()[0] ?? { top: 0, left: 0 }
-      top -= relativeRect.top
-      left -= relativeRect.left
-      // adjusts positions in order to avoid overflowing the window and leaving a margin to the corners
-      if (top <= 0) top += MARGIN_TO_CORNERS_PX
-      else if (top + tooltipHeight >= document.body.clientHeight - MARGIN_TO_CORNERS_PX) {
-        top = document.body.clientHeight - MARGIN_TO_CORNERS_PX + tooltipHeight
-      }
-      if (left <= 0) left += MARGIN_TO_CORNERS_PX
-      else if (left + tooltipWidth >= document.body.clientWidth - MARGIN_TO_CORNERS_PX) {
-        left = document.body.clientWidth - MARGIN_TO_CORNERS_PX - tooltipWidth
-      }
-      this.tooltipRef.current.style.top = `${top}px`
-      this.tooltipRef.current.style.left = `${left}px`
-      if (hideOnClickOutside) {
-        this.clickListener = (e: MouseEvent) => {
-          if (this.tooltipRef.current?.contains(e.target as HTMLElement)) return
-          this.hide()
-        }
-        document.addEventListener('click', this.clickListener)
+    await delay(10)
+    if (!this.tooltipRef.current) return
+    const anchorRect = anchor.getClientRects()[0]
+    this.tooltipRef.current.classList.add('visible')
+    const tooltipWidth = this.tooltipRef.current.clientWidth
+    const tooltipHeight = this.tooltipRef.current.clientHeight
+    let top = 0
+    let left = 0
+    if (position === 'left' || position === 'right') {
+      top = anchorRect.top + anchorRect.height / 2 - tooltipHeight / 2
+      if (position === 'left') left = anchorRect.left - tooltipWidth
+      else left = anchorRect.left + anchorRect.width
+    } else {
+      left = anchorRect.left + anchorRect.width / 2 - tooltipWidth / 2
+      if (position === 'top') top = anchorRect.top - tooltipHeight
+      else top = anchorRect.top + anchorRect.height
+    }
+    // takes the parent the tooltip is positioned relative to into consideration
+    this.computeRelativeTo()
+    const relativeRect = this.relativeTo?.getClientRects()[0] ?? { top: 0, left: 0 }
+    top -= relativeRect.top
+    left -= relativeRect.left
+    // adjusts positions in order to avoid overflowing the window and leaving a margin to the corners
+    if (top <= 0) top += MARGIN_TO_CORNERS_PX
+    else if (top + tooltipHeight >= document.body.clientHeight - MARGIN_TO_CORNERS_PX) {
+      top = document.body.clientHeight - MARGIN_TO_CORNERS_PX + tooltipHeight
+    }
+    if (left <= 0) left += MARGIN_TO_CORNERS_PX
+    else if (left + tooltipWidth >= document.body.clientWidth - MARGIN_TO_CORNERS_PX) {
+      left = document.body.clientWidth - MARGIN_TO_CORNERS_PX - tooltipWidth
+    }
+    this.tooltipRef.current.style.top = `${top}px`
+    this.tooltipRef.current.style.left = `${left}px`
+    if (hideOnClickOutside) {
+      this.clickListener = (e: MouseEvent) => {
+        if (this.tooltipRef.current?.contains(e.target as HTMLElement)) return
+        this.hide()
       }
-    }, 10)
+      document.addEventListener('click', this.clickListener)
+    }
   }
 
+  /**
+   * 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/layout.css

@@ -73,6 +73,11 @@
         display: none;
       }
     }
+    .quick-command-selector {
+      width: auto;
+      left: 10px;
+      right: 10px;
+    }
   }
 }
 

package/src/regex.ts

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

package/src/right-panel/DefaultPanel.tsx

@@ -40,8 +40,12 @@ 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>

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

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() {