# Brainfish In-App Widget

This package provides a simple way to integrate a Brainfish in-app widget in your website or web application. It supports popup widgets with contextual help functionality.

## Installation

```bash
npm install @brainfish-ai/web-widget
```

### Directly in your HTML

```html
<script type="module">
    import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js"
    Brainfish.Widgets.init({ widgetKey: "your-key" });
</script>
```

## Popup Widget

The popup widget provides a floating button that opens a search interface in a modal overlay.

### Basic Usage

```html
<!-- The widget will automatically create a floating button -->
<script>
    Brainfish.Widgets.init({
        widgetKey: "your-widget-key",
        environment: "production" // or "staging", "local"
    });
</script>
```

### Widget Control API

```javascript
// Open the widget
Brainfish.Widgets.open();

// Open the widget with custom positioning
Brainfish.Widgets.open({
    position: 'bottom-right' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});

// Close the widget
Brainfish.Widgets.close();

// Create a new conversation thread
// If widget is open, resets the current conversation
// If widget is closed, opens it with a new conversation
Brainfish.Widgets.createNewThread();

// Check if widget is ready
if (Brainfish.Widgets.isReady) {
    // Widget is ready to use
}
```

### User Management

```javascript
// Identify a user
Brainfish.Widgets.identify({
    name: "John Doe",
    email: "john@example.com",
    userId: "user_123"
});

// Set secret attributes (for internal use)
Brainfish.Widgets.setSecretAttributes("internal_data_123");
```

### Customization with Overrides

Customize your widget's appearance and behavior using the `overrides` configuration:

```javascript
Brainfish.Widgets.init({
    widgetKey: "your-widget-key",
    overrides: {
        // Suggested questions that appear when widget opens
        suggestions: [
            'How do I reset my password?',
            'How do I contact support?',
            'What are your pricing plans?'
        ],

        // Theme customization
        theme: {
            inputButtonBgColor: '#3b82f6',
            inputButtonColor: '#ffffff'
        },

        // Widget settings
        panelTitle: 'Help Center',
        placeholder: 'Ask a question...',

        // Action buttons
        bodyActionButtons: [
            {
                icon: 'Calendar',
                type: 'link',
                label: 'Book a Demo',
                value: 'https://calendly.com/your-company'
            }
        ]
    }
});
```

**📚 For complete customization options, see:**
- [**Overrides Guide**](https://help.brainfi.sh/articles/brainfish-widget-overrides-guide-K96JtYxorD) - Complete documentation with examples
- [**Quick Reference**](https://help.brainfi.sh/articles/brainfish-widget-overrides-guide-K96JtYxorD#h-settings-reference) - Fast lookup for common configurations

### Custom Positioning

Both `open()` and `onContextHelp()` methods support custom positioning to control where the widget appears on screen. This is useful for creating contextual experiences or avoiding UI conflicts.

**Available Positions:**
- `'bottom-left'` - Widget appears in bottom-left corner (default)
- `'bottom-right'` - Widget appears in bottom-right corner
- `'top-left'` - Widget appears in top-left corner
- `'top-right'` - Widget appears in top-right corner

**Usage Examples:**

```javascript
// Open widget in different positions
Brainfish.Widgets.open({ position: 'top-right' });
Brainfish.Widgets.open({ position: 'bottom-left' });

// Contextual help with positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
    position: 'top-left'
});

// Dynamic positioning based on user interaction
function showHelpNearElement(question, element) {
    const rect = element.getBoundingClientRect();
    const position = rect.left < window.innerWidth / 2 ? 'bottom-left' : 'bottom-right';

    Brainfish.Widgets.onContextHelp(question, { position });
}
```

### Contextual Help Feature

The contextual help feature allows you to open the widget with a pre-filled question based on user interaction.

```javascript
// Trigger contextual help with a specific question
Brainfish.Widgets.onContextHelp("How do I reset my password?");

// Trigger contextual help with custom positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
    position: 'top-left' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});
```

#### Implementation Examples

**HTML with Help Icons:**
```html
<div class="form-field">
    <label>Email Address</label>
    <input type="email" value="user@example.com">
    <button class="help-icon"
            data-question="How do I change my email address?"
            data-position="top-left">
        <i class="ph ph-question"></i>
    </button>
</div>

<script>
// Add event listeners to help icons with custom positioning
document.querySelectorAll('.help-icon').forEach(icon => {
    icon.addEventListener('click', (e) => {
        const question = e.target.dataset.question;
        const position = e.target.dataset.position || 'bottom-right';
        Brainfish.Widgets.onContextHelp(question, { position });
    });
});
</script>
```

**Direct Button Integration:**
```html
<button onclick="Brainfish.Widgets.onContextHelp('How do I reset my password?', { position: 'top-right' })">
    Reset Password
</button>
```

**Programmatic Usage:**
```javascript
function showHelp(question, position = 'bottom-right') {
    Brainfish.Widgets.onContextHelp(question, { position });
}

// Usage with different positions
showHelp("How do I update my profile?", 'top-left');
showHelp("How do I contact support?", 'bottom-right');
```

### Event Listeners

The widget emits events when it opens and closes. You can listen to these events:

```javascript
// Set up the abort controller
const controller = new AbortController();
const { signal } = controller;

// Listen for widget events
window.addEventListener('onBrainfishWidgetOpen', (event) => {
    console.log('Widget opened');
    // Your custom logic here
}, { signal });

window.addEventListener('onBrainfishWidgetClose', (event) => {
    console.log('Widget closed');
    // Your custom logic here
}, { signal });

// Clean up event listeners when no longer needed
controller.abort();
```

### Analytics Events

The widget automatically tracks analytics events:

- **Open Widget** - When the widget is opened
- **Open Widget - Contextual Help** - When opened via contextual help
- **Open Widget - Custom Trigger** - When opened with custom trigger
- **Close Widget** - When the widget is closed

## Build

Run the following command to build the widget:

```bash
yarn build:web-widget
```

## Testing locally

### Start the local server

```bash
cd packages/web-widget
npx serve ./ -p 8000 -C
```

### Open the Playground

The playground provides a comprehensive testing environment for the Brainfish widget:

```bash
open http://localhost:8000/playground/index.html
```

The playground includes:
- **Widget Configuration** - Set environment, API key, and widget settings
- **Contextual Help Testing** - Test the new contextual help feature with sample questions
- **Real-world Demo** - See how customers would implement contextual help in their apps
- **API Testing** - Test all widget methods and functionality
- **Live Logs** - Monitor widget events and debugging information

### Test Different Environments

You can test the widget in different environments by passing the `env` parameter:

```bash
# Local environment
open http://localhost:8000/playground/index.html?env=local

# Staging environment
open http://localhost:8000/playground/index.html?env=staging

# Production environment
open http://localhost:8000/playground/index.html?env=prod
```

### Agent Widget Development

If you want to test with the agent widget (Next.js app), start it locally:

```bash
cd packages/agent-widget
npm run dev
```

This will run the agent widget on port 3000, which the playground will automatically connect to in local development mode.