@delmaredigital/payload-puck 0.1.0

package/examples/config/custom-config.ts

@@ -0,0 +1,223 @@
+/**
+ * Custom Puck Configuration Example
+ *
+ * This example demonstrates how to:
+ * - Import the base payload-puck configuration
+ * - Add your own custom components using mergeConfigs
+ * - Exclude unwanted built-in components
+ * - Organize components into categories
+ *
+ * Copy and adapt this file for your project's needs.
+ */
+
+import type { Config as PuckConfig } from '@measured/puck'
+
+// =============================================================================
+// Import the base configuration and merge utility
+// =============================================================================
+
+/**
+ * The editorConfig is the full payload-puck configuration with all built-in
+ * components. It includes:
+ * - Layout: Container, Flex, Grid, Section, Spacer
+ * - Typography: Heading, Text, RichText
+ * - Media: Image, TextImageSplit
+ * - Interactive: Button, Card, Divider, Accordion, CallToAction
+ *
+ * mergeConfigs is a utility that helps combine configurations while:
+ * - Preserving base component configurations
+ * - Adding new custom components
+ * - Merging categories appropriately
+ * - Excluding components you don't need
+ */
+import { editorConfig, mergeConfigs } from '@delmaredigital/payload-puck/config'
+
+// =============================================================================
+// Import your custom components
+// =============================================================================
+
+/**
+ * Import your custom component configurations.
+ * Each should export a ComponentConfig object.
+ *
+ * See examples/components/CustomBanner.tsx for how to create these.
+ */
+import { CustomBannerConfig } from '../components/CustomBanner'
+
+// You might also have other custom components:
+// import { HeroConfig } from '../components/Hero'
+// import { TestimonialConfig } from '../components/Testimonial'
+// import { PricingTableConfig } from '../components/PricingTable'
+
+// =============================================================================
+// Create your merged configuration
+// =============================================================================
+
+/**
+ * Use mergeConfigs to combine the base config with your customizations.
+ *
+ * Options:
+ * - base: The configuration to extend (typically editorConfig)
+ * - components: Object mapping component names to their configs
+ * - categories: Object to define/extend component categories
+ * - root: Optional root configuration overrides
+ * - exclude: Array of component names to remove from base
+ */
+export const customConfig = mergeConfigs({
+  // Start with the full payload-puck configuration
+  base: editorConfig,
+
+  // Add your custom components
+  // The key becomes the component's identifier in the editor
+  components: {
+    // Add the Banner component
+    Banner: CustomBannerConfig,
+
+    // Add more custom components as needed:
+    // Hero: HeroConfig,
+    // Testimonial: TestimonialConfig,
+    // PricingTable: PricingTableConfig,
+  },
+
+  // Organize components into categories
+  // Categories appear as collapsible sections in Puck's component picker
+  categories: {
+    // Add Banner to the existing 'interactive' category
+    // The components array is merged with existing components in that category
+    interactive: {
+      title: 'Interactive',
+      components: ['Banner'],
+      // Note: Banner will be added alongside existing interactive components
+      // (Button, Card, Divider, Accordion, CallToAction)
+    },
+
+    // You can also create entirely new categories:
+    // marketing: {
+    //   title: 'Marketing',
+    //   components: ['Hero', 'Testimonial', 'PricingTable'],
+    //   defaultExpanded: false, // Collapsed by default
+    // },
+  },
+
+  // Exclude components you don't need
+  // This removes them from both the component list and categories
+  exclude: [
+    // Example: Remove CallToAction if you have your own marketing components
+    // 'CallToAction',
+
+    // Example: Remove TextImageSplit if you prefer custom layouts
+    // 'TextImageSplit',
+  ],
+
+  // Optional: Override root configuration
+  // The root defines page-level fields and the wrapper render function
+  // root: {
+  //   fields: {
+  //     // Add custom page-level fields
+  //     pageDescription: {
+  //       type: 'textarea',
+  //       label: 'Meta Description',
+  //     },
+  //     headerStyle: {
+  //       type: 'select',
+  //       label: 'Header Style',
+  //       options: [
+  //         { label: 'Default', value: 'default' },
+  //         { label: 'Transparent', value: 'transparent' },
+  //         { label: 'Dark', value: 'dark' },
+  //       ],
+  //     },
+  //   },
+  //   defaultProps: {
+  //     pageDescription: '',
+  //     headerStyle: 'default',
+  //   },
+  // },
+})
+
+// =============================================================================
+// Alternative: Minimal configuration with only your components
+// =============================================================================
+
+/**
+ * If you want to start from scratch with only specific components,
+ * you can build a config directly without merging.
+ *
+ * This is useful when you want full control over what's available.
+ */
+// import type { ComponentConfig } from '@measured/puck'
+// import { ContainerConfig, FlexConfig } from '@delmaredigital/payload-puck/components'
+// import { HeadingConfig, TextConfig } from '@delmaredigital/payload-puck/components'
+//
+// export const minimalConfig: PuckConfig = {
+//   root: {
+//     fields: {
+//       title: { type: 'text', label: 'Page Title' },
+//     },
+//     defaultProps: {
+//       title: 'New Page',
+//     },
+//     render: ({ children }) => <>{children}</>,
+//   },
+//   categories: {
+//     layout: {
+//       title: 'Layout',
+//       components: ['Container', 'Flex'],
+//     },
+//     content: {
+//       title: 'Content',
+//       components: ['Heading', 'Text', 'Banner'],
+//     },
+//   },
+//   components: {
+//     Container: ContainerConfig as ComponentConfig<any>,
+//     Flex: FlexConfig as ComponentConfig<any>,
+//     Heading: HeadingConfig as ComponentConfig<any>,
+//     Text: TextConfig as ComponentConfig<any>,
+//     Banner: CustomBannerConfig as ComponentConfig<any>,
+//   },
+// }
+
+// =============================================================================
+// Usage in your Puck Editor
+// =============================================================================
+
+/**
+ * Import this config in your Puck editor page:
+ *
+ * ```tsx
+ * // app/(manage)/pages/[id]/edit/page.tsx
+ * 'use client'
+ *
+ * import { Puck } from '@measured/puck'
+ * import { customConfig } from '@/lib/puck/custom-config'
+ * import { ThemeProvider } from '@delmaredigital/payload-puck/theme'
+ *
+ * export default function EditorPage({ data, onSave }) {
+ *   return (
+ *     <ThemeProvider>
+ *       <Puck
+ *         config={customConfig}
+ *         data={data}
+ *         onPublish={onSave}
+ *       />
+ *     </ThemeProvider>
+ *   )
+ * }
+ * ```
+ *
+ * And in your page renderer:
+ *
+ * ```tsx
+ * // app/(frontend)/[...slug]/page.tsx
+ * import { Render } from '@measured/puck'
+ * import { customConfig } from '@/lib/puck/custom-config'
+ *
+ * export default function Page({ data }) {
+ *   return <Render config={customConfig} data={data} />
+ * }
+ * ```
+ */
+
+// Export for use in your application
+export default customConfig

