@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/api-reference/functions/register-overlay-portal.md

@@ -0,0 +1,45 @@
+# registerOverlayPortal
+
+Register a node as an [Overlay Portal](/docs/integrating-puck/overlay-portals), enabling interaction beneath the Puck overlay.
+
+```tsx
+import { registerOverlayPortal } from "@puckeditor/core";
+
+const MyComponent = () => {
+  const ref = useRef(null);
+
+  useEffect(() => registerOverlayPortal(ref.current), [ref.current]);
+
+  return <button ref={ref}>Clickable</button>;
+};
+```
+
+## Args
+
+| Param           | Example | Type                                                                        | Status |
+| --------------- | ------- | --------------------------------------------------------------------------- | ------ |
+| [`el`](#el)     | `div`   | [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) | -      |
+| [`opts`](#opts) | `{}`    | [Config](/docs/api-reference/configuration/config)                          | -      |
+
+### `el`
+
+The element to turn into a portal. Will do nothing if `null` or `undefined`.
+
+### `opts`
+
+| Param                | Example | Type    | Status |
+| -------------------- | ------- | ------- | ------ |
+| `disableDrag`        | `false` | boolean | -      |
+| `disableDragOnFocus` | `false` | boolean | -      |
+
+#### `opts.disableDrag`
+
+Disable triggering a drag of the parent component when interacting with this element. Defaults to `false`.
+
+#### `opts.disableDragOnFocus`
+
+Disable triggering a drag of the parent component when interacting with this element once it is focused. Drag is disabled following a short delay after focusing. Defaults to `true`.
+
+## Returns
+
+A function to clean-up the portal.

package/dist/docs/api-reference/functions/resolve-all-data.md

@@ -0,0 +1,27 @@
+# resolveAllData
+
+Utility function to execute all [`resolveData` methods](/docs/api-reference/configuration/component-config#resolvedatadata-params) on a data payload outside of the [`<Puck>`](/docs/api-reference/components/puck) editor, returning the updated value.
+
+```tsx
+import { resolveAllData } from "@puckeditor/core";
+
+const updatedData = await resolveAllData(data, config);
+```
+
+This is useful if you need to run your resolvers before passing your data to [`<Render>`](/docs/api-reference/components/render).
+
+## Args
+
+| Param                   | Example              | Type                                               |
+| ----------------------- | -------------------- | -------------------------------------------------- |
+| `data`                  | `{}`                 | [Data](/docs/api-reference/data-model/data)        |
+| `config`                | `{ components: {} }` | [Config](/docs/api-reference/configuration/config) |
+| [`metadata`](#metadata) | `{}`                 | Object                                             |
+
+### metadata
+
+An object containing additional data provided to each component's [resolveData](/docs/api-reference/configuration/component-config#resolvedatadata-params) functions.
+
+## Returns
+
+The updated [Data](/docs/api-reference/data-model/data) object.

package/dist/docs/api-reference/functions/set-deep.md

@@ -0,0 +1,55 @@
+# setDeep
+
+A convenience utility for setting the value of a key deep within an object.
+
+Useful when implementing [field transforms](/docs/api-reference/field-transforms).
+
+This function only duplicates the objects and arrays along the path to the key being set, leaving the rest of the input object or array unchanged.
+
+```tsx
+import { setDeep } from "@puckeditor/core";
+
+const newData = setDeep(
+  {
+    object: {
+      array: [{ key: "Hello, world" }],
+    },
+  },
+  "object.array[0].key",
+  "Goodbye, world"
+);
+
+console.log(newData);
+// {
+//   object: {
+//     array: [{ key: "Goodbye, world" }],
+//   },
+// }
+```
+
+## Args
+
+| Param             | Example                 | Type            |
+| ----------------- | ----------------------- | --------------- |
+| [`input`](#input) | `{}`                    | Object \| Array |
+| [`path`](#path)   | `"object.array[0].key"` | String          |
+| [`value`](#value) | `"Hello, world"`        | Any             |
+
+### `input`
+
+The input object or array that contains the key to be updated.
+
+### `path`
+
+A dot-notated path that describes a key deep within an object or array.
+
+Uses dot-notation and square brackets:
+
+- `.` deliminates sub-props in an [object field](/docs/api-reference/fields/object) (i.e. `a.b` represents `b` where `a` is `{b: "Value"}`)
+- `[*]` which donate an index in an [array field](/docs/api-reference/fields/array) where `*` is an integer (i.e. `a[0].b` represents `b` in the first item in array `a` with the value `[{b: "Value"}]`)
+
+Commonly provided by the [propPath parameter](/docs/api-reference/field-transforms#proppath) for field transforms.
+
+### `value`
+
+The value to set the key to.

package/dist/docs/api-reference/functions/transform-props.md

@@ -0,0 +1,51 @@
+# transformProps
+
+Transform component props stored in a [Data payload](/docs/api-reference/data-model/data). This convenience method can be used for [prop renames and other data migrations](/docs/integrating-puck/data-migration).
+
+This method will modify all data in [`content`](/docs/api-reference/data-model/data#content) and [`zones`](/docs/api-reference/data-model/data#zones).
+
+```tsx
+import { transformProps } from "@puckeditor/core";
+
+const data = {
+  content: [{ type: "HeadingBlock", props: { title: "Hello, world" } }],
+};
+
+const updatedData = transformProps(data, {
+  // Rename `title` to `heading`
+  HeadingBlock: ({ title, ...props }) => ({ heading: title, ...props }),
+});
+
+console.log(updatedData);
+// { content: [{ type: "HeadingBlock", props: { heading: "Hello, world" } }] };
+```
+
+## Args
+
+| Param                       | Example                                | Type                                               | Status   |
+| --------------------------- | -------------------------------------- | -------------------------------------------------- | -------- |
+| [`data`](#data)             | `{}`                                   | [Data](/docs/api-reference/data-model/data)        | Required |
+| [`transforms`](#transforms) | `{ HeadingBlock: (props) => (props) }` | Object                                             | Required |
+| [`config`](#config)         | `{ components: {} }`                   | [Config](/docs/api-reference/configuration/config) | -        |
+
+### `data`
+
+The [Data payload](/docs/api-reference/data-model/data) to be transformed.
+
+### `transforms`
+
+An object describing the transform functions for each component defined in your [`config`](/docs/api-reference/configuration/config).
+
+- `root` is a reserved property, and can be used to update the [`root` component](/docs/api-reference/configuration/config#root) props.
+
+### `config`
+
+A [config](/docs/api-reference/configuration/config) object. Required if transforming data within [slots](/docs/api-reference/fields/slot).
+
+## Returns
+
+The updated [Data](/docs/api-reference/data-model/data) object.
+
+## Notes
+
+- It's important to consider that data may include both components with old data and new data, and write your transform accordingly.

package/dist/docs/api-reference/functions/use-get-puck.md

@@ -0,0 +1,24 @@
+# useGetPuck
+
+A hook that returns a function that retrieves the latest [`PuckApi`](/docs/api-reference/puck-api) at call time. This is useful in callbacks, effects, or any logic that runs outside the component render lifecycle.
+
+```tsx
+import { useGetPuck } from "@puckeditor/core";
+
+const Example = () => {
+  const getPuck = useGetPuck();
+
+  const handleClick = useCallback(() => {
+    // Current PuckApi is always provided
+    const { appState } = getPuck();
+  }, [getPuck]);
+
+  return <button onClick={handleClick}>Click me</button>;
+};
+```
+
+If you need to react to changes to `PuckApi`, try the [`usePuck` hook](/docs/api-reference/functions/use-puck).
+
+## Returns
+
+A function to retrieve the latest [`PuckApi`](/docs/api-reference/puck-api) data at call time.

package/dist/docs/api-reference/functions/use-puck.md

@@ -0,0 +1,43 @@
+# usePuck
+
+A hook for accessing the [`PuckApi`](/docs/api-reference/puck-api) as part of your React render lifecycle.. The best way to access `usePuck` is via the `createUsePuck()` factory.
+
+```tsx
+import { createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const Example = () => {
+  const type = usePuck((s) => s.selectedItem?.type || "Nothing");
+
+  return <h2>{type} selected</h2>;
+};
+```
+
+You can also access `usePuck` as a direct export, but you won't be able to use [selectors](#selectordata), resulting in unwanted re-renders and degraded performance.
+
+## Args
+
+| Param                             | Example                      | Type     |
+| --------------------------------- | ---------------------------- | -------- |
+| [`selector(data)`](#selectordata) | `(s: PuckApi) => s.appState` | Function |
+
+### `selector(data)`
+
+A selector function that describes what `usePuck` returns. Receives [`PuckApi`](/docs/api-reference/puck-api) and returns anything. Be as granular as possible to minimize re-renders.
+
+```tsx
+// Good: only re-render when the `selectedItem` changes
+const selectedItem = usePuck((s) => s.selectedItem);
+
+// Bad: re-render when anything changes
+const { selectedItem } = usePuck();
+const { selectedItem } = usePuck((s) => s);
+
+// Bad: selector creates a new object reference, causing an infinite comparison loop
+const { selectedItem } = usePuck((s) => ({ ...s.selectedItem }));
+```
+
+## Returns
+
+Whatever is returned by the [`selector`](#selectordata).

package/dist/docs/api-reference/functions/walk-tree.md

@@ -0,0 +1,88 @@
+# walkTree
+
+Recursively walk the entire tree for the [`Data`](/docs/api-reference/data-model/data) or a single [`ComponentData`](/docs/api-reference/data-model/component-data) node, using a depth-first approach where the deepest [slots](/docs/api-reference/fields/slot) are processed first.
+
+Receives a callback function that is called once for each slot. You can optionally return a value to update the slot.
+
+```tsx
+import { walkTree } from "@puckeditor/core";
+
+// Add the example prop to all children in the data
+const newData = walkTree(data, config, (content) =>
+  content.map((child) => ({
+    ...child,
+    props: { ...child.props, example: "Hello, world" },
+  }))
+);
+
+console.log(newData);
+// {
+//   "root": {},
+//   "content": [
+//     {
+//       "type": "Component",
+//       "props": {
+//         "id": "1234",
+//         "content": [
+//           {
+//             "type": "Child",
+//             "props": { "id": "5678", "example": "Hello, world" }
+//           }
+//         ],
+//         "example": "Hello, world"
+//       }
+//     }
+//   ]
+// }
+```
+
+## Args
+
+| Param                                        | Example                            | Type                                                                                                          |
+| -------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [`data`](#data)                              | `{ root: {}, content: [] }`        | [Data](/docs/api-reference/data-model/data) \| [ComponentData](/docs/api-reference/data-model/component-data) |
+| [`config`](#config)                          | `{ components: {} }`               | [Config](/docs/api-reference/configuration/config)                                                            |
+| [`callbackFn()`](#callbackfncontent-options) | `(content) => content.slice(0, 1)` | Function                                                                                                      |
+
+### `data`
+
+The [`Data`](/docs/api-reference/data-model/data) or [`ComponentData`](/docs/api-reference/data-model/component-data) to traverse.
+
+### `config`
+
+A Puck [config](/docs/api-reference/configuration/config) object, used to determine which components contain slots.
+
+### `callbackFn(content, options)`
+
+A callback function called for each slot. Receives an array of [`ComponentData`](/docs/api-reference/data-model/component-data). Optionally returns an updated array of [`ComponentData`](/docs/api-reference/data-model/component-data) to update the content for this slot.
+
+#### Args
+
+| Param                 | Example                                         | Type                                                               |
+| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------ |
+| [`content`](#content) | `[{ type: "Heading", props: {} }]`              | [`ComponentData[]`](/docs/api-reference/data-model/component-data) |
+| [`options`](#options) | `{ parentId: "Flex-123", propName: "Content" }` | object                                                             |
+
+##### `content`
+
+An array of [`ComponentData`](/docs/api-reference/data-model/component-data), containing all the nodes for this slot.
+
+##### `options`
+
+An object containing additional options
+
+##### `options.parentId`
+
+The id of the parent component that defines this slot.
+
+##### `options.propName`
+
+The name of the slot field.
+
+#### Returns
+
+Optionally return an updated array of [`ComponentData`](/docs/api-reference/data-model/component-data) objects.
+
+## Returns
+
+A new [`Data`](/docs/api-reference/data-model/data) or [`ComponentData`](/docs/api-reference/data-model/component-data) object populated with any values returned by the callbackFn.

package/dist/docs/api-reference/functions.md

@@ -0,0 +1,8 @@
+# Functions
+
+- [migrate](/docs/api-reference/functions/migrate) - Migrate a legacy [data payload](/docs/api-reference/data-model/data) to the latest shape.
+- [resolveAllData](/docs/api-reference/functions/resolve-all-data) - Utility function to execute all [`resolveData` methods](/docs/api-reference/configuration/component-config#resolvedatadata-params) on a data payload.
+- [transformProps](/docs/api-reference/functions/transform-props) - Transform component props stored in the [data payload](/docs/api-reference/data-model/data). Use this for migrations, like prop renames.
+- [useGetPuck](/docs/api-reference/functions/use-get-puck) - A hook for accessing the latest [PuckApi](/docs/api-reference/puck-api) outside of the React render lifecycle.
+- [usePuck](/docs/api-reference/functions/use-puck) - A hook for accessing the [PuckApi](/docs/api-reference/puck-api) inside your components.
+- [walkTree](/docs/api-reference/functions/walk-tree) - Walk the tree recursively, modifying it if necessary.

package/dist/docs/api-reference/overrides/action-bar.md

@@ -0,0 +1,35 @@
+# actionBar
+
+Override the action bar. Use the [`<ActionBar>` component](/docs/api-reference/components/action-bar) to extend the default ActionBar UI.
+
+```tsx
+import { ActionBar } from "@puckeditor/core";
+
+const overrides = {
+  actionBar: ({ children, label }) => (
+    <ActionBar label={label}>
+      <ActionBar.Group>{children}</ActionBar.Group>
+    </ActionBar>
+  ),
+};
+```
+
+## Props
+
+| Prop                            | Example          | Type      |
+| ------------------------------- | ---------------- | --------- |
+| [`children`](#children)         | `<div />`        | ReactNode |
+| [`label`](#label)               | `"HeadingBlock"` | String    |
+| [`parentAction`](#parentAction) | `<div />`        | ReactNode |
+
+### `children`
+
+A fragment containing the default [actions](/docs/api-reference/components/action-bar-action). This should normally be rendered inside an [`<ActionBar.Group>`](/docs/api-reference/components/action-bar-group).
+
+### `label`
+
+The default label for the action bar.
+
+### `parentAction`
+
+A single [`<ActionBar.Action>`](/docs/api-reference/components/action-bar-action) to select the current component's parent.

package/dist/docs/api-reference/overrides/component-overlay.md

@@ -0,0 +1,41 @@
+# componentOverlay
+
+Override the overlay shown on hover or selection of a component.
+
+```tsx
+const overrides = {
+  overlay: ({ children }) => <div>{children}</div>,
+};
+```
+
+## Props
+
+| Prop                              | Example        | Type      |
+| --------------------------------- | -------------- | --------- |
+| [`children`](#children)           | `<div />`      | ReactNode |
+| [`componentId`](#componentid)     | `Heading-1234` | string    |
+| [`componentType`](#componenttype) | `Heading`      | string    |
+| [`hover`](#hover)                 | `false`        | boolean   |
+| [`isSelected`](#isselected)       | `false`        | boolean   |
+
+### `children`
+
+The default node for the overlay.
+
+### `componentId`
+
+The [id](/docs/api-reference/overrides/component-overlay) for the component underneath the overlay.
+
+### `componentType`
+
+The [type](/docs/api-reference/overrides/component-overlay) for the component underneath the overlay.
+
+### `hover`
+
+Whether or not the the component for this overlay is hovered over.
+
+A parent will not be `true` if a child node is `true`.
+
+### `isSelected`
+
+Whether or not the the component for this overlay is selected.

package/dist/docs/api-reference/overrides/drawer-item.md

@@ -0,0 +1,24 @@
+# drawerItem
+
+Override an item within the component drawer.
+
+```tsx
+const overrides = {
+  drawerItem: ({ name }) => <div>{name}</div>,
+};
+```
+
+## Props
+
+| Prop                    | Example    | Type      |
+| ----------------------- | ---------- | --------- |
+| [`children`](#children) | `<div />`  | ReactNode |
+| [`name`](#name)         | `"Button"` | ReactNode |
+
+### `children`
+
+The default node for the drawer item.
+
+### `name`
+
+The name of the drawer item.

package/dist/docs/api-reference/overrides/drawer.md

@@ -0,0 +1,19 @@
+# drawer
+
+Override the component drawer.
+
+```tsx
+const overrides = {
+  drawer: ({ children }) => <div>{children}</div>,
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `children`
+
+The default node for the component list.

package/dist/docs/api-reference/overrides/field-label.md

@@ -0,0 +1,18 @@
+# fieldLabel
+
+Override the label for all internal fields.
+
+```tsx
+const overrides = {
+  fieldLabel: ({ children, label }) => (
+    <label>
+      <div>{label}</div>
+      {children}
+    </label>
+  ),
+};
+```
+
+## Props
+
+See [FieldLabel](/docs/api-reference/components/field-label) component.

package/dist/docs/api-reference/overrides/field-types.md

@@ -0,0 +1,51 @@
+# fieldTypes
+
+Override or hide each [field type](/docs/api-reference/fields).
+
+```tsx
+const overrides = {
+  fieldTypes: {
+    number: ({ onChange }) => (
+      <input type="number" onChange={(e) => onChange(e.currentTarget.value)} />
+    ),
+    text: ({ onChange }) => (
+      <input type="text" onChange={(e) => onChange(e.currentTarget.value)} />
+    ),
+    // ...
+  },
+};
+```
+
+You can specify a custom render method for each known [field type](/docs/api-reference/fields), or introduce completely new ones.
+
+## Hiding field types
+
+Set a field type to `null` to hide every field of that type from the fields sidebar.
+
+```tsx
+const overrides = {
+  fieldTypes: {
+    text: null,
+  },
+};
+```
+
+[Plugins](/docs/api-reference/plugins) can override this behavior, showing hidden field types if necessary.
+
+## Render Props
+
+Extends the [`<AutoField>` API](/docs/api-reference/components/auto-field).
+
+| Prop                    | Example     | Type                                                           |
+| ----------------------- | ----------- | -------------------------------------------------------------- |
+| [`children`](#children) | `<input />` | ReactNode                                                      |
+| [`name`](#name)         | `"title"`   | string                                                         |
+| `...`                   | `{}`        | [`<AutoField>` API](/docs/api-reference/components/auto-field) |
+
+### `children`
+
+The default node for this field type.
+
+### `name`
+
+The name of the prop this field is rendering for.

package/dist/docs/api-reference/overrides/fields.md

@@ -0,0 +1,19 @@
+# fields
+
+Override the fields wrapper.
+
+```tsx
+const overrides = {
+  fields: ({ children }) => <div>{children}</div>,
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `children`
+
+The default node for the fields.

package/dist/docs/api-reference/overrides/header-actions.md

@@ -0,0 +1,24 @@
+# headerActions
+
+Override the header actions. Return a fragment so your items appear inline.
+
+```tsx
+const overrides = {
+  headerActions: ({ children }) => (
+    <>
+      {children}
+      <button>Click me</button>
+    </>
+  ),
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `children`
+
+The default node for the header actions, which includes the default publish button.

package/dist/docs/api-reference/overrides/header.md

@@ -0,0 +1,29 @@
+# header
+
+Override the header.
+
+```tsx
+const overrides = {
+  header: ({ actions }) => (
+    <header>
+      <span>My header</span>
+      <div>{actions}</div>
+    </header>
+  ),
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`actions`](#actions)   | `<div />` | ReactNode |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `actions`
+
+A node containing the [`headerActions`](/docs/api-reference/overrides/header-actions).
+
+### `children`
+
+The default node for the header.

package/dist/docs/api-reference/overrides/iframe.md

@@ -0,0 +1,32 @@
+# iframe
+
+Override the root of the iframe.
+
+```tsx
+const overrides = {
+  iframe: ({ children, document }) => {
+    useEffect(() => {
+      if (document) {
+        document.body.setAttribute("style", "background: hotpink;");
+      }
+    }, [document]);
+
+    return <>{children}</>;
+  },
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`document`](#document) | `{}`      | Document  |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `document`
+
+The document of the iframe window.
+
+### `children`
+
+The default node for the iframe.

package/dist/docs/api-reference/overrides/outline.md

@@ -0,0 +1,19 @@
+# outline
+
+Override the outline.
+
+```tsx
+const overrides = {
+  outline: ({ children }) => <div>{children}</div>,
+};
+```
+
+## Props
+
+| Prop                    | Example   | Type      |
+| ----------------------- | --------- | --------- |
+| [`children`](#children) | `<div />` | ReactNode |
+
+### `children`
+
+The default node for the outline.