npm package: @shimmerbyte/drag-cart
Description: A highly configurable drag-and-drop shopping cart system for React applications
Author: SHiMMeRbyte
Latest version: 1.0.0

# @shimmerbyte/drag-cart

A highly configurable, TypeScript-first drag-and-drop shopping cart system for React applications. Provides smooth animations, customizable theming, and minimal dependencies.

## ✨ Features

- 🎯 **Zero Dependencies** - Only React and React-DOM as peer dependencies
- 🎨 **Fully Customizable** - Complete theming and styling control
- 📱 **Touch Friendly** - Works on mobile and desktop
- 🔧 **TypeScript Native** - Full type safety with generics
- 🚀 **Performance Optimized** - Minimal re-renders and efficient animations
- 💾 **Persistence Built-in** - localStorage/sessionStorage support (Pro+)
- 🎭 **Render Props** - Custom render functions for complete control (Pro+)
- 🧩 **Modular Design** - Use individual hooks and components as needed
- 📊 **Analytics Ready** - Built-in tracking for cart interactions (Pro+)
- 🆓 **Freemium Model** - Start free, upgrade when you need more

## 💰 Pricing

### Free Tier
- ✅ Up to 5 items per cart
- ✅ Basic drag & drop functionality
- ✅ Standard animations
- ✅ Community support
- ⚠️ Includes watermark

### Pro Tier - $29/month
- ✅ Up to 100 items per cart
- ✅ Multiple carts (up to 5)
- ✅ Custom themes & advanced animations
- ✅ Cart persistence
- ✅ Analytics tracking
- ✅ Custom render functions
- ✅ No watermark
- ✅ Priority support

### Enterprise Tier - $99/month
- ✅ Unlimited items & carts
- ✅ White-label licensing
- ✅ Advanced customization
- ✅ Dedicated support
- ✅ Custom integrations

