@delmaredigital/payload-puck 0.1.0

package/dist/plugin/index.d.ts

@@ -0,0 +1,289 @@
+import { c as PuckPluginOptions, d as PuckAdminConfig } from '../index-CoUQnyC3.js';
+import { Field, CollectionConfig, Plugin } from 'payload';
+import { L as LayoutDefinition } from '../types-D7D3rZ1J.js';
+import '@measured/puck';
+import 'react';
+
+/**
+ * Types for Puck field utilities
+ *
+ * These types support the getPuckFields() utility for hybrid collection integration.
+ */
+
+/**
+ * Conversion type option for the conversion tracking field
+ */
+interface ConversionTypeOption {
+    label: string;
+    value: string;
+}
+/**
+ * Options for getPuckFields() utility function
+ *
+ * Use this to configure which Puck-related fields to include
+ * when adding Puck support to an existing collection.
+ *
+ * @example
+ * ```typescript
+ * import { getPuckFields } from '@delmaredigital/payload-puck'
+ *
+ * const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   fields: [
+ *     // Your existing fields...
+ *     { name: 'layout', type: 'blocks', blocks: [...] },
+ *
+ *     // Add Puck support
+ *     ...getPuckFields({
+ *       includeSEO: false,      // Using your own SEO fields
+ *       includeConversion: true,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+interface GetPuckFieldsOptions {
+    /**
+     * Include SEO field group using official @payloadcms/plugin-seo convention
+     * (meta.title, meta.description, meta.image, noindex, nofollow, excludeFromSitemap)
+     * @default true
+     */
+    includeSEO?: boolean;
+    /**
+     * Include conversion tracking field group (isConversionPage, conversionType, conversionValue)
+     * @default false
+     */
+    includeConversion?: boolean;
+    /**
+     * Include editor version field ('legacy' | 'puck' discriminator)
+     * @default true
+     */
+    includeEditorVersion?: boolean;
+    /**
+     * Include page layout selector field
+     * @default true
+     */
+    includePageLayout?: boolean;
+    /**
+     * Include isHomepage checkbox field
+     * @default false
+     */
+    includeIsHomepage?: boolean;
+    /**
+     * Custom layouts for the page layout selector.
+     * If not provided, uses the plugin's DEFAULT_LAYOUTS.
+     *
+     * Only the `value` and `label` properties are used for the Payload field.
+     * Header/footer components are used by the editor and renderer.
+     */
+    layouts?: LayoutDefinition[];
+    /**
+     * Default editor version value for new pages.
+     * @default 'puck'
+     */
+    defaultEditorVersion?: 'legacy' | 'puck';
+    /**
+     * Name of the legacy blocks field to check when detecting editor version.
+     * Used by the smart detection hook to determine if existing pages have legacy content.
+     * @default 'layout'
+     */
+    legacyBlocksFieldName?: string;
+    /**
+     * Whether to place applicable fields in the sidebar.
+     * @default true
+     */
+    sidebarPosition?: boolean;
+    /**
+     * Custom conversion type options for the conversion tracking field.
+     * Only used when includeConversion is true.
+     *
+     * @example
+     * ```typescript
+     * ...getPuckFields({
+     *   includeConversion: true,
+     *   conversionTypeOptions: [
+     *     { label: 'Registration', value: 'registration' },
+     *     { label: 'Donation', value: 'donation' },
+     *     { label: 'Course Start', value: 'course_start' },
+     *   ],
+     * })
+     * ```
+     */
+    conversionTypeOptions?: ConversionTypeOption[];
+}
+
+/**
+ * Puck Field Utilities
+ *
+ * Provides reusable field definitions for adding Puck support to existing collections.
+ * Use getPuckFields() for easy integration, or import individual fields for granular control.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Use getPuckFields() for recommended defaults
+ * import { getPuckFields } from '@delmaredigital/payload-puck'
+ *
+ * const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   fields: [
+ *     // Your existing fields...
+ *     ...getPuckFields({ includeSEO: false }),
+ *   ],
+ * }
+ *
+ * // Option 2: Import individual fields
+ * import { puckDataField, editorVersionField } from '@delmaredigital/payload-puck'
+ *
+ * const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   fields: [
+ *     // Your existing fields...
+ *     puckDataField,
+ *     editorVersionField,
+ *   ],
+ * }
+ * ```
+ */
+
+/**
+ * Puck data field - stores the visual editor JSON data.
+ * This field is always hidden in the admin UI as it's managed via the visual editor.
+ */
+declare const puckDataField: Field;
+/**
+ * Creates an editor version field with smart detection for hybrid setups.
+ *
+ * The field uses a beforeValidate hook to intelligently determine the editor version:
+ * - New pages: Default to 'puck' (or custom defaultValue)
+ * - Existing pages with legacy blocks but no puckData: Set to 'legacy'
+ * - Existing pages with puckData: Set to 'puck'
+ *
+ * This prevents existing legacy content from being incorrectly marked as 'puck'
+ * when the field is first added to a collection.
+ *
+ * @param defaultValue - The default editor version for NEW pages ('puck' or 'legacy')
+ * @param sidebar - Whether to position in the sidebar (default: true)
+ * @param legacyBlocksFieldName - Name of the legacy blocks field to check (default: 'layout')
+ */
+declare function createEditorVersionField(defaultValue?: 'legacy' | 'puck', sidebar?: boolean, legacyBlocksFieldName?: string): Field;
+/**
+ * Pre-configured editor version field with 'puck' as default.
+ * Use createEditorVersionField() for custom configuration.
+ */
+declare const editorVersionField: Field;
+/**
+ * Creates a page layout field with custom layouts.
+ *
+ * @param layouts - Array of layout definitions (defaults to DEFAULT_LAYOUTS)
+ * @param sidebar - Whether to position in the sidebar (default: true)
+ */
+declare function createPageLayoutField(layouts?: LayoutDefinition[], sidebar?: boolean): Field;
+/**
+ * Pre-configured page layout field with DEFAULT_LAYOUTS.
+ * Use createPageLayoutField() for custom layouts.
+ */
+declare const pageLayoutField: Field;
+/**
+ * Homepage flag field - marks a page as the site homepage.
+ */
+declare const isHomepageField: Field;
+/**
+ * SEO/Meta field group with all metadata fields.
+ * Uses the official @payloadcms/plugin-seo convention: meta.title, meta.description
+ *
+ * Includes: title, description, image, noindex, nofollow, excludeFromSitemap
+ */
+declare const seoFieldGroup: Field;
+/**
+ * Pre-configured conversion tracking field group with default options.
+ * Use createConversionFieldGroup() for custom conversion types.
+ */
+declare const conversionFieldGroup: Field;
+/**
+ * Returns an array of Puck-related field definitions for hybrid collection integration.
+ *
+ * Use this when you have an existing collection with legacy Payload blocks and want
+ * to ADD Puck support without replacing your entire collection configuration.
+ *
+ * @param options - Configuration options for which fields to include
+ * @returns Array of Field definitions to spread into your collection's fields array
+ *
+ * @example
+ * ```typescript
+ * import { getPuckFields } from '@delmaredigital/payload-puck'
+ *
+ * export const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   fields: [
+ *     // Your existing fields
+ *     { name: 'title', type: 'text', required: true },
+ *     { name: 'slug', type: 'text', required: true },
+ *
+ *     // Legacy Payload blocks (keep these!)
+ *     { name: 'layout', type: 'blocks', blocks: [...] },
+ *
+ *     // Add Puck fields for hybrid editing
+ *     ...getPuckFields({
+ *       includeSEO: false,       // You have your own SEO fields
+ *       includeConversion: true, // Include conversion tracking
+ *       includeEditorVersion: true,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+declare function getPuckFields(options?: GetPuckFieldsOptions): Field[];
+
+/**
+ * Generates a Pages collection configuration for Puck
+ */
+declare function generatePagesCollection(slug: string, options: PuckPluginOptions): CollectionConfig;
+
+/**
+ * Templates Collection - Stores reusable Puck component configurations
+ *
+ * This collection stores serialized Puck component data that can be
+ * loaded into Template components for reuse across pages.
+ */
+declare const TemplatesCollection: CollectionConfig;
+
+/**
+ * Generates the UI field configuration for the Edit with Puck button
+ */
+declare function generatePuckEditField(collectionSlug: string, adminConfig?: PuckAdminConfig): Field;
+/**
+ * Creates a Payload plugin that integrates Puck visual page builder
+ *
+ * This plugin:
+ * - Generates a Pages collection with puckData field
+ * - Adds an "Edit with Puck" button in the admin document view
+ *
+ * The Puck editor itself runs outside of Payload admin. Create your own
+ * editor page (e.g., /pages/[id]/edit) using the PuckEditor component.
+ *
+ * @example
+ * ```typescript
+ * import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     createPuckPlugin({
+ *       pagesCollection: 'pages',
+ *       access: {
+ *         read: () => true,
+ *         create: ({ req }) => !!req.user,
+ *         update: ({ req }) => !!req.user,
+ *         delete: ({ req }) => req.user?.role === 'admin',
+ *       },
+ *       admin: {
+ *         editorPathPattern: '/pages/{id}/edit',
+ *         buttonLabel: 'Visual Editor',
+ *       },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function createPuckPlugin(options?: PuckPluginOptions): Plugin;
+
+export { type GetPuckFieldsOptions, PuckAdminConfig, PuckPluginOptions, TemplatesCollection, conversionFieldGroup, createEditorVersionField, createPageLayoutField, createPuckPlugin, editorVersionField, generatePagesCollection, generatePuckEditField, getPuckFields, isHomepageField, pageLayoutField, puckDataField, seoFieldGroup };