@measured/puck 0.11.0-canary.4613df4 → 0.11.0-canary.7f13efc

package/README.md

@@ -234,33 +234,28 @@ 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
+## External fields
 
-Adaptors can be used to import data from a third-party API, such as a headless CMS.
+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 use an adaptor to query data from a third party API:
+The `external` field type enables us 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,
+          fetchList: async () => {
+            const response = await fetch("https://www.example.com/api");
+
+            return {
+              text: response.json().text,
+            };
+          },
         },
       },
       render: ({ myData }) => {
@@ -271,25 +266,15 @@ const config = {
 };
 ```
 
-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`.
+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.
 
-### resolveProps()
-
-`resolveProps` is defined in the component config, and allows the developer to make asynchronous calls to change the props after they've been set by Puck.
-
-#### Args
-
-- **props** (`object`): the current props for your component stored in the Puck data
-
-#### Response
+### resolveData()
 
-- **props** (`object`): the resolved props for your component. Will not be stored in the Puck data
-- **readOnly** (`object`): an object describing which fields on the component are currently read-only
-  - **[prop]** (`boolean`): boolean describing whether or not the prop field is read-only
+`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
 
@@ -309,7 +294,7 @@ const config = {
           type: "text",
         },
       },
-      resolveProps: async (props) => {
+      resolveData: async (props) => {
         return {
           props: {
             title: props.text,
@@ -327,35 +312,31 @@ const config = {
 };
 ```
 
-##### Combining with adaptors
+##### Combining with external fields
 
-A more advanced pattern is to combine the `resolveProps` method with the adaptors to dynamically fetch data when rendering the component.
+A more advanced pattern is to combine the `resolveData` method with `external` fields 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,
+          placeholder: "Select from example.com",
+          fetchList: async () => {
+            const response = await fetch("https://www.example.com/api");
+
+            return {
+              id: response.json().id,
+            };
+          },
         },
         title: {
           type: "text",
         },
       },
-      resolveProps: async (props) => {
+      resolveData: async (props) => {
         if (!myData.id) {
           return { props, readOnly: { title: false } };
         }
@@ -381,14 +362,16 @@ const config = {
 };
 ```
 
-### resolveData()
+### 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>`.
 
-`resolveData` is a utility function exported by Puck to enable the developer to resolve their custom props before rendering their component with `<Render>`. This is ideally done on the server. If you're using `resolveProps`, you _must_ use `resolveData` before rendering.
+If your `resolveData` methods rely on any external APIs, you should run this before rendering your page.
 
 ```tsx
-import { resolveData } from "@measured/puck";
+import { resolveAllData } from "@measured/puck";
 
-const resolvedData = resolveData(data, config);
+const resolvedData = resolveAllData(data, config);
 ```
 
 ## Reference
@@ -431,18 +414,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.
-    - **resolveProps** (`async (props: object) => object` [optional]): Function to dynamically change props before rendering the component.
-      - Args
-        - **props** (`object`): the current props for your component stored in the Puck data
-      - Response
-        - **props** (`object`): the resolved props for your component. Will not be stored in the Puck data
-        - **readOnly** (`object`): an object describing which fields on the component are currently read-only
-          - **[prop]** (`boolean`): boolean describing whether or not the prop field is read-only
+    - **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
@@ -494,14 +472,12 @@ A `Field` represents a user input field shown in the Puck interface.
 
 ### External Fields
 
-External fields can be used to load content from an external content repository, like Strapi.js, using an `Adaptor`.
+External fields can be used to load content from an external content repository, like Strapi.js.
 
 - **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
+- **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
 
@@ -532,13 +508,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
+- **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
+
+### `ComponentData`
+
+- **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`