@openpolicy/react 0.0.19 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@openpolicy/react",
-	"version": "0.0.19",
+	"version": "0.0.20",
 	"type": "module",
 	"description": "React components and hooks for OpenPolicy",
 	"license": "GPL-3.0-only",
@@ -12,7 +12,8 @@
 	"files": [
 		"dist",
 		"styles.css",
-		"README.md"
+		"README.md",
+		"skills"
 	],
 	"exports": {
 		".": {
@@ -36,7 +37,8 @@
 		"@openpolicy/core": "workspace:*",
 		"@openpolicy/tooling": "workspace:*",
 		"@types/react": "^19.0.0",
-		"react": "^19.0.0"
+		"react": "^19.0.0",
+		"@tanstack/intent": "^0.0.29"
 	},
 	"publishConfig": {
 		"exports": {
@@ -46,5 +48,8 @@
 			},
 			"./styles.css": "./styles.css"
 		}
-	}
+	},
+	"keywords": [
+		"tanstack-intent"
+	]
 }

package/skills/cookie-banner/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: cookie-banner
+description: >
+  Cookie consent banner with useCookies hook, route state machine (cookie | preferences | closed), acceptAll, acceptNecessary, save, categories, toggle, ConsentGate conditional rendering, has expression DSL, localStorage persistence under op_consent key.
+type: framework
+library: openpolicy
+framework: react
+library_version: "0.0.19"
+requires:
+  - openpolicy/define-config
+  - openpolicy/render-policies
+sources:
+  - jamiedavenport/openpolicy:packages/react/src/context.tsx
+  - jamiedavenport/openpolicy:apps/www/registry/cookie-banner.tsx
+---
+
+This skill builds on openpolicy/define-config and openpolicy/render-policies. Read them first.
+
+## Route State Machine
+
+`useCookies()` exposes a `route` value that drives which UI to show:
+
+```
+"cookie"       — consent not yet given; show the banner
+"preferences"  — user clicked "Manage"; show the preferences panel
+"closed"       — consent resolved; render nothing
+```
+
+The provider sets `route` to `"cookie"` automatically when `status === "undecided"` (no prior consent in localStorage). Once the user acts (`acceptAll`, `acceptNecessary`, or `save`), the provider sets `route` to `"closed"`. `setRoute` lets you navigate between `"cookie"` and `"preferences"` manually.
+
+## Setup
+
+The following is a complete minimal implementation using plain divs and buttons — no UI library required.
+
+### 1. Config — include a `cookie` section
+
+```ts
+// openpolicy.ts
+import { defineConfig } from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: {
+    name: "Acme",
+    legalName: "Acme, Inc.",
+    address: "123 Main St, San Francisco, CA",
+    contact: "privacy@acme.com",
+  },
+  cookie: {
+    cookies: {
+      essential: true,
+      analytics: true,
+      marketing: false,
+    },
+  },
+});
+```
+
+### 2. Provider — wrap your app root
+
+```tsx
+// App.tsx
+import { OpenPolicy } from "@openpolicy/react";
+import config from "./openpolicy";
+import { CookieBanner } from "./CookieBanner";
+import { CookiePreferences } from "./CookiePreferences";
+
+export function App() {
+  return (
+    <OpenPolicy config={config}>
+      <CookieBanner />
+      <CookiePreferences />
+      {/* rest of app */}
+    </OpenPolicy>
+  );
+}
+```
+
+### 3. Banner — gate on `route === "cookie"`
+
+```tsx
+// CookieBanner.tsx
+import { useCookies } from "@openpolicy/react";
+
+export function CookieBanner() {
+  const { route, setRoute, acceptAll, acceptNecessary } = useCookies();
+
+  if (route !== "cookie") return null;
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        bottom: "1rem",
+        right: "1rem",
+        padding: "1.5rem",
+        background: "#fff",
+        border: "1px solid #e5e7eb",
+        borderRadius: "0.5rem",
+        maxWidth: "24rem",
+        zIndex: 50,
+      }}
+    >
+      <p style={{ marginBottom: "1rem" }}>
+        We use cookies to improve your experience and analyse site traffic.
+      </p>
+      <div style={{ display: "flex", gap: "0.5rem", justifyContent: "flex-end" }}>
+        <button onClick={() => setRoute("preferences")}>Manage Cookies</button>
+        <button onClick={acceptNecessary}>Necessary Only</button>
+        <button onClick={acceptAll}>Accept All</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### 4. Preferences panel — toggle categories, then save
+
+```tsx
+// CookiePreferences.tsx
+import { useCookies } from "@openpolicy/react";
+
+export function CookiePreferences() {
+  const { route, setRoute, categories, toggle, save, acceptNecessary } =
+    useCookies();
+
+  if (route !== "preferences") return null;
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "rgba(0,0,0,0.5)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        zIndex: 50,
+      }}
+    >
+      <div
+        style={{
+          background: "#fff",
+          padding: "2rem",
+          borderRadius: "0.5rem",
+          minWidth: "20rem",
+        }}
+      >
+        <h2>Cookie preferences</h2>
+        <p>Choose which cookies you allow.</p>
+
+        <ul style={{ listStyle: "none", padding: 0 }}>
+          {categories.map(({ key, label, enabled, locked }) => (
+            <li
+              key={key}
+              style={{
+                display: "flex",
+                justifyContent: "space-between",
+                padding: "0.5rem 0",
+              }}
+            >
+              <span>{label}</span>
+              <input
+                type="checkbox"
+                checked={enabled}
+                disabled={locked}
+                onChange={() => toggle(key)}
+              />
+            </li>
+          ))}
+        </ul>
+
+        <div style={{ display: "flex", gap: "0.5rem", justifyContent: "flex-end" }}>
+          <button onClick={acceptNecessary}>Reject All</button>
+          <button onClick={() => save()}>Save Preferences</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Core Patterns
+
+### 1. Route-gated rendering
+
+Always check `route` before rendering. Each component owns one route value and returns `null` for all others.
+
+```tsx
+// Banner owns "cookie"
+if (route !== "cookie") return null;
+
+// Preferences owns "preferences"
+if (route !== "preferences") return null;
+```
+
+Navigating between them:
+
+```tsx
+// Open preferences from banner
+<button onClick={() => setRoute("preferences")}>Manage Cookies</button>
+
+// Close preferences without saving (returns to "closed", not back to "cookie")
+<button onClick={() => setRoute("closed")}>Cancel</button>
+```
+
+### 2. Preferences panel with categories, toggle, and save
+
+`categories` is derived from your config's `cookie.cookies` keys. Each entry:
+
+```ts
+type CookieCategory = {
+  key: string;    // "essential" | "analytics" | "marketing" | ...
+  label: string;  // human-readable, e.g. "Analytics"
+  enabled: boolean;
+  locked: boolean; // true for "essential" — cannot be toggled
+};
+```
+
+`toggle(key)` updates local draft state without persisting. `save()` merges draft into localStorage and closes the banner. Until `save()` is called, the user's changes are not committed.
+
+```tsx
+{categories.map(({ key, label, enabled, locked }) => (
+  <label key={key}>
+    <input
+      type="checkbox"
+      checked={enabled}
+      disabled={locked}
+      onChange={() => toggle(key)}
+    />
+    {label}
+  </label>
+))}
+<button onClick={() => save()}>Save</button>
+```
+
+### 3. ConsentGate — conditional rendering by consent
+
+Wrap any content that should only appear when a category has consent:
+
+```tsx
+import { ConsentGate } from "@openpolicy/react";
+
+// Simple category string
+<ConsentGate requires="analytics">
+  <AnalyticsDashboard />
+</ConsentGate>
+
+// Compound expression
+<ConsentGate requires={{ and: ["analytics", "marketing"] }}>
+  <RetargetingPixel />
+</ConsentGate>
+
+<ConsentGate requires={{ or: ["analytics", "functional"] }}>
+  <EnhancedFeatures />
+</ConsentGate>
+```
+
+`has()` from `useCookies()` evaluates the same `HasExpression` DSL imperatively:
+
+```tsx
+const { has } = useCookies();
+
+// Load analytics script only when consent is given
+useEffect(() => {
+  if (has("analytics")) {
+    loadAnalytics();
+  }
+}, [has]);
+```
+
+`HasExpression` type: `string | { and: HasExpression[] } | { or: HasExpression[] } | { not: HasExpression }`
+
+### 4. shadcn registry shortcut
+
+For a pre-styled banner and preferences panel that matches your shadcn/ui theme:
+
+```sh
+shadcn add @openpolicy/cookie-banner
+```
+
+This installs `CookieBanner` and `CookiePreferences` components using shadcn Card, Dialog, Switch, and Button primitives. The logic is identical to the manual implementation above — only the styling differs.
+
+## Common Mistakes
+
+### Mistake 1 — Not gating banner render on `route === "cookie"` (HIGH)
+
+Without the route check the banner renders permanently, ignoring whether consent has already been given.
+
+```tsx
+// WRONG: renders always, no route check
+function CookieBanner() {
+  const { acceptAll, acceptNecessary } = useCookies();
+  return <div>...</div>;
+}
+
+// Correct
+function CookieBanner() {
+  const { route, acceptAll, acceptNecessary } = useCookies();
+  if (route !== "cookie") return null;
+  return <div>...</div>;
+}
+```
+
+### Mistake 2 — Building custom consent state with `useState` instead of `useCookies()` (HIGH)
+
+Manual `useState` consent flags miss localStorage persistence, cross-tab sync, and the `document.body` `data-consent-*` attributes that `useCookies()` maintains automatically.
+
+```tsx
+// WRONG: custom state, no persistence or sync
+const [accepted, setAccepted] = useState(false);
+// manually writing to localStorage, missing cross-tab broadcast
+
+// Correct: use the hook
+const { status, acceptAll, acceptNecessary, has } = useCookies();
+```
+
+The provider writes consent under key `"op_consent"` in localStorage and syncs via `useSyncExternalStore` — all tabs sharing the same origin update simultaneously.
+
+### Mistake 3 — Using `useCookies()` without `<OpenPolicy>` provider (HIGH)
+
+Without the provider, `useCookies()` reads from the default context: `consent: null`, `categories: []`, `route: "closed"`. The banner never appears and the preferences panel renders no toggles. There is no thrown error — it fails silently.
+
+```tsx
+// WRONG: no provider
+function App() {
+  return <CookieBanner />;
+}
+
+// Correct: provider at root, banner and preferences inside it
+function App() {
+  return (
+    <OpenPolicy config={config}>
+      <CookieBanner />
+      <CookiePreferences />
+    </OpenPolicy>
+  );
+}
+```