package/examples/config/payload.config.example.ts

@@ -0,0 +1,64 @@
+/**
+ * Payload Configuration with Puck Plugin
+ *
+ * Copy to: src/payload.config.ts (merge with existing config)
+ *
+ * This shows the minimal configuration needed to add Puck to your Payload setup.
+ */
+
+import { buildConfig } from 'payload'
+import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'
+// Import your other Payload plugins, collections, etc.
+
+export default buildConfig({
+  // ... your existing config (admin, db, etc.)
+
+  plugins: [
+    // Add Puck plugin
+    createPuckPlugin({
+      // Collection slug for pages (default: 'pages')
+      pagesCollection: 'pages',
+
+      // Auto-generate the Pages collection (default: true)
+      // Set to false if you want to define your own collection
+      autoGenerateCollection: true,
+
+      // Optional: Override collection config
+      collectionOverrides: {
+        admin: {
+          defaultColumns: ['title', 'slug', 'updatedAt'],
+        },
+      },
+
+      // Optional: Custom access control
+      access: {
+        read: () => true,
+        create: ({ req }) => !!req.user,
+        update: ({ req }) => !!req.user,
+        delete: ({ req }) => !!req.user,
+      },
+
+      // Optional: Custom layouts (shown in editor page layout selector)
+      // Only value/label are needed here - header/footer components are added
+      // in your puck-layouts.ts file for editor preview and frontend rendering
+      layouts: [
+        { value: 'default', label: 'Default' },
+        { value: 'landing', label: 'Landing' },
+        { value: 'full-width', label: 'Full Width' },
+      ],
+
+      // Admin UI configuration
+      admin: {
+        // URL pattern for the editor (use {id} placeholder)
+        editorPathPattern: '/pages/{id}/edit',
+        // Button label in Payload admin
+        buttonLabel: 'Edit with Puck',
+      },
+    }),
+
+    // ... your other plugins
+  ],
+
+  // Required for Puck pages: Enable drafts on the pages collection
+  // (The plugin handles this automatically when autoGenerateCollection is true)
+})

