npm package: @liaplus/voice-navigation-ai
Description: AI-powered voice navigation component for Next.js with OpenAI integration
Author: LiaPlus
Latest version: 1.0.1

# 🎤 Voice Navigation AI

An AI-powered voice navigation component for Next.js applications with OpenAI integration. Provides hands-free website navigation with speech recognition and natural language processing.

[![npm version](https://img.shields.io/npm/v/@liaplus/voice-navigation-ai.svg)](https://www.npmjs.com/package/@liaplus/voice-navigation-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🎯 **AI-Powered Commands** - Natural language understanding with OpenAI
- 🗣️ **Speech Recognition** - Built-in Web Speech API support
- 📱 **Fully Responsive** - Optimized for mobile, tablet, and desktop
- ⚡ **Easy Integration** - Drop-in component for Next.js 13+
- 🎨 **Customizable** - Extend with custom commands and styling
- ♿ **Accessible** - WCAG compliant with ARIA labels
- 🌐 **Multi-Language** - Support for multiple languages (configurable)
- 🔧 **Type Safe** - Full TypeScript support

## 📦 Installation

```bash
npm install @liaplus/voice-navigation-ai
```

### Peer Dependencies

Make sure you have the required peer dependencies installed:

```bash
npm install next react react-dom
```

### Additional Dependencies

The package also requires these dependencies (automatically installed):

```bash
npm install lucide-react class-variance-authority clsx tailwind-merge
```

## 🚀 Quick Start

### 1. Add the Component to Your Layout

```tsx
// app/layout.tsx
import { VoiceNavigationAdvanced } from '@liaplus/voice-navigation-ai'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <VoiceNavigationAdvanced />
      </body>
    </html>
  )
}
```

### 2. Create the API Route

Create a new file at `app/api/voice-command/route.ts`:

```tsx
// app/api/voice-command/route.ts
export { POST } from '@liaplus/voice-navigation-ai/api'
```

### 3. Set Environment Variable

Add your OpenAI API key to `.env.local`:

```bash
OPENAI_API_KEY=sk-your-openai-api-key-here
```

That's it! 🎉 Your voice navigation is now active.

## 📖 Detailed Setup

### Custom API Handler

If you need more control over the API handler:

```tsx
// app/api/voice-command/route.ts
import { createVoiceCommandHandler } from '@liaplus/voice-navigation-ai/api'

export const POST = createVoiceCommandHandler({
  openaiApiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini', // or 'gpt-4'
  systemPrompt: `Your custom system prompt here...`
})
```

### Custom Commands

Extend the default commands with your own:

```tsx
import { VoiceNavigationAdvanced } from '@liaplus/voice-navigation-ai'

export default function Layout({ children }) {
  return (
    <>
      {children}
      <VoiceNavigationAdvanced
        customCommands={{
          'dashboard': {
            keywords: ['dashboard', 'go to dashboard', 'show dashboard'],
            action: '/dashboard', // String path for navigation
            description: 'Go to dashboard',
            category: 'navigation'
          },
          'logout': {
            keywords: ['logout', 'sign out', 'log out'],
            action: () => {
              // Custom function
              signOut()
            },
            description: 'Sign out',
            category: 'system'
          }
        }}
      />
    </>
  )
}
```

### Component Props

```tsx
interface VoiceNavigationProps {
  /**
   * Custom command mappings to extend or override default commands
   */
  customCommands?: Record<string, {
    keywords: string[]
    action: string | (() => void)
    description: string
    category: 'navigation' | 'scrolling' | 'content' | 'system' | 'products' | 'resources' | 'solutions' | 'info'
  }>
  
  /**
   * API endpoint for AI-powered voice command processing
   * @default '/api/voice-command'
   */
  apiEndpoint?: string
  
  /**
   * Enable AI mode by default
   * @default false
   */
  defaultAIMode?: boolean
  
  /**
   * Enable voice feedback by default
   * @default true
   */
  defaultVoiceFeedback?: boolean
  
  /**
   * Show commands list by default
   * @default true
   */
  defaultShowCommands?: boolean
}
```

## 🎮 Default Commands

### 📜 Scrolling
- "scroll up" / "move up" / "go up"
- "scroll down" / "move down" / "go down"
- "go to top" / "top of page"
- "go to bottom" / "bottom of page"
- "go to middle" / "center"

### 🧭 Navigation
- "go home" / "home page"
- "show products" / "products page"
- "show pricing" / "pricing page"
- "about us" / "about page"
- "contact us" / "contact page"
- "solutions page"

### 🔧 System
- "go back" / "back"
- "print page" / "print"
- "hide commands" / "show commands"
- "scroll commands up" / "scroll commands down"

### 📖 Content
- "read page" / "read content"
- "stop reading" / "stop"

### ℹ️ Info
- "help" / "show commands"

## 🎨 Styling

The component uses Tailwind CSS classes. Make sure your `tailwind.config.js` includes the package:

```js
// tailwind.config.js
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@liaplus/voice-navigation-ai/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}
```

### Custom Styling

You can customize the appearance by wrapping the component and applying custom CSS classes or by modifying your Tailwind theme.

## 🔐 Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes (for AI mode) | Your OpenAI API key |

### Getting an OpenAI API Key

1. Go to [OpenAI Platform](https://platform.openai.com/)
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Add it to your `.env.local` file

## 🌐 Browser Support

- ✅ Chrome (Desktop & Mobile)
- ✅ Edge (Desktop & Mobile)
- ✅ Safari (Desktop & Mobile)
- ⚠️ Firefox (Desktop only - limited speech recognition support)

The Web Speech API is required for voice recognition. The component will automatically hide itself if speech recognition is not supported.

## 📱 Responsive Design

The component is fully responsive with:
- **Mobile**: Bottom sheet layout, larger touch targets
- **Tablet**: Optimized positioning and sizing
- **Desktop**: Traditional floating UI with compact controls

## 🛠️ Advanced Usage

### Without AI Mode (Keyword Matching Only)

You can use the component without OpenAI by simply not setting the `OPENAI_API_KEY` or by keeping AI mode disabled:

```tsx
<VoiceNavigationAdvanced
  defaultAIMode={false}
/>
```

### Custom API Endpoint

If you're hosting the API route at a different path:

```tsx
<VoiceNavigationAdvanced
  apiEndpoint="/api/custom/voice"
/>
```

### Programmatic Control

Access the component via ref for programmatic control (advanced):

```tsx
const voiceNavRef = useRef()

// Toggle listening programmatically
voiceNavRef.current?.toggleListening()
```

## 🧪 Testing

The component includes built-in error handling for:
- Microphone permission denied
- Network failures
- API errors
- Unsupported browsers

## 📄 License

MIT © [LiaPlus](https://github.com/liaplus)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📞 Support

- 📧 Email: support@liaplus.com
- 🐛 Issues: [GitHub Issues](https://github.com/liaplus/voice-navigation-ai/issues)
- 📖 Documentation: [Full Documentation](https://github.com/liaplus/voice-navigation-ai/wiki)

## 🙏 Acknowledgments

- Built with [Next.js](https://nextjs.org/)
- Powered by [OpenAI](https://openai.com/)
- Icons by [Lucide](https://lucide.dev/)
- UI components inspired by [shadcn/ui](https://ui.shadcn.com/)

---

Made with ❤️ by [LiaPlus](https://liaplus.com)