package/skills/render-policies/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: render-policies
+description: >
+  Render OpenPolicy privacy, terms of service, and cookie policy documents as
+  React components using @openpolicy/react. Components — PrivacyPolicy,
+  TermsOfService, CookiePolicy — read config from the OpenPolicyProvider
+  (alias OpenPolicy) context and accept optional config and components props
+  for per-page overrides and full rendering customization via PolicyComponents.
+type: framework
+library: openpolicy
+framework: react
+library_version: "0.0.19"
+requires:
+  - openpolicy/define-config
+sources:
+  - jamiedavenport/openpolicy:packages/react/src/context.tsx
+  - jamiedavenport/openpolicy:packages/react/src/render.tsx
+  - jamiedavenport/openpolicy:packages/react/src/types.ts
+---
+
+This skill builds on openpolicy/define-config. Read it first.
+
+## Setup
+
+Install the package:
+
+```sh
+bun add @openpolicy/react
+```
+
+Wrap your app with the provider, import styles, and render a policy page:
+
+```tsx
+// layout.tsx (or _app.tsx)
+import '@openpolicy/react/styles.css';
+import { OpenPolicy } from '@openpolicy/react';
+import config from './openpolicy';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <OpenPolicy config={config}>
+      {children}
+    </OpenPolicy>
+  );
+}
+```
+
+```tsx
+// app/privacy/page.tsx
+import { PrivacyPolicy } from '@openpolicy/react';
+
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+## Core Patterns
+
+### 1. Provider at app root
+
+`OpenPolicyProvider` (exported as `OpenPolicy`) must wrap the entire application. All policy components and hooks read from this context.
+
+```tsx
+import { OpenPolicy } from '@openpolicy/react';
+import config from './openpolicy';
+
+<OpenPolicy config={config}>
+  <App />
+</OpenPolicy>
+```
+
+`config` must be an `OpenPolicyConfig` (the nested shape produced by `defineConfig()`). The provider also injects default styles via a React `<style>` tag, so the CSS import is optional when using the provider — but import it explicitly for non-provider rendering paths.
+
+### 2. Rendering all three policy types
+
+Each component reads its slice of the config from context automatically:
+
+```tsx
+import { PrivacyPolicy, TermsOfService, CookiePolicy } from '@openpolicy/react';
+
+// Privacy policy page
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+
+// Terms of service page
+export default function TermsPage() {
+  return <TermsOfService />;
+}
+
+// Cookie policy page
+export default function CookiePolicyPage() {
+  return <CookiePolicy />;
+}
+```
+
+All three components accept the same optional props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `OpenPolicyConfig \| PrivacyPolicyConfig` (or equivalent) | Per-page config override; falls back to context |
+| `components` | `PolicyComponents` | Override default renderers for individual node types |
+| `style` | `CSSProperties` | Inline styles applied to the wrapper `<div>` |
+
+### 3. Component customization with PolicyComponents
+
+Override any node renderer by passing a `components` prop. The `PolicyComponents` interface:
+
+```ts
+type PolicyComponents = {
+  Section?: ComponentType<{ section: DocumentSection; children: ReactNode }>;
+  Heading?: ComponentType<{ node: HeadingNode }>;
+  Paragraph?: ComponentType<{ node: ParagraphNode; children: ReactNode }>;
+  List?: ComponentType<{ node: ListNode; children: ReactNode }>;
+  Text?: ComponentType<{ node: TextNode }>;
+  Bold?: ComponentType<{ node: BoldNode }>;
+  Italic?: ComponentType<{ node: ItalicNode }>;
+  Link?: ComponentType<{ node: LinkNode }>;
+}
+```
+
+All fields are optional — unspecified slots use the default renderers. Example: swap in a custom heading:
+
+```tsx
+import { PrivacyPolicy } from '@openpolicy/react';
+import type { HeadingNode } from '@openpolicy/core';
+
+function MyHeading({ node }: { node: HeadingNode }) {
+  return <h2 className="text-2xl font-bold text-slate-900">{node.text}</h2>;
+}
+
+export default function PrivacyPage() {
+  return <PrivacyPolicy components={{ Heading: MyHeading }} />;
+}
+```
+
+### 4. Theming with CSS custom properties
+
+The `.op-policy` wrapper exposes CSS custom properties. Override them globally or scoped:
+
+```css
+.op-policy {
+  --op-heading-color: #0f172a;
+  --op-body-color: #475569;
+  --op-link-color: #6366f1;
+  --op-link-color-hover: #4f46e5;
+  --op-font-family: 'Inter', sans-serif;
+  --op-font-size-body: 0.9375rem;
+  --op-font-size-heading: 1.125rem;
+  --op-font-weight-heading: 600;
+  --op-line-height: 1.75;
+  --op-section-gap: 2.5rem;
+  --op-border-color: #e2e8f0;
+  --op-border-radius: 0.5rem;
+}
+```
+
+### 5. shadcn/ui registry install
+
+Pre-styled variants are available via the shadcn registry. Install individual components:
+
+```sh
+shadcn add @openpolicy/privacy-policy
+shadcn add @openpolicy/terms-of-service
+shadcn add @openpolicy/cookie-policy
+```
+
+This copies styled component files into your project that you can edit freely. They use the same `PolicyComponents` customization interface under the hood.
+
+## Common Mistakes
+
+### CRITICAL — Using `openPolicy()` from `@openpolicy/vite` to generate static files
+
+The `openPolicy()` Vite plugin emits `.md` / `.html` / `.pdf` files at build time. It is a separate, legacy path. Agents trained on older docs may reach for it when asked to "add a privacy policy page."
+
+```ts
+// vite.config.ts — WRONG
+import { openPolicy } from '@openpolicy/vite';
+plugins: [openPolicy({ formats: ['html'], outDir: 'public' })]
+```
+
+The correct approach is React runtime rendering — render `<PrivacyPolicy />` as a page component. The static files produced by `openPolicy()` are never read by the React components.
+
+```tsx
+// correct: render as a React page
+import { PrivacyPolicy } from '@openpolicy/react';
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+### HIGH — Rendering policy components outside `<OpenPolicy>` provider
+
+`PrivacyPolicy`, `TermsOfService`, and `CookiePolicy` call `useContext(OpenPolicyContext)` and return `null` when no config is found. Without the provider, nothing renders and no error is thrown — the bug is invisible in development.
+
+```tsx
+// privacy-page.tsx — WRONG: no provider anywhere in the tree
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+Wrap at the application root, not inside individual pages:
+
+```tsx
+// layout.tsx — correct
+import config from './openpolicy';
+export default function RootLayout({ children }) {
+  return (
+    <OpenPolicy config={config}>
+      {children}
+    </OpenPolicy>
+  );
+}
+
+// privacy-page.tsx — correct: provider is already in the tree
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+### MEDIUM — Not importing `@openpolicy/react/styles.css`
+
+Without the CSS import, policy components render as unstyled HTML. The provider injects inline styles via a React `<style>` tag, but this may not work in all SSR or bundler setups.
+
+```tsx
+// WRONG: no styles imported
+import { PrivacyPolicy } from '@openpolicy/react';
+```
+
+```tsx
+// correct
+import '@openpolicy/react/styles.css';
+import { PrivacyPolicy } from '@openpolicy/react';
+```
+
+The default styles scope all rules to `.op-policy` so they do not leak to the rest of the page.