@nukipa/post-renderer-react 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @nukipa/post-renderer-react
+
+React adapter for `@nukipa/post-content`. Renders a CMS post body, then
+hydrates interactive islands (lead-gen forms, contact forms, CTA click
+tracking, basic carousels).
+
+```tsx
+import { PostBody } from '@nukipa/post-renderer-react';
+import { createNukipaClient } from '@nukipa/site-sdk';
+
+const client = createNukipaClient({ /* ... */ });
+
+<PostBody
+  body={post.body}
+  components={post.components}
+  sources={post.sources}
+  postId={post.id}
+  lang={post.language}
+  client={client}
+/>
+```
+
+## What it hydrates
+
+| Island             | Behaviour                                                            |
+| ------------------ | -------------------------------------------------------------------- |
+| `cta`              | Click-track via `client.recordCtaClick`. Anchor stays SSR-rendered.  |
+| `form`             | Mounts `<LeadForm>` against the form slug.                           |
+| `contact-form`     | Mounts `<ContactForm>` reading the schema from the DOM.              |
+| `carousel`         | Prev/next handlers, no autoplay.                                     |
+| `chart`, `widget`  | Not hydrated — placeholder HTML only. Wire per-tenant if needed.     |
+
+The CTA anchor is hybrid by design: search engines and no-JS clients
+follow the real `href`; the click-tracker is purely additive on hydration.
+
+## Pass `client`
+
+If `client` is omitted, interactive islands silently no-op — the static
+HTML still renders correctly. Pass `client` when you want forms to submit
+and CTA pings to fire.
+
+## Styling
+
+All static blocks use `bp-*` classes from `@nukipa/post-content`. Forms
+use BEM-ish `lead-form__*` / `contact-form__*` classes. Lift the relevant
+CSS from `apps/public/app/components/BlogArticle.vue` (scoped style block)
+into your tenant site.

package/dist/ContactForm.d.ts

@@ -0,0 +1,17 @@
+export interface ContactFormProps {
+    /**
+     * Same-origin endpoint that relays to
+     * `POST /public/v1/posts/:postId/contact-form-submissions`. The host's
+     * route handler is responsible for resolving the postId from the URL.
+     * Defaults to `/api/contact-form-submissions/:postId` (caller substitutes
+     * the postId before passing).
+     */
+    endpoint: string;
+    componentId: string;
+    title?: string | null;
+    description?: string | null;
+    submitLabel?: string | null;
+    successMessage?: string | null;
+    fields: Array<Record<string, unknown>>;
+}
+export declare function ContactForm({ endpoint, componentId, title, description, submitLabel, successMessage, fields }: ContactFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/ContactForm.js

@@ -0,0 +1,49 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+export function ContactForm({ endpoint, componentId, title, description, submitLabel, successMessage, fields }) {
+    const [values, setValues] = useState({});
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [success, setSuccess] = useState(null);
+    if (success)
+        return _jsx("div", { className: "contact-form contact-form--done", children: _jsx("p", { children: success }) });
+    async function onSubmit(e) {
+        e.preventDefault();
+        if (busy)
+            return;
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ component_id: componentId, values })
+            });
+            if (!res.ok) {
+                const data = await res.json().catch(() => ({}));
+                throw new Error(data?.error?.message || 'Submission failed');
+            }
+            setSuccess(successMessage || 'Thanks — we got your message.');
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Submission failed');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return (_jsxs("form", { className: "contact-form", onSubmit: onSubmit, noValidate: true, children: [title && _jsx("h3", { className: "contact-form__title", children: title }), description && _jsx("p", { className: "contact-form__desc", children: description }), fields.map((raw) => {
+                const f = raw;
+                const id = `contact-${componentId}-${f.key}`;
+                const onChange = (e) => {
+                    const v = e.target.type === 'checkbox'
+                        ? e.target.checked
+                        : e.target.value;
+                    setValues((s) => ({ ...s, [f.key]: v }));
+                };
+                return (_jsxs("div", { className: "contact-form__field", children: [f.label && _jsx("label", { htmlFor: id, children: f.label }), f.type === 'textarea'
+                            ? _jsx("textarea", { id: id, name: f.key, required: f.required, value: String(values[f.key] ?? ''), onChange: onChange })
+                            : _jsx("input", { id: id, name: f.key, type: f.type === 'email' ? 'email' : f.type === 'phone' ? 'tel' : f.type === 'number' ? 'number' : 'text', required: f.required, value: String(values[f.key] ?? ''), onChange: onChange })] }, f.key));
+            }), error && _jsx("p", { className: "contact-form__error", role: "alert", children: error }), _jsx("button", { type: "submit", disabled: busy, className: "contact-form__submit", children: busy ? '…' : (submitLabel || 'Send') })] }));
+}

