Sprout Sidekick

A Vue 3 plugin providing responsive chat components with custom Sidekick branding, Rubik font, and shared state management.

Features

• 🎨 Custom Branding: Built-in Sidekick design with Rubik font
• 💬 Chat Components: Ready-to-use chat interface components
• 🔄 Shared State: Automatic state synchronization between components
• 📱 Responsive: Mobile-friendly design
• 🎯 TypeScript: Full TypeScript support
• 🎨 Tailwind CSS: Styled with Tailwind CSS
• ⚡ Vue 3: Built for Vue 3 with Composition API
• 🔔 Error Handling: Built-in snackbar notifications for errors and success messages

Demo

🚀 Try the Live Demo - See the components in action with interactive examples.

Installation

npm install @sprout_lbjocson/sprout-sidekick

Quick Start

1. Install the plugin

import { createApp } from 'vue'
import App from './App.vue'
import SproutSidekick from '@sprout_lbjocson/sprout-sidekick'
import '@sprout_lbjocson/sprout-sidekick/dist/sprout-sidekick.css'

const app = createApp(App)

app.use(SproutSidekick, {
  mode: 'PROD', // Required: 'QA' or 'PROD'
  appName: 'My Application', // Required: Your app name (used for analytics)
  skipDesignSystem: true, // Optional: Skip if design system is already installed
})

app.mount('#app')

2. Use the components

<template>
  <div>
    <!-- Full chat interface -->
    <SidekickChat />

    <!-- Floating chat widget -->
    <SidekickChatPlugin />
  </div>
</template>

<script setup>
import { useChatStore } from '@sprout_lbjocson/sprout-sidekick'

const chatStore = useChatStore()

onMounted(() => {
  // Set the token
  chatStore.setToken('your-token-here')
})
</script>

Components

SidekickChat

The main chat interface component for full-page chat experiences.

<SidekickChat />

SidekickChatPlugin

A floating chat widget component that can be positioned anywhere on the page.

<SidekickChatPlugin />

Additional Components

The plugin also includes:

• SidekickChatInput - Standalone chat input component
• SidekickLoader - Loading animation component
• SidekickMessages - Message display component

Plugin Options

interface SidekickChatOptions {
  mode: 'QA' | 'PROD' | 'qa' | 'prod' // Required: Backend environment
  appName: string // Required: Your application name (for analytics)
  skipDesignSystem?: boolean // Optional: Skip design system installation
  baseUrl?: string // Optional: Custom backend URL (overrides mode)
  deviceSource?: 'mobile' | 'web' // Optional: Device type (default: 'web')
}

Required Parameters

• mode: Specifies which backend environment to use ('QA' or 'PROD')
• appName: Identifies your application in analytics tracking

Optional Parameters

• baseUrl: Custom backend URL (takes precedence over mode)
• deviceSource: Device type identifier ('mobile' or 'web', default: 'web')
• skipDesignSystem: Skip design system installation if already installed

Environment Variables

The plugin requires environment variables to be set in your .env file:

VITE_CHAT_BE_QA=https://agent-center-be-qa.sprout.ph
VITE_CHAT_BE_PROD=https://agent-center-be.sprout.ph

Configuration Examples

Minimal configuration (QA environment):

app.use(SproutSidekickPlugin, {
  mode: 'QA', // Required
  appName: 'Sprout HR', // Required
})

Production configuration:

app.use(SproutSidekickPlugin, {
  mode: 'PROD', // Required
  appName: 'Sprout Payroll', // Required
  skipDesignSystem: true,
})

Mobile app configuration:

app.use(SproutSidekickPlugin, {
  mode: 'PROD', // Required
  appName: 'Sprout Mobile', // Required
  deviceSource: 'mobile', // Optional
})

Using custom baseUrl:

app.use(SproutSidekickPlugin, {
  mode: 'QA', // Required (even though baseUrl will override)
  appName: 'Custom App', // Required
  baseUrl: 'https://my-custom-backend.com', // This URL will be used
})

Priority Order for Backend URL:

1. baseUrl (if provided) - highest priority
2. mode (uses corresponding environment variable)
3. Throws error if neither is properly configured

::: warning Both mode and appName are required. The plugin will throw an error at installation time if either is missing. :::

Design System Handling

The plugin automatically detects if the Sprout Design System is already installed in your application to prevent duplicate installations. This ensures optimal performance and avoids conflicts.

Automatic Detection: The plugin checks for existing design system components before installation.

Manual Control: You can explicitly skip design system installation:

app.use(SproutSidekickPlugin, {
  skipDesignSystem: true, // Skip design system installation
})

Use Cases for skipDesignSystem: true:

• Your application already has the design system installed
• You want to use a different version of the design system
• You're managing design system installation separately

Error Handling

The plugin includes built-in error handling with user-friendly snackbar notifications for various scenarios:

• Authentication Errors: Invalid tokens, expired sessions, permission issues
• Message Sending Failures: Network connectivity, server errors, validation issues
• Session Management: Errors when clearing conversations or managing sessions
• Network Issues: Connection timeouts, offline status, server unavailability

Error notifications appear automatically using the design system's snackbar component and provide specific, actionable feedback to users.

State Management

Use the built-in chat store for state management:

import { useChatStore } from '@sprout_lbjocson/sprout-sidekick'

const chatStore = useChatStore()

// Access chat state
console.log(chatStore.messages)
console.log(chatStore.isTyping)

// Send a message
chatStore.sendMessage('Hello, world!')

// Authentication
chatStore.setToken('your-token')
chatStore.clearToken()

Types

The plugin exports comprehensive TypeScript types:

// Plugin options
interface SidekickChatOptions {
  mode: 'QA' | 'PROD' | 'qa' | 'prod'
  appName: string
  skipDesignSystem?: boolean
  baseUrl?: string
  deviceSource?: 'mobile' | 'web'
}

// Chat message
interface ChatMessage {
  id: string
  text: string
  sender: 'user' | 'bot' | 'ticket'
  timestamp: Date
  isStreaming?: boolean
  thoughtSteps?: ThoughtStep[]
  thinkingDuration?: number
  isError?: boolean
  errorDetails?: ErrorDetails
  feedback?: Feedback
  analyticsId?: string
  redactedText?: string
  kbSources?: KBSource[]
}

// Chat state
interface ChatState {
  messages: ChatMessage[]
  isTyping: boolean
  isConnected: boolean
  token: string | null
  isOpen: boolean
  user: AuthUser | null
  currentStreamingMessage: ChatMessage | null
}

See the full TypeScript definitions for all available types.

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Run tests
npm run test:unit

# Lint code
npm run lint

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.