package/examples/lib/puck-layouts.ts

@@ -0,0 +1,258 @@
+/**
+ * Custom Page Layouts
+ *
+ * Copy this file to: src/lib/puck-layouts.ts
+ *
+ * Define custom page layouts that affect how Puck content is rendered.
+ * Each layout can specify CSS classes, max-width constraints, header/footer
+ * components, and editor preview styling.
+ *
+ * Usage:
+ * 1. Copy this file to your project's lib folder
+ * 2. Import your Header/Footer components
+ * 3. Customize the layouts to match your design system
+ * 4. Import and use in your PuckEditor, PageRenderer, and plugin config
+ */
+
+import {
+  DEFAULT_LAYOUTS,
+  createLayout,
+  mergeLayouts,
+  type LayoutDefinition,
+} from '@delmaredigital/payload-puck/layouts'
+
+// =============================================================================
+// Import your site's header/footer components
+// =============================================================================
+
+// Uncomment and adjust these imports for your project:
+// import { Header } from '@/components/header'
+// import { Footer } from '@/components/footer'
+
+// =============================================================================
+// Layouts with Header/Footer Examples
+// =============================================================================
+
+/**
+ * Default layout with sticky header
+ *
+ * For layouts with sticky/fixed headers, set stickyHeaderHeight to the
+ * header's pixel height. This adds padding-top to content in both the
+ * editor preview AND the frontend, ensuring content doesn't render
+ * behind the header.
+ *
+ * Note: stickyFooter defaults to true - the footer will always be pushed
+ * to the bottom of the viewport even with minimal content. Set to false
+ * if you want the footer to flow naturally after content.
+ */
+export const defaultWithHeader = createLayout({
+  value: 'default',
+  label: 'Default',
+  description: 'Standard page layout with header and footer',
+  classes: {
+    wrapper: '',
+    container: 'mx-auto px-4 sm:px-6 lg:px-8',
+    content: '',
+  },
+  maxWidth: '1200px',
+  fullWidth: false,
+  // Uncomment to add your header/footer:
+  // header: Header,
+  // footer: Footer,
+  // Editor preview settings
+  editorBackground: '#ffffff',
+  editorDarkMode: false,
+  // Set this to your header's height if it's sticky/fixed
+  stickyHeaderHeight: 80,
+  // stickyFooter: true (default) - footer stays at bottom of viewport
+  // Set to false if you want footer to flow after content:
+  // stickyFooter: false,
+})
+
+/**
+ * Landing page layout - no header/footer
+ *
+ * Full-width layout for custom landing pages where you want
+ * complete control over the header area (e.g., transparent headers
+ * over hero sections).
+ */
+export const landingLayout = createLayout({
+  value: 'landing',
+  label: 'Landing',
+  description: 'Full-width layout without header/footer',
+  classes: {
+    wrapper: '',
+    container: '',
+    content: '',
+  },
+  fullWidth: true,
+  // No header/footer - landing pages have custom designs
+  editorBackground: '#f8fafc',
+  editorDarkMode: false,
+})
+
+/**
+ * Dark theme layout example
+ *
+ * Demonstrates editorDarkMode for layouts with dark backgrounds.
+ */
+export const darkLayout = createLayout({
+  value: 'dark',
+  label: 'Dark',
+  description: 'Dark theme layout',
+  classes: {
+    wrapper: 'bg-gray-900',
+    container: 'mx-auto px-4 sm:px-6 lg:px-8',
+    content: '',
+  },
+  maxWidth: '1200px',
+  fullWidth: false,
+  // Uncomment to add dark-themed header/footer:
+  // header: DarkHeader,
+  // footer: DarkFooter,
+  editorBackground: '#111827', // gray-900
+  editorDarkMode: true,
+  stickyHeaderHeight: 80,
+})
+
+// =============================================================================
+// Additional Layout Examples
+// =============================================================================
+
+/**
+ * Blog post layout - narrow width optimized for reading
+ */
+export const blogLayout = createLayout({
+  value: 'blog',
+  label: 'Blog Post',
+  description: 'Narrow layout optimized for long-form reading',
+  classes: {
+    wrapper: '',
+    container: 'mx-auto px-4 sm:px-6',
+    content: 'prose prose-lg max-w-none',
+  },
+  maxWidth: '720px',
+  fullWidth: false,
+  // Uncomment for blog header/footer:
+  // header: Header,
+  // footer: Footer,
+  editorBackground: '#ffffff',
+  stickyHeaderHeight: 80,
+})
+
+/**
+ * Documentation layout - with sidebar space consideration
+ */
+export const docsLayout = createLayout({
+  value: 'docs',
+  label: 'Documentation',
+  description: 'Layout for documentation pages',
+  classes: {
+    wrapper: '',
+    container: 'mx-auto px-4 sm:px-6 lg:px-8',
+    content: 'prose max-w-none',
+  },
+  maxWidth: '900px',
+  fullWidth: false,
+})
+
+/**
+ * Dashboard layout - full width with minimal padding
+ */
+export const dashboardLayout = createLayout({
+  value: 'dashboard',
+  label: 'Dashboard',
+  description: 'Full-width layout for dashboards and data displays',
+  classes: {
+    wrapper: 'min-h-screen bg-gray-50',
+    container: 'p-4 sm:p-6',
+    content: '',
+  },
+  fullWidth: true,
+  editorBackground: '#f9fafb', // gray-50
+})
+
+/**
+ * Marketing layout - sections span full width, content contained
+ */
+export const marketingLayout = createLayout({
+  value: 'marketing',
+  label: 'Marketing',
+  description: 'Full-width sections with contained content areas',
+  classes: {
+    wrapper: '',
+    container: '',
+    content: '',
+  },
+  fullWidth: true,
+  // Uncomment for marketing header/footer:
+  // header: Header,
+  // footer: Footer,
+  dataAttributes: {
+    'data-page-type': 'marketing',
+  },
+  stickyHeaderHeight: 80,
+})
+
+// =============================================================================
+// Combined Layouts
+// =============================================================================
+
+/**
+ * All custom layouts combined with defaults
+ *
+ * Use this in your PuckEditor and PageRenderer
+ */
+export const customLayouts: LayoutDefinition[] = mergeLayouts(
+  DEFAULT_LAYOUTS,
+  [
+    defaultWithHeader,
+    landingLayout,
+    darkLayout,
+    blogLayout,
+    docsLayout,
+    dashboardLayout,
+    marketingLayout,
+  ],
+  { replace: true } // Replace default layouts with our customized versions
+)
+
+// =============================================================================
+// Usage Examples
+// =============================================================================
+
+/*
+// 1. In your editor page (e.g., app/(manage)/pages/[id]/edit/page.tsx):
+import { PuckEditor } from '@delmaredigital/payload-puck/editor'
+import { customLayouts } from '@/lib/puck-layouts'
+
+<PuckEditor
+  config={editorConfig}
+  pageId={page.id}
+  initialData={page.puckData}
+  layouts={customLayouts}  // <-- Pass layouts here
+/>
+
+// 2. In your page renderer (e.g., app/(frontend)/[...slug]/page.tsx):
+import { PageRenderer } from '@delmaredigital/payload-puck/render'
+import { customLayouts } from '@/lib/puck-layouts'
+
+<PageRenderer
+  data={page.puckData}
+  layouts={customLayouts}  // <-- Pass layouts here
+/>
+
+// 3. In payload.config.ts (optional - for layout field in Pages collection):
+import { customLayouts } from '@/lib/puck-layouts'
+
+createPuckPlugin({
+  layouts: customLayouts,
+  // ... other options
+})
+
+// 4. Create a custom Puck config with layouts:
+import { createConfig } from '@delmaredigital/payload-puck/config'
+import { customLayouts } from '@/lib/puck-layouts'
+
+const myConfig = createConfig(customLayouts)
+*/