package/dist/LeadForm.d.ts

@@ -0,0 +1,16 @@
+export interface LeadFormProps {
+    /** Form slug — must match a `cms.forms` row for the resolved tenant. */
+    slug: string;
+    /**
+     * Same-origin endpoint the host owns. Defaults to `/api/forms`. The
+     * handler:
+     *   - GET  `${endpoint}/:slug`   → relays to /public/v1/forms/:slug
+     *   - POST `${endpoint}`         → relays to /public/v1/forms/:slug/submit
+     *     with body `{ slug, ...values }`.
+     */
+    endpoint?: string;
+    title?: string | null;
+    description?: string | null;
+    submitLabel?: string | null;
+}
+export declare function LeadForm({ slug, endpoint, title, description, submitLabel }: LeadFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/LeadForm.js

@@ -0,0 +1,89 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+export function LeadForm({ slug, endpoint = '/api/forms', title, description, submitLabel }) {
+    const [form, setForm] = useState(null);
+    const [values, setValues] = useState({});
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [success, setSuccess] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        fetch(`${endpoint}/${encodeURIComponent(slug)}`)
+            .then((r) => (r.ok ? r.json() : null))
+            .then((j) => {
+            if (cancelled || !j)
+                return;
+            const f = (j.data ?? j);
+            setForm(f);
+            // Seed values so checkbox/text aren't undefined.
+            const seed = {};
+            for (const field of f.fields || []) {
+                seed[field.key] = field.type === 'checkbox' ? false : '';
+            }
+            setValues(seed);
+        })
+            .catch(() => { });
+        return () => { cancelled = true; };
+    }, [slug, endpoint]);
+    if (!form)
+        return _jsx("div", { className: "lead-form lead-form--loading" });
+    if (success)
+        return _jsx("div", { className: "lead-form lead-form--done", children: _jsx("p", { children: success }) });
+    async function onSubmit(e) {
+        e.preventDefault();
+        if (busy)
+            return;
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ slug, ...values })
+            });
+            const data = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new Error(data?.error?.message || 'Submission failed');
+            }
+            const onSubmitCfg = form?.on_submit;
+            if (data?.redirect_url) {
+                window.location.href = data.redirect_url;
+                return;
+            }
+            if (onSubmitCfg?.redirect_url) {
+                window.location.href = onSubmitCfg.redirect_url;
+                return;
+            }
+            setSuccess(data?.success_message || onSubmitCfg?.success_message || 'Thanks — we got your message.');
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Submission failed');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return (_jsxs("form", { className: "lead-form", onSubmit: onSubmit, noValidate: true, children: [(title || form.name) && _jsx("h3", { className: "lead-form-title", children: title || form.name }), description && _jsx("p", { className: "lead-form-description", children: description }), form.fields.map((field) => {
+                const id = `lead-${slug}-${field.key}`;
+                const onChange = (e) => {
+                    const v = e.target.type === 'checkbox'
+                        ? e.target.checked
+                        : e.target.value;
+                    setValues((s) => ({ ...s, [field.key]: v }));
+                };
+                return (_jsxs("label", { className: `lead-form-field${field.type === 'checkbox' ? ' lead-form-field--checkbox' : ''}`, children: [_jsxs("span", { className: "lead-form-label", children: [field.label, field.required && _jsx("span", { className: "lead-form-required", children: "*" })] }), field.type === 'textarea' ? (_jsx("textarea", { id: id, name: field.key, required: field.required, rows: 4, className: "lead-form-textarea", value: String(values[field.key] ?? ''), onChange: onChange })) : field.type === 'select' ? (_jsxs("select", { id: id, name: field.key, required: field.required, className: "lead-form-input", value: String(values[field.key] ?? ''), onChange: onChange, children: [_jsx("option", { value: "", disabled: true, children: "\u2014" }), (field.options || []).map((opt) => {
+                                    const v = typeof opt === 'string' ? opt : opt.value;
+                                    const l = typeof opt === 'string' ? opt : opt.label;
+                                    return _jsx("option", { value: v, children: l }, v);
+                                })] })) : field.type === 'checkbox' ? (_jsx("input", { id: id, name: field.key, type: "checkbox", className: "lead-form-checkbox", checked: Boolean(values[field.key]), onChange: onChange })) : (_jsx("input", { id: id, name: field.key, type: htmlInputType(field.type), required: field.required, className: "lead-form-input", value: String(values[field.key] ?? ''), onChange: onChange }))] }, field.key));
+            }), error && _jsx("p", { className: "lead-form-error", role: "alert", children: error }), _jsx("button", { type: "submit", className: "lead-form-submit", disabled: busy, children: busy ? '…' : (submitLabel || 'Send') })] }));
+}
+function htmlInputType(t) {
+    switch (t) {
+        case 'email': return 'email';
+        case 'phone': return 'tel';
+        case 'number': return 'number';
+        default: return 'text';
+    }
+}

