Jidou Chat Widget

A lightweight, customizable chat widget for AI-powered customer support.

Features

• Multiple Display Modes: Floating, fullscreen, and embedded
• Internationalization: Supports English, Traditional Chinese (zh-TW), Simplified Chinese (zh-CN), and Japanese
• Theming: Light/dark themes with customizable colors
• Real-time Communication: WebSocket-based messaging with auto-reconnect
• Message Persistence: Local storage for chat history
• Responsive Design: Works on desktop and mobile
• Configurable Typing Indicator: Choose between animated dots or typewriter-style text with custom verbs
• Shadow DOM: Isolated styles that won't conflict with host page

Installation

Via Script Tag

<script>
  window.JidouChatSettings = {
    clientId: 'YOUR_CLIENT_ID',
    // ... other options
  };
</script>
<script src="https://cdn.jidou.ai/widget.js"></script>

Via NPM

npm install @jidou-ai/chat-widget

import { Widget } from '@jidou-ai/chat-widget';

const widget = new Widget({
  clientId: 'YOUR_CLIENT_ID',
  // ... other options
});
widget.init();

Configuration

window.JidouChatSettings = {
  // Required
  clientId: 'YOUR_CLIENT_ID',

  // Display mode: 'floating' | 'fullscreen' | 'embedded'
  displayMode: 'floating',

  // Language: 'en' | 'zh-TW' | 'zh-CN' | 'ja' | 'auto'
  language: 'auto',

  // Theme: 'light' | 'dark'
  theme: 'light',

  // WebSocket URL (optional, uses default if not specified)
  wsUrl: 'wss://chat.jidou.ai/ws',

  // Custom colors
  colors: {
    primary: '#4F46E5',
    background: '#FFFFFF',
    text: '#1F2937',
    botBubble: '#F3F4F6',
    userBubble: '#4F46E5',
  },

  // Launcher configuration (floating mode only)
  launcher: {
    show: true,
    position: 'bottom-right', // 'bottom-right' | 'bottom-left'
    size: 'medium',           // 'small' | 'medium' | 'large'
    shape: 'circle',          // 'circle' | 'rounded'
    offsetX: 20,
    offsetY: 20,
    tooltip: {
      show: true,
      text: 'Need help?',
    },
  },

  // Chat window configuration
  chatWindow: {
    width: 380,
    height: 600,
    borderRadius: 16,
    typingIndicator: {
      style: 'dots',       // 'dots' | 'text'
      texts: ['Thinking...', 'Analyzing...', 'Composing...'],  // text style only
      interval: 2000,      // ms to pause at each completed word (text style only)
    },
    header: {
      title: 'AI Assistant',
      subtitle: 'Online',
      logo: {
        show: true,
        url: 'https://example.com/logo.png',
        size: 40,
      },
    },
    footer: {
      input: {
        placeholder: 'Type a message...',
        maxLength: 1000,
      },
      branding: {
        show: true,
        text: 'Powered by Jidou',
      },
    },
    welcomeScreen: {
      quickReplies: {
        items: [
          { text: 'Getting Started', icon: '🚀' },
          { text: 'Pricing', icon: '💰' },
          { text: 'Support', icon: '🆘' },
        ],
      },
    },
  },

  // Behavior configuration
  behavior: {
    autoOpen: {
      enabled: false,
      delay: 3000,
    },
    persistence: {
      enabled: true,
      duration: 7, // days
    },
  },

  // Container for embedded mode
  container: '#chat-container',

  // Z-index
  zIndex: 9999,

  // Event hooks
  hooks: {
    onLoad: () => {},
    onReady: () => {},
    onOpen: () => {},
    onClose: () => {},
    onMessageSent: (message) => {},
    onMessageReceived: (message) => {},
    onConnectionStateChange: (state) => {},
    onReconnect: (attempt) => {},
    onError: (error) => {},
  },
};

API

The widget exposes a global JidouChat object with the following methods:

// Open the chat window
JidouChat.open();

// Close the chat window
JidouChat.close();

// Toggle the chat window
JidouChat.toggle();

// Check if chat is open
JidouChat.isOpen();

// Send a message programmatically
JidouChat.sendMessage('Hello!');

// Change display mode
JidouChat.setDisplayMode('fullscreen');
JidouChat.setDisplayMode('floating');
JidouChat.setDisplayMode('embedded', { container: '#my-container' });

// Get current display mode
JidouChat.getDisplayMode();

// Get current state
JidouChat.getState();

// Subscribe to events
JidouChat.on('onMessageReceived', (message) => {
  console.log('New message:', message);
});

// Unsubscribe from events
JidouChat.off('onMessageReceived', handler);

// Destroy the widget
JidouChat.destroy();

Typing Indicator

The widget supports two typing indicator styles when the assistant is composing a response:

Dots (default)

The classic animated dots (...) indicator. No configuration needed.

Text (typewriter)

A typewriter-style animation that cycles through configurable verb phrases character by character, similar to the Claude Code CLI.

chatWindow: {
  typingIndicator: {
    style: 'text',
    // Optional: custom texts (defaults to i18n "Thinking...", "Analyzing...", "Composing...")
    texts: ['Searching knowledge base...', 'Crafting response...', 'Almost done...'],
    // Optional: pause duration in ms at each completed word (default: 2000)
    interval: 2500,
  },
}

When using style: 'text' without providing texts, the widget uses built-in translations based on the current language setting:

| Language | Default texts | |----------|--------------| | English | Thinking..., Analyzing..., Composing... | | 繁體中文 | 思考中..., 分析中..., 撰寫中... | | 简体中文 | 思考中..., 分析中..., 撰写中... | | 日本語 | 考え中..., 分析中..., 作成中... |

Internationalization

The widget automatically detects browser language when language: 'auto' is set. Supported languages:

| Code | Language | |------|----------| | en | English | | zh-TW | Traditional Chinese | | zh-CN | Simplified Chinese | | ja | Japanese |

Translated strings include:

• Connection status (Connecting, Connected, Disconnected, etc.)
• Chat window title
• Input placeholder
• Button labels (Close, Expand, Collapse)
• Branding text
• Typing indicator texts (Thinking, Analyzing, Composing)

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Install dependencies
npm install

# Start development server with mock WebSocket
npm run dev

# Build for production
npm run build

# Run tests
npm test

Project Structure

src/
├── components/       # UI components
│   ├── BaseComponent.ts
│   ├── ChatWindow.ts
│   ├── ConnectionStatus.ts
│   ├── InputArea.ts
│   ├── Launcher.ts
│   ├── MessageList.ts
│   ├── QuickReplies.ts
│   └── icons.ts
├── core/
│   └── Widget.ts     # Main widget class
├── i18n/             # Internationalization
│   ├── index.ts
│   └── translations.ts
├── services/         # Business logic
│   ├── ChatHistoryManager.ts
│   ├── StateManager.ts
│   └── WebSocketClient.ts
├── styles/           # CSS styles
├── types/            # TypeScript types
├── utils/            # Utility functions
└── index.ts          # Entry point

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

Copyright © Jidou AI. All rights reserved.