@preprio/toolkit 0.5.0-rc.2 → 0.5.0-rc.3

package/README.md

@@ -250,6 +250,155 @@ The loader rewrites `w_` to the width Next asks for and scales `h_` alongside it
 
 See the runnable example at `examples/nextjs` for the full source of truth.
 
+### Live preview (beta)
+
+True live preview inside the Prepr editor iframe: keystrokes patch your query
+results instantly by item `_id`; saves refetch the affected queries.
+
+**Requirements.** Live preview runs only where the Prepr middleware handles
+the request with `preview: true` (`createPreprMiddleware(request, { preview })`
+in `proxy.ts`). Make sure your middleware `matcher` covers every page you
+preview: on a page it skips, live preview does nothing and shows no error.
+Pass your preview flag as `enabled` to every live preview entry point below;
+each one does nothing without it.
+
+Live updates and click-to-edit find content by id, never by position, so
+they stay correct while an editor adds, removes or reorders blocks before
+saving:
+
+- Select `_id` (and ideally `__typename`) on every model and component level
+  that should live-update. Items without `_id` silently stay static.
+- In dynamic content fields, select `_id` on every entry type (`Text`,
+  `Quote`, …). `Assets` entries have no `_id` of their own: select
+  `items { _id }` instead.
+- Render each dynamic content entry inside an element marked with
+  `data-prepr-edit-target="<field>.<index>"` and
+  `data-prepr-entry-id="<entry _id>"` (for `Assets`, the first asset's
+  `_id`). The index is the fallback when no id matches.
+- Values without a hidden edit link (images, videos, other URLs) are made
+  click-to-edit with `previewAttrs({ id, field }, { enabled: isPreview })`
+  on the element that renders them.
+- Where the page renders a linked item whose content comes from items nested
+  inside it (for example a personalization or a shared section referenced
+  from a stack), wrap it in an element with
+  `data-prepr-reference="<linked item _id>"`. The editor only knows the items
+  the open item links to directly; content inside the wrapper is outlined as
+  that linked item, and clicking it opens the link in the editor.
+
+Configure once in a small client component mounted in your root layout:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { initLivePreview } from '@preprio/toolkit/nextjs/live';
+
+export default function LivePreviewInit({ preview }: { preview: boolean }) {
+  useEffect(() => {
+    initLivePreview({
+      // Your preview flag. Without it nothing starts.
+      enabled: preview,
+      // Runs a registered query against Prepr GraphQL. `query` is whatever
+      // you registered (string or DocumentNode) — you own the transport.
+      fetcher: async (query, variables) => {
+        /* POST to your Prepr GraphQL endpoint, return json.data */
+      },
+    });
+  }, [preview]);
+  return null;
+}
+```
+
+Register query results in client components with `useLive`:
+
+```tsx
+'use client';
+import { useLive } from '@preprio/toolkit/nextjs/live';
+
+export default function PageContent({ data, slug }) {
+  const liveData = useLive(data, {
+    query: GetPageBySlugDocument,
+    variables: { slug },
+  });
+  // render from liveData — it re-renders on editor keystrokes and saves
+}
+```
+
+In `'use client'` files always import from `@preprio/toolkit/nextjs/live` —
+the `/nextjs` barrel also exports server-only helpers (`next/headers`), which
+a client module graph must not include.
+
+Omitting `query`/`variables` degrades that registration to keystroke pushes
+only. For server-component pages, mount `<PreprRefresh enabled={preview} />`
+instead — it calls `router.refresh()` on every save. Don't combine
+`PreprRefresh` with `useLive` registrations that pass a `query`: a save would
+both refetch and refresh. `useLive` without a `query` works alongside it.
+
+Without `enabled`, and outside the Prepr editor iframe, all of this is a
+passthrough with zero overhead. The CMS editor must emit `prepr:fieldChange` (per keystroke) and
+`prepr:itemChanged` (on save, with the root content item id) into the preview
+iframe — `examples/editor-emulator` emulates this for local development.
+Unsaved structural changes (adding/reordering components) appear after save;
+typed text is live immediately.
+
+#### Unsaved changes in server components: `normalizeQuery` (experimental, Next.js 16+)
+
+Server components show the editor's unsaved changes when you pass their query
+results through `normalizeQuery`, with whatever client you fetch with:
+
+```ts
+import { normalizeQuery } from '@preprio/toolkit/nextjs';
+
+const preview = process.env.VERCEL_ENV !== 'production';
+
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
+```
+
+Mount `<PreprRefresh enabled={preview} />` in the root layout. While an
+editor types, it sends the unsaved changes to the server and the route
+re-renders with them; on save it refreshes with the stored content.
+
+- The query (source text, a `DocumentNode`, or a typed document string) tells
+  the toolkit which response key holds which field. Changes land under
+  aliases, inside single components, on dynamic content entries, and on every
+  place the same item appears. Fields the query did not select are left
+  alone. Select `_id` on every item and component that should update.
+- Changed text keeps its hidden edit link, so it stays click-to-edit.
+- `useLive` data keeps the typed values across these re-renders.
+
+**Production safety.** Pass `enabled` from the same preview flag you give the
+middleware, and never `true` on a production deployment:
+
+- With `enabled: false` (the default) the result is returned untouched and
+  the request is never read, so static and ISR pages stay static.
+  `PreprRefresh`, `initLivePreview` and `useLive` don't listen to the editor
+  at all.
+- Next.js registers the toolkit's server action in every build that imports
+  `@preprio/toolkit/nextjs/live`, so anyone can call it, browsers and scripts
+  alike. It does nothing (no parsing, no storage, no re-render) unless the
+  Prepr middleware handled the request with `preview: true`. The middleware
+  drops `Prepr-*` headers a client sends, so this can't be forged on a page
+  the middleware runs for. On a page its `matcher` skips, a forged header can
+  at most trigger an extra render, never change content, because
+  `normalizeQuery` there still needs `enabled`.
+- Changes only reach the re-render of the editor's own server action call.
+  The action stores them in the server process under a random, single-use
+  token and sets only that token as a cookie that expires immediately. Any
+  other request carrying the cookie, such as a plain or cacheable GET that
+  replays a token, sees nothing.
+- Changes are only accepted from the Prepr editor (`https://*.prepr.io`, or
+  your `allowedEditorOrigins` via `initLivePreview`), never from another page
+  that frames your site. They are validated as hostile input: link fields
+  never take `javascript:`, `vbscript:` or `data:` URLs. HTML text is passed
+  on as typed, like rich text from the API.
+
+On Next.js 15 and older the action does nothing and pages update on save.
+
+For Astro and Nuxt, see their sections. The framework-free core exports,
+`normalizeQuery(query, result, { log })`, `startHtmlLivePreview()` and
+`readLiveLogFromRequest(request)` from `@preprio/toolkit`, cover any other
+server-rendered stack.
+
 ## Astro
 
 **`src/middleware.ts`**
