@delmaredigital/payload-puck 0.4.0 → 0.6.1

package/dist/ai/plugins/promptEditorPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptEditorPlugin.d.ts","sourceRoot":"","sources":["../../../src/ai/plugins/promptEditorPlugin.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,UAAU,CAqBZ"}

package/dist/ai/plugins/promptEditorPlugin.js

@@ -0,0 +1,39 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Sparkles } from 'lucide-react';
+import { PromptEditorPanel } from './PromptEditorPanel.js';
+/**
+ * Creates a Puck plugin for managing AI prompts in the editor
+ *
+ * This plugin adds an "AI Prompts" panel to the Puck plugin rail where users
+ * can view, create, edit, and delete example prompts without writing code.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { createPromptEditorPlugin } from '@delmaredigital/payload-puck/ai'
+ *
+ * const promptEditorPlugin = createPromptEditorPlugin()
+ *
+ * <PuckEditor plugins={[aiPlugin, promptEditorPlugin]} />
+ * ```
+ *
+ * @example With custom options
+ * ```tsx
+ * const promptEditorPlugin = createPromptEditorPlugin({
+ *   apiEndpoint: '/api/puck/ai-prompts',
+ *   canEdit: true,
+ *   canCreate: true,
+ *   canDelete: false, // Disable delete for non-admins
+ * })
+ * ```
+ */
+export function createPromptEditorPlugin(options = {}) {
+    const { apiEndpoint = '/api/puck/ai-prompts', canEdit = true, canCreate = true, canDelete = true, } = options;
+    return {
+        name: 'prompt-editor',
+        label: 'AI Prompts',
+        icon: _jsx(Sparkles, { size: 16 }),
+        render: () => (_jsx(PromptEditorPanel, { apiEndpoint: apiEndpoint, canEdit: canEdit, canCreate: canCreate, canDelete: canDelete })),
+    };
+}
+//# sourceMappingURL=promptEditorPlugin.js.map

package/dist/ai/plugins/promptEditorPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptEditorPlugin.js","sourceRoot":"","sources":["../../../src/ai/plugins/promptEditorPlugin.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AAGZ,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAqC,EAAE;IAEvC,MAAM,EACJ,WAAW,GAAG,sBAAsB,EACpC,OAAO,GAAG,IAAI,EACd,SAAS,GAAG,IAAI,EAChB,SAAS,GAAG,IAAI,GACjB,GAAG,OAAO,CAAA;IAEX,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,KAAC,QAAQ,IAAC,IAAI,EAAE,EAAE,GAAI;QAC5B,MAAM,EAAE,GAAG,EAAE,CAAC,CACZ,KAAC,iBAAiB,IAChB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,SAAS,GACpB,CACH;KACF,CAAA;AACH,CAAC"}

package/dist/ai/presets/componentAiDefaults.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentAiOverrides } from '../types.js';
+/**
+ * Default AI configurations for built-in payload-puck components
+ *
+ * These provide sensible defaults that help the AI understand how to use
+ * each component effectively. Users can override or extend these.
+ *
+ * NOTE: Custom fields (type: 'custom') are automatically excluded by injectAiConfig.
+ * This includes: _reset, visibility, background, media, animation, padding, margin,
+ * border, dimensions, transform, alignment fields, etc.
+ *
+ * @example Using defaults
+ * ```typescript
+ * import { injectAiConfig, defaultComponentAiConfig } from '@delmaredigital/payload-puck/ai'
+ *
+ * const aiEnabledConfig = injectAiConfig(editorConfig, defaultComponentAiConfig)
+ * ```
+ *
+ * @example Extending defaults
+ * ```typescript
+ * const customAiConfig = {
+ *   ...defaultComponentAiConfig,
+ *   Heading: {
+ *     ...defaultComponentAiConfig.Heading,
+ *     ai: {
+ *       instructions: 'Use our brand voice',
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export declare const defaultComponentAiConfig: ComponentAiOverrides;
+/**
+ * Minimal AI configuration for components
+ *
+ * Use this for a lighter-weight configuration that only marks
+ * required fields. Custom fields are still auto-excluded by injectAiConfig.
+ */
+export declare const minimalComponentAiConfig: ComponentAiOverrides;
+//# sourceMappingURL=componentAiDefaults.d.ts.map

