@measured/puck 0.11.3 → 0.12.0-canary.01939fc

package/README.md

@@ -1,4 +1,4 @@
-# puck
+# Puck
 
 The self-hosted, drag and drop editor for React.
 
@@ -17,25 +17,30 @@ The self-hosted, drag and drop editor for React.
   </a>
 </p>
 
-## Features
+## Demo
 
-- 🖱️ **Drag and drop**: Visual editing for your existing React component library
-- 🌐 **Integrations**: Load your content from a 3rd party headless CMS
-- ✍️ **Inline editing**: Author content directly via puck for convenience
-- ⭐️ **No vendor lock-in**: Self-host or integrate with your existing application
+Visit https://demo.puckeditor.com/edit to try the demo.
 
-[See demo](https://puck-editor-demo.vercel.app/edit)
+## Documentation
 
-## Example
+Visit https://puckeditor.com to view the full documentation.
+
+## Quick start
+
+Install the package:
+
+```sh
+npm i @measured/puck --save # or npx create-puck-app my-app
+```
 
 Render the editor:
 
 ```jsx
 // Editor.jsx
 import { Puck } from "@measured/puck";
-import "@measured/puck/dist/index.css";
+import "@measured/puck/puck.css";
 
-// Create puck component config
+// Create Puck component config
 const config = {
   components: {
     HeadingBlock: {
@@ -71,465 +76,24 @@ Render the page:
 ```jsx
 // Page.jsx
 import { Render } from "@measured/puck";
-import "@measured/puck/dist/index.css";
+import "@measured/puck/puck.css";
 
 export function Page() {
   return <Render config={config} data={data} />;
 }
 ```
 
-## Installation
-
-Install the package
-
-```
-npm i @measured/puck --save
-```
+## Recipes
 
-Or generate a puck application using a recipe
+Use `create-puck-app` to quickly spin up a a pre-configured app based on our provided [recipes](https://github.com/measuredco/puck/tree/main/recipes):
 
 ```sh
 npx create-puck-app my-app
 ```
 
-## Recipes
-
-Puck is a React component that can be easily integrated into your existing application. We also provide helpful recipes for common use cases:
-
-- [**next**](https://github.com/measuredco/puck/tree/main/recipes/next): Next.js app example
-
-## Plugins
-
-Puck can be configured to work with plugins. Plugins can extend the functionality to support novel functionality.
-
-### Official plugins
-
-- [`heading-analyzer`](https://github.com/measuredco/puck/tree/main/packages/plugin-heading-analyzer): Analyze the heading outline of your page and be warned when you're not respecting WCAG 2 accessibility standards.
-
-### Developing a plugin
-
-The plugin API follows a React paradigm. Each plugin passed to the Puck editor can provide three functions:
-
-- `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 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.
-
-#### Example
-
-Here's an example plugin that creates a button to toggle the left side-bar:
-
-```jsx
-const myPlugin = {
-  renderRootFields: ({ children, dispatch, state }) => (
-    <div>
-      {children}
-
-      <button
-        onClick={() => {
-          dispatch({
-            type: "setUi",
-            ui: { leftSideBarVisible: !state.ui.leftSideBarVisible },
-          });
-        }}
-      >
-        Toggle side-bar
-      </button>
-    </div>
-  ),
-};
-```
-
-## Custom fields
-
-Puck supports custom fields using the `custom` field type and `render` method.
-
-In this example, we optionally add the `<FieldLabel>` component to add a label:
-
-```tsx
-import { FieldLabel } from "@measured/puck";
-
-export const MyComponent: ComponentConfig = {
-  fields: {
-    myField: {
-      type: "custom",
-      render: ({ field, name, onChange, value }) => {
-        return (
-          <FieldLabel label={field.label || name}>
-            <input
-              placeholder="Enter text..."
-              type="text"
-              name={name}
-              defaultValue={value}
-              onChange={(e) => onChange(e.currentTarget.value)}
-            ></input>
-          </FieldLabel>
-        );
-      },
-    },
-  },
-};
-```
-
-## DropZones
-
-Puck supports creating complex layouts (like multi-column layouts) using the `<DropZone>` component.
-
-### Example
-
-In this example, we use the `<DropZone>` component to render two nested DropZones within another component:
-
-```tsx
-import { DropZone } from "@measured/puck";
-
-export const MyComponent: ComponentConfig = {
-  render: () => {
-    return (
-      <div>
-        <DropZone zone="first-drop-zone">
-        <DropZone zone="second-drop-zone">
-      </div>
-    )
-  }
-};
-```
-
-### Custom root entry points
-
-You can also do this at the root of your component. This is useful if you have a fixed layout and only want to make certain parts of your page customisable:
-
-```tsx
-import { DropZone, Config } from "@measured/puck";
-
-export const config: Config = {
-  root: {
-    render: ({ children }) => {
-      return (
-        <div>
-          {/* children renders the default zone. This can be omitted if necessary. */}
-          {children}
-
-          <div>
-            <DropZone zone="other-drop-zone">
-          </div>
-        </div>
-      )
-    }
-  }
-};
-```
-
-### The Rules of DropZones
-
-The current DropZone implementation has certain rules and limitations:
-
-1. You can drag from the component list on the LHS into any DropZone
-2. You can drag components between DropZones, so long as those DropZones share a parent (also known as _area_)
-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>`
-
-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
-- **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
-- **headerPath** (`string` [optional]): Set a path to show after the header title
-- **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
-
-### `<DropZone>`
-
-The `<DropZone>` component allows you to create advanced layouts, like multi-columns.
-
-- **zone** (`string`): Identifier for the zone of your component, unique to the parent component
-- **style** (`CSSProperties`): Custom inline styles
-
-### `Config`
-
-The `Config` object describes which components Puck should render, how they should render and which inputs are available to them.
-
-- **root** (`object`)
-  - **fields** (`object`):
-    - **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.
-
-### All Fields
-
-- **label** (`text` [optional]): A label for the input. Will use the key if not provided.
-
-### 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`)
-
-### 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
-  - **value** (`any`): Value for the field
-  - **onChange** (`(value: any) => void`): Callback to change the value
-  - **readOnly** (`boolean` | `undefined`): Whether or not the field should be in readOnly mode
-
-### `AppState`
-
-The `AppState` object stores the puck application state.
-
-- **data** (`Data`): The page data currently being rendered
-- **ui** (`object`):
-  - **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** (`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`
-
-Plugins that can be used to enhance Puck.
+Available recipes include:
 
-- **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
+- [**next**](https://github.com/measuredco/puck/tree/main/recipes/next): Next.js 13 app example, using App Router and static page generation
 
 ## Hire the Puck team
 

package/dist/Config-a03de579.d.ts

@@ -0,0 +1,196 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type ItemSelector = {
+    index: number;
+    zone?: string;
+};
+
+type DropZoneProps = {
+    zone: string;
+    style?: CSSProperties;
+};
+declare function DropZone(props: DropZoneProps): react_jsx_runtime.JSX.Element;
+
+type WithPuckProps<Props> = Props & {
+    id: string;
+};
+type BaseField = {
+    label?: string;
+};
+type TextField = BaseField & {
+    type: "text" | "number" | "textarea";
+};
+type SelectField = BaseField & {
+    type: "select" | "radio";
+    options: {
+        label: string;
+        value: string | number | boolean;
+    }[];
+};
+type ArrayField<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = BaseField & {
+    type: "array";
+    arrayFields: {
+        [SubPropName in keyof Props[0]]: Field<Props[0][SubPropName]>;
+    };
+    defaultItemProps?: Props[0];
+    getItemSummary?: (item: Props[0], index?: number) => string;
+};
+type Adaptor<AdaptorParams = {}, TableShape extends Record<string, any> = {}, PropShape = TableShape> = {
+    name: string;
+    fetchList: (adaptorParams?: AdaptorParams) => Promise<TableShape[] | null>;
+    mapProp?: (value: TableShape) => PropShape;
+};
+type ExternalFieldWithAdaptor<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = BaseField & {
+    type: "external";
+    placeholder?: string;
+    adaptor: Adaptor<any, any, Props>;
+    adaptorParams?: object;
+    getItemSummary: (item: Props, index?: number) => string;
+};
+type ExternalField<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = BaseField & {
+    type: "external";
+    placeholder?: string;
+    fetchList: () => Promise<any[] | null>;
+    mapProp?: (value: any) => Props;
+    getItemSummary: (item: Props, index?: number) => string;
+};
+type CustomField<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = BaseField & {
+    type: "custom";
+    render: (props: {
+        field: CustomField;
+        name: string;
+        value: any;
+        onChange: (value: Props) => void;
+        readOnly?: boolean;
+    }) => ReactElement;
+};
+type Field<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = TextField | SelectField | ArrayField<Props> | ExternalField<Props> | ExternalFieldWithAdaptor<Props> | CustomField;
+type DefaultRootProps = {
+    title?: string;
+    [key: string]: any;
+};
+type DefaultComponentProps = {
+    [key: string]: any;
+    editMode?: boolean;
+};
+type Fields<ComponentProps extends DefaultComponentProps = DefaultComponentProps> = {
+    [PropName in keyof Omit<Required<ComponentProps>, "children" | "editMode">]: Field<ComponentProps[PropName]>;
+};
+type Content<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = ComponentData<Props>[];
+type PuckComponent<Props extends DefaultComponentProps = DefaultComponentProps> = (props: WithPuckProps<Props & {
+    puck: PuckContext;
+}>) => JSX.Element;
+type PuckContext = {
+    renderDropZone: typeof DropZone;
+};
+type ComponentConfig<ComponentProps extends DefaultComponentProps = DefaultComponentProps, DefaultProps = ComponentProps, DataShape = ComponentData<ComponentProps>> = {
+    render: PuckComponent<ComponentProps>;
+    defaultProps?: DefaultProps;
+    fields?: Fields<ComponentProps>;
+    resolveData?: (data: DataShape, params: {
+        changed: Partial<Record<keyof ComponentProps, boolean>>;
+    }) => Promise<Partial<ComponentDataWithOptionalProps<ComponentProps>>> | Partial<ComponentDataWithOptionalProps<ComponentProps>>;
+};
+type Category<ComponentName> = {
+    components?: ComponentName[];
+    title?: string;
+    visible?: boolean;
+    defaultExpanded?: boolean;
+};
+type Config<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}, RootProps extends DefaultRootProps = DefaultRootProps, CategoryName extends string = string> = {
+    categories?: Record<CategoryName, Category<keyof Props>> & {
+        other?: Category<Props>;
+    };
+    components: {
+        [ComponentName in keyof Props]: Omit<ComponentConfig<Props[ComponentName], Props[ComponentName]>, "type">;
+    };
+    root?: Partial<ComponentConfig<RootProps & {
+        children: ReactNode;
+    }, Partial<RootProps & {
+        children: ReactNode;
+    }>, RootDataWithProps<RootProps>>>;
+};
+type BaseData<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = {
+    readOnly?: Partial<Record<keyof Props, boolean>>;
+};
+type ComponentData<Props extends DefaultComponentProps = DefaultComponentProps> = {
+    type: keyof Props;
+    props: WithPuckProps<Props>;
+} & BaseData<Props>;
+type RootDataWithProps<Props extends DefaultRootProps = DefaultRootProps> = {
+    props: Props;
+};
+type RootDataWithoutProps<Props extends DefaultRootProps = DefaultRootProps> = Props;
+type RootData<Props extends DefaultRootProps = DefaultRootProps> = BaseData<Props> & Partial<RootDataWithProps<Props>> & Partial<RootDataWithoutProps<Props>>;
+type ComponentDataWithOptionalProps<Props extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}> = Omit<ComponentData, "props"> & {
+    props: Partial<WithPuckProps<Props>>;
+};
+type MappedItem = ComponentData;
+type Data<Props extends DefaultComponentProps = DefaultComponentProps, RootProps extends DefaultRootProps = DefaultRootProps> = {
+    root: RootData<RootProps>;
+    content: Content<WithPuckProps<Props>>;
+    zones?: Record<string, Content<WithPuckProps<Props>>>;
+};
+type ItemWithId = {
+    _arrayId: string;
+    _originalIndex: number;
+    data: any;
+};
+type ArrayState = {
+    items: ItemWithId[];
+    openId: string;
+};
+type UiState = {
+    leftSideBarVisible: boolean;
+    itemSelector: ItemSelector | null;
+    arrayState: Record<string, ArrayState | undefined>;
+    componentList: Record<string, {
+        components?: string[];
+        title?: string;
+        visible?: boolean;
+        expanded?: boolean;
+    }>;
+};
+type AppState = {
+    data: Data;
+    ui: UiState;
+};
+
+export { AppState as A, BaseField as B, Config as C, Data as D, ExternalFieldWithAdaptor as E, Field as F, ItemSelector as I, MappedItem as M, PuckComponent as P, RootDataWithProps as R, SelectField as S, TextField as T, UiState as U, DefaultRootProps as a, RootData as b, ArrayField as c, Adaptor as d, ExternalField as e, CustomField as f, DefaultComponentProps as g, Fields as h, Content as i, PuckContext as j, ComponentConfig as k, BaseData as l, ComponentData as m, RootDataWithoutProps as n, ItemWithId as o, ArrayState as p, DropZone as q };