acronweb-cookies/README.md

A modern, GDPR-compliant cookie consent plugin for React and Next.js applications

# AcronWeb Cookies

A modern, GDPR-compliant cookie consent plugin for React and Next.js applications with Firebase integration.

## Features

- 🍪 **GDPR Compliant** - Full compliance with cookie consent regulations
- 🌍 **Multi-language Support** - Built-in Greek and English support
- 🔥 **Firebase Integration** - Store user consent data in Firestore
- 📱 **Responsive Design** - Beautiful UI that works on all devices
- ⚡ **Lightweight** - Minimal bundle size with no unnecessary dependencies
- 🎨 **Customizable** - Easy to customize colors, content, and positioning
- 🔒 **Secure** - Proper cookie handling with security best practices
- 📊 **Analytics Ready** - Track consent patterns and user behavior

## Installation

### For React.js projects:

```bash
npm install acronweb-cookies
# or
yarn add acronweb-cookies
```

### For Next.js projects:

```bash
npm install acronweb-cookies
# or
yarn add acronweb-cookies
```

### Required Peer Dependencies

This plugin requires the following peer dependencies. Install them in your project:

```bash
# For Firebase integration
npm install firebase

# For animations and icons
npm install framer-motion lucide-react

# If not already installed
npm install react react-dom
```

**Note:** If you don't need Firebase integration, you can skip installing `firebase`. The plugin will work without it, but won't store consent data in Firestore.

## Quick Start

### Basic Usage

```tsx
import { CookieConsent } from 'acronweb-cookies';

function App() {
  return (
    <div>
      <h1>My Website</h1>
      <CookieConsent />
    </div>
  );
}
```

### With Firebase Integration

```tsx
import { CookieConsent } from 'acronweb-cookies';

const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "your-app-id"
};

function App() {
  return (
    <div>
      <h1>My Website</h1>
      <CookieConsent 
        firebaseConfig={firebaseConfig}
        language="en"
        onAccept={(consent) => console.log('User accepted:', consent)}
        onDecline={() => console.log('User declined')}
      />
    </div>
  );
}
```

## Configuration Options

### CookieConsent Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `language` | `'el' \| 'en'` | `'el'` | Language for the consent dialog |
| `firebaseConfig` | `FirebaseConfig` | `undefined` | Firebase configuration object |
| `onAccept` | `(consent: boolean) => void` | `undefined` | Callback when user accepts |
| `onDecline` | `() => void` | `undefined` | Callback when user declines |
| `customContent` | `object` | `undefined` | Custom text content |
| `privacyUrl` | `string` | `'/privacy'` | URL to privacy policy |
| `showPoweredBy` | `boolean` | `true` | Show "Powered by AcronWeb" |
| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Theme mode |
| `position` | `string` | `'bottom-left'` | Position of the dialog |
| `autoHide` | `boolean` | `false` | Auto-hide after delay |
| `autoHideDelay` | `number` | `5000` | Auto-hide delay in ms |

### Custom Content Example

```tsx
<CookieConsent
  customContent={{
    el: {
      title: 'Τα Cookies μας',
      description: 'Χρησιμοποιούμε cookies για καλύτερη εμπειρία.',
      accept: 'Αποδοχή',
      decline: 'Απόρριψη',
      learnMore: 'Περισσότερα'
    },
    en: {
      title: 'Our Cookies',
      description: 'We use cookies for better experience.',
      accept: 'Accept',
      decline: 'Decline',
      learnMore: 'Learn More'
    }
  }}
/>
```

## Firebase Setup

### 1. Create Firebase Project

1. Go to [Firebase Console](https://console.firebase.google.com/)
2. Create a new project or select existing one
3. Enable Firestore Database

### 2. Configure Firestore Rules

```javascript
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Allow read/write for users collection
    match /users/{userId} {
      allow read, write: if true;
    }
    
    // Allow read/write for consents collection
    match /consents/{consentId} {
      allow read, write: if true;
    }
  }
}
```

### 3. Get Firebase Config

1. Go to Project Settings
2. Scroll down to "Your apps"
3. Click on the web app or create one
4. Copy the config object

### 4. Data Structure

The plugin creates two collections in Firestore:

#### `users` Collection
```javascript
{
  id: "user_abc123_1234567890",
  consent: true,
  language: "en",
  userAgent: "Mozilla/5.0...",
  ipAddress: "192.168.1.1",
  country: "Greece",
  city: "Athens",
  createdAt: Timestamp,
  updatedAt: Timestamp
}
```

#### `consents` Collection
```javascript
{
  id: "user_abc123_1234567890_1234567890",
  consent: true,
  timestamp: Timestamp,
  language: "en",
  userAgent: "Mozilla/5.0...",
  ipAddress: "192.168.1.1",
  country: "Greece",
  city: "Athens",
  createdAt: Timestamp,
  updatedAt: Timestamp
}
```

## Utility Functions

### Programmatically Open Consent Dialog

```tsx
import { openCookieConsent } from 'acronweb-cookies';

function MyComponent() {
  const handleOpenConsent = () => {
    openCookieConsent();
  };

  return (
    <button onClick={handleOpenConsent}>
      Open Cookie Settings
    </button>
  );
}
```

### Get Current Consent Status

```tsx
import { getCookieConsent } from 'acronweb-cookies';

const consent = getCookieConsent(); // true, false, or null
```

### Set Consent Programmatically

```tsx
import { setCookieConsent } from 'acronweb-cookies';

setCookieConsent(true, {
  necessary: true,
  analytics: true,
  marketing: false,
  preferences: true
});
```

### Clear All Consent Data

```tsx
import { clearCookieConsent } from 'acronweb-cookies';

clearCookieConsent();
```

## Styling

The component uses Tailwind CSS classes. If you're not using Tailwind, you can override styles:

```css
/* Custom styles */
.acronweb-cookie-consent {
  /* Your custom styles */
}
```

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

For support, please open an issue on GitHub or contact us at support@acronweb.com.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

**Made with ❤️ by AcronWeb**