@delmaredigital/payload-puck 0.1.0

package/dist/utils-gAvt0Vhw.d.ts

@@ -0,0 +1,85 @@
+import { L as LayoutDefinition, a as LayoutConfig, b as LayoutOption } from './types-D7D3rZ1J.js';
+
+/**
+ * Default Layout Definitions
+ *
+ * These provide sensible defaults for common page layout patterns.
+ * Users can override or extend these in their own configuration.
+ */
+
+/**
+ * Default layout - standard content width with padding
+ */
+declare const defaultLayout: LayoutDefinition;
+/**
+ * Landing layout - optimized for marketing/landing pages
+ */
+declare const landingLayout: LayoutDefinition;
+/**
+ * Full width layout - edge-to-edge content
+ */
+declare const fullWidthLayout: LayoutDefinition;
+/**
+ * Narrow layout - ideal for blog posts and articles
+ */
+declare const narrowLayout: LayoutDefinition;
+/**
+ * Wide layout - extra wide content area
+ */
+declare const wideLayout: LayoutDefinition;
+/**
+ * Default layouts included with the plugin
+ */
+declare const DEFAULT_LAYOUTS: LayoutDefinition[];
+/**
+ * Extended layouts for users who want more options
+ */
+declare const EXTENDED_LAYOUTS: LayoutDefinition[];
+/**
+ * Default layout configuration
+ */
+declare const DEFAULT_LAYOUT_CONFIG: LayoutConfig;
+
+/**
+ * Layout Utilities
+ *
+ * Functions for working with layout configurations.
+ */
+
+/**
+ * Resolves a layout config, merging with defaults if needed
+ */
+declare function resolveLayoutConfig(config?: Partial<LayoutConfig>): LayoutConfig;
+/**
+ * Gets a layout definition by value
+ */
+declare function getLayout(layouts: LayoutDefinition[], value: string, fallback?: string): LayoutDefinition | undefined;
+/**
+ * Converts layout definitions to Puck select options
+ */
+declare function layoutsToOptions(layouts: LayoutDefinition[]): LayoutOption[];
+/**
+ * Converts layout definitions to Payload select options
+ */
+declare function layoutsToPayloadOptions(layouts: LayoutDefinition[]): Array<{
+    label: string;
+    value: string;
+}>;
+/**
+ * Creates a custom layout definition
+ */
+declare function createLayout(config: Omit<LayoutDefinition, 'value' | 'label'> & {
+    value: string;
+    label: string;
+}): LayoutDefinition;
+/**
+ * Merges layout configurations
+ */
+declare function mergeLayouts(base: LayoutDefinition[], custom: LayoutDefinition[], options?: {
+    /** Replace base layouts instead of merging */
+    replace?: boolean;
+    /** Exclude these layout values from base */
+    exclude?: string[];
+}): LayoutDefinition[];
+
+export { DEFAULT_LAYOUTS as D, EXTENDED_LAYOUTS as E, DEFAULT_LAYOUT_CONFIG as a, layoutsToOptions as b, createLayout as c, defaultLayout as d, layoutsToPayloadOptions as e, fullWidthLayout as f, getLayout as g, landingLayout as l, mergeLayouts as m, narrowLayout as n, resolveLayoutConfig as r, wideLayout as w };

package/examples/README.md

