@puckeditor/cli 0.24.0-canary.301a0304

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

@@ -0,0 +1,211 @@
+# Array
+
+Render a list of items with a subset of fields. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      render: ({ items }) => {
+        return (
+          <ul>
+            {items.map((item, i) => (
+              <li key={i}>{item.title}</li>
+            ))}
+          </ul>
+        );
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                           | Example                                       | Type               | Status   |
+| ----------------------------------------------- | --------------------------------------------- | ------------------ | -------- |
+| [`type`](#type)                                 | `type: "array"`                               | "array"            | Required |
+| [`arrayFields`](#arrayfields)                   | `arrayFields: { title: { type: "text" } }`    | Object             | Required |
+| [`defaultItemProps`](#defaultitemprops)         | `defaultItemProps: { title: "Hello, world" }` | Object \| Function | -        |
+| [`getItemSummary()`](#getitemsummaryitem-index) | `getItemSummary: (item) => item.title`        | Function           | -        |
+| [`max`](#max)                                   | `max: 3`                                      | Number             | -        |
+| [`min`](#min)                                   | `min: 1`                                      | Number             | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"array"` for Array fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `arrayFields`
+
+Describe the fields for each item in the array. Shares an API with `fields`.
+
+Can include any field type, including nested array fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Optional params
+
+### `defaultItemProps`
+
+Set the default values when a new item is added to the array. Can be an object or a function that receives the current array index.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+          defaultItemProps: {
+            title: "Hello, world",
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+You can also use a function to generate dynamic defaults:
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+            order: { type: "number" },
+          },
+          defaultItemProps: (index) => ({
+            title: `Item ${index + 1}`,
+            order: index + 1,
+          }),
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `getItemSummary(item, index)`
+
+Get a label of each item in the array. Returns a [ReactNode](https://react.dev/learn/typescript#typing-children).
+
+> **Warning:** Avoid using interactive HTML elements like `<button>`, `<input>`, or `<a>` inside `getItemSummary`. These elements can interfere with the array field's built-in interactions (such as drag-and-drop reordering and item expansion). Stick to non-interactive elements like `<div>`, `<span>`, `<p>`, or plain text for summaries.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+          getItemSummary: (item) => item.title || "Item",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `max`
+
+The maximum amount of items allowed in the array.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+          max: 3,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `min`
+
+The minimum amount of items allowed in the array.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "array",
+          arrayFields: {
+            title: { type: "text" },
+          },
+          min: 1,
+        },
+      },
+      // ...
+    },
+  },
+};
+```

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

@@ -0,0 +1,96 @@
+# Base
+
+The base type shared by all fields.
+
+## Params
+
+| Param                     | Example               | Type      | Status |
+| ------------------------- | --------------------- | --------- | ------ |
+| [`label`](#label)         | `label: "Title"`      | String    | -      |
+| [`labelIcon`](#labelicon) | `labelIcon: <Icon />` | ReactNode | -      |
+| [`metadata`](#metadata)   | `metadata: {}`        | Object    | -      |
+| [`visible`](#visible)     | `visible: false`      | Boolean   | -      |
+
+## Optional params
+
+### `label`
+
+Set the label for the input. Puck will use the key if not provided.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          label: "My Field",
+          // ...
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `labelIcon`
+
+Set an icon to display next to the label.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          labelIcon: <Icon />,
+          // ...
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `metadata`
+
+An object containing additional information for the field.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          metadata: {
+            title: "Hello, world",
+          },
+          // ...
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `visible`
+
+Show or hide the field. Defaults to `true`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          visible: false,
+          // ...
+        },
+      },
+      // ...
+    },
+  },
+};
+```

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

@@ -0,0 +1,193 @@
+# Custom
+
+Implement a field with a custom UI. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+import { FieldLabel } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+            />
+          ),
+        },
+      },
+      render: ({ title }) => {
+        return <p>{title}</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                 | Example                   | Type     | Status   |
+| ------------------------------------- | ------------------------- | -------- | -------- |
+| [`type`](#type)                       | `type: "custom"`          | "custom" | Required |
+| [`render()`](#renderparams)           | `render: () => <input />` | Function | Required |
+| [`contentEditable`](#contentEditable) | `contentEditable: true`   | Boolean  | -        |
+| [`key`](#key)                         | `key: "custom-text"`      | String   | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"custom"` for Custom fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+            />
+          ),
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `render(params)`
+
+Render the custom field.
+
+```tsx
+import { FieldLabel } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+            />
+          ),
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+#### `params`
+
+| Param                 | Example                    | Type     |
+| --------------------- | -------------------------- | -------- |
+| `field`               | `{ type: "custom" }`       | Object   |
+| `id`                  | `id`                       | String   |
+| `name`                | `"title"`                  | String   |
+| `onChange(value, ui)` | `onChange("Hello, world")` | Function |
+| `value`               | `"Hello, world"`           | Any      |
+
+##### onChange(value, [ui])
+
+Set the value of the field and optionally update the [Puck UI state](/docs/api-reference/data-model/app-state#ui).
+
+| Param   | Example                       | Type                                                   | Status   |
+| ------- | ----------------------------- | ------------------------------------------------------ | -------- |
+| `value` | `"Hello, world"`              | Any                                                    | Required |
+| `ui`    | `{leftSideBarVisible: false}` | [UiState](/docs/api-reference/data-model/app-state#ui) |          |
+
+## Optional params
+
+### `contentEditable`
+
+Enable inline text editing for this field. Only works if the value is a string. Defaults to `false`.
+
+> **Warning:** When setting `contentEditable`, your [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) prop will be converted to an [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) when rendered inside [`<Puck>`](/docs/api-reference/components/puck) (but not [`<Render>`](/docs/api-reference/components/render)). When using TypeScript, change your `string` to  `string | ReactNode`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          contentEditable: true,
+          render: ({ name, onChange, value }) => (
+            <input
+              value={value} // Bind to value for 2-way binding
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+            />
+          ),
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `key`
+
+Assign a unique key to force the field to remount when using [`resolveFields`](/docs/api-reference/configuration/component-config#resolvefieldsdata-params) to resolve different custom field types on the same prop.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        isText: {
+          type: "radio",
+          options: [
+            { label: "Yes", value: true },
+            { label: "No", value: false },
+          ],
+        },
+      },
+      resolveFields: (data, params) => {
+        if (data.props.isText) {
+          return {
+            ...params.fields,
+            prop: {
+              type: "custom",
+              key: "custom-text",
+              // ...
+            },
+          };
+        } else {
+          return {
+            ...params.fields,
+            prop: {
+              type: "custom",
+              key: "custom-number",
+              // ...
+            },
+          };
+        }
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Further reading
+
+- [Custom Fields guide](/docs/extending-puck/custom-fields)
+- [The `<FieldLabel>` API reference](/docs/api-reference/components/field-label)