npm package: @quickquerybot/widget
Description: React component for embedding QuickQueryBot chat widget
Author: QuickQueryBot
Latest version: 1.0.1

# @quickquerybot/widget

A React component and JavaScript library for easily embedding the QuickQueryBot chat widget in your web applications.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Methods](#usage-methods)
  - [React Component](#react-component)
  - [React Hook](#react-hook)
  - [JavaScript/TypeScript (Non-React)](#javascripttypescript-non-react)
- [Framework Integration](#framework-integration)
  - [Next.js](#nextjs-integration)
  - [Create React App](#create-react-app)
  - [Vite](#vite)
  - [Angular](#angular)
  - [Vue](#vue)
- [Configuration Options](#configuration-options)
- [Customization Examples](#customization-examples)
- [TypeScript Support](#typescript-support)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#license)

## Installation

Install the package using npm or yarn:

```bash
# Using npm
npm install @quickquerybot/widget

# Using yarn
yarn add @quickquerybot/widget

# Using pnpm
pnpm add @quickquerybot/widget
```

## Quick Start

The fastest way to add the chat widget to your React application is to use the `ChatWidget` component:

```jsx
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div>
      <h1>My Website</h1>
      
      {/* Add the chat widget anywhere in your component tree */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;
```

## Usage Methods

### React Component

The `ChatWidget` component is the recommended way to use the widget in React applications:

```jsx
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div>
      {/* The widget will be fixed-positioned at bottom-right by default */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
        position="bottom-right"
        title="Customer Support"
        welcomeMessage="Hello! How can I assist you today?"
      />
    </div>
  );
}
```

### React Hook

The hook approach is useful when you need more control or have specific initialization requirements:

```jsx
import { useEffect } from 'react';
import { useChatWidget } from '@quickquerybot/widget';

function App() {
  // Initialize chat widget with configuration
  useChatWidget({
    websiteId: 'your-website-id',
    primaryColor: '#0070f3',
    welcomeMessage: 'Hello! How can I help you today?',
    // Only open during business hours
    position: new Date().getHours() < 17 ? 'bottom-right' : 'hidden'
  });
  
  return (
    <div>
      <h1>My Website</h1>
      {/* Widget is injected into the DOM automatically */}
    </div>
  );
}
```

### JavaScript/TypeScript (Non-React)

For non-React applications or scenarios where you need full control over initialization:

```js
import { initChatWidget } from '@quickquerybot/widget';

// Initialize the widget when you're ready
function setupChat() {
  initChatWidget({
    websiteId: 'your-website-id',
    primaryColor: '#0070f3',
    position: 'bottom-right'
  });
}

// Call on page load or after user interaction
document.addEventListener('DOMContentLoaded', setupChat);

// Or trigger based on user behavior
document.getElementById('help-button').addEventListener('click', () => {
  setupChat();
  // Optionally open the chat immediately
  window.__quickquerybot_open_chat?.();
});
```

## Framework Integration

### Next.js Integration

#### App Router (Next.js 13+)

Use the component in a client-side component:

```jsx
'use client';

import { ChatWidget } from '@quickquerybot/widget';

export default function Layout({ children }) {
  return (
    <div>
      {children}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}
```

#### Pages Router

```jsx
// In _app.js or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </>
  );
}

export default MyApp;
```

### Create React App

```jsx
// In src/App.js or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        {/* Your app content */}
      </header>
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;
```

### Vite

```jsx
// In src/App.jsx or a layout component
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  return (
    <div className="App">
      {/* Your app content */}
      <ChatWidget 
        websiteId="your-website-id"
        primaryColor="#0070f3"
      />
    </div>
  );
}

export default App;
```

### Angular

For Angular applications, you'll need to use the widget.js script directly:

```typescript
// In app.component.ts
import { Component, OnInit } from '@angular/core';
import { initChatWidget } from '@quickquerybot/widget';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit {
  ngOnInit() {
    initChatWidget({
      websiteId: 'your-website-id',
      primaryColor: '#0070f3',
    });
  }
}
```

### Vue

For Vue applications, create a component to wrap the widget:

```vue
<!-- ChatWidget.vue -->
<template>
  <div></div> <!-- Widget is injected into DOM directly -->
</template>

<script>
import { initChatWidget } from '@quickquerybot/widget';

export default {
  name: 'ChatWidget',
  props: {
    websiteId: {
      type: String,
      required: true
    },
    primaryColor: {
      type: String,
      default: '#0070f3'
    },
    position: {
      type: String,
      default: 'bottom-right'
    }
  },
  mounted() {
    initChatWidget({
      websiteId: this.websiteId,
      primaryColor: this.primaryColor,
      position: this.position
    });
  }
}
</script>
```

Then use it in your app:

```vue
<!-- App.vue -->
<template>
  <div id="app">
    <!-- Your app content -->
    <ChatWidget websiteId="your-website-id" />
  </div>
</template>

<script>
import ChatWidget from './components/ChatWidget.vue';

export default {
  name: 'App',
  components: {
    ChatWidget
  }
}
</script>
```

## Configuration Options

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| `websiteId` | string | **Required.** Unique identifier for your website | - |
| `title` | string | Title displayed in the chat header | "Chat Assistant" |
| `welcomeMessage` | string | Initial message displayed when chat is opened | "Hello! How can I help you today?" |
| `primaryColor` | string | Primary color for buttons and header | "#0070f3" |
| `messageColor` | string | Color for user messages | Same as primaryColor |
| `botMessageColor` | string | Color for bot messages | "#f1f1f1" |
| `position` | string | Position of widget on screen. Options: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` | "bottom-right" |
| `inputPlaceholder` | string | Placeholder for message input | "Type your message..." |
| `apiEndpoint` | string | Custom API endpoint for the chat service | Based on origin |
| `scriptUrl` | string | Custom URL for the widget script | Based on origin |

## Customization Examples

### Styling the Widget

```jsx
import { ChatWidget } from '@quickquerybot/widget';

// Example with full styling options
<ChatWidget 
  websiteId="your-website-id"
  title="Product Support"
  welcomeMessage="Hi there! Need help with our product?"
  primaryColor="#4F46E5" // Indigo
  messageColor="#4F46E5" // User message bubbles
  botMessageColor="#F3F4F6" // Bot message bubbles
  position="bottom-right"
  inputPlaceholder="Ask a question..."
/>
```

### Conditionally Showing the Widget

```jsx
import { useState, useEffect } from 'react';
import { ChatWidget } from '@quickquerybot/widget';

function App() {
  const [showWidget, setShowWidget] = useState(false);
  
  // Show widget after 5 seconds
  useEffect(() => {
    const timer = setTimeout(() => {
      setShowWidget(true);
    }, 5000);
    
    return () => clearTimeout(timer);
  }, []);
  
  return (
    <div>
      <h1>My Website</h1>
      {showWidget && (
        <ChatWidget 
          websiteId="your-website-id"
          primaryColor="#0070f3"
        />
      )}
    </div>
  );
}
```

## TypeScript Support

The package includes full TypeScript definitions. Import the types when needed:

```tsx
import { ChatWidget, ChatWidgetProps } from '@quickquerybot/widget';

// You can use the ChatWidgetProps type for your own components
interface MyComponentProps {
  widgetConfig: ChatWidgetProps;
}

function MyComponent({ widgetConfig }: MyComponentProps) {
  return (
    <div>
      <ChatWidget {...widgetConfig} />
    </div>
  );
}
```

## API Reference

### `ChatWidget` Component

React component for embedding the chat widget.

```tsx
import { ChatWidget } from '@quickquerybot/widget';

<ChatWidget 
  websiteId="your-website-id"
  // ... other props
/>
```

### `useChatWidget` Hook

React hook for initializing the chat widget.

```tsx
import { useChatWidget } from '@quickquerybot/widget';

function Component() {
  useChatWidget({
    websiteId: 'your-website-id',
    // ... other props
  });
  
  return <div>Your component</div>;
}
```

### `initChatWidget` Function

Vanilla JavaScript function for initializing the chat widget.

```typescript
import { initChatWidget } from '@quickquerybot/widget';

initChatWidget({
  websiteId: 'your-website-id',
  // ... other props
});
```

## Troubleshooting

### Widget Not Appearing

1. Verify your `websiteId` is correct and exists in your QuickQueryBot dashboard
2. Check browser console for errors
3. Ensure you're using a client-side component in Next.js (add 'use client' directive)
4. Verify the widget script is loading properly (check network tab)

### Styling Issues

1. Make sure color values are valid CSS colors
2. For conflicts with your site CSS, try adjusting z-index:

```jsx
<ChatWidget 
  websiteId="your-website-id"
  // Custom styling with higher z-index if needed
  customStyles={{
    container: { zIndex: 10000 }
  }}
/>
```

### API Connection Issues

If the widget isn't connecting to your API:

1. Check the API endpoint URL
2. Verify CORS settings on your server
3. Check authentication requirements

## Development

If you're contributing to this package:

1. Clone the repository
2. Install dependencies: `npm install`
3. Build the package: `npm run build`
4. Run tests: `npm test`

## License

MIT