@delmaredigital/payload-puck 0.1.0

package/dist/editor/index.d.mts

@@ -0,0 +1,784 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Data, Config, Plugin, Overrides } from '@measured/puck';
+import * as React$1 from 'react';
+import { CSSProperties, ReactNode, ComponentType } from 'react';
+import { T as ThemeConfig } from '../types-_6MvjyKv.mjs';
+export { default as headingAnalyzer } from '@measured/puck-plugin-heading-analyzer';
+
+/**
+ * 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 style configuration for theme-aware preview
+ * @deprecated Use LayoutDefinition with editorBackground and editorDarkMode instead
+ */
+interface LayoutStyle {
+    /**
+     * CSS background value (color, gradient, etc.)
+     */
+    background: string;
+    /**
+     * Whether this layout uses dark mode styling
+     */
+    isDark: boolean;
+    /**
+     * Header component to render above the page content in the editor preview
+     */
+    header?: ComponentType;
+    /**
+     * Footer component to render below the page content in the editor preview
+     */
+    footer?: ComponentType;
+}
+interface IframeWrapperProps {
+    children: ReactNode;
+    /**
+     * The iframe document to apply styles to
+     */
+    document?: Document;
+    /**
+     * Layout definitions - the primary way to configure layouts.
+     * Reads header, footer, editorBackground, and editorDarkMode from each layout.
+     */
+    layouts?: LayoutDefinition[];
+    /**
+     * Layout style configurations keyed by layout value
+     * @deprecated Use `layouts` prop instead
+     */
+    layoutStyles?: Record<string, LayoutStyle>;
+    /**
+     * Key in root.props to read layout value from
+     * @default 'pageLayout'
+     */
+    layoutKey?: string;
+    /**
+     * Default layout to use if none specified
+     * @default 'default'
+     */
+    defaultLayout?: string;
+}
+/**
+ * Theme-aware iframe wrapper component
+ *
+ * Uses usePuck to read the pageLayout from root.props and applies
+ * appropriate background and theme class to the preview iframe.
+ *
+ * @example
+ * ```tsx
+ * // Using layouts (recommended)
+ * const overrides = {
+ *   iframe: ({ children, document }) => (
+ *     <IframeWrapper
+ *       document={document}
+ *       layouts={[
+ *         { value: 'default', label: 'Default', header: Header, footer: Footer },
+ *         { value: 'landing', label: 'Landing', editorBackground: '#f8fafc' },
+ *       ]}
+ *     >
+ *       {children}
+ *     </IframeWrapper>
+ *   ),
+ * }
+ * ```
+ */
+declare const IframeWrapper: React$1.NamedExoticComponent<IframeWrapperProps>;
+
+interface PuckEditorProps {
+    /**
+     * Page ID for save operations
+     */
+    pageId: string;
+    /**
+     * Initial Puck data to load
+     */
+    initialData: Data;
+    /**
+     * Puck configuration with components and settings
+     */
+    config: Config;
+    /**
+     * Page title for display
+     */
+    pageTitle: string;
+    /**
+     * Page slug for preview URL
+     */
+    pageSlug: string;
+    /**
+     * API endpoint for save operations
+     * @default '/api/puck/pages'
+     */
+    apiEndpoint?: string;
+    /**
+     * URL to navigate to when back button is clicked
+     */
+    backUrl?: string;
+    /**
+     * Preview URL or function to generate preview URL from slug
+     */
+    previewUrl?: string | ((slug: string) => string);
+    /**
+     * Whether to enable viewport switching
+     * @default true
+     */
+    enableViewports?: boolean;
+    /**
+     * Additional Puck plugins to use.
+     * The headingAnalyzer plugin is included by default.
+     * Set to `false` to disable all default plugins.
+     */
+    plugins?: Plugin[] | false;
+    /**
+     * Layout definitions for the editor preview.
+     * The editor reads header, footer, editorBackground, and editorDarkMode
+     * from the layout definition matching the selected pageLayout.
+     */
+    layouts?: LayoutDefinition[];
+    /**
+     * Layout style configurations for theme-aware preview
+     * @deprecated Use `layouts` prop instead. layoutStyles will be removed in a future version.
+     */
+    layoutStyles?: Record<string, LayoutStyle>;
+    /**
+     * Key in root.props to read layout value from
+     * @default 'pageLayout'
+     */
+    layoutKey?: string;
+    /**
+     * Custom actions to render at the start of the header
+     */
+    headerActionsStart?: ReactNode;
+    /**
+     * Custom actions to render at the end of the header
+     */
+    headerActionsEnd?: ReactNode;
+    /**
+     * Puck overrides to merge with defaults
+     */
+    overrides?: Partial<Overrides>;
+    /**
+     * Callback on successful save
+     */
+    onSaveSuccess?: (data: Data) => void;
+    /**
+     * Callback on save error
+     */
+    onSaveError?: (error: Error) => void;
+    /**
+     * Callback when data changes
+     */
+    onChange?: (data: Data) => void;
+    /**
+     * Initial document status from Payload (_status field)
+     * Automatically populated when using PuckEditorView
+     */
+    initialStatus?: 'draft' | 'published';
+    /**
+     * Theme configuration for customizing component styles
+     * When provided, components will use themed styles
+     */
+    theme?: ThemeConfig;
+}
+/**
+ * Puck Editor wrapper with dynamic import
+ *
+ * This component wraps PuckEditorCore with next/dynamic to prevent
+ * hydration mismatches caused by Puck's random ID generation for
+ * drag-and-drop functionality.
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ *
+ * import { PuckEditor } from '@delmaredigital/payload-puck/editor'
+ * import { editorConfig } from '@delmaredigital/payload-puck/config/editor'
+ *
+ * export function PageEditor({ page }) {
+ *   return (
+ *     <PuckEditor
+ *       pageId={page.id}
+ *       initialData={page.puckData}
+ *       config={editorConfig}
+ *       pageTitle={page.title}
+ *       pageSlug={page.slug}
+ *       backUrl="/admin/pages"
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare function PuckEditor({ pageId, initialData, config, pageTitle, pageSlug, apiEndpoint, backUrl, previewUrl, enableViewports, plugins, layouts, layoutStyles, layoutKey, headerActionsStart, headerActionsEnd, overrides, onSaveSuccess, onSaveError, onChange, initialStatus, theme, }: PuckEditorProps): react_jsx_runtime.JSX.Element;
+
+interface PuckEditorCoreProps {
+    /**
+     * Page ID for save operations
+     */
+    pageId: string;
+    /**
+     * Initial Puck data to load
+     */
+    initialData: Data;
+    /**
+     * Puck configuration with components and settings
+     */
+    config: Config;
+    /**
+     * Page title for display
+     */
+    pageTitle: string;
+    /**
+     * Page slug for preview URL
+     */
+    pageSlug: string;
+    /**
+     * API endpoint for save operations
+     * @default '/api/puck/pages'
+     */
+    apiEndpoint?: string;
+    /**
+     * URL to navigate to when back button is clicked
+     */
+    backUrl?: string;
+    /**
+     * Preview URL or function to generate preview URL from slug
+     */
+    previewUrl?: string | ((slug: string) => string);
+    /**
+     * Whether to enable viewport switching
+     * @default true
+     */
+    enableViewports?: boolean;
+    /**
+     * Additional Puck plugins to use.
+     * The headingAnalyzer plugin is included by default.
+     * Set to `false` to disable all default plugins.
+     */
+    plugins?: Plugin[] | false;
+    /**
+     * Layout definitions for the editor preview.
+     * The editor reads header, footer, editorBackground, and editorDarkMode
+     * from the layout definition matching the selected pageLayout.
+     */
+    layouts?: LayoutDefinition[];
+    /**
+     * Layout style configurations for theme-aware preview
+     * @deprecated Use `layouts` prop instead. layoutStyles will be removed in a future version.
+     */
+    layoutStyles?: Record<string, LayoutStyle>;
+    /**
+     * Key in root.props to read layout value from
+     * @default 'pageLayout'
+     */
+    layoutKey?: string;
+    /**
+     * Custom actions to render at the start of the header
+     */
+    headerActionsStart?: ReactNode;
+    /**
+     * Custom actions to render at the end of the header
+     */
+    headerActionsEnd?: ReactNode;
+    /**
+     * Puck overrides to merge with defaults
+     */
+    overrides?: Partial<Overrides>;
+    /**
+     * Callback on successful save
+     */
+    onSaveSuccess?: (data: Data) => void;
+    /**
+     * Callback on save error
+     */
+    onSaveError?: (error: Error) => void;
+    /**
+     * Callback when data changes
+     */
+    onChange?: (data: Data) => void;
+    /**
+     * Initial document status from Payload (_status field)
+     * Used to show draft/published badge in the header
+     */
+    initialStatus?: 'draft' | 'published';
+    /**
+     * Theme configuration for customizing component styles
+     * When provided, components will use themed styles
+     */
+    theme?: ThemeConfig;
+}
+/**
+ * Full-featured Puck editor implementation
+ *
+ * Provides a complete editing experience with:
+ * - Save draft and publish functionality
+ * - Unsaved changes tracking with beforeunload warning
+ * - Interactive/Edit mode toggle
+ * - Theme-aware preview backgrounds
+ * - Responsive viewport switching
+ * - Custom header actions
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ *
+ * import { PuckEditorCore } from '@delmaredigital/payload-puck/editor'
+ * import { editorConfig } from '@delmaredigital/payload-puck/config/editor'
+ *
+ * export function PageEditor({ page }) {
+ *   return (
+ *     <PuckEditorCore
+ *       pageId={page.id}
+ *       initialData={page.puckData}
+ *       config={editorConfig}
+ *       pageTitle={page.title}
+ *       pageSlug={page.slug}
+ *       backUrl="/admin/pages"
+ *       layoutStyles={{
+ *         default: { background: '#fff', isDark: false },
+ *         dark: { background: '#1a1a1a', isDark: true },
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare function PuckEditorCore({ pageId, initialData, config, pageTitle, pageSlug, apiEndpoint, backUrl, previewUrl, enableViewports, plugins, layouts, layoutStyles, layoutKey, headerActionsStart, headerActionsEnd, overrides: customOverrides, onSaveSuccess, onSaveError, onChange: onChangeProp, initialStatus, theme, }: PuckEditorCoreProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the PuckEditorView component
+ */
+interface PuckEditorViewProps {
+    /**
+     * Puck configuration with components and settings
+     */
+    config: Config;
+    /**
+     * Collection slug for API endpoints
+     * @default 'pages'
+     */
+    collectionSlug?: string;
+    /**
+     * Base API path for Puck operations
+     * @default '/api/puck'
+     */
+    apiBasePath?: string;
+    /**
+     * URL to navigate to when back button is clicked
+     * Falls back to /admin/collections/{collectionSlug}
+     */
+    backUrl?: string;
+    /**
+     * Preview URL or function to generate preview URL from slug
+     */
+    previewUrl?: string | ((slug: string) => string);
+    /**
+     * Layout styles for theme-aware preview
+     */
+    layoutStyles?: Record<string, {
+        background: string;
+        isDark: boolean;
+    }>;
+    /**
+     * Key in root.props to read layout value from
+     * @default 'pageLayout'
+     */
+    layoutKey?: string;
+    /**
+     * Additional Puck plugins to use.
+     * The headingAnalyzer plugin is included by default.
+     * Set to `false` to disable all default plugins.
+     */
+    plugins?: Plugin[] | false;
+    /**
+     * Callback on successful save
+     */
+    onSaveSuccess?: (data: Data) => void;
+    /**
+     * Callback on save error
+     */
+    onSaveError?: (error: Error) => void;
+}
+/**
+ * Ready-to-use Puck editor page component
+ *
+ * Use this in your own editor page route (e.g., /pages/[id]/edit).
+ * It auto-fetches page data from the API and renders the PuckEditor.
+ *
+ * @example
+ * ```tsx
+ * // src/app/pages/[id]/edit/page.tsx
+ * 'use client'
+ *
+ * import { PuckEditorView } from '@delmaredigital/payload-puck/editor'
+ * import { editorConfig } from '@/puck/config'
+ *
+ * export default function PageEditor() {
+ *   return (
+ *     <PuckEditorView
+ *       config={editorConfig}
+ *       collectionSlug="pages"
+ *       apiBasePath="/api/puck"
+ *       backUrl="/admin/collections/pages"
+ *       previewUrl={(slug) => `/${slug}`}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare function PuckEditorView({ config, collectionSlug, apiBasePath, backUrl, previewUrl, layoutStyles, layoutKey, plugins, onSaveSuccess, onSaveError, }: PuckEditorViewProps): react_jsx_runtime.JSX.Element;
+
+interface HeaderActionsProps {
+    /**
+     * Default Puck header actions (undo/redo, publish button)
+     */
+    children: ReactNode;
+    /**
+     * Handler for back button click
+     */
+    onBack: () => void;
+    /**
+     * Handler for preview button click
+     */
+    onPreview: () => void;
+    /**
+     * Handler for save button click
+     */
+    onSave: (data: Data) => void;
+    /**
+     * Handler for publish button click (optional, uses default Puck publish if not provided)
+     */
+    onPublish?: (data: Data) => void;
+    /**
+     * Whether a save operation is in progress
+     */
+    isSaving: boolean;
+    /**
+     * Whether there are unsaved changes
+     */
+    hasUnsavedChanges: boolean;
+    /**
+     * Last saved timestamp
+     */
+    lastSaved: Date | null;
+    /**
+     * Document status from Payload (_status field)
+     * Shows visual indicator for draft vs published
+     */
+    documentStatus?: 'draft' | 'published';
+    /**
+     * Whether the document has ever been published (initially or during this session)
+     * Used to show "Unpublished Changes" vs "Draft" badge
+     */
+    wasPublished?: boolean;
+    /**
+     * Custom actions to render at the start of the header
+     */
+    actionsStart?: ReactNode;
+    /**
+     * Custom actions to render at the end of the header (before publish)
+     */
+    actionsEnd?: ReactNode;
+    /**
+     * Whether to show the save draft button
+     * @default true
+     */
+    showSaveDraft?: boolean;
+    /**
+     * Whether to show the view page button
+     * @default true
+     */
+    showViewPage?: boolean;
+    /**
+     * Whether to show the interactive mode toggle
+     * @default false
+     * @deprecated Use the Preview button instead
+     */
+    showInteractiveToggle?: boolean;
+    /**
+     * Whether to show the preview button
+     * @default true
+     */
+    showPreviewButton?: boolean;
+    /**
+     * Handler for opening the preview modal
+     */
+    onOpenPreview?: () => void;
+    /**
+     * Whether to show the version history button
+     * @default true
+     */
+    showVersionHistory?: boolean;
+    /**
+     * Page ID for version history (required if showVersionHistory is true)
+     */
+    pageId?: string;
+    /**
+     * API endpoint base path for version history
+     * @default '/api/puck/pages'
+     */
+    apiEndpoint?: string;
+    /**
+     * Error message to display (e.g., validation errors)
+     */
+    saveError?: string | null;
+    /**
+     * Handler to dismiss the error message
+     */
+    onDismissError?: () => void;
+}
+/**
+ * Custom header actions component for the Puck editor
+ *
+ * Provides standard actions: Back, Edit/Interactive toggle, View Page, Save Draft
+ * Also displays save status and last saved time.
+ *
+ * @example
+ * ```tsx
+ * const overrides = {
+ *   headerActions: ({ children }) => (
+ *     <HeaderActions
+ *       onBack={handleBack}
+ *       onPreview={handlePreview}
+ *       onSave={handleSave}
+ *       isSaving={isSaving}
+ *       hasUnsavedChanges={hasUnsavedChanges}
+ *       lastSaved={lastSaved}
+ *     >
+ *       {children}
+ *     </HeaderActions>
+ *   ),
+ * }
+ * ```
+ */
+declare const HeaderActions: React$1.NamedExoticComponent<HeaderActionsProps>;
+
+interface LoadingStateProps {
+    /**
+     * Loading message to display
+     * @default 'Loading editor...'
+     */
+    message?: string;
+}
+/**
+ * Loading indicator shown while the Puck editor is being loaded
+ *
+ * Used as the fallback for dynamic import with ssr: false
+ */
+declare function LoadingState({ message }: LoadingStateProps): react_jsx_runtime.JSX.Element;
+
+interface PreviewModalProps {
+    /**
+     * Whether the modal is open
+     */
+    isOpen: boolean;
+    /**
+     * Handler for closing the modal
+     */
+    onClose: () => void;
+    /**
+     * Puck data to render in the preview
+     */
+    data: Data | null;
+    /**
+     * Page title for the modal header
+     */
+    pageTitle?: string;
+    /**
+     * Handler for opening the page in a new tab
+     */
+    onOpenInNewTab?: () => void;
+    /**
+     * Available layouts for rendering
+     */
+    layouts?: LayoutDefinition[];
+    /**
+     * Whether there are unsaved changes in the editor
+     */
+    hasUnsavedChanges?: boolean;
+    /**
+     * Handler to save the current data before navigating
+     */
+    onSave?: () => Promise<void>;
+    /**
+     * Whether a save is in progress
+     */
+    isSaving?: boolean;
+}
+/**
+ * Full-screen preview modal with client-side rendering
+ *
+ * Renders the current editor data directly using PageRenderer.
+ * Links prompt for confirmation before navigating (with option to save first).
+ *
+ * Features:
+ * - Zero consumer setup required
+ * - Shows current editor state (including unsaved changes)
+ * - Interactive elements (accordions, hover states) still work
+ * - Links show confirmation dialog before navigating
+ */
+declare const PreviewModal: React$1.NamedExoticComponent<PreviewModalProps>;
+
+/**
+ * Version entry from Payload's versions system
+ */
+interface PageVersion {
+    id: string;
+    parent: string;
+    version: {
+        title?: string;
+        slug?: string;
+        _status?: 'draft' | 'published';
+        updatedAt: string;
+        createdAt: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    autosave?: boolean;
+    latest?: boolean;
+}
+interface VersionHistoryProps {
+    /**
+     * Page ID to fetch versions for
+     */
+    pageId: string;
+    /**
+     * API endpoint base path
+     * @default '/api/puck/pages'
+     */
+    apiEndpoint?: string;
+    /**
+     * Callback when a version is restored
+     */
+    onRestore?: (version: PageVersion) => void;
+    /**
+     * Whether restore operations are disabled
+     */
+    disabled?: boolean;
+}
+/**
+ * Version history dropdown for the Puck editor
+ *
+ * Shows a list of previous versions with the ability to restore them.
+ */
+declare const VersionHistory: React$1.NamedExoticComponent<VersionHistoryProps>;
+
+interface UseUnsavedChangesReturn {
+    hasUnsavedChanges: boolean;
+    markClean: () => void;
+    markDirty: () => void;
+}
+/**
+ * Hook to track unsaved changes and warn before navigation
+ *
+ * Registers a beforeunload handler to prevent accidental navigation
+ * when there are unsaved changes.
+ *
+ * @example
+ * ```tsx
+ * const { hasUnsavedChanges, markClean, markDirty } = useUnsavedChanges()
+ *
+ * const handleChange = () => {
+ *   markDirty()
+ * }
+ *
+ * const handleSave = async () => {
+ *   await save()
+ *   markClean()
+ * }
+ * ```
+ */
+declare function useUnsavedChanges(): UseUnsavedChangesReturn;
+
+export { HeaderActions, type HeaderActionsProps, IframeWrapper, type IframeWrapperProps, type LayoutStyle, LoadingState, type LoadingStateProps, type PageVersion, PreviewModal, type PreviewModalProps, PuckEditor, PuckEditorCore, type PuckEditorCoreProps, type PuckEditorProps, PuckEditorView, type PuckEditorViewProps, type UseUnsavedChangesReturn, VersionHistory, type VersionHistoryProps, useUnsavedChanges };