@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/api-reference/fields/slot.md

@@ -0,0 +1,302 @@
+# Slot
+
+Define a drag-and-drop area containing nested components. Extends [Base](/docs/api-reference/fields/base).
+
+- This field produces an array of [ComponentData](/docs/api-reference/data-model/component-data)
+- The array is transformed to a [render function](#render-function) before being provided to `render()`
+
+This field does render any UI in the form section.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      render: ({ content: Content }) => {
+        return <Content />;
+      },
+    },
+    Card: {
+      render: () => <div>Hello, world</div>,
+    },
+  },
+};
+```
+
+## TypeScript
+
+When using TypeScript, make sure to use the `Slot` type so the render prop is correctly transformed.
+
+```tsx
+import { Slot } from "@puckeditor/core";
+
+type Props = {
+  Example: {
+    content: Slot; // Converted from the ComponentData[] type into a render function
+  };
+};
+```
+
+## Params
+
+| Param                   | Example                      | Type   | Status   |
+| ----------------------- | ---------------------------- | ------ | -------- |
+| [`type`](#type)         | `type: "slot"`               | "slot" | Required |
+| [`allow`](#allow)       | `allow: ["HeadingBlock"]`    | Array  | -        |
+| [`disallow`](#disallow) | `disallow: ["HeadingBlock"]` | Array  | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"slot"` for Slot fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Optional params
+
+### `allow`
+
+Only allow specific components to be dragged into the slot. Will be overwritten by the [`allow` prop](#allow-1) provided to the render function.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+          allow: ["HeadingBlock"],
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `disallow`
+
+Allow all but specific components to be dragged into the slot. Any items in `allow` will override `disallow`. Will be overwritten by the [`disallow` prop](#disallow-1) provided to the render function.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+          disallow: ["HeadingBlock"],
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Render function
+
+Slot data is provided to `render()` as a render function (or component). Provide props to this function to customize the behavior of the slot at render-time.
+
+| Param                               | Example                      | Type                                 | Status |
+| ----------------------------------- | ---------------------------- | ------------------------------------ | ------ |
+| [`allow`](#allow-1)                 | `allow: ["HeadingBlock"]`    | Array                                | -      |
+| [`as`](#as)                         | `as: "span"`                 | ElementType                          | -      |
+| [`className`](#classname)           | `className: "MyClass"`       | String                               | -      |
+| [`collisionAxis`](#collisionaxis)   | `collisionAxis: "x"`         | String                               | -      |
+| [`disallow`](#disallow-1)           | `disallow: ["HeadingBlock"]` | Array                                | -      |
+| [`minEmptyHeight`](#minemptyheight) | `minEmptyHeight: "256px"`    | CSSProperties["minHeight"] \| number | -      |
+| [`ref`](#ref)                       | `ref: ref`                   | Ref                                  | -      |
+| [`style`](#style)                   | `style: {display: "flex"}`   | CSSProperties                        | -      |
+
+### `allow`
+
+Only allow specific components to be dragged into the slot. Overrides the [`allow` parameter](#allow) provided to the field.
+
+> **Note:** Drag-and-drop in the outline does not respect this prop. Prefer the [`allow`
+> field parameter](#allow), which is enforced everywhere.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content allow={["HeadingBlock"]} />;
+      },
+    },
+  },
+};
+```
+
+### `as`
+
+Render a custom element or component for the slot.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content as="table" />;
+      },
+    },
+  },
+};
+```
+
+Any additional props are forwarded to the element or component provided via `as`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content as="details" open />;
+      },
+    },
+  },
+};
+```
+
+The following props are **not** forwarded to the `as` element, because Puck either consumes them internally or they are incompatible with slots:
+
+| Prop                      | Reason                              |
+| ------------------------- | ----------------------------------- |
+| `zone`                    | Identifies the drop zone internally |
+| `content`                 | Injected by Puck internally         |
+| `config`                  | Injected by Puck internally         |
+| `metadata`                | Injected by Puck internally         |
+| `dangerouslySetInnerHTML` | Isn't compatible with Puck slots    |
+| `children`                | Isn't compatible with Puck slots    |
+
+### `className`
+
+Provide a className to the rendered element. The default styles will still be applied.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content className="MyComponent" />;
+      },
+    },
+  },
+};
+```
+
+### `collisionAxis`
+
+Configure which axis Puck will use for overlap collision detection.
+
+Options:
+
+- `x` - detect collisions based their x-axis overlap
+- `y` - detect collisions based their y-axis overlap
+- `dynamic` - automatically choose an axis based on the direction of travel
+
+The defaults are set based on the CSS layout of the parent:
+
+- grid: `dynamic`
+- flex (row): `x`
+- inline/inline-block: `x`
+- Everything else: `y`
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content collisionAxis="dynamic" />;
+      },
+    },
+  },
+};
+```
+
+### `disallow`
+
+Allow all but specific components to be dragged into the slot. Any items in `allow` will override `disallow`.
+
+> **Note:** Drag-and-drop in the outline does not respect this prop. Prefer the
+> [`disallow` field parameter](#disallow), which is enforced everywhere.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content }) => {
+        return <Content disallow={["HeadingBlock"]} />;
+      },
+    },
+  },
+};
+```
+
+### `minEmptyHeight`
+
+The minimum height of the slot when empty. Defaults to `128px`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return <Content minEmptyHeight="256px" />;
+      },
+    },
+  },
+};
+```
+
+### `ref`
+
+A [React ref](https://react.dev/learn/manipulating-the-dom-with-refs), assigned to the root node of the slot.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        const ref = useRef();
+
+        return <Content ref={ref} />;
+      },
+    },
+  },
+};
+```
+
+### `style`
+
+Provide a style attribute to the slot. The default styles will still be applied.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content style={{ display: "flex" }} />;
+      },
+    },
+  },
+};
+```

package/dist/docs/api-reference/fields/text.md

@@ -0,0 +1,93 @@
+# Text
+
+Render a `text` input. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      render: ({ title }) => {
+        return <p>{title}</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                 | Example                         | Type    | Status   |
+| ------------------------------------- | ------------------------------- | ------- | -------- |
+| [`type`](#type)                       | `type: "text"`                  | "text"  | Required |
+| [`contentEditable`](#contentEditable) | `contentEditable: true`         | Boolean | -        |
+| [`placeholder`](#placeholder)         | `placeholder: "Lorem ipsum..."` | String  | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"text"` for Text fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "text",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Optional params
+
+### contentEditable
+
+Enable inline text editing for this field. Defaults to `false`.
+
+> **Warning:** When setting `contentEditable`, your [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) prop will be converted to an [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) when rendered inside [`<Puck>`](/docs/api-reference/components/puck) (but not [`<Render>`](/docs/api-reference/components/render)). When using TypeScript, change your `string` to  `string | ReactNode`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "text",
+          contentEditable: true,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Placeholder
+
+The placeholder text to display when the field is empty.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "text",
+          placeholder: "Lorem ipsum...",
+        },
+      },
+      // ...
+    },
+  },
+};
+```

package/dist/docs/api-reference/fields/textarea.md

@@ -0,0 +1,93 @@
+# Textarea
+
+Render a `textarea` input. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        description: {
+          type: "textarea",
+        },
+      },
+      render: ({ description }) => {
+        return <p>{description}</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                 | Example                         | Type       | Status   |
+| ------------------------------------- | ------------------------------- | ---------- | -------- |
+| [`type`](#type)                       | `type: "textarea"`              | "textarea" | Required |
+| [`contentEditable`](#contentEditable) | `contentEditable: true`         | Boolean    | -        |
+| [`placeholder`](#placeholder)         | `placeholder: "Lorem ipsum..."` | String     | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"textarea"` for Textarea fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        description: {
+          type: "textarea",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Optional params
+
+### contentEditable
+
+Enable inline text editing for this field. Defaults to `false`.
+
+> **Warning:** When setting `contentEditable`, your [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) prop will be converted to an [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) when rendered inside [`<Puck>`](/docs/api-reference/components/puck) (but not [`<Render>`](/docs/api-reference/components/render)). When using TypeScript, change your `string` to  `string | ReactNode`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        description: {
+          type: "textarea",
+          contentEditable: true,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Placeholder
+
+The placeholder text to display when the field is empty.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        description: {
+          type: "textarea",
+          placeholder: "Lorem ipsum...",
+        },
+      },
+      // ...
+    },
+  },
+};
+```

package/dist/docs/api-reference/fields.md

@@ -0,0 +1,16 @@
+# Fields
+
+A field represents a user input shown in the Puck interface.
+
+- [Base](/docs/api-reference/fields/base) - The base type shared by all fields.
+- [Array](/docs/api-reference/fields/array) - Render a list of items with a subset of fields.
+- [Custom](/docs/api-reference/fields/custom) - Implement a field with a custom UI.
+- [External](/docs/api-reference/fields/external) - Select data from a list, typically populated via a third-party API.
+- [Number](/docs/api-reference/fields/number) - Render a `number` input.
+- [Object](/docs/api-reference/fields/object) - Render a subset of fields.
+- [Radio](/docs/api-reference/fields/radio) - Render a `radio` input with a list of options.
+- [RichText](/docs/api-reference/fields/richtext) - Render a rich text editor.
+- [Select](/docs/api-reference/fields/select) - Render a `select` input with a list of options.
+- [Slot](/docs/api-reference/fields/slot) - Define an area containing nested components.
+- [Text](/docs/api-reference/fields/text) - Render a `text` input.
+- [Textarea](/docs/api-reference/fields/textarea) - Render a `textarea` input.

package/dist/docs/api-reference/functions/migrate.md

@@ -0,0 +1,204 @@
+# migrate
+
+Migrate the [Data payload](/docs/api-reference/data-model/data) to the latest shape, automatically transforming deprecated data.
+
+```tsx
+import { migrate } from "@puckeditor/core";
+
+migrate(legacyData);
+```
+
+## Migrations
+
+### Root data to props
+
+Migrates any props stored on root data to the `props` object.
+
+**Before**
+
+```json
+{
+  "root": {
+    "title": "Hello, world"
+  }
+}
+```
+
+**After**
+
+```json
+{
+  "root": {
+    "props": { "title": "Hello, world" }
+  }
+}
+```
+
+### DropZones to slots
+
+Migrates all [DropZone](/docs/api-reference/components/drop-zone) data from [`zones`](/docs/api-reference/data-model/data#zones) to inline [slots](/docs/api-reference/fields/slot). Requires slots to be provided via the [`config`](#config) arg, where the field name for the slot matches the `zone` prop of the DropZone. See the [DropZone to slots migration guide](/docs/guides/migrations/dropzones-to-slots) for more information.
+
+**Before**
+
+```json
+{
+  "content": [
+    {
+      "type": "Grid",
+      "props": {
+        "id": "Grid-12345"
+      }
+    }
+  ],
+  "zones": {
+    "Grid-12345:items": [
+      {
+        "type": "HeadingBlock",
+        "props": {
+          "id": "Heading-12345",
+          "title": "Hello, world"
+        }
+      }
+    ]
+  }
+}
+```
+
+**After**
+
+```json
+{
+  "content": [
+    {
+      "type": "Grid",
+      "props": {
+        "id": "Grid-12345",
+        "items": [
+          {
+            "type": "HeadingBlock",
+            "props": {
+              "id": "Heading-12345",
+              "title": "Hello, world"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Args
+
+| Param                                   | Example                                       | Type                                               | Status   |
+| --------------------------------------- | --------------------------------------------- | -------------------------------------------------- | -------- |
+| [`data`](#data)                         | `{ content: [{type: "Heading", props: {} }]}` | [Data](/docs/api-reference/data-model/data)        | Required |
+| [`config`](#config)                     | `{ components: {} }`                          | [Config](/docs/api-reference/configuration/config) | -        |
+| [`migrationOptions`](#migrationoptions) | `{ migrateDynamicZonesForComponent: {} }`     | [MigrationOptions](#migrationoptions-type)         | -        |
+
+### `data`
+
+The legacy data you want to transform.
+
+### `config`
+
+A [config](/docs/api-reference/configuration/config) object. Required if migrating data with [slots](/docs/api-reference/fields/slot).
+
+### `migrationOptions`
+
+Options to customize how data is migrated.
+
+#### `migrateDynamicZonesForComponent`
+
+An object mapping component names to custom dropzone migration functions. The function will be called for any component with DropZones that don't have a slot field definition with a matching name in the config.
+
+Each migration function receives:
+
+- `props`: The current component props
+- `zones`: A record of zone names to their content
+
+The function should return the updated component props with the migrated zone data.
+
+```tsx
+migrate(legacyData, config, {
+  migrateDynamicZonesForComponent: {
+    Columns: (props, zones) => {
+      return {
+        ...props,
+        columns: Object.values(zones).map((zone) => ({
+          column: zone,
+        })),
+      };
+    },
+  },
+});
+```
+
+**Before**
+
+```json
+{
+  "root": {
+    "props": {
+      "title": "Legacy Zones Migration"
+    }
+  },
+  "content": [
+    {
+      "type": "Columns",
+      "props": {
+        "columns": [{}],
+        "id": "Columns-eb9dfe22-4408-44e6-b8e5-fbaedbbdb3be"
+      }
+    }
+  ],
+  "zones": {
+    "Columns-eb9dfe22-4408-44e6-b8e5-fbaedbbdb3be:column-0": [
+      {
+        "type": "Text",
+        "props": {
+          "text": "Drop zone 1",
+          "id": "Text-c2b5c0a5-d76b-4120-8bb3-99934e119967"
+        }
+      }
+    ]
+  }
+}
+```
+
+**After**
+
+```json
+{
+  "root": {
+    "props": {
+      "title": "Legacy Zones Migration"
+    }
+  },
+  "content": [
+    {
+      "type": "Columns",
+      "props": {
+        "columns": [
+          {
+            "column": [
+              {
+                "type": "Text",
+                "props": {
+                  "text": "Drop zone 1",
+                  "id": "Text-c2b5c0a5-d76b-4120-8bb3-99934e119967"
+                }
+              }
+            ]
+          }
+        ],
+        "id": "Columns-eb9dfe22-4408-44e6-b8e5-fbaedbbdb3be"
+      }
+    }
+  ]
+}
+```
+
+## Returns
+
+The updated [Data](/docs/api-reference/data-model/data) object.