@@ -0,0 +1,240 @@
+# Puck Plugin Examples
+
+Copy these files to your project as a starting point. Each file includes comments explaining what to customize.
+
+## Directory Structure
+
+```
+examples/
+├── api/
+│   └── puck/
+│       └── pages/
+│           ├── route.ts              # List & create pages
+│           └── [id]/
+│               ├── route.ts          # Get, update, delete page
+│               └── versions/
+│                   └── route.ts      # Version history (optional)
+├── app/
+│   ├── (frontend)/
+│   │   └── page.tsx                  # Homepage route (root "/")
+│   ├── pages/
+│   │   └── [id]/
+│   │       └── edit/
+│   │           └── page.tsx          # Visual editor page
+│   └── [...slug]/
+│       └── page.tsx                  # Dynamic page renderer
+├── config/
+│   └── payload.config.example.ts     # Payload plugin configuration
+└── lib/
+    ├── puck-theme.ts                 # Theme configuration
+    └── puck-layouts.ts               # Custom page layouts
+```
+
+**Note:** The plugin automatically creates a `puck-templates` collection for the Template component. No additional API routes are needed - templates use Payload's built-in REST API at `/api/puck-templates`.
+
+## Quick Setup
+
+### 1. Add the Plugin to Payload Config
+
+Reference the example configuration and merge with your existing `payload.config.ts`:
+
+```bash
+# View the example config
+cat node_modules/@delmaredigital/payload-puck/examples/config/payload.config.example.ts
+```
+
+Add the plugin to your config:
+
+```typescript
+import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'
+
+export default buildConfig({
+  plugins: [
+    createPuckPlugin({
+      pagesCollection: 'pages',
+    }),
+  ],
+  // ... rest of your config
+})
+```
+
+### 2. Copy API Routes
+
+```bash
+# From your project root
+cp -r node_modules/@delmaredigital/payload-puck/examples/api/puck src/app/api/
+```
+
+### 3. Copy Editor Page
+
+```bash
+# Adjust the destination path as needed for your route structure
+mkdir -p src/app/\(manage\)/pages/\[id\]/edit
+cp node_modules/@delmaredigital/payload-puck/examples/app/pages/\[id\]/edit/page.tsx src/app/\(manage\)/pages/\[id\]/edit/
+```
+
+### 4. Copy Frontend Routes
+
+```bash
+# Homepage route (handles root "/")
+mkdir -p src/app/\(frontend\)
+cp node_modules/@delmaredigital/payload-puck/examples/app/\(frontend\)/page.tsx src/app/\(frontend\)/
+
+# Dynamic catch-all route (handles "/about", "/contact", etc.)
+mkdir -p src/app/\(frontend\)/\[...slug\]
+cp node_modules/@delmaredigital/payload-puck/examples/app/\[...slug\]/page.tsx src/app/\(frontend\)/\[...slug\]/
+```
+
+### 5. Copy Theme (Optional)
+
+```bash
+mkdir -p src/lib
+cp node_modules/@delmaredigital/payload-puck/examples/lib/puck-theme.ts src/lib/
+```
+
+Then uncomment the theme imports in the editor and renderer pages.
+
+### 6. Copy Layouts (Optional)
+
+```bash
+cp node_modules/@delmaredigital/payload-puck/examples/lib/puck-layouts.ts src/lib/
+```
+
+Then update your plugin config and renderer to use custom layouts.
+
+## Customization
+
+### Authentication
+
+Edit the `authenticate` function in each API route to match your auth setup:
+
+```typescript
+authenticate: async (request) => {
+  // Your auth logic here
+  const session = await getSession(request)
+  if (!session?.user) return { authenticated: false }
+  return { authenticated: true, user: session.user }
+},
+```
+
+### Permissions
+
+Customize the `canView`, `canEdit`, `canPublish`, and `canDelete` hooks:
+
+```typescript
+canEdit: async (user, pageId) => {
+  // Example: Only editors and admins can edit
+  return { allowed: ['editor', 'admin'].includes(user?.role) }
+},
+```
+
+### Theme
+
+Edit `lib/puck-theme.ts` to match your CSS variables:
+
+```typescript
+buttonVariants: {
+  default: {
+    // Use your CSS variable classes
+    classes: 'bg-brand text-brand-foreground hover:bg-brand/90',
+  },
+},
+```
+
+### Layouts
+
+Edit `lib/puck-layouts.ts` to define custom page layouts with header/footer support:
+
+```typescript
+import { createLayout, mergeLayouts, DEFAULT_LAYOUTS } from '@delmaredigital/payload-puck/layouts'
+import { Header } from '@/components/header'
+import { Footer } from '@/components/footer'
+
+// Layout with sticky header
+const defaultLayout = createLayout({
+  value: 'default',
+  label: 'Default',
+  description: 'Standard page with header and footer',
+  maxWidth: '1200px',
+  // Header/footer rendered in both editor preview and frontend
+  header: Header,
+  footer: Footer,
+  // Editor preview settings
+  editorBackground: '#ffffff',
+  editorDarkMode: false,
+  // IMPORTANT: Set this if your header is sticky/fixed
+  // This adds padding-top in both editor AND frontend so content doesn't render behind the header
+  stickyHeaderHeight: 80, // Height of your sticky header in pixels
+})
+
+// Landing layout without header/footer
+const landingLayout = createLayout({
+  value: 'landing',
+  label: 'Landing',
+  description: 'Full-width layout without header/footer',
+  fullWidth: true,
+  // No header/footer - content controls the entire page
+  editorBackground: '#f8fafc',
+})
+
+// Dark theme example
+const darkLayout = createLayout({
+  value: 'dark',
+  label: 'Dark',
+  description: 'Dark theme layout',
+  maxWidth: '1200px',
+  header: Header, // Could be a dark-themed header
+  footer: Footer,
+  editorBackground: '#111827',
+  editorDarkMode: true, // Sets dark mode class on iframe
+  stickyHeaderHeight: 80,
+})
+
+// Combine with defaults
+export const customLayouts = mergeLayouts(
+  DEFAULT_LAYOUTS,
+  [defaultLayout, landingLayout, darkLayout],
+  { replace: true } // Replace defaults with our versions
+)
+```
+
+Use layouts in your editor page:
+
+```typescript
+import { PuckEditor } from '@delmaredigital/payload-puck/editor'
+import { customLayouts } from '@/lib/puck-layouts'
+
+<PuckEditor
+  config={editorConfig}
+  pageId={page.id}
+  initialData={page.puckData}
+  layouts={customLayouts}  // Editor reads header/footer from layouts
+/>
+```
+
+And in your PageRenderer:
+
+```typescript
+import { PageRenderer } from '@delmaredigital/payload-puck/render'
+import { customLayouts } from '@/lib/puck-layouts'
+
+<PageRenderer
+  data={page.puckData}
+  layouts={customLayouts}  // Frontend renders header/footer from layouts
+/>
+```
+
+#### Layout Definition Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `value` | `string` | Unique identifier |
+| `label` | `string` | Display name in editor |
+| `header` | `ComponentType` | Header component for preview & frontend |
+| `footer` | `ComponentType` | Footer component for preview & frontend |
+| `stickyHeaderHeight` | `number` | Height of sticky/fixed header (applies padding in editor & frontend) |
+| `editorBackground` | `string` | Background color for editor preview |
+| `editorDarkMode` | `boolean` | Use dark mode in editor preview |
+| `maxWidth` | `string` | Container max-width (e.g., `'1200px'`) |
+| `fullWidth` | `boolean` | If true, no container constraints |
+| `classes` | `object` | CSS classes for wrapper/container/content |

