@measured/puck 0.11.0-canary.6145c32 → 0.11.0-canary.b28404f

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,163 @@ 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.
+
+### 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
+
+- **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
+
+#### 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",
+        },
+      },
+      resolveProps: 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 `resolveProps` 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",
+        },
+      },
+      resolveProps: 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>;
+      },
+    },
+  },
+};
+```
+
+### resolveData()
+
+`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.
+
+```tsx
+import { resolveData } from "@measured/puck";
+
+const resolvedData = resolveData(data, config);
+```
+
 ## Reference
 
 ### `<Puck>`
@@ -241,6 +401,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
@@ -275,22 +436,76 @@ The `Config` object describes which components Puck should render, how they shou
     - **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
+- **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`)
+
+### 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
@@ -307,6 +522,11 @@ 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`
 
@@ -320,15 +540,6 @@ The `Data` object stores the puck page data.
   - **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.
-
-- **name** (`string`): The human-readable name of the adaptor
-- **fetchList** (`(adaptorParams: object) => object`): Fetch a list of content and return an array
-
-> NB Using an adaptor on the reserved field name `_data` will spread the resulting data over your object, and lock the overridden fields.
-
 ### `Plugin`
 
 Plugins that can be used to enhance Puck.

package/dist/index.css

@@ -475,17 +475,17 @@
 }
 
 /* css-module:/home/runner/work/puck/puck/packages/core/components/InputOrGroup/fields/ArrayField/styles.module.css/#css-module-data */
