@measured/puck 0.11.0-canary.c8c02fd → 0.11.0-canary.f9033e2

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
@@ -232,6 +234,155 @@ 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
 
+## Adaptors
+
+Adaptors can be used to import data from a third-party API, such as a headless CMS.
+
+### Example
+
+The `external` field type enables us to use an adaptor to query data from a third party API:
+
+```tsx
+const myAdaptor = {
+  name: "My adaptor",
+  fetchList: async () => {
+    const response = await fetch("https://www.example.com/api");
+
+    return {
+      text: response.json().text,
+    };
+  },
+};
+
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        myData: {
+          type: "external",
+          adaptor: myAdaptor,
+        },
+      },
+      render: ({ myData }) => {
+        return <h1>{myData.text}</h1>;
+      },
+    },
+  },
+};
+```
+
+When the user interacts with this adaptor, 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 adaptors
+
+A more advanced pattern is to combine the `resolveData` method with the adaptors to dynamically fetch data when rendering the component.
+
+```tsx
+const myAdaptor = {
+  name: "My adaptor",
+  fetchList: async () => {
+    const response = await fetch("https://www.example.com/api");
+
+    return {
+      id: response.json().id,
+    };
+  },
+};
+
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        myData: {
+          type: "external",
+          adaptor: myAdaptor,
+        },
+        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>`
@@ -272,11 +423,13 @@ 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
@@ -288,17 +441,58 @@ The `Config` object describes which components Puck should render, how they shou
 
 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`)
+
+### Radio Fields
+
+- **type** (`"radio"`)
+- **options** (`object[]`): array of items to render
   - **label** (`string`)
   - **value** (`string` | `number` | `boolean`)
-- **adaptor** (`Adaptor`): Content adaptor if using the `external` input type
+
+### 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, using an `Adaptor`.
+
+- **type** (`"external"`)
+- **adaptor** (`Adaptor`): Content adaptor responsible for fetching data to show in the table
+  - **name** (`string`): The human-readable name of the adaptor
+  - **fetchList** (`(adaptorParams: object) => object`): Fetch content from a third-party API and return an array
+  - **mapProp** (`(selectedItem: object) => object`): Map the selected item into another shape
 - **adaptorParams** (`object`): Paramaters passed to the adaptor
+
+### Custom Fields
+
+- **type** (`"custom"`)
 - **render** (`Component`): Render a custom field. Receives the props:
   - **field** (`Field`): Field configuration
   - **name** (`string`): Name of the field
@@ -325,22 +519,20 @@ The `AppState` object stores the puck application state.
 
 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`