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

package/src/chat-interceptors/send-message.ts

@@ -1,9 +1,46 @@
 import { aiClient, StackspotAPIError } from '@stack-spot/portal-network'
-import { ChatEntry, KnowledgeSource } from '../state/ChatEntry'
+import { ChatResponse3 } from '@stack-spot/portal-network/api/ai'
+import { ChatEntry, KnowledgeSource, TextChatEntry } from '../state/ChatEntry'
 import { ChatState } from '../state/ChatState'
+import { LabeledWithImage } from '../state/types'
 import { buildConversationContext } from '../utils/chat'
 import { genericSourcesToKnowledgeSources } from '../utils/knowledge-source'
 
+/**
+ * Transforms a chat response from the backend into a chat entry that can be added to the chat.
+ * @param response the original response.
+ * @param knowledgeSources the knowledge sources already in format used by the chat.
+ * @param agent the current chat agent.
+ * @param includeDate whether or not to include the date in the chat entry.
+ * @returns the TextChatEntry to build a ChatEntry.
+ */
+function createEntryValueFromChatResponse(
+  response: Partial<ChatResponse3>,
+  knowledgeSources: KnowledgeSource[] | undefined,
+  agent: LabeledWithImage | undefined,
+  includeDate = false,
+): TextChatEntry {
+  return {
+    agentType: 'bot',
+    type: 'md',
+    content: response.answer ?? '',
+    messageId: response.message_id ?? undefined,
+    knowledgeSources,
+    agent: agent,
+    updated: includeDate ? new Date().toISOString() : undefined,
+  }
+}
+
+/**
+ * The chat interceptor that sends the message to the AI agent, interprets the response and adds it to the chat.
+ * 
+ * The message added to the chat is streamed, i.e. it changes over time, until it's completed.
+ * 
+ * @param entry the chat entry.
+ * @param chat the chat state.
+ * @param signal a signal that can be canceled by the user.
+ * @returns undefined
+ */
 export async function sendMessageInterceptor(entry: ChatEntry, chat: ChatState, signal: AbortSignal) {
   const { agentType, content } = entry.getValue()
   if (agentType !== 'user') return
@@ -20,18 +57,11 @@ export async function sendMessageInterceptor(entry: ChatEntry, chat: ChatState,
     if (value.sources?.length !== knowledgeSources?.length) {
       knowledgeSources = genericSourcesToKnowledgeSources(value.sources)
     }
-    botEntry.setValue({
-      agentType: 'bot',
-      type: 'md',
-      content: value.answer ?? '',
-      messageId: value.message_id ?? undefined,
-      knowledgeSources,
-      updated: new Date().toISOString(),
-      agent: chat.get('agent'),
-    })
+    botEntry.setValue(createEntryValueFromChatResponse(value, knowledgeSources, chat.get('agent')))
   })
   try {
-    await stream.getValue()
+    const finalValue = await stream.getValue()
+    botEntry.setValue(createEntryValueFromChatResponse(finalValue, knowledgeSources, chat.get('agent'), true))
     aiClient.chat.invalidate({ conversationId: chat.id })
     if (isFirstMessage) aiClient.chats.invalidate()
   } catch (error: any) {

package/src/components/Accordion.tsx

@@ -9,7 +9,14 @@ import { styled } from 'styled-components'
 import { WithChildren } from '../types'
 
 interface Props extends WithStyle, Required<WithChildren> {
+  /**
+   * The header of the accordion (always rendered). The body (hidden part) must be passed as the children.
+   */
   header: React.ReactNode,
+  /**
+   * Whether or not to start expanded.
+   * @default false
+   */
   startExpanded?: boolean,
 }
 
@@ -48,6 +55,9 @@ const StyledAccordion = styled.div`
   }
 `
 
+/**
+ * A component that can have it's content shown or hidden (animated).
+ */
 export const Accordion = ({ children, header, className, startExpanded, style }: Props) => {
   const [expanded, setExpanded] = useState(startExpanded)
   return (

package/src/components/AdaptiveTextArea.tsx

@@ -1,15 +1,32 @@
+/* eslint-disable react/display-name */
 import { Textarea } from '@citric/core'
-import { useEffect, useRef } from 'react'
+import { forwardRef, useEffect, useRef } from 'react'
 import { PropsOf } from '../types'
 
 interface Props extends PropsOf<typeof Textarea> {
+  /**
+   * A function to run whenever the height of the text area increases.
+   */
   onIncreaseSize?: () => void,
+  /**
+   * A function to run whenever the text area value becomes empty.
+   */
   onResetSize?: () => void,
+  /**
+   * The maximum height this textarea can get to.
+   */
   maxHeight?: number,
 }
 
-export const AdaptiveTextArea = ({ value, onIncreaseSize, onResetSize, maxHeight, style, ...props }: Props) => {
-  const ref = useRef<HTMLTextAreaElement>(null)
+/**
+ * The adaptive textarea grows in height whenever needed until the maximum height is reached.
+ */
+export const AdaptiveTextArea = forwardRef<HTMLTextAreaElement, Props>((
+  { value, onIncreaseSize, onResetSize, maxHeight, style, ...props },
+  externalRef,
+) => {
+  const localRef = useRef<HTMLTextAreaElement>(null)
+  const ref = externalRef as React.RefObject<HTMLTextAreaElement> ?? localRef
 
   useEffect(() => {
     if (!ref.current) return
@@ -31,4 +48,4 @@ export const AdaptiveTextArea = ({ value, onIncreaseSize, onResetSize, maxHeight
   }, [value, maxHeight])
 
   return <Textarea {...props} ref={ref} value={value} style={{ ...style, maxHeight }} />
-}
+})

package/src/components/AutoFocus.tsx

@@ -0,0 +1,34 @@
+/* eslint-disable react/display-name */
+import { focusFirstChild, TagPriorityElement } from '@stack-spot/portal-components'
+import { forwardRef, RefObject, useEffect, useRef } from 'react'
+
+interface Props extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * A delay in ms to focus the first focusable element.
+   */
+  delay?: number,
+  /**
+   * Instead of focusing the first element overall, focus the first according to this list of priorities.
+   * 
+   * 'other' means elements that are normally not focusable, but have positive tabIndex values.
+   */
+  priority?: TagPriorityElement[],
+  /**
+   * Ignores any element that matches this query selector.
+   */
+  ignore?: string,
+}
+
+/**
+ * Focus the first focusable child as soon as the component mounts.
+ */
+export const AutoFocus = forwardRef<HTMLDivElement, Props>(({ children, delay = 0, priority, ignore, ...props }, externalRef) => {
+  const localRef = useRef<HTMLDivElement>(null)
+  const ref = externalRef as RefObject<HTMLDivElement> ?? localRef
+
+  useEffect(() => {
+    setTimeout(() => focusFirstChild(ref.current, { priority, ignore }), delay)
+  }, [])
+
+  return <div ref={ref} {...props}>{children}</div>
+})

package/src/components/Fading.tsx

@@ -0,0 +1,66 @@
+/* eslint-disable react/display-name */
+import { WithStyle } from '@stack-spot/portal-theme'
+import { forwardRef, useEffect, useRef, useState } from 'react'
+import { WithChildren } from '../types'
+
+interface Props extends WithChildren, WithStyle {
+  /**
+   * Whether or not the content is visible.
+   */
+  visible: boolean,
+  /**
+   * Duration of the animation in ms.
+   * @default 300
+   */
+  duration?: number,
+  /**
+   * Function to run right before animation to show the content starts.
+   */
+  beforeFadeIn?: () => void,
+  /**
+   * Function to run right before animation to hide the content starts.
+   */
+  beforeFadeOut?: () => void,
+  /**
+   * Function to run right after the animation to show the content ends.
+   */
+  afterFadeIn?: () => void,
+  /**
+   * Function to run right after the animation to hide the content ends.
+   */
+  afterFadeOut?: () => void,
+}
+
+export const Fading = forwardRef<HTMLDivElement, Props>((
+  { visible, children, duration = 300, afterFadeIn, afterFadeOut, beforeFadeIn, beforeFadeOut, className, style },
+  ref,
+) => {
+  const [isOpaque, setOpaque] = useState(visible)
+  const [isRendered, setRendered] = useState(visible)
+  const previous = useRef(visible)
+  const timeout = useRef<number[]>([])
+  const opacity: React.CSSProperties = { transition: `opacity ${duration / 1000}s`, opacity: isOpaque ? 1 : 0 }
+
+  useEffect(() => {
+    if (previous.current === visible) return
+    timeout.current.forEach(window.clearTimeout)
+    timeout.current = []
+    if (visible) {
+      setRendered(true)
+      if (afterFadeIn) timeout.current.push(window.setTimeout(afterFadeIn, duration))
+      beforeFadeIn?.()
+      timeout.current.push(window.setTimeout(() => setOpaque(true), 0))
+      
+    } else {
+      setOpaque(false)
+      beforeFadeOut?.()
+      timeout.current.push(window.setTimeout(() => {
+        setRendered(false)
+        afterFadeOut?.()
+      }, duration))
+    }
+    previous.current = visible
+  }, [visible])
+
+  return isRendered ? <div ref={ref} className={className} style={{ ...style, ...opacity }}>{children}</div> : null
+})

package/src/components/FadingOverflow.tsx

@@ -10,12 +10,38 @@ type Side = 'top' | 'right' | 'left' | 'bottom'
 type ScrollType = 'none' | 'wheel' | 'bar' | 'arrows'
 
 interface Props extends WithChildren, WithStyle {
+  /**
+   * How to scroll the content.
+   * - none: overflow is hidden. No scrolling.
+   * - wheel: the content is solely scrollable through the mouse wheel and keyboard arrows, no scroll bars are rendered.
+   * - bar: this is the normal browser scroll. The content will be scrollable through the mouse wheel, keyboard and scrollbar.
+   * - arrows: arrows will be placed in the far edges of the sides that must be scrolled. The content is scrolled through the mouse wheel,
+   * keyboard and these arrows. Hovering an arrow slowly scrolls the content, clicking the arrow fully scrolls the content in its direction.
+   * There are no scrollbars in this scenario.
+   * @default 'none'
+   */
   scroll?: ScrollType,
+  /**
+   * If true, a horizontal scroll can be performed by using the vertical mouse wheel.
+   * @default false
+   */
   enableHorizontalScrollWithVerticalWheel?: boolean,
+  /**
+   * Which sides to fade when the content overflows.
+   * 
+   * Important: it seems the current solution doesn't support mixing vertical and horizontal scrolls. I'm not sure if this is possible, I
+   * believed combining linear gradients would work, but it doesn't.
+   */
   sides?: Side[],
 }
 
+// Scrolling can be very fast, this sets a lower limit for us to run listeners without impacting performance.
 const MIN_CHECK_INTERVAL_MS = 20
+// The interval which to scroll the content when a scroll arrow is hovered.
+const SCROLL_INTERVAL_MS = 20
+// This sets the speed of the scroll when the user hovers a scroll arrow.
+const SCROLL_PX = 4
+// Fade masks
 const masks = {
   right: 'linear-gradient(to left, rgb(0, 0, 0, 0) 0%, rgb(0, 0, 0) min(30%, 100px), rgba(0, 0, 0) 100%)',
   left: 'linear-gradient(to right, rgb(0, 0, 0, 0) 0%, rgb(0, 0, 0) min(30%, 100px), rgba(0, 0, 0) 100%)',
@@ -95,9 +121,11 @@ const OverflowBox = styled.div`
   }
 `
 
-const SCROLL_INTERVAL_MS = 20
-const SCROLL_PX = 4
-
+/**
+ * This component applies a fading graphical effect to its content if it overflows in any of the sides specified by the props.
+ * 
+ * This also controls how this overflow is scrolled, introducing a new scrolling technique, which applies arrows to the overflowing side.
+ */
 export const FadingOverflow = (
   { children, scroll = 'none', sides, enableHorizontalScrollWithVerticalWheel, className, ...props }: Props,
 ) => {

package/src/components/FallbackBoundary/ErrorBoundary.tsx

@@ -1,15 +1,29 @@
+import { IconBox, Text } from '@citric/core'
+import { TimesCircle } from '@citric/icons'
 import { ErrorDescription, ErrorFeedback } from '@stack-spot/portal-components/error'
 import { StackspotAPIError } from '@stack-spot/portal-network'
 import { Component } from 'react'
+import { styled } from 'styled-components'
 
 interface State extends ErrorDescription {
   hasError: boolean,
 }
 
 interface Props {
+  mini?: boolean,
+  message?: string,
   children: React.ReactNode,
 }
 
+const ErrorBox = styled.div`
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+`
+
 /**
  * An Error Boundary that renders an ErrorFeedback instead of its content if any of its children throws.
  * 
@@ -40,9 +54,18 @@ export class ErrorBoundary extends Component<Props, State> {
     if (this.props.children !== prevProps.children) this.setState({ hasError: false })
   }
 
+  private renderError() {
+    return this.props.mini
+      ? (
+        <ErrorBox className="error">
+          <IconBox size="lg" colorIcon="danger.500"><TimesCircle /></IconBox>
+          <Text colorScheme="light.700">{this.props.message || this.state.message}</Text>
+        </ErrorBox>
+      )
+      : <ErrorFeedback className="error" code={this.state.code} message={this.props.message || this.state.message} />
+  }
+
   render() {
-    return this.state.hasError
-      ? <ErrorFeedback code={this.state.code} message={this.state.message} />
-      : this.props.children
+    return this.state.hasError ? this.renderError() : this.props.children
   }
 }

package/src/components/FallbackBoundary/Loading.tsx

@@ -10,5 +10,5 @@ const LoadingBox = styled.div`
 `
 
 export const Loading = () => (
-  <LoadingBox><LoadingCircular /></LoadingBox>
+  <LoadingBox className="loading"><LoadingCircular /></LoadingBox>
 )

package/src/components/FallbackBoundary/index.tsx

@@ -3,11 +3,22 @@ import { WithChildren } from '../../types'
 import { ErrorBoundary } from './ErrorBoundary'
 import { Loading } from './Loading'
 
+interface Props extends WithChildren {
+  /**
+   * Use this to show errors in small spaces.
+   */
+  mini?: boolean,
+  /**
+   * Replaces the error message with this text.
+   */
+  message?: string,
+}
+
 /**
  * Fallbacks for errors and loadings (suspense).
  */
-export const FallbackBoundary = ({ children }: WithChildren) => (
-  <ErrorBoundary>
+export const FallbackBoundary = ({ children, mini, message }: Props) => (
+  <ErrorBoundary mini={mini} message={message}>
     <Suspense fallback={<Loading />}>
       {children}
     </Suspense>

package/src/components/HistoryList.tsx

@@ -1,4 +1,3 @@
-/* eslint-disable no-empty-pattern */
 import { Text } from '@citric/core'
 import { theme, WithStyle } from '@stack-spot/portal-theme'
 import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
@@ -10,9 +9,21 @@ import { subtractDays } from '../utils/date'
 type HistorySectionName = 'today' | 'yesterday' | 'last7' | 'last30' | 'older'
 
 interface Props<T> extends WithStyle {
+  /**
+   * The items in the history.
+   */
   items: T[],
+  /**
+   * A function to render an item.
+   */
   renderItem: (item: T) => React.ReactNode,
+  /**
+   * A function that returns the date of the item.
+   */
   getDate: (item: T) => Date,
+  /**
+   * A function that returns a unique id for the item.
+   */
   keygen: (item: T) => React.Key,
 }
 
@@ -53,6 +64,9 @@ function dateToSectionName(date: Date): HistorySectionName {
   return date.getTime() >= last30Days.getTime() ? 'last30' : 'older'
 }
 
+/**
+ * Renders a history list, where the items are combined into sections according to their dates.
+ */
 export function HistoryList<T>({ getDate, items, keygen, className, style, renderItem }: Props<T>) {
   const t = useTranslate(dictionary)
   const sections = useMemo(() => {

package/src/components/IconInput.tsx

@@ -47,6 +47,9 @@ const InputBox = styled.div`
   }
 `
 
+/**
+ * A text input with an icon at the left side.
+ */
 export const IconInput = ({ icon, onChange, style, className, disabled, onFocus, onBlur, ...props }: Props) => {
   const [focused, setFocused] = useState(false)
 

package/src/components/OverlayMenu.tsx

@@ -1,7 +1,8 @@
-/* eslint-disable no-empty-pattern */
+/* eslint-disable react/display-name */
 import { IconBox, Text } from '@citric/core'
+import { useKeyboardControls } from '@stack-spot/portal-components'
 import { theme, WithStyle } from '@stack-spot/portal-theme'
-import { useMemo } from 'react'
+import { forwardRef, RefObject, useCallback, useRef } from 'react'
 import { styled } from 'styled-components'
 import { ButtonAction, WithChildren } from '../types'
 import { Tooltip } from './Tooltip'
@@ -9,10 +10,27 @@ import { useTooltip } from './Tooltip/context'
 import { TooltipPosition } from './Tooltip/types'
 
 interface Props extends WithStyle, WithChildren {
+  /**
+   * The position of the menu relative to its children.
+   */
   position?: TooltipPosition,
+  /**
+   * The actions of the menu.
+   */
   actions: ButtonAction[],
 }
 
+interface MenuProps {
+  /**
+   * The actions of the menu.
+   */
+  actions: ButtonAction[],
+  /**
+   * A reference to the HTML element that triggered the menu.
+   */
+  trigger: RefObject<HTMLDivElement>,
+}
+
 const MenuList = styled.ul`
   margin: 0;
   padding: 0;
@@ -37,8 +55,9 @@ const MenuList = styled.ul`
       gap: 8px;
       background-color: transparent;
       border: none;
+      outline: none;
 
-      &:hover {
+      &:hover, &:focus {
         background-color: ${theme.color.light[500]};
       }
     }
@@ -53,25 +72,62 @@ const StyledButton = styled.button<{ $color: string | undefined }>`
   }
 `
 
-export const OverlayMenu = ({ actions, children, className, position, style }: Props) => {
+const Menu = ({ actions, trigger }: MenuProps) => {
   const tooltip = useTooltip()
-  const menu = useMemo(() => {
-    const items = actions.map(({ label, onClick, className, color, icon, style }) => (
-      <li key={label} className={className} style={style}>
-        <StyledButton $color={color} onClick={() => {
-          onClick()
-          tooltip.hide()
-        }}>
-          <IconBox>{icon}</IconBox>
-          <Text>{label}</Text>
-        </StyledButton>
-      </li>
-    ))
-    return <MenuList>{items}</MenuList>
-  }, [actions])
+  const ref = useRef<HTMLUListElement>(null)
+
+  useKeyboardControls({
+    querySelectors: 'button',
+    onPressEscape: () => {
+      tooltip.hide()
+      trigger.current?.focus()
+    },
+    ref,
+  }, [])
+
   return (
-    <Tooltip content={menu} custom position={position} className={className} style={style} triggeredBy="click">
+    <MenuList ref={ref}>
+      {actions.map(({ label, onClick, className, color, icon, style }) => (
+        <li key={label} className={className} style={style}>
+          <StyledButton $color={color} onClick={() => {
+            onClick()
+            tooltip.hide()
+          }}>
+            <IconBox>{icon}</IconBox>
+            <Text>{label}</Text>
+          </StyledButton>
+        </li>
+      ))}
+    </MenuList>
+  )
+}
+
+/**
+ * A floating menu that shows up when the user clicks the children.
+ * 
+ * This uses the tooltip component to build the menu.
+ */
+export const OverlayMenu = forwardRef<HTMLDivElement, Props>(({ actions, children, className, position, style }, externalRef) => {
+  const localRef = useRef<HTMLDivElement>(null)
+  const ref = externalRef as RefObject<HTMLDivElement> ?? localRef
+  const tooltip = useTooltip()
+
+  const onShow = useCallback(() => {
+    tooltip.tooltipRef.current?.querySelector('button')?.focus()
+  }, [])
+
+  return (
+    <Tooltip
+      content={<Menu actions={actions} trigger={ref} />}
+      custom
+      position={position}
+      className={className}
+      style={style}
+      triggeredBy="click"
+      onShow={onShow}
+      ref={ref}
+    >
       {children}
     </Tooltip>
   )
-}
+})

package/src/components/ProgressBar.tsx

@@ -2,10 +2,28 @@ import { listToClass, theme, WithStyle } from '@stack-spot/portal-theme'
 import { styled } from 'styled-components'
 
 interface Props extends WithStyle {
+  /**
+   * Whether or not the progress bar is visible.
+   */
   visible?: boolean,
+  /**
+   * When true, the progress bar becomes very colorful and bright.
+   */
   shimmer?: boolean,
+  /**
+   * Color to use in the progress bar that appears in the foreground. Arrays create linear gradients.
+   * @default primary.500 if shimmer is false, white otherwise.
+   */
   foregroundColor?: string | string[],
+  /**
+   * Color to use in the progress bar that appears in the background. Arrays create linear gradients.
+   * @default light.500 if shimmer is false, a transparent white otherwise.
+   */
   backgroundColor?: string | string[],
+  /**
+   * Only useful if `shimmer` is true. This allows to customize the colors in the shimmering effect. Arrays create linear gradients.
+   * @default ['#ff6633', '#d668cd', '#ff6633', '#FFF8', '#299cf4']
+   */
   shimmerColor?: string | string[],
 }
 
@@ -21,6 +39,7 @@ function gradientFromColorArray(colors: string[]) {
   return `linear-gradient(to right, ${partials.join(', ')})`
 }
 
+// the shimmering effect requires more space
 const SHIMMER_PADDING = '10px'
 
 const Styled = styled.div<{ $bg: string[], $fg: string[], $shimmer: string[] }>`
@@ -123,6 +142,10 @@ const Styled = styled.div<{ $bg: string[], $fg: string[], $shimmer: string[] }>`
   }
 `
 
+/**
+ * A progress bar with indefinite progress report. This renders a narrower bar on top of larger one that animates from the left to the
+ * right.
+ */
 export const ProgressBar = ({
   visible = true,
   shimmer,

package/src/components/QuickStartButton.tsx

@@ -7,6 +7,9 @@ interface Props extends ButtonAction, WithStyle {
   background?: string,
 }
 
+/**
+ * A button for quick starting a conversation.
+ */
 const QuickButton = styled.button<{ $color?: string, $bg?: string }>`
   display: flex;
   flex-direction: column;

package/src/components/RightPanelForm.tsx

@@ -1,6 +1,7 @@
 import { Card } from '@citric/ui'
 import { styled } from 'styled-components'
 import { PropsOf } from '../types'
+import { AutoFocus } from './AutoFocus'
 import { FallbackBoundary } from './FallbackBoundary'
 
 const Form = styled.form`
@@ -40,16 +41,21 @@ const Form = styled.form`
   }
 `
 
+/**
+ * A form that goes into a right panel. This controls style, errors, loading focus and form submission.
+ */
 export const RightPanelForm = ({ children, onSubmit, ...props }: PropsOf<typeof Form>) => (
   <FallbackBoundary>
-    <Form
-      {...props}
-      onSubmit={(e) => {
-        e.preventDefault()
-        onSubmit?.(e)
-      }}
-    >
-      {children}
-    </Form>
+    <AutoFocus>
+      <Form
+        {...props}
+        onSubmit={(e) => {
+          e.preventDefault()
+          onSubmit?.(e)
+        }}
+      >
+        {children}
+      </Form>
+    </AutoFocus>
   </FallbackBoundary>
 )

package/src/components/RightPanelTabs.tsx

@@ -24,6 +24,9 @@ const StyledTabsItem = styled(TabsItem)`
   overflow: hidden;
 `
 
+/**
+ * Tabs for the right panel content.
+ */
 export const RightPanelTabs = ({ tabs }: Props) => {
   const [currentTab, setCurrentTab] = useState(0)
   const tabItems = useMemo(() => tabs.map(({ content, title }) => (