@delmaredigital/payload-puck 0.1.3 → 0.3.0

package/dist/plugin/collections/Pages.js

@@ -0,0 +1,117 @@
+import { DEFAULT_LAYOUTS } from '../../layouts/defaults';
+import { puckDataField, createEditorVersionField, createPageLayoutField, isHomepageField, seoFieldGroup, conversionFieldGroup, } from '../fields';
+/**
+ * Default access function - allows all
+ */
+const defaultAccess = () => true;
+/**
+ * Generates a Pages collection configuration for Puck
+ */
+export function generatePagesCollection(slug, options) {
+    const { collectionOverrides = {}, access = {}, layouts = DEFAULT_LAYOUTS, additionalFields = [], } = options;
+    const baseFields = [
+        // Core Fields (title and slug with duplication hooks - unique to collection generation)
+        {
+            name: 'title',
+            type: 'text',
+            required: true,
+            hooks: {
+                beforeDuplicate: [
+                    ({ value }) => {
+                        if (!value)
+                            return value;
+                        const copyMatch = value.match(/^(.+) \(Copy(?: (\d+))?\)$/);
+                        if (copyMatch) {
+                            const baseName = copyMatch[1];
+                            const copyNum = copyMatch[2] ? parseInt(copyMatch[2], 10) + 1 : 2;
+                            return `${baseName} (Copy ${copyNum})`;
+                        }
+                        return `${value} (Copy)`;
+                    },
+                ],
+            },
+        },
+        {
+            name: 'slug',
+            type: 'text',
+            required: true,
+            unique: true,
+            index: true,
+            admin: {
+                position: 'sidebar',
+                description: 'URL path for this page (auto-generated from title)',
+            },
+            hooks: {
+                beforeValidate: [
+                    ({ data, value }) => {
+                        if (data && !value && data.title) {
+                            return data.title
+                                .toLowerCase()
+                                .replace(/[^\w\s-]/g, '')
+                                .replace(/\s+/g, '-')
+                                .replace(/-+/g, '-')
+                                .trim();
+                        }
+                        return value;
+                    },
+                ],
+                beforeDuplicate: [
+                    ({ value }) => {
+                        if (!value)
+                            return value;
+                        const copyMatch = value.match(/^(.+)-copy(?:-(\d+))?$/);
+                        if (copyMatch) {
+                            const baseName = copyMatch[1];
+                            const copyNum = copyMatch[2] ? parseInt(copyMatch[2], 10) + 1 : 2;
+                            return `${baseName}-copy-${copyNum}`;
+                        }
+                        return `${value}-copy`;
+                    },
+                ],
+            },
+        },
+        // Page Layout
+        createPageLayoutField(layouts, true),
+        // Editor Version
+        createEditorVersionField('puck', true),
+        // Homepage Flag
+        isHomepageField,
+        // Puck Data (hidden - managed via visual editor)
+        puckDataField,
+        // SEO Fields
+        seoFieldGroup,
+        // Conversion Tracking Fields
+        conversionFieldGroup,
+        // Additional fields from options
+        ...additionalFields,
+    ];
+    return {
+        slug,
+        admin: {
+            useAsTitle: 'title',
+            group: 'Content',
+            defaultColumns: ['title', 'slug', '_status', 'updatedAt'],
+            ...(collectionOverrides.admin ?? {}),
+        },
+        access: {
+            read: access.read ?? defaultAccess,
+            create: access.create ?? defaultAccess,
+            update: access.update ?? defaultAccess,
+            delete: access.delete ?? defaultAccess,
+            ...(collectionOverrides.access ?? {}),
+        },
+        versions: typeof collectionOverrides.versions === 'object'
+            ? { drafts: true, ...collectionOverrides.versions }
+            : { drafts: true },
+        fields: baseFields,
+        ...collectionOverrides,
+        // Ensure fields aren't overwritten by collectionOverrides
+        ...(collectionOverrides.fields && {
+            fields: [...baseFields, ...collectionOverrides.fields],
+        }),
+    };
+}
+// Note: puckDataField is now exported from '../fields' for hybrid collection integration
+// Re-export for backwards compatibility
+export { puckDataField } from '../fields';
+//# sourceMappingURL=Pages.js.map