package/dist/ai/presets/componentAiDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentAiDefaults.d.ts","sourceRoot":"","sources":["../../../src/ai/presets/componentAiDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,wBAAwB,EAAE,oBA2MtC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,oBA2BtC,CAAA"}

package/dist/ai/presets/componentAiDefaults.js

@@ -0,0 +1,239 @@
+/**
+ * Default AI configurations for built-in payload-puck components
+ *
+ * These provide sensible defaults that help the AI understand how to use
+ * each component effectively. Users can override or extend these.
+ *
+ * NOTE: Custom fields (type: 'custom') are automatically excluded by injectAiConfig.
+ * This includes: _reset, visibility, background, media, animation, padding, margin,
+ * border, dimensions, transform, alignment fields, etc.
+ *
+ * @example Using defaults
+ * ```typescript
+ * import { injectAiConfig, defaultComponentAiConfig } from '@delmaredigital/payload-puck/ai'
+ *
+ * const aiEnabledConfig = injectAiConfig(editorConfig, defaultComponentAiConfig)
+ * ```
+ *
+ * @example Extending defaults
+ * ```typescript
+ * const customAiConfig = {
+ *   ...defaultComponentAiConfig,
+ *   Heading: {
+ *     ...defaultComponentAiConfig.Heading,
+ *     ai: {
+ *       instructions: 'Use our brand voice',
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export const defaultComponentAiConfig = {
+    // Typography Components
+    Heading: {
+        ai: {
+            instructions: 'Use for section headings and titles. Choose appropriate heading level (h1-h6) based on document structure.',
+        },
+        fields: {
+            text: {
+                ai: { required: true },
+            },
+            level: {
+                ai: {
+                    instructions: 'Use h1 only once per page for the main title. Use h2 for main sections, h3 for subsections.',
+                },
+            },
+        },
+    },
+    Text: {
+        ai: {
+            instructions: 'Use for body text and single paragraphs.',
+        },
+        fields: {
+            content: {
+                ai: { required: true },
+            },
+        },
+    },
+    RichText: {
+        ai: {
+            instructions: 'Use for formatted text content with multiple paragraphs, lists, links, or other rich formatting.',
+        },
+        fields: {
+            content: {
+                ai: {
+                    required: true,
+                    // TipTap content is complex, provide schema hint
+                    schema: { type: 'string' },
+                    instructions: 'Provide HTML content for the rich text editor.',
+                },
+            },
+        },
+    },
+    // Interactive Components
+    Button: {
+        ai: {
+            instructions: 'Use for call-to-action buttons. Always provide meaningful, action-oriented button text.',
+        },
+        fields: {
+            label: {
+                ai: {
+                    required: true,
+                    instructions: 'Use action-oriented text like "Get Started", "Learn More", "Sign Up", "Contact Us".',
+                },
+            },
+            href: {
+                ai: {
+                    required: true,
+                    instructions: 'Use # as placeholder if the actual URL is unknown.',
+                },
+            },
+            variant: {
+                ai: {
+                    instructions: 'Use "primary" for main CTAs, "secondary" for less prominent actions, "outline" for subtle actions.',
+                },
+            },
+        },
+    },
+    // Media Components
+    Image: {
+        ai: {
+            instructions: 'Use for displaying images. Note: AI cannot select actual images from the media library.',
+        },
+        fields: {
+            alt: {
+                ai: {
+                    instructions: 'Provide descriptive alt text for accessibility. Describe what the image shows.',
+                },
+            },
+        },
+    },
+    // Layout Components
+    Section: {
+        ai: {
+            instructions: 'Use to group related content into a section. Sections can have background colors and padding.',
+        },
+    },
+    Container: {
+        ai: {
+            instructions: 'Use to constrain content width and center it on the page. Good for text-heavy sections.',
+        },
+    },
+    Flex: {
+        ai: {
+            instructions: 'Use for horizontal or vertical layouts with flexible spacing between items.',
+        },
+        fields: {
+            direction: {
+                ai: {
+                    instructions: 'Use "row" for horizontal layout, "column" for vertical stacking.',
+                },
+            },
+            gap: {
+                ai: {
+                    instructions: 'Set spacing between items. Common values: 8, 16, 24, 32.',
+                },
+            },
+        },
+    },
+    Grid: {
+        ai: {
+            instructions: 'Use for multi-column layouts. Specify the number of columns.',
+        },
+        fields: {
+            columns: {
+                ai: {
+                    instructions: 'Use 2-4 columns for most layouts. 12-column grid for advanced layouts.',
+                },
+            },
+        },
+    },
+    // Content Components
+    Card: {
+        ai: {
+            instructions: 'Use for content cards with optional image, title, and description. Good for feature lists, team members, products.',
+        },
+        fields: {
+            title: {
+                ai: { required: true },
+            },
+            description: {
+                ai: {
+                    instructions: 'Keep descriptions concise, 1-2 sentences.',
+                },
+            },
+        },
+    },
+    Accordion: {
+        ai: {
+            instructions: 'Use for FAQ sections or collapsible content. Each item has a title and expandable content.',
+        },
+        fields: {
+            items: {
+                ai: {
+                    required: true,
+                    instructions: 'Provide an array of items with title and content properties.',
+                },
+            },
+        },
+    },
+    // Utility Components
+    Spacer: {
+        ai: {
+            instructions: 'Use to add vertical spacing between elements. Specify height in pixels.',
+        },
+        fields: {
+            height: {
+                ai: {
+                    instructions: 'Common values: 16, 24, 32, 48, 64. Use larger values for section breaks.',
+                },
+            },
+        },
+    },
+    Divider: {
+        ai: {
+            instructions: 'Use to visually separate sections of content with a horizontal line.',
+        },
+    },
+    // Template Component
+    Template: {
+        ai: {
+            instructions: 'Use to insert a saved page template. Note: AI cannot select actual templates.',
+        },
+    },
+};
+/**
+ * Minimal AI configuration for components
+ *
+ * Use this for a lighter-weight configuration that only marks
+ * required fields. Custom fields are still auto-excluded by injectAiConfig.
+ */
+export const minimalComponentAiConfig = {
+    Heading: {
+        fields: {
+            text: { ai: { required: true } },
+        },
+    },
+    Text: {
+        fields: {
+            content: { ai: { required: true } },
+        },
+    },
+    RichText: {
+        fields: {
+            content: {
+                ai: {
+                    required: true,
+                    schema: { type: 'string' },
+                },
+            },
+        },
+    },
+    Button: {
+        fields: {
+            label: { ai: { required: true } },
+            href: { ai: { required: true } },
+        },
+    },
+};
+//# sourceMappingURL=componentAiDefaults.js.map