package/examples/api/puck/pages/[id]/route.ts

@@ -0,0 +1,64 @@
+/**
+ * Puck Pages API - Get, Update, Delete
+ *
+ * Copy this file to: app/api/puck/pages/[id]/route.ts
+ *
+ * Provides:
+ * - GET: Get a single page by ID
+ * - PATCH: Update a page (supports draft/publish)
+ * - DELETE: Delete a page
+ */
+
+import { createPuckApiRoutesWithId } from '@delmaredigital/payload-puck/api'
+import config from '@payload-config'
+import { getPayload } from 'payload'
+import { headers } from 'next/headers'
+
+export const { GET, PATCH, DELETE } = createPuckApiRoutesWithId({
+  collection: 'pages',
+  payloadConfig: config,
+  auth: {
+    // Customize authentication logic for your app
+    authenticate: async (request) => {
+      const payload = await getPayload({ config })
+      const { user } = await payload.auth({ headers: await headers() })
+
+      if (!user) {
+        return { authenticated: false }
+      }
+
+      return {
+        authenticated: true,
+        user: { id: user.id, role: (user as any).role },
+      }
+    },
+
+    // Optional: Customize who can view a page
+    canView: async (user, pageId) => {
+      return { allowed: true }
+    },
+
+    // Optional: Customize who can edit a page
+    canEdit: async (user, pageId) => {
+      return { allowed: !!user }
+    },
+
+    // Optional: Customize who can publish (defaults to canEdit)
+    canPublish: async (user, pageId) => {
+      return { allowed: !!user }
+    },
+
+    // Optional: Customize who can delete a page
+    canDelete: async (user, pageId) => {
+      // Example: Only admins can delete
+      return { allowed: user?.role === 'admin' }
+    },
+  },
+
+  // Optional: Map Puck root props to Payload fields
+  rootPropsMapping: [
+    { from: 'metaTitle', to: 'seo.metaTitle' },
+    { from: 'metaDescription', to: 'seo.metaDescription' },
+    { from: 'pageLayout', to: 'pageLayout' },
+  ],
+})

package/examples/api/puck/pages/[id]/versions/route.ts

