@delmaredigital/payload-puck 0.1.0

package/dist/types-D7D3rZ1J.d.mts

@@ -0,0 +1,116 @@
+import { CSSProperties, ReactNode, ComponentType } from 'react';
+
+/**
+ * Layout System Types
+ *
+ * Defines the structure for page layouts that affect how content is rendered.
+ */
+
+/**
+ * A layout option shown in the Puck editor's layout selector
+ */
+interface LayoutOption {
+    /** Unique identifier for the layout */
+    value: string;
+    /** Display name in the editor */
+    label: string;
+    /** Optional description shown in the editor */
+    description?: string;
+}
+/**
+ * CSS class configuration for a layout
+ */
+interface LayoutClasses {
+    /** Classes applied to the outermost wrapper */
+    wrapper?: string;
+    /** Classes applied to the main content container */
+    container?: string;
+    /** Classes applied to the content area */
+    content?: string;
+}
+/**
+ * Style configuration for a layout
+ */
+interface LayoutStyles {
+    /** Styles applied to the outermost wrapper */
+    wrapper?: CSSProperties;
+    /** Styles applied to the main content container */
+    container?: CSSProperties;
+    /** Styles applied to the content area */
+    content?: CSSProperties;
+}
+/**
+ * Complete layout definition
+ */
+interface LayoutDefinition extends LayoutOption {
+    /** CSS classes to apply */
+    classes?: LayoutClasses;
+    /** Inline styles to apply */
+    styles?: LayoutStyles;
+    /** Custom wrapper component (overrides default rendering) */
+    wrapper?: React.ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Max width constraint (e.g., '1200px', '100%') */
+    maxWidth?: string;
+    /** Whether the layout uses full viewport width */
+    fullWidth?: boolean;
+    /** Additional data attributes to add */
+    dataAttributes?: Record<string, string>;
+    /**
+     * Header component to render above the page content.
+     * Shown in both the editor preview and the rendered page.
+     */
+    header?: ComponentType;
+    /**
+     * Footer component to render below the page content.
+     * Shown in both the editor preview and the rendered page.
+     */
+    footer?: ComponentType;
+    /**
+     * Background color/gradient for the editor preview.
+     * Applied to the iframe body in the Puck editor.
+     * @default '#ffffff'
+     */
+    editorBackground?: string;
+    /**
+     * Whether this layout uses dark mode styling in the editor preview.
+     * Controls text color and theme class on the iframe.
+     * @default false
+     */
+    editorDarkMode?: boolean;
+    /**
+     * Height of a sticky/fixed header in pixels.
+     * Used to add padding-top to the content area in the editor preview
+     * so content doesn't render behind the header.
+     * @example 64 // for a 64px tall sticky header
+     */
+    stickyHeaderHeight?: number;
+    /**
+     * Whether to push the footer to the bottom of the viewport.
+     * Uses flexbox to ensure the footer stays at the bottom even when
+     * page content is minimal. Set to `false` to allow footer to flow
+     * naturally after content.
+     * @default true
+     */
+    stickyFooter?: boolean;
+}
+/**
+ * Layout configuration passed to the plugin/renderer
+ */
+interface LayoutConfig {
+    /** Available layouts */
+    layouts: LayoutDefinition[];
+    /** Default layout value to use */
+    defaultLayout?: string;
+}
+/**
+ * Props passed to a custom layout wrapper component
+ */
+interface LayoutWrapperProps {
+    children: ReactNode;
+    layout: LayoutDefinition;
+    pageTitle?: string;
+}
+
+export type { LayoutDefinition as L, LayoutConfig as a, LayoutOption as b, LayoutClasses as c, LayoutStyles as d, LayoutWrapperProps as e };

package/dist/types-D7D3rZ1J.d.ts