package/examples/lib/puck-theme.ts

@@ -0,0 +1,94 @@
+/**
+ * Puck Theme Configuration
+ *
+ * Copy this file to: src/lib/puck-theme.ts
+ *
+ * Customizes Puck component styles to match your design system.
+ * This example uses shadcn/ui CSS variable conventions.
+ *
+ * Usage:
+ * ```tsx
+ * import { puckTheme } from '@/lib/puck-theme'
+ *
+ * <PageRenderer data={data} config={config} theme={puckTheme} />
+ * <PuckEditor ... theme={puckTheme} />
+ * ```
+ */
+
+import type { ThemeConfig } from '@delmaredigital/payload-puck/theme'
+
+/**
+ * Theme using CSS variables from your design system
+ *
+ * Assumes your globals.css defines:
+ * --primary, --primary-foreground
+ * --secondary, --secondary-foreground
+ * --accent, --accent-foreground
+ * --muted, --muted-foreground
+ * --destructive, --destructive-foreground
+ * --background, --foreground
+ * --input, --ring
+ */
+export const puckTheme: ThemeConfig = {
+  // Button component variants
+  buttonVariants: {
+    default: {
+      classes: 'bg-primary text-primary-foreground hover:bg-primary/90',
+    },
+    secondary: {
+      classes: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+    },
+    outline: {
+      classes: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+    },
+    ghost: {
+      classes: 'hover:bg-accent hover:text-accent-foreground',
+    },
+    destructive: {
+      classes: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+    },
+    link: {
+      classes: 'text-primary underline-offset-4 hover:underline',
+    },
+  },
+
+  // CTA button variants
+  ctaButtonVariants: {
+    primary: {
+      classes: 'bg-primary text-primary-foreground hover:bg-primary/90',
+    },
+    secondary: {
+      classes: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+    },
+    outline: {
+      classes: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+    },
+  },
+
+  // CTA background styles
+  ctaBackgroundStyles: {
+    default: 'bg-muted',
+    dark: 'bg-primary text-primary-foreground',
+    light: 'bg-background',
+  },
+
+  // Focus ring class
+  focusRingColor: 'focus:ring-ring',
+
+  // Color picker presets - customize with your brand colors
+  colorPresets: [
+    { hex: '#ffffff', label: 'White' },
+    { hex: '#f8fafc', label: 'Background' },
+    { hex: '#f1f5f9', label: 'Secondary' },
+    { hex: '#e2e8f0', label: 'Muted' },
+    { hex: '#64748b', label: 'Muted FG' },
+    { hex: '#334155', label: 'Slate 700' },
+    { hex: '#1e293b', label: 'Primary' },
+    { hex: '#0f172a', label: 'Foreground' },
+    { hex: '#000000', label: 'Black' },
+    // Add your brand accent colors:
+    // { hex: '#3b82f6', label: 'Brand Blue' },
+    // { hex: '#10b981', label: 'Success' },
+    // { hex: '#ef4444', label: 'Danger' },
+  ],
+}