v0.11.0 - Categories and dynamic props

Summary

This release introduces new APIs for categories and dynamic prop resolution, and updates the Next.js recipe to render static pages.

Categories API

The categories API enables the user to group their components in the left side bar.

Users can configure categories using the new categories configuration on the Puck config. They can also override this behaviour by using the renderComponentList API, accessible via the Puck root or plugins.

  categories: {
    layout: {
      components: ["Columns", "Flex", "VerticalSpace"],
    },
    typography: {
      components: ["Heading", "Text"],
    },
    interactive: {
      title: "Actions",
      components: ["ButtonGroup"],
    },
  },

Dynamic prop resolution

Dynamic prop resolution is an extremely powerful feature that enables developers to dynamically change props after the user has changed them. Full documentation available in the README.

This can be paired with external fields to query data from a third-party API, and also allows you to set fields as read-only.

const config = {
  components: {
    HeadingBlock: {
      fields: {
        heading: {
          type: "text",
        },
        title: {
          type: "text",
        },
      },
      resolveData: async (props) => {
        return {
          props: {
            title: props.heading, // map `heading` to `title`
          },
          readOnly: {
            title: true, // make `title` read-only
          },
        };
      },
      render: ({ title }) => {
        return <h1>{title}</h1>;
      },
    },
  },
};

Next.js recipe now supports static rendering

The default Next.js recipe has been updated to support static rendering, enabling Puck to generate static pages.

If you’ve already generated from this recipe and want to enable static rendering, we recommend manually updating your code to follow the latest best practices.

Deprecations

This release includes various backwards-compatible deprecations that will be breaking in a future release.

Deprecate use of props under root in Puck data in favour of root.props (7593584)

This affects all existing data payloads that make use of root. This allows us to align the behaviour of root with other components, including the new resolveData API.

{
  "root": {
    "title": "Hello, world"
  }
}

{
  "root": {
    "props": {
      "title": "Hello, world"
    },
  }
}

We may consider making this permanently backwards compatible via the transformers proposal.

Deprecate adaptor in favour of new external field APIs (7f13efc)

The adaptor API on external field types has been removed in favour of keeping them at the root of the field configuration.

{
  myField: {
    type: "external",
    adaptor: {
      name: "External Source",
      fetchList: () => {}
    }
  }
}

{
  myField: {
    type: "external",
    placeholder: "Select from External Source",
    fetchList: () => {}
  }
}

Deprecate magic _data API in favour of resolveData (4ee31e7)

The magic _data field name previously allowed you to spread the result of your adaptor call across your object. This has been replaced in favour of resolveData.

{
  fields: {
    _data: {
      type: "external",
      adaptor: {
        name: "External Source",
        fetchList: () => {
          return [{ title: "Hello, world" }];
        },
      },
    },
    title: {
      type: "text",
    },
  },
};

{
  fields: {
    data: {
      type: "external",
      // Also note adaptor API change
      placeholder: "Load from external Source",
      fetchList: () => {
        return [{ title: "Hello, world" }];
      },
    },
    title: {
      type: "text",
    },
  },
  resolveData: ({ props }) => ({ props: { ...props, ...props.data } }),
};

Features

• add categories API for grouping components in side bar (594cc76)
• add read-only states to all field types (746d896)
• add icon to external fields (a3a018b)
• add loading state to external field modal (5b4fc92)
• add lock icon when field is read-only (a051000)
• add mapProp API to external fields (86c4979)
• add renderComponentList API (ec985e3)
• add resolveData API for modifying props dynamically (c1181ad)
• deprecate adaptors in favour of new external field APIs (7f13efc)
• deprecate magic adaptor _data behaviour in favour of resolveData API (4ee31e7)
• deprecate props under root in favour of root.props (7593584)
• make external field more consistent with other fields (5bfbc5b)
• update next recipe to render to static (a333857)

Bug Fixes

• don't flicker root DropZone when dragging (358435c)
• ensure array fields can render if value is undefined (47ab3c9)
• isolate external field modal from high z-indexes (fdf97c7)
• make Field types required based on type (daf36ac)
• prevent global style pollution in external fields (429731d)
• prevent long header titles from rendering over actions (4613df4)
• use correct heading component for external inputs (462266d)

Performance Improvements

• cache data between fetchList calls in external fields (04b7322)
• improve render performance of fields (d92de7f)

New Contributors

• @sagarchoudhary96 made their first contribution in https://github.com/measuredco/puck/pull/180

Full Changelog: https://github.com/measuredco/puck/compare/v0.10.0...v0.11.0