-._ArrayField_zp334_5 {
+._ArrayField_32vor_5 {
   display: flex;
   flex-direction: column;
   background-color: var(--puck-color-grey-8);
   border: 1px solid var(--puck-color-grey-8);
   border-radius: 4px;
 }
-._ArrayField--isDraggingFrom_zp334_13 {
+._ArrayField--isDraggingFrom_32vor_13 {
   background-color: var(--puck-color-azure-9);
 }
-._ArrayField-addButton_zp334_17 {
+._ArrayField-addButton_32vor_17 {
   background-color: white;
   border: none;
   border-radius: 4px;
@@ -498,37 +498,37 @@
   padding: 16px;
   text-align: left;
 }
-._ArrayField--hasItems_zp334_31 > ._ArrayField-addButton_zp334_17 {
+._ArrayField--hasItems_32vor_31 > ._ArrayField-addButton_32vor_17 {
   border-top-left-radius: 0;
   border-top-right-radius: 0;
 }
-._ArrayField_zp334_5:not(._ArrayField--isDraggingFrom_zp334_13) > ._ArrayField-addButton_zp334_17:hover {
+._ArrayField_32vor_5:not(._ArrayField--isDraggingFrom_32vor_13) > ._ArrayField-addButton_32vor_17:hover {
   background: var(--puck-color-azure-9);
   color: var(--puck-color-azure-4);
 }
-._ArrayFieldItem_zp334_45 {
+._ArrayFieldItem_32vor_45 {
   background: white;
   border-top-left-radius: 4px;
   border-top-right-radius: 4px;
   display: block;
   margin-bottom: 1px;
 }
-._ArrayField--isDraggingFrom_zp334_13 > ._ArrayFieldItem_zp334_45:not(._ArrayFieldItem--isDragging_zp334_53) {
+._ArrayField--isDraggingFrom_32vor_13 > ._ArrayFieldItem_32vor_45:not(._ArrayFieldItem--isDragging_32vor_53) {
   border-bottom: 1px solid var(--puck-color-grey-8);
   margin-bottom: 0;
 }
-._ArrayFieldItem--isExpanded_zp334_58 {
+._ArrayFieldItem--isExpanded_32vor_58 {
   border-bottom: 0;
   outline: 1px solid var(--puck-color-azure-6);
 }
-._ArrayFieldItem--isDragging_zp334_53 {
+._ArrayFieldItem--isDragging_32vor_53 {
   box-shadow: rgba(140, 152, 164, 0.25) 0 3px 6px 0;
 }
-._ArrayFieldItem_zp334_45 + ._ArrayFieldItem_zp334_45 {
+._ArrayFieldItem_32vor_45 + ._ArrayFieldItem_32vor_45 {
   border-top-left-radius: 0;
   border-top-right-radius: 0;
 }
-._ArrayFieldItem-summary_zp334_72 {
+._ArrayFieldItem-summary_32vor_72 {
   color: var(--puck-color-grey-3);
   display: flex;
   align-items: center;
@@ -539,48 +539,45 @@
   position: relative;
   overflow: hidden;
 }
-._ArrayFieldItem--isExpanded_zp334_58 > ._ArrayFieldItem-summary_zp334_72 {
+._ArrayFieldItem--isExpanded_32vor_58 > ._ArrayFieldItem-summary_32vor_72 {
   font-weight: 600;
 }
-._ArrayFieldItem_zp334_45:first-of-type > ._ArrayFieldItem-summary_zp334_72 {
+._ArrayFieldItem_32vor_45:first-of-type > ._ArrayFieldItem-summary_32vor_72 {
   border-top-left-radius: 4px;
   border-top-right-radius: 4px;
 }
-._ArrayFieldItem-summary_zp334_72:hover,
-._ArrayFieldItem--isExpanded_zp334_58 > ._ArrayFieldItem-summary_zp334_72 {
+._ArrayFieldItem-summary_32vor_72:hover,
+._ArrayFieldItem--isExpanded_32vor_58 > ._ArrayFieldItem-summary_32vor_72 {
   background: var(--puck-color-azure-9);
   cursor: pointer;
   color: var(--puck-color-azure-4);
 }
-._ArrayFieldItem-summary_zp334_72::-webkit-details-marker {
+._ArrayFieldItem-body_32vor_100 {
   display: none;
 }
-._ArrayFieldItem-body_zp334_104 {
-  display: none;
-}
-._ArrayFieldItem--isExpanded_zp334_58 > ._ArrayFieldItem-body_zp334_104 {
+._ArrayFieldItem--isExpanded_32vor_58 > ._ArrayFieldItem-body_32vor_100 {
   display: block;
 }
-._ArrayFieldItem-fieldset_zp334_112 {
+._ArrayFieldItem-fieldset_32vor_108 {
   border: none;
   border-top: 1px solid var(--puck-color-grey-8);
   margin: 0;
   padding: 16px;
 }
-._ArrayFieldItem-rhs_zp334_119 {
+._ArrayFieldItem-rhs_32vor_115 {
   display: flex;
   gap: 8px;
   align-items: center;
 }
-._ArrayFieldItem-actions_zp334_125 {
+._ArrayFieldItem-actions_32vor_121 {
   display: flex;
   gap: 8px;
   opacity: 0;
 }
-._ArrayFieldItem-summary_zp334_72:hover > ._ArrayFieldItem-rhs_zp334_119 > ._ArrayFieldItem-actions_zp334_125 {
+._ArrayFieldItem-summary_32vor_72:hover > ._ArrayFieldItem-rhs_32vor_115 > ._ArrayFieldItem-actions_32vor_121 {
   opacity: 1;
 }
-._ArrayFieldItem-action_zp334_125:hover {
+._ArrayFieldItem-action_32vor_121:hover {
   background: var(--puck-color-grey-9);
   border-radius: 4px;
   color: var(--puck-color-blue);
@@ -723,11 +720,44 @@
 }
 
 /* css-module:/home/runner/work/puck/puck/packages/core/components/ComponentList/styles.module.css/#css-module-data */
-._ComponentList_bvy0z_1 {
+._ComponentList_3rdy2_1 {
   font-family: var(--puck-font-stack);
   max-width: 100%;
 }
-._ComponentList-item_bvy0z_6 {
+._ComponentList--isExpanded_3rdy2_6 + ._ComponentList_3rdy2_1 {
+  margin-top: 12px;
+}
+._ComponentList-content_3rdy2_10 {
+  display: none;
+}
+._ComponentList--isExpanded_3rdy2_6 > ._ComponentList-content_3rdy2_10 {
+  display: block;
+}
+._ComponentList-title_3rdy2_18 {
+  color: var(--puck-color-grey-4);
+  display: flex;
+  font-size: var(--puck-font-size-xxxs);
+  list-style: none;
+  padding: 8px;
+  text-transform: uppercase;
+  gap: 4px;
+  border-radius: 4px;
+}
+._ComponentList--isExpanded_3rdy2_6 ._ComponentList-title_3rdy2_18 {
+  margin-bottom: 4px;
+}
+._ComponentList-title_3rdy2_18:hover {
+  background-color: var(--puck-color-azure-9);
+  color: var(--puck-color-azure-4);
+  cursor: pointer;
+}
+._ComponentList-titleIcon_3rdy2_39 {
+  margin-left: auto;
+}
+._ComponentListItem_3rdy2_43:last-of-type ._ComponentListItem-draggable_3rdy2_43 {
+  margin-bottom: 0px;
+}
+._ComponentListItem-draggable_3rdy2_43 {
   background: white;
   padding: 12px;
   display: flex;
@@ -740,13 +770,10 @@
   cursor: grab;
   margin-bottom: 12px;
 }
-._ComponentList-item_bvy0z_6:last-of-type {
-  margin-bottom: 0px;
-}
-._ComponentList-itemIcon_bvy0z_24 {
+._ComponentListItemIcon_3rdy2_61 {
   color: var(--puck-color-grey-4);
 }
-._ComponentList_bvy0z_1:not(._ComponentList--isDraggingFrom_bvy0z_28) ._ComponentList-item_bvy0z_6:hover {
+._ComponentList_3rdy2_1:not(._ComponentList--isDraggingFrom_3rdy2_65) ._ComponentListItem-draggable_3rdy2_43:hover {
   background-color: var(--puck-color-azure-9);
   color: var(--puck-color-azure-4);
 }