@preprio/toolkit 0.5.0-rc.5 → 0.5.0-rc.7

package/README.md

@@ -127,6 +127,7 @@ Per-framework peer dependencies — all optional; installing without them is fin
 | `@preprio/toolkit/astro`          | none (`.astro` components compile in your own pipeline) |
 | `@preprio/toolkit/sveltekit`      | `svelte` (only for the `.svelte` components)            |
 | `@preprio/toolkit/sveltekit/live` | none (returns a plain Svelte store)                     |
+| `@preprio/toolkit/codegen`        | `graphql` >= 16 (build time, from your Codegen setup)   |
 | `@preprio/toolkit/nuxt`           | `vue` (only for the `.vue` components)                  |
 | `@preprio/toolkit/nuxt/live`      | `vue` >= 3.3                                            |
 
@@ -621,23 +622,22 @@ const location = useLocation();
 
 ### Tracking pageviews
 
-`loadTrackingPixel` queues one `pageload` event when it installs. Client-side route changes emit nothing on their own, so fire them yourself:
+The pixel tracks pageviews by itself, client-side route changes included. It counts a view for the Prepr content item named by a `prepr:id` meta tag in `<head>`, and watches that tag: when a route change points it at another item, the pixel records a new view. Render the tag on every page that shows a Prepr item:
 
 ```tsx
-import { useEffect } from 'react';
-import { useLocation } from 'react-router';
-import { trackEvent } from '@preprio/toolkit';
-
-function usePreprPageviews() {
-  const { pathname } = useLocation();
-
-  useEffect(() => {
-    trackEvent('pageload');
-  }, [pathname]);
+function Page({ page }: { page: { _id: string } }) {
+  return (
+    <>
+      <meta property="prepr:id" content={page._id} />
+      {/* … */}
+    </>
+  );
 }
 ```
 
-This double-counts the first pageview, since the pixel's own install event fires too. Skip the initial run with a ref if the exact count matters.
+React 19 hoists a `<meta>` rendered anywhere in the tree into `<head>`. On React 18, set it with your head manager (`react-helmet-async` or similar) instead.
+
+A page without the tag records no view. Calling `trackEvent('pageload')` yourself does not help: the pixel takes one `pageload` per page load and ignores the rest. Use `trackEvent` for your own events, such as `trackEvent('add_to_cart', { productId })`.
 
 The `id` is your access token, and in a client-rendered app it is public — bundled into JS and visible in devtools. Use a tracking-only token; do not derive it from a browser-exposed GraphQL URL, which would also expose content read access.
 
@@ -729,22 +729,129 @@ exactly these.
 
 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:
+saving. Every model, component and dynamic content entry that should
+live-update needs `_id` (and ideally `__typename`) in the query result; items
+without `_id` stay static.
+
+There are three ways to get them there. Pick the first that fits your setup.
+
+#### Option 1: GraphQL Codegen (recommended)
+
+Add the `preprIds` document transform to your Codegen output. `_id` is
+added wherever your schema has one: on models and components, and inside
+each member of a dynamic content field. Collections like `Pages` and unions
+themselves never get an `_id`, so the queries stay valid. Your `.graphql`
+files stay as they are; the generated documents and types include the field,
+at no runtime cost. Adding a field never breaks code that compiles today, so
+this is safe to turn on in an existing project.
+
+```ts
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli';
+import { preprIds } from '@preprio/toolkit/codegen';
+
+const config: CodegenConfig = {
+  schema: process.env.PREPR_GRAPHQL_URL,
+  documents: ['src/queries/**/*.graphql'],
+  generates: {
+    'src/gql/': {
+      preset: 'client',
+      documentTransforms: [preprIds],
+    },
+  },
+};
+
+export default config;
+```
+
+Run Codegen again after adding it. Needs `graphql` 16 or later, which a
+Codegen setup already has.
+
+To add `__typename` everywhere too, use `createPreprIds({ typename: true })`
+instead. It is off by default because a selected `__typename` changes the
+generated types: each member of a union is typed on its own, so code that
+reads a union's fields without checking `__typename` first stops compiling.
+Live preview only needs it on dynamic content entries, where you select it
+already to render them.
+
+#### Option 2: at runtime, without Codegen
+
+`addPreprIds(document, schema)` does the same to a parsed query. It needs
+your schema, which Prepr serves through introspection on the same GraphQL
+URL. Load it once on the server, and transform each query once:
+
+```ts
+import { addPreprIds } from '@preprio/toolkit/codegen';
+import {
+  buildClientSchema,
+  getIntrospectionQuery,
+  parse,
+  print,
+  type GraphQLSchema,
+} from 'graphql';
+
+const url = process.env.PREPR_GRAPHQL_URL!;
+
+let schema: Promise<GraphQLSchema> | undefined;
+function preprSchema(): Promise<GraphQLSchema> {
+  schema ??= fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: getIntrospectionQuery() }),
+  })
+    .then((response) => response.json())
+    .then(({ data }) => buildClientSchema(data));
+  return schema;
+}
+
+const prepared = new Map<string, string>();
+export async function withPreprIds(query: string): Promise<string> {
+  let result = prepared.get(query);
+  if (!result) {
+    result = print(addPreprIds(parse(query), await preprSchema()));
+    prepared.set(query, result);
+  }
+  return result;
+}
+```
+
+Then send `await withPreprIds(query)` instead of `query` in your fetch
+helper. With a client that takes a `DocumentNode`, pass
+`addPreprIds(document, schema)` instead. Keep this on the server: the
+GraphQL URL carries your access token.
+
+#### Option 3: by hand
+
+Select `_id` (and `__typename`) on every model and component level, and on
+every entry type in dynamic content fields (`Text`, `Quote`, …). `Assets`
+entries have no `_id` of their own: select `items { _id }` instead.
+
+The rest is about rendering:
 
-- Select `_id` (and ideally `__typename`) on every model and component level
-  that should live-update. Items without `_id` 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.
 - A `Text` entry's content updates whether the query selects `body`,
   `html` or `text` (the latter with tags stripped).
