@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/integrating-puck/categories.md

@@ -0,0 +1,92 @@
+# Categories
+
+Categories allow you to group components in the left side bar.
+
+## Creating categories
+
+Use the [`categories` API](/docs/api-reference/configuration/config#categories) to define the component categories.
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["HeadingBlock", "ParagraphBlock"],
+    },
+  },
+  // ...
+};
+```
+
+Components can appear in separate categories:
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["HeadingBlock", "ParagraphBlock"],
+    },
+    foundational: {
+      components: ["HeadingBlock"],
+    },
+  },
+  // ...
+};
+```
+
+You can also change the title, collapse and hide categories:
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["HeadingBlock", "ParagraphBlock"],
+      title: "Text",
+      defaultExpanded: false, // Collapse this category by default
+    },
+    foundational: {
+      components: ["HeadingBlock"],
+      visible: false, // Mark this category as hidden
+    },
+  },
+  // ...
+};
+```
+
+## The "other" category
+
+Any uncategorized components will be grouped in the `other` category. This will be visible by default. It respects the same API as other categories.
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["HeadingBlock", "ParagraphBlock"],
+    },
+    other: {
+      title: "Other components",
+    },
+  },
+  // ...
+};
+```
+
+## TypeScript
+
+You can pass in available category names to the `Config` type if using TypeScript
+
+```tsx
+import type { Config } from "@puckeditor/core";
+
+const config: Config<{}, {}, "typography" | "interactive"> = {
+  categories: {
+    typography: {},
+    interactive: {},
+  },
+  // ...
+};
+```
+
+## Further reading
+
+- [`categories` API reference](/docs/api-reference/configuration/config#categories)
+- [`renderComponentList` API reference](/docs/api-reference/components/puck#rendercomponentlistparams)

package/dist/docs/integrating-puck/component-configuration.md

@@ -0,0 +1,159 @@
+# Component Configuration
+
+Puck's core behaviour is configured via the [Config](/docs/api-reference/configuration/config). This describes:
+
+- which components are available to Puck
+- how to render each component
+- which fields to show when the user selects a component
+- additional information, like [category grouping](/docs/integrating-puck/categories)
+
+The [Config](/docs/api-reference/configuration/config) is provided via the `config` prop to the main Puck components:
+
+- [`<Puck>`](/docs/api-reference/components/puck) reads the Config and renders an editor UI. The user interacts with the editor to produce a [data payload](/docs/api-reference/data-model/data).
+- [`<Render>`](/docs/api-reference/components/render) takes a [data payload](/docs/api-reference/data-model/data) and renders it according to the provided Config.
+
+## The `render` function
+
+Components can be defined via the `components` object in [Config](/docs/api-reference/configuration/config). Every definition must provide a [`render` function](/docs/api-reference/configuration/component-config#renderprops):
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      render: () => {
+        return <h1>Hello, world</h1>;
+      },
+    },
+  },
+};
+```
+
+This tells Puck that **HeadingBlock** is a valid component, and describes how to render it.
+
+When the user drags the component onto the preview and hits **Publish** in the editor UI via the `<Puck>` component, this Config will produce a [data payload](/docs/api-reference/data-model/data) like this:
+
+```json
+{
+  "content": [
+    {
+      "type": "HeadingBlock",
+      "props": {
+        "id": "HeadingBlock-1234"
+      }
+    }
+  ],
+  "root": {}
+}
+```
+
+The data payload and Config together tell `<Render>` how to render the page. It can also be provided to `<Puck>` as an [initial `data` payload](/docs/api-reference/components/puck#data).
+
+### TypeScript
+
+If you're using TypeScript, we recommend strictly typing your config:
+
+```tsx
+import type { Config } from "@puckeditor/core";
+
+type Components = {
+  HeadingBlock: {};
+};
+
+const config: Config<Components> = {
+  components: {
+    HeadingBlock: {
+      render: () => {
+        return <h1>Hello, world</h1>;
+      },
+    },
+  },
+};
+```
+
+## Adding fields
+
+[Fields](/docs/api-reference/fields) allow users to provide input to components. The value of each field is passed in as a prop to the `render` function.
+
+You can define a field via the [`fields` parameter](/docs/api-reference/configuration/component-config#fields):
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      render: ({ title }) => {
+        return <h1>{title}</h1>;
+      },
+    },
+  },
+};
+```
+
+This will render a [Text field](/docs/api-reference/fields/text) when the user selects an instance of the **HeadingBlock** component in the editor UI.
+
+When the user modifies the input, the editor will produce a data payload like this:
+
+```json
+{
+  "content": [
+    {
+      "type": "HeadingBlock",
+      "props": {
+        "id": "HeadingBlock-1234",
+        "title": "Hello, world"
+      }
+    }
+  ],
+  "root": {}
+}
+```
+
+### TypeScript
+
+It's best to define the props for the component if using TypeScript. This enables strict type checking for your fields.
+
+```tsx
+import type { Config } from "@puckeditor/core";
+
+type Components = {
+  HeadingBlock: {
+    title: string;
+  };
+};
+
+const config: Config<Components> = {
+  // ...
+};
+```
+
+## Setting default props
+
+Default props allow you to set an initial value for a prop when a new component is added.
+
+Provide an object to the [`defaultProps`](/docs/api-reference/configuration/component-config#fields) parameter to configure this:
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+      },
+      defaultProps: {
+        title: "Hello, world",
+      },
+      render: ({ title }) => {
+        return <h1>{title}</h1>;
+      },
+    },
+  },
+};
+```
+
+Unlike [default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters), `defaultProps` are stored in the data payload and will populate the Puck fields.

package/dist/docs/integrating-puck/data-migration.md

@@ -0,0 +1,86 @@
+# Data Migration
+
+## Version migrating
+
+Puck follows semantic versioning. Major releases may introduce breaking changes for your Data payload.
+
+Puck provides the [`migrate`](/docs/api-reference/functions/migrate) helper method to help migrate legacy data payloads to the latest data model, transforming any deprecated properties to their latest counterparts as described by the [Data API reference](/docs/api-reference/data-model/data).
+
+```tsx
+import { migrate } from "@puckeditor/core";
+
+migrate(legacyData);
+```
+
+## Breaking changes to props
+
+Renaming or removing the props passed to your components are considered breaking changes. Any existing [Data](/docs/api-reference/data-model/data) payloads that reference these props will be unable to render.
+
+There are two strategies for dealing with this:
+
+1. Retaining backwards-compatible props
+2. Implementing a prop migration
+
+### Retaining backwards-compatibility
+
+The easiest way to avoid breaking changes is to implement your prop changes in a backwards compatible manor:
+
+```tsx
+const config = {
+  HeadingBlock: ({ title, heading }) => <h1>{heading || title}</h1>,
+};
+```
+
+### Implementing a prop migration
+
+It will often be preferrable to update the underlying [Data](/docs/api-reference/data-model/data) payload. Puck provides the [`transformProps`](/docs/api-reference/functions/transform-props) utility method to conveniently transform the props for a given component throughout the payload.
+
+```tsx
+import { transformProps } from "@puckeditor/core";
+
+const config = {
+  // Renamed `title` prop to `heading`
+  HeadingBlock: ({ heading }) => <h1>{heading}</h1>,
+};
+
+const data = {
+  content: [
+    // HeadingBlock references the legacy `title` prop
+    { type: "HeadingBlock", props: { title: "Hello, world" } },
+  ],
+};
+
+const updatedData = transformProps(data, {
+  // Map `heading` to the legacy `title` prop
+  HeadingBlock: ({ title, ...props }) => ({ heading: title, ...props }),
+});
+
+console.log(updatedData);
+// { content: [{ type: "HeadingBlock", props: { heading: "Hello, world" } }] };
+```
+
+You may choose to run this transform every time you render your content, or perform a batch operation against your database.
+
+File: `Example showing data being updated before rendering`
+
+```tsx
+import { Puck, Render, transformProps } from "@puckeditor/core";
+
+const transforms = {
+  HeadingBlock: ({ title, ...props }) => ({ heading: title, ...props }),
+};
+
+export const MyEditor = ({ data, config }) => (
+  <Puck data={transformProps(data, transforms)} config={config} />
+);
+
+export const MyPage = ({ data, config }) => (
+  <Render data={transformProps(data, transforms)} config={config} />
+);
+```
+
+## Further reading
+
+- [`Data` API reference](/docs/api-reference/data-model/data)
+- [`migrate` API reference](/docs/api-reference/functions/migrate)
+- [`transformProps` API reference](/docs/api-reference/functions/transform-props)

package/dist/docs/integrating-puck/dynamic-fields.md

@@ -0,0 +1,86 @@
+# Dynamic Fields
+
+Dynamic field resolution allows you to change the [field configuration](/docs/api-reference/configuration/component-config#fields) for a component based on the current component props.
+
+## Dynamic component fields
+
+The [`resolveFields` function](/docs/api-reference/configuration/component-config#resolvefieldsdata-params) allows you to make synchronous and asynchronous changes to the field configuration.
+
+For example, we can set the configuration of one field based on the prop value of 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;
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Making asynchronous calls
+
+The [`resolveFields` function](/docs/api-reference/configuration/component-config#resolvefieldsdata-params) also enables asynchronous calls.
+
+Here's an example populating the options for a [`select` field](/docs/api-reference/fields/select) based on a [`radio` field](/docs/api-reference/fields/radio)
+
+```tsx
+const config = {
+  components: {
+    MyComponent: {
+      resolveFields: async (data, { changed, lastFields }) => {
+        // Don't call the API unless `category` has changed
+        if (!changed.category) return lastFields;
+
+        // Make an asynchronous API call to get the options
+        const options = await getOptions(data.category);
+
+        return {
+          category: {
+            type: "radio",
+            options: [
+              { label: "Fruit", value: "fruit" },
+              { label: "Vegetables", value: "vegetables" },
+            ],
+          },
+          item: {
+            type: "select",
+            options,
+          },
+        };
+      },
+      render: ({ item }) => <h1>{item}</h1>,
+    },
+  },
+};
+```
+
+## Limitations
+
+The [`slot` field](/docs/api-reference/fields/slot) is not currently supported by Dynamic Fields, but most use-cases can be achieved using [Dynamic Props](/docs/integrating-puck/dynamic-props).
+
+## Further reading
+
+- [`resolveFields` API reference](/docs/api-reference/configuration/component-config#resolvefieldsdata-params)

package/dist/docs/integrating-puck/dynamic-props.md

@@ -0,0 +1,137 @@
+# Dynamic Props
+
+Dynamic prop resolution allows you to change the props for a component after the props have been changed by the user. This is useful for making third-party API calls, such as requesting the latest content from a headless CMS.
+
+## Dynamic component props
+
+The [`resolveData` function](/docs/api-reference/configuration/component-config#resolvedatadata-params) allows you to make changes to the props and set fields as read-only.
+
+For example, we can set the value of one prop to another:
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: {
+          type: "text",
+        },
+        resolvedTitle: {
+          type: "text",
+        },
+      },
+      resolveData: async ({ props }) => {
+        return {
+          props: {
+            resolvedTitle: props.title,
+          },
+        };
+      },
+      render: ({ resolvedTitle }) => {
+        return <h1>{resolvedTitle}</h1>;
+      },
+    },
+  },
+};
+```
+
+> When inserting components with `resolveData`, the Puck state will update twice - once for the initial insert, and once more when the method resolves, if it changes the data. This will be reflected in the undo/redo history.
+
+### Setting fields as read-only
+
+[`resolveData`](/docs/api-reference/configuration/component-config#resolvedatadata-params) also allows us to mark fields as read-only using the [`readOnly` parameter](/docs/api-reference/configuration/component-config#datareadonly-1).
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      // ...
+      resolveData: async ({ props }) => {
+        return {
+          props: {
+            resolvedTitle: props.title,
+          },
+          readOnly: { resolvedTitle: true },
+        };
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Preventing duplicate calls
+
+It's possible that `resolveData` may carry out an expensive operation (like an API call) that we want to avoid making unless a specific prop has changed.
+
+This can be restricted by checking the [`changed` param](/docs/api-reference/configuration/component-config#paramschanged) before calling any expensive operations.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      // ...
+      resolveData: async ({ props }, { changed }) => {
+        if (!changed.text) return { props };
+
+        return {
+          props: {
+            resolvedTitle: await expensiveOperation(props.title),
+          },
+        };
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Dynamic Root props
+
+The `resolveData` method is also available on the [root component](/docs/api-reference/configuration/config#root).
+
+```tsx
+const config = {
+  components: {},
+  root: {
+    fields: {
+      title: {
+        type: "text",
+      },
+      resolvedTitle: {
+        type: "text",
+      },
+    },
+    resolveData: async ({ props }) => {
+      return {
+        props: {
+          resolvedTitle: props.title,
+        },
+      };
+    },
+    render: ({ children, resolvedTitle }) => {
+      return (
+        <>
+          <h1>{resolvedTitle}</h1>
+          {children}
+        </>
+      );
+    },
+  },
+};
+```
+
+## Triggering `resolveData`
+
+Resolve data is triggered whenever the props for a component change, or when the [`resolveAllData` utility](/docs/api-reference/functions/resolve-all-data) is used.
+
+```tsx
+import { resolveAllData } from "@puckeditor/core";
+
+const updatedData = await resolveAllData(data, config);
+```
+
+## Further reading
+
+- [`resolveData` API reference](/docs/api-reference/configuration/component-config#resolvedatadata-params)
+- [`resolveAllData` API reference](/docs/api-reference/functions/resolve-all-data)

package/dist/docs/integrating-puck/external-data-sources.md

@@ -0,0 +1,149 @@
+# External Data Sources
+
+There are several different approaches for loading external data into a Puck component.
+
+It's possible for Puck components to load their own data internally on the client, or on the server using [React server components](/docs/integrating-puck/server-components). This doesn't require any Puck configuration.
+
+If you want to provide the user a way to select the data, you can use the [`external` field type](/docs/api-reference/fields/external).
+
+## Selecting external data
+
+The [`external` field type](/docs/api-reference/fields/external) allows users to select tabular data from a third-party data source, like a headless CMS. This will load the data once and save it into the [data payload](/docs/api-reference/data-model/data).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            // Query an API for a list of items
+            const items = await fetch(`/api/items`).then((res) => res.json());
+            // [
+            //   { title: "Hello, world", description: "Lorem ipsum 1" },
+            //   { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            // ];
+
+            return items;
+          },
+        },
+      },
+      render: ({ data }) => {
+        if (!data) {
+          return "No data selected";
+        }
+
+        return (
+          <>
+            <b>{data.title}</b>
+            <p>{data.description}</p>
+          </>
+        );
+      },
+    },
+  },
+};
+```
+
+You can also use the [`showSearch` parameter](/docs/api-reference/fields/external#showsearch) to show a search input to the user.
+
+## Data syncing
+
+To keep the data in sync with the external source, we can combine the `external` field with the [`resolveData`](/docs/api-reference/configuration/component-config#resolvedatadata-params) function.
+
+This technique re-fetches the content every time the page is loaded, or the [`resolveAllData` utility](/docs/api-reference/functions/resolve-all-data) is called.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            // Query an API for a list of items
+            const items = await fetch(`/api/items`).then((res) => res.json());
+            // [
+            //   { title: "Hello, world", id: 0 },
+            //   { title: "Goodbye, world", id: 1 },
+            // ];
+
+            return items;
+          },
+        },
+      },
+      resolveData: async ({ props }, { changed }) => {
+        if (!props.data) return { props };
+
+        // Don't query unless `data` has changed since resolveData was last run
+        if (!changed.data) return { props };
+
+        // Re-query the API for a particular item
+        const latestData = await fetch(`/api/items/${props.data.id}`).then(
+          (res) => res.json()
+        );
+        // { title: "Hello, world", description: "Lorem ipsum 1", id: 0 }
+
+        return {
+          props: {
+            // Update the value for `data`
+            data: latestData,
+          },
+        };
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Hybrid authoring
+
+Hybrid authoring enables users to edit fields inline, or populate those fields with data from an external source.
+
+This can be achieved by mapping the data from `data.title` to `title` in [`resolveData`](/docs/api-reference/configuration/component-config#resolvedatadata-params), and marking the field as read-only.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          // ...
+        },
+        title: {
+          type: "text",
+        },
+      },
+      resolveData: async ({ props }, { changed }) => {
+        // Remove read-only from the title field if `data` is empty
+        if (!props.data) return { props, readOnly: { title: false } };
+
+        // Don't query unless `data` has changed since resolveData was last run
+        if (!changed.data) return { props };
+
+        return {
+          props: {
+            title: props.data.title,
+            readOnly: { title: true },
+          },
+        };
+      },
+      render: ({ title }) => <b>{title}</b>,
+    },
+  },
+};
+```
+
+## External data packages
+
+We provide helper packages to load data from common data sources.
+
+- [`contentful`](https://github.com/puckeditor/puck/tree/main/packages/field-contentful): Select content entries from a [Contentful](https://www.contentful.com) space.
+
+## Further reading
+
+- [`external` field API reference](/docs/api-reference/fields/external)
+- [`resolveData` API reference](/docs/api-reference/configuration/component-config#resolvedatadata-params)
+- [`resolveAllData` API reference](/docs/api-reference/functions/resolve-all-data)