npm package: @siteproof/react
Description: React components for SiteProof visual editor — Provider, Editable, EditableCollection, and hooks
Author: Phoenix AI Consulting, LLC
Latest version: 0.1.3

# @siteproof/react

React components for [SiteProof](https://siteproof.dev) visual editor integration. Provides `<SiteProofProvider>`, `<Editable>`, `<EditableCollection>`, and content-fetching hooks.

## Installation

```bash
npm install @siteproof/sdk @siteproof/react
```

## Components

### `<SiteProofProvider>`

Wrap your app's root layout. In production, renders children as-is (zero overhead). In editor mode, initializes the PostMessage bridge and field registry.

```tsx
import '../siteproof.config';
import { SiteProofProvider } from '@siteproof/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SiteProofProvider>{children}</SiteProofProvider>
      </body>
    </html>
  );
}
```

### `<Editable>`

Wraps content that clients can edit through the visual editor. In production, renders children unchanged. In editor mode, registers the field, reports its position, and handles inline editing.

```tsx
import { Editable } from '@siteproof/react';

export function Hero() {
  return (
    <section>
      <Editable field="home.hero.title" type="text" label="Hero Title">
        <h1>Welcome to our site</h1>
      </Editable>
      <Editable field="home.hero.image" type="image" label="Hero Image">
        <img src="/hero.jpg" alt="Hero" />
      </Editable>
    </section>
  );
}
```

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `field` | `string` | Unique field path (e.g., `"home.hero.title"`) |
| `type` | `"text" \| "richtext" \| "image" \| "toggle" \| "collection"` | Field type |
| `label` | `string` | Human-readable label shown in the editor UI |
| `children` | `ReactNode` | The content to wrap |

### `<EditableCollection>`

Wraps repeated content groups (feature cards, testimonials, etc.).

```tsx
import { EditableCollection } from '@siteproof/react';

export function Features({ features }) {
  return (
    <EditableCollection field="home.features" label="Features">
      {features.map(f => <FeatureCard key={f.id} {...f} />)}
    </EditableCollection>
  );
}
```

## Hooks

### `useSiteProofContent(collection, options?)`

Fetches content from a Payload CMS collection.

```tsx
const page = useSiteProofContent<PageData>('pages', {
  where: { slug: { equals: 'home' } }
});
```

### `useSiteProofCollection(collection, options?)`

Fetches multiple items from a collection.

```tsx
const posts = useSiteProofCollection<Post>('posts', {
  limit: 10,
  sort: '-createdAt'
});
```

### `useEditorContext()`

Access the editor context (active field, editor state, etc.).

```tsx
const { isEditorMode, activeField } = useEditorContext();
```

## How It Works

The SDK has two modes:

- **Production**: All components are transparent wrappers. `<Editable>` renders `{children}` directly. `<SiteProofProvider>` renders `<>{children}</>`. No runtime cost.
- **Editor mode**: Detected automatically when loaded inside SiteProof's editor iframe. Components register fields, report positions via `IntersectionObserver`, and handle PostMessage-based inline editing.

## Peer Dependencies

- `react` >= 18.0.0
- `react-dom` >= 18.0.0

## License

MIT - Phoenix AI Consulting, LLC