init commit for iPAL-kit plugin

2026-07-18 20:30:23 +02:00
parent 10638127a9
commit 5733a9c8bf
119 changed files with 6892 additions and 411 deletions
@@ -0,0 +1,134 @@
+# consent
+
+Banner zgody na cookies (GDPR): 4 kategorie (necessary / functional /
+analytics / marketing), zapis w cookie z wersjonowaniem, Google Consent Mode,
+treść z globala CookieSettings. Domyślny wygląd w czystym Tailwind,
+nadpisywalny.
+
+## Zależność
+
+Banner używa ikony z `lucide-react`:
+
+```json
+"dependencies": { "lucide-react": "^0.400.0" }
+```
+
+## Config
+
+Brak opcji — global **CookieSettings** jest zawsze budowany. Edytor zarządza
+treścią bannera (message, przyciski, kategorie, settingsTitle) w panelu,
+localized. Link do polityki prywatności bierze się z system pages
+(`privacyPolicy`), nie z osobnego pola.
+
+## Front — Provider + banner
+
+Provider owija aplikację, banner i button renderują się same. Import z
+`ipal-kit/client`:
+
+```tsx
+// app/(frontend)/[locale]/layout.tsx
+import { ConsentProvider, CookieBanner, CookieButton } from 'ipal-kit/client'
+import { getConsentTexts } from 'ipal-kit'
+
+export default async function Layout({ children, params }) {
+  const { locale } = await params
+  const payload = await getPayload({ config })
+
+  // teksty z CookieSettings + link do polityki z system pages
+  const settings = await payload.findGlobal({ slug: 'site-settings', locale: 'all', depth: 1 })
+  const texts = await getConsentTexts({
+    payload, config: i18nConfig, locale,
+    privacyPolicy: { label: 'Polityka prywatności', page: settings.privacyPolicy },
+  })
+
+  return (
+    <ConsentProvider texts={texts}>
+      {children}
+      <CookieBanner />
+      <CookieButton />
+    </ConsentProvider>
+  )
+}
+```
+
+## Nadpisywanie wyglądu (Poziom 2)
+
+Domyślne klasy Tailwind można nadpisać przez `classNames`:
+
+```tsx
+<CookieBanner classNames={{
+  root: 'fixed inset-x-0 bottom-0 ...',   // Twój layout
+  primaryButton: 'btn btn-primary',        // np. DaisyUI
+  secondaryButton: 'btn btn-ghost',
+}} />
+```
+
+## Gating skryptów wg zgody
+
+```ts
+import { updateConsent, setDefaultConsent } from 'ipal-kit'
+// wysyła sygnały do Google Consent Mode (gtag) na podstawie stanu zgody
+```
+
+Logika (kategorie, storage, parsowanie) też jest dostępna server-safe z
+`ipal-kit`:
+
+```ts
+import { parseConsent, CONSENT_COOKIE, CONSENT_CATEGORIES } from 'ipal-kit'
+// np. gating skryptów server-side na podstawie cookie zgody
+```
+
+## Wygląd — nadpisywanie stylów
+
+Banner i przycisk mają domyślny, neutralny wygląd (light + dark) i działają bez
+żadnej konfiguracji. Kolory i zaokrąglenia idą przez CSS custom properties z
+fallbackami — żeby przestylować pod klienta, zadeklaruj zmienne w swoim CSS.
+Bez importów, bez propsów, bez walki ze specificity:
+
+```css
+/* global.css — wszystko opcjonalne, nadpisz tylko to, co chcesz */
+:root {
+  --ipal-primary: #16a34a;
+  --ipal-primary-hover: #15803d;
+  --ipal-radius: 1rem;
+}
+```
+
+Dostępne tokeny (każdy ma odpowiednik `-dark` używany pod `dark:`):
+
+| Token | Domyślnie | Co koloruje |
+|---|---|---|
+| `--ipal-surface` | `#fff` | tło bannera i przycisku |
+| `--ipal-border` | `#e5e5e5` | obramowania |
+| `--ipal-text` | `#404040` | tekst treści |
+| `--ipal-text-strong` | `#171717` | nagłówki, nazwy kategorii |
+| `--ipal-text-muted` | `#737373` | opisy kategorii |
+| `--ipal-primary` | `#2563eb` | przycisk główny, ikona, link, checkbox |
+| `--ipal-primary-hover` | `#1d4ed8` | hover przycisku głównego |
+| `--ipal-primary-text` | `#fff` | tekst na przycisku głównym |
+| `--ipal-hover` | `#f5f5f5` | hover przycisków drugorzędnych |
+| `--ipal-radius` | `0.375rem` | zaokrąglenie przycisków |
+
+Wymaga `@source` skanującego pakiet (patrz frontend-setup.md) — inaczej Tailwind
+nie wygeneruje tych klas.
+
+### Gdy tokeny nie wystarczą
+
+Układ (odstępy, pozycja, breakpointy) nie jest tokenizowany — to nie jest coś,
+co zmienia się per brand, a wystawienie go oznaczałoby wymyślanie CSS od nowa,
+zmienna po zmiennej. Na większe zmiany są `classNames`:
+
+```tsx
+<CookieBanner classNames={{
+  root: 'fixed inset-0 z-50 grid place-items-center bg-black/50',  // modal zamiast paska
+  primaryButton: 'btn btn-primary',                                 // np. DaisyUI
+  secondaryButton: 'btn btn-ghost',
+}} />
+<CookieButton className="fixed bottom-6 right-6 ..." />
+```
+
+Sloty: `root`, `primaryButton`, `secondaryButton`. Podany className zastępuje
+domyślny (nie dokleja się).
+
+Elementy mają też `data-ipal="banner"` i `data-ipal="cookie-button"` — stabilne
+uchwyty do CSS albo testów e2e.