@@ -0,0 +1,47 @@
+/**
+ * Puck Pages Versions API
+ *
+ * Copy this file to: app/api/puck/pages/[id]/versions/route.ts
+ *
+ * Provides:
+ * - GET: List page versions
+ * - POST: Restore a specific version
+ *
+ * The History button automatically appears in the editor when this route exists.
+ */
+
+import { createPuckApiRoutesVersions } from '@delmaredigital/payload-puck/api'
+import config from '@payload-config'
+import { getPayload } from 'payload'
+import { headers } from 'next/headers'
+
+export const { GET, POST } = createPuckApiRoutesVersions({
+  collection: 'pages',
+  payloadConfig: config,
+  auth: {
+    // Customize authentication logic for your app
+    authenticate: async (request) => {
+      const payload = await getPayload({ config })
+      const { user } = await payload.auth({ headers: await headers() })
+
+      if (!user) {
+        return { authenticated: false }
+      }
+
+      return {
+        authenticated: true,
+        user: { id: user.id, role: (user as any).role },
+      }
+    },
+
+    // Optional: Customize who can view versions
+    canView: async (user, pageId) => {
+      return { allowed: !!user }
+    },
+
+    // Optional: Customize who can restore versions
+    canEdit: async (user, pageId) => {
+      return { allowed: !!user }
+    },
+  },
+})

package/examples/api/puck/pages/route.ts

@@ -0,0 +1,45 @@
+/**
+ * Puck Pages API - List & Create
+ *
+ * Copy this file to: app/api/puck/pages/route.ts
+ *
+ * Provides:
+ * - GET: List all pages
+ * - POST: Create a new page
+ */
+
+import { createPuckApiRoutes } from '@delmaredigital/payload-puck/api'
+import config from '@payload-config'
+import { getPayload } from 'payload'
+import { headers } from 'next/headers'
+
+export const { GET, POST } = createPuckApiRoutes({
+  collection: 'pages',
+  payloadConfig: config,
+  auth: {
+    // Customize authentication logic for your app
+    authenticate: async (request) => {
+      const payload = await getPayload({ config })
+      const { user } = await payload.auth({ headers: await headers() })
+
+      if (!user) {
+        return { authenticated: false }
+      }
+
+      return {
+        authenticated: true,
+        user: { id: user.id, role: (user as any).role },
+      }
+    },
+
+    // Optional: Customize who can list pages
+    canList: async (user) => {
+      return { allowed: true }
+    },
+
+    // Optional: Customize who can create pages
+    canCreate: async (user) => {
+      return { allowed: !!user }
+    },
+  },
+})

package/examples/app/(frontend)/page.tsx

@@ -0,0 +1,94 @@
+/**
+ * Homepage Route
+ *
+ * Copy this file to: app/(frontend)/page.tsx
+ *
+ * Handles the root URL ("/") separately from the catch-all [...slug] route.
+ * Looks for a page with slug "home" or isHomepage=true.
+ */
+
+import { notFound } from 'next/navigation'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+import { PageRenderer } from '@delmaredigital/payload-puck/render'
+import { baseConfig } from '@delmaredigital/payload-puck/config'
+import { LayoutWrapper, DEFAULT_LAYOUTS } from '@delmaredigital/payload-puck/layouts'
+// Import your custom layouts - create from examples/lib/puck-layouts.ts
+// import { siteLayouts } from '@/lib/puck-layouts'
+// Import your theme - create from examples/lib/puck-theme.ts
+// import { puckTheme } from '@/lib/puck-theme'
+import type { Data as PuckData } from '@measured/puck'
+import type { Metadata } from 'next'
+
+// Generate SEO metadata for homepage
+export async function generateMetadata(): Promise<Metadata> {
+  const payload = await getPayload({ config })
+
+  // Find homepage by isHomepage flag or slug
+  const { docs } = await payload.find({
+    collection: 'pages',
+    where: {
+      or: [
+        { isHomepage: { equals: true } },
+        { slug: { equals: 'home' } },
+      ],
+    },
+    limit: 1,
+  })
+
+  const page = docs[0] as any
+  if (!page) return { title: 'Home' }
+
+  return {
+    title: page.meta?.title || page.title,
+    description: page.meta?.description,
+  }
+}
+
+export default async function HomePage() {
+  const payload = await getPayload({ config })
+
+  // Find homepage by isHomepage flag or slug
+  const { docs } = await payload.find({
+    collection: 'pages',
+    where: {
+      or: [
+        { isHomepage: { equals: true } },
+        { slug: { equals: 'home' } },
+      ],
+    },
+    limit: 1,
+  })
+
+  const page = docs[0] as any
+  if (!page) notFound()
+
+  // Handle pages without content
+  if (!page.puckData) {
+    return (
+      <div className="container mx-auto py-12 text-center">
+        <h1 className="text-2xl font-bold mb-4">{page.title}</h1>
+        <p className="text-muted-foreground">
+          This page has no content yet. Edit it in the admin panel.
+        </p>
+      </div>
+    )
+  }
+
+  // Find the layout definition based on page's pageLayout setting
+  // Use your custom siteLayouts instead of DEFAULT_LAYOUTS for header/footer
+  const layouts = DEFAULT_LAYOUTS // Replace with: siteLayouts
+  const pageLayout = page.puckData?.root?.props?.pageLayout || 'default'
+  const layout = layouts.find((l) => l.value === pageLayout)
+
+  return (
+    <LayoutWrapper layout={layout}>
+      <PageRenderer
+        data={page.puckData as PuckData}
+        config={baseConfig}
+        // Optional: Custom theme - uncomment after creating puck-theme.ts
+        // theme={puckTheme}
+      />
+    </LayoutWrapper>
+  )
+}

