@inov-ai/feedback-widget/examples/README.md

Modern React feedback widget with surveys, analytics, and Next.js 15 support. Collect user feedback and run surveys in your SaaS applications.

# Usage Examples and Testing Guide

This directory contains comprehensive examples demonstrating how to use the `@inov-ai/feedback-widget` package in various scenarios.

## Examples Overview

### 1. `basic-usage.tsx`
- Minimal setup with just the required props
- Perfect for quick integration
- Shows default behavior and styling

### 2. `nextjs-usage.tsx`
- Complete Next.js 15 integration example
- Includes analytics integration (Google Analytics)
- Error monitoring setup (Sentry)
- Custom CSS styling
- Environment variable configuration

### 3. `advanced-usage.tsx`
- Provider pattern implementation
- Custom trigger components
- Multiple feedback entry points
- Advanced event handling
- Complex styling customization

### 4. `migration-guide.tsx`
- Step-by-step migration from script tag
- Comparison of before/after
- Next.js specific configurations
- Benefits explanation

## Testing the Package Locally

### 1. Build the Package
```bash
cd inov-ai-feedback-widget
npm run build
```

### 2. Link for Local Testing
```bash
# In the widget package directory
npm link

# In your test project
npm link @inov-ai/feedback-widget
```

### 3. Create a Test Next.js App
```bash
npx create-next-app@latest feedback-test --typescript --tailwind --app
cd feedback-test
npm link @inov-ai/feedback-widget
```

### 4. Add to Your Test App
```tsx
// app/page.tsx
'use client';

import { InovaiWidget } from '@inov-ai/feedback-widget';

export default function Home() {
  return (
    <main>
      <h1>Testing Feedback Widget</h1>
      <InovaiWidget
        siteKey="test-key"
        primaryColor="#3b82f6"
        position="bottom-right"
        onSubmit={(data) => console.log('Feedback:', data)}
      />
    </main>
  );
}
```

## Features Demonstrated

### Core Features
- ✅ Next.js 15 compatibility
- ✅ SSR support
- ✅ TypeScript integration
- ✅ Theme detection
- ✅ Multiple positions
- ✅ Custom triggers
- ✅ Path filtering
- ✅ Feedback categories

### Advanced Features
- ✅ Provider pattern
- ✅ Custom styling
- ✅ Event callbacks
- ✅ Error handling
- ✅ Analytics integration
- ✅ Multiple entry points
- ✅ Dynamic configuration

### Customization Options
- ✅ Colors and fonts
- ✅ Animations
- ✅ Button styling
- ✅ Modal appearance
- ✅ Custom CSS injection
- ✅ Responsive design

## Browser Support

The widget supports all modern browsers:
- Chrome/Edge 88+
- Firefox 85+
- Safari 14+
- Mobile browsers

## Performance

- Bundle size: ~15KB gzipped
- Tree-shakeable
- Code splitting support
- Lazy loading components
- Minimal runtime overhead

## Troubleshooting

### Common Issues

1. **Module not found error**
   - Ensure the package is built: `npm run build`
   - Check the import path is correct

2. **Hydration mismatch**
   - Use 'use client' directive in Next.js
   - The widget automatically handles SSR

3. **TypeScript errors**
   - Ensure you have the latest TypeScript version
   - Check that all required props are provided

4. **Styling issues**
   - Use the `customCSS` prop for overrides
   - Check theme detection is working correctly

### Next.js Specific

1. **CSP headers**
   - No external scripts needed, so no CSP issues

2. **App Router vs Pages Router**
   - Both are supported
   - Use 'use client' directive in App Router

3. **Dynamic imports**
   ```tsx
   import dynamic from 'next/dynamic';
   
   const InovaiWidget = dynamic(
     () => import('@inov-ai/feedback-widget'),
     { ssr: false }
   );
   ```

## Publishing Checklist

Before publishing to npm:

- [ ] All examples work correctly
- [ ] Build succeeds without errors
- [ ] TypeScript types are exported
- [ ] README is comprehensive
- [ ] Version number is updated
- [ ] No security vulnerabilities
- [ ] Tests pass (when added)
- [ ] Bundle size is acceptable