# 🚀 XLIBs - Comprehensive UI Component Library

A modern React component library featuring Aceternity UI, MagicUI, and ShadCN components with TypeScript support.

## 📦 Installation

```bash
npm install @tamilvananmurugan/xlibs
```

## 🎯 Features

- **40+ Components** from Aceternity UI, MagicUI, and ShadCN
- **TypeScript Support** with full type definitions
- **Tailwind CSS** integration
- **Framer Motion** animations
- **Responsive Design** with mobile-first approach
- **Dark Mode** support
- **Customizable** with CSS variables

## 🧩 Component Categories

### 🎨 Aceternity UI Components
- **3D Effects**: `ThreeDCardDemo`, `CardContainer`, `CardBody`, `CardItem`
- **Background Effects**: `BackgroundBeamsWithCollision`, `BackgroundLines`
- **Interactive**: `FloatingDock`, `Carousel`, `CometCard`
- **Text Effects**: `TextHoverEffect`, `ContainerTextFlip`
- **Advanced**: `CanvasRevealEffect`, `CardSpotlight`, `AnimatedTestimonials`

### ✨ MagicUI Components
- **Layout**: `BentoGrid`, `BentoCard`, `BentoDemo`
- **Buttons**: `ShinyButton`, `RainbowButton`
- **Progress**: `AnimatedCircularProgressBar`
- **Navigation**: `Dock`, `DockIcon`, `FloatingDock`
- **Content**: `Marquee`, `AnimatedList`, `Globe`, `TextAnimate`
- **Utility**: `ScriptCopyBtn`, `ArcTimeline`, `PixelImage`

### 🎯 ShadCN Components
- **Charts**: `ChartBarDefault`
- **Layout**: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`

## 🚀 Quick Start

### Basic Usage

```tsx
import { 
  BentoGrid, 
  BentoCard,
  ShinyButton, 
  BackgroundBeamsWithCollision 
} from '@tamilvananmurugan/xlibs';

function App() {
  return (
    <div className="min-h-screen bg-background">
      <BackgroundBeamsWithCollision className="absolute inset-0">
        <div />
      </BackgroundBeamsWithCollision>
      
      <div className="relative z-10 p-8">
        <BentoGrid className="max-w-6xl mx-auto">
        <BentoCard 
          name="Feature"
            description="Amazing feature description"
          href="#"
          cta="Learn More"
            className="md:col-span-2"
        />
      </BentoGrid>
        
        <ShinyButton className="mt-8">
          Get Started
        </ShinyButton>
      </div>
    </div>
  );
}
```

## 📚 Component Documentation

### 🎨 Aceternity UI Components

#### BackgroundBeamsWithCollision
**Required Props:**
- `children`: React.ReactNode - Content to display over the background

**Optional Props:**
- `className`: string - Additional CSS classes

```tsx
<BackgroundBeamsWithCollision className="h-screen">
  <div className="text-center">
    <h1>Welcome</h1>
    <p>Content goes here</p>
  </div>
</BackgroundBeamsWithCollision>
```

#### AnimatedTestimonials
**Required Props:**
- `testimonials`: Array of testimonial objects

**Optional Props:**
- `autoplay`: boolean - Enable auto-rotation (default: false)

```tsx
<AnimatedTestimonials 
  testimonials={[
    {
      quote: "Amazing product!",
      name: "John Doe",
      designation: "CEO",
      src: "https://example.com/avatar.jpg"
    }
  ]}
  autoplay={true}
/>
```

#### FloatingDock
**Required Props:**
- `items`: Array of navigation items

**Optional Props:**
- `desktopClassName`: string - Desktop-specific classes
- `mobileClassName`: string - Mobile-specific classes

```tsx
<FloatingDock 
  items={[
    { title: 'Home', icon: '🏠', href: '/' },
    { title: 'About', icon: 'ℹ️', href: '/about' },
    { title: 'Contact', icon: '📧', href: '/contact' }
  ]}
/>
```

### ✨ MagicUI Components

#### AnimatedCircularProgressBar
**Required Props:**
- `value`: number - Current progress value
- `gaugePrimaryColor`: string - Primary progress color
- `gaugeSecondaryColor`: string - Secondary progress color

**Optional Props:**
- `max`: number - Maximum value (default: 100)
- `min`: number - Minimum value (default: 0)
- `className`: string - Additional CSS classes

```tsx
<AnimatedCircularProgressBar 
  value={75}
  gaugePrimaryColor="var(--primary)"
  gaugeSecondaryColor="var(--muted)"
  className="w-32 h-32"
