@delmaredigital/payload-puck 0.6.24 → 0.6.26

package/dist/admin/PuckEditorView.d.ts

@@ -1,4 +1,5 @@
 import type { Config as PuckConfig, Data, Plugin as PuckPlugin } from '@puckeditor/core';
+import type { RootPropsMapping } from '../api/types.js';
 /**
  * Props for the PuckEditorView component
  */
@@ -52,6 +53,14 @@ export interface PuckEditorViewProps {
      * Callback on save error
      */
     onSaveError?: (error: Error) => void;
+    /**
+     * Custom root.props ↔ Payload field mappings, merged with the defaults.
+     *
+     * Must match the `rootPropsMapping` passed to the API routes / plugin so the
+     * editor hydrates the same fields it persists on save — otherwise
+     * custom-mapped fields appear to revert after publish.
+     */
+    rootPropsMapping?: RootPropsMapping[];
 }
 /**
  * Ready-to-use Puck editor page component
@@ -80,5 +89,5 @@ export interface PuckEditorViewProps {
  * }
  * ```
  */
-export declare function PuckEditorView({ config, collectionSlug, apiBasePath, backUrl, previewUrl, layoutStyles, layoutKey, plugins, onSaveSuccess, onSaveError, }: PuckEditorViewProps): import("react").JSX.Element;
+export declare function PuckEditorView({ config, collectionSlug, apiBasePath, backUrl, previewUrl, layoutStyles, layoutKey, plugins, onSaveSuccess, onSaveError, rootPropsMapping, }: PuckEditorViewProps): import("react").JSX.Element;
 export default PuckEditorView;

package/dist/admin/PuckEditorView.js