[**Get your license key →**](https://shimmerbyte.com/drag-cart/pricing)

## 📦 Installation

```bash
npm install @shimmerbyte/drag-cart
# or
yarn add @shimmerbyte/drag-cart
```

## 🚀 Quick Start

### Basic Setup (Free Tier)

```tsx
import React from 'react';
import { 
  CartProvider, 
  DragCart, 
  useDragHandlers, 
  useCartMethods 
} from '@shimmerbyte/drag-cart';

// Your product type
interface Product {
  id: string;
  title: string;
  price: number;
  image?: string;
}

// Draggable product component
const ProductCard: React.FC<{ product: Product }> = ({ product }) => {
  const dragHandlers = useDragHandlers<Product>();
  
  return (
    <div className="product-card">
      <h3>{product.title}</h3>
      <p>${product.price}</p>
      
      {/* Drag handle */}
      <button
        onMouseDown={(e) => dragHandlers.onMouseDown(e, {
          id: product.id,
          data: product
        })}
        className="drag-handle"
      >
        🛒 Drag to Cart
      </button>
    </div>
  );
};

// Cart display component
const CartDisplay: React.FC = () => {
  const { items, itemCount, removeItem } = useCartMethods<Product>();
  
  return (
    <div className="cart">
      <h3>Cart ({itemCount} items)</h3>
      {items.map(item => (
        <div key={item.id} className="cart-item">
          <span>{item.data.title}</span>
          <span>${item.data.price}</span>
          <button onClick={() => removeItem(item.id)}>Remove</button>
        </div>
      ))}
    </div>
  );
};

// Main app
const App: React.FC = () => {
  const products: Product[] = [
    { id: '1', title: 'Awesome Product', price: 29.99 },
    { id: '2', title: 'Cool Gadget', price: 49.99 },
  ];

  return (
    <CartProvider<Product>>
      <div className="app">
        <div className="products">
          {products.map(product => (
            <ProductCard key={product.id} product={product} />
          ))}
        </div>
        
        <CartDisplay />
        
        {/* Drag and drop system */}
        <DragCart<Product> 
          onDrop={(item) => console.log('Added to cart:', item.data.title)}
        />
      </div>
    </CartProvider>
  );
};
```

### Pro Setup with License Key

```tsx
import { CartProvider } from '@shimmerbyte/drag-cart';

const proConfig = {
  license: {
    tier: 'pro' as const,
    apiKey: 'your-pro-license-key-here',
  },
  maxItems: 100,
  persistence: {
    key: 'my-app-cart',
    storage: 'localStorage',
  },
  analytics: {
    enabled: true,
    trackingId: 'your-analytics-id',
  },
};

<CartProvider<Product> config={proConfig}>
  {/* Your app */}
</CartProvider>
```

## 🔑 License Management

### Getting Your License Key

1. Visit [shimmerbyte.com/drag-cart/pricing](https://shimmerbyte.com/drag-cart/pricing)
2. Choose your plan (Pro or Enterprise)
3. Complete the checkout process
4. You'll receive your license key via email
5. Add it to your configuration

### License Configuration

```tsx
import { LicenseConfig } from '@shimmerbyte/drag-cart';

const licenseConfig: LicenseConfig = {
  tier: 'pro', // 'free' | 'pro' | 'enterprise'
  apiKey: 'pk_live_your_license_key_here',
  // Optional: Set expiration for trial licenses
  expiresAt: '2024-12-31T23:59:59Z',
};
```

### Environment Variables

For security, store your license key in environment variables:

```bash
# .env
REACT_APP_DRAG_CART_LICENSE_KEY=pk_live_your_license_key_here
```

```tsx
const config = {
  license: {
    tier: 'pro' as const,
    apiKey: process.env.REACT_APP_DRAG_CART_LICENSE_KEY,
  },
};
```

### License Validation

The library automatically validates your license:

```tsx
import { useLicense } from '@shimmerbyte/drag-cart';

const MyComponent = () => {
  const { isValid, error, canUseFeature, upgradeUrl } = useLicense();
  
  if (!isValid) {
    return (
      <div>
        <p>License error: {error}</p>
        <a href={upgradeUrl}>Upgrade Now</a>
      </div>
    );
  }
  
  return (
    <div>
      {canUseFeature('customThemes') && <CustomThemeSelector />}
      {canUseFeature('analytics') && <AnalyticsDashboard />}
    </div>
  );
};
```

## 🎨 Theming & Customization

### Basic Theming (All Tiers)

```tsx
const basicTheme = {
  colors: {
    primary: '#your-brand-color',
    secondary: '#your-secondary-color',
  },
};

<CartProvider theme={basicTheme}>
  {/* Your app */}
</CartProvider>
```

### Advanced Theming (Pro+ Only)

```tsx
const advancedTheme = {
  overlay: {
    background: 'rgba(255, 255, 255, 0.95)',
    border: '3px solid #ff6b6b',
    borderRadius: '12px',
    shadow: '0 20px 40px rgba(255, 107, 107, 0.3)',
  },
  animations: {
    duration: '400ms',
    easing: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
  },
};
```

### Custom Render Functions (Pro+ Only)

```tsx
const CustomDragCart: React.FC = () => {
  return (
    <DragCart<Product>
      renderOverlay={(item, isOverDropZone) => (
        <div className={`custom-overlay ${isOverDropZone ? 'active' : ''}`}>
          <img src={item.data.image} alt={item.data.title} />
          <h4>{item.data.title}</h4>
          <p>${item.data.price}</p>
          {isOverDropZone && <span>✅ Ready to add!</span>}
        </div>
      )}
      renderDropZone={(isActive) => (
        <div className={`custom-drop-zone ${isActive ? 'active' : ''}`}>
          {isActive ? '🎯 Drop it!' : '🛒 Cart'}
        </div>
      )}
    />
  );
};
```

## 📊 Analytics (Pro+ Only)

```tsx
const analyticsConfig = {
  analytics: {
    enabled: true,
    trackingId: 'your-analytics-id',
    events: {
      dragStart: true,
      dragEnd: true,
      itemAdded: true,
      itemRemoved: true,
      cartCleared: true,
    },
  },
};
```

## 🔧 Advanced Configuration

### Feature Limits by Tier

| Feature | Free | Pro | Enterprise |
|---------|------|-----|------------|
| Max Items | 5 | 100 | Unlimited |
| Max Carts | 1 | 5 | Unlimited |
| Custom Themes | ❌ | ✅ | ✅ |
| Advanced Animations | ❌ | ✅ | ✅ |
| Persistence | ❌ | ✅ | ✅ |
| Analytics | ❌ | ✅ | ✅ |
| Custom Render | ❌ | ✅ | ✅ |
| Watermark | ✅ | ❌ | ❌ |

### Upgrade Prompts

The library automatically shows upgrade prompts when users hit limits:

```tsx
// Customize upgrade prompts
const config = {
  onLicenseError: (error: string) => {
    console.log('License error:', error);
    // Show custom upgrade UI
  },
};
```

## 🐛 Troubleshooting

### License Issues

1. **Invalid License Key**
   - Verify your license key is correct
   - Check if it's expired
   - Ensure you're using the right tier

2. **Network Issues**
   - License validation requires internet connection
   - Check firewall/proxy settings
   - Validation is cached for 1 hour

3. **Development Mode**
   - Use test keys: `test_pro_key` or `test_enterprise_key`
   - Set `NODE_ENV=development`

### Common Issues

1. **Watermark Showing on Paid Tier**
   - Check license validation
   - Verify API key is correct
   - Clear license cache: `licenseValidator.clearCache()`

2. **Features Not Working**
   - Check tier limits with `useLicense().limits`
   - Verify license is valid with `useLicense().isValid`

## 🤝 Support

- **Free Tier**: Community support via GitHub Issues
- **Pro Tier**: Priority email support (24-48h response)
- **Enterprise Tier**: Dedicated support with SLA

## 📄 License

MIT License - see LICENSE file for details.

**Note**: While the code is MIT licensed, commercial usage beyond the free tier limits requires a valid license key from SHiMMeRbyte.

---

Built with ❤️ by the SHiMMeRbyte team

[Get your license key](https://shimmerbyte.com/drag-cart/pricing) • [Documentation](https://docs.shimmerbyte.com/drag-cart) • [Support](mailto:support@shimmerbyte.com)