package/dist/plugin/collections/Pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pages.js","sourceRoot":"","sources":["../../../src/plugin/collections/Pages.ts"],"names":[],"mappings":"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"}

package/dist/plugin/fields/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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,
+ *   ],
+ * }
+ * ```
+ */
+import type { Field } from 'payload';
+import type { GetPuckFieldsOptions, ConversionTypeOption } from './types';
+import type { LayoutDefinition } from '../../layouts/types';
+/**
+ * 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.
+ */
+export 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')
+ */
+export 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.
+ */
+export 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)
+ */
+export declare function createPageLayoutField(layouts?: LayoutDefinition[], sidebar?: boolean): Field;
+/**
+ * Pre-configured page layout field with DEFAULT_LAYOUTS.
+ * Use createPageLayoutField() for custom layouts.
+ */
+export declare const pageLayoutField: Field;
+/**
+ * Homepage flag field - marks a page as the site homepage.
+ */
+export 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
+ */
+export declare const seoFieldGroup: Field;
+/**
+ * Default conversion type options
+ */
+export declare const DEFAULT_CONVERSION_TYPES: ConversionTypeOption[];
+/**
+ * Creates a conversion tracking field group with custom options.
+ *
+ * @param conversionTypes - Custom conversion type options (defaults to DEFAULT_CONVERSION_TYPES)
+ * @param sidebar - Whether to position in the sidebar (default: true)
+ *
+ * @example
+ * ```typescript
+ * // Use default conversion types
+ * ...getPuckFields({ includeConversion: true })
+ *
+ * // Use custom conversion types
+ * ...getPuckFields({
+ *   includeConversion: true,
+ *   conversionTypeOptions: [
+ *     { label: 'Registration', value: 'registration' },
+ *     { label: 'Donation', value: 'donation' },
+ *     { label: 'Course Start', value: 'course_start' },
+ *     { label: 'Custom', value: 'custom' },
+ *   ],
+ * })
+ * ```
+ */
+export declare function createConversionFieldGroup(conversionTypes?: ConversionTypeOption[], sidebar?: boolean): Field;
+/**
+ * Pre-configured conversion tracking field group with default options.
+ * Use createConversionFieldGroup() for custom conversion types.
+ */
+export 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,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+export declare function getPuckFields(options?: GetPuckFieldsOptions): Field[];
+export type { GetPuckFieldsOptions, ConversionTypeOption } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/fields/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAQ3D;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,KAO3B,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,GAAE,QAAQ,GAAG,MAAe,EACxC,OAAO,GAAE,OAAc,EACvB,qBAAqB,GAAE,MAAiB,GACvC,KAAK,CA6CP;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAA8C,CAAA;AAE/E;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,gBAAgB,EAAoB,EAC7C,OAAO,GAAE,OAAc,GACtB,KAAK,CAYP;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,KAA+B,CAAA;AAE7D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,KAQ7B,CAAA;AAMD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,KA6D3B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,oBAAoB,EAQ1D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,GAAE,oBAAoB,EAA6B,EAClE,OAAO,GAAE,OAAc,GACtB,KAAK,CA0CP;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAoC,CAAA;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,KAAK,EAAE,CA8CzE;AAGD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA"}

package/dist/plugin/fields/index.js

@@ -0,0 +1,364 @@
+/**
+ * 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,
+ *   ],
+ * }
+ * ```
+ */
+import { DEFAULT_LAYOUTS } from '../../layouts/defaults';
+import { layoutsToPayloadOptions } from '../../layouts/utils';
+// =============================================================================
+// Core Fields
+// =============================================================================
+/**
+ * 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.
+ */
+export const puckDataField = {
+    name: 'puckData',
+    type: 'json',
+    admin: {
+        hidden: true,
+        description: 'Puck editor data - managed via visual editor',
+    },
+};
+/**
+ * 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')
+ */
+export function createEditorVersionField(defaultValue = 'puck', sidebar = true, legacyBlocksFieldName = 'layout') {
+    return {
+        name: 'editorVersion',
+        type: 'select',
+        // NO defaultValue here - we use the hook to intelligently detect the value
+        // This prevents migrations from blindly setting 'puck' on legacy pages
+        options: [
+            { label: 'Legacy (Payload Blocks)', value: 'legacy' },
+            { label: 'Puck Visual Editor', value: 'puck' },
+        ],
+        admin: {
+            position: sidebar ? 'sidebar' : undefined,
+            description: 'Which editor was used to create this page',
+        },
+        hooks: {
+            beforeValidate: [
+                ({ value, data, operation }) => {
+                    // If value is explicitly set (and not null/undefined), keep it
+                    if (value)
+                        return value;
+                    // Detect based on content - works for both new and existing documents
+                    const legacyBlocks = data?.[legacyBlocksFieldName];
+                    const hasLegacyBlocks = Array.isArray(legacyBlocks) && legacyBlocks.length > 0;
+                    const puckData = data?.puckData;
+                    const hasPuckData = puckData?.content && Array.isArray(puckData.content) && puckData.content.length > 0;
+                    // If has legacy blocks but no puck data, it's a legacy page
+                    if (hasLegacyBlocks && !hasPuckData) {
+                        return 'legacy';
+                    }
+                    // If has puck data, it's a puck page
+                    if (hasPuckData) {
+                        return 'puck';
+                    }
+                    // For new documents with no content yet, use configured default
+                    // For existing documents with no content, also use default
+                    return defaultValue;
+                },
+            ],
+        },
+    };
+}
+/**
+ * Pre-configured editor version field with 'puck' as default.
+ * Use createEditorVersionField() for custom configuration.
+ */
+export const editorVersionField = createEditorVersionField('puck', true);
+/**
+ * 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)
+ */
+export function createPageLayoutField(layouts = DEFAULT_LAYOUTS, sidebar = true) {
+    return {
+        name: 'pageLayout',
+        type: 'select',
+        required: true,
+        defaultValue: 'default',
+        options: layoutsToPayloadOptions(layouts),
+        admin: {
+            position: sidebar ? 'sidebar' : undefined,
+            description: 'Overall page structure and layout style',
+        },
+    };
+}
+/**
+ * Pre-configured page layout field with DEFAULT_LAYOUTS.
+ * Use createPageLayoutField() for custom layouts.
+ */
+export const pageLayoutField = createPageLayoutField();
+/**
+ * Homepage flag field - marks a page as the site homepage.
+ */
+export const isHomepageField = {
+    name: 'isHomepage',
+    type: 'checkbox',
+    defaultValue: false,
+    admin: {
+        position: 'sidebar',
+        description: 'Mark this page as the homepage',
+    },
+};
+// =============================================================================
+// Field Groups
+// =============================================================================
+/**
+ * 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
+ */
+export const seoFieldGroup = {
+    name: 'meta',
+    type: 'group',
+    label: 'SEO',
+    admin: {
+        position: 'sidebar',
+    },
+    fields: [
+        {
+            name: 'title',
+            type: 'text',
+            label: 'Meta Title',
+            admin: {
+                description: 'Override the page title for search engines',
+            },
+        },
+        {
+            name: 'description',
+            type: 'textarea',
+            label: 'Meta Description',
+            admin: {
+                description: 'Description shown in search engine results',
+            },
+        },
+        {
+            name: 'image',
+            type: 'upload',
+            relationTo: 'media',
+            label: 'Open Graph Image',
+            admin: {
+                description: 'Image shown when sharing on social media',
+            },
+        },
+        {
+            name: 'noindex',
+            type: 'checkbox',
+            label: 'No Index',
+            defaultValue: false,
+            admin: {
+                description: 'Prevent search engines from indexing this page',
+            },
+        },
+        {
+            name: 'nofollow',
+            type: 'checkbox',
+            label: 'No Follow',
+            defaultValue: false,
+            admin: {
+                description: 'Prevent search engines from following links on this page',
+            },
+        },
+        {
+            name: 'excludeFromSitemap',
+            type: 'checkbox',
+            label: 'Exclude from Sitemap',
+            defaultValue: false,
+            admin: {
+                description: 'Exclude this page from the XML sitemap',
+            },
+        },
+    ],
+};
+/**
+ * Default conversion type options
+ */
+export const DEFAULT_CONVERSION_TYPES = [
+    { label: 'Lead', value: 'lead' },
+    { label: 'Registration', value: 'registration' },
+    { label: 'Purchase', value: 'purchase' },
+    { label: 'Donation', value: 'donation' },
+    { label: 'Newsletter Signup', value: 'newsletter' },
+    { label: 'Contact Form', value: 'contact' },
+    { label: 'Custom', value: 'custom' },
+];
+/**
+ * Creates a conversion tracking field group with custom options.
+ *
+ * @param conversionTypes - Custom conversion type options (defaults to DEFAULT_CONVERSION_TYPES)
+ * @param sidebar - Whether to position in the sidebar (default: true)
+ *
+ * @example
+ * ```typescript
+ * // Use default conversion types
+ * ...getPuckFields({ includeConversion: true })
+ *
+ * // Use custom conversion types
+ * ...getPuckFields({
+ *   includeConversion: true,
+ *   conversionTypeOptions: [
+ *     { label: 'Registration', value: 'registration' },
+ *     { label: 'Donation', value: 'donation' },
+ *     { label: 'Course Start', value: 'course_start' },
+ *     { label: 'Custom', value: 'custom' },
+ *   ],
+ * })
+ * ```
+ */
+export function createConversionFieldGroup(conversionTypes = DEFAULT_CONVERSION_TYPES, sidebar = true) {
+    return {
+        name: 'conversionTracking',
+        type: 'group',
+        label: 'Conversion Tracking',
+        admin: {
+            position: sidebar ? 'sidebar' : undefined,
+            description: 'Configure conversion tracking for analytics',
+        },
+        fields: [
+            {
+                name: 'isConversionPage',
+                type: 'checkbox',
+                label: 'Is Conversion Page',
+                defaultValue: false,
+                admin: {
+                    description: 'Check this if this page represents a completed conversion (e.g., thank you page)',
+                },
+            },
+            {
+                name: 'conversionType',
+                type: 'select',
+                label: 'Conversion Type',
+                options: conversionTypes,
+                admin: {
+                    description: 'Type of conversion this page represents',
+                    condition: (data, siblingData) => siblingData?.isConversionPage === true,
+                },
+            },
+            {
+                name: 'conversionValue',
+                type: 'number',
+                label: 'Conversion Value',
+                defaultValue: 0,
+                admin: {
+                    description: 'Monetary value of this conversion (0 for non-monetary conversions)',
+                    condition: (data, siblingData) => siblingData?.isConversionPage === true,
+                },
+            },
+        ],
+    };
+}
+/**
+ * Pre-configured conversion tracking field group with default options.
+ * Use createConversionFieldGroup() for custom conversion types.
+ */
+export const conversionFieldGroup = createConversionFieldGroup();
+// =============================================================================
+// Main Utility Function
+// =============================================================================
+/**
+ * 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,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
+export function getPuckFields(options = {}) {
+    const { includeSEO = true, includeConversion = false, includeEditorVersion = true, includePageLayout = true, includeIsHomepage = false, layouts = DEFAULT_LAYOUTS, defaultEditorVersion = 'puck', legacyBlocksFieldName = 'layout', sidebarPosition = true, conversionTypeOptions, } = options;
+    const fields = [];
+    // Core puckData field (always included - this is essential for Puck)
+    fields.push(puckDataField);
+    // Editor version field (discriminator for hybrid rendering)
+    // Uses smart detection to preserve legacy pages when field is first added
+    if (includeEditorVersion) {
+        fields.push(createEditorVersionField(defaultEditorVersion, sidebarPosition, legacyBlocksFieldName));
+    }
+    // Page layout field
+    if (includePageLayout) {
+        fields.push(createPageLayoutField(layouts, sidebarPosition));
+    }
+    // Homepage flag
+    if (includeIsHomepage) {
+        fields.push(isHomepageField);
+    }
+    // SEO group
+    if (includeSEO) {
+        fields.push(seoFieldGroup);
+    }
+    // Conversion tracking group (with optional custom conversion types)
+    if (includeConversion) {
+        fields.push(createConversionFieldGroup(conversionTypeOptions, sidebarPosition));
+    }
+    return fields;
+}
+//# sourceMappingURL=index.js.map

package/dist/plugin/fields/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugin/fields/index.ts"],"names":[],"mappings":"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"}