package/dist/PostBody.d.ts

@@ -0,0 +1,28 @@
+import { type PostComponent, type PostSource } from '@nukipa/post-content';
+import { type IslandEndpoints } from './islands';
+export interface PostBodyProps {
+    body: string;
+    components?: PostComponent[];
+    sources?: PostSource[];
+    postId?: string | null;
+    lang?: string;
+    /**
+     * Same-origin relay endpoints the host app exposes. Defaults match the
+     * Next.js template's route handlers under `app/api/*`. The host's
+     * server-side handler forwards to the gateway with `X-Forwarded-Host`
+     * attached — the browser can't set that header itself.
+     */
+    endpoints?: Partial<IslandEndpoints>;
+    className?: string;
+}
+/**
+ * Render a CMS post body. Server-renders the HTML directly via
+ * `dangerouslySetInnerHTML`; client-hydrates interactive islands
+ * (lead-gen forms, contact forms, CTA click tracking, basic carousels)
+ * after mount.
+ *
+ * Forms and CTA clicks POST to same-origin relay routes the host app
+ * owns — see `endpoints` prop. The defaults match the relays in
+ * `templates/site-nextjs/app/api/`.
+ */
+export declare function PostBody({ body, components, sources, postId, lang, endpoints, className }: PostBodyProps): import("react/jsx-runtime").JSX.Element;

package/dist/PostBody.js