@@ -0,0 +1,116 @@
+import { CSSProperties, ReactNode, ComponentType } from 'react';
+
+/**
+ * Layout System Types
+ *
+ * Defines the structure for page layouts that affect how content is rendered.
+ */
+
+/**
+ * A layout option shown in the Puck editor's layout selector
+ */
+interface LayoutOption {
+    /** Unique identifier for the layout */
+    value: string;
+    /** Display name in the editor */
+    label: string;
+    /** Optional description shown in the editor */
+    description?: string;
+}
+/**
+ * CSS class configuration for a layout
+ */
+interface LayoutClasses {
+    /** Classes applied to the outermost wrapper */
+    wrapper?: string;
+    /** Classes applied to the main content container */
+    container?: string;
+    /** Classes applied to the content area */
+    content?: string;
+}
+/**
+ * Style configuration for a layout
+ */
+interface LayoutStyles {
+    /** Styles applied to the outermost wrapper */
+    wrapper?: CSSProperties;
+    /** Styles applied to the main content container */
+    container?: CSSProperties;
+    /** Styles applied to the content area */
+    content?: CSSProperties;
+}
+/**
+ * Complete layout definition
+ */
+interface LayoutDefinition extends LayoutOption {
+    /** CSS classes to apply */
+    classes?: LayoutClasses;
+    /** Inline styles to apply */
+    styles?: LayoutStyles;
+    /** Custom wrapper component (overrides default rendering) */
+    wrapper?: React.ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Max width constraint (e.g., '1200px', '100%') */
+    maxWidth?: string;
+    /** Whether the layout uses full viewport width */
+    fullWidth?: boolean;
+    /** Additional data attributes to add */
+    dataAttributes?: Record<string, string>;
+    /**
+     * Header component to render above the page content.
+     * Shown in both the editor preview and the rendered page.
+     */
+    header?: ComponentType;
+    /**
+     * Footer component to render below the page content.
+     * Shown in both the editor preview and the rendered page.
+     */
+    footer?: ComponentType;
+    /**
+     * Background color/gradient for the editor preview.
+     * Applied to the iframe body in the Puck editor.
+     * @default '#ffffff'
+     */
+    editorBackground?: string;
+    /**
+     * Whether this layout uses dark mode styling in the editor preview.
+     * Controls text color and theme class on the iframe.
+     * @default false
+     */
+    editorDarkMode?: boolean;
+    /**
+     * Height of a sticky/fixed header in pixels.
+     * Used to add padding-top to the content area in the editor preview
+     * so content doesn't render behind the header.
+     * @example 64 // for a 64px tall sticky header
+     */
+    stickyHeaderHeight?: number;
+    /**
+     * Whether to push the footer to the bottom of the viewport.
+     * Uses flexbox to ensure the footer stays at the bottom even when
+     * page content is minimal. Set to `false` to allow footer to flow
+     * naturally after content.
+     * @default true
+     */
+    stickyFooter?: boolean;
+}
+/**
+ * Layout configuration passed to the plugin/renderer
+ */
+interface LayoutConfig {
+    /** Available layouts */
+    layouts: LayoutDefinition[];
+    /** Default layout value to use */
+    defaultLayout?: string;
+}
+/**
+ * Props passed to a custom layout wrapper component
+ */
+interface LayoutWrapperProps {
+    children: ReactNode;
+    layout: LayoutDefinition;
+    pageTitle?: string;
+}
+
+export type { LayoutDefinition as L, LayoutConfig as a, LayoutOption as b, LayoutClasses as c, LayoutStyles as d, LayoutWrapperProps as e };

package/dist/types-_6MvjyKv.d.mts

