@puckeditor/cli 0.24.0-canary.301a0304

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

@@ -0,0 +1,413 @@
+# External
+
+Select data from a list, typically populated via a third-party API. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            // ... fetch data from a third party API, or other async source
+
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+        },
+      },
+      render: ({ data }) => {
+        return <p>{data?.title || "No data selected"}</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                                     | Example                                      | Type       | Status   |
+| ----------------------------------------- | -------------------------------------------- | ---------- | -------- |
+| [`type`](#type)                           | `type: "external"`                           | "external" | Required |
+| [`fetchList()`](#fetchlistqueryparams)    | `fetchList: async () => []`                  | Function   | Required |
+| [`cache`](#cache)                         | `cache: { enabled: true }`                   | Object     | -        |
+| [`filterFields`](#filterfields)           | `{ "rating": { type: "number" } }`           | Object     | -        |
+| [`getItemSummary()`](#getitemsummaryitem) | `getItemSummary: async ({ title }) => title` | Function   | -        |
+| [`initialFilters`](#initialfilters)       | `{ "rating": 1 }`                            | Object     | -        |
+| [`initialQuery`](#initialquery)           | `initialQuery: "Hello, world"`               | String     | -        |
+| [`mapProp()`](#mappropitem)               | `mapProp: async ({ title }) => title`        | Function   | -        |
+| [`mapRow()`](#maprowitem)                 | `mapRow: async ({ title }) => title`         | Function   | -        |
+| [`placeholder`](#placeholder)             | `placeholder: "Select content"`              | String     | -        |
+| [`renderFooter()`](#renderfooterprops)    | `renderFooter: (props) => <p>Hello</p>`      | Function   | -        |
+| [`showSearch`](#showsearch)               | `showSearch: true`                           | Boolean    | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"external"` for Array fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `fetchList(queryParams)`
+
+Return a promise with a list of objects to be rendered in a tabular format via the external input modal.
+
+The table will only render strings and numbers.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            // ... fetch data from a third party API, or other async source
+
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+#### `queryParams`
+
+The parameters passed to the `fetchList` method based on your field configuration.
+
+| Param                 | Example             | Type   |
+| --------------------- | ------------------- | ------ |
+| [`query`](#query)     | `"My Query"`        | String |
+| [`filters`](#filters) | `"{ "rating": 1 }"` | Object |
+
+##### `query`
+
+The search query when using [`showSearch`](#showsearch).
+
+##### `filters`
+
+An object describing the filters configured by [`filterFields`](#filterfields).
+
+## Optional params
+
+### `cache`
+
+Puck will automatically cache the output of the [`fetchList()`](#fetchlistqueryparams) function in memory.
+
+You can disable this behaviour by setting `cache: { enabled: false }` on your field.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          cache: { enabled: true },
+          fetchList: async () => {
+            // ... fetch data from a third party API, or other async source
+
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `filterFields`
+
+An object describing filters for your query using the [Fields API](/docs/api-reference/fields)
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async ({ filters }) => {
+            return [
+              { title: "Apple", description: "Lorem ipsum 1", rating: 5 },
+              { title: "Orange", description: "Lorem ipsum 2", rating: 3 },
+            ].filter((item) => item.rating >= (filters.rating || 0));
+          },
+          filterFields: {
+            rating: {
+              type: "number",
+            },
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `getItemSummary(item)`
+
+Get the label to show once the item is selected. 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: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+          getItemSummary: (item) => item.title,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `initialFilters`
+
+The initial filter values when using [`filterFields`](#filterfields).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async ({ filters }) => {
+            return [
+              { title: "Apple", description: "Lorem ipsum 1", rating: 5 },
+              { title: "Orange", description: "Lorem ipsum 2", rating: 3 },
+            ].filter((item) => item.rating >= (filters.rating || 0));
+          },
+          filterFields: {
+            rating: {
+              type: "number",
+            },
+          },
+          initialFilters: {
+            rating: 1,
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `initialQuery`
+
+Set an initial query when using showing a search input with [`showSearch`](#showsearch).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async ({ query }) => {
+            return [
+              { title: "Apple", description: "Lorem ipsum 1" },
+              { title: "Orange", description: "Lorem ipsum 2" },
+            ].filter((item) => {
+              // ...
+            });
+          },
+          showSearch: true,
+          initialQuery: "Apple",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `mapProp(item)`
+
+Modify the shape of the item selected by the user in the table before writing to the page data.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+          mapProp: (item) => item.description,
+        },
+      },
+      render: ({ data }) => {
+        return <p>{data || "No data selected"}</p>;
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `mapRow(item)`
+
+Modify the shape of the item before rendering it in the table. This will not affect the selected data.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+          mapRow: (item) => ({ ...item, title: item.title.toUpperCase() }),
+        },
+      },
+      render: ({ data }) => {
+        return <p>{data || "No data selected"}</p>;
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `placeholder`
+
+Set the placeholder text when no item is selected.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Apple", description: "Lorem ipsum 1" },
+              { title: "Orange", description: "Lorem ipsum 2" },
+            ];
+          },
+          placeholder: "Pick your favorite fruit",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `renderFooter(props)`
+
+Customize what will be displayed in the footer of the modal.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async () => {
+            return [
+              { title: "Hello, world", description: "Lorem ipsum 1" },
+              { title: "Goodbye, world", description: "Lorem ipsum 2" },
+            ];
+          },
+          renderFooter: ({ items }) => (
+            <b>Custom footer with {items.length} results</b>
+          ),
+        },
+      },
+      render: ({ data }) => {
+        return <p>{data || "No data selected"}</p>;
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `showSearch`
+
+Show a search input, the value of which will be passed to `fetchList` as the `query` param.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        data: {
+          type: "external",
+          fetchList: async ({ query }) => {
+            return [
+              { title: "Apple", description: "Lorem ipsum 1" },
+              { title: "Orange", description: "Lorem ipsum 2" },
+            ].filter((item) => {
+              // ...
+            });
+          },
+          showSearch: true,
+        },
+      },
+      // ...
+    },
+  },
+};
+```

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

@@ -0,0 +1,132 @@
+# Number
+
+Render a `number` input. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+        },
+      },
+      render: ({ myNumber }) => {
+        return <div>{myNumber}</div>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                         | Example                         | Type     | Status   |
+| ----------------------------- | ------------------------------- | -------- | -------- |
+| [`type`](#type)               | `type: "number"`                | "number" | Required |
+| [`max`](#max)                 | `max: 10`                       | number   | -        |
+| [`min`](#min)                 | `min: 0`                        | number   | -        |
+| [`placeholder`](#placeholder) | `placeholder: "Lorem ipsum..."` | String   | -        |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"number"` for Number fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Optional params
+
+### `max`
+
+The maximum numeric value allowed.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+          max: 10,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `min`
+
+The minimum numeric value allowed.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+          min: 0,
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Placeholder
+
+The placeholder text to display when the field is empty.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+          placeholder: "Lorem ipsum...",
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `step`
+
+The stepping interval when interacting with the field.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        myNumber: {
+          type: "number",
+          step: 0.1,
+        },
+      },
+      // ...
+    },
+  },
+};
+```

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

@@ -0,0 +1,78 @@
+# Object
+
+Render an object with a subset of fields. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        params: {
+          type: "object",
+          objectFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      render: ({ params }) => {
+        return <p>{params.title}</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                           | Example                                     | Type    | Status   |
+| ------------------------------- | ------------------------------------------- | ------- | -------- |
+| [`type`](#type)                 | `type: "array"`                             | "array" | Required |
+| [`objectFields`](#objectfields) | `objectFields: { title: { type: "text" } }` | Object  | Required |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"object"` for Object fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "object",
+          objectFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `objectFields`
+
+Describe the fields for the object. Shares an API with `fields`.
+
+Can include any field type, including nested object fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        items: {
+          type: "object",
+          objectFields: {
+            title: { type: "text" },
+          },
+        },
+      },
+      // ...
+    },
+  },
+};
+```

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

@@ -0,0 +1,82 @@
+# Radio
+
+Render a `radio` input with a list of options. Extends [Base](/docs/api-reference/fields/base).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        textAlign: {
+          type: "radio",
+          options: [
+            { label: "Left", value: "left" },
+            { label: "Right", value: "right" },
+          ],
+        },
+      },
+      defaultProps: {
+        textAlign: "left",
+      },
+      render: ({ textAlign }) => {
+        return <p style={{ textAlign }}>Hello, world</p>;
+      },
+    },
+  },
+};
+```
+
+## Params
+
+| Param                 | Example                                               | Type     | Status   |
+| --------------------- | ----------------------------------------------------- | -------- | -------- |
+| [`type`](#type)       | `type: "radio"`                                       | "radio"  | Required |
+| [`options`](#options) | `options: [{ label: "Option 1", value: "option-1" }]` | Object[] | Required |
+
+## Required params
+
+### `type`
+
+The type of the field. Must be `"radio"` for Array fields.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        textAlign: {
+          type: "radio",
+          options: [
+            { label: "Left", value: "left" },
+            { label: "Right", value: "right" },
+          ],
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+### `options`
+
+The options for the radio field. The `value` can be a String, Number or Boolean.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        textAlign: {
+          type: "radio",
+          options: [
+            { label: "Left", value: "left" },
+            { label: "Right", value: "right" },
+          ],
+        },
+      },
+      // ...
+    },
+  },
+};
+```