@snf/access-qa-bot 2.1.0-rc.6 → 2.1.0

package/README.md

@@ -1,8 +1,6 @@
 # Q&A Bot
 
-A React component for integrating the Q&A Bot into your application. The bot can operate in two modes: **floating** (chat button that opens/closes a window) or **embedded** (always visible inline).
-
-**Architecture**: Everything is React-backed for consistency and simplicity. HTML/plain JS usage loads a React-based standalone bundle.
+A React component for integrating the Q&A Bot into your application.  Also includes a standalone bundle for plain HTML/JS usage.
 
 ## Installation
 
@@ -34,99 +32,16 @@ The Q&A Bot supports two display modes:
 - **Floating Mode** (default): Shows a chat button that opens/closes a floating chat window
 - **Embedded Mode**: Always visible, embedded directly in the page content
 
-**All integration methods support both modes**, but have different defaults:
-
-| Method | Default Mode | Override |
-|--------|--------------|----------|
-| Element ID (`#qa-bot`) | Floating | Set `embedded: true` |
-| CSS Class (`.embedded-qa-bot`) | Embedded | n/a |
-| JavaScript API | Floating | Set `embedded: true` |
-
 ## Integration Methods
 
-### Method 1: Auto-Detection by Element ID (Floating by Default)
-
-Simply add a div with id `qa-bot` to your HTML:
-
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
-
-<!-- Automatically creates a floating chat button -->
-<div id="qa-bot"></div>
-```
-
-### Method 2: Auto-Detection by CSS Class (Embedded by Default)
+The QABot can be integrated using a standalone javascript function, or as a react/preact component.
 
-Use the `embedded-qa-bot` class with optional data attributes:
+### React Component
 
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
-
-<!-- Automatically creates an embedded chat widget -->
-<div class="embedded-qa-bot"
-     data-welcome="Hello!"></div>
-```
-
-### Method 3: Programmatic JavaScript API (Floating by Default)
-
-Call the `qaBot()` function with full control:
-
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
-
-<div id="my-bot-container"></div>
-
-<script>
-// Check if user is logged in by looking for auth cookie
-function isUserLoggedIn() {
-    return document.cookie.split(';').some(cookie => {
-        return cookie.trim().startsWith('SESSaccesscisso=');
-    });
-}
-
-window.addEventListener('load', function() {
-    const botController = qaBot({
-        target: document.getElementById('my-bot-container'),
-        embedded: false,  // false = floating (default), true = embedded
-        welcome: "Custom welcome message!",
-        isLoggedIn: isUserLoggedIn(),
-        defaultOpen: false,
-    });
-
-    // Use the controller to interact with the bot
-    botController.addMessage("Hello from JavaScript!");
-    botController.openChat();  // Only works in floating mode
-});
-</script>
-```
-
-## Programmatic Control
-
-When using the JavaScript API in plain HTML/JS (requires standalone bundle), you get a controller object with these methods:
-
-```javascript
-const botController = qaBot({...});
-
-// Add a message to the chat
-botController.addMessage("Hello World!");
-
-// Set user login status
-botController.setBotIsLoggedIn(true);
-
-// Control chat window (floating mode only)
-botController.openChat();
-botController.closeChat();
-botController.toggleChat();
-
-// Cleanup
-botController.destroy();
-```
-
-**Note**: The `qaBot()` function requires the standalone bundle (`access-qa-bot.standalone.js`) to be loaded first. React/Preact applications should use the `<QABot />` component instead.
-
-## As a React Component
-
-For React applications, import and use the component directly. If you want to be able to imperatively add a message to the chat, you can use the ref to do so.
+For React applications, import and use the component directly.
+- To control the chat programmatically, manage `open` and `isLoggedIn` state in your parent component.
+- Use `onOpenChange` to keep your state in sync with user interactions.
+- You can imperatively add a message to the bot using the `addMessage` function
 
 ```jsx
 import React, { useRef, useState } from 'react';