@@ -29,7 +29,7 @@ import { mapPayloadFieldsToRootProps } from '../api/utils/mapRootProps.js';
  *   )
  * }
  * ```
- */ export function PuckEditorView({ config, collectionSlug = 'pages', apiBasePath = '/api/puck', backUrl, previewUrl, layoutStyles, layoutKey = 'pageLayout', plugins, onSaveSuccess, onSaveError }) {
+ */ export function PuckEditorView({ config, collectionSlug = 'pages', apiBasePath = '/api/puck', backUrl, previewUrl, layoutStyles, layoutKey = 'pageLayout', plugins, onSaveSuccess, onSaveError, rootPropsMapping }) {
     const params = useParams();
     const searchParams = useSearchParams();
     // Get page ID from route params or search params
@@ -203,7 +203,7 @@ import { mapPayloadFieldsToRootProps } from '../api/utils/mapRootProps.js';
     // Hydrate root.props from Payload fields — ensures saved values like pageLayout,
     // isHomepage, conversion settings etc. are reflected in the editor UI even if
     // they weren't stored in puckData (Puck may strip props that match defaults)
-    const payloadRootProps = mapPayloadFieldsToRootProps(page);
+    const payloadRootProps = mapPayloadFieldsToRootProps(page, rootPropsMapping);
     const initialData = {
         ...basePuckData,
         root: {

package/dist/endpoints/index.d.ts

@@ -8,8 +8,15 @@
  * Payload's local API, so collection-level access rules are enforced.
  */
 import type { PayloadHandler } from 'payload';
+import type { RootPropsMapping } from '../api/types.js';
 export interface PuckEndpointOptions {
     collections: string[];
+    /**
+     * Custom root.props → Payload field mappings, merged with the defaults.
+     * Lets fields edited via Puck root fields (e.g. conversionTracking) sync
+     * back to their Payload columns on save/publish.
+     */
+    rootPropsMapping?: RootPropsMapping[];
 }
 /**
  * GET /api/puck/:collection

package/dist/endpoints/index.js

@@ -9,6 +9,25 @@
  */ import { APIError } from 'payload';
 import { unsetHomepage, HomepageConflictError } from '../plugin/hooks/isHomepageUnique.js';
 import { resolveLocale } from '../utils/locale.js';
+import { mapRootPropsToPayloadFields, deepMerge } from '../api/utils/mapRootProps.js';
+/**
+ * Merge a Puck save payload's `data` with the Payload fields derived from its
+ * `puckData.root.props`.
+ *
+ * Mapped fields form the base; the explicitly-sent fields (puckData, title,
+ * slug, isHomepage, folder, pageSegment) take precedence. Without this, fields
+ * exposed as Puck root fields (e.g. conversionTracking, meta, pageLayout) are
+ * persisted only inside the puckData blob and never reach their Payload
+ * columns — so they appear to "revert" on publish. Mirrors the sync performed
+ * by createPuckApiRoutesWithId's PATCH handler.
+ */ function applyRootPropsMapping(data, rootPropsMapping) {
+    const rootProps = data?.puckData?.root?.props || {};
+    const mappedFields = mapRootPropsToPayloadFields(rootProps, rootPropsMapping);
+    const merged = {};
+    deepMerge(merged, mappedFields);
+    deepMerge(merged, data);
+    return merged;
+}
 /**
  * GET /api/puck/:collection
  * List all documents in a Puck-enabled collection
@@ -51,7 +70,7 @@ import { resolveLocale } from '../utils/locale.js';
  * POST /api/puck/:collection
  * Create a new document in a Puck-enabled collection
  */ export function createCreateHandler(options) {
-    const { collections } = options;
+    const { collections, rootPropsMapping } = options;
     return async (req)=>{
         try {
             const collection = req.routeParams?.collection;
@@ -65,11 +84,12 @@ import { resolveLocale } from '../utils/locale.js';
             const body = await req.json?.();
             const { _locale, ...data } = body || {};
             const locale = resolveLocale(req, _locale);
+            const createData = applyRootPropsMapping(data, rootPropsMapping);
             const doc = await req.payload.create({
                 collection: collection,
                 req,
                 overrideAccess: false,
-                data,
+                data: createData,
                 draft: true,
                 ...locale ? {
                     locale
@@ -133,7 +153,7 @@ import { resolveLocale } from '../utils/locale.js';
  * PATCH /api/puck/:collection/:id
  * Update a document (supports draft saving, publishing, and homepage swapping)
  */ export function createUpdateHandler(options) {
-    const { collections } = options;
+    const { collections, rootPropsMapping } = options;
     return async (req)=>{
         try {
             const collection = req.routeParams?.collection;
@@ -150,10 +170,17 @@ import { resolveLocale } from '../utils/locale.js';
             const locale = resolveLocale(req, _locale);
             // Determine if this is a publish or draft save
             const shouldPublish = _status === 'published';
+            // Sync Puck root.props → Payload fields (e.g. conversionTracking, meta,
+            // pageLayout) so values edited via Puck root fields persist to their
+            // columns on publish instead of living only inside the puckData blob.
+            const updateData = applyRootPropsMapping(data, rootPropsMapping);
+            updateData._status = shouldPublish ? 'published' : 'draft';
             // Handle homepage swap if requested
             // When swapHomepage is true and isHomepage is being set to true,
-            // we need to unset the current homepage first
-            if (swapHomepage && data.isHomepage === true) {
+            // we need to unset the current homepage first. Read the resolved value
+            // from updateData so this works whether isHomepage arrived as a top-level
+            // field or was mapped in from root.props.
+            if (swapHomepage && updateData.isHomepage === true) {
                 // Find the current homepage
                 const existingHomepage = await req.payload.find({
                     collection: collection,
@@ -190,10 +217,7 @@ import { resolveLocale } from '../utils/locale.js';
                 req,
                 overrideAccess: false,
                 id,
-                data: {
-                    ...data,
-                    _status: shouldPublish ? 'published' : 'draft'
-                },
+                data: updateData,
                 draft: !shouldPublish,
                 context: {
                     // Skip the isHomepage hook if we've already handled the swap

package/dist/plugin/index.js

@@ -105,7 +105,7 @@ import { createContextListHandler, createContextCreateHandler, createContextUpda
  * })
  * ```
  */ export function createPuckPlugin(options = {}) {
-    const { pagesCollection = 'pages', autoGenerateCollection = true, admin: pluginAdminConfig = {}, enableAdminView = true, adminViewPath = '/puck-editor', enableEndpoints = true, pageTreeIntegration, editorStylesheet, editorStylesheetUrls = [], editorStylesheetCompiled, ai: aiConfig, previewUrl } = options;
+    const { pagesCollection = 'pages', autoGenerateCollection = true, admin: pluginAdminConfig = {}, enableAdminView = true, adminViewPath = '/puck-editor', enableEndpoints = true, pageTreeIntegration, editorStylesheet, editorStylesheetUrls = [], editorStylesheetCompiled, ai: aiConfig, previewUrl, rootPropsMapping } = options;
     const { addEditButton = true } = pluginAdminConfig;
     // Parse page-tree integration config
     // - undefined: auto-detect at runtime (null stored, view will check for pageSegment field)
@@ -264,7 +264,8 @@ import { createContextListHandler, createContextCreateHandler, createContextUpda
             pagesCollection
         ];
         const endpointOptions = {
-            collections: puckCollections
+            collections: puckCollections,
+            rootPropsMapping
         };
         // Parameterized endpoint paths that should only exist once (with merged collections)
         const parameterizedPuckPaths = new Set([
@@ -411,6 +412,10 @@ import { createContextListHandler, createContextCreateHandler, createContextUpda
                     pageTree: pageTreeConfig ?? incomingConfig.custom?.puck?.pageTree,
                     editorStylesheets: editorStylesheets.length > 0 ? editorStylesheets : incomingConfig.custom?.puck?.editorStylesheets,
                     previewUrl: previewUrl ?? incomingConfig.custom?.puck?.previewUrl,
+                    // Custom root.props ↔ Payload field mappings. Stored so the editor
+                    // load view can hydrate root.props from the same mappings the save
+                    // endpoints use, keeping the round-trip symmetric for custom fields.
+                    rootPropsMapping: rootPropsMapping ?? incomingConfig.custom?.puck?.rootPropsMapping,
                     ai: aiConfig?.enabled ? {
                         enabled: true,
                         context: aiConfig.context,

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ import type { Config as PuckConfig, Data as PuckData } from '@puckeditor/core';
 import type { ThemeConfig } from '../theme/types.js';
 import type { LayoutDefinition } from '../layouts/types.js';
 import type { PuckPluginAiConfig } from '../ai/types.js';
+import type { RootPropsMapping } from '../api/types.js';
 /**
  * Admin UI configuration for the Puck plugin
  */
@@ -96,6 +97,16 @@ export interface PuckPluginOptions {
      * @default true
      */
     enableEndpoints?: boolean;
+    /**
+     * Custom mappings from Puck `root.props` to Payload collection fields.
+     *
+     * Merged with the built-in defaults (title, slug, meta.*, pageLayout,
+     * conversionTracking.*, etc.). Applied in both directions: Payload field →
+     * root.prop when loading the editor, and root.prop → Payload field when
+     * saving/publishing, so values edited via Puck root fields persist to their
+     * columns instead of living only inside the puckData blob.
+     */
+    rootPropsMapping?: RootPropsMapping[];
     /**
      * Integration with @delmaredigital/payload-page-tree plugin
      *

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.24";
+export declare const VERSION = "0.6.26";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.js - do not edit manually
-export const VERSION = '0.6.24';
+export const VERSION = '0.6.26';

package/dist/views/PuckEditorView.js

@@ -63,6 +63,7 @@ import { mapPayloadFieldsToRootProps } from '../api/utils/mapRootProps.js';
     const aiConfig = payload.config.custom?.puck?.ai;
     const editorStylesheets = payload.config.custom?.puck?.editorStylesheets;
     const previewUrlConfig = payload.config.custom?.puck?.previewUrl;
+    const rootPropsMapping = payload.config.custom?.puck?.rootPropsMapping;
     // Fetch the page data
     // Use depth: 1 if previewUrl is a function (may need relationship data like organization)
     let page = null;
@@ -163,8 +164,10 @@ import { mapPayloadFieldsToRootProps } from '../api/utils/mapRootProps.js';
     };
     if (page) {
         // Map Payload document fields to root.props format
-        // This ensures fields like title, slug, isHomepage, pageLayout are synced
-        const syncedRootProps = mapPayloadFieldsToRootProps(page);
+        // This ensures fields like title, slug, isHomepage, pageLayout are synced.
+        // Pass the configured custom mappings so the load direction mirrors the
+        // save endpoints (otherwise custom-mapped fields would appear to revert).
+        const syncedRootProps = mapPayloadFieldsToRootProps(page, rootPropsMapping);
         // Handle folder ID specially (could be object or string)
         if (pageTreeConfig && page.folder !== undefined) {
             const folderId = typeof page.folder === 'object' ? page.folder?.id : page.folder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-puck",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "description": "Puck visual page builder plugin for Payload CMS",
   "type": "module",
   "license": "MIT",
@@ -152,9 +152,9 @@
     }
   },
   "dependencies": {
-    "@puckeditor/cloud-client": "^0.6.0",
-    "@puckeditor/plugin-ai": "^0.6.0",
-    "@puckeditor/plugin-heading-analyzer": "^0.21.1",
+    "@puckeditor/cloud-client": "^0.7.0",
+    "@puckeditor/plugin-ai": "^0.7.0",
+    "@puckeditor/plugin-heading-analyzer": "^0.21.2",
     "@radix-ui/react-popover": "^1.1.15",
     "@tiptap/core": "^3.20.1",
     "@tiptap/extension-color": "^3.20.1",
@@ -171,9 +171,9 @@
     "lucide-react": "^0.469.0"
   },
   "devDependencies": {
-    "@payloadcms/next": "^3.79.0",
-    "@payloadcms/ui": "^3.79.0",
-    "@puckeditor/core": "^0.21.1",
+    "@payloadcms/next": "^3.84.1",
+    "@payloadcms/ui": "^3.84.1",
+    "@puckeditor/core": "^0.21.2",
     "@swc/cli": "^0.6.0",
     "@swc/core": "^1.15.18",
     "@types/node": "^24.12.0",
@@ -181,7 +181,7 @@
     "@types/react-dom": "^19.2.3",
     "copyfiles": "^2.4.1",
     "next": "^16.2.6",
-    "payload": "^3.79.0",
+    "payload": "^3.84.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "typescript": "^5.9.3"