@measured/puck 0.11.0-canary.6145c32 → 0.11.0-canary.7f13efc

package/README.md

@@ -1,5 +1,7 @@
 # puck
 
+The self-hosted, drag and drop editor for React.
+
 <p align="left">
   <a aria-label="Measured logo" href="https://measured.co">
     <img src="https://img.shields.io/badge/MADE%20BY%20Measured-000000.svg?style=for-the-badge&labelColor=000">
@@ -15,7 +17,7 @@
   </a>
 </p>
 
-The self-hosted, drag and drop editor for React.
+## Features
 
 - 🖱️ **Drag and drop**: Visual editing for your existing React component library
 - 🌐 **Integrations**: Load your content from a 3rd party headless CMS
@@ -111,10 +113,11 @@ The plugin API follows a React paradigm. Each plugin passed to the Puck editor c
 - `renderRoot` (`Component`): Render the root node of the preview content
 - `renderRootFields` (`Component`): Render the root fields
 - `renderFields` (`Component`): Render the fields for the currently selected component
+- `renderComponentList` (`Component`): Render the component list
 
 Each render function receives three props:
 
-- **children** (`ReactNode`): The normal contents of the root or field. You must render this.
+- **children** (`ReactNode`): The normal contents of the root or field. You must render this if provided.
 - **state** (`AppState`): The current application state, including data and UI state
 - **dispatch** (`(action: PuckAction) => void`): The Puck dispatcher, used for making data changes or updating the UI. See the [action definitions](https://github.com/measuredco/puck/blob/main/packages/core/reducer/actions.tsx) for a full reference of available mutations.
 
@@ -231,6 +234,146 @@ The current DropZone implementation has certain rules and limitations:
 3. You can't drag between DropZones that don't share a parent (or _area_)
 4. Your mouse must be directly over a DropZone for a collision to be detected
 
+## External fields
+
+External fields can be used to import data from a third-party API, such as a headless CMS.
+
+### Example
+
+The `external` field type enables us to query data from a third party API:
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        myData: {
+          type: "external",
+          fetchList: async () => {
+            const response = await fetch("https://www.example.com/api");
+
+            return {
+              text: response.json().text,
+            };
+          },
+        },
+      },
+      render: ({ myData }) => {
+        return <h1>{myData.text}</h1>;
+      },
+    },
+  },
+};
+```
+
+When the user interacts with this external field, they'll be presented with a list of items to choose from. Once they select an item, the value will be mapped onto the prop. In this case, `myData`.
+
+## Dynamic prop resolution
+
+Dynamic prop resolution allows developers to resolve props for components without saving the data to the Puck data model.
+
+### resolveData()
+
+`resolveData` is defined in the component config, and allows the developer to make asynchronous calls to change the [ComponentData](#componentdata) after they've been set by Puck. Receives [ComponentData](#componentdata) and returns [ComponentData](#componentdata).
+
+#### Examples
+
+##### Basic example
+
+In this example, we remap the `text` prop to the `title` prop and mark the `title` field as read-only.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        text: {
+          type: "text",
+        },
+        title: {
+          type: "text",
+        },
+      },
+      resolveData: async (props) => {
+        return {
+          props: {
+            title: props.text,
+          },
+          readOnly: {
+            title: true,
+          },
+        };
+      },
+      render: ({ title }) => {
+        return <h1>{title}</h1>;
+      },
+    },
+  },
+};
+```
+
+##### Combining with external fields
+
+A more advanced pattern is to combine the `resolveData` method with `external` fields to dynamically fetch data when rendering the component.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        myData: {
+          type: "external",
+          placeholder: "Select from example.com",
+          fetchList: async () => {
+            const response = await fetch("https://www.example.com/api");
+
+            return {
+              id: response.json().id,
+            };
+          },
+        },
+        title: {
+          type: "text",
+        },
+      },
+      resolveData: async (props) => {
+        if (!myData.id) {
+          return { props, readOnly: { title: false } };
+        }
+
+        const latestData = await fetch(
+          `https://www.example.com/api/${myData.id}`
+        );
+
+        return {
+          props: {
+            title: latestData.json().text,
+          },
+          readOnly: {
+            title: true,
+          },
+        };
+      },
+      render: ({ title }) => {
+        return <h1>{title}</h1>;
+      },
+    },
+  },
+};
+```
+
+### resolveAllData()
+
+`resolveAllData` is a utility function exported by Puck to enable the developer to run all their `resolveData` methods before rendering the component with `<Render>`.
+
+If your `resolveData` methods rely on any external APIs, you should run this before rendering your page.
+
+```tsx
+import { resolveAllData } from "@measured/puck";
+
+const resolvedData = resolveAllData(data, config);
+```
+
 ## Reference
 
 ### `<Puck>`
@@ -241,6 +384,7 @@ The `<Puck>` component renders the Puck editor.
 - **data** (`Data`): Initial data to render
 - **onChange** (`(Data) => void` [optional]): Callback that triggers when the user makes a change
 - **onPublish** (`(Data) => void` [optional]): Callback that triggers when the user hits the "Publish" button
+- **renderComponentList** (`Component` [optional]): Render function for wrapping the component list
 - **renderHeader** (`Component` [optional]): Render function for overriding the Puck header component
 - **renderHeaderActions** (`Component` [optional]): Render function for overriding the Puck header actions. Use a fragment.
 - **headerTitle** (`string` [optional]): Set the title shown in the header title
@@ -270,27 +414,74 @@ The `Config` object describes which components Puck should render, how they shou
     - **title** (`Field`): Title of the content, typically used for the page title.
     - **[fieldName]** (`Field`): User defined fields, used to describe the input data stored in the `root` key.
   - **render** (`Component`): Render a React component at the root of your component tree. Useful for defining context providers.
+  - **resolveData** (`async (data: ComponentData) => ComponentData` [optional]): Function to dynamically change props before rendering the root.
 - **components** (`object`): Definitions for each of the components you want to show in the visual editor
   - **[componentName]** (`object`)
     - **fields** (`Field`): The Field objects describing the input data stored against this component.
     - **render** (`Component`): Render function for your React component. Receives props as defined in fields.
     - **defaultProps** (`object` [optional]): Default props to pass to your component. Will show in fields.
+    - **resolveData** (`async (data: ComponentData) => ComponentData` [optional]): Function to dynamically change props before rendering the component.
+- **categories** (`object`): Component categories for rendering in the side bar or restricting in DropZones
+  - **[categoryName]** (`object`)
+    - **components** (`sting[]`, [optional]): Array containing the names of components in this category
+    - **title** (`sting`, [optional]): Title of the category
+    - **visible** (`boolean`, [optional]): Whether or not the category should be visible in the side bar
+    - **defaultExpanded** (`boolean`, [optional]): Whether or not the category should be expanded in the side bar by default
 
 ### `Field`
 
 A `Field` represents a user input field shown in the Puck interface.
 
-- **type** (`text` | `textarea` | `number` | `select` | `radio` | `external` | `array` | `custom`): The input type to render
+### All Fields
+
 - **label** (`text` [optional]): A label for the input. Will use the key if not provided.
-- **arrayFields** (`object`): Object describing sub-fields for items in an `array` input
-  - **[fieldName]** (`Field`): The Field objects describing the input data for each item
-- **getItemSummary** (`(object, number) => string` [optional]): Function to get the name of each item when using the `array` or `external` field types
-- **defaultItemProps** (`object` [optional]): Default props to pass to each new item added, when using a `array` field type
-- **options** (`object[]`): array of items to render for select or radio inputs
+
+### Text Fields
+
+- **type** (`"text"`)
+
+### Textarea Fields
+
+- **type** (`"textarea"`)
+
+### Number Fields
+
+- **type** (`"number"`)
+
+### Select Fields
+
+- **type** (`"select"`)
+- **options** (`object[]`): array of items to render
   - **label** (`string`)
   - **value** (`string` | `number` | `boolean`)
-- **adaptor** (`Adaptor`): Content adaptor if using the `external` input type
-- **adaptorParams** (`object`): Paramaters passed to the adaptor
+
+### Radio Fields
+
+- **type** (`"radio"`)
+- **options** (`object[]`): array of items to render
+  - **label** (`string`)
+  - **value** (`string` | `number` | `boolean`)
+
+### Array Fields
+
+- **type** (`"array"`)
+- **arrayFields** (`object`): Object describing sub-fields for each item
+  - **[fieldName]** (`Field`): The Field objects describing the input data for each item
+  - **getItemSummary** (`(object, number) => string` [optional]): Function to get the label of each item
+- **defaultItemProps** (`object` [optional]): Default props to pass to each new item added, when using a `array` field type
+
+### External Fields
+
+External fields can be used to load content from an external content repository, like Strapi.js.
+
+- **type** (`"external"`)
+- **placeholder** (`string`): A placeholder for the external field button
+- **fetchList** (`() => object`): Fetch content from a third-party API and return an array
+- **mapProp** (`(selectedItem: object) => object`): Map the selected item into another shape
+
+### Custom Fields
+
+- **type** (`"custom"`)
 - **render** (`Component`): Render a custom field. Receives the props:
   - **field** (`Field`): Field configuration
   - **name** (`string`): Name of the field
@@ -307,27 +498,30 @@ The `AppState` object stores the puck application state.
   - **leftSideBarVisible** (boolean): Whether or not the left side bar is visible
   - **itemSelector** (object): An object describing which item is selected
   - **arrayState** (object): An object describing the internal state of array items
+  - **componentList** (object): An object describing the component list. Similar shape to `Config.categories`.
+    - **components** (`sting[]`, [optional]): Array containing the names of components in this category
+    - **title** (`sting`, [optional]): Title of the category
+    - **visible** (`boolean`, [optional]): Whether or not the category is visible in the side bar
+    - **expanded** (`boolean`, [optional]): Whether or not the category is expanded in the side bar
 
 ### `Data`
 
 The `Data` object stores the puck page data.
 
-- **root** (`object`):
-  - **title** (string): Title of the content, typically used for the page title
-  - **[prop]** (string): User defined data from `root` fields
-- **content** (`object[]`):
-  - **type** (string): Component name
-  - **props** (object):
-    - **[prop]** (string): User defined data from component fields
-
-### `Adaptor`
-
-An `Adaptor` can be used to load content from an external content repository, like Strapi.js.
+- **root** (`ComponentData`): The component data for the root of your configuration.
+  - **props** (object): Extends `ComponentData.props`, with some additional props
+    - **title** (`string`, [optional]): Title of the content, typically used for the page title
+- **content** (`ComponentData[]`): Component data for the main content
+- **zones** (`object`, [optional]): Component data for all DropZones
+  **[zoneCompound]** (`ComponentData[]`): Component data for a specific DropZone `zone` within a component instance
 
-- **name** (`string`): The human-readable name of the adaptor
-- **fetchList** (`(adaptorParams: object) => object`): Fetch a list of content and return an array
+### `ComponentData`
 
-> NB Using an adaptor on the reserved field name `_data` will spread the resulting data over your object, and lock the overridden fields.
+- **type** (`string`): Component name
+- **props** (`object`):
+  - **[prop]** (`any`): User defined data from component fields
+- **readOnly** (`object`): Object describing which fields on the component are currently read-only. Can use dot-notation for arrays, like `array[1].text` or `array[*].text`.
+  - **[prop]** (`boolean`): boolean describing whether or not the prop field is read-only
 
 ### `Plugin`