@puckeditor/cli 0.24.0-canary.301a0304

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

@@ -0,0 +1,63 @@
+# Actions
+
+Actions enable you to make changes to the internal [AppState](/docs/api-reference/data-model/app-state) via the [dispatcher](/docs/api-reference/puck-api#dispatch).
+
+This is a partial reference of the most useful actions. A full reference is available in [the codebase](https://github.com/puckeditor/puck/blob/main/packages/core/reducer/actions.tsx).
+
+## Types
+
+### `setData`
+
+Modify the [data payload](/docs/api-reference/data-model/data) currently managed by Puck.
+
+| Param  | Example           | Type                                        | Status   |
+| ------ | ----------------- | ------------------------------------------- | -------- |
+| `type` | `type: "setData"` | "setData"                                   | Required |
+| `data` | `data: {}`        | [Data](/docs/api-reference/data-model/data) | Required |
+
+#### Example
+
+```tsx
+dispatch({
+  type: "setData",
+  data: {},
+});
+```
+
+### `setUi`
+
+Change a value on Puck's [UI state](/docs/api-reference/data-model/app-state#ui).
+
+| Param  | Example                             | Type                                         | Status   |
+| ------ | ----------------------------------- | -------------------------------------------- | -------- |
+| `type` | `type: "setUi"`                     | "setUi"                                      | Required |
+| `ui`   | `ui: { leftSideBarVisible: false }` | [UiState](/docs/api-reference/app-state/#ui) | Required |
+
+#### Example
+
+```tsx
+dispatch({
+  type: "setUi",
+  ui: {
+    leftSideBarVisible: false,
+  },
+});
+```
+
+### `set`
+
+Change the entire [AppState](/docs/api-reference/data-model/app-state) in a single action.
+
+| Param   | Example                       | Type                                                 | Status   |
+| ------- | ----------------------------- | ---------------------------------------------------- | -------- |
+| `type`  | `type: "set"`                 | "set"                                                | Required |
+| `state` | `state: { data: {}, ui: {} }` | [AppState](/docs/api-reference/data-model/app-state) | Required |
+
+#### Example
+
+```tsx
+dispatch({
+  type: "set",
+  state: { data: {}, ui: {} },
+});
+```

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

@@ -0,0 +1,35 @@
+# \<ActionBar.Action\>
+
+Render an action button in the [`<ActionBar>`](/docs/api-reference/components/action-bar). Often used inside an [`<ActionBar.Group>`](/docs/api-reference/components/action-bar-group).
+
+```tsx
+<ActionBar>
+  <ActionBar.Action onClick={() => console.log("Clicked!")}>★</ActionBar.Action>
+</ActionBar>
+```
+
+## Props
+
+| Prop                    | Example      | Type      | Status   |
+| ----------------------- | ------------ | --------- | -------- |
+| [`children`](#children) | `<svg />`    | ReactNode | Required |
+| [`onClick`](#on-clicke) | `() => void` | Function  | -        |
+| [`label`](#label)       | `"Label"`    | String    | -        |
+
+## Required Props
+
+### `children`
+
+A node to render as the children of the action. Should be a string or an icon.
+
+Puck uses [Lucide icons](https://lucide.dev/icons/). You can use [lucide-react](https://lucide.dev/guide/packages/lucide-react) to choose a similar icon, if desired.
+
+### `onClick(e)`
+
+An [onClick callback](https://react.dev/learn/responding-to-events) triggered when the user clicks the action.
+
+## Optional Props
+
+### `label`
+
+A label to provide an accessible label when using icon.

package/dist/docs/api-reference/components/action-bar-group.md

@@ -0,0 +1,24 @@
+# \<ActionBar.Group\>
+
+Render an action group in the [`<ActionBar>`](/docs/api-reference/components/action-bar). Use [`<ActionBar.Separator>`](/docs/api-reference/components/action-bar-separator) instead to avoid wrapping elements.
+
+```tsx
+<ActionBar label="Actions">
+  <ActionBar.Group>Group 1</ActionBar.Group>
+  <ActionBar.Group>Group 2</ActionBar.Group>
+</ActionBar>
+```
+
+## Props
+
+| Prop                    | Example   | Type      | Status   |
+| ----------------------- | --------- | --------- | -------- |
+| [`children`](#children) | `<div />` | ReactNode | Required |
+
+## Required Props
+
+### `children`
+
+A node to render as the children of the action. If a fragment, the items will be rendered in a flex row.
+
+Normally contains [`<ActionBar.Action>`](/docs/api-reference/components/action-bar-action)

package/dist/docs/api-reference/components/action-bar-label.md

@@ -0,0 +1,25 @@
+# \<ActionBar.Label\>
+
+Render a label in the [`<ActionBar>`](/docs/api-reference/components/action-bar) or an [`<ActionBar.Group>`](/docs/api-reference/components/action-bar-group).
+
+```tsx
+<ActionBar>
+  <ActionBar.Label label="Label 1" />
+  <ActionBar.Group>
+    <ActionBar.Label label="Label 2" />
+    <ActionBar.Action>★</ActionBar.Action>
+  </ActionBar.Group>
+</ActionBar>
+```
+
+## Props
+
+| Prop              | Example   | Type   | Status   |
+| ----------------- | --------- | ------ | -------- |
+| [`label`](#label) | `"Label"` | String | Required |
+
+## Required Props
+
+### `label`
+
+The label text.

package/dist/docs/api-reference/components/action-bar-separator.md

@@ -0,0 +1,16 @@
+# \<ActionBar.Separator\>
+
+Render a separator in the [`<ActionBar>`](/docs/api-reference/components/action-bar). An alternative to [`<ActionBar.Group>`](/docs/api-reference/components/action-bar-group) that avoids wrapping elements.
+
+```tsx
+<ActionBar>
+  <ActionBar.Label label="Label 1" />
+  <ActionBar.Separator />
+  <ActionBar.Label label="Label 2" />
+  <ActionBar.Action>★</ActionBar.Action>
+</ActionBar>
+```
+
+## Props
+
+This component doesn't accept any props.

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

@@ -0,0 +1,32 @@
+# \<ActionBar\>
+
+Render the Puck ActionBar. Use this when overriding the [actionBar](/docs/api-reference/overrides/action-bar).
+
+```tsx
+<ActionBar label="Actions">
+  <ActionBar.Group>
+    <ActionBar.Action onClick={() => console.log("Clicked!")}>
+      ★
+    </ActionBar.Action>
+  </ActionBar.Group>
+</ActionBar>
+```
+
+## Props
+
+| Prop                    | Example   | Type      | Status   |
+| ----------------------- | --------- | --------- | -------- |
+| [`children`](#children) | `<div />` | ReactNode | Required |
+| [`label`](#label)       | `"Label"` | String    | Required |
+
+## Required Props
+
+### `children`
+
+The children for the ActionBar. Normally a fragment of [`<ActionBar.Action>` components](/docs/api-reference/components/action-bar-action).
+
+If this is a fragment, it will be rendered in a flex row.
+
+### `label`
+
+The label for the ActionBar.

package/dist/docs/api-reference/components/auto-field.md

@@ -0,0 +1,63 @@
+# \<AutoField\>
+
+Render a Puck field based on a [Field](/docs/api-reference/fields) object. Use this when building [custom fields](/docs/extending-puck/custom-fields) that need to use Puck-style fields internally.
+
+```tsx
+import { Autofield } from "@puckeditor/core";
+
+const CustomField = ({ onChange, value }) => (
+  <AutoField field={{ type: "text" }} onChange={onChange} value={value} />
+);
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: MyCustomField,
+        },
+      },
+    },
+  },
+};
+```
+
+## Props
+
+| Prop                    | Example                      | Type                                | Status   |
+| ----------------------- | ---------------------------- | ----------------------------------- | -------- |
+| [`field`](#field)       | `{ type: "text" }`           | [Field](/docs/api-reference/fields) | Required |
+| [`onChange`](#onchange) | `onChange("Goodbye, world")` | Function                            | Required |
+| [`value`](#value)       | `"Hello, world"`             | Any                                 | Required |
+| [`id`](#id)             | `"my-input"`                 | String                              | -        |
+| [`readOnly`](#readonly) | `true`                       | Boolean                             | -        |
+
+## Required Props
+
+### `field`
+
+An object containing the user defined [Field](/docs/api-reference/fields) configuration.
+
+### `onChange`
+
+A callback that triggers when the value changes.
+
+### `value`
+
+The current value for the field.
+
+## Optional Props
+
+### `id`
+
+An optional ID for this field. Will be generated if not specified.
+
+### `readOnly`
+
+A boolean describing whether or not this field is `readOnly`.
+
+## Further reading
+
+- [Custom fields](/docs/extending-puck/custom-fields)
+- [The `<FieldLabel>` API reference](/docs/api-reference/components/field-label)

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

@@ -0,0 +1,75 @@
+# \<Drawer.Item\>
+
+An item that can be dragged from a [`<Drawer>`](/docs/api-reference/components/drawer).
+
+```tsx
+import { Puck, Drawer } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck>
+      <Drawer>
+        <Drawer.Item name="Orange" />
+      </Drawer>
+    </Puck>
+  );
+}
+```
+
+## Props
+
+| Prop                                | Example                   | Type     | Status   |
+| ----------------------------------- | ------------------------- | -------- | -------- |
+| [`name`](#name)                     | `name: "Orange"`          | String   | Required |
+| [`children`](#children)             | `children: () => <div />` | Function | -        |
+| [`id`](#id)                         | `id: "OrangeComponent"`   | String   | -        |
+| [`isDragDisabled`](#isdragdisabled) | `isDragDisabled: false`   | Boolean  | -        |
+
+## Required props
+
+### `name`
+
+The name of this drawer item.
+
+- This will be rendered on the item by default.
+- Will be used as the `id`, unless otherwise specified
+
+## Optional props
+
+### `children`
+
+A custom render function to render inside the component.
+
+```tsx
+import { Puck, Drawer } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck>
+      <Drawer>
+        <Drawer.Item name="Orange">{() => <div>Orange 🍊</div>}</Drawer.Item>
+      </Drawer>
+    </Puck>
+  );
+}
+```
+
+#### Render Props
+
+| Prop                      | Example             | Type   |
+| ------------------------- | ------------------- | ------ |
+| [`children`](#children-1) | `children: <div />` | String |
+
+##### `children`
+
+The original node for the drawer item.
+
+### `id`
+
+A unique id for this drawer item. Defaults to the value of [`name`](#name).
+
+If using the `<Drawer>` as a component list to be dragged into `<Puck.Preview>`, this should be the key of a component defined in the [Config](/docs/api-reference/configuration/config).
+
+### `isDragDisabled`
+
+Whether or not this item is disabled.

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

@@ -0,0 +1,29 @@
+# \<Drawer\>
+
+A list of items that can be dragged into a [`<Puck.Preview>`](/docs/api-reference/components/puck-preview). Used for composing custom Puck UIs.
+
+```tsx
+import { Puck, Drawer } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck>
+      <Drawer>
+        <Drawer.Item name="Orange" />
+      </Drawer>
+    </Puck>
+  );
+}
+```
+
+## Props
+
+| Param                   | Example                     | Type      | Status   |
+| ----------------------- | --------------------------- | --------- | -------- |
+| [`children`](#children) | `children: <Drawer.Item />` | ReactNode | Required |
+
+## Required props
+
+### `children`
+
+A React node representing the contents of the `<Drawer>`. Will likely contain [`<Drawer.Item>`](/docs/api-reference/components/drawer-item) nodes.

package/dist/docs/api-reference/components/drop-zone.md

@@ -0,0 +1,232 @@
+# \<DropZone\>
+
+> **Note:** The [`<DropZone>` component](/docs/api-reference/components/drop-zone) component is being replaced by the [`slot` field](/docs/api-reference/fields/slot), and will soon be deprecated and removed. For migration notes, see [these docs](/docs/guides/migrations/dropzones-to-slots).
+
+Place droppable regions (zones) inside other components to enable nested components.
+
+```tsx
+import { DropZone } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+## Props
+
+| Param                               | Example                      | Type                                 | Status   |
+| ----------------------------------- | ---------------------------- | ------------------------------------ | -------- |
+| [`zone`](#zone)                     | `zone: "my-zone"`            | String                               | Required |
+| [`allow`](#allow)                   | `allow: ["HeadingBlock"]`    | Array                                | -        |
+| [`className`](#classname)           | `className: "MyClass"`       | String                               | -        |
+| [`collisionAxis`](#collisionaxis)   | `collisionAxis: "x"`         | String                               | -        |
+| [`disallow`](#disallow)             | `disallow: ["HeadingBlock"]` | Array                                | -        |
+| [`minEmptyHeight`](#minemptyheight) | `minEmptyHeight: "256px"`    | CSSProperties["minHeight"] \| number | -        |
+| [`ref`](#ref)                       | `ref: ref`                   | Ref                                  | -        |
+| [`style`](#style)                   | `style: {display: "flex"}`   | CSSProperties                        | -        |
+
+## Required props
+
+### `zone`
+
+Set the zone identifier for the given DropZone.
+
+Must be unique within this component, but two different components can both define DropZones with the same `zone` value.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+## Optional props
+
+### `allow`
+
+Only allow specific components to be dragged into the DropZone:
+
+> **Note:** Drag-and-drop in the outline does not respect this prop. Prefer the [`allow`
+> parameter on the slot field](/docs/api-reference/fields/slot#allow), which is
+> enforced everywhere.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" allow={["HeadingBlock"]} />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `className`
+
+Provide a className to the DropZone component. The default DropZone styles will still be applied.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" className="MyComponent" />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `collisionAxis`
+
+Configure which axis Puck will use for overlap collision detection.
+
+Options:
+
+- `x` - detect collisions based their x-axis overlap
+- `y` - detect collisions based their y-axis overlap
+- `dynamic` - automatically choose an axis based on the direction of travel
+
+The defaults are set based on the CSS layout of the parent:
+
+- grid: `dynamic`
+- flex (row): `x`
+- inline/inline-block: `x`
+- Everything else: `y`
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" collisionAxis="dynamic" />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `disallow`
+
+Allow all but specific components to be dragged into the DropZone. Any items in `allow` will override `disallow`.
+
+> **Note:** Drag-and-drop in the outline does not respect this prop. Prefer the
+> [`disallow` parameter on the slot
+> field](/docs/api-reference/fields/slot#disallow), which is enforced
+> everywhere.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" disallow={["HeadingBlock"]} />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `minEmptyHeight`
+
+The minimum height of the DropZone when empty. Defaults to `128px`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" minEmptyHeight="256px" />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `ref`
+
+A [React ref](https://react.dev/learn/manipulating-the-dom-with-refs), assigned to the root node of the DropZone.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        const ref = useRef();
+
+        return (
+          <div>
+            <DropZone zone="my-content" ref={ref} />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+### `style`
+
+Provide a style attribute to the DropZone. The default DropZone styles will still be applied.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      render: () => {
+        return (
+          <div>
+            <DropZone zone="my-content" style={{ display: "flex" }} />
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+## React server components
+
+By default, DropZones don't work with React server components as they rely on context.
+
+Instead, you can use the [`renderDropZone` method](/docs/api-reference/configuration/component-config#propspuckrenderdropzone) passed to your component render function.