@delmaredigital/payload-puck 0.1.3 → 0.3.0

package/dist/utils/index.js

@@ -1,426 +1,57 @@
-'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
+/**
+ * Migration and Validation Utilities
+ *
+ * This module provides utilities for migrating legacy Payload CMS pages
+ * to Puck format and validating Puck data structures.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   migrateLegacyToPuck,
+ *   validatePuckData,
+ *   getMigrationPreview,
+ *   blockTypeMap,
+ * } from '@delmaredigital/payload-puck/utils'
+ *
+ * // Preview migration
+ * const preview = getMigrationPreview(legacyPage)
+ * console.log('Blocks to migrate:', preview.blockCount)
+ * console.log('Warnings:', preview.warnings)
+ *
+ * // Perform migration
+ * const puckData = migrateLegacyToPuck(legacyPage)
+ *
+ * // Validate result
+ * const validation = validatePuckData(puckData)
+ * if (validation.valid) {
+ *   await payload.update({ collection: 'pages', id: pageId, data: { puckData } })
+ * }
+ * ```
+ */
+// =============================================================================
+// Migration Exports
+// =============================================================================
+export { 
+// Main migration function
+migrateLegacyToPuck, 
+// Preview function
+getMigrationPreview, 
+// Block type mapping
+blockTypeMap, 
+// ID generation
+generatePuckId, 
+// Prop transformation utilities
+transformBlockProps, transformMediaReference, transformRichText, transformRelationshipArray, } from './migration';
+// =============================================================================
+// Validation Exports
+// =============================================================================
+export { 
+// Main validation function
+validatePuckData, 
+// Type guards
+isPuckData, isPuckRootProps, 
+// Assertion helper
+assertPuckData, 
+// JSON parsing helper
+parsePuckDataJson, } from './validation';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO;AACL,0BAA0B;AAC1B,mBAAmB;AACnB,mBAAmB;AACnB,mBAAmB;AACnB,qBAAqB;AACrB,YAAY;AACZ,gBAAgB;AAChB,cAAc;AACd,gCAAgC;AAChC,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,GAQ3B,MAAM,aAAa,CAAA;AAEpB,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,OAAO;AACL,2BAA2B;AAC3B,gBAAgB;AAChB,cAAc;AACd,UAAU,EACV,eAAe;AACf,mBAAmB;AACnB,cAAc;AACd,sBAAsB;AACtB,iBAAiB,GAIlB,MAAM,cAAc,CAAA"}

package/dist/utils/{index.d.mts → migration.d.ts}

@@ -1,21 +1,15 @@
-import { P as PuckPageData, M as MediaObject, a as PuckRootProps } from '../index-CQu6SzDg.mjs';
-import 'payload';
-import '@measured/puck';
-import '../types-D7D3rZ1J.mjs';
-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.
  */
-
+import type { PuckPageData, MediaObject } from '../types';
 /**
  * Legacy block from Payload CMS pages.
  * Each block has a blockType discriminator and various props.
  */
-interface LegacyBlock {
+export interface LegacyBlock {
     blockType: string;
     id?: string | null;
     blockName?: string | null;
@@ -25,7 +19,7 @@ interface LegacyBlock {
  * Subset of Page type used for migration.
  * Only includes fields relevant to content migration.
  */
-interface LegacyPage {
+export interface LegacyPage {
     title: string;
     slug: string;
     pageLayout?: string;
@@ -35,7 +29,7 @@ interface LegacyPage {
 /**
  * Media reference in Puck format
  */
-interface MediaReference {
+export interface MediaReference {
     id: string | number;
     url?: string;
     alt?: string;
@@ -45,7 +39,7 @@ interface MediaReference {
 /**
  * Puck content item structure
  */
-interface PuckContentItem {
+export interface PuckContentItem {
     type: string;
     props: {
         id: string;
@@ -56,17 +50,17 @@ interface PuckContentItem {
  * 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>;
+export 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;
+export 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 | {
+export declare function transformMediaReference(media: string | number | {
     id: string | number;
     url?: string;
     alt?: string;
@@ -77,11 +71,11 @@ declare function transformMediaReference(media: string | number | {
  * 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;
+export declare function transformRichText(richText: unknown): string | undefined;
 /**
  * Transforms an array of relationships to Puck format.
  */
-declare function transformRelationshipArray<T extends {
+export declare function transformRelationshipArray<T extends {
     id: string | number;
     title?: string;
     slug?: string;
@@ -94,7 +88,7 @@ declare function transformRelationshipArray<T extends {
  * Transform props for a specific block type.
  * Handles any block-specific transformations needed.
  */
-declare function transformBlockProps(block: LegacyBlock, options?: {
+export declare function transformBlockProps(block: LegacyBlock, options?: {
     richTextFields?: string[];
     mediaFields?: string[];
     customTransformers?: Record<string, (value: unknown) => unknown>;
@@ -102,7 +96,7 @@ declare function transformBlockProps(block: LegacyBlock, options?: {
 /**
  * Options for the migration function
  */
-interface MigrateLegacyOptions {
+export interface MigrateLegacyOptions {
     /**
      * Custom block type mapping to extend or override defaults
      */
@@ -153,11 +147,11 @@ interface MigrateLegacyOptions {
  * })
  * ```
  */
-declare function migrateLegacyToPuck(page: LegacyPage, options?: MigrateLegacyOptions): PuckPageData;
+export declare function migrateLegacyToPuck(page: LegacyPage, options?: MigrateLegacyOptions): PuckPageData;
 /**
  * Migration preview result
  */
-interface MigrationPreview {
+export interface MigrationPreview {
     title: string;
     slug: string;
     blockCount: number;
@@ -173,95 +167,5 @@ interface MigrationPreview {
  * @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 };
+export declare function getMigrationPreview(page: LegacyPage, customBlockTypeMap?: Record<string, string>): MigrationPreview;
+//# sourceMappingURL=migration.d.ts.map