@cognigy/chat-components-vue 0.1.0

package/src/composables/useCollation.ts

@@ -0,0 +1,163 @@
+/**
+ * useCollation composable
+ * Collates consecutive bot messages into single messages for streaming output
+ *
+ * When `collateStreamedOutputs` is enabled in config, consecutive bot messages
+ * are grouped together so they appear as a single message with combined text.
+ */
+
+import { computed, type ComputedRef, toValue, type MaybeRefOrGetter } from 'vue'
+import type { IMessage } from '@cognigy/socket-client'
+import type { ChatConfig } from '../types'
+
+/**
+ * A message that may have been collated from multiple bot messages.
+ * When collated, text becomes an array and collatedFrom contains the originals.
+ */
+export type CollatedMessage = IMessage & {
+  /**
+   * Original messages that were collated into this one (only present if collated)
+   */
+  collatedFrom?: IMessage[]
+}
+
+export interface UseCollationReturn {
+  /**
+   * Messages with consecutive bot messages collated
+   */
+  collatedMessages: ComputedRef<CollatedMessage[]>
+
+  /**
+   * Whether collation is currently enabled
+   */
+  isCollationEnabled: ComputedRef<boolean>
+
+  /**
+   * Original message count
+   */
+  originalCount: ComputedRef<number>
+
+  /**
+   * Collated message count
+   */
+  collatedCount: ComputedRef<number>
+}
+
+/**
+ * Check if two messages can be collated together
+ */
+function canCollate(current: IMessage, previous: IMessage): boolean {
+  // Must both be bot messages
+  if (current.source !== 'bot' || previous.source !== 'bot') {
+    return false
+  }
+
+  // Must both be simple text messages (no rich content)
+  if (current.data?._cognigy?._webchat || previous.data?._cognigy?._webchat) {
+    return false
+  }
+
+  // Must both have text
+  if (!current.text || !previous.text) {
+    return false
+  }
+
+  // Don't collate if either has attachments
+  if (current.data?.attachments || previous.data?.attachments) {
+    return false
+  }
+
+  // Don't collate plugin messages
+  if (current.data?._plugin || previous.data?._plugin) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Collate consecutive bot messages into combined messages
+ *
+ * @param messages - Array of messages (can be ref, getter, or plain value)
+ * @param config - Chat configuration (can be ref, getter, or plain value)
+ * @returns Reactive collated messages
+ *
+ * @example
+ * ```ts
+ * const { collatedMessages, isCollationEnabled } = useCollation(messages, config)
+ *
+ * // Use in template
+ * <Message v-for="msg in collatedMessages" :key="msg.traceId" :message="msg" />
+ * ```
+ */
+export function useCollation(
+  messages: MaybeRefOrGetter<IMessage[]>,
+  config?: MaybeRefOrGetter<ChatConfig | undefined>
+): UseCollationReturn {
+  const isCollationEnabled = computed(() => {
+    const cfg = toValue(config)
+    return cfg?.settings?.behavior?.collateStreamedOutputs === true
+  })
+
+  const collatedMessages = computed<CollatedMessage[]>(() => {
+    const msgs = toValue(messages)
+    const enabled = isCollationEnabled.value
+
+    if (!enabled || !msgs || msgs.length === 0) {
+      return msgs as CollatedMessage[]
+    }
+
+    const result: CollatedMessage[] = []
+
+    for (let i = 0; i < msgs.length; i++) {
+      const current = msgs[i]
+
+      // Check if we can collate with the last message in result
+      if (result.length > 0) {
+        const lastCollated = result[result.length - 1]
+        const lastOriginal = lastCollated.collatedFrom
+          ? lastCollated.collatedFrom[lastCollated.collatedFrom.length - 1]
+          : lastCollated
+
+        if (canCollate(current, lastOriginal)) {
+          // Collate: combine texts with newline separator
+          const existingText = lastCollated.text ?? ''
+          const currentText = current.text ?? ''
+
+          const collatedFrom = lastCollated.collatedFrom
+            ? [...lastCollated.collatedFrom, current]
+            : [lastOriginal, current]
+
+          // Update the last message with combined text (joined by newline)
+          result[result.length - 1] = {
+            ...lastCollated,
+            text: existingText + '\n' + currentText,
+            collatedFrom,
+          }
+          continue
+        }
+      }
+
+      // Can't collate, add as new message
+      result.push(current as CollatedMessage)
+    }
+
+    return result
+  })
+
+  const originalCount = computed(() => {
+    const msgs = toValue(messages)
+    return msgs?.length ?? 0
+  })
+
+  const collatedCount = computed(() => {
+    return collatedMessages.value.length
+  })
+
+  return {
+    collatedMessages,
+    isCollationEnabled,
+    originalCount,
+    collatedCount,
+  }
+}

package/src/composables/useImageContext.ts

@@ -0,0 +1,27 @@
+import { inject, provide, InjectionKey, ComputedRef } from 'vue'
+import type { IWebchatButton } from '../types'
+
+export interface ImageContext {
+  onExpand: () => void
+  onClose: () => void
+  url: string
+  altText?: string
+  button?: IWebchatButton
+  isDownloadable: ComputedRef<boolean>
+}
+
+export const ImageContextKey: InjectionKey<ImageContext> = Symbol('ImageContext')
+
+export function provideImageContext(context: ImageContext) {
+  provide(ImageContextKey, context)
+}
+
+export function useImageContext() {
+  const context = inject(ImageContextKey)
+
+  if (!context) {
+    throw new Error('useImageContext must be used within an ImageMessage component')
+  }
+
+  return context
+}

package/src/composables/useMessageContext.ts

@@ -0,0 +1,41 @@
+/**
+ * Message context composable
+ * Provides message context to child components using Vue's provide/inject
+ */
+
+import { inject, provide, type InjectionKey } from 'vue'
+import type { MessageContext } from '../types'
+
+// Injection key for message context
+export const MessageContextKey: InjectionKey<MessageContext> = Symbol('MessageContext')
+
+/**
+ * Provide message context to child components
+ * @param context - Message context to provide
+ */
+export function provideMessageContext(context: MessageContext) {
+  provide(MessageContextKey, context)
+}
+
+/**
+ * Use message context in a child component
+ * @returns Message context or throws error if not provided
+ */
+export function useMessageContext(): MessageContext {
+  const context = inject(MessageContextKey)
+
+  if (!context) {
+    console.error('useMessageContext: Context not provided. Make sure component is wrapped in MessageProvider.')
+    throw new Error('useMessageContext must be used within a message context provider')
+  }
+
+  return context
+}
+
+/**
+ * Use message context with optional fallback
+ * @returns Message context or undefined if not provided
+ */
+export function useMessageContextOptional(): MessageContext | undefined {
+  return inject(MessageContextKey, undefined)
+}

package/src/composables/useSanitize.ts

@@ -0,0 +1,25 @@
+/**
+ * HTML sanitization composable
+ * Uses message context for config
+ */
+
+import { computed } from 'vue'
+import { useMessageContext } from './useMessageContext'
+import { sanitizeHTMLWithConfig } from '../utils/sanitize'
+
+export function useSanitize() {
+  const { config } = useMessageContext()
+
+  const isSanitizeEnabled = computed(() => !config?.settings?.layout?.disableHtmlContentSanitization)
+  const customAllowedHtmlTags = computed(() => config?.settings?.widgetSettings?.customAllowedHtmlTags)
+
+  const processHTML = (text: string): string => {
+    if (!isSanitizeEnabled.value) return text
+    return sanitizeHTMLWithConfig(text, customAllowedHtmlTags.value)
+  }
+
+  return {
+    processHTML,
+    isSanitizeEnabled,
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Main entry point for @cognigy/chat-components-vue
+ * Exports all public components, composables, and utilities
+ */
+
+// Main Component
+export { default as Message } from './components/Message.vue'
+
+// Common Components
+export { default as TypingIndicator } from './components/common/TypingIndicator.vue'
+export { default as ChatEvent } from './components/common/ChatEvent.vue'
+export { default as Typography } from './components/common/Typography.vue'
+export { default as ActionButtons } from './components/common/ActionButtons.vue'
+export { default as ActionButton } from './components/common/ActionButton.vue'
+export { default as ChatBubble } from './components/common/ChatBubble.vue'
+
+// Message Types
+export { default as TextMessage } from './components/messages/TextMessage.vue'
+export { default as ImageMessage } from './components/messages/ImageMessage.vue'
+export { default as VideoMessage } from './components/messages/VideoMessage.vue'
+export { default as AudioMessage } from './components/messages/AudioMessage.vue'
+export { default as TextWithButtons } from './components/messages/TextWithButtons.vue'
+export { default as Gallery } from './components/messages/Gallery.vue'
+export { default as List } from './components/messages/List.vue'
+export { default as FileMessage } from './components/messages/FileMessage.vue'
+export { default as DatePicker } from './components/messages/DatePicker.vue'
+export { default as AdaptiveCard } from './components/messages/AdaptiveCard.vue'
+
+// Components to be exported as they are created:
+// export { default as Message } from './components/Message.vue'
+
+// Composables
+export { useMessageContext, useMessageContextOptional, provideMessageContext, MessageContextKey } from './composables/useMessageContext'
+export { useSanitize } from './composables/useSanitize'
+export { useImageContext, provideImageContext, ImageContextKey } from './composables/useImageContext'
+export { useChannelPayload, type UseChannelPayloadReturn } from './composables/useChannelPayload'
+export { useCollation, type UseCollationReturn, type CollatedMessage } from './composables/useCollation'
+
+// SVG Icons
+export { DownloadIcon, CloseIcon, VideoPlayIcon, AudioPlayIcon, AudioPauseIcon, ArrowBackIcon, LinkIcon } from './assets/svg'
+
+// Utilities
+export { match, getChannelPayload } from './utils/matcher'
+export { sanitizeHTMLWithConfig, sanitizeContent } from './utils/sanitize'
+export { configColorsToCssVariables } from './utils/theme'
+export { getWebchatButtonLabel, interpolateString, getRandomId, moveFocusToMessageFocusTarget, replaceUrlsWithHTMLanchorElem, getBackgroundImage, getFileName, getFileExtension, getSizeLabel, isImageAttachment, VALID_IMAGE_MIME_TYPES } from './utils/helpers'
+
+// Types
+export type {
+  ChatConfig,
+  ChatSettings,
+  ChatTheme,
+  MessageProps,
+  MessageSender,
+  MessagePlugin,
+  MessagePluginOptions,
+  MessageContext,
+  IMessage,
+  IWebchatButton,
+  IWebchatQuickReply,
+  IWebchatTemplateAttachment,
+  IWebchatAttachmentElement,
+  IWebchatAudioAttachment,
+  IWebchatImageAttachment,
+  IWebchatVideoAttachment,
+  IUploadFileAttachmentData,
+  IDatePickerData,
+  IWebchatChannelPayload,
+} from './types'
+
+export type { TagVariant } from './components/common/Typography.vue'

package/src/types/index.ts

@@ -0,0 +1,373 @@
+/**
+ * Type definitions for Vue chat components
+ * These mirror the React version types but adapted for Vue
+ */
+
+import type { IMessage } from '@cognigy/socket-client'
+import type { Component } from 'vue'
+
+// =============================================================================
+// Extended Socket Client Types
+// =============================================================================
+
+/**
+ * Extended IMessage with optional runtime properties not in base interface.
+ * The socket-client IMessage doesn't include 'id', but it may be present at runtime.
+ */
+export interface IMessageWithId extends IMessage {
+  id?: string
+}
+
+/**
+ * Type guard to check if a message has an id property
+ */
+export function hasMessageId(message: IMessage): message is IMessageWithId & { id: string } {
+  return 'id' in message && typeof (message as IMessageWithId).id === 'string'
+}
+
+/**
+ * Get message ID with fallback to timestamp-based ID
+ */
+export function getMessageId(message: IMessage): string {
+  if (hasMessageId(message)) {
+    return message.id
+  }
+  return `message-${message.timestamp ?? Date.now()}`
+}
+
+/**
+ * Adaptive card payload structure.
+ * Used for type narrowing when accessing adaptive card data from message payloads.
+ */
+export interface IAdaptiveCardPayload {
+  adaptiveCard: unknown
+}
+
+/**
+ * Type guard to check if a payload contains an adaptive card
+ */
+export function isAdaptiveCardPayload(
+  payload: unknown
+): payload is IAdaptiveCardPayload {
+  return (
+    typeof payload === 'object' &&
+    payload !== null &&
+    'adaptiveCard' in payload
+  )
+}
+
+// =============================================================================
+// Window Interface Extension (for testing)
+// =============================================================================
+
+declare global {
+  interface Window {
+    /** Test-only: Message ID for component testing */
+    __TEST_MESSAGE_ID__?: string
+  }
+}
+
+/**
+ * Configuration for the chat components
+ * Mirrors IWebchatConfig from React version
+ */
+export interface ChatConfig {
+  active?: boolean
+  URLToken?: string
+  initialSessionId?: string
+  settings?: ChatSettings
+  isConfigLoaded?: boolean
+  isTimedOut?: boolean
+}
+
+export interface ChatSettings {
+  layout?: {
+    title?: string
+    logoUrl?: string
+    botAvatarName?: string
+    botLogoUrl?: string
+    agentAvatarName?: string
+    agentLogoUrl?: string
+    disableHtmlContentSanitization?: boolean
+    enableGenericHTMLStyling?: boolean
+    disableBotOutputBorder?: boolean
+    botOutputMaxWidthPercentage?: number
+    disableUrlButtonSanitization?: boolean
+    dynamicImageAspectRatio?: boolean
+    showEngagementInChat?: boolean
+  }
+  colors?: {
+    // Primary action colors
+    primaryColor?: string
+    primaryColorHover?: string
+    primaryColorFocus?: string
+    primaryColorDisabled?: string
+    primaryContrastColor?: string
+    secondaryColor?: string
+
+    // Message bubble colors
+    botMessageColor?: string
+    botMessageContrastColor?: string
+    userMessageColor?: string
+    userMessageContrastColor?: string
+    agentMessageColor?: string
+    agentMessageContrastColor?: string
+
+    // Message bubble borders
+    borderBotMessage?: string
+    borderUserMessage?: string
+    borderAgentMessage?: string
+
+    // Link color
+    textLinkColor?: string
+  }
+  behavior?: {
+    renderMarkdown?: boolean
+    enableTypingIndicator?: boolean
+    messageDelay?: number
+    collateStreamedOutputs?: boolean
+    focusInputAfterPostback?: boolean
+  }
+  widgetSettings?: {
+    enableDefaultPreview?: boolean
+    enableStrictMessengerSync?: boolean
+    customAllowedHtmlTags?: string[]
+    enableAutoFocus?: boolean
+    disableRenderURLsAsLinks?: boolean
+    disableTextInputSanitization?: boolean
+    sourceDirectionMapping?: {
+      user?: 'incoming' | 'outgoing'
+      bot?: 'incoming' | 'outgoing'
+      agent?: 'incoming' | 'outgoing'
+    }
+  }
+  customTranslations?: {
+    ariaLabels?: {
+      messageHeader?: {
+        user?: string
+        bot?: string
+        timestamp?: string
+      }
+      opensInNewTab?: string
+      actionButtonPositionText?: string
+      viewImageInFullsize?: string
+      fullSizeImageViewerTitle?: string
+      downloadFullsizeImage?: string
+      closeFullsizeImageModal?: string
+      playAudio?: string
+      pauseAudio?: string
+      audioPlaybackProgress?: string
+      audioTimeRemaining?: string
+      downloadTranscript?: string
+      playVideo?: string
+      slide?: string
+      // Extensibility: consumers can add custom aria labels with any key
+      [key: string]: any
+    }
+    // Extensibility: consumers can add custom translation sections
+    [key: string]: any
+  }
+}
+
+/**
+ * Theme configuration
+ */
+export interface ChatTheme {
+  primaryColor?: string
+  primaryColorHover?: string
+  secondaryColor?: string
+  backgroundBotMessage?: string
+  backgroundUserMessage?: string
+  textDark?: string
+  textLight?: string
+  fontFamily?: string
+}
+
+/**
+ * Message sender callback type.
+ * The data parameter uses Record<string, any> because it passes through
+ * unchanged to @cognigy/socket-client - shape is determined by backend.
+ */
+export type MessageSender = (
+  text?: string,
+  data?: Record<string, any> | null,
+  options?: Partial<SendMessageOptions>
+) => void
+
+export interface SendMessageOptions {
+  label: string
+  collate: boolean
+}
+
+// =============================================================================
+// Component Prop Types
+// =============================================================================
+
+/**
+ * Custom icon for action buttons.
+ * Can be a Vue component or a string identifier.
+ */
+export type CustomIcon = Component | string
+
+/**
+ * Analytics event data passed to analytics callbacks.
+ * Shape varies by event type, so we use Record<string, any> for flexibility.
+ */
+export type AnalyticsEventData = Record<string, any>
+
+/**
+ * Callback for emitting analytics events from components.
+ */
+export type AnalyticsEventCallback = (event: string, data?: AnalyticsEventData) => void
+
+/**
+ * Props for the Message component
+ */
+export interface MessageProps {
+  message: IMessage
+  action?: MessageSender
+  config?: ChatConfig
+  theme?: ChatTheme
+  prevMessage?: IMessage
+  disableHeader?: boolean
+  plugins?: MessagePlugin[]
+  onEmitAnalytics?: (event: string, payload?: unknown) => void
+}
+
+/**
+ * Options for match rules and plugins
+ */
+export interface MatchRuleOptions {
+  /** If true, continue matching after this rule (allows multiple components) */
+  passthrough?: boolean
+  /** Render component in fullscreen mode */
+  fullscreen?: boolean
+  /** Render component at full width */
+  fullwidth?: boolean
+}
+
+/**
+ * Internal match rule used by the matcher system.
+ * These define which message types map to which internal components.
+ * Components are resolved by name lookup in Message.vue.
+ */
+export interface MatchRule {
+  /** Unique name identifying this rule (maps to component in Message.vue) */
+  name: string
+  /** Function to determine if this rule matches a message */
+  match: (message: IMessage, config?: ChatConfig) => boolean
+  /** Optional rule behavior settings */
+  options?: MatchRuleOptions
+}
+
+/**
+ * External message plugin for custom message types.
+ * Users provide these to handle custom message formats.
+ */
+export interface MessagePlugin extends MatchRule {
+  /** Vue component to render for matched messages (required for external plugins) */
+  component: Component
+}
+
+/**
+ * Union type for matcher results - can be internal rule or external plugin
+ */
+export type MatchResult = MatchRule | MessagePlugin
+
+/**
+ * Type guard to check if a match result is an external plugin with a component
+ */
+export function isMessagePlugin(rule: MatchResult): rule is MessagePlugin {
+  return 'component' in rule && isValidComponent(rule.component)
+}
+
+/**
+ * Check if a value is a valid Vue component (not null/undefined/empty)
+ */
+export function isValidComponent(component: unknown): component is Component {
+  if (!component) return false
+  if (typeof component === 'function') return true
+  if (typeof component === 'object' && Object.keys(component).length > 0) return true
+  return false
+}
+
+/** @deprecated Use MatchRuleOptions instead */
+export type MessagePluginOptions = MatchRuleOptions
+
+/**
+ * Context provided to message components
+ */
+export interface MessageContext {
+  message: IMessage
+  config?: ChatConfig
+  theme?: ChatTheme
+  action?: MessageSender
+  onEmitAnalytics?: (event: string, payload?: unknown) => void
+}
+
+/**
+ * DatePicker plugin data interface
+ */
+export interface IDatePickerData {
+  openPickerButtonText?: string
+  submitButtonText?: string
+  eventName?: string
+  dateFormat?: string
+  defaultDate?: string
+  minDate?: string
+  maxDate?: string
+  mode?: 'single' | 'multiple' | 'range'
+  enableTime?: boolean
+  time_24hr?: boolean
+  noCalendar?: boolean
+  weekNumbers?: boolean
+  locale?: string
+  enable_disable?: string[]
+  function_enable_disable?: string
+  wantDisable?: boolean
+  defaultHour?: number
+  defaultMinute?: number
+  hourIncrement?: number
+  minuteIncrement?: number
+}
+
+/**
+ * Export types from @cognigy/socket-client for convenience
+ */
+export type { IMessage } from '@cognigy/socket-client'
+export type {
+  IWebchatButton,
+  IWebchatQuickReply,
+  IWebchatTemplateAttachment,
+  IWebchatAttachmentElement,
+  IWebchatAudioAttachment,
+  IWebchatImageAttachment,
+  IWebchatVideoAttachment,
+  IUploadFileAttachmentData,
+} from '@cognigy/socket-client'
+
+// =============================================================================
+// Webchat Channel Payload Types
+// =============================================================================
+
+// Import the types we need for the interface
+import type {
+  IWebchatQuickReply as QuickReply,
+  IWebchatTemplateAttachment as TemplateAttachment,
+  IWebchatAudioAttachment as AudioAttachment,
+  IWebchatImageAttachment as ImageAttachment,
+  IWebchatVideoAttachment as VideoAttachment,
+} from '@cognigy/socket-client'
+
+/**
+ * Webchat channel payload structure
+ * This is the shape of _webchat, _facebook, or _defaultPreview in message.data._cognigy
+ */
+export interface IWebchatChannelPayload {
+  message?: {
+    text?: string
+    quick_replies?: QuickReply[]
+    attachment?: TemplateAttachment | AudioAttachment | ImageAttachment | VideoAttachment
+  }
+  adaptiveCard?: unknown
+}