package/dist/ai/presets/componentAiDefaults.js.map

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

package/dist/ai/presets/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * AI Preset Configurations
+ *
+ * This module exports comprehensive AI instructions for Puck components
+ * and page composition patterns.
+ *
+ * @example Using comprehensive config (recommended)
+ * ```typescript
+ * import { comprehensiveComponentAiConfig } from '@delmaredigital/payload-puck/ai'
+ * import { injectAiConfig } from '@delmaredigital/payload-puck/ai'
+ *
+ * const aiEnabledConfig = injectAiConfig(editorConfig, comprehensiveComponentAiConfig)
+ * ```
+ *
+ * @example Adding page pattern context to AI system prompt
+ * ```typescript
+ * import { pagePatternSystemContext } from '@delmaredigital/payload-puck/ai'
+ *
+ * createPuckAiApiRoutes({
+ *   ai: {
+ *     context: `${yourBusinessContext}\n\n${pagePatternSystemContext}`,
+ *   },
+ * })
+ * ```
+ */
+import type { ComponentAiOverrides } from '../types.js';
+import { pagePatternContext, componentFieldReference } from './instructions/pagePatterns.js';
+export { defaultComponentAiConfig, minimalComponentAiConfig, } from './componentAiDefaults.js';
+/**
+ * Comprehensive AI configuration for all built-in components
+ *
+ * Combines detailed instructions from all component categories:
+ * - Typography: Heading, Text, RichText
+ * - Layout: Section, Container, Flex, Grid, Spacer
+ * - Interactive: Button, Card, Accordion, Divider
+ * - Media: Image, Template
+ *
+ * Each component includes:
+ * - Purpose and usage guidelines
+ * - Correct field names and recommended values
+ * - Composition patterns with other components
+ * - Common mistakes to avoid
+ */
+export declare const comprehensiveComponentAiConfig: ComponentAiOverrides;
+/**
+ * System context string for AI page generation
+ *
+ * Contains comprehensive guidance on:
+ * - Page structure patterns (hero, features, testimonials, FAQ, CTA)
+ * - Page type templates (landing, about, services, contact)
+ * - Typography hierarchy rules
+ * - Spacing and color guidelines
+ * - Responsive considerations
+ *
+ * Add this to your AI context for better page generation:
+ *
+ * @example
+ * ```typescript
+ * createPuckAiApiRoutes({
+ *   ai: {
+ *     context: `${yourBusinessContext}\n\n${pagePatternSystemContext}`,
+ *   },
+ * })
+ * ```
+ */
+export declare const pagePatternSystemContext = "\n## Page Composition Guidelines\n\nWhen creating pages, follow these patterns to build professional, well-structured layouts.\n\n### Page Structure Fundamentals\n\nEVERY page should be composed of multiple Section components at the root level:\n- Pages are built by stacking Section components vertically\n- Each Section represents a distinct content area\n- Sections should NOT be nested inside other Sections\n- Use Flex and Grid INSIDE Sections for layout\n\n### Hero Section Pattern\n\nThe hero is typically the first section on a landing page.\n\nSTRUCTURE:\n```\nSection (with sectionPadding, optional sectionBackground)\n  \u2514\u2500 Flex (direction: column, alignItems: center, gap: 24)\n      \u251C\u2500 Heading (level: h1, alignment: center) - Main headline\n      \u251C\u2500 Text (size: lg, alignment: center) - Subheadline/description\n      \u2514\u2500 Flex (direction: row, gap: 16, justifyContent: center) - CTA buttons\n          \u251C\u2500 Button (variant: default, size: lg) - Primary CTA\n          \u2514\u2500 Button (variant: outline) - Secondary CTA\n```\n\nVARIATIONS:\n- Minimal: Just Heading + Button\n- Standard: Heading + Text + Button(s)\n- Full: Heading + Text + Buttons + Image below\n\n### Features Section Pattern\n\nShowcase features, services, or benefits.\n\nSTRUCTURE:\n```\nSection (light or white background)\n  \u251C\u2500 Flex (direction: column, alignItems: center, gap: 16)\n  \u2502   \u251C\u2500 Heading (level: h2, alignment: center) - Section title\n  \u2502   \u2514\u2500 Text (alignment: center) - Section description\n  \u2514\u2500 Grid (numColumns: 3, gap: 24)\n      \u251C\u2500 Card (heading + text, no image)\n      \u251C\u2500 Card\n      \u2514\u2500 Card\n```\n\nVARIATIONS:\n- 2 columns for comparison features\n- 3 columns for standard features (most common)\n- 4 columns for icon-style features\n\n### Testimonials Section Pattern\n\nSocial proof with customer quotes.\n\nSTRUCTURE:\n```\nSection (subtle background color for contrast)\n  \u251C\u2500 Heading (level: h2, alignment: center) - \"What Our Customers Say\"\n  \u2514\u2500 Grid (numColumns: 2 or 3, gap: 24)\n      \u251C\u2500 Card (text: quote, heading: name + role)\n      \u251C\u2500 Card\n      \u2514\u2500 Card\n```\n\n### FAQ Section Pattern\n\nFrequently asked questions with expandable answers.\n\nSTRUCTURE:\n```\nSection\n  \u2514\u2500 Container (for constrained width)\n      \u251C\u2500 Heading (level: h2, alignment: center) - \"Frequently Asked Questions\"\n      \u2514\u2500 Accordion (items array with questions/answers)\n```\n\n### CTA (Call-to-Action) Section Pattern\n\nFinal conversion section, often with contrasting background.\n\nSTRUCTURE:\n```\nSection (contrasting sectionBackground color)\n  \u2514\u2500 Flex (direction: column, alignItems: center, gap: 24)\n      \u251C\u2500 Heading (level: h2, alignment: center) - Compelling headline\n      \u251C\u2500 Text (alignment: center) - Supporting message\n      \u2514\u2500 Button (variant: default, size: lg) - Single strong CTA\n```\n\n### About Section Pattern\n\nCompany or personal introduction.\n\nSTRUCTURE:\n```\nSection\n  \u2514\u2500 Flex (direction: row, gap: 48, alignItems: center)\n      \u251C\u2500 Image (aspectRatio: 4:3) - Team photo or illustration\n      \u2514\u2500 Flex (direction: column, gap: 16)\n          \u251C\u2500 Heading (level: h2)\n          \u251C\u2500 Text or RichText\n          \u2514\u2500 Button (optional)\n```\n\n### Team Section Pattern\n\nTeam members or leadership profiles.\n\nSTRUCTURE:\n```\nSection\n  \u251C\u2500 Heading (level: h2, alignment: center) - \"Meet Our Team\"\n  \u2514\u2500 Grid (numColumns: 3 or 4, gap: 24)\n      \u251C\u2500 Card (image: avatar, heading: name, text: role)\n      \u251C\u2500 Card\n      \u251C\u2500 Card\n      \u2514\u2500 Card\n```\n\n### Pricing Section Pattern\n\nPricing tiers or plans.\n\nSTRUCTURE:\n```\nSection\n  \u251C\u2500 Flex (direction: column, alignItems: center)\n  \u2502   \u251C\u2500 Heading (level: h2, alignment: center) - \"Simple Pricing\"\n  \u2502   \u2514\u2500 Text (alignment: center) - \"Choose the plan that works for you\"\n  \u2514\u2500 Grid (numColumns: 3, gap: 24)\n      \u251C\u2500 Card (heading: plan name, text: price + features)\n      \u251C\u2500 Card (featured tier)\n      \u2514\u2500 Card\n```\n\n---\n\n## Page Type Templates\n\n### Landing Page Structure\n1. Hero Section (headline, subheadline, CTA buttons)\n2. Features Section (3-column grid of benefit cards)\n3. About/How It Works Section (image + text side-by-side)\n4. Testimonials Section (2-3 customer quotes)\n5. FAQ Section (common questions in accordion)\n6. CTA Section (final conversion push)\n\n### About Page Structure\n1. Hero Section (company name, mission statement)\n2. Story Section (company history/journey)\n3. Values Section (3-4 core values in cards)\n4. Team Section (team member grid)\n5. CTA Section (contact or join us)\n\n### Services Page Structure\n1. Hero Section (services overview)\n2. Services Grid (3-4 service cards)\n3. Process Section (how you work)\n4. Testimonials (client success stories)\n5. CTA Section (get started)\n\n### Contact Page Structure\n1. Hero Section (contact headline)\n2. Contact Info Section (address, phone, email)\n3. FAQ Section (common questions)\n\n---\n\n## Typography Hierarchy Rules\n\nHEADING LEVELS:\n- h1: Page title in hero (ONE per page maximum)\n- h2: Major section headings\n- h3: Card titles, subsection headings\n- h4-h6: Rarely needed, for deeply nested content\n\nTEXT SIZES:\n- xl/lg: Hero subtitles, important callouts\n- base: Body text, descriptions (default)\n- sm: Secondary text, captions\n- xs: Legal text, fine print\n\n---\n\n## Spacing Guidelines\n\nSECTION PADDING (sectionPadding):\n- Hero sections: 80-96px top/bottom\n- Standard sections: 48-64px top/bottom\n- Dense sections: 32-48px top/bottom\n\nCOMPONENT GAP:\n- Tight: 8px (buttons in a compact row)\n- Compact: 16px (related elements)\n- Comfortable: 24px (card grids, flex items)\n- Spacious: 32-48px (section content groups)\n\nGRID GAP:\n- Cards: 24px typical\n- Compact grid: 16px\n- Spacious grid: 32px\n\n---\n\n## Color & Background Strategy\n\nUse sectionBackground to create visual hierarchy and professional appearance.\n\nSECTION BACKGROUND PATTERNS:\n- Hero Section: Dark or gradient background to create impact\n- Features/Content: Light or white background\n- Testimonials: Subtle contrasting background\n- CTA Section: Brand color or contrasting background\n- Alternating: Switch between white and light gray for visual rhythm\n\nVISUAL RHYTHM:\n- Alternate section backgrounds to create clear visual separation\n- Hero sections typically have bold backgrounds (dark, gradient, or brand color)\n- Content sections typically have light/white backgrounds\n- CTA sections often use brand colors for emphasis\n\n---\n\n## Responsive Considerations\n\nGRID BEHAVIOR:\n- Grid automatically stacks to single column on mobile\n- Plan content to work in both multi-column and stacked views\n\nFLEX BEHAVIOR:\n- Row layouts wrap on narrow screens\n- Consider how button groups will stack\n\nCONTENT WIDTH:\n- Section content constrained to ~1200px max-width by default\n- Text-heavy sections might use narrower (800-900px) constraint\n\n\n\n## Quick Field Reference\n\nBUTTON: text (required), link (required), variant (default/secondary/outline), size (sm/default/lg), openInNewTab (yes/no)\n\nCARD: heading (required), text, image (user selects), link, shadow (none/sm/md/lg/xl)\n\nHEADING: text (required), level (h1-h6), alignment (left/center/right)\n\nTEXT: content (required), size (xs/sm/base/lg/xl), alignment (left/center/right)\n\nRICHTEXT: content (required, HTML string)\n\nACCORDION: items (array of {title, content, defaultOpen}), allowMultiple (yes/no)\n\nSECTION: content (slot), semanticElement, id, sectionBackground, sectionPadding\n  - sectionBackground: { type: 'solid', solid: { hex, opacity? } } or { type: 'gradient', gradient: { type, angle, stops } }\n  - sectionPadding: { xs: { top, right, bottom, left, unit: 'px', linked: boolean } }\n\nFLEX: content (slot), direction (row/column), justifyContent, alignItems, gap (number), wrap (wrap/nowrap)\n  - justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between'\n  - alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'\n\nGRID: content (slot), numColumns (1-12), gap (number)\n\nSPACER: size (8/16/24/32/48/64/80/96/128), direction (vertical/horizontal/both)\n\nDIVIDER: style (solid/dashed/dotted)\n\nIMAGE: image (user selects), alt, aspectRatio (auto/1:1/16:9/4:3/3:2), link\n";
+/**
+ * Just the page pattern context (without field reference)
+ * Use if you only need the composition patterns
+ */
+export { pagePatternContext };
+/**
+ * Just the field reference (without patterns)
+ * Use if you only need a quick field name reference
+ */
+export { componentFieldReference };
+/**
+ * List of all component names by category
+ */
+export declare const allComponents: {
+    readonly typography: readonly ["Heading", "Text", "RichText"];
+    readonly layout: readonly ["Section", "Container", "Flex", "Grid", "Spacer"];
+    readonly interactive: readonly ["Button", "Card", "Accordion", "Divider"];
+    readonly media: readonly ["Image", "Template"];
+};
+/**
+ * Flat list of all component names
+ */
+export declare const componentNames: readonly ["Heading", "Text", "RichText", "Section", "Container", "Flex", "Grid", "Spacer", "Button", "Card", "Accordion", "Divider", "Image", "Template"];
+export { typographyInstructions } from './instructions/typography.js';
+export { layoutInstructions } from './instructions/layout.js';
+export { interactiveInstructions } from './instructions/interactive.js';
+export { mediaInstructions } from './instructions/media.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/presets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/presets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAOvD,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAG5F,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AAEjC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,EAAE,oBAK5C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,g9QAAwD,CAAA;AAE7F;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAElC;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAA;AAEV;;GAEG;AACH,eAAO,MAAM,cAAc,2JAKjB,CAAA;AAGV,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/ai/presets/index.js

