@tamilvananmurugan/xlibs/DEVELOPER_GUIDE.md

A comprehensive React UI component library with MagicUI, Aceternity UI, Chart components, and more. IMPORTANT: Import CSS separately for proper styling.

# 🚀 XLIBs Developer Guide

## 📦 NPM Package: @tamilvananmurugan/xlibs

A comprehensive React UI component library with MagicUI, Aceternity UI, Chart components, and smart component selection system.

---


## 🛠️ Installation

### **Latest Version (Recommended)**
```bash
npm install @tamilvananmurugan/xlibs
```

### **Specific Version**
```bash
npm install @tamilvananmurugan/xlibs@1.0.9
```

### **Yarn Installation**
```bash
yarn add @tamilvananmurugan/xlibs
```

---


## 📋 Dependencies

### **Peer Dependencies (Required)**
```json
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}
```

### **Included Dependencies (Bundled)**
- `framer-motion` - Animation library
- `recharts` - Chart components
- `lucide-react` - Icon library
- `@radix-ui/*` - UI primitives
- `tailwind-merge` - CSS utility merging
- `class-variance-authority` - Component variants

---


## 🎯 Basic Usage

### **1. Import Components**
```javascript
import { 
  Card, 
  AnimatedGradientText, 
  ChartBar,
  BentoGrid,
  BentoCard 
} from '@tamilvananmurugan/xlibs';
```

### **2. Import CSS (Required)**
```javascript
import '@tamilvananmurugan/xlibs/xlibs.css';
```

### **3. Use Components**
```jsx
function App() {
  return (
    <div className="p-8">
      <AnimatedGradientText 
        text="Welcome to XLIBs" 
        className="text-4xl font-bold" 
      />
      
      <Card className="mt-6">
        <CardBody>
          <h2>Component Library</h2>
          <p>Build beautiful UIs with ease</p>
        </CardBody>
      </Card>
    </div>
  );
}
```

---


## 🎨 Component Categories

### **Card Components**
```javascript
import { 
  Card, CardBody, CardHeader, CardTitle, 
  CardDescription, CardContent, CardFooter 
} from '@tamilvananmurugan/xlibs';
```

### **Text Animation Components**
```javascript
import { 
  AnimatedGradientText, AnimatedShinyText, 
  TextGenerateEffect, FlipWords 
} from '@tamilvananmurugan/xlibs';
```

### **Chart Components**
```javascript
import { 
  ChartBar, ChartAreaInteractive, ChartBarStacked,
  ChartContainer, ChartTooltip 
} from '@tamilvananmurugan/xlibs';
```

### **Magic UI Components**
```javascript
import { 
  AnimatedBeam, BorderBeam, MagicCard,
  ShinyButton, RainbowButton 
} from '@tamilvananmurugan/xlibs';
```

### **Layout Components**
```javascript
import { 
  BentoGrid, BentoCard, LayoutGrid,
  Tabs, FadeInDiv 
} from '@tamilvananmurugan/xlibs';
```

---


## 🧠 Smart Component Selection

### **Using Smart Selector**
```javascript
import { SmartComponentSelector } from '@tamilvananmurugan/xlibs';

function ComponentPicker() {
  return (
    <SmartComponentSelector 
      useCase="Create a dashboard card with charts"
      variant="modern"
      size="lg"
    />
  );
}
```

### **Programmatic Selection**
```javascript
import { 
  getComponentsByLayoutHint, 
  getComponentMetadata 
} from '@tamilvananmurugan/xlibs';

// Get components for specific layout
const cardComponents = getComponentsByLayoutHint('card');

// Get component metadata
const cardInfo = getComponentMetadata('Card');
```

---


## 📱 YAML Configuration for Cursor AI