@@ -301,6 +450,34 @@ The `.astro` components ship as source, compiled by your own Astro/Vite pipeline
 
 See the runnable example at `examples/astro` for the full source of truth.
 
+### Live preview (experimental)
+
+Show the editor's unsaved changes while they type. Pass `preview` to
+`onPreprRequest` as above, and run each query result through
+`normalizeQuery` with your preview flag:
+
+```astro
+---
+import { normalizeQuery } from '@preprio/toolkit/astro';
+
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = normalizeQuery(GetPageDocument, data, {
+  enabled: preview,
+  locals: Astro.locals,
+});
+---
+```
+
+`PreprToolbar.astro` does the rest. Inside the Prepr editor it requests the
+page again with the unsaved changes and updates only the parts of the DOM that
+changed; on save it shows the stored content. Preview must render on demand
+(`output: 'server'`).
+
+Safety: the middleware only accepts changes in preview, from a same-origin
+`POST` that carries the toolkit's header and a JSON body, and marks that
+response `Cache-Control: private, no-store`. With `enabled: false` the result
+is returned untouched. Changes are accepted only from the Prepr editor.
+
 ## SvelteKit
 
 **`src/hooks.server.ts`**
@@ -412,6 +589,25 @@ The `.vue` components ship as source (compiled by your own Vite/Vue pipeline) an
 
 See the runnable example at `examples/nuxt` for the full source of truth.
 
