@afex-dapps/cookie/README.md

Cookie Consent library for React

# @afex-dapps/cookie

A modern, flexible cookie consent management library for React applications. This library simplifies cookie consent handling, ensuring GDPR compliance while providing a customizable and user-friendly experience.

---

## Features

- 🎨 **Customizable UI and Themes**: Easily style the cookie banner using CSS variables or the `styles` prop.
- 🌐 **Internationalization (i18n) Support**: Define translations for multiple languages and auto-detect user preferences.
- 🔒 **GDPR-Compliant Cookie Management**: Manage cookies with opt-in/opt-out modes and auto-clear functionality.
- ⚡ **Lightweight and Fast**: Minimal performance overhead with efficient design.
- 🔄 **Auto-Clearing Cookies**: Automatically clear cookies based on user preferences.
- 🤖 **Bot Detection**: Prevent bots and crawlers from interacting with the cookie banner.
- 📱 **Responsive Design**: Fully responsive and mobile-friendly.

---

## Installation

Install the library and its peer dependency using your preferred package manager:

```bash
npm install @afex-dapps/cookie vanilla-cookieconsent
# or
yarn add @afex-dapps/cookie vanilla-cookieconsent
# or
pnpm add @afex-dapps/cookie vanilla-cookieconsent
```

---

## Quick Start

### 1. Import the Required CSS

```tsx
import "vanilla-cookieconsent/dist/cookieconsent.css";
```

### 2. Basic Usage Example

```tsx
import { useCookieBanner, createCookieConfiguration } from "@afex-dapps/cookie";
import { Fragment } from "react";

import "vanilla-cookieconsent/dist/cookieconsent.css";

const configuration = createCookieConfiguration({
  categories: {
    necessary: { enabled: true, readOnly: true },
    analytics: { enabled: true },
  },
  language: {
    default: "en",
    translations: {
      en: {
        consentModal: {
          title: "Cookie preferences",
          description: "We use cookies to enhance your experience.",
          acceptAllBtn: "Accept all",
          acceptNecessaryBtn: "Accept necessary only",
        },
      },
    },
  },
});

export function App() {
  const { userId, updateUserId } = useCookieBanner({ configuration });
  return <Fragment>{/* Your app content */}</Fragment>;
}
```

---

## Customization

### Theming & Styles

#### Via `styles` Prop

```tsx
import { createCookieStyles } from "@afex-dapps/cookie";

const styles = createCookieStyles({
  ".cc--darkmode": {
    "--cc-bg": "#000",
    "--cc-color": "#fff",
  },
});

useCookieBanner({ styles, activeTheme: "dark" });
```

#### Via CSS Variables

```css
#cc-main .cm__btn[data-role="all"] {
  --cc-btn-primary-bg: #093159;
}

#cc-main .cm__btn[data-role="necessary"] {
  --cc-btn-primary-color: #eaeff2;
  --cc-btn-primary-bg: #1c75e1;
}

#cc-main .cm__btn--secondary {
  --cc-btn-secondary-bg: transparent;

  &:hover {
    --cc-btn-secondary-bg: #1c75e1;
  }
}
```

---

## Advanced Usage

### Google Consent Mode

Integrate with Google Consent Mode for advanced analytics. See the [Google Consent Mode Guide](https://cookieconsent.orestbida.com/advanced/google-consent-mode.html).

### Working with User Preferences

```tsx
import { useCookieBanner } from "@afex-dapps/cookie";
import * as CookieConsent from "vanilla-cookieconsent";

function CookieManager() {
  const { acceptCategory, acceptService, getUserPreferences, show, hide } =
    CookieConsent;
  const { updateUserId } = useCookieBanner();
  const preferences = getUserPreferences();

  return (
    <div>
      <h1>User Preferences</h1>
      <pre>{JSON.stringify(preferences, null, 2)}</pre>
      <button onClick={() => show()}>Show Cookie Banner</button>
      <button onClick={hide}>Hide Cookie Banner</button>
      <button onClick={() => acceptCategory("analytics")}>
        Accept Analytics Cookies
      </button>
      <button onClick={() => acceptService("ga")}>
        Accept Google Analytics Cookies
      </button>
      <button onClick={() => updateUserId("newUserId")}>Update User ID</button>
    </div>
  );
}
```

### Advanced Configuration Example

```tsx
const configuration = createCookieConfiguration({
  autoClearCookies: true,
  autoShow: true,
  manageScriptTags: true,
  hideFromBots: true,
  disablePageInteraction: false,
  cookie: {
    name: "cc_gdpr",
    path: "/",
    expiresAfterDays: 182,
    sameSite: "Lax",
    useLocalStorage: false,
  },
  categories: {
    necessary: { enabled: true, readOnly: true },
    analytics: {
      enabled: true,
      autoClear: { cookies: [{ name: /^(_ga|_gid|mp_)/ }] },
      services: {
        ga: {
          label: "Google Analytics",
          cookies: [{ name: /^(_ga|_gid)/ }],
        },
      },
    },
  },
});

useCookieBanner({ configuration });
```

---

## Exports

### Functions

- **`useCookieBanner`**: A React hook to manage the cookie banner lifecycle and user interactions.
- **`createCookieConfiguration`**: Utility to create a cookie consent configuration by merging defaults with custom options.
- **`createCookieStyles`**: Utility to define custom styles for the cookie banner.
- **`css`**: Helper function to generate CSS variable strings for cookie styles.

### Types

- **`CookieBannerProps`**: Props for the `useCookieBanner` hook, including `delay`, `configuration`, and `firebase` options.
- **`CookieVariable`**: List of CSS variables available for styling the cookie banner.
- **`CookieConsentConfiguration`**: Configuration options for the cookie consent modal, including categories, language, and callbacks.
- **`FirebaseConfig`**: Configuration for integrating Firebase to store cookie consent data.

### Constants

- **`cookieConsentAttributes`**: An object containing data attributes to control the cookie consent manager from HTML elements.
- **`cookieConsentEvents`**: An object containing event names dispatched by the cookie consent manager.

---

## API Reference

### `useCookieBanner` Hook

| Return Value             | Type     | Description                              |
| ------------------------ | -------- | ---------------------------------------- |
| `userId`                 | `string` | Unique identifier for the current user   |
| `updateUserId`           | Function | Update the user's identifier             |
| `retrieveUserCookieData` | Function | Retrieve stored cookie data for the user |
| `updateUserCookieData`   | Function | Update the stored cookie data for user   |

### `createCookieConfiguration`

Merges the default configuration with custom options to create a complete cookie consent configuration.

### `createCookieStyles`

Defines custom styles for the cookie banner using CSS properties and nested selectors.

### `css`

Generates CSS variable strings for cookie styles, e.g., `var(--cc-primary-color)`.

### External Library

For more in-depth information about the underlying cookie consent functionality, refer to the [vanilla-cookieconsent documentation](https://cookieconsent.orestbida.com/).

---

## License

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