@@ -0,0 +1,37 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { renderPostBody } from '@nukipa/post-content';
+import { hydrateIslands } from './islands';
+const DEFAULT_ENDPOINTS = {
+    forms: '/api/forms',
+    ctaClicks: '/api/cta-clicks',
+    contactForms: '/api/contact-form-submissions'
+};
+/**
+ * Render a CMS post body. Server-renders the HTML directly via
+ * `dangerouslySetInnerHTML`; client-hydrates interactive islands
+ * (lead-gen forms, contact forms, CTA click tracking, basic carousels)
+ * after mount.
+ *
+ * Forms and CTA clicks POST to same-origin relay routes the host app
+ * owns — see `endpoints` prop. The defaults match the relays in
+ * `templates/site-nextjs/app/api/`.
+ */
+export function PostBody({ body, components = [], sources = [], postId = null, lang, endpoints, className }) {
+    const ref = useRef(null);
+    const { html, mounts } = renderPostBody({
+        body,
+        components,
+        sources,
+        options: { lang, postId }
+    });
+    const merged = { ...DEFAULT_ENDPOINTS, ...(endpoints || {}) };
+    useEffect(() => {
+        if (!ref.current)
+            return undefined;
+        return hydrateIslands(ref.current, mounts, { endpoints: merged, postId });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [body, postId, merged.forms, merged.ctaClicks, merged.contactForms]);
+    return (_jsx("div", { ref: ref, className: className ?? 'prose-body', dangerouslySetInnerHTML: { __html: html } }));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { PostBody } from './PostBody';
+export { LeadForm } from './LeadForm';
+export { ContactForm } from './ContactForm';
+export { renderSourcesList } from '@nukipa/post-content';
+export type { PostBodyProps } from './PostBody';
+export type { IslandEndpoints } from './islands';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PostBody } from './PostBody';
+export { LeadForm } from './LeadForm';
+export { ContactForm } from './ContactForm';
+export { renderSourcesList } from '@nukipa/post-content';

package/dist/islands.d.ts

@@ -0,0 +1,15 @@
+import type { Mount } from '@nukipa/post-content';
+export interface IslandEndpoints {
+    /** POST { slug, ...values } — relay to /public/v1/forms/:slug/submit. */
+    forms: string;
+    /** POST { cta_id, cta_label, cta_url, post_id, page_path, ... }. */
+    ctaClicks: string;
+    /** POST { component_id, values } scoped to a postId in the URL: `${contactForms}/${postId}`. */
+    contactForms: string;
+}
+interface HydrationContext {
+    endpoints: IslandEndpoints;
+    postId: string | null;
+}
+export declare function hydrateIslands(root: HTMLElement, mounts: Mount[], ctx: HydrationContext): () => void;
+export {};

package/dist/islands.js

@@ -0,0 +1,106 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+// Island hydration for the post body.
+//
+// `hydrateIslands` walks the rendered HTML for `data-island="..."` markers
+// and attaches behaviour. Returns a cleanup function that unbinds every
+// listener and unmounts every React root — call from a useEffect cleanup.
+//
+// Forms and CTA clicks POST to same-origin relay routes (the host app's
+// server-side handler attaches `X-Forwarded-Host` and forwards to the
+// gateway). Browser-direct calls to the gateway aren't viable: gateway
+// CORS uses an allowlist, and `X-Forwarded-Host` is not in `allowedHeaders`
+// so a browser couldn't spoof its own host anyway.
+import { createRoot } from 'react-dom/client';
+import { LeadForm } from './LeadForm';
+import { ContactForm } from './ContactForm';
+export function hydrateIslands(root, mounts, ctx) {
+    const cleanups = [];
+    // CTAs: enhance the existing <a> with a click tracker. We don't replace
+    // the link — server-rendered HTML stays the source of truth so SEO + no-JS
+    // clients still navigate. Use sendBeacon when available (survives unload).
+    const anchors = root.querySelectorAll('[data-island="cta"] a[data-cta-id]');
+    anchors.forEach((a) => {
+        const onClick = () => {
+            try {
+                const payload = JSON.stringify({
+                    cta_id: a.getAttribute('data-cta-id'),
+                    cta_label: a.getAttribute('data-cta-label'),
+                    cta_url: a.getAttribute('href'),
+                    post_id: ctx.postId,
+                    page_path: typeof window !== 'undefined' ? window.location.pathname : null,
+                    referrer: typeof document !== 'undefined' ? document.referrer || null : null,
+                    user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : null
+                });
+                if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+                    navigator.sendBeacon(ctx.endpoints.ctaClicks, new Blob([payload], { type: 'application/json' }));
+                }
+                else {
+                    fetch(ctx.endpoints.ctaClicks, {
+                        method: 'POST',
+                        body: payload,
+                        headers: { 'Content-Type': 'application/json' },
+                        keepalive: true
+                    }).catch(() => { });
+                }
+            }
+            catch { /* never block navigation */ }
+        };
+        a.addEventListener('click', onClick, { passive: true });
+        cleanups.push(() => a.removeEventListener('click', onClick));
+    });
+    // Lead-gen forms.
+    const leadEls = root.querySelectorAll('[data-island="form"]');
+    leadEls.forEach((el) => {
+        const slug = el.getAttribute('data-form-slug');
+        if (!slug)
+            return;
+        const r = createRoot(el);
+        r.render(_jsx(LeadForm, { slug: slug, endpoint: ctx.endpoints.forms, title: el.getAttribute('data-form-title'), description: el.getAttribute('data-form-description'), submitLabel: el.getAttribute('data-form-submit-label') }));
+        cleanups.push(() => r.unmount());
+    });
+    // Contact forms (inline schema on the post component).
+    const contactEls = root.querySelectorAll('[data-island="contact-form"]');
+    contactEls.forEach((el) => {
+        const componentId = el.getAttribute('data-component-id') || '';
+        const raw = el.getAttribute('data-content') || '{}';
+        let content = {};
+        try {
+            content = JSON.parse(raw);
+        }
+        catch { /* ignore */ }
+        if (!ctx.postId)
+            return;
+        const r = createRoot(el);
+        r.render(_jsx(ContactForm, { endpoint: `${ctx.endpoints.contactForms}/${ctx.postId}`, componentId: componentId, title: content.title ?? null, description: content.description ?? null, submitLabel: content.submit_label ?? null, successMessage: content.success_message ?? null, fields: content.fields ?? [] }));
+        cleanups.push(() => r.unmount());
+    });
+    // Carousel: minimal prev/next behaviour, no autoplay.
+    const carousels = root.querySelectorAll('[data-island="carousel"]');
+    carousels.forEach((el) => {
+        const slides = Array.from(el.querySelectorAll('.bp-carousel__slide'));
+        if (slides.length === 0)
+            return;
+        let active = slides.findIndex((s) => s.classList.contains('active'));
+        if (active < 0)
+            active = 0;
+        const setActive = (i) => {
+            const next = (i + slides.length) % slides.length;
+            slides[active].classList.remove('active');
+            slides[next].classList.add('active');
+            active = next;
+        };
+        const prev = el.querySelector('[data-carousel-prev]');
+        const next = el.querySelector('[data-carousel-next]');
+        const onPrev = () => setActive(active - 1);
+        const onNext = () => setActive(active + 1);
+        prev?.addEventListener('click', onPrev);
+        next?.addEventListener('click', onNext);
+        cleanups.push(() => {
+            prev?.removeEventListener('click', onPrev);
+            next?.removeEventListener('click', onNext);
+        });
+    });
+    return () => { for (const fn of cleanups)
+        fn(); };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name":    "@nukipa/post-renderer-react",
+  "version": "0.1.0",
+  "description": "React adapter for @nukipa/post-content — renders Nukipa CMS post bodies and hydrates interactive islands (forms, CTAs, carousels).",
+  "license": "MIT",
+  "author": "Nukipa Labs",
+  "homepage": "https://github.com/nukipa-labs/nukipa/tree/main/packages/post-renderer-react",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nukipa-labs/nukipa.git",
+    "directory": "packages/post-renderer-react"
+  },
+  "bugs": {
+    "url": "https://github.com/nukipa-labs/nukipa/issues"
+  },
+  "keywords": ["nukipa", "cms", "react", "renderer", "post"],
+  "type":    "module",
+  "main":    "./dist/index.js",
+  "types":   "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types":  "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default":"./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build":          "tsc -p tsconfig.build.json",
+    "clean":          "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@nukipa/post-content": "^0.1.0"
+  },
+  "peerDependencies": {
+    "marked":    "^17.0.0",
+    "react":     "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react":     "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript":       "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}