@measured/puck 0.3.1 → 0.4.0

package/README.md

@@ -7,13 +7,14 @@ The self-hosted, drag and drop editor for React.
 - ✍️ **Inline editing**: Author content directly via puck for convenience
 - ⭐️ **No vendor lock-in**: Self-host or integrate with your existing application
 
-![puck](https://github.com/measuredco/puck/assets/985961/10257000-ece7-4728-9e71-6204d2f1540e)
-
 [See demo](https://puck-demo-six.vercel.app/custom/edit)
 
 ## Example
 
+Render the editor:
+
 ```jsx
+// Editor.jsx
 import { Puck } from "puck";
 
 // Create puck component config
@@ -31,20 +32,25 @@ const config = {
 };
 
 // Describe the initial data
-const data = {
-  content: [
-    {
-      type: "HeadingBlock",
-      props: {
-        title: "Home Page",
-      },
-    },
-  ],
-};
+const initialData = {};
+
+// Save the data to your database
+const save = (data) => {};
+
+// Render Puck editor
+export function Editor() {
+  return <Puck config={config} data={data} onPublish={save} />;
+}
+```
+
+Render the page:
+
+```jsx
+// Page.jsx
+import { Render } from "puck";
 
-// Render Puck
 export function Page() {
-  return <Puck config={config} data={data} />;
+  return <Render config={config} data={data} />;
 }
 ```
 
@@ -80,21 +86,19 @@ Puck can be configured to work with plugins. Plugins can extend the functionalit
 
 The plugin API follows a React paradigm. Each plugin passed to the Puck editor can provide three functions:
 
-#### `Plugin`
-
-- `renderPage` (`Component`): Render the root node of the preview content
-- `renderPageFields` (`Component`): Render the page fields
+- `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
 
-Each render function receives the `children` prop, which you should render to show the page or fields, and the `data` prop, which can be used to read the data model for the page.
+Each render function receives the `children` prop, which you must render, and the `data` prop, which can be used to read the data model.
 
 #### Example
 
-Here's a basic plugin that renders a "My plugin" heading in the page field area:
+Here's a basic plugin that renders a "My plugin" heading in the root field area:
 
 ```jsx
 const myPlugin = {
-  renderPageFields: (props) => (
+  renderRootFields: (props) => (
     <div>
       {props.children}
 
@@ -106,14 +110,32 @@ const myPlugin = {
 
 ## Reference
 
+### `<Puck>`
+
+The `<Puck>` component renders the Puck editor.
+
+- **config** (`Config`): Puck component configuration
+- **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
+- **renderHeader** (`Component` [optional]): Render function for overriding the Puck header component
+- **plugins** (`Plugin[]` [optional]): Array of plugins that can be used to enhance Puck
+
+### `<Render>`
+
+The `<Render>` component renders user-facing UI using Puck data.
+
+- **config** (`Config`): Puck component configuration
+- **data** (`Data`): Data to render
+
 ### `Config`
 
 The `Config` object describes which components Puck should render, how they should render and which inputs are available to them.
 
-- **page** (`object`)
+- **root** (`object`)
   - **fields** (`object`):
-    - **title** (`Field`): A mandatory field for the page title.
-    - **[fieldName]** (`Field`): User defined fields, used to describe the input data stored in the `page` key.
+    - **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.
 - **components** (`object`): Definitions for each of the components you want to show in the visual editor
   - **[componentName]** (`object`)
@@ -129,24 +151,43 @@ A `Field` represents a user input field shown in the Puck interface.
 - **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 an `array` field type
+- **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-type inputs
   - **label** (`string`)
   - **value** (`string`)
+- **adaptor** (`Adaptor`): Content adaptor if using the `external` input type
+- **adaptorParams** (`object`): Paramaters passed to the adaptor
 
 ### `Data`
 
-The `Data` object stores the state of a page.
+The `Data` object stores the puck state.
 
-- **page** (`object`):
-  - **title** (string): Page title
-  - **[prop]** (string): User defined data from page fields
+- **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.
+
+- **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.
+
+- **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
+
 ## License
 
 MIT © [Measured Co.](https://github.com/measuredco)

package/dist/index.css

@@ -208,13 +208,13 @@
 }
 
 /* css-module:/home/runner/work/puck/puck/packages/core/components/ExternalInput/styles.module.css/#css-module-data */
-._ExternalInput_v316c_1 {
+._ExternalInput_1dp4v_1 {
   font-family: var(--puck-font-stack);
 }
-._ExternalInput-actions_v316c_5 {
+._ExternalInput-actions_1dp4v_5 {
   display: flex;
 }
-._ExternalInput-button_v316c_9 {
+._ExternalInput-button_1dp4v_9 {
   background-color: white;
   border: 1px solid var(--puck-color-grey-8);
   border-radius: 4px;
@@ -225,20 +225,21 @@
   text-overflow: ellipsis;
   position: relative;
   overflow: hidden;
+  flex-grow: 1;
 }
-._ExternalInput-button_v316c_9:hover,
-._ExternalInput-detachButton_v316c_23:hover {
+._ExternalInput-button_1dp4v_9:hover,
+._ExternalInput-detachButton_1dp4v_24:hover {
   cursor: pointer;
   background: var(--puck-color-grey-10);
   border-color: var(--puck-color-neutral-3);
   z-index: 1;
 }
-._ExternalInput--hasData_v316c_30 ._ExternalInput-button_v316c_9 {
+._ExternalInput--hasData_1dp4v_31 ._ExternalInput-button_1dp4v_9 {
   color: var(--puck-color-neutral-4);
   border-top-right-radius: 0px;
   border-bottom-right-radius: 0px;
 }
-._ExternalInput-detachButton_v316c_23 {
+._ExternalInput-detachButton_1dp4v_24 {
   border: 1px solid var(--puck-color-grey-8);
   border-top-right-radius: 4px;
   border-bottom-right-radius: 4px;
@@ -246,7 +247,7 @@
   padding: 8px 12px;
   margin-left: -1px;
 }
-._ExternalInput-modal_v316c_45 {
+._ExternalInput-modal_1dp4v_46 {
   background: #00000099;
   display: none;
   justify-content: center;
@@ -259,10 +260,10 @@
   z-index: 1;
   padding: 64px;
 }
-._ExternalInput--modalVisible_v316c_59 ._ExternalInput-modal_v316c_45 {
+._ExternalInput--modalVisible_1dp4v_60 ._ExternalInput-modal_1dp4v_46 {
   display: flex;
 }
-._ExternalInput-modalInner_v316c_63 {
+._ExternalInput-modalInner_1dp4v_64 {
   width: 100%;
   max-width: 1024px;
   border-radius: 16px;
@@ -272,51 +273,51 @@
   flex-direction: column;
   max-height: 90vh;
 }
-._ExternalInput-modalHeading_v316c_74 {
+._ExternalInput-modalHeading_1dp4v_75 {
   background-color: white;
   padding: 32px 24px;
 }
-._ExternalInput-modalTableWrapper_v316c_79 {
+._ExternalInput-modalTableWrapper_1dp4v_80 {
   overflow-x: scroll;
   overflow-y: scroll;
   flex-grow: 1;
 }
-._ExternalInput_v316c_1 table {
+._ExternalInput_1dp4v_1 table {
   border-spacing: 0px;
   color: var(--puck-color-neutral-4);
   position: relative;
 }
-._ExternalInput_v316c_1 thead {
+._ExternalInput_1dp4v_1 thead {
   position: sticky;
   top: 0;
 }
-._ExternalInput_v316c_1 th {
+._ExternalInput_1dp4v_1 th {
   background-color: var(--puck-color-grey-1);
   color: white;
   font-weight: 700;
   padding: 16px 24px;
   opacity: 0.9;
 }
-._ExternalInput_v316c_1 td {
+._ExternalInput_1dp4v_1 td {
   padding: 16px 24px;
 }
-._ExternalInput_v316c_1 tr:nth-of-type(n) {
+._ExternalInput_1dp4v_1 tr:nth-of-type(n) {
   background-color: white;
 }
-._ExternalInput_v316c_1 tr:nth-of-type(2n) {
+._ExternalInput_1dp4v_1 tr:nth-of-type(2n) {
   background-color: var(--puck-color-grey-9);
 }
-._ExternalInput_v316c_1 tr td:first-of-type {
+._ExternalInput_1dp4v_1 tr td:first-of-type {
   font-weight: 500;
 }
-._ExternalInput_v316c_1 tr:hover {
+._ExternalInput_1dp4v_1 tr:hover {
   background: var(--puck-color-grey-10);
   color: var(--puck-color-azure-4);
   cursor: pointer;
   position: relative;
   margin-left: -5px;
 }
-._ExternalInput_v316c_1 tr:hover td:first-of-type {
+._ExternalInput_1dp4v_1 tr:hover td:first-of-type {
   border-left: 4px solid var(--puck-color-azure-4);
   padding-left: 20px;
 }

package/dist/index.d.ts

@@ -17,14 +17,14 @@ type Field<Props extends {
     arrayFields?: {
         [SubPropName in keyof Props]: Field<Props[SubPropName]>;
     };
-    getItemSummary?: (item: Props, index: number) => string;
+    getItemSummary?: (item: Props, index?: number) => string;
     defaultItemProps?: Props;
     options?: {
         label: string;
         value: string | number;
     }[];
 };
-type DefaultPageProps = {
+type DefaultRootProps = {
     children: ReactNode;
     title: string;
     editMode: boolean;
@@ -46,11 +46,11 @@ type Config<Props extends {
     [key: string]: any;
 } = {
     [key: string]: any;
-}, PageProps extends DefaultPageProps = DefaultPageProps> = {
+}, RootProps extends DefaultRootProps = DefaultRootProps> = {
     components: {
         [ComponentName in keyof Props]: ComponentConfig<Props[ComponentName]>;
     };
-    page?: ComponentConfig<PageProps & {
+    root?: ComponentConfig<RootProps & {
         children: ReactNode;
     }>;
 };
@@ -70,23 +70,23 @@ type Data<Props extends {
     [key: string]: any;
 } = {
     [key: string]: any;
-}, PageProps extends {
+}, RootProps extends {
     title: string;
     [key: string]: any;
 } = {
     title: string;
     [key: string]: any;
 }> = {
-    page: PageProps;
+    root: RootProps;
     content: MappedItem<Props>[];
 };
 
 type Plugin = {
-    renderPageFields?: (props: {
+    renderRootFields?: (props: {
         children: ReactNode;
         data: Data;
     }) => ReactElement<any>;
-    renderPage?: (props: {
+    renderRoot?: (props: {
         children: ReactNode;
         data: Data;
     }) => ReactElement<any>;
@@ -114,4 +114,4 @@ declare function Render({ config, data }: {
     data: Data;
 }): react_jsx_runtime.JSX.Element;
 
-export { Adaptor, ComponentConfig, Config, Data, DefaultComponentProps, DefaultPageProps, Field, Fields, Puck, Render };
+export { Adaptor, ComponentConfig, Config, Data, DefaultComponentProps, DefaultRootProps, Field, Fields, Puck, Render };

package/dist/index.js

@@ -293,7 +293,7 @@ var import_react4 = require("react");
 
 // css-module:/home/runner/work/puck/puck/packages/core/components/ExternalInput/styles.module.css#css-module
 init_react_import();
-var styles_module_default2 = { "ExternalInput": "_ExternalInput_v316c_1", "ExternalInput-actions": "_ExternalInput-actions_v316c_5", "ExternalInput-button": "_ExternalInput-button_v316c_9", "ExternalInput-detachButton": "_ExternalInput-detachButton_v316c_23", "ExternalInput--hasData": "_ExternalInput--hasData_v316c_30", "ExternalInput-modal": "_ExternalInput-modal_v316c_45", "ExternalInput--modalVisible": "_ExternalInput--modalVisible_v316c_59", "ExternalInput-modalInner": "_ExternalInput-modalInner_v316c_63", "ExternalInput-modalHeading": "_ExternalInput-modalHeading_v316c_74", "ExternalInput-modalTableWrapper": "_ExternalInput-modalTableWrapper_v316c_79" };
+var styles_module_default2 = { "ExternalInput": "_ExternalInput_1dp4v_1", "ExternalInput-actions": "_ExternalInput-actions_1dp4v_5", "ExternalInput-button": "_ExternalInput-button_1dp4v_9", "ExternalInput-detachButton": "_ExternalInput-detachButton_1dp4v_24", "ExternalInput--hasData": "_ExternalInput--hasData_1dp4v_31", "ExternalInput-modal": "_ExternalInput-modal_1dp4v_46", "ExternalInput--modalVisible": "_ExternalInput--modalVisible_1dp4v_60", "ExternalInput-modalInner": "_ExternalInput-modalInner_1dp4v_64", "ExternalInput-modalHeading": "_ExternalInput-modalHeading_1dp4v_75", "ExternalInput-modalTableWrapper": "_ExternalInput-modalTableWrapper_1dp4v_80" };
 
 // components/ExternalInput/index.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
@@ -333,7 +333,7 @@ var ExternalInput = ({
             {
               onClick: () => setOpen(true),
               className: getClassName2("button"),
-              children: selectedData ? selectedData.attributes.title : `Select from ${field.adaptor.name}`
+              children: selectedData ? field.getItemSummary ? field.getItemSummary(selectedData) : `${field.adaptor.name} item` : `Select from ${field.adaptor.name}`
             }
           ),
           selectedData && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
@@ -356,8 +356,8 @@ var ExternalInput = ({
             children: [
               /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { className: getClassName2("modalHeading"), children: "Select content" }),
               data.length ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: getClassName2("modalTableWrapper"), children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("table", { children: [
-                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("thead", { children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("tr", { children: Object.keys(data[0].attributes).map((key) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("th", { style: { textAlign: "left" }, children: key }, key)) }) }),
-                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("tbody", { children: data.map((item) => {
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("thead", { children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("tr", { children: Object.keys(data[0]).map((key) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("th", { style: { textAlign: "left" }, children: key }, key)) }) }),
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("tbody", { children: data.map((item, i) => {
                   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
                     "tr",
                     {
@@ -367,12 +367,12 @@ var ExternalInput = ({
                         setOpen(false);
                         setSelectedData(item);
                       },
-                      children: Object.keys(item.attributes).map((key) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("td", { children: item.attributes[key] }, key))
+                      children: Object.keys(item).map((key) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("td", { children: item[key] }, key))
                     },
-                    item.id
+                    i
                   );
                 }) })
-              ] }) }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { children: "No content" })
+              ] }) }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { style: { padding: 24 }, children: "No content" })
             ]
           }
         ) })
@@ -868,7 +868,7 @@ var PluginRenderer = ({
 };
 function Puck({
   config,
-  data: initialData = { content: [], page: { title: "" } },
+  data: initialData = { content: [], root: { title: "" } },
   onChange,
   onPublish,
   plugins = [],
@@ -884,20 +884,20 @@ function Puck({
         PluginRenderer,
         {
           plugins,
-          renderMethod: "renderPage",
+          renderMethod: "renderRoot",
           data: pageProps.data,
-          children: ((_a2 = config.page) == null ? void 0 : _a2.render) ? (_b2 = config.page) == null ? void 0 : _b2.render(__spreadProps(__spreadValues({}, pageProps), { editMode: true })) : pageProps.children
+          children: ((_a2 = config.root) == null ? void 0 : _a2.render) ? (_b2 = config.root) == null ? void 0 : _b2.render(__spreadProps(__spreadValues({}, pageProps), { editMode: true })) : pageProps.children
         }
       );
     },
-    [config.page]
+    [config.root]
   );
   const PageFieldWrapper = (0, import_react7.useCallback)(
     (props) => /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
       PluginRenderer,
       {
         plugins,
-        renderMethod: "renderPageFields",
+        renderMethod: "renderRootFields",
         data: props.data,
         children: props.children
       }
@@ -917,8 +917,8 @@ function Puck({
     []
   );
   const FieldWrapper = selectedIndex !== null ? ComponentFieldWrapper : PageFieldWrapper;
-  const pageFields = ((_a = config.page) == null ? void 0 : _a.fields) || defaultPageFields;
-  let fields = selectedIndex !== null ? ((_b = config.components[data.content[selectedIndex].type]) == null ? void 0 : _b.fields) || {} : pageFields;
+  const rootFields = ((_a = config.root) == null ? void 0 : _a.fields) || defaultPageFields;
+  let fields = selectedIndex !== null ? ((_b = config.components[data.content[selectedIndex].type]) == null ? void 0 : _b.fields) || {} : rootFields;
   (0, import_react7.useEffect)(() => {
     if (onChange)
       onChange(data);
@@ -1036,7 +1036,8 @@ function Puck({
                       {
                         style: {
                           textAlign: "center",
-                          color: "var(--puck-color-grey-6)"
+                          color: "var(--puck-color-grey-6)",
+                          fontFamily: "var(--puck-font-stack)"
                         },
                         children: "Add items to your page"
                       }
@@ -1083,7 +1084,7 @@ function Puck({
                       overflow: "hidden",
                       zoom: 0.75
                     },
-                    children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Page, __spreadProps(__spreadValues({ data }, data.page), { children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(DroppableStrictMode_default, { droppableId: "droppable", children: (provided, snapshot) => /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
+                    children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Page, __spreadProps(__spreadValues({ data }, data.root), { children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(DroppableStrictMode_default, { droppableId: "droppable", children: (provided, snapshot) => /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
                       "div",
                       __spreadProps(__spreadValues({}, provided.droppableProps), {
                         ref: provided.innerRef,
@@ -1176,7 +1177,7 @@ function Puck({
                         if (selectedIndex !== null) {
                           currentProps = data.content[selectedIndex].props;
                         } else {
-                          currentProps = data.page;
+                          currentProps = data.root;
                         }
                         if (fieldName === "_data") {
                           if (!value) {
@@ -1188,8 +1189,7 @@ function Puck({
                           } else {
                             const changedFields = filter(
                               // filter out anything not supported by this component
-                              value.attributes,
-                              // TODO type properly after getting proper state library
+                              value,
                               Object.keys(fields)
                             );
                             newProps = __spreadProps(__spreadValues(__spreadValues({}, currentProps), changedFields), {
@@ -1212,7 +1212,7 @@ function Puck({
                             }))
                           }));
                         } else {
-                          setData(__spreadProps(__spreadValues({}, data), { page: newProps }));
+                          setData(__spreadProps(__spreadValues({}, data), { root: newProps }));
                         }
                       };
                       if (selectedIndex !== null) {
@@ -1235,8 +1235,8 @@ function Puck({
                             field,
                             name: fieldName,
                             label: field.label,
-                            readOnly: ((_d = (_c = data.page._meta) == null ? void 0 : _c.locked) == null ? void 0 : _d.indexOf(fieldName)) > -1,
-                            value: data.page[fieldName],
+                            readOnly: ((_d = (_c = data.root._meta) == null ? void 0 : _c.locked) == null ? void 0 : _d.indexOf(fieldName)) > -1,
+                            value: data.root[fieldName],
                             onChange: onChange2
                           },
                           `page_${fieldName}`
@@ -1262,8 +1262,8 @@ function Render({ config, data }) {
     const Component = config.components[item.type].render;
     return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(Component, __spreadValues({}, item.props), item.props.id);
   });
-  if (config.page) {
-    return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(config.page.render, __spreadProps(__spreadValues({}, data.page), { editMode: false, children }));
+  if (config.root) {
+    return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(config.root.render, __spreadProps(__spreadValues({}, data.root), { editMode: false, children }));
   }
   return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { children });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@measured/puck",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",