@@ -0,0 +1,110 @@
+/**
+ * AI Preset Configurations
+ *
+ * This module exports comprehensive AI instructions for Puck components
+ * and page composition patterns.
+ *
+ * @example Using comprehensive config (recommended)
+ * ```typescript
+ * import { comprehensiveComponentAiConfig } from '@delmaredigital/payload-puck/ai'
+ * import { injectAiConfig } from '@delmaredigital/payload-puck/ai'
+ *
+ * const aiEnabledConfig = injectAiConfig(editorConfig, comprehensiveComponentAiConfig)
+ * ```
+ *
+ * @example Adding page pattern context to AI system prompt
+ * ```typescript
+ * import { pagePatternSystemContext } from '@delmaredigital/payload-puck/ai'
+ *
+ * createPuckAiApiRoutes({
+ *   ai: {
+ *     context: `${yourBusinessContext}\n\n${pagePatternSystemContext}`,
+ *   },
+ * })
+ * ```
+ */
+// Import instruction modules
+import { typographyInstructions, typographyComponents } from './instructions/typography.js';
+import { layoutInstructions, layoutComponents } from './instructions/layout.js';
+import { interactiveInstructions, interactiveComponents } from './instructions/interactive.js';
+import { mediaInstructions, mediaComponents } from './instructions/media.js';
+import { pagePatternContext, componentFieldReference } from './instructions/pagePatterns.js';
+// Re-export legacy config for backward compatibility
+export { defaultComponentAiConfig, minimalComponentAiConfig, } from './componentAiDefaults.js';
+/**
+ * Comprehensive AI configuration for all built-in components
+ *
+ * Combines detailed instructions from all component categories:
+ * - Typography: Heading, Text, RichText
+ * - Layout: Section, Container, Flex, Grid, Spacer
+ * - Interactive: Button, Card, Accordion, Divider
+ * - Media: Image, Template
+ *
+ * Each component includes:
+ * - Purpose and usage guidelines
+ * - Correct field names and recommended values
+ * - Composition patterns with other components
+ * - Common mistakes to avoid
+ */
+export const comprehensiveComponentAiConfig = {
+    ...typographyInstructions,
+    ...layoutInstructions,
+    ...interactiveInstructions,
+    ...mediaInstructions,
+};
+/**
+ * System context string for AI page generation
+ *
+ * Contains comprehensive guidance on:
+ * - Page structure patterns (hero, features, testimonials, FAQ, CTA)
+ * - Page type templates (landing, about, services, contact)
+ * - Typography hierarchy rules
+ * - Spacing and color guidelines
+ * - Responsive considerations
+ *
+ * Add this to your AI context for better page generation:
+ *
+ * @example
+ * ```typescript
+ * createPuckAiApiRoutes({
+ *   ai: {
+ *     context: `${yourBusinessContext}\n\n${pagePatternSystemContext}`,
+ *   },
+ * })
+ * ```
+ */
+export const pagePatternSystemContext = `${pagePatternContext}\n\n${componentFieldReference}`;
+/**
+ * Just the page pattern context (without field reference)
+ * Use if you only need the composition patterns
+ */
+export { pagePatternContext };
+/**
+ * Just the field reference (without patterns)
+ * Use if you only need a quick field name reference
+ */
+export { componentFieldReference };
+/**
+ * List of all component names by category
+ */
+export const allComponents = {
+    typography: typographyComponents,
+    layout: layoutComponents,
+    interactive: interactiveComponents,
+    media: mediaComponents,
+};
+/**
+ * Flat list of all component names
+ */
+export const componentNames = [
+    ...typographyComponents,
+    ...layoutComponents,
+    ...interactiveComponents,
+    ...mediaComponents,
+];
+// Re-export instruction modules for advanced usage
+export { typographyInstructions } from './instructions/typography.js';
+export { layoutInstructions } from './instructions/layout.js';
+export { interactiveInstructions } from './instructions/interactive.js';
+export { mediaInstructions } from './instructions/media.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/presets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/presets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,6BAA6B;AAC7B,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AAC3F,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAC9F,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC5E,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAE5F,qDAAqD;AACrD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAyB;IAClE,GAAG,sBAAsB;IACzB,GAAG,kBAAkB;IACrB,GAAG,uBAAuB;IAC1B,GAAG,iBAAiB;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,kBAAkB,OAAO,uBAAuB,EAAE,CAAA;AAE7F;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAElC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,UAAU,EAAE,oBAAoB;IAChC,MAAM,EAAE,gBAAgB;IACxB,WAAW,EAAE,qBAAqB;IAClC,KAAK,EAAE,eAAe;CACd,CAAA;AAEV;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,GAAG,oBAAoB;IACvB,GAAG,gBAAgB;IACnB,GAAG,qBAAqB;IACxB,GAAG,eAAe;CACV,CAAA;AAEV,mDAAmD;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/ai/presets/instructions/interactive.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentAiOverrides } from '../../types.js';
+/**
+ * Comprehensive AI instructions for interactive components
+ *
+ * These instructions teach the AI:
+ * - Button, Card, Accordion, and Divider usage
+ * - Correct field names and recommended values
+ * - Common patterns and compositions
+ */
+export declare const interactiveInstructions: ComponentAiOverrides;
+/**
+ * Interactive component names for reference
+ */
+export declare const interactiveComponents: readonly ["Button", "Card", "Accordion", "Divider"];
+//# sourceMappingURL=interactive.d.ts.map

package/dist/ai/presets/instructions/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../../../src/ai/presets/instructions/interactive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAU1D;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,oBA4UrC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,qDAAsD,CAAA"}