package/examples/app/[...slug]/page.tsx

@@ -0,0 +1,101 @@
+/**
+ * Dynamic Page Renderer
+ *
+ * Copy this file to: app/(frontend)/[...slug]/page.tsx
+ * (or your preferred route structure)
+ *
+ * Renders Puck pages from Payload CMS with:
+ * - SEO metadata generation
+ * - 404 handling for missing pages
+ * - Layout-based header/footer rendering
+ * - Optional theming support
+ */
+
+import { notFound } from 'next/navigation'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+import { PageRenderer } from '@delmaredigital/payload-puck/render'
+import { baseConfig } from '@delmaredigital/payload-puck/config'
+import { LayoutWrapper, DEFAULT_LAYOUTS } from '@delmaredigital/payload-puck/layouts'
+// Import your custom layouts - create from examples/lib/puck-layouts.ts
+// import { siteLayouts } from '@/lib/puck-layouts'
+// Import your theme - create from examples/lib/puck-theme.ts
+// import { puckTheme } from '@/lib/puck-theme'
+import type { Data as PuckData } from '@measured/puck'
+import type { Metadata } from 'next'
+
+interface PageParams {
+  slug: string[]
+}
+
+// Generate SEO metadata from page data
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<PageParams>
+}): Promise<Metadata> {
+  const { slug } = await params
+  const payload = await getPayload({ config })
+
+  const { docs } = await payload.find({
+    collection: 'pages',
+    where: { slug: { equals: slug.join('/') } },
+    limit: 1,
+  })
+
+  const page = docs[0] as any
+  if (!page) return {}
+
+  return {
+    title: page.meta?.title || page.title,
+    description: page.meta?.description,
+    robots: page.meta?.noindex ? { index: false } : undefined,
+  }
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<PageParams>
+}) {
+  const { slug } = await params
+  const payload = await getPayload({ config })
+
+  const { docs } = await payload.find({
+    collection: 'pages',
+    where: { slug: { equals: slug.join('/') } },
+    limit: 1,
+  })
+
+  const page = docs[0] as any
+  if (!page) notFound()
+
+  // Handle pages without content
+  if (!page.puckData) {
+    return (
+      <div className="container mx-auto py-12 text-center">
+        <h1 className="text-2xl font-bold mb-4">{page.title}</h1>
+        <p className="text-muted-foreground">
+          This page has no content yet. Edit it in the admin panel.
+        </p>
+      </div>
+    )
+  }
+
+  // Find the layout definition based on page's pageLayout setting
+  // Use your custom siteLayouts instead of DEFAULT_LAYOUTS for header/footer
+  const layouts = DEFAULT_LAYOUTS // Replace with: siteLayouts
+  const pageLayout = page.puckData?.root?.props?.pageLayout || 'default'
+  const layout = layouts.find((l) => l.value === pageLayout)
+
+  return (
+    <LayoutWrapper layout={layout}>
+      <PageRenderer
+        data={page.puckData as PuckData}
+        config={baseConfig}
+        // Optional: Custom theme - uncomment after creating puck-theme.ts
+        // theme={puckTheme}
+      />
+    </LayoutWrapper>
+  )
+}