@preprio/toolkit 0.2.0 → 0.3.2

package/README.md

@@ -1,5 +1,10 @@
 # @preprio/toolkit
 
+> **Beta — pre-1.0.** The package is published to `latest` and is safe to use, but the
+> public API can still change between minor versions (`0.2.x` → `0.3.0`). Every change
+> is documented in [Breaking changes](https://github.com/preprio/prepr-toolkit/blob/main/RELEASING.md#breaking-changes). Pin an exact
+> version in production, or use a tilde range (`~0.2.0`) so you only pick up patches.
+
 A framework-agnostic TypeScript library that provides preview functionality, visual editing, and A/B testing for [Prepr CMS](https://prepr.io). Ships thin wrappers for Next.js, Nuxt, Astro, and SvelteKit on top of a vanilla core that runs anywhere.
 
 Every integration is the same three steps:
@@ -10,6 +15,8 @@ Every integration is the same three steps:
 
 Jump to your framework: [Next.js](#nextjs) · [Astro](#astro) · [SvelteKit](#sveltekit) · [Nuxt](#nuxt) · [React without a framework](#react-no-framework) · [anything else](#any-other-framework).
 
+Coming from `@preprio/prepr-nextjs`? See the [migration guide](https://github.com/preprio/prepr-toolkit/blob/main/MIGRATION.md).
+
 ## Quick Start (Next.js)
 
 ```bash
@@ -812,6 +819,12 @@ createPreprPreview({ props, options: { locale: 'nl' } });
 - **Confirm the middleware matcher**: if `config.matcher` excludes the current path, no Prepr headers were set for it. `getPreprUUID()` returning `null` confirms this.
 - **Check for `prepr_hide_bar=true`** in the URL, which suppresses the bar by design.
 
+### Click-to-edit not working on some elements
+
+- **Check the token permissions**: "Enable edit mode" must be checked on the token in Prepr.
+- **Check whether the encoded text sits in a hidden element.** The parent of the encoded text node is what becomes editable, and a parent that renders no box (`display: none`, `visibility: hidden`, the `hidden` attribute) is skipped — it cannot be hovered or clicked. Put `data-prepr-edit-target` on the visible ancestor that should be editable instead. See [Choosing the element that becomes editable](#choosing-the-element-that-becomes-editable).
+- **Inspect the tagged elements**: `document.querySelectorAll('[data-prepr-encoded]')` in the console lists everything edit mode found. An element you expected to be in that list points at one of the two cases above.
+
 ### Headers not working
 
 - **Middleware setup**: confirm `middleware.ts` sits in the project root (or `src/`) and its matcher covers the route.
@@ -883,7 +896,40 @@ The toolbar renders with Preact into a shadow-DOM custom element (`<prepr-toolba
 
 With edit mode enabled, the toolkit scans for stega-encoded content, strips the invisible Unicode characters after load so they cannot cause layout shifts, highlights editable elements by cursor proximity, and talks to the Prepr editor over a `postMessage` bridge when running inside the live-preview iframe.
 
-Stega cleaning is automatic. There is no need to call `vercelStegaSplit` or hand-manage hidden spans — the data attributes the toolkit relies on survive the clean, so edit mode still activates instantly.
+Stega cleaning is automatic. There is no need to call `vercelStegaSplit` or to strip the payload yourself before rendering — the data attributes the toolkit relies on survive the clean, so edit mode still activates instantly.
+
+#### Choosing the element that becomes editable
+
+The element that gets the outline, the tooltip and the click handler is the **parent of the encoded text node**. Rendering `{title}` inside an `<h2>` makes the `<h2>` editable, which is what you want almost every time.
+
+Two rules govern the choice:
+
+- A parent that renders no box is skipped. An element hidden with `display: none`, `visibility: hidden`, or the `hidden` attribute cannot be hovered or outlined, so tagging it would produce an element that looks editable to the code and is unreachable to the visitor. Nothing is tagged for it.
+- `data-prepr-edit-target` overrides the parent. The closest ancestor carrying it becomes the editable element instead.
+
+That attribute is the supported way to separate _where the payload lives_ from _what the visitor clicks_. It is what makes the hidden-payload pattern work:
+
+```html
+<!-- The payload rides in a visually hidden span; the <article> is what
+     gets outlined and clicked. -->
+<article data-prepr-edit-target>
+  <h2>Product title</h2>
+  <span hidden>{encodedPayload}</span>
+</article>
+```
+
+Without the attribute that span is skipped entirely — it renders no box, so there is nothing to click.
+
+It is equally useful when the encoded text sits deep inside markup you do not control, and the natural click target is an ancestor:
+
+```html
+<figure data-prepr-edit-target>
+  <img src="..." alt="..." />
+  <figcaption><em>{encodedCaption}</em></figcaption>
+</figure>
+```
+
+Without it the `<em>` would be the editable element; with it the whole figure is.
 
 ## Examples
 
@@ -897,6 +943,14 @@ Runnable examples live in the repository root:
 | `examples/nuxt`      | `server/middleware`, `useAsyncData`, `.vue` components             |
 | `examples/express`   | Vanilla core — a hand-written adapter for an unsupported framework |
 
+## Migrating from `@preprio/prepr-nextjs`
+
+`@preprio/toolkit` replaces the Next.js-only `@preprio/prepr-nextjs` package. Most of
+the change is import paths — the middleware signature is unchanged and the server
+helpers keep their names — but the toolbar's provider and the stylesheet are gone.
+
+The [migration guide](https://github.com/preprio/prepr-toolkit/blob/main/MIGRATION.md) has the diffs.
+
 ## Support
 
 - **Documentation**: [Prepr Documentation](https://docs.prepr.io)

package/dist/astro/index.cjs

@@ -30,7 +30,7 @@ __export(astro_exports, {
 module.exports = __toCommonJS(astro_exports);
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/astro/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/{chunk-4PJK6IQ4.js → chunk-GIEOTQD4.js}

@@ -169,6 +169,20 @@ function walkTextNodes(root, visit) {
     visit(node);
   }
 }
+function resolveEditTarget(node) {
+  const parent = node.parentElement;
+  if (!parent) return null;
+  const editTarget = parent.closest("[data-prepr-edit-target]");
+  if (editTarget) return editTarget;
+  return isRenderedElement(parent) ? parent : null;
+}
+function isRenderedElement(element) {
+  if (element.hidden) return false;
+  if (element.getClientRects().length === 0) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.display !== "none";
+}
 function tagEncodedElement(element, decoded) {
   element.setAttribute("data-prepr-encoded", "");
   element.setAttribute("data-prepr-href", decoded.href);
@@ -192,7 +206,7 @@ var StegaElements = class {
   tagFromTextNode(node) {
     const decoded = this.decode(node.textContent);
     if (!decoded?.href) return false;
-    const target = node.parentElement;
+    const target = resolveEditTarget(node);
     if (!target || target.hasAttribute("data-prepr-encoded")) return false;
     tagEncodedElement(target, decoded);
     return true;
@@ -630,11 +644,7 @@ function createStegaAutoClean() {
       if (!decoded?.href) return false;
       cleaned.set(textNode, { original: textContent, cleaned: stripped });
       textNode.textContent = stripped;
-      let target = textNode.parentElement;
-      const editTargetParent = textNode.parentElement?.closest(
-        "[data-prepr-edit-target]"
-      );
-      if (editTargetParent) target = editTargetParent;
+      const target = resolveEditTarget(textNode);
       if (target) {
         tagEncodedElement(target, decoded);
         return true;

package/dist/index.cjs

@@ -44,7 +44,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/features.ts
 function isEnabled(config) {
@@ -420,6 +420,20 @@ function walkTextNodes(root, visit) {
     visit(node);
   }
 }
+function resolveEditTarget(node) {
+  const parent = node.parentElement;
+  if (!parent) return null;
+  const editTarget = parent.closest("[data-prepr-edit-target]");
+  if (editTarget) return editTarget;
+  return isRenderedElement(parent) ? parent : null;
+}
+function isRenderedElement(element) {
+  if (element.hidden) return false;
+  if (element.getClientRects().length === 0) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.display !== "none";
+}
 function tagEncodedElement(element, decoded) {
   element.setAttribute("data-prepr-encoded", "");
   element.setAttribute("data-prepr-href", decoded.href);
@@ -445,11 +459,7 @@ function createStegaAutoClean() {
       if (!decoded?.href) return false;
       cleaned.set(textNode, { original: textContent, cleaned: stripped });
       textNode.textContent = stripped;
-      let target = textNode.parentElement;
-      const editTargetParent = textNode.parentElement?.closest(
-        "[data-prepr-edit-target]"
-      );
-      if (editTargetParent) target = editTargetParent;
+      const target = resolveEditTarget(textNode);
       if (target) {
         tagEncodedElement(target, decoded);
         return true;
@@ -545,7 +555,7 @@ var StegaElements = class {
   tagFromTextNode(node) {
     const decoded = this.decode(node.textContent);
     if (!decoded?.href) return false;
-    const target = node.parentElement;
+    const target = resolveEditTarget(node);
     if (!target || target.hasAttribute("data-prepr-encoded")) return false;
     tagEncodedElement(target, decoded);
     return true;

package/dist/index.d.cts

@@ -5,7 +5,7 @@ export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.2";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { g as PreprEnvironment, h as PreprEventType, i as PreprFeatureConfig, j
  * Package version; must match package.json. Lives in its own leaf module so
  * core can import it without cycling through the barrel.
  */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.2";
 
 /**
  * Resolve a `PreprFeatures` bag to plain booleans, defaulting every omitted key

package/dist/index.js

@@ -17,10 +17,10 @@ import {
   setTrackingParam,
   stegaClean,
   trackEvent
-} from "./chunk-4PJK6IQ4.js";
+} from "./chunk-GIEOTQD4.js";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/server.ts
 var PreprError = class extends Error {

package/dist/nextjs/components.cjs

@@ -396,6 +396,20 @@ function walkTextNodes(root, visit) {
     visit(node);
   }
 }
+function resolveEditTarget(node) {
+  const parent = node.parentElement;
+  if (!parent) return null;
+  const editTarget = parent.closest("[data-prepr-edit-target]");
+  if (editTarget) return editTarget;
+  return isRenderedElement(parent) ? parent : null;
+}
+function isRenderedElement(element) {
+  if (element.hidden) return false;
+  if (element.getClientRects().length === 0) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.display !== "none";
+}
 function tagEncodedElement(element, decoded) {
   element.setAttribute("data-prepr-encoded", "");
   element.setAttribute("data-prepr-href", decoded.href);
@@ -421,11 +435,7 @@ function createStegaAutoClean() {
       if (!decoded?.href) return false;
       cleaned.set(textNode, { original: textContent, cleaned: stripped });
       textNode.textContent = stripped;
-      let target = textNode.parentElement;
-      const editTargetParent = textNode.parentElement?.closest(
-        "[data-prepr-edit-target]"
-      );
-      if (editTargetParent) target = editTargetParent;
+      const target = resolveEditTarget(textNode);
       if (target) {
         tagEncodedElement(target, decoded);
         return true;
@@ -521,7 +531,7 @@ var StegaElements = class {
   tagFromTextNode(node) {
     const decoded = this.decode(node.textContent);
     if (!decoded?.href) return false;
-    const target = node.parentElement;
+    const target = resolveEditTarget(node);
     if (!target || target.hasAttribute("data-prepr-encoded")) return false;
     tagEncodedElement(target, decoded);
     return true;

package/dist/nextjs/components.js

@@ -2,7 +2,7 @@
 import {
   createPreprPreview,
   loadTrackingPixel
-} from "../chunk-4PJK6IQ4.js";
+} from "../chunk-GIEOTQD4.js";
 
 // src/nextjs/components.ts
 import { usePathname, useRouter } from "next/navigation";

package/dist/nextjs/index.cjs

@@ -38,7 +38,7 @@ module.exports = __toCommonJS(nextjs_exports);
 var import_server = require("next/server");
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nextjs/index.js

@@ -2,7 +2,7 @@
 import { NextResponse } from "next/server";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nuxt/index.cjs

@@ -35,7 +35,7 @@ __export(nuxt_exports, {
 module.exports = __toCommonJS(nuxt_exports);
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/nuxt/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/react/components.cjs

@@ -395,6 +395,20 @@ function walkTextNodes(root, visit) {
     visit(node);
   }
 }
+function resolveEditTarget(node) {
+  const parent = node.parentElement;
+  if (!parent) return null;
+  const editTarget = parent.closest("[data-prepr-edit-target]");
+  if (editTarget) return editTarget;
+  return isRenderedElement(parent) ? parent : null;
+}
+function isRenderedElement(element) {
+  if (element.hidden) return false;
+  if (element.getClientRects().length === 0) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.display !== "none";
+}
 function tagEncodedElement(element, decoded) {
   element.setAttribute("data-prepr-encoded", "");
   element.setAttribute("data-prepr-href", decoded.href);
@@ -420,11 +434,7 @@ function createStegaAutoClean() {
       if (!decoded?.href) return false;
       cleaned.set(textNode, { original: textContent, cleaned: stripped });
       textNode.textContent = stripped;
-      let target = textNode.parentElement;
-      const editTargetParent = textNode.parentElement?.closest(
-        "[data-prepr-edit-target]"
-      );
-      if (editTargetParent) target = editTargetParent;
+      const target = resolveEditTarget(textNode);
       if (target) {
         tagEncodedElement(target, decoded);
         return true;
@@ -520,7 +530,7 @@ var StegaElements = class {
   tagFromTextNode(node) {
     const decoded = this.decode(node.textContent);
     if (!decoded?.href) return false;
-    const target = node.parentElement;
+    const target = resolveEditTarget(node);
     if (!target || target.hasAttribute("data-prepr-encoded")) return false;
     tagEncodedElement(target, decoded);
     return true;

package/dist/react/components.js

@@ -371,6 +371,20 @@ function walkTextNodes(root, visit) {
     visit(node);
   }
 }
+function resolveEditTarget(node) {
+  const parent = node.parentElement;
+  if (!parent) return null;
+  const editTarget = parent.closest("[data-prepr-edit-target]");
+  if (editTarget) return editTarget;
+  return isRenderedElement(parent) ? parent : null;
+}
+function isRenderedElement(element) {
+  if (element.hidden) return false;
+  if (element.getClientRects().length === 0) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.display !== "none";
+}
 function tagEncodedElement(element, decoded) {
   element.setAttribute("data-prepr-encoded", "");
   element.setAttribute("data-prepr-href", decoded.href);
@@ -396,11 +410,7 @@ function createStegaAutoClean() {
       if (!decoded?.href) return false;
       cleaned.set(textNode, { original: textContent, cleaned: stripped });
       textNode.textContent = stripped;
-      let target = textNode.parentElement;
-      const editTargetParent = textNode.parentElement?.closest(
-        "[data-prepr-edit-target]"
-      );
-      if (editTargetParent) target = editTargetParent;
+      const target = resolveEditTarget(textNode);
       if (target) {
         tagEncodedElement(target, decoded);
         return true;
@@ -496,7 +506,7 @@ var StegaElements = class {
   tagFromTextNode(node) {
     const decoded = this.decode(node.textContent);
     if (!decoded?.href) return false;
-    const target = node.parentElement;
+    const target = resolveEditTarget(node);
     if (!target || target.hasAttribute("data-prepr-encoded")) return false;
     tagEncodedElement(target, decoded);
     return true;

package/dist/sveltekit/index.cjs

@@ -35,7 +35,7 @@ __export(sveltekit_exports, {
 module.exports = __toCommonJS(sveltekit_exports);
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/dist/sveltekit/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.2";
 
 // src/core/constants.ts
 var COOKIE_PREVIEW_MODE = "Prepr-Preview-Mode";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preprio/toolkit",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Prepr personalization, A/B testing and preview toolkit for React, Next.js, Nuxt, Astro, SvelteKit and Express",
   "license": "Apache-2.0",
   "author": "Prepr B.V. (https://prepr.io)",