npm package: @mayurkakade/bot-avatar
Description: An interactive 3D bot avatar component built with React Three Fiber. Features customizable emotions, speaking animations, and smooth transitions.
Author: Mayur Kakade
Latest version: 1.0.0

# Bot Avatar

An interactive 3D bot avatar component built with React Three Fiber. Features smooth animations, customizable themes, and expressive states.

## Features

- Multiple bot states (IDLE, LISTENING, THINKING, TALKING, SURPRISED, SAD)
- Customizable color themes
- Smooth animations and transitions
- Eye tracking and mouth animations
- Particle effects during speech
- Fully composable component architecture

## Installation

```bash
npm install @mayurkakade/bot-avatar
```

### Peer Dependencies

Make sure you have the following peer dependencies installed:

```bash
npm install react react-dom three @react-three/fiber @react-three/drei @react-three/postprocessing
```

## Usage

### Basic Example (New Expression System)

The new expression system allows you to combine emotions with activities like speaking!

```tsx
import React, { useState } from 'react';
import { BotScene, BotExpression, createExpression } from '@mayurkakade/bot-avatar';

function App() {
  const [expression, setExpression] = useState<BotExpression>(
    createExpression('NEUTRAL', 'IDLE')
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene expression={expression} />

      <button onClick={() => setExpression(createExpression('HAPPY', 'SPEAKING'))}>
        Happy Speaking
      </button>
      <button onClick={() => setExpression(createExpression('SAD', 'SPEAKING'))}>
        Sad Speaking
      </button>
    </div>
  );
}
```

### Using Helper Functions

```tsx
import { BotScene, BotExpressions } from '@mayurkakade/bot-avatar';

function App() {
  const [expression, setExpression] = useState(BotExpressions.neutral());

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene expression={expression} />

      <button onClick={() => setExpression(BotExpressions.happySpeaking())}>
        Happy Speaking
      </button>
      <button onClick={() => setExpression(BotExpressions.surprisedSpeaking())}>
        Surprised Speaking
      </button>
      <button onClick={() => setExpression(BotExpressions.sadSpeaking())}>
        Sad Speaking
      </button>
    </div>
  );
}
```

### Legacy State API (Still Supported)

```tsx
import React, { useState } from 'react';
import { BotScene, BotState } from '@mayurkakade/bot-avatar';

function App() {
  const [botState, setBotState] = useState<BotState>('IDLE');

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene botState={botState} />

      <button onClick={() => setBotState('TALKING')}>
        Make Bot Talk
      </button>
    </div>
  );
}
```

### Using Custom Colors

```tsx
import { BotScene, BotColors, THEME_PRESETS } from '@mayurkakade/bot-avatar';

const customColors: BotColors = {
  primary: '#ff6b6b',
  secondary: '#4ecdc4',
  tertiary: '#ffe66d'
};

function App() {
  return (
    <BotScene
      botState="IDLE"
      colors={customColors}
    />
  );
}

// Or use built-in presets
function AppWithPreset() {
  return (
    <BotScene
      botState="IDLE"
      colors={THEME_PRESETS.Emerald}
    />
  );
}
```

### Look At Control

```tsx
import { BotScene, BotLookAt } from '@mayurkakade/bot-avatar';

function App() {
  const [lookAt, setLookAt] = useState<BotLookAt>({ x: 0, y: 0 });

  const handleMouseMove = (e: MouseEvent) => {
    const x = (e.clientX / window.innerWidth) * 2 - 1;
    const y = -(e.clientY / window.innerHeight) * 2 + 1;
    setLookAt({ x, y });
  };

  return (
    <div onMouseMove={handleMouseMove} style={{ width: '100vw', height: '100vh' }}>
      <BotScene
        botState="IDLE"
        lookAt={lookAt}
      />
    </div>
  );
}
```

### Composable Components

For advanced use cases, you can use individual components:

```tsx
import { Canvas } from '@react-three/fiber';
import {
  BotAvatar,
  SceneLighting,
  Rings,
  BotColors
} from '@mayurkakade/bot-avatar';

function CustomScene() {
  const colors: BotColors = {
    primary: '#00bcd4',
    secondary: '#9c27b0',
    tertiary: '#ff5722'
  };

  return (
    <Canvas>
      <SceneLighting state="IDLE" colors={colors} />
      <BotAvatar state="TALKING" colors={colors} lookAt={{ x: 0, y: 0 }} />
      <Rings />
    </Canvas>
  );
}
```

## API Reference

### BotScene

Main component that renders the complete bot scene.

**Props:**
- `expression?: BotExpression` - Bot expression (emotion + activity) - **New!**
- `botState?: BotState` - Current state (legacy support)
- `colors?: BotColors` - Custom color scheme (optional, defaults to Gemini theme)
- `lookAt?: BotLookAt` - Look direction (optional, defaults to { x: 0, y: 0 })

### BotAvatar

The avatar component without the Canvas wrapper.

**Props:**
- `expression?: BotExpression` - Bot expression (emotion + activity) - **New!**
- `state?: BotState` - Current state (legacy support)
- `colors: BotColors` - Color scheme
- `lookAt?: BotLookAt` - Look direction (optional)

### Helper Functions

#### createExpression
```tsx
createExpression(emotion: BotEmotion, activity?: BotActivity): BotExpression
```

#### BotExpressions
Pre-built expressions for quick use:
```tsx
BotExpressions.neutral()
BotExpressions.neutralSpeaking()
BotExpressions.happy()
BotExpressions.happySpeaking()
BotExpressions.surprised()
BotExpressions.surprisedSpeaking()
BotExpressions.sad()
BotExpressions.sadSpeaking()
BotExpressions.thinking()
BotExpressions.thinkingSpeaking()
// ... and more
```

### Types

#### BotExpression (New!)
```tsx
interface BotExpression {
  emotion: BotEmotion;
  activity: BotActivity;
}

type BotEmotion = 'NEUTRAL' | 'HAPPY' | 'SURPRISED' | 'SAD' | 'THINKING';
type BotActivity = 'IDLE' | 'LISTENING' | 'SPEAKING';
```

**Key Feature:** You can now combine any emotion with any activity! For example:
- `{ emotion: 'HAPPY', activity: 'SPEAKING' }` - Bot speaks while happy
- `{ emotion: 'SAD', activity: 'SPEAKING' }` - Bot speaks while sad
- `{ emotion: 'SURPRISED', activity: 'LISTENING' }` - Bot listens while surprised

#### BotState (Legacy)
```tsx
type BotState = 'IDLE' | 'LISTENING' | 'THINKING' | 'TALKING' | 'SURPRISED' | 'SAD';
```

#### BotColors
```tsx
interface BotColors {
  primary: string;   // Main face color (e.g. Cyan)
  secondary: string; // Secondary gradient color (e.g. Purple)
  tertiary: string;  // Accent/Tertiary gradient color (e.g. Orange)
}
```

#### BotLookAt
```tsx
interface BotLookAt {
  x: number; // Horizontal direction (-1 to 1)
  y: number; // Vertical direction (-1 to 1)
}
```

### Theme Presets

```tsx
import { THEME_PRESETS } from '@mayurkakade/bot-avatar';

// Available presets:
THEME_PRESETS.Gemini
THEME_PRESETS.Emerald
THEME_PRESETS.Rose
THEME_PRESETS.Amber
THEME_PRESETS.Slate
```

## Development

```bash
# Install dependencies
npm install

# Run demo
npm run dev

# Build library
npm run build

# Build demo
npm run build:demo
```

## License

MIT