-- 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: preview })`
-  on the element that renders them.
+- **Dynamic content entries are found automatically.** In preview,
+  `normalizeQuery`, `normalizedQuery` and `useNormalizedQuery` add each
+  entry's `_id` (and, for `Text` entries, the field path) to the hidden edit
+  link of every text inside it. Click-to-edit and the editor's "jump to
+  field" then find the entry by id, also after an editor reorders entries.
+  Render a `Text` entry's HTML straight into one wrapper element, so its
+  edit link lands on that wrapper and the whole entry is outlined.
+- Prepr images are click-to-edit inside the editor without any markup: the
+  toolkit matches image URLs (also through image optimizers like
+  `/_next/image`) to the open item's assets.
+- **Set the attributes yourself only where that does not reach:**
+  - Data you fetch in the browser without those helpers: run it through
+    `annotateEditLinks(result, query)` from `@preprio/toolkit`, or mark the
+    element as below.
+  - An entry with no text and no Prepr image (an embed, a video URL): wrap
+    it in an element with `data-prepr-edit-target="<field>.<index>"` and
+    `data-prepr-entry-id="<entry _id>"` (for `Assets`, the first asset's
+    `_id`). Attributes you set always win over the automatic ones.
+  - Other values without a hidden edit link (video and other URLs): make
+    them click-to-edit with
+    `previewAttrs({ id, field }, { enabled: preview })` 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
@@ -1105,7 +1212,7 @@ createPreprPreview({ props, options: { locale: 'nl' } });
 
 - **Check `enabled`**: every live preview entry point needs your preview flag, and the middleware must run with `preview: true` for that page.
 - **Check the preview URL in Prepr**: it must point at a deployment that uses the GraphQL Preview token. A production build with preview off shows saved content only.
-- **Check `_id`**: an item or component whose query does not select `_id` stays static. See [Preparing your queries](#preparing-your-queries).
+- **Check `_id`**: an item or component whose query does not select `_id` stays static. Add the `preprIds` Codegen transform, or see [Preparing your queries](#preparing-your-queries).
 - **Check the frame**: a `Refused to frame` error in the browser console means your `Content-Security-Policy` `frame-ancestors` does not list your Prepr environment.
 - **Next.js only shows changes on save**: `normalizeQuery` with `PreprRefresh` needs Next.js 16 or later.
 

package/dist/astro/index.cjs

@@ -31,7 +31,7 @@ __export(astro_exports, {
 module.exports = __toCommonJS(astro_exports);
 
 // src/version.ts
-var VERSION = "0.5.0-rc.5";
+var VERSION = "0.5.0-rc.7";
 
 // src/core/features.ts
 function isEnabled(config) {
@@ -430,14 +430,14 @@ function indexSnapshot(data) {
   const index = /* @__PURE__ */ new Map();
   const visited = /* @__PURE__ */ new WeakSet();
   const path = [];
-  function walk(node) {
+  function walk2(node) {
     if (node === null || typeof node !== "object") return;
     if (visited.has(node)) return;
     visited.add(node);
     if (Array.isArray(node)) {
       for (let i = 0; i < node.length; i++) {
         path.push(i);
-        walk(node[i]);
+        walk2(node[i]);
         path.pop();
       }
       return;
@@ -455,11 +455,11 @@ function indexSnapshot(data) {
     for (const key in record) {
       if (!Object.prototype.hasOwnProperty.call(record, key)) continue;
       path.push(key);
-      walk(record[key]);
+      walk2(record[key]);
       path.pop();
     }
   }
-  walk(data);
+  walk2(data);
   return index;
 }
 
@@ -916,12 +916,12 @@ function resolveFields(selections, typename, doc, options) {
     }
   };
   const applies = (on, list) => conditionMatches(on, typename) || typename !== void 0 && typeConditions(list, doc).includes(typename);
-  const walk = (list, matched) => {
+  const walk2 = (list, matched) => {
     for (const s of list) {
       if (s.kind === "field") {
         add(matched ? exact : loose, s);
       } else if (s.kind === "inline") {
-        walk(s.selections, matched && applies(s.on, s.selections));
+        walk2(s.selections, matched && applies(s.on, s.selections));
       } else {
         const fragment = doc.fragments.get(s.name);
         if (!fragment) continue;
@@ -929,11 +929,11 @@ function resolveFields(selections, typename, doc, options) {
         if (walkedMatched.has(fragment)) continue;
         if (!asMatched && walkedLoose.has(fragment)) continue;
         (asMatched ? walkedMatched : walkedLoose).add(fragment);
-        walk(fragment.selections, asMatched);
+        walk2(fragment.selections, asMatched);
       }
     }
   };
-  walk(selections, true);
+  walk2(selections, true);
   if (!options.strict) {
     for (const [key, field] of loose) {
       if (!exact.has(key)) exact.set(key, field);
@@ -950,21 +950,21 @@ function typeConditions(selections, doc) {
   if (hit) return hit;
   const names = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Set();
-  const walk = (list) => {
+  const walk2 = (list) => {
     for (const s of list) {
       if (s.kind === "inline") {
         if (s.on) names.add(s.on);
-        walk(s.selections);
+        walk2(s.selections);
       } else if (s.kind === "spread") {
         const fragment = doc.fragments.get(s.name);
         if (!fragment || seen.has(fragment)) continue;
         seen.add(fragment);
         names.add(fragment.on);
-        walk(fragment.selections);
+        walk2(fragment.selections);
       }
     }
   };
-  walk(selections);
+  walk2(selections);
   const conditions = [...names];
   conditionsCache.set(selections, conditions);
   return conditions;
@@ -1259,7 +1259,7 @@ function resolveTargets(root, doc, ownerPath, segments) {
   let current = root;
   const out = [];
   const plain = /* @__PURE__ */ new Set();
-  const walk = (node, sel, i, path) => {
+  const walk2 = (node, sel, i, path) => {
     if (i === segments.length) {
       out.push(path);
       return;
@@ -1269,10 +1269,10 @@ function resolveTargets(root, doc, ownerPath, segments) {
       if (INDEX_SEGMENT.test(segment)) {
         const position = Number(segment);
         if (position < node.length) {
-          walk(node[position], sel, i + 1, [...path, position]);
+          walk2(node[position], sel, i + 1, [...path, position]);
         }
       } else if (segment === "items") {
-        walk(node, sel, i + 1, path);
+        walk2(node, sel, i + 1, path);
       }
       return;
     }
@@ -1305,11 +1305,11 @@ function resolveTargets(root, doc, ownerPath, segments) {
           current = writeAtPath(current, fieldPath, value);
         }
       }
-      walk(value, field.selections, i + 1, fieldPath);
+      walk2(value, field.selections, i + 1, fieldPath);
     }
-    if (!matched && segment === "items") walk(node, sel, i + 1, path);
+    if (!matched && segment === "items") walk2(node, sel, i + 1, path);
   };
-  walk(owner, selections, 0, ownerPath);
+  walk2(owner, selections, 0, ownerPath);
   return { root: current, targets: out, plain };
 }
 var NON_ALPHANUMERIC = /[^a-z0-9]/gi;
@@ -1432,11 +1432,11 @@ function listKeysIn(result) {
     if (!byType) {
       byType = /* @__PURE__ */ new Map();
       const seen = /* @__PURE__ */ new WeakSet();
-      const walk = (node) => {
+      const walk2 = (node) => {
         if (node === null || typeof node !== "object" || seen.has(node)) return;
         seen.add(node);
         if (Array.isArray(node)) {
-          node.forEach(walk);
+          node.forEach(walk2);
           return;
         }
         const record = node;
@@ -1447,10 +1447,10 @@ function listKeysIn(result) {
             if (!keys) byType.set(type, keys = /* @__PURE__ */ new Set());
             keys.add(key);
           }
-          walk(value);
+          walk2(value);
         }
       };
-      walk(result);
+      walk2(result);
       listKeysCache.set(result, byType);
     }
     return byType.get(typename) ?? NO_KEYS;
@@ -1492,7 +1492,7 @@ function findEditLink(root) {
   if (linkCache.has(root)) return linkCache.get(root) ?? null;
   let found = null;
   const seen = /* @__PURE__ */ new WeakSet();
-  const walk = (node) => {
+  const walk2 = (node) => {
     if (found) return;
     if (typeof node === "string") {
       if (!(0, import_stega2.vercelStegaSplit)(node).encoded) return;
@@ -1507,9 +1507,9 @@ function findEditLink(root) {
     }
     if (node === null || typeof node !== "object" || seen.has(node)) return;
     seen.add(node);
-    for (const value of Object.values(node)) walk(value);
+    for (const value of Object.values(node)) walk2(value);
   };
-  walk(root);
+  walk2(root);
   linkCache.set(root, found);
   return found;
 }
@@ -1535,6 +1535,101 @@ async function readLiveLogFromRequest(request) {
   }
 }
 
+// src/core/live-preview/edit-links.ts
+var import_stega3 = require("@vercel/stega");
+var ENTRY_PARAM = "entry";
+var TOP_LEVEL_ENTRY = /^[A-Za-z0-9_]+\.\d+$/;
+function entryIdOf(element) {
+  if (!isRecord(element)) return void 0;
+  if (typeof element._id === "string") return element._id;
+  if (element.__typename !== "Assets" || !Array.isArray(element.items)) {
+    return void 0;
+  }
+  const first = element.items[0];
+  return isRecord(first) && typeof first._id === "string" ? first._id : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function annotate(value, ctx) {
+  if (!ctx.entryId) return value;
+  const { cleaned, encoded } = (0, import_stega3.vercelStegaSplit)(value);
+  if (!encoded) return value;
+  let payload;
+  try {
+    payload = (0, import_stega3.vercelStegaDecode)(encoded);
+  } catch {
+    return value;
+  }
+  if (typeof payload?.href !== "string") return value;
+  let url;
+  try {
+    url = new URL(payload.href);
+  } catch {
+    return value;
+  }
+  if (url.searchParams.has(ENTRY_PARAM)) return value;
+  url.searchParams.set(ENTRY_PARAM, ctx.entryId);
+  const itemId = decodeURIComponent(url.pathname.split("/").pop() ?? "");
+  if (!url.searchParams.has("field") && ctx.entryField && TOP_LEVEL_ENTRY.test(ctx.entryField) && itemId === ctx.entryOwnerId) {
+    url.searchParams.set("field", ctx.entryField);
+  }
+  return (0, import_stega3.vercelStegaCombine)(
+    cleaned,
+    { ...payload, href: url.toString() },
+    false
+  );
+}
+function walk(value, selections, ctx) {
+  if (typeof value === "string") return annotate(value, ctx);
+  if (Array.isArray(value)) {
+    let changed2 = false;
+    const next2 = value.map((element, index) => {
+      const path = [...ctx.path, String(index)];
+      const entryId = ctx.inAssets ? void 0 : entryIdOf(element);
+      const entry = entryId ? {
+        entryId,
+        entryField: ctx.ownerId ? path.join(".") : void 0,
+        entryOwnerId: ctx.ownerId,
+        inAssets: isRecord(element) && element._id === void 0
+      } : {};
+      const out = walk(element, selections, { ...ctx, ...entry, path });
+      if (out !== element) changed2 = true;
+      return out;
+    });
+    return changed2 ? next2 : value;
+  }
+  if (!isRecord(value)) return value;
+  const id = typeof value._id === "string" ? value._id : void 0;
+  const typename = typeof value.__typename === "string" ? value.__typename : void 0;
+  const fields = ctx.doc && selections ? collectFields(selections, typename, ctx.doc) : null;
+  let changed = false;
+  const next = {};
+  for (const [key, child] of Object.entries(value)) {
+    const field = fields?.get(key);
+    const name = field?.name ?? key;
+    const out = walk(child, field?.selections ?? null, {
+      ...ctx,
+      ownerId: id ?? ctx.ownerId,
+      path: id ? [name] : [...ctx.path, name]
+    });
+    if (out !== child) changed = true;
+    next[key] = out;
+  }
+  return changed ? next : value;
+}
+function annotateEditLinks(result, query, operationName) {
+  let doc = null;
+  if (query !== void 0) {
+    try {
+      doc = readQueryDocument(query, operationName);
+    } catch {
+      doc = null;
+    }
+  }
+  return walk(result, doc?.operation ?? null, { doc, path: [] });
+}
+
 // src/astro/index.ts
 var LIVE_LOG = /* @__PURE__ */ Symbol.for("@preprio/toolkit/astro-live-log");
 async function onPreprRequest(context, next, options) {
@@ -1575,10 +1670,11 @@ async function getToolbarProps(headers, token, features) {
   return getToolbarPropsFromHeaders(headers, token, features);
 }
 function normalizeQuery2(query, result, options = {}) {
-  if (!options.enabled || !options.locals) return result;
-  const log = options.locals[LIVE_LOG];
-  if (!log?.length) return result;
-  return normalizeQuery(query, result, {
+  if (!options.enabled) return result;
+  const annotated = annotateEditLinks(result, query, options.operationName);
+  const log = options.locals?.[LIVE_LOG];
+  if (!log?.length) return annotated;
+  return normalizeQuery(query, annotated, {
     log,
     operationName: options.operationName
   });