### **Content YAML Structure**
```yaml
# content.yaml
screens:
  dashboard:
    title: "Dashboard"
    description: "Main dashboard with analytics and charts"
    components:
      - type: "header"
        content: "Welcome to Dashboard"
        style: "gradient-text"
      
      - type: "stats-grid"
        items:
          - label: "Total Users"
            value: "12,345"
            trend: "+12%"
          - label: "Revenue"
            value: "$45,678"
            trend: "+8%"
      
      - type: "chart-section"
        title: "Analytics Overview"
        charts:
          - type: "bar-chart"
            data: "user-growth-data"
          - type: "line-chart"
            data: "revenue-trend-data"
      
      - type: "recent-activity"
        title: "Recent Activities"
        items: "activity-feed-data"

  profile:
    title: "User Profile"
    description: "User profile management screen"
    components:
      - type: "profile-header"
        avatar: "user-avatar"
        name: "John Doe"
        role: "Administrator"
      
      - type: "profile-form"
        fields:
          - name: "email"
            type: "email"
            required: true
          - name: "phone"
            type: "tel"
            required: false
      
      - type: "action-buttons"
        primary: "Save Changes"
        secondary: "Cancel"
```

### **Layout YAML Structure**
```yaml
# layout.yaml
layouts:
  dashboard:
    type: "bento-grid"
    grid:
      rows: 3
      columns: 4
      gap: "1rem"
    
    sections:
      header:
        position: [1, 1, 4, 1]
        component: "AnimatedGradientText"
        props:
          text: "Dashboard"
          className: "text-4xl font-bold"
      
      stats:
        position: [1, 2, 4, 1]
        component: "BentoGrid"
        props:
          className: "grid-cols-4 gap-4"
        children:
          - component: "Card"
            props:
              className: "p-4 text-center"
            children:
              - component: "CardTitle"
                content: "Total Users"
              - component: "CardContent"
                content: "12,345"
      
      charts:
        position: [2, 1, 2, 2]
        component: "ChartContainer"
        children:
          - component: "ChartBar"
            props:
              data: "user-data"
              size: "lg"
      
      sidebar:
        position: [2, 3, 2, 2]
        component: "Sidebar"
        props:
          className: "bg-gray-50 p-4"
        children:
          - component: "Timeline"
            props:
              data: "activity-data"

  profile:
    type: "centered-layout"
    maxWidth: "2xl"
    padding: "2rem"
    
    sections:
      header:
        component: "Card"
        props:
          className: "mb-6"
        children:
          - component: "CardHeader"
            children:
              - component: "CardTitle"
                content: "Profile Settings"
      
      form:
        component: "Card"
        children:
          - component: "CardContent"
            className: "space-y-4"
            children:
              - component: "Input"
                props:
                  type: "email"
                  placeholder: "Email"
                  required: true
              - component: "Input"
                props:
                  type: "tel"
                  placeholder: "Phone"
      
      actions:
        component: "div"
        className: "flex gap-4 justify-end mt-6"
        children:
          - component: "ShinyButton"
            props:
              variant: "outline"
            content: "Cancel"
          - component: "ShinyButton"
            content: "Save Changes"
```

---


## 🤖 Cursor AI Prompting Guide

### **Basic Screen Creation Prompt**
```
Create a React screen using @tamilvananmurugan/xlibs package with the following requirements:

1. Import the required components from '@tamilvananmurugan/xlibs'
2. Import CSS: import '@tamilvananmurugan/xlibs/xlibs.css'
3. Use BentoGrid layout for responsive design
4. Include the following components:
   - Header with AnimatedGradientText
   - Stats cards using Card components
   - Chart section with ChartBar
   - Sidebar with navigation
5. Use Tailwind CSS for styling
6. Make it responsive and mobile-friendly
```

### **Advanced Layout Prompt**
```
Create a complex dashboard layout using @tamilvananmurugan/xlibs with:

1. BentoGrid layout system (3x4 grid)
2. Magic UI components for animations
3. Chart components for data visualization
4. Responsive sidebar navigation
5. Interactive hover effects
6. Proper TypeScript types
7. Tailwind CSS styling
8. Framer Motion animations

Use the component library's smart selection system and ensure all imports are correct.
```

