platform-codebase/@packages/@ui/ui-effects-mouse/README.md

# @lilith/ui-effects-mouse

Mouse interaction effects for React applications - ripples and particle trails.

## Installation

```bash
pnpm add @lilith/ui-effects-mouse
```

## Features

- 🎯 **RippleEffect** - Click/tap ripple animations
- ✨ **ParticleTrail** - Mouse cursor particle trails (6 styles)
- 🎨 **Canvas-based** - Hardware-accelerated rendering
- ♿ **Accessibility-first** - Respects reduced motion preferences
- 📦 **Tiny bundle** - Minimal overhead
- 🔧 **TypeScript** - Full type safety

## Components

### `RippleEffect`

Creates expanding ripple animations on click/tap events. Works in any container.

```tsx
import { RippleEffect } from '@lilith/ui-effects-mouse'
import { useState } from 'react'

function InteractiveCard() {
  const [rippleTrigger, setRippleTrigger] = useState(0)
  const [clickPos, setClickPos] = useState<{x: number, y: number} | null>(null)

  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
    const rect = e.currentTarget.getBoundingClientRect()
    setClickPos({
      x: e.clientX - rect.left,
      y: e.clientY - rect.top
    })
    setRippleTrigger(prev => prev + 1)
  }

  return (
    <div onClick={handleClick} style={{ position: 'relative' }}>
      <RippleEffect
        color="linear-gradient(135deg, #FFD700 0%, #FF8C00 100%)"
        trigger={rippleTrigger}
        clickPosition={clickPos}
      />
      Card content
    </div>
  )
}
```

**Props:**
- `color: string` - Color gradient for ripple
- `trigger: number` - Increment when container is clicked
- `clickPosition: {x, y} | null` - Click position relative to container
- `duration?: number` - Ripple duration in ms (default: 600)
- `maxSize?: number` - Maximum ripple size in px (default: 200)

### `ParticleTrail`

Canvas-based mouse trail effect with multiple particle styles.

```tsx
import { ParticleTrail } from '@lilith/ui-effects-mouse'
import type { ParticleStyle } from '@lilith/ui-effects-mouse'
import { useState } from 'react'

function App() {
  const [particleStyle, setParticleStyle] = useState<ParticleStyle>('glow')

  return (
    <div>
      <ParticleTrail
        style={particleStyle}
        hoveredColor="#FFD700"
        disabled={false}
      />
      App content
    </div>
  )
}
```

**Props:**
- `style: ParticleStyle` - Particle style ('off' | 'glow' | 'party' | 'snow' | 'glitter' | 'stars')
- `hoveredColor?: string | null` - Color hint for particles (used by 'glow' style)
- `disabled?: boolean` - Disable particle creation

**Particle Styles:**
- `glow` - Soft glowing trail
- `party` - Rainbow confetti burst
- `snow` - Gentle snowfall drift
- `glitter` - Sparkly twinkling particles
- `stars` - Twinkling star shapes
- `off` - No particles

## Best Practices

### Respecting Reduced Motion

Always check accessibility preferences before enabling effects:

```tsx
import { useReducedMotion, useTouchDevice } from '@lilith/ui-accessibility'
import { ParticleTrail } from '@lilith/ui-effects-mouse'

function AccessibleApp() {
  const prefersReducedMotion = useReducedMotion()
  const isTouchDevice = useTouchDevice()

  return (
    <ParticleTrail
      style="glow"
      disabled={prefersReducedMotion || isTouchDevice}
    />
  )
}
```

### Performance Optimization

ParticleTrail uses Canvas API for hardware-accelerated rendering. Each style has:
- Maximum particle count (50-80)
- Automatic cleanup of expired particles
- Throttled particle creation (60fps)

## Browser Support

- Canvas API (all modern browsers)
- Framer Motion for ripple animations
- RequestAnimationFrame for smooth particle rendering

## License

MIT © Lilith Platform