React Bug Selector Widget

A React widget for collecting bug reports with element selection and AI analysis.

Installation

npm install react-bug-selector-widget

Quick Start

import React from 'react'
import { FloatingWidget, WidgetProvider } from 'react-bug-selector-widget'

function App() {
  return (
    <WidgetProvider>
      <div className="your-app">
        {/* Your app content */}
        <h1>My Application</h1>
        
        {/* The floating bug report widget */}
        <FloatingWidget 
          position="bottom-right"
          panelWidth="320px"
          panelHeight="400px"
        />
      </div>
    </WidgetProvider>
  )
}

export default App

Important: The WidgetProvider must wrap any component that uses FloatingWidget or other widget components. In Next.js 15 apps, this typically goes in your root layout or _app.tsx file.

Features

• Element Selection: Click to select any element on the page
• Chat Interface: Guided conversation to gather bug details
• AI Analysis: Optional AI-powered bug analysis
• Floating Widget: Non-intrusive floating button interface
• TypeScript: Full TypeScript support
• IP Address Collection: Automatic user IP detection for identification (v1.1.2+)

API

Components

FloatingWidget

The main widget component that provides a floating button interface.

<FloatingWidget 
  position="bottom-right" // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  panelWidth="320px"     // Width of the chat panel
  panelHeight="400px"    // Height of the chat panel
  offset={{ x: 0, y: 0 }} // Optional position offset
  className=""           // Optional custom CSS class
/>

Props:

• position: Position of the floating button (default: 'bottom-right')
• panelWidth: Width of the chat panel (default: '320px')
• panelHeight: Height of the chat panel (default: '400px')
• offset: Optional x/y offset for fine-tuning position
• className: Optional CSS class for custom styling

WidgetProvider

Context provider that must wrap your app.

<WidgetProvider>
  {/* Your app */}
</WidgetProvider>

Hooks

useWidget

Access widget state and actions.

const { 
  state, 
  startBugReport, 
  addMessage, 
  submitBugReport 
} = useWidget()

Backend Integration

Your backend needs to handle bug report submissions:

// POST /api/bugs
app.post('/api/bugs', (req, res) => {
  const bugReport = req.body
  // Save to database
  res.json({ success: true, data: { id: 123 } })
})

Database Schema & Migrations

The package includes database migration guides in the migrations/ directory:

• migrations/schema.json - Complete database schema
• migrations/README.md - SQL migration examples for all major databases
• migrations/CHANGELOG.md - Version history of schema changes

To check the migration files after installing:

ls node_modules/react-bug-selector-widget/migrations/

Quick Migration for v1.1.2+

If upgrading from an older version, add the IP address column:

-- PostgreSQL/MySQL
ALTER TABLE bug_reports ADD COLUMN userIpAddress VARCHAR(45);

License

MIT