### **Component-Specific Prompt**
```
Create a data visualization screen using @tamilvananmurugan/xlibs chart components:

1. Import ChartBar, ChartAreaInteractive, ChartContainer
2. Use Card components for layout structure
3. Implement responsive chart sizing
4. Add proper TypeScript interfaces for data
5. Include chart legends and tooltips
6. Use the package's built-in chart utilities
7. Ensure proper CSS imports for styling
```

---


## 🎨 Bento Grid Layout Examples

### **Basic Bento Grid**
```jsx
import { BentoGrid, BentoCard } from '@tamilvananmurugan/xlibs';

function Dashboard() {
  return (
    <BentoGrid className="max-w-6xl mx-auto p-4">
      <BentoCard 
        name="Analytics"
        description="View your data insights"
        Icon={ChartIcon}
        href="/analytics"
        cta="View Details"
      />
      <BentoCard 
        name="Users"
        description="Manage user accounts"
        Icon={UsersIcon}
        href="/users"
        cta="Manage Users"
      />
      <BentoCard 
        name="Settings"
        description="Configure your application"
        Icon={SettingsIcon}
        href="/settings"
        cta="Configure"
      />
    </BentoGrid>
  );
}
```

### **Custom Grid Layout**
```jsx
import { LayoutGrid } from '@tamilvananmurugan/xlibs';

function CustomLayout() {
  const cards = [
    {
      id: 1,
      content: <ChartBar data={chartData} />,
      className: "col-span-2 row-span-2",
      thumbnail: "/chart-preview.jpg"
    },
    {
      id: 2,
      content: <UserStats />,
      className: "col-span-1 row-span-1",
      thumbnail: "/stats-preview.jpg"
    }
  ];

  return (
    <LayoutGrid cards={cards} />
  );
}
```

---


## 🔧 Troubleshooting

### **Common Issues**

1. **Components not importing**
   - Ensure you're using the latest version
   - Check import syntax
   - Verify CSS is imported

2. **Styling not working**
   - Import CSS: `import '@tamilvananmurugan/xlibs/xlibs.css'`
   - Ensure Tailwind CSS is configured
   - Check component className props

3. **TypeScript errors**
   - Install types: `npm install @types/react @types/react-dom`
   - Check component prop interfaces
   - Verify import paths

### **Debug Commands**
```bash
# Check package version
npm list @tamilvananmurugan/xlibs

# Reinstall package
npm uninstall @tamilvananmurugan/xlibs
npm install @tamilvananmurugan/xlibs

# Check available exports
node -e "console.log(Object.keys(require('@tamilvananmurugan/xlibs')))"
```

---


## 📚 Additional Resources

- **Package**: [@tamilvananmurugan/xlibs](https://www.npmjs.com/package/@tamilvananmurugan/xlibs)
- **Documentation**: See `COMPONENT_USAGE_GUIDE.md` for detailed component usage
- **Examples**: Check the `docs/` folder for usage examples
- **Issues**: Report issues on the package repository

---


## 🚀 Quick Start Template

```jsx
import React from 'react';
import { 
  Card, 
  CardBody, 
  AnimatedGradientText,
  BentoGrid,
  BentoCard 
} from '@tamilvananmurugan/xlibs';
import '@tamilvananmurugan/xlibs/xlibs.css';

function App() {
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <AnimatedGradientText 
        text="Welcome to XLIBs" 
        className="text-5xl font-bold text-center mb-8" 
      />
      
      <BentoGrid className="max-w-6xl mx-auto">
        <BentoCard 
          name="Get Started"
          description="Begin building your UI"
          href="/docs"
          cta="Learn More"
        />
      </BentoGrid>
    </div>
  );
}

export default App;
```

---


**Happy coding with XLIBs! 🎉**