@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/api-reference/configuration/component-config.md

@@ -0,0 +1,569 @@
+# ComponentConfig
+
+The configuration for each component defined in [`Config`](/docs/api-reference/configuration/config).
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                                    | Example                                         | Type     | Status   |
+| -------------------------------------------------------- | ----------------------------------------------- | -------- | -------- |
+| [`render()`](#renderprops)                               | `render: () => <div />`                         | Function | Required |
+| [`fields`](#fields)                                      | `fields: { title: { type: "text"} }`            | Object   | -        |
+| [`defaultProps`](#defaultprops)                          | `defaultProps: { title: "Hello, world" }`       | Object   | -        |
+| [`inline`](#inline)                                      | `inline: true`                                  | Boolean  | -        |
+| [`label`](#label)                                        | `label: "Heading Block"`                        | String   | -        |
+| [`metadata`](#metadata)                                  | `metadata: {}`                                  | Object   | -        |
+| [`permissions()`](#permissions)                          | `permissions: { delete: false }`                | Object   | -        |
+| [`resolveData()`](#resolvedatadata-params)               | `resolveData: async ({ props }) => ({ props })` | Object   | -        |
+| [`resolveFields()`](#resolvefieldsdata-params)           | `resolveFields: async ({ props }) => ({})`      | Object   | -        |
+| [`resolvePermissions()`](#resolvepermissionsdata-params) | `resolvePermissions: async ({ props }) => ({})` | Object   | -        |
+
+## Required params
+
+### `render(props)`
+
+A render function to render your component. Receives props as defined in `fields`, and some internal Puck props.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      render: () => <h1>Hello, world</h1>,
+    },
+  },
+};
+```
+
+#### Render props
+
+| Arg                                             | Example       | Type     |
+| ----------------------------------------------- | ------------- | -------- |
+| [`id`](#id)                                     | `button-1234` | String   |
+| [`puck.dragRef`](#puckdragref)                  | `null`        | Function |
+| [`puck.isEditing`](#puckisediting)              | `false`       | Boolean  |
+| [`puck.metadata`](/docs/api-reference/metadata) | `{}`          | Object   |
+| [`puck.renderDropZone`](#puckrenderdropzone)    | `() => {}`    | Function |
+| [`...props`](#props)                            | `{}`          | Object   |
+
+##### `id`
+
+A unique identifier for the component. Auto-generated by default.
+
+##### `puck.dragRef`
+
+A `ref` that tells Puck which element is draggable. Apply this to your components when using the [`inline` parameter](#inline) for advanced CSS layouts.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      inline: true,
+      render: ({ puck: { dragRef } }) => {
+        return <div ref={dragRef}>Hello, world</div>;
+      },
+    },
+  },
+};
+```
+
+##### `puck.isEditing`
+
+A boolean describing whether or not this component is being rendered in the `<Puck>` component.
+
+##### `puck.metadata`
+
+An object containing the global metadata provided to the [`<Puck>`](/docs/api-reference/components/puck#metadata) or [`<Render>`](/docs/api-reference/components/render#metadata) component, merged with any metadata defined in this [component's config](#metadata).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      inline: true,
+      render: ({ text, puck: { metadata } }) => {
+        return <div>Hello, {metadata.text || text}</div>;
+      },
+    },
+  },
+};
+```
+
+##### `puck.renderDropZone`
+
+> **Note:** `puck.renderDropZone` and the [`<DropZone>` component](/docs/api-reference/components/drop-zone) are deprecated in favor of the [`slot` field](/docs/api-reference/fields/slot), and will be removed in a future release. For migration notes, see [these docs](/docs/guides/migrations/dropzones-to-slots).
+
+A render method that creates a [`<DropZone>`](/docs/api-reference/components/drop-zone) for creating nested components. Use this method instead of the `<DropZone>` when implementing React server components.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: ({ puck: { renderDropZone } }) => {
+        return <div>{renderDropZone({ zone: "my-content" })}</div>;
+      },
+    },
+  },
+};
+```
+
+##### `...props`
+
+The remaining props are provided by the user-defined [fields](#fields).
+
+## Optional params
+
+### `fields`
+
+An object describing which [`Field`](/docs/api-reference/fields) to show for each prop passed to the component.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
+```
+
+### `defaultProps`
+
+Default props to apply to a new instance of the component.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      defaultProps: { title: "Hello, world" },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
+```
+
+### `inline`
+
+Render your component without a wrapping element. Use this to [create advanced CSS layouts](/docs/integrating-puck/multi-column-layouts#advanced-css-layouts). Defaults to `false`.
+
+When `true`, you must to specify which item is draggable via the [`puck.dragRef` prop](#puckdragref).
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      inline: true,
+      render: ({ puck }) => <h1 ref={puck.dragRef}>Hello, World</h1>,
+    },
+  },
+};
+```
+
+### `label`
+
+A label to show when referring to your component within the Puck editor. Defaults to the key of your component.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      label: "Heading Block",
+      render: () => <h1>Hello, World</h1>,
+    },
+  },
+};
+```
+
+### `metadata`
+
+An object containing any additional values. Provided to their [`render`](#renderprops) and [`resolveData`](#resolvedatadata-params) functions.
+
+Will be merged with the global `metadata` prop provided to the [`<Puck>`](/docs/api-reference/components/puck#metadata) or [`<Render>`](/docs/api-reference/components/render#metadata) component, overriding any keys with the same name.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      metadata: {
+        title: "Hello, world",
+      },
+      render: ({ puck }) => <h1>{puck.metadata.title}</h1>,
+    },
+  },
+};
+```
+
+### `permissions`
+
+Set the [permissions](/docs/api-reference/permissions) for all instances of a component to toggle functionality. Inherits [global permissions](/docs/api-reference/components/puck/#permissions).
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      permissions: {
+        delete: false, // Disable deletion of all HeadingBlock instances
+      },
+      render: () => <h1>Hello, World</h1>,
+    },
+  },
+};
+```
+
+### `resolveData(data, params)`
+
+Dynamically change the props and set fields as read-only. Supports asynchronous calls.
+
+This function is triggered when [`<Puck>`](/docs/api-reference/components/puck) renders, when a field is changed, when the [`resolveAllData` function](/docs/api-reference/functions/resolve-all-data) is called, or when the component is moved to a different parent.
+
+File: `Example mapping 'title' to 'resolvedTitle'`
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      resolveData: async ({ props }) => {
+        return {
+          props: { resolvedTitle: props.title },
+          readOnly: { resolvedTitle: true },
+        };
+      },
+      render: ({ resolvedTitle }) => <h1>{resolvedTitle}</h1>,
+    },
+  },
+};
+```
+
+#### Args
+
+| Prop     | Example                                                                        | Type   |
+| -------- | ------------------------------------------------------------------------------ | ------ |
+| `data`   | `{ props: { title: "Hello, world" }, readOnly: {} }`                           | Object |
+| `params` | `{ changed: { title: true }, metadata: { foo: "bar" }, parent: {}, root: {} }` | Object |
+
+##### `data.props`
+
+The current props for the component.
+
+```tsx
+const resolveData = async ({ props }) => {
+  return {
+    props: { resolvedTitle: props.title },
+  };
+};
+```
+
+##### `data.readOnly`
+
+The fields currently set to read-only for this component.
+
+##### `params.changed`
+
+An object describing which props have changed on this component since the last time `resolveData` was called.
+
+File: `Example only updating 'resolvedTitle' when 'title' changes`
+
+```tsx
+const resolveData = async ({ props }, { changed }) => {
+  if (!changed.title) {
+    return { props };
+  }
+
+  return {
+    props: { resolvedTitle: props.title },
+  };
+};
+```
+
+##### `params.lastData`
+
+The data object from the previous run of this function.
+
+##### `params.metadata`
+
+An object containing the global metadata provided to the [`<Puck>`](/docs/api-reference/components/puck#metadata) or [`<Render>`](/docs/api-reference/components/render#metadata) component, merged with any metadata defined in this [component's config](#metadata).
+
+File: `Example only updating 'resolvedTitle' when 'title' changes`
+
+```tsx
+const resolveData = async ({ props }, { metadata }) => {
+  return {
+    props: { title: metadata.title || props.title },
+  };
+};
+```
+
+##### `params.parent`
+
+The [component data](/docs/api-reference/data-model/component-data) of the parent.
+
+If the parent implements [resolveData](#resolvedatadata-params), this parameter will return the unresolved data on initial render, as resolvers are executed bottom-up.
+
+##### `params.root`
+
+The [root data](/docs/api-reference/data-model/root-data) for the current document. Useful for resolving a component's props based on values stored on the root.
+
+File: `Example using a root prop to resolve the title`
+
+```tsx
+const resolveData = async ({ props }, { root }) => {
+  return {
+    props: { title: `${root.props?.title} — ${props.title}` },
+  };
+};
+```
+
+##### `params.trigger`
+
+The event that triggered this resolveData call. One of:
+
+- `insert` - the component was inserted
+- `replace` - the component was replaced, such as when a field value is changed
+- `move` - the component moved between parents
+- `load` - the Puck editor was loaded
+- `force` - an execution was forced via the [`resolveAllData` function](/docs/api-reference/functions/resolve-all-data)
+
+#### Returns
+
+| Prop   | Example                                              | Type   |
+| ------ | ---------------------------------------------------- | ------ |
+| `data` | `{ props: { title: "Hello, world" }, readOnly: {} }` | Object |
+
+##### `data.props`
+
+A partial props object containing modified props. Will be spread into the other props.
+
+File: `Example only updating resolvedTitle when title changes`
+
+```tsx
+const resolveData = async ({ props }) => {
+  return {
+    props: { resolvedTitle: props.title },
+  };
+};
+```
+
+##### `data.readOnly`
+
+A partial object describing fields to set as readonly. Will be spread into the existing readOnly state.
+
+File: `Example only updating resolvedTitle when title changes`
+
+```tsx
+const resolveData = async ({ props }) => {
+  return {
+    props: { resolvedTitle: props.title },
+    readOnly: { resolvedTitle: true }, // Make the `resolvedTitle` field read-only
+  };
+};
+```
+
+### `resolveFields(data, params)`
+
+Dynamically set the fields for this component. Supports asynchronous calls.
+
+This function is triggered when the component data changes.
+
+File: `Example changing one field based on another`
+
+```tsx
+const config = {
+  components: {
+    MyComponent: {
+      resolveFields: (data) => {
+        const fields = {
+          drink: {
+            type: "radio",
+            options: [
+              { label: "Water", value: "water" },
+              { label: "Orange juice", value: "orange-juice" },
+            ],
+          },
+        };
+
+        if (data.props.drink === "water") {
+          return {
+            ...fields,
+            waterType: {
+              // ... Define field
+            },
+          };
+        }
+
+        return fields;
+      },
+      // ...
+    },
+  },
+};
+```
+
+#### Args
+
+| Prop     | Example                                                                               | Type   |
+| -------- | ------------------------------------------------------------------------------------- | ------ |
+| `data`   | `{ props: { title: "Hello, world" }, readOnly: {} }`                                  | Object |
+| `params` | `{ appState: {}, changed: {}, fields: {}, lastData: {}, lastFields: {}, parent: {} }` | Object |
+
+##### `data.props`
+
+The current props for the selected component.
+
+##### `data.readOnly`
+
+The fields currently set to read-only for this component.
+
+##### `params.appState`
+
+An object describing the [AppState](/docs/api-reference/data-model/app-state).
+
+##### `params.changed`
+
+An object describing which props have changed on this component since the last time this function was called.
+
+File: `Example only updating the fields when 'fieldType' changes`
+
+```tsx
+const resolveFields = async ({ props }, { changed, lastFields }) => {
+  if (!changed.fieldType) {
+    return lastFields;
+  }
+
+  return {
+    title: {
+      type: fieldType,
+    },
+  };
+};
+```
+
+##### `params.fields`
+
+The static fields for this component as defined by [`fields`](#fields).
+
+##### `params.lastData`
+
+The data object from the previous run of this function.
+
+##### `params.lastFields`
+
+The last fields object created by the previous run of this function.
+
+##### `params.metadata`
+
+An object containing the global metadata provided to the [`<Puck>`](/docs/api-reference/components/puck#metadata) or [`<Render>`](/docs/api-reference/components/render#metadata) component, merged with any metadata defined in this [component's config](#metadata).
+
+##### `params.parent`
+
+The parent data object if this item is within a [DropZone](/docs/api-reference/components/drop-zone).
+
+### `resolvePermissions(data, params)`
+
+Dynamically set the [permissions](/docs/api-reference/permissions) for this component to toggle functionality. Can be used to control the permissions on a specific component instance. Inherits [`permissions`](#permissions). Supports asynchronous calls.
+
+This function is triggered when [`<Puck>`](/docs/api-reference/components/puck) renders, when the component is inserted, when its data changes, or when it's moved to a different parent.
+
+File: `Setting permissions for a specific instance`
+
+```tsx
+const config = {
+  components: {
+    MyComponent: {
+      resolvePermissions: (data, { permissions }) => {
+        if (data.props.id === "MyComponent-1234") {
+          return {
+            delete: false, // Disable deletion on component with id MyComponent-1234
+          };
+        }
+
+        return { permissions }; // Fallback to inherited permissions
+      },
+      // ...
+    },
+  },
+};
+```
+
+#### Args
+
+| Prop     | Example                                                                                         | Type   |
+| -------- | ----------------------------------------------------------------------------------------------- | ------ |
+| `data`   | `{ props: { title: "Hello, world" }, readOnly: {} }`                                            | Object |
+| `params` | `{ appState: {}, changed: {}, permissions: {}, lastData: {}, lastPermissions: {}, parent: {} }` | Object |
+
+##### `data.props`
+
+The current props for the selected component.
+
+##### `data.readOnly`
+
+The fields currently set to read-only for this component.
+
+##### `params.appState`
+
+An object describing the [AppState](/docs/api-reference/data-model/app-state).
+
+##### `params.changed`
+
+An object describing which props have changed on this component since the last time this function was called. This helps prevent duplicate calls when making async operations.
+
+File: `Example only updating the permissions when 'example' prop changes`
+
+```tsx
+const resolvePermissions = async ({ props }, { changed, lastPermissions }) => {
+  if (!changed.example) {
+    return lastPermissions; // Return the last permissions unless the `example` prop has changed
+  }
+
+  return await expensiveAsyncOperation();
+};
+```
+
+##### `params.permissions`
+
+The static fields for this component as defined by [`permissions`](#permissions).
+
+##### `params.lastData`
+
+The data object from the previous run of this function.
+
+##### `params.lastPermissions`
+
+The last permissions object created by the previous run of this function.
+
+##### `params.parent`
+
+The [component data](/docs/api-reference/data-model/component-data) of the parent.
+
+If the parent implements [resolveData](#resolvedatadata-params), this parameter will return the unresolved data on initial render.
+
+#### Returns
+
+A [`fields`](#fields) object.

package/dist/docs/api-reference/configuration/config.md

@@ -0,0 +1,108 @@
+# Config
+
+The main configuration object describing what Puck can render.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        children: {
+          type: "text",
+        },
+      },
+      render: ({ children }) => {
+        return <h1>{children}</h1>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                       | Example                                                        | Type                                                                    | Status   |
+| --------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- | -------- |
+| [`components`](#components) | `components: { HeadingBlock: {{ render: () => <h1 /> } }`      | Object                                                                  | Required |
+| [`root`](#root)             | `root: { render: () => <div /> }`                              | [`ComponentConfig`](/docs/api-reference/configuration/component-config) | -        |
+| [`categories`](#categories) | `categories: { typography: { components: ["HeadingBlock"] } }` | Object                                                                  | -        |
+
+## Required params
+
+### `components`
+
+An object describing the components available to Puck. Each component definition implements the [`ComponentConfig` API](/docs/api-reference/configuration/component-config).
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        children: {
+          type: "text",
+        },
+      },
+      render: ({ children }) => {
+        return <h1>{children}</h1>;
+      },
+    },
+  },
+};
+```
+
+## Optional params
+
+### `root`
+
+An object describing the root of your component tree. This component wraps the rest of your components. Implements the [`ComponentConfig` API](/docs/api-reference/configuration/component-config).
+
+- You must return children to render the default content.
+
+```tsx
+const config = {
+  root: {
+    render: ({ children }) => {
+      return <div>{children}</div>;
+    },
+  },
+  // ...
+};
+```
+
+### `categories`
+
+An object describing categories for your components. Will be used to group the components in the left side-bar.
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["HeadingBlock"],
+    },
+  },
+  // ...
+};
+```
+
+#### `categories[key].components`
+
+An array of components in this category.
+
+- Must use names of [`components`](#components).
+- A component can appear in more than one category.
+
+#### `categories[key].title`
+
+The user-facing title for the category. Will use the `category` key if not provided.
+
+#### `categories[key].visible`
+
+A boolean describing whether or not the category should be visible in the side bar. **Defaults to `true`**.
+
+#### `categories[key].defaultExpanded`
+
+A boolean describing whether or not the category should be expanded by default in the side bar. **Defaults to `true`**.
+
+#### `categories["other"]`
+
+The default category for all uncategorized components. Receives all other categories params.

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

@@ -0,0 +1,4 @@
+# Configuration
+
+- [Config](/docs/api-reference/configuration/config) - The main configuration object describing what Puck can render.
+- [ComponentConfig](/docs/api-reference/configuration/component-config) - The configuration of each component defined in the main config.