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,125 @@
+# IPAL — Dokumentacja modułów
+
+**Stawiasz nowy projekt?** → [getting-started.md](./getting-started.md)
+
+IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który
+dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
+wizualne i podłączenia do Next.js.
+
+## Zasada
+
+- **Plugin** = logika, helpery, konfiguracja, globale.
+- **Klient (projekt)** = komponenty (wygląd), pliki-podłączenia Next.js
+  (jednolinijkowe re-eksporty), konfiguracja front.
+
+## Instalacja i wpięcie
+
+### Wymagane zależności
+
+Projekt klienta musi mieć (poza payloadem):
+
+```json
+"dependencies": {
+  "@payloadcms/plugin-seo": "3.84.1",
+  "@payloadcms/plugin-form-builder": "3.84.1",
+  "nodemailer": "^8.0.1",
+  "lucide-react": "^0.400.0",
+  "slugify": "^1.6.6",
+  "server-only": "^0.0.1"
+}
+```
+
+Wersje `@payloadcms/*` **muszą** być identyczne z wersją `payload`. Wymuś
+spójność przez `pnpm.overrides` (patrz niżej), inaczej Payload odrzuci wpięcie
+pluginów (pusty tab SEO, brak kolekcji Forms) albo crashuje.
+
+```json
+"pnpm": {
+  "overrides": {
+    "payload": "3.84.1",
+    "@payloadcms/ui": "3.84.1",
+    "@payloadcms/next": "3.84.1",
+    "@payloadcms/db-sqlite": "3.84.1",
+    "@payloadcms/richtext-lexical": "3.84.1",
+    "@payloadcms/plugin-seo": "3.84.1",
+    "@payloadcms/plugin-form-builder": "3.84.1"
+  }
+}
+```
+
+### Po wpięciu — wygeneruj importMap
+
+Plugin dostarcza komponenty admina (pola SEO). Po dodaniu uruchom:
+
+```bash
+pnpm payload generate:importmap
+```
+
+Bez tego pola SEO nie wyrenderują się (błąd `PayloadComponent not found in
+importMap`).
+
+```ts
+// payload.config.ts
+import { ipalKit } from 'ipal-kit'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    ipalKit({
+      i18n: {
+        defaultLocale: 'pl',
+        locales: [
+          { code: 'pl', label: 'Polski' },
+          { code: 'en', label: 'English' },
+        ],
+      },
+      access: { authCollection: 'users' },
+      pages: { slug: 'pages' },
+      seo: { collections: ['pages', 'posts'] },
+      forms: { redirectRelationships: ['pages'] },
+    }),
+  ],
+})
+```
+
+## Entry pointy pakietu
+
+| Import | Zawiera | Kontekst |
+|---|---|---|
+| `ipal-kit` | logika server-safe, plugin, helpery | server / config |
+| `ipal-kit/server` | runtime server-only (sendEmail, verifyTurnstile, submitForm) | Server Actions / route handlers |
+| `ipal-kit/client` | komponenty client (consent, Turnstile, Analytics) | `'use client'` |
+| `ipal-kit/rsc` | RenderBlocks (RSC) | server component |
+| `ipal-kit/next/middleware` | locale middleware | middleware.ts |
+
+## Moduły
+
+| Moduł | Opis | Dok |
+|---|---|---|
+| i18n | Lokalizacja, negocjacja locale, ścieżki URL | [i18n.md](./i18n.md) |
+| pages | System pages (homepage/privacy/cookies) → ścieżki | [pages.md](./pages.md) |
+| access | Role admin > editor > user, kontrola dostępu | [access.md](./access.md) |
+| payload-helpers | getSiteSettings / getSiteIntegrations | [payload-helpers.md](./payload-helpers.md) |
+| seo | Metadata, hreflang, auto-fill, plugin-seo | [seo.md](./seo.md) |
+| blocks | RenderBlocks — silnik renderowania bloków | [blocks.md](./blocks.md) |
+| consent | Banner cookies GDPR, Google Consent Mode | [consent.md](./consent.md) |
+| turnstile | Cloudflare Turnstile (widget + verify) | [turnstile.md](./turnstile.md) |
+| email | SMTP z panelu: adapter Payloada + sendEmail | [email.md](./email.md) |
+| forms | Form-builder + submitForm (Turnstile + zapis) | [forms.md](./forms.md) |
+| analytics | GA4 / GTM spięte z Consent Mode | [analytics.md](./analytics.md) |
+| slug | Auto-slug z tytułu, per locale | [slug.md](./slug.md) |
+| content | Blog/archiwa: kolekcje pod stroną-archiwum, listing, paginacja | [content.md](./content.md) |
+
+Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
+Referencja wdrożenia frontu: [frontend-setup.md](./frontend-setup.md)
+
+## Zasady dla wszystkich modułów
+
+1. **Helpery przyjmują `payload` jako argument** — plugin nigdy nie woła
+   `getPayload` sam.
+2. **Sekrety w panelu** — SMTP, Turnstile secret, R2 w SiteIntegrations
+   (admin-only). Odczyt server-side przez Local API.
+3. **Client/server split** — kod z sekretami ma `server-only`; komponenty
+   client w `ipal-kit/client`.
+4. **Generyki na typy klienta** — helpery przyjmują `<T>` (np. wygenerowany
+   `SiteSetting`), bo plugin nie zna typów projektu.