@delmaredigital/payload-puck 0.1.0

package/dist/utils/index.d.ts

@@ -0,0 +1,267 @@
+import { P as PuckPageData, M as MediaObject, a as PuckRootProps } from '../index-CoUQnyC3.js';
+import 'payload';
+import '@measured/puck';
+import '../types-D7D3rZ1J.js';
+import 'react';
+
+/**
+ * Migration Utility for Converting Legacy Payload CMS Pages to Puck Format
+ *
+ * This utility converts legacy Payload CMS page block structures to the
+ * Puck visual editor format, enabling seamless migration of existing content.
+ */
+
+/**
+ * Legacy block from Payload CMS pages.
+ * Each block has a blockType discriminator and various props.
+ */
+interface LegacyBlock {
+    blockType: string;
+    id?: string | null;
+    blockName?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Subset of Page type used for migration.
+ * Only includes fields relevant to content migration.
+ */
+interface LegacyPage {
+    title: string;
+    slug: string;
+    pageLayout?: string;
+    layout?: LegacyBlock[] | null;
+    [key: string]: unknown;
+}
+/**
+ * Media reference in Puck format
+ */
+interface MediaReference {
+    id: string | number;
+    url?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Puck content item structure
+ */
+interface PuckContentItem {
+    type: string;
+    props: {
+        id: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Maps legacy Payload block types (camelCase) to Puck component types (PascalCase).
+ * Extend this map to support additional custom block types.
+ */
+declare const blockTypeMap: Record<string, string>;
+/**
+ * Generates a unique ID for Puck content items.
+ * Uses a format compatible with Puck's internal ID scheme.
+ */
+declare function generatePuckId(legacyId?: string | null): string;
+/**
+ * Transforms a Payload media reference (ID or Media object) to Puck MediaReference format.
+ * Handles both ID-only references and full Media objects.
+ */
+declare function transformMediaReference(media: string | number | {
+    id: string | number;
+    url?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+} | MediaObject | null | undefined): MediaReference | null;
+/**
+ * Transforms Lexical rich text content to a serialized string format.
+ * Puck stores rich text as JSON strings for the custom editors.
+ */
+declare function transformRichText(richText: unknown): string | undefined;
+/**
+ * Transforms an array of relationships to Puck format.
+ */
+declare function transformRelationshipArray<T extends {
+    id: string | number;
+    title?: string;
+    slug?: string;
+}>(relations: (string | number | T)[] | null | undefined): Array<{
+    id: string | number;
+    title: string;
+    slug?: string;
+}> | undefined;
+/**
+ * Transform props for a specific block type.
+ * Handles any block-specific transformations needed.
+ */
+declare function transformBlockProps(block: LegacyBlock, options?: {
+    richTextFields?: string[];
+    mediaFields?: string[];
+    customTransformers?: Record<string, (value: unknown) => unknown>;
+}): Record<string, unknown>;
+/**
+ * Options for the migration function
+ */
+interface MigrateLegacyOptions {
+    /**
+     * Custom block type mapping to extend or override defaults
+     */
+    blockTypeMap?: Record<string, string>;
+    /**
+     * Additional rich text field names to transform
+     */
+    richTextFields?: string[];
+    /**
+     * Additional media field names to transform
+     */
+    mediaFields?: string[];
+    /**
+     * Custom prop transformers for specific field names
+     */
+    customTransformers?: Record<string, (value: unknown) => unknown>;
+    /**
+     * Whether to skip unknown block types (default: true)
+     * If false, unknown blocks will throw an error
+     */
+    skipUnknownBlocks?: boolean;
+    /**
+     * Callback for handling unknown block types
+     */
+    onUnknownBlock?: (block: LegacyBlock) => PuckContentItem | null;
+}
+/**
+ * Migrates a legacy Payload CMS page to Puck format.
+ *
+ * This function:
+ * 1. Extracts root props (title, pageLayout, etc.)
+ * 2. Converts each block in the layout array to a Puck content item
+ * 3. Maps block types from camelCase to PascalCase using blockTypeMap
+ * 4. Transforms block props appropriately
+ *
+ * @param page - The legacy Page object from Payload CMS
+ * @param options - Migration options
+ * @returns PuckPageData ready for use with the Puck editor
+ *
+ * @example
+ * ```ts
+ * const legacyPage = await payload.findByID({ collection: 'pages', id: pageId })
+ * const puckData = migrateLegacyToPuck(legacyPage)
+ * await payload.update({
+ *   collection: 'pages',
+ *   id: pageId,
+ *   data: { puckData },
+ * })
+ * ```
+ */
+declare function migrateLegacyToPuck(page: LegacyPage, options?: MigrateLegacyOptions): PuckPageData;
+/**
+ * Migration preview result
+ */
+interface MigrationPreview {
+    title: string;
+    slug: string;
+    blockCount: number;
+    blockTypes: string[];
+    warnings: string[];
+    unmappedBlockTypes: string[];
+}
+/**
+ * Gets a summary of a legacy page for migration preview.
+ * Useful for showing users what will be migrated before committing.
+ *
+ * @param page - The legacy page to preview
+ * @param customBlockTypeMap - Optional custom block type mapping
+ * @returns Preview information about the migration
+ */
+declare function getMigrationPreview(page: LegacyPage, customBlockTypeMap?: Record<string, string>): MigrationPreview;
+
+/**
+ * Puck Data Validation Utilities
+ *
+ * Provides validation functions for ensuring Puck data structures are well-formed.
+ */
+
+/**
+ * Result of a validation operation
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Options for validation
+ */
+interface ValidationOptions {
+    /**
+     * Whether to validate that all content items have IDs
+     * @default true
+     */
+    requireContentIds?: boolean;
+    /**
+     * Whether to validate root props
+     * @default true
+     */
+    validateRoot?: boolean;
+    /**
+     * Required root prop fields
+     * @default ['title']
+     */
+    requiredRootProps?: string[];
+    /**
+     * Allowed component types (if specified, unknown types will be flagged)
+     */
+    allowedComponentTypes?: string[];
+    /**
+     * Whether to treat unknown component types as errors (vs warnings)
+     * @default false
+     */
+    strictComponentTypes?: boolean;
+}
+/**
+ * Type guard to check if a value is a valid PuckPageData structure.
+ * Performs basic structural validation.
+ */
+declare function isPuckData(data: unknown): data is PuckPageData;
+/**
+ * Type guard for PuckRootProps
+ */
+declare function isPuckRootProps(props: unknown): props is PuckRootProps;
+/**
+ * Validates that a PuckPageData structure is well-formed.
+ * Useful for testing and debugging migration issues.
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```ts
+ * const result = validatePuckData(puckData)
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors)
+ * }
+ * ```
+ */
+declare function validatePuckData(data: unknown, options?: ValidationOptions): ValidationResult;
+/**
+ * Validates and returns typed PuckPageData, throwing if invalid.
+ *
+ * @param data - The data to validate
+ * @param options - Validation options
+ * @returns The validated PuckPageData
+ * @throws Error if validation fails
+ */
+declare function assertPuckData(data: unknown, options?: ValidationOptions): PuckPageData;
+/**
+ * Safely parses JSON and validates as PuckPageData.
+ *
+ * @param json - JSON string to parse
+ * @param options - Validation options
+ * @returns Validation result with parsed data if valid
+ */
+declare function parsePuckDataJson(json: string, options?: ValidationOptions): ValidationResult & {
+    data?: PuckPageData;
+};
+
+export { type LegacyBlock, type LegacyPage, type MediaReference, type MigrateLegacyOptions, type MigrationPreview, type PuckContentItem, type ValidationOptions, type ValidationResult, assertPuckData, blockTypeMap, generatePuckId, getMigrationPreview, isPuckData, isPuckRootProps, migrateLegacyToPuck, parsePuckDataJson, transformBlockProps, transformMediaReference, transformRelationshipArray, transformRichText, validatePuckData };

package/dist/utils/index.js

@@ -0,0 +1,426 @@
+'use strict';
+
+// src/utils/migration.ts
+var blockTypeMap = {
+  heroBlock: "Hero",
+  richTextBlock: "RichText",
+  containerBlock: "Container",
+  flexBlock: "Flex",
+  gridBlock: "Grid",
+  sectionBlock: "Section",
+  spacerBlock: "Spacer",
+  headingBlock: "Heading",
+  textBlock: "Text",
+  imageBlock: "Image",
+  buttonBlock: "Button",
+  cardBlock: "Card",
+  dividerBlock: "Divider",
+  accordionBlock: "Accordion"
+};
+function generatePuckId(legacyId) {
+  if (legacyId) {
+    return legacyId;
+  }
+  return `puck-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+function transformMediaReference(media) {
+  if (media === null || media === void 0) {
+    return null;
+  }
+  if (typeof media === "number" || typeof media === "string") {
+    return { id: media };
+  }
+  return {
+    id: media.id,
+    url: media.url,
+    alt: media.alt,
+    width: media.width,
+    height: media.height
+  };
+}
+function transformRichText(richText) {
+  if (!richText) {
+    return void 0;
+  }
+  if (typeof richText === "string") {
+    return richText;
+  }
+  if (typeof richText === "object") {
+    try {
+      return JSON.stringify(richText);
+    } catch {
+      console.warn("[payload-puck] Failed to serialize rich text content");
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function transformRelationshipArray(relations) {
+  if (!relations || !Array.isArray(relations)) {
+    return void 0;
+  }
+  return relations.map((rel) => {
+    if (typeof rel === "number" || typeof rel === "string") {
+      return { id: rel, title: "" };
+    }
+    return {
+      id: rel.id,
+      title: rel.title || "",
+      slug: rel.slug
+    };
+  });
+}
+var RICH_TEXT_FIELDS = [
+  "headingRich",
+  "subheadingRich",
+  "textRich",
+  "content",
+  "leftContent",
+  "rightContent",
+  "bodyContent",
+  "description"
+];
+var MEDIA_FIELDS = [
+  "backgroundImage",
+  "image",
+  "rightImage",
+  "leftImage",
+  "profileImage",
+  "media",
+  "thumbnail",
+  "icon"
+];
+function transformBlockProps(block, options) {
+  const { blockType, id, blockName, ...restProps } = block;
+  const richTextFields = options?.richTextFields || RICH_TEXT_FIELDS;
+  const mediaFields = options?.mediaFields || MEDIA_FIELDS;
+  const customTransformers = options?.customTransformers || {};
+  const props = {
+    id: generatePuckId(id)
+  };
+  for (const [key, value] of Object.entries(restProps)) {
+    if (customTransformers[key]) {
+      props[key] = customTransformers[key](value);
+      continue;
+    }
+    if (richTextFields.includes(key)) {
+      props[key] = transformRichText(value);
+      continue;
+    }
+    if (mediaFields.includes(key)) {
+      props[key] = transformMediaReference(
+        value
+      );
+      continue;
+    }
+    if (Array.isArray(value)) {
+      props[key] = value.map((item) => {
+        if (typeof item === "object" && item !== null) {
+          const { id: itemId, ...itemRest } = item;
+          return {
+            ...itemRest,
+            id: itemId || generatePuckId()
+          };
+        }
+        return item;
+      });
+      continue;
+    }
+    props[key] = value;
+  }
+  return props;
+}
+function migrateLegacyToPuck(page, options = {}) {
+  const {
+    blockTypeMap: customBlockTypeMap,
+    richTextFields,
+    mediaFields,
+    customTransformers,
+    skipUnknownBlocks = true,
+    onUnknownBlock
+  } = options;
+  const effectiveBlockTypeMap = {
+    ...blockTypeMap,
+    ...customBlockTypeMap
+  };
+  const rootProps = {
+    title: page.title,
+    pageLayout: page.pageLayout || "default"
+  };
+  const content = [];
+  if (page.layout && Array.isArray(page.layout)) {
+    for (const block of page.layout) {
+      const legacyBlock = block;
+      const puckType = effectiveBlockTypeMap[legacyBlock.blockType];
+      if (!puckType) {
+        if (onUnknownBlock) {
+          const customItem = onUnknownBlock(legacyBlock);
+          if (customItem) {
+            content.push(customItem);
+          }
+          continue;
+        }
+        if (skipUnknownBlocks) {
+          console.warn(
+            `[payload-puck] Unknown block type "${legacyBlock.blockType}" - skipping during migration`
+          );
+          continue;
+        }
+        throw new Error(
+          `Unknown block type "${legacyBlock.blockType}" encountered during migration`
+        );
+      }
+      const transformedProps = transformBlockProps(legacyBlock, {
+        richTextFields,
+        mediaFields,
+        customTransformers
+      });
+      const contentItem = {
+        type: puckType,
+        props: transformedProps
+      };
+      content.push(contentItem);
+    }
+  }
+  const puckData = {
+    root: {
+      props: rootProps
+    },
+    content,
+    zones: {}
+  };
+  return puckData;
+}
+function getMigrationPreview(page, customBlockTypeMap) {
+  const warnings = [];
+  const blockTypes = [];
+  const unmappedBlockTypes = [];
+  const effectiveBlockTypeMap = {
+    ...blockTypeMap,
+    ...customBlockTypeMap
+  };
+  if (page.layout && Array.isArray(page.layout)) {
+    for (const block of page.layout) {
+      const legacyBlock = block;
+      const puckType = effectiveBlockTypeMap[legacyBlock.blockType];
+      if (puckType) {
+        blockTypes.push(puckType);
+      } else {
+        warnings.push(`Unknown block type: ${legacyBlock.blockType}`);
+        if (!unmappedBlockTypes.includes(legacyBlock.blockType)) {
+          unmappedBlockTypes.push(legacyBlock.blockType);
+        }
+      }
+    }
+  }
+  return {
+    title: page.title,
+    slug: page.slug,
+    blockCount: page.layout?.length || 0,
+    blockTypes,
+    warnings,
+    unmappedBlockTypes
+  };
+}
+
+// src/utils/validation.ts
+function isPuckData(data) {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+  const obj = data;
+  if (!obj.root || typeof obj.root !== "object") {
+    return false;
+  }
+  const root = obj.root;
+  if (!root.props || typeof root.props !== "object") {
+    return false;
+  }
+  if (!Array.isArray(obj.content)) {
+    return false;
+  }
+  for (const item of obj.content) {
+    if (!item || typeof item !== "object") {
+      return false;
+    }
+    const contentItem = item;
+    if (typeof contentItem.type !== "string") {
+      return false;
+    }
+    if (!contentItem.props || typeof contentItem.props !== "object") {
+      return false;
+    }
+  }
+  if (obj.zones !== void 0 && typeof obj.zones !== "object") {
+    return false;
+  }
+  return true;
+}
+function isPuckRootProps(props) {
+  if (!props || typeof props !== "object") {
+    return false;
+  }
+  return true;
+}
+function validatePuckData(data, options = {}) {
+  const {
+    requireContentIds = true,
+    validateRoot = true,
+    requiredRootProps = ["title"],
+    allowedComponentTypes,
+    strictComponentTypes = false
+  } = options;
+  const errors = [];
+  const warnings = [];
+  if (!data || typeof data !== "object") {
+    errors.push("Data must be a non-null object");
+    return { valid: false, errors, warnings };
+  }
+  const obj = data;
+  if (!obj.root || typeof obj.root !== "object") {
+    errors.push("Missing or invalid root object");
+  } else if (validateRoot) {
+    const root = obj.root;
+    if (!root.props || typeof root.props !== "object") {
+      errors.push("Missing root.props object");
+    } else {
+      const rootProps = root.props;
+      for (const prop of requiredRootProps) {
+        if (rootProps[prop] === void 0 || rootProps[prop] === null) {
+          errors.push(`Missing required root prop: ${prop}`);
+        }
+      }
+      if (rootProps.pageLayout !== void 0) {
+        if (typeof rootProps.pageLayout !== "string") {
+          errors.push("root.props.pageLayout must be a string");
+        }
+      }
+    }
+  }
+  if (!Array.isArray(obj.content)) {
+    errors.push("content must be an array");
+  } else {
+    const seenIds = /* @__PURE__ */ new Set();
+    obj.content.forEach((item, index) => {
+      if (!item || typeof item !== "object") {
+        errors.push(`Content item at index ${index} is not an object`);
+        return;
+      }
+      const contentItem = item;
+      if (!contentItem.type || typeof contentItem.type !== "string") {
+        errors.push(`Content item at index ${index} missing or invalid type`);
+      } else if (allowedComponentTypes) {
+        if (!allowedComponentTypes.includes(contentItem.type)) {
+          const message = `Unknown component type "${contentItem.type}" at index ${index}`;
+          if (strictComponentTypes) {
+            errors.push(message);
+          } else {
+            warnings.push(message);
+          }
+        }
+      }
+      if (!contentItem.props || typeof contentItem.props !== "object") {
+        errors.push(`Content item at index ${index} missing props object`);
+      } else if (requireContentIds) {
+        const props = contentItem.props;
+        if (!props.id || typeof props.id !== "string") {
+          errors.push(`Content item at index ${index} missing or invalid props.id`);
+        } else {
+          if (seenIds.has(props.id)) {
+            warnings.push(
+              `Duplicate content item ID "${props.id}" at index ${index}`
+            );
+          }
+          seenIds.add(props.id);
+        }
+      }
+    });
+  }
+  if (obj.zones !== void 0) {
+    if (typeof obj.zones !== "object" || obj.zones === null) {
+      errors.push("zones must be an object");
+    } else {
+      const zones = obj.zones;
+      for (const [zoneName, zoneContent] of Object.entries(zones)) {
+        if (!Array.isArray(zoneContent)) {
+          errors.push(`Zone "${zoneName}" content must be an array`);
+          continue;
+        }
+        zoneContent.forEach((item, index) => {
+          if (!item || typeof item !== "object") {
+            errors.push(`Zone "${zoneName}" item at index ${index} is not an object`);
+            return;
+          }
+          const contentItem = item;
+          if (!contentItem.type || typeof contentItem.type !== "string") {
+            errors.push(
+              `Zone "${zoneName}" item at index ${index} missing or invalid type`
+            );
+          }
+          if (!contentItem.props || typeof contentItem.props !== "object") {
+            errors.push(
+              `Zone "${zoneName}" item at index ${index} missing props object`
+            );
+          } else if (requireContentIds) {
+            const props = contentItem.props;
+            if (!props.id || typeof props.id !== "string") {
+              errors.push(
+                `Zone "${zoneName}" item at index ${index} missing or invalid props.id`
+              );
+            }
+          }
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function assertPuckData(data, options) {
+  const result = validatePuckData(data, options);
+  if (!result.valid) {
+    throw new Error(
+      `Invalid Puck data: ${result.errors.join("; ")}`
+    );
+  }
+  return data;
+}
+function parsePuckDataJson(json, options) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (e) {
+    return {
+      valid: false,
+      errors: [`Invalid JSON: ${e instanceof Error ? e.message : "Parse error"}`],
+      warnings: []
+    };
+  }
+  const result = validatePuckData(parsed, options);
+  if (result.valid) {
+    return {
+      ...result,
+      data: parsed
+    };
+  }
+  return result;
+}
+
+exports.assertPuckData = assertPuckData;
+exports.blockTypeMap = blockTypeMap;
+exports.generatePuckId = generatePuckId;
+exports.getMigrationPreview = getMigrationPreview;
+exports.isPuckData = isPuckData;
+exports.isPuckRootProps = isPuckRootProps;
+exports.migrateLegacyToPuck = migrateLegacyToPuck;
+exports.parsePuckDataJson = parsePuckDataJson;
+exports.transformBlockProps = transformBlockProps;
+exports.transformMediaReference = transformMediaReference;
+exports.transformRelationshipArray = transformRelationshipArray;
+exports.transformRichText = transformRichText;
+exports.validatePuckData = validatePuckData;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map