Flow Connect Chat Widget 💬

Modern Angular chat widget library with WebSocket and Demo modes. Built with Angular 17+ Standalone Components and Signals.

✨ Features

• 🚀 Angular 17+ - Standalone Components, Signals, Control Flow
• 🎮 Demo Mode - Works without configuration
• 🌐 WebSocket Support - Real-time custom servers
• 📱 Responsive Design - Mobile, tablet, desktop
• 🌗 Theme System - Light/Dark/Auto with persistence
• ⚡ Auto Fallback - Intelligent mode switching
• 💪 TypeScript - Fully typed

📦 Complete Installation Guide

Step 1: Install the Library

npm install flow-connect-chat

✅ No additional configuration required! The library is publicly available on npm.

Step 2: Configure HttpClient with Fetch ⚠️ REQUIRED

For Standalone Applications (Angular 17+):

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideHttpClient, withFetch } from '@angular/common/http';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(withFetch()), // ⚠️ REQUIRED - Uses modern Fetch API
    // ... your other providers
  ]
});

For NgModule Applications:

// app.module.ts
import { HttpClientModule } from '@angular/common/http';

@NgModule({
  imports: [
    HttpClientModule, // ⚠️ REQUIRED for chat widget
    // ... other imports
  ],
  // ...
})
export class AppModule {}

Step 3: Configure Styles ⚠️ REQUIRED

Method 1: Angular.json Configuration (Recommended)

Add to your angular.json file:

{
  "projects": {
    "your-project-name": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/flow-connect-chat/styles.css",
              "src/styles.css"
            ]
          }
        },
        "test": {
          "options": {
            "styles": [
              "node_modules/flow-connect-chat/styles.css",
              "src/styles.css"
            ]
          }
        }
      }
    }
  }
}

Method 2: Import in styles.css

/* src/styles.css */
@import "flow-connect-chat/styles.css";

/* If above doesn't work, use explicit path: */
@import "../node_modules/flow-connect-chat/styles.css";

🚀 Quick Start

Modern Angular chat widget library with WebSocket and Demo modes. Built with Angular 17+ Standalone Components and Signals.

✨ Features

• 🚀 Angular 17+ - Standalone Components, Signals, Control Flow
• 🎮 Demo Mode - Works without configuration
• � WebSocket Support - Real-time custom servers
• 📱 Responsive Design - Mobile, tablet, desktop
• 🌗 Theme System - Light/Dark/Auto with persistence
• ⚡ Auto Fallback - Intelligent mode switching
• 💪 TypeScript - Fully typed

� Installation

npm install flow-connect-chat

⚡ Quick Start

Basic Usage (Demo Mode)

// app.component.ts
import { Component } from '@angular/core';
import { ChatWidget } from 'flow-connect-chat';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ChatWidget],
  template: `
    <!-- Works immediately - no configuration needed! -->
    <ng-chat-widget 
      title="Support Chat"
      position="right">
    </ng-chat-widget>
  `
})
export class AppComponent {}

WebSocket Mode

// app.component.ts
import { Component, signal } from '@angular/core';
import { ChatWidget, ChatConfig } from 'flow-connect-chat';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ChatWidget],
  template: `
    <ng-chat-widget 
      title="Real-time Chat"
      [websocketConfig]="websocketConfig()">
    </ng-chat-widget>
  `
})
export class AppComponent {
  websocketConfig = signal<ChatConfig>({
    websocketUrl: 'wss://your-server.com/chat',
    connectionOptions: {
      autoReconnect: true,
      reconnectDelay: 3000,
      maxReconnectAttempts: 5
    }
  });
}

📋 Configuration Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | title | string | 'Assistant' | Chat window title | | position | 'left' \| 'right' | 'right' | Position (bubble mode) | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color theme | | showAsBubble | boolean | true | Floating vs embedded mode | | width | string | '' | Custom width (400px, 50%) | | height | string | '' | Custom height (600px, 80vh) | | websocketConfig | ChatConfig | null | WebSocket integration |

🎯 Two Operation Modes

1. 🎮 Demo Mode (Default)

<!-- No configuration needed -->
<ng-chat-widget title="Demo Chat"></ng-chat-widget>

• ✅ Works immediately without setup
• ✅ Simulated responses
• ✅ Perfect for testing

2. 🌐 WebSocket Mode

websocketConfig = signal<ChatConfig>({
  websocketUrl: 'wss://your-server.com/chat'
});

• ✅ Custom server integration
• ✅ Real-time messaging
• ✅ Full control

� TypeScript Interfaces

interface ChatConfig {
  websocketUrl: string;
  connectionOptions?: {
    autoReconnect?: boolean;
    reconnectDelay?: number;
    maxReconnectAttempts?: number;
  };
}

interface User {
  id: string;
  name: string;
  email?: string;
  avatar?: string;
  isOnline: boolean;
}

� Display Modes

Bubble Mode (Default)

<!-- Floating chat bubble -->
<ng-chat-widget title="Support"></ng-chat-widget>