+### Live preview (experimental)
+
+Show the editor's unsaved changes while they type, with no server round trip:
+
+```ts
+import { useNormalizedQuery } from '@preprio/toolkit/nuxt/live';
+
+const { data, refresh } = await useAsyncData('page', () => fetchPage(slug));
+const page = useNormalizedQuery(GetPageDocument, data, {
+  enabled: preview, // your preview flag; nothing starts without it
+  onSave: refresh,
+});
+```
+
+Render from `page`. Nuxt hydrates the whole page, so every component that
+shows a changed field updates. Without `enabled`, on the server and outside
+the Prepr editor's preview iframe it returns the data unchanged. Changes are accepted only from
+the Prepr editor.
+
 ## React (no framework)
 
 `@preprio/toolkit/react` carries the two components that need nothing but React — for Vite + React Router, TanStack Router, Remix SPA mode, or Create React App. Next.js users want the [Next.js section](#nextjs) instead; its `PreprToolbar` binds the App Router for you.
@@ -636,7 +832,7 @@ controller.destroy();
 | Option       | Type                     | Description                                                                                                                                                                                                                                                                                      |
 | ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `props`      | `PreprToolbarProps`      | From `getToolbarProps`. Optional — a headless preview has no segment list to pass.                                                                                                                                                                                                               |
-| `options`    | `PreprPreviewOptions`    | `{ debug?, locale?, features?, ui?, allowedEditorOrigins?, autoClean? }`. See [Preview options](#preview-options).                                                                                                                                                                               |
+| `options`    | `PreprPreviewOptions`    | `{ debug?, locale?, features?, ui?, allowedEditorOrigins?, strictMode?, autoClean? }`. See [Preview options](#preview-options).                                                                                                                                                                  |
 | `navigation` | `PreprNavigationAdapter` | How segment/variant switches navigate. Optional — omitted, the toolbar uses `window.location.assign` (a full page load). `reload` is optional too, runs after a preview-mode toggle, and defaults to `window.location.reload()`. The Next.js and SvelteKit wrappers wire all of this up for you. |
 
 `createPreprPreview` is a no-op outside a browser (no `window`/`document`) and returns a controller whose `destroy()` does nothing, so it is safe to call during SSR. Call it **once per page** — two calls start two bridges and announce the preview twice.
@@ -694,14 +890,15 @@ createPreprMiddleware(request, response, { preview });
 createPreprPreview({ props, options: { debug: true, locale: 'nl' } });
 ```
 
-| Option                 | Type            | Default       | Description                                                                                                                                                 |
-| ---------------------- | --------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debug`                | `boolean`       | `false`       | Enable debug logging.                                                                                                                                       |
-| `locale`               | `'en' \| 'nl'`  | auto-detected | UI language. Falls back to the first supported browser language, then `en`.                                                                                 |
-| `features`             | `PreprFeatures` | all enabled   | Which features run. See [Feature flags](#feature-flags).                                                                                                    |
-| `ui`                   | `boolean`       | `true`        | Mount the visible toolbar. See [Headless preview](#headless-preview-no-toolbar-ui).                                                                         |
-| `allowedEditorOrigins` | `string[]`      | `*.prepr.io`  | Exact editor origins allowed to drive this preview, for self-hosted or local editors. Replaces the wildcard. `['*']` accepts any origin — development only. |
-| `autoClean`            | `boolean`       | `true`        | Strip the invisible stega characters from visible text. See [Stega auto-cleaning](#stega-auto-cleaning).                                                    |
+| Option                 | Type                           | Default       | Description                                                                                                                                                                                                                                                                   |
+| ---------------------- | ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debug`                | `boolean`                      | `false`       | Enable debug logging.                                                                                                                                                                                                                                                         |
+| `locale`               | `'en' \| 'nl' \| 'fr' \| 'de'` | auto-detected | UI language. Falls back to the first supported browser language, then `en`. Inside the Prepr editor, the editor's interface language wins.                                                                                                                                    |
+| `features`             | `PreprFeatures`                | all enabled   | Which features run. See [Feature flags](#feature-flags).                                                                                                                                                                                                                      |
+| `ui`                   | `boolean`                      | `true`        | Mount the visible toolbar. See [Headless preview](#headless-preview-no-toolbar-ui).                                                                                                                                                                                           |
+| `allowedEditorOrigins` | `string[]`                     | `*.prepr.io`  | Exact editor origins allowed to drive this preview, for self-hosted or local editors. Replaces the wildcard. `['*']` accepts any origin — development only.                                                                                                                   |
+| `strictMode`           | `boolean`                      | `false`       | Your preview token uses GraphQL strict mode (required fields never null). The editor then holds back new entries until their required fields are filled and never sends a cleared required field as null. Also on `PreprRefresh`, `initLivePreview` and `useNormalizedQuery`. |
+| `autoClean`            | `boolean`                      | `true`        | Strip the invisible stega characters from visible text. See [Stega auto-cleaning](#stega-auto-cleaning).                                                                                                                                                                      |
 
 `features` and `ui` are independent: `features` decides _what runs_, `ui` decides _whether the toolbar is visible_.
 
@@ -809,7 +1006,7 @@ Because the toolbar renders inside a shadow root, none of your own page CSS —
 
 ### Internationalization
 
-The toolbar UI ships with English and Dutch. Pass `locale` explicitly, or omit it to auto-detect from the browser and fall back to `en`:
+The toolbar UI ships with English, Dutch, French and German. Pass `locale` explicitly, or omit it to auto-detect from the browser and fall back to `en`. Inside the Prepr editor's preview, the visual editor's labels follow the language the editor user has set for the CMS, falling back to `locale` when the editor sends a language the toolkit does not support:
 
 ```typescript
 createPreprPreview({ props, options: { locale: 'nl' } });