npm package: @orion-studios/payload-visual-builder
Description: Visual drag-and-drop page editor for Payload CMS
Author: Orion Studios
Latest version: 0.1.4

# @orion-studios/payload-visual-builder

Visual drag-and-drop page editor for Payload CMS with inline editing, undo/redo, and real-time preview.

## Installation

```bash
npm install @orion-studios/payload-visual-builder
```

## Features

- **Drag-and-Drop Interface**: Reorder blocks with smooth animations
- **Inline Editing**: Edit text directly on the page
- **Undo/Redo**: 120-item history stack
- **Real-time Preview**: See changes instantly
- **PostMessage Communication**: Secure iframe-based architecture
- **Save Draft/Publish**: Direct integration with Payload's draft system
- **TypeScript Support**: Full type definitions

## Usage

### Step 1: Add Visual Builder View to Collection

```typescript
// src/collections/Pages.ts
import { CollectionConfig } from 'payload'
import { getVisualBuilderView } from '@orion-studios/payload-visual-builder'

export const Pages: CollectionConfig = {
  slug: 'pages',
  admin: {
    components: {
      views: {
        edit: {
          visual: getVisualBuilderView(), // Adds "Visual Builder" tab
        },
      },
    },
  },
  fields: [
    {
      name: 'layout',
      type: 'blocks',
      blocks: [...], // Your blocks from payload-blocks
    },
  ],
}
```

### Step 2: Create Builder Route

```typescript
// src/app/(frontend)/builder/[id]/page.tsx
import { createBuilderRoute } from '@orion-studios/payload-visual-builder'
import { getPayloadClient } from '@/lib/payload'

export default async function BuilderPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const payload = await getPayloadClient()

  return createBuilderRoute(payload, id)
}
```

### Step 3: That's It!

Open any page in Payload admin and click the "Visual Builder" tab to start editing visually.

## Customization

### Custom Path and Label

```typescript
import { getVisualBuilderView } from '@orion-studios/payload-visual-builder'

export const Pages: CollectionConfig = {
  admin: {
    components: {
      views: {
        edit: {
          visual: getVisualBuilderView({
            path: '/editor',
            label: 'Page Editor',
          }),
        },
      },
    },
  },
}
```

### Custom Collection

```typescript
// Builder route for custom collection
return createBuilderRoute(payload, id, {
  collection: 'posts',
  depth: 2,
})
```

## How It Works

1. **Iframe Architecture**: The visual builder loads your page in an iframe for isolation
2. **PostMessage API**: Parent and child communicate via secure postMessage
3. **State Management**: Changes are tracked locally with undo/redo support
4. **Save Integration**: Saves directly to Payload's API (draft or published)

## Components

### BuilderPageEditor

The main visual editor component (exported but typically used via `createBuilderRoute`).

### PageVisualEditorView

Server component wrapper for the admin view.

### PageVisualEditorClient

Client component that manages iframe communication and toolbar.

## Requirements

- Payload CMS 3.x
- Next.js 14+ or 15+
- React 18+

## License

MIT © Orion Studios