@@ -166,8 +81,8 @@ function MyApp() {
             </button>
 
             <QABot
-                ref={botRef} // This is only needed if you want to add a message from outside the flow
-                embedded={false}  // true for embedded, false for floating
+                ref={botRef} // only needed if you want use the addMessage function
+                embedded={false}
                 isLoggedIn={isLoggedIn}
                 open={chatOpen}
                 onOpenChange={setChatOpen}
@@ -179,112 +94,81 @@ function MyApp() {
 }
 ```
 
-**React Component Notes:**
-- Uses **controlled component pattern**: manage `open` and `isLoggedIn` state in your parent component
-- `onOpenChange` callback receives the new open state when user interacts with chat
-- For programmatic message injection, use the ref: `botRef.current?.addMessage("Hello!")`
-- `defaultOpen` prop not available - use `open` prop with `useState` instead
-- For state management (login, chat open/close), use props and state instead of imperative methods
-
-## Configuration Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `apiKey` / `api-key` | string | API key for authentication (defaults to demo key) |
-| `defaultOpen` / `default-open` | boolean | Whether floating chat opens initially (ignored in embedded mode) **React Component: Use `open` prop instead** |
-| `embedded` | boolean | **false** = floating mode, **true** = embedded mode |
-| `isLoggedIn` / `is-logged-in` | boolean | Sets initial login state and reacts to changes |
-| `loginUrl` / `login-url` | string | URL to redirect for login (default: '/login') |
-| `open` | boolean | **React Component only**: Controls chat window open state (floating mode only) |
-| `onOpenChange` | function | **React Component only**: Callback when chat window open state changes |
-| `ringEffect` / `ring-effect` | boolean | Enable phone ring animation on tooltip (floating mode only) |
-| `welcome` | string | Welcome message shown to the user |
-
-**Note**: The React component uses a controlled component pattern with `open`/`onOpenChange`, while the JavaScript API uses `defaultOpen` for initial state.
-
-### CSS Custom Properties (Theming)
-
-Customize the appearance by setting CSS custom properties on the container:
-
-```html
-<div id="qa-bot" style="
-    --primary-color: #007bff;
-    --secondary-color: #6c757d;
-    --font-family: 'Arial', sans-serif;
-"></div>
-```
+#### React Component Props
 
-## Direct CDN Deployment
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `apiKey` | string | `"demo-key"` | API key for authentication |
+| `embedded` | boolean | `false` | Floating or embedded mode |
+| `isLoggedIn` | boolean | `false` | User login state |
+| `loginUrl` | string | `"/login"` | Login redirect URL |
+| `open` | boolean | - | Controls chat window (floating mode only) |
+| `onOpenChange` | function | - | Chat window state change callback |
+| `ringEffect` | boolean | `true` | Phone ring animation on tooltip |
+| `welcome` | string | - | Welcome message |
 
-For websites that don't use npm, include directly via CDN:
+### Standalone Javascript
 
 ```html
-<!-- CSS (optional, for embedded styling) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.2.0/build/static/css/main.css">
-
-<!-- JavaScript -->
-<script src="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.2.0/dist/access-qa-bot.standalone.js"></script>
+<script src="https://unpkg.com/@snf/access-qa-bot@2.1.0/dist/access-qa-bot.standalone.js"></script>
 
-<!-- Your content -->
 <div id="qa-bot"></div>
-```
-
-## Development and Testing
-
-### Development Server (React Implementation)
-```bash
-npm start
-# Opens http://localhost:3000 with React dev server
-```
-
-### Testing Standalone Integration
-```bash
-# Build the library and project
-npm run build:lib
-npm run build
-
-# Serve the standalone demo files
-npx serve
 
-# Then visit:
-# http://localhost:3000/index.html (integration demos)
+<script>
+qaBot({
+    target: document.getElementById('qa-bot'),
+    embedded: false,
+    welcome: "Custom welcome message!",
+    defaultOpen: false,
+});
+</script>
 ```
 
-## File Structure Guide
+#### Programmatic Control
 
-- **`index.html`** - Main demo showing all integration methods
-- **`public/index.html`** - React app template (Create React App)
-- **`build/index.html`** - Built React app
-- **`src/`** - Source code
-  - **`components/QABot.js`** - Main React component
-  - **`lib.js`** - React-backed implementation for all usage patterns
+When using the JavaScript API in plain HTML/JS (requires standalone bundle), you get a controller object with imperative methods:
 
-## Important Notes
-
-1. **React-Backed Architecture**:
-   - Everything uses React components internally for consistency
-   - HTML/plain JS usage loads a React-based standalone bundle
-   - Single implementation reduces complexity and bugs
+```javascript
+const botController = qaBot({
+    target: document.getElementById('qa-bot'),
+    embedded: false,
+    welcome: "Custom welcome message!",
+    defaultOpen: false,
+});
 
-2. **Embedded vs Floating**:
-   - Embedded mode is always visible and ignores `defaultOpen`
-   - Floating mode shows a chat button; `defaultOpen` controls initial state
-   - Chat window controls (`openChat`, `closeChat`, `toggleChat`) only work in floating mode
+botController.addMessage("Hello World!");
+botController.setBotIsLoggedIn(true);
+// (floating mode only)
+botController.openChat();
+botController.closeChat();
+botController.toggleChat();
+// Cleanup
+botController.destroy();
+```
 
-3. **Ring Effect**:
-   - Only works in floating mode when the tooltip is visible
-   - Triggers a phone-like ring animation to draw attention
-   - Activates once when the bot is first loaded (500ms delay)
-   - Won't repeat if user has already interacted with the chat
+#### JavaScript API Configuration
 
-4. **Auto-Detection**: The standalone script automatically detects and initializes:
-   - `#qa-bot` → Floating mode
-   - `.embedded-qa-bot` → Embedded mode
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `target` | HTMLElement | - | **Required**: DOM element to render into |
+| `apiKey` | string | `"demo-key"` | API key for authentication |
+| `defaultOpen` | boolean | `false` | Initial chat window state |
+| `embedded` | boolean | `false` | Floating or embedded mode |
+| `isLoggedIn` | boolean | `false` | User login state |
+| `loginUrl` | string | `"/login"` | Login redirect URL |
+| `ringEffect` | boolean | `true` | Phone ring animation on tooltip |
+| `welcome` | string | - | Welcome message |
 
-5. **API Key**: Defaults to demo key if not provided
+> **More Examples**: See `index.html` in this repository for examples including login state management, embedded mode, and programmatic control. Run the react app to see the same in a react context.
 
-6. **Browser Support**: Uses modern browser features; consider polyfills for older browsers
+### CSS Custom Properties (Theming)
 
-## Examples Repository
+Customize the appearance by setting CSS custom properties on the container:
 
-See the demo files in this repository for complete working examples of all integration methods.
+```html
+<div id="qa-bot" style="
+    --primary-color: #007bff;
+    --secondary-color: #6c757d;
+    --font-family: 'Arial', sans-serif;
+"></div>
+```