webim-adapter 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# webim-adapter
+
+Render pages built with the WebIM page builder inside any React app.
+
+```bash
+npm install webim-adapter
+```
+
+```jsx
+import { WebimPage } from 'webim-adapter';
+
+<WebimPage
+  apiUrl="https://api.example.com/api" // WebIM gateway base
+  tenant="acme"                        // tenant slug (X-Tenant header)
+  slug="landing"                       // published page slug
+  locale="tr"                          // optional content locale
+  mode="auto"                          // auto | light | dark
+  fallback={<Spinner />}               // while loading
+  errorFallback={<NotFound />}         // on 404 / network error
+  onLoad={(bundle) => (document.title = bundle.seo?.title ?? bundle.title)}
+/>
+```
+
+Only published pages render — drafts 404. The component fetches the page
+(`GET /render/:slug`) and the tenant's public theme/component libraries
+(`GET /settings/public`) in parallel, then renders the block tree with the
+same renderer the builder uses. Embedded WebIM forms submit to the public
+forms engine automatically.
+
+## SSR / prefetching
+
+`WebimPage` fetches on mount. For server rendering, fetch the bundle
+yourself and render the pure component:
+
+```jsx
+import { fetchPage, WebimContent } from 'webim-adapter';
+
+// in a server loader
+const bundle = await fetchPage({ apiUrl, tenant: 'acme', slug: 'landing' });
+
+// in the component tree
+<WebimContent bundle={bundle} mode="light" />
+```
+
+## Script-tag embed (no React required)
+
+For plain HTML / WordPress-style sites, `build/webim-embed.js` is a
+self-contained bundle (React included). Either drop containers and one tag:
+
+```html
+<div data-webim-page data-api="https://api.example.com/api"
+     data-tenant="acme" data-slug="landing" data-mode="auto"></div>
+<script src="https://unpkg.com/webim-adapter/build/webim-embed.js"></script>
+```
+
+…or let the script tag place the page right where it sits:
+
+```html
+<script src=".../webim-embed.js" data-api="…" data-tenant="acme" data-slug="landing"></script>
+```
+
+`data-locale` and `data-mode` (`auto|light|dark`) work on both. Containers
+added after load: `window.WebimEmbed.scan()`, or
+`window.WebimEmbed.mount(el, { apiUrl, tenant, slug, locale, mode })`.
+
+## Server-rendered HTML (zero-JS consumers / SEO)
+
+The WebIM gateway serves a complete HTML document per published page:
+
+```
+GET /api/render/:slug/html?tenant=acme&locale=tr&mode=light
+```
+
+Browser-navigable (tenant rides the query string), with the page's SEO meta
+in the head and custom JS inlined. Static markup: theme, blocks, custom
+CSS/JS and iframes all work; React-stateful pieces (engine-wired form
+submits, sliders/tabs, Embed-block markup) stay inert — use the script
+embed when those matter. The endpoint allows iframing, so
+`<iframe src=".../render/landing/html?tenant=acme">` is also a valid embed.
+
+Node servers can render themselves via `webim-adapter/ssr`:
+
+```js
+import { fetchPage, renderPageDocument, renderBundleHtml } from 'webim-adapter/ssr';
+
+const bundle = await fetchPage({ apiUrl, tenant, slug });
+const document = renderPageDocument(bundle, { mode: 'light', lang: 'en' });
+const bodyOnly = renderBundleHtml(bundle); // splice into your own layout
+```
+
+## Draft previews
+
+Only published pages render publicly. To preview a draft, an authenticated
+editor mints a signed 30-minute token:
+
+```
+POST /api/pages/:id/preview-token   (Bearer auth)
+→ { token, expires_in, slug }
+```
+
+The token unlocks that one page's current state everywhere:
+
+```jsx
+<WebimPage … preview={token} />
+await fetchPage({ …, preview: token });
+GET /api/render/:slug/html?tenant=acme&preview=<token>
+```
+
+The Pages list in the dashboard has a "Copy preview link" action that mints
+a token and copies the ready-to-share HTML URL.
+
+## Lower-level exports
+
+- `PageRenderer` — render a raw `blocks` tree you already have.
+- `renderRichContent(value)` — render a rich-text field value from a
+  collection entry.
+- `resolveTheme(meta, themes)` — pick the theme tokens for a page.
+
+## Notes
+
+- Peer deps: `react` / `react-dom` 19+ (Google Font links rely on React 19
+  head hoisting).
+- A page's custom code (`meta.custom.js` and Embed blocks) executes in the
+  host page — embed content only from tenants you trust, exactly like a tag
+  manager snippet.
+- The WebIM gateway must allow CORS from the host origin.