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

@lilith/ui-effects-mouse

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

Installation

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.

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.

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:

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