@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/integrating-puck/rich-text-editing.md

@@ -0,0 +1,230 @@
+# Rich Text Editing
+
+Puck supports rich text editing via the [`richtext`](/docs/api-reference/fields/richtext) field.
+
+## Adding a rich text field
+
+To use rich text, add the `richtext` field to your component config:
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+## Enabling inline editing
+
+Set [`contentEditable`](/docs/api-reference/fields/richtext#contenteditable) to make the field editable inline:
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          contentEditable: true,
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+## Customizing behavior
+
+The rich text field is built with [Tiptap](https://tiptap.dev), and comes with [several Tiptap extensions](/docs/api-reference/fields/richtext#included-extensions) pre-configured. Editor behavior can be customized by configuring these extensions.
+
+### Disabling functionality
+
+Disable any extension by setting it to `false` in [`options`](/docs/api-reference/fields/richtext#options):
+
+```ts
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          options: {
+            // Disable bold extension
+            bold: false,
+          },
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+### Configuring extensions
+
+Provide configuration options for the [included extensions](/docs/api-reference/fields/richtext#included-extensions) directly to `options` for further customization:
+
+```ts
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          options: {
+            // Restrict headings to h1 and h2
+            // https://tiptap.dev/docs/editor/extensions/nodes/heading
+            heading: { levels: [1, 2] },
+          },
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+## Customizing the menu bar
+
+Use [`renderMenu()`](/docs/api-reference/fields/richtext#rendermenuprops) to customize the menu bar layout using the [`<RichTextMenu>`](/docs/api-reference/components/rich-text-menu) component:
+
+```tsx
+import { RichTextMenu } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          renderMenu: () => (
+            {/*  Always wrap in <RichTextMenu> */}
+            <RichTextMenu>
+              {/* Group items in <RichTextMenu.Group> */}
+              <RichTextMenu.Group>
+                {/* Only include the bold control */}
+                <RichTextMenu.Bold />
+              </RichTextMenu.Group>
+            </RichTextMenu>
+          ),
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+> **Note:** Hiding a control does not disable the functionality. Users can still use
+> keyboard shortcuts and other input mechanisms. To disable functionality, use
+> [`options`](/docs/api-reference/fields/richtext#options).
+
+A full list of controls is available in the [included controls API reference](/docs/api-reference/components/rich-text-menu#included-controls).
+
+## Adding custom extensions
+
+### Configure the extension
+
+Provide additional [Tiptap extensions](https://tiptap.dev/docs/editor/extensions/overview) to the [`tiptap.extensions`](/docs/api-reference/fields/richtext#tiptapextensions) parameter to introduce new functionality:
+
+```tsx
+import Superscript from "@tiptap/extension-superscript";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          tiptap: {
+            extensions: [Superscript],
+          },
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+### Add a new control
+
+If you're adding a control for a new extension, first update the [`tiptap.selector`](/docs/api-reference/fields/richtext#tiptapselector) to make the state available to the menu:
+
+```tsx
+import Superscript from "@tiptap/extension-superscript";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          tiptap: {
+            extensions: [Superscript],
+            selector: ({ editor }) => ({
+              isSuperscript: editor?.isActive("superscript"),
+              canSuperscript: editor?.can().chain().toggleSuperscript().run(),
+            }),
+          },
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+Then implement a new control with [`<RichTextMenu.Control>`](/docs/api-reference/components/rich-text-menu-control) and render it with `renderMenu()`:
+
+```tsx
+import Superscript from "@tiptap/extension-superscript";
+import { Superscript } from "lucide-react";
+import { RichTextMenu } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        body: {
+          type: "richtext",
+          // ...
+          renderMenu: ({ children, editor, editorState }) => (
+            <RichTextMenu>
+              {/* Render the default controls */}
+              {children}
+
+              <RichTextMenu.Group>
+                <RichTextMenu.Control
+                  icon={<Superscript />}
+                  onClick={() =>
+                    editor?.chain().focus().toggleSuperscript().run()
+                  }
+                  active={editorState?.isSuperscript}
+                  disabled={!editorState?.canSuperscript}
+                />
+              </RichTextMenu.Group>
+            </RichTextMenu>
+          ),
+        },
+      },
+      render: ({ body }) => body,
+    },
+  },
+};
+```
+
+## Further reading
+
+- [`richtext` field API reference](/docs/api-reference/fields/richtext)
+- [`<RichTextMenu>` API reference](/docs/api-reference/components/rich-text-menu)
+- [Tiptap Overview](https://tiptap.dev/docs/editor/getting-started/overview)
+- [Tiptap Extensions](https://tiptap.dev/docs/editor/extensions/overview)

package/dist/docs/integrating-puck/root-configuration.md

@@ -0,0 +1,171 @@
+# Root Configuration
+
+The root is the top-level component within Puck. It:
+
+1. Renders a single wrapper around your other components. This can be overwritten with a `render` function.
+2. Stores meta data, like the page title. This can be extended with `fields`.
+
+Configuring the root is similar to [configuring components](/docs/integrating-puck/component-configuration).
+
+## The root `render` function
+
+Use the [`root` parameter](/docs/api-reference/configuration/config#root) to specify a [`render` function](/docs/api-reference/configuration/component-config#renderprops):
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      render: () => {
+        return <h1>Hello, world</h1>;
+      },
+    },
+  },
+  root: {
+    render: ({ children }) => {
+      return <div>{children}</div>;
+    },
+  },
+};
+```
+
+The root `render` function will wrap all of the components. `children` is a node containing the nested components.
+
+If you don't render `children`, your components will not be rendered unless you define another [slot](/docs/api-reference/fields/slot).
+
+### Example output
+
+Given a minimal data payload containing one **HeadingBlock**
+
+```json
+{
+  "content": [
+    {
+      "type": "HeadingBlock",
+      "props": {
+        "id": "HeadingBlock-1234"
+      }
+    }
+  ],
+  "root": {}
+}
+```
+
+the example config will render HTML nodes like this:
+
+```html
+<!-- root render -->
+<div>
+  <!-- HeadingBlock render -->
+  <h1>Hello, world</h1>
+
+  <!-- Remaining nodes -->
+</div>
+```
+
+## Adding fields
+
+Root fields provide user input to the root render method, and can be used to store metadata.
+
+By default, `root` is configured with a `title` text field:
+
+```tsx
+const config = {
+  // ...
+  root: {
+    render: ({ children, title }) => {
+      return (
+        <div>
+          <h1>{title}</h1>
+          {children}
+        </div>
+      );
+    },
+  },
+};
+```
+
+You can override the default field configuration by providing custom [Fields](/docs/api-reference/fields) to the [`fields` parameter](/docs/api-reference/configuration/component-config#fields):
+
+```tsx
+const config = {
+  // ...
+  root: {
+    fields: {
+      title: { type: "text" }, // You need to redefine the `title` field if we want to retain it
+      description: { type: "textarea" },
+    },
+    render: ({ children, title, description }) => {
+      return (
+        <div>
+          <h1>{title}</h1>
+          <p>{description}</p>
+          {children}
+        </div>
+      );
+    },
+  },
+};
+```
+
+When the user modifies the inputs, the editor will produce a data payload like this:
+
+```json
+{
+  "content": [
+    // ...
+  ],
+  "root": {
+    "props": {
+      "title": "Hello, world",
+      "description": "Lorem ipsum"
+    }
+  }
+}
+```
+
+### TypeScript
+
+Generic types can be passed to the `Config` type to strictly type your root configuration:
+
+```tsx
+import type { Config } from "@puckeditor/core";
+
+type RootProps = {
+  description: string;
+};
+
+const config: Config<{}, RootProps> = {
+  // ...
+};
+```
+
+## Setting default props
+
+Provide an object to the [`defaultProps`](/docs/api-reference/configuration/component-config#fields) parameter to configure default props for the root fields:
+
+```tsx
+const config = {
+  // ...
+  root: {
+    fields: {
+      title: { type: "text" },
+      description: { type: "textarea" },
+    },
+    defaultProps: {
+      title: "Hello, world",
+      description: "Lorem ipsum",
+    },
+    render: ({ children, title, description }) => {
+      return (
+        <div>
+          <h1>{title}</h1>
+          <p>{description}</p>
+          {children}
+        </div>
+      );
+    },
+  },
+};
+```
+
+Unlike [default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters), `defaultProps` are stored in the data payload and will populate the Puck fields.

package/dist/docs/integrating-puck/server-components.md

@@ -0,0 +1,199 @@
+# React Server Components
+
+Puck provides support for [React Server Components](https://react.dev/reference/react/use-server#use-server) (RSC), but the interactive-nature of Puck requires special consideration.
+
+## Environments
+
+### Server
+
+Puck supports the server environment for the following APIs:
+
+- The [`<Render>`](/docs/api-reference/components/render) component, for rendering pages produced by Puck
+- The [`resolveAllData`](/docs/api-reference/functions/resolve-all-data) lib, for running all [data resolvers](/docs/integrating-puck/dynamic-props)
+
+These APIs can be used in an RSC environment, but in order to do so the Puck config that they reference must be RSC-friendly.
+
+This can be done by either avoiding client-only code (React `useState`, etc), or split out client components with the `"use client";` directive.
+
+### Client
+
+All other Puck APIs, including the core `<Puck>` component, cannot run in an RSC environment due to their high-degree of interactivity.
+
+As these APIs render on the client, the Puck config provided must be safe for client-use, avoiding any server-specific logic.
+
+## Implementations
+
+Since the Puck config can be referenced on the client or the server, we need to consider how to satisfy both environments.
+
+There are three approaches to this:
+
+1. Avoid using any client-specific functionality (like React `useState`) in your components
+2. Mark your components up with the `"use client";` directive if you need client-specific functionality
+3. Create separate configs for client and server rendering
+
+### 1. Avoid client-specific code
+
+Avoiding client-specific code is the easiest way to support RSC across both environments, but may not be realistic for all users. This normally means avoiding React hooks like `useState` or `useContext`.
+
+If you're using the legacy [`<DropZone>` component](/docs/api-reference/components/drop-zone), you will may encounter issues with server components. We recommend migrating to the [`slot` field](/docs/api-reference/fields/slot) which provides native server component support. Alternatively, see [our previous server components guide](https://puckeditor.com/v/0.18.3/docs/integrating-puck/server-components) for information on handling DropZones.
+
+### 2. Marking up components with `"use client";`
+
+Many modern component libraries will require some degree of client-side behaviour. For these cases, you'll need to mark them up with the `"use client";` directive.
+
+To achieve this, you must import each of those component from a separate file:
+
+File: `puck.config.tsx`
+
+```tsx
+import type { Config } from "@puckeditor/core";
+import type { HeadingBlockProps } from "./components/HeadingBlock";
+import HeadingBlock from "./components/HeadingBlock";
+
+type Props = {
+  HeadingBlock: HeadingBlockProps;
+};
+
+export const config: Config<Props> = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      defaultProps: {
+        title: "Heading",
+      },
+      // You must call the component, rather than passing it in directly. This will change in the future.
+      render: ({ title }) => <HeadingBlock title={title} />,
+    },
+  },
+};
+```
+
+And add the `"use client";` directive to the top of each component file:
+
+File: `components/HeadingBlock.tsx`
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+export type HeadingBlockProps = {
+  title: string;
+};
+
+export default ({ title }: { title: string }) => {
+  useState(); // useState fails on the server
+
+  return (
+    <div style={{ padding: 64 }}>
+      <h1>{title}</h1>
+    </div>
+  );
+};
+```
+
+This config can now be rendered inside an RSC component, such as a Next.js app router page:
+
+File: `app/page.tsx`
+
+```tsx
+import { config } from "../puck.config.tsx";
+
+export default async function Page() {
+  const data = await getData(); // Some server function
+
+  const resolvedData = await resolveAllData(data, config); // Optional call to resolveAllData, if this needs to run server-side
+
+  return <Render data={resolvedData} config={config} />;
+}
+```
+
+### 3. Creating separate configs
+
+Alternatively, consider entirely separate configs for the `<Puck>` and `<Render>` components. This approach can enable you to have different rendering behavior for a component for when it renders on the client or the server.
+
+Create a shared config type:
+
+File: `puck-types.ts`
+
+```tsx
+import type { Config } from "@puckeditor/core";
+
+type Props = {
+  HeadingBlock: {
+    title: string;
+  };
+};
+
+export type UserConfig = Config<Props>;
+```
+
+Define a client component config for use within the `<Puck>` component:
+
+File: `puck.config.client.tsx`
+
+```tsx
+import type { UserConfig } from "./puck-types.ts";
+
+export const config: UserConfig = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      defaultProps: {
+        title: "Heading",
+      },
+      render: ({ title }) => {
+        useState(); // useState fails on the server
+
+        return (
+          <div style={{ padding: 64 }}>
+            <h1>{title}</h1>
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+Define a server config using the shared types for use within the `<Render>` component, excluding editor-only behaviour where possible but preserving any fields required for render-time transforms like [`richtext`](/docs/api-reference/fields/richtext) and [`slot`](/docs/api-reference/fields/slot):
+
+File: `puck.config.server.tsx`
+
+```tsx
+import type { UserConfig } from "./puck-types.ts";
+
+export const config: UserConfig = {
+  components: {
+    HeadingBlock: {
+      render: ({ title }) => {
+        return (
+          <div style={{ padding: 64 }}>
+            <h1>{title}</h1>
+          </div>
+        );
+      },
+    },
+  },
+};
+```
+
+Render the appropriate config depending on the environment. Here's a Next.js app router example of a server render:
+
+File: `app/page.tsx`
+
+```tsx
+import { config } from "../puck.config.server.tsx";
+
+export default async function Page() {
+  const data = await getData(); // Some server function
+
+  return <Render data={data} config={config} />;
+}
+```
+
+If your server config omits those render-relevant fields entirely, Puck cannot infer which props should be transformed before render. In practice this means rich text will be escaped as plain strings, and slot data will not be converted into nested components.

package/dist/docs/integrating-puck/styling.md

@@ -0,0 +1,117 @@
+# Styling
+
+Puck includes stylesheets for the interface. There are two types of styles:
+
+1. Editor styles, for the editor interface
+2. Preview styles, for the drag-and-drop canvas, isolated within an iframe
+
+By default, Puck will load styles at runtime.
+
+## Style isolation
+
+Puck isolates the canvas using an iframe, automatically syncing stylesheets from the host application. It also provides APIs for fine-tuning behavior.
+
+### Opting out of iframes
+
+Opt-out of iframe rendering to completely disable preview isolation with [`iframe.enabled`](/docs/api-reference/components/puck#enabled):
+
+```tsx
+export function Editor() {
+  return (
+    <Puck
+      iframe={{
+        enabled: false,
+      }}
+      // ...
+    />
+  );
+}
+```
+
+Note that this will also disable [viewports](/docs/integrating-puck/viewports).
+
+### Disabling style sync
+
+Disable iframe style sync using [`iframe.syncHostStyles`](/docs/api-reference/components/puck#synchoststyles):
+
+```tsx
+export function Editor() {
+  return (
+    <Puck
+      iframe={{
+        syncHostStyles: false,
+      }}
+      // ...
+    />
+  );
+}
+```
+
+Puck will still inject preview styles for drag-and-drop behavior into the iframe.
+
+### Injecting styles manually
+
+Manually inject styles into the iframe using the [`iframe` override](/docs/api-reference/overrides/iframe):
+
+```tsx
+const overrides = {
+  iframe: ({ children, document }) => {
+    useEffect(() => {
+      if (document) {
+        document.body.setAttribute("style", "background: hotpink;");
+      }
+    }, [document]);
+
+    return <>{children}</>;
+  },
+};
+
+export function Editor() {
+  return (
+    <Puck
+      overrides={overrides}
+      // ...
+    />
+  );
+}
+```
+
+Learn more about overrides in [Extending Puck: UI Overrides](/docs/extending-puck/ui-overrides).
+
+## Bundling CSS
+
+By default, Puck loads styles client-side. This is fine for most use-cases, but can result in a flash of unstyled content ([FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content)).
+
+### Avoiding FOUC
+
+You can avoid FOUC by bundling `puck.css`:
+
+```css
+@import "@puckeditor/core/puck.css";
+```
+
+When bundling CSS, make sure you consider the impact on your production CSS bundle.
+
+> **Note:** Note that this will result in Puck's editor styles being injected into the
+> iframe unless you [disable style sync](#disabling-style-sync).
+
+### Excluding external imports
+
+Puck includes references to external font packages. Use the `no-external` CSS bundle to exclude them:
+
+```css
+/* @import "@puckeditor/core/puck.css"; */
+@import "@puckeditor/core/no-external.css";
+```
+
+## Theming
+
+Puck supports theming through CSS variables. See [Theming](/docs/extending-puck/theming) for more information.
+
+## Further reading
+
+- [`iframe` API reference](/docs/api-reference/components/puck#iframe)
+- [`iframe` override](/docs/api-reference/overrides/iframe)
+- [Theming](/docs/extending-puck/theming)
+- [UI Overrides](/docs/extending-puck/ui-overrides)
+- [Viewports](/docs/integrating-puck/viewports)