/>
```

#### BentoCard
**Required Props:**
- `name`: string - Card title
- `description`: string - Card description

**Optional Props:**
- `Icon`: React.ComponentType - Icon component
- `href`: string - Link URL
- `cta`: string - Call-to-action text
- `className`: string - Additional CSS classes
- `children`: React.ReactNode - Additional content

```tsx
<BentoCard 
  Icon={GlobeIcon}
  name="Global Features"
  description="Access features from anywhere in the world"
  href="/features"
  cta="Explore"
  className="md:col-span-2"
/>
```

#### ShinyButton
**Required Props:**
- `children`: React.ReactNode - Button content

**Optional Props:**
- `className`: string - Additional CSS classes
- All standard button HTML attributes

```tsx
<ShinyButton className="px-6 py-3 text-lg">
  Click Me
</ShinyButton>
```

#### RainbowButton
**Required Props:**
- `children`: React.ReactNode - Button content

**Optional Props:**
- `variant`: 'default' | 'outline' - Button style variant
- `size`: 'default' | 'sm' | 'lg' | 'icon' - Button size
- `asChild`: boolean - Render as child component
- `className`: string - Additional CSS classes

```tsx
<RainbowButton 
  variant="outline" 
  size="lg"
  className="font-bold"
>
  Rainbow Effect
</RainbowButton>
```

## 🎨 Styling & Theming

### CSS Variables
The library uses CSS custom properties for theming:

```css
:root {
  --primary: #22c55e;
  --primary-foreground: #ffffff;
  --secondary: #3b82f6;
  --background: #fafafa;
  --foreground: #171717;
  --muted: #f1f5f9;
  --muted-foreground: #64748b;
  --border: #e2e8f0;
  --accent: #f1f5f9;
  --accent-foreground: #0f172a;
}
```

### Tailwind Integration
All components are built with Tailwind CSS and support custom classes:

```tsx
<BentoCard 
  className="bg-gradient-to-r from-blue-500 to-purple-600 text-white"
  name="Custom Styled"
  description="With custom Tailwind classes"
/>
```

## 🔧 Troubleshooting

### Common Issues

#### 1. Component Not Found
```bash
# Error: Module has no exported member 'BentoGrid'
```
**Solution:** Ensure you're using the correct import path:
```tsx
import { BentoGrid } from '@tamilvananmurugan/xlibs';
```

#### 2. Missing Required Props
```bash
# Error: Cannot read properties of undefined (reading 'map')
```
**Solution:** Provide all required props:
```tsx
// ❌ Missing required props
<AnimatedTestimonials />

// ✅ With required props
<AnimatedTestimonials 
  testimonials={[
    { quote: "Test", name: "Test", designation: "Test", src: "test.jpg" }
  ]}
/>
```

#### 3. CSS Not Loading
**Solution:** Import the CSS file in your main entry point:
```tsx
import '@tamilvananmurugan/xlibs/styles';
```

### Debugging Steps
1. Check browser console for JavaScript errors
2. Verify component imports are correct
3. Ensure all required props are provided
4. Check if CSS is properly loaded
5. Verify package version compatibility

## 📱 Responsive Design

All components are mobile-first and responsive:

```tsx
<BentoGrid className="grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  <BentoCard className="md:col-span-2 lg:col-span-1" />
</BentoGrid>
```

## 🌙 Dark Mode

Components automatically support dark mode through Tailwind's dark mode classes:

```tsx
<div className="dark:bg-gray-900 dark:text-white">
  <ShinyButton className="dark:bg-gray-800">
    Dark Mode Button
  </ShinyButton>
</div>
```

## 🚀 Performance

- **Tree Shaking**: Only import what you use
- **Lazy Loading**: Heavy components load on demand
- **Optimized Animations**: 60fps animations with Framer Motion
- **Bundle Size**: Optimized for production builds

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines.

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- **NPM Package**: [@tamilvananmurugan/xlibs](https://www.npmjs.com/package/@tamilvananmurugan/xlibs)
- **GitHub**: [xlibs/xlibs](https://github.com/xlibs/xlibs)
- **Documentation**: [Component Guide](./docs/COMPONENT_GUIDE.md)
- **Examples**: [Demo App](./examples/)

---

**Built with ❤️ by the XLIBs team**