@@ -0,0 +1,104 @@
+/**
+ * Theme Type Definitions
+ *
+ * Defines all theme-related TypeScript interfaces for the payload-puck plugin.
+ * These types enable consuming applications to customize button variants,
+ * color presets, and other visual styles.
+ */
+/**
+ * Configuration for a single button variant
+ */
+interface ButtonVariantConfig {
+    /** Tailwind classes for the variant */
+    classes: string;
+    /** Optional CSS variable reference for dynamic theming */
+    cssVariable?: string;
+}
+/**
+ * Map of button variant names to their configurations
+ */
+interface ButtonVariantStyles {
+    default?: ButtonVariantConfig;
+    primary?: ButtonVariantConfig;
+    secondary?: ButtonVariantConfig;
+    outline?: ButtonVariantConfig;
+    ghost?: ButtonVariantConfig;
+    destructive?: ButtonVariantConfig;
+    link?: ButtonVariantConfig;
+    [key: string]: ButtonVariantConfig | undefined;
+}
+/**
+ * Color preset for the color picker
+ */
+interface ColorPreset {
+    /** Hex color value (e.g., '#3b82f6') */
+    hex: string;
+    /** Display label for the preset */
+    label: string;
+    /** Optional CSS variable reference (e.g., 'var(--color-primary)') */
+    cssVariable?: string;
+}
+/**
+ * Background style configurations for CTA components
+ */
+interface BackgroundStyles {
+    default?: string;
+    dark?: string;
+    light?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Theme configuration provided by consuming applications
+ * All properties are optional and will be merged with defaults
+ */
+interface ThemeConfig {
+    /**
+     * Button variant styles
+     * Merged with default button variants
+     */
+    buttonVariants?: Partial<ButtonVariantStyles>;
+    /**
+     * CTA button variant styles
+     * Merged with default CTA button variants
+     */
+    ctaButtonVariants?: Partial<ButtonVariantStyles>;
+    /**
+     * CTA background styles
+     * Merged with default background styles
+     */
+    ctaBackgroundStyles?: Partial<BackgroundStyles>;
+    /**
+     * Color picker preset colors
+     * If provided, replaces defaults unless extendColorPresets is true
+     */
+    colorPresets?: ColorPreset[];
+    /**
+     * Whether to extend default color presets (true) or replace them (false)
+     * @default false
+     */
+    extendColorPresets?: boolean;
+    /**
+     * Focus ring color class (e.g., 'focus:ring-primary')
+     * @default 'focus:ring-blue-500'
+     */
+    focusRingColor?: string;
+}
+/**
+ * Fully resolved theme with all defaults applied
+ * This is what components receive via useTheme()
+ */
+interface ResolvedTheme {
+    buttonVariants: ButtonVariantStyles;
+    ctaButtonVariants: ButtonVariantStyles;
+    ctaBackgroundStyles: BackgroundStyles;
+    colorPresets: ColorPreset[];
+    focusRingColor: string;
+}
+/**
+ * Theme context value provided by ThemeProvider
+ */
+interface ThemeContextValue {
+    theme: ResolvedTheme;
+}
+
+export type { ButtonVariantStyles as B, ColorPreset as C, ResolvedTheme as R, ThemeConfig as T, BackgroundStyles as a, ButtonVariantConfig as b, ThemeContextValue as c };

package/dist/types-_6MvjyKv.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Theme Type Definitions
+ *
+ * Defines all theme-related TypeScript interfaces for the payload-puck plugin.
+ * These types enable consuming applications to customize button variants,
+ * color presets, and other visual styles.
+ */
+/**
+ * Configuration for a single button variant
+ */
+interface ButtonVariantConfig {
+    /** Tailwind classes for the variant */
+    classes: string;
+    /** Optional CSS variable reference for dynamic theming */
+    cssVariable?: string;
+}
+/**
+ * Map of button variant names to their configurations
+ */
+interface ButtonVariantStyles {
+    default?: ButtonVariantConfig;
+    primary?: ButtonVariantConfig;
+    secondary?: ButtonVariantConfig;
+    outline?: ButtonVariantConfig;
+    ghost?: ButtonVariantConfig;
+    destructive?: ButtonVariantConfig;
+    link?: ButtonVariantConfig;
+    [key: string]: ButtonVariantConfig | undefined;
+}
+/**
+ * Color preset for the color picker
+ */
+interface ColorPreset {
+    /** Hex color value (e.g., '#3b82f6') */
+    hex: string;
+    /** Display label for the preset */
+    label: string;
+    /** Optional CSS variable reference (e.g., 'var(--color-primary)') */
+    cssVariable?: string;
+}
+/**
+ * Background style configurations for CTA components
+ */
+interface BackgroundStyles {
+    default?: string;
+    dark?: string;
+    light?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Theme configuration provided by consuming applications
+ * All properties are optional and will be merged with defaults
+ */
+interface ThemeConfig {
+    /**
+     * Button variant styles
+     * Merged with default button variants
+     */
+    buttonVariants?: Partial<ButtonVariantStyles>;
+    /**
+     * CTA button variant styles
+     * Merged with default CTA button variants
+     */
+    ctaButtonVariants?: Partial<ButtonVariantStyles>;
+    /**
+     * CTA background styles
+     * Merged with default background styles
+     */
+    ctaBackgroundStyles?: Partial<BackgroundStyles>;
+    /**
+     * Color picker preset colors
+     * If provided, replaces defaults unless extendColorPresets is true
+     */
+    colorPresets?: ColorPreset[];
+    /**
+     * Whether to extend default color presets (true) or replace them (false)
+     * @default false
+     */
+    extendColorPresets?: boolean;
+    /**
+     * Focus ring color class (e.g., 'focus:ring-primary')
+     * @default 'focus:ring-blue-500'
+     */
+    focusRingColor?: string;
+}
+/**
+ * Fully resolved theme with all defaults applied
+ * This is what components receive via useTheme()
+ */
+interface ResolvedTheme {
+    buttonVariants: ButtonVariantStyles;
+    ctaButtonVariants: ButtonVariantStyles;
+    ctaBackgroundStyles: BackgroundStyles;
+    colorPresets: ColorPreset[];
+    focusRingColor: string;
+}
+/**
+ * Theme context value provided by ThemeProvider
+ */
+interface ThemeContextValue {
+    theme: ResolvedTheme;
+}
+
+export type { ButtonVariantStyles as B, ColorPreset as C, ResolvedTheme as R, ThemeConfig as T, BackgroundStyles as a, ButtonVariantConfig as b, ThemeContextValue as c };

package/dist/utils/index.d.mts

@@ -0,0 +1,267 @@
+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.
+ */
+
+/**
+ * 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 };