<!-- Custom position and size -->
<ng-chat-widget 
  title="Help Desk"
  position="left"
  width="450px"
  height="650px">
</ng-chat-widget>

Embedded Mode

<!-- Integrated in your layout -->
<ng-chat-widget 
  title="Customer Service"
  [showAsBubble]="false"
  width="400px"
  height="600px">
</ng-chat-widget>

📐 Sizing Examples

<!-- Fixed size -->
<ng-chat-widget width="400px" height="600px">

<!-- Responsive -->
<ng-chat-widget width="90vw" height="80vh">

<!-- CSS calc -->
<ng-chat-widget width="min(400px, 90vw)" height="max(500px, 70vh)">

🎨 Theming

The widget automatically adapts to your system theme or you can force a specific theme:

<ng-chat-widget theme="light">   <!-- Light theme -->
<ng-chat-widget theme="dark">    <!-- Dark theme -->
<ng-chat-widget theme="auto">    <!-- System theme (default) -->

� Complete Setup Checklist

Follow this checklist to ensure proper installation:

• [ ] ✅ Registry configured: .npmrc file created with GitHub Packages registry
• [ ] ✅ Library installed: npm install flow-connect-chat
• [ ] ✅ HttpClient configured: Added provideHttpClient(withFetch()) in main.ts
• [ ] ✅ Styles configured: Added styles in angular.json or styles.css
• [ ] ✅ Component imported: Import ChatWidget in your component
• [ ] ✅ Development server restarted: npm start or ng serve

🚨 Common Issues & Solutions

❌ Error: "No provider found for HttpClient"

Solution: Configure HttpClient in your application

// ✅ Add this to main.ts
import { provideHttpClient, withFetch } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(withFetch()), // This line is required!
  ]
});

❌ Error: "Cannot resolve styles" or Widget appears unstyled

Solution: Configure styles properly

// ✅ Option 1: Add to angular.json (Recommended)
"styles": [
  "node_modules/flow-connect-chat/styles.css",
  "src/styles.css"
]

/* ✅ Option 2: Add to src/styles.css */
@import "flow-connect-chat/styles.css";

❌ Error: "Package not found" when installing

Solution: Configure GitHub Packages registry

# ✅ Create .npmrc file
echo "@flowconnect-ia:registry=https://npm.pkg.github.com" > .npmrc

❌ Widget not showing or console errors

Solutions:

1. ✅ Restart development server: npm start
2. ✅ Clear npm cache: npm cache clean --force
3. ✅ Reinstall: rm -rf node_modules && npm install
4. ✅ Check browser console for specific error messages

🧪 Verify Installation

Run this quick test to verify everything is working:

// test-component.ts
import { Component } from '@angular/core';
import { ChatWidget } from 'flow-connect-chat';

@Component({
  selector: 'app-test',
  standalone: true,
  imports: [ChatWidget],
  template: `
    <div style="padding: 20px;">
      <h2>Chat Widget Test</h2>
      <ng-chat-widget title="Test Chat" position="right"></ng-chat-widget>
    </div>
  `
})
export class TestComponent {}

Expected result: A chat bubble should appear in the bottom-right corner with proper styling.

💡 IntelliSense & TypeScript Support

This library provides complete TypeScript support with:

• ✅ Full type definitions for all interfaces
• ✅ JSDoc documentation in autocomplete
• ✅ Parameter hints and suggestions
• ✅ Error detection at compile time
• ✅ Import auto-completion

Example with IntelliSense:

import { 
  ChatWidget,           // Main component
  ChatConfig,           // WebSocket configuration  
  ChatPosition,         // 'left' | 'right'
  ChatTheme,           // 'light' | 'dark' | 'auto'
  MessageType,         // Message content types
  UserRole             // User role types
} from 'flow-connect-chat';

// Your IDE will provide full autocomplete and type checking
const config: ChatConfig = {
  websocketUrl: '',   // ← IntelliSense shows: "WebSocket server URL"
  connectionOptions: {
    autoReconnect: true,      // ← IntelliSense suggests boolean
    reconnectDelay: 3000      // ← IntelliSense shows number type
  }
};

Available Types:

| Type | Description | Values | |------|-------------|---------| | ChatPosition | Widget position | 'left' | 'right' | | ChatTheme | Color theme | 'light' | 'dark' | 'auto' | | MessageType | Message content type | 'text' | 'image' | 'file' | etc. | | UserRole | User role | 'agent' | 'customer' | 'admin' | 'bot' | | UserStatus | User online status | 'online' | 'offline' | 'away' | 'busy' | | MessageStatus | Message delivery status | 'sending' | 'sent' | 'delivered' | etc. |

�📖 Documentation

For complete documentation, advanced examples, and configuration options:

📚 Full Documentation

🛠️ Development

# Clone repository
git clone https://github.com/FlowConnect-IA/chat.git
cd chat && npm install

# Start development server  
npm start

# Build library
npm run build:lib

🤝 Contributing

Contributions welcome! Please read our Contributing Guide.

📄 License

MIT License © FlowConnect IA

Made with ❤️ using Angular 17+ and modern best practices