Add slots API

[chrisvxd]

Introduce the slots API, the main feature to achieve #255. The ticket should likely not be closed until the migration strategy is determined, which may be part of a follow-on.

API

Slots are like DropZones, but as a field, with the data stored on the prop.

{
  fields: {
    content: { type: "slot" }
  },
  render: ({ content: Content }) => (
    <div>< Content  /></div>
  )
}

The data format follows the standard Puck data format for content, and supports all standard component APIs including defaultProps and resolveData:

{
  defaultProps: {
    children: [
      {
        type: "Heading",
        props: {
          id: "123456789",
          title: "I'm inside a slot"
        }
      }
    ]
  }
}

This unlocked powerful patterns like the new Template demo component which allows you to save and load pre-configured templates of components.

This model is deterministic, making it possible easily convert it into other formats (like XML), or render in third party environments (even outside of React). For example, you could use react-from-json:

import React from "react";
import ReactFromJSON from "react-from-json";

const entry = {
  type: "Foo",
  props: {
    children: [
      {
        type: "Bar",
        props: {
          baz: "Hello, world",
        },
      },
    ],
  },
};

const mapping = {
  Foo: ({ children }) => (
    <div>
      <div>{children}</div>
    </div>
  ),
  Bar: ({ baz }) => <span>{baz}</span>,
};

const Example = () => {
  return <ReactFromJSON entry={entry} mapping={mapping} />;
};

Drive-by features

• New trigger parameter provided to resolveData to determine what behaviour caused the data resolution (params.changed flags all fields as true on initialization in resolveData method #963)
• Expose RootConfig type
• Implement replaceRoot action for changing root values specifically (NB may become irrelevant after full migration to slots)

Migration

This change is backwards compatible, but it does deprecate DropZones. The PR includes a migration guide.

Part 2 (ticket TBD) of the deprecation will involve the following breaking changes, and be implemented before v1:

• Complete removal of DropZones and zones
• Migration of content to a child prop on root
• Deprecation of the RSC bundle

Remaining tasks

• Root fields not showing
• Empty arrays pollute index
• Tests
• Permissions
• Store index in history
• Consider removing performance warning
• Consider stripping index from public APIs (history, anything else)
• Docs
• Remove or tidy debug plugin
• Add deprecation notice to DropZone
• Follow ons
  • Consider rendering mode (interactive vs preview) to slot field
  • Add DropZones to Slots support to “migrate()” helper
  • Disable drag of all slot children during resolving
  • Add API to lock DropZone, used for templates
  • Expose slot helper utils, possibly as separate library (walkTree, mapSlots, randomizeIds), etc
  • Create part 2 migration ticket

---

Closes #255, closes #963, closes #950, closes #862

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
puck-demo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 21, 2025 2:02pm
puck-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 21, 2025 2:02pm