feat: add data migration API

apps/docs/pages/docs/api-reference/data.mdx

@@ -18,27 +18,31 @@ An object produced by Puck describing the shape of content.
 }
 ```
 
-## `content`
+This document describes the latest supported data. To learn more about automatic data migration, visit the [Data Migration docs](/docs/integrating-puck/data-migration).
+
+## Params
+
+#### `content`
 
 An array containing an object for each component in the main content region.
 
-### `content[*]`
+#### `content[*]`
 
-#### Params
+##### Params
 
 | Param                          | Example                            | Type    | Status   |
 | ------------------------------ | ---------------------------------- | ------- | -------- |
 | [`type`](#contenttype)         | `type: "HeadingBlock"`             | "array" | Required |
 | [`props`](#contentprops)       | `props: { title: "Hello, world" }` | Object  | Required |
 | [`readOnly`](#contentreadonly) | `readOnly: { title: true }`        | Object  | -        |
 
-#### Required params
+##### Required params
 
-##### `content[*].type`
+###### `content[*].type`
 
 The type of the component, which tells Puck to run the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the component of the [same key](/docs/api-reference/config#components).
 
-##### `content[*].props`
+###### `content[*].props`
 
 The props stored based on the [`component config`](/docs/api-reference/configuration/component-config) that Puck will pass to the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the component of the [same key](/docs/api-reference/config#components).
 
@@ -58,9 +62,9 @@ The props stored based on the [`component config`](/docs/api-reference/configura
 }
 ```
 
-#### Optional params
+##### Optional params
 
-##### `content[*].readOnly`
+###### `content[*].readOnly`
 
 An object describing which fields are set to [read-only](/docs/api-reference/configuration/component-config#datareadonly-1).
 
@@ -83,20 +87,20 @@ An object describing which fields are set to [read-only](/docs/api-reference/con
 }
 ```
 
-## `root`
+### `root`
 
 An object describing data for the [`root` config](/docs/api-reference/config#root).
 
-### Params
+#### Params
 
 | Param                       | Example                            | Type   | Status |
 | --------------------------- | ---------------------------------- | ------ | ------ |
 | [`props`](#rootprops)       | `props: { title: "Hello, world" }` | Object | -      |
 | [`readOnly`](#rootreadonly) | `readOnly: { title: true }`        | Object | -      |
 
-### Optional params
+#### Optional params
 
-#### `root.props`
+##### `root.props`
 
 The props stored based on the [`component config`](/docs/api-reference/configuration/component-config) that Puck will pass to the [`render()`](/docs/api-reference/configuration/component-config#renderprops) method for the [`root` config](/docs/api-reference/config#root).
 
@@ -108,7 +112,7 @@ The props stored based on the [`component config`](/docs/api-reference/configura
 }
 ```
 
-#### `root.readOnly`
+##### `root.readOnly`
 
 An object describing which fields are set to [read-only](/docs/api-reference/configuration/component-config#datareadonly-1).
 
@@ -124,11 +128,11 @@ An object describing which fields are set to [read-only](/docs/api-reference/con
 }
 ```
 
-## `zones`
+### `zones`
 
 An object describing nested content regions for each [DropZone](/docs/api-reference/components/drop-zone).
 
-### `zones[zoneKey]`
+#### `zones[zoneKey]`
 
 An array describing the content for a particular region. Shares a shape with [`content`](#content).
 

apps/docs/pages/docs/api-reference/functions.mdx

@@ -1,4 +1,5 @@
 # Functions
 
+- [migrate](functions/migrate) - Migrate a legacy [data payload](/docs/api-reference/data) to the latest shape.
 - [resolveAllData](functions/resolve-all-data) - Utility function to execute all [`resolveData` methods](/docs/api-reference/configuration/component-config#resolvedatadata-params) on a data payload.
 - [transformProps](functions/transform-props) - Transform component props stored in the [data payload](/docs/api-reference/data). Use this for migrations, like prop renames.

apps/docs/pages/docs/api-reference/functions/migrate.mdx

@@ -0,0 +1,21 @@
+---
+title: migrate
+---
+
+# migrate
+
+Migrate the [Data payload](/docs/api-reference/data) to the latest shape, automatically transforming deprecated data.
+
+```tsx copy showLineNumbers {7-10}
+import { migrate } from "@measured/puck";
+
+migrate(legacyData);
+```
+
+## Returns
+
+The updated [Data](/docs/api-reference/data) object.
+
+## Notes
+
+- Called internally whenever you pass data to [`<Puck>`](/docs/api-reference/components/puck) or [`<Render>`](/docs/api-reference/components/render), or calling [`transformProps`](/docs/api-reference/functions/transform-props).

apps/docs/pages/docs/integrating-puck/_meta.json

@@ -5,5 +5,7 @@
   "categories": {},
   "dynamic-props": {},
   "external-data-sources": {},
-  "server-components": {}
+  "server-components": {},
+  "prop-migration": {},
+  "data-migration": {}
 }

apps/docs/pages/docs/integrating-puck/data-migration.mdx

@@ -0,0 +1,36 @@
+# Data Migration
+
+Puck automatically migrates legacy data payloads on render, transforming any deprecated properties to their latest counterparts as described by [Data](/docs/api-reference/data).
+
+This data migration strategy reduces the number of breaking changes required.
+
+Specifically, Puck will migrate the data when rendering [`<Puck>`](/docs/api-reference/components/puck) or [`<Render>`](/docs/api-reference/components/render), or calling [`transformProps`](/docs/api-reference/functions/transform-props).
+
+## Types
+
+Puck exports two types:
+
+- `Data`, a backwards compatible type that supports all deprecated data shapes still supported.
+- `CurrentData`, the latest data shape used by Puck internally.
+
+You'll generally want to use `Data` to avoid breaking changes during minor version upgrades, but can use `CurrentData` to stay on the bleeding edge.
+
+## Manually migrating data
+
+If you manually want to update your data payload to the latest `CurrentData`, you can run the `migrate` method:
+
+```tsx
+import { migrate } from "@measured/puck";
+
+migrate(legacyData);
+```
+
+## Opting out
+
+There is currently no way to opt-out of automatic data migrations.
+
+## Further reading
+
+- [`Data` API reference](/docs/api-reference/data)
+- [`migrate` API reference](/docs/api-reference/functions/migrate)
+- [Prop migration](/docs/integrating-puck/prop-migration)

packages/core/index.ts

@@ -11,6 +11,6 @@ export * from "./components/Puck";
 export * from "./components/Render";
 
 export * from "./lib/resolve-all-data";
-export { transformProps } from "./transforms";
+export { migrate, transformProps } from "./transforms";
 
 export { FieldLabel } from "./components/InputOrGroup";