@delmaredigital/payload-puck 0.1.3 → 0.3.0

package/examples/README.md

@@ -1,247 +0,0 @@
-# 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 "/")
-│   ├── (manage)/
-│   │   └── layout.tsx                # Editor layout (imports Tailwind CSS)
-│   ├── 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 & Layout
-
-```bash
-# Create route group and copy layout (REQUIRED for Tailwind styles)
-mkdir -p src/app/\(manage\)/pages/\[id\]/edit
-cp node_modules/@delmaredigital/payload-puck/examples/app/\(manage\)/layout.tsx src/app/\(manage\)/
-
-# Copy editor page
-cp node_modules/@delmaredigital/payload-puck/examples/app/pages/\[id\]/edit/page.tsx src/app/\(manage\)/pages/\[id\]/edit/
-```
-
-> **Important:** The layout file imports Tailwind CSS. Without it, the editor will be completely unstyled. Update the CSS import path in `layout.tsx` to match your project's globals.css location.
-
-### 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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * 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/(manage)/layout.tsx

@@ -1,31 +0,0 @@
-/**
- * Layout for Puck Editor routes
- *
- * IMPORTANT: This layout must import your Tailwind CSS for the editor to be styled.
- * Update the import path to match your project's globals.css location.
- */
-
-// Import your Tailwind CSS - adjust path as needed
-import '@/app/(frontend)/globals.css'
-// Or if your globals.css is elsewhere:
-// import '@/styles/globals.css'
-// import '../globals.css'
-
-export const metadata = {
-  title: 'Puck Editor',
-  description: 'Visual page editor',
-}
-
-export default function ManageLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  return (
-    // NOTE: data-theme="light" is required if your CSS uses opacity:0 until theme is set
-    // (common FOUC prevention pattern). Adjust to match your theme system.
-    <html lang="en" data-theme="light">
-      <body>{children}</body>
-    </html>
-  )
-}

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

@@ -1,101 +0,0 @@
-/**
- * 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>
-  )
-}