### Setup development environment

Source: https://github.com/puckeditor/puck/blob/main/CONTRIBUTING.md

Commands to initialize the project dependencies and start the development server for the demo application.

```shell
yarn
```

```shell
cd apps/demo
yarn dev
```

--------------------------------

### Nested Components Example

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/slot.mdx

Demonstrates how to use a slot component to render nested components within a Puck editor. This example shows a 'Card' component being placed inside an 'Example' slot.

```javascript
import { PuckPreview } from "@/docs/components/Preview";
import { Puck } from "@/puck";

// ... other imports and component definitions

<PuckPreview
  label="Nested components example"
  config={{
    components: {
      Example: {
        fields: {
          content: {
            type: "slot",
          },
        },
        render: ({ content: Content }) => {
          return (
            <div style={{ padding: 32 }}>
              <Content />
            </div>
          );
        },
      },
      Card: {
        render: () => {
          return (
            <div
              style={{
                background: "white",
                border: "1px solid black",
                borderRadius: 4,
                padding: 16,
              }}
            >
              Hello, world
            </div>
          );
        },
      },
    },
  }}
  data={{
  }}
>

  <div
    style={{
      "--puck-slot-color-bg": "#fff2ee",
      "--puck-slot-color-border": "#f6823b",
    }}>
    <div style={{display:"grid", gridTemplateColumns: "1fr 2fr", gap: 8}}>
      <Puck.Components />
      <Puck.Preview />
    </div>
  </div>
</PuckPreview>
```

--------------------------------

### Overlay Portals Example for Tabs in React

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/overlay-portals.mdx

This snippet shows an example of using Overlay Portals to create interactive tabs within the Puck editor preview. It utilizes `OverlayPortalTabsPreview` component, implying a setup for tabbed content interaction.

```tsx
import { OverlayPortalTabsPreview } from "@/docs/components/Preview";

// Assuming this is part of a component configuration for Puck
// The actual implementation would involve defining the 'Example' component
// that renders the OverlayPortalTabsPreview.

// Example component structure (conceptual):
// const Example = () => {
//   return <OverlayPortalTabsPreview />;
// };

```

--------------------------------

### Initialize and Use outlinePlugin in Puck Editor (TypeScript)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/plugins/outline-plugin.mdx

Demonstrates how to import and use the outlinePlugin within a Puck Editor component. This example shows the basic setup for integrating the plugin, which is often included by default but can be explicitly managed for order customization.

```tsx
import { Puck, outlinePlugin } from "@puckeditor/core";

const outline = outlinePlugin();

export function Editor() {
  return <Puck plugins={[outline]} />;
}
```

--------------------------------

### Install and Configure Heading Analyzer Plugin

Source: https://github.com/puckeditor/puck/blob/main/packages/plugin-heading-analyzer/README.md

Instructions for installing the plugin via npm and integrating it into a Puck editor instance. The plugin requires importing the CSS file to ensure proper styling of the visual outline.

```bash
npm i @puckeditor/plugin-heading-analyzer
```

```jsx
import { Puck } from "@puckeditor/core";
import headingAnalyzer from "@puckeditor/plugin-heading-analyzer";
import "@puckeditor/plugin-heading-analyzer/dist/index.css";

export function Page() {
  return <Puck
    config={config}
    data={data}
    plugins={[
        headingAnalyzer
    ]}
  />;
}
```

--------------------------------

### Install Puck Editor Core Package

Source: https://github.com/puckeditor/puck/blob/main/README.md

Install the core Puck editor package using npm. This command is used to add Puck to an existing project.

```sh
npm i @puckeditor/core --save
```

--------------------------------

### Install Emotion Cache Plugin

Source: https://github.com/puckeditor/puck/blob/main/packages/plugin-emotion-cache/README.md

Installs the @puckeditor/plugin-emotion-cache package using npm. This is the first step to integrating Emotion cache with Puck.

```shell
npm i @puckeditor/plugin-emotion-cache
```

--------------------------------

### Setting Initial Puck Data

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Provide the initial content and root structure for the Puck editor using the `data` prop. This example sets up a page with a 'Hello, world' heading.

```tsx
export function Editor() {
  return (
    <Puck
      data={{
        content: [
          {
            props: { children: "Hello, world", id: "id" },
            type: "HeadingBlock",
          },
        ],
        root: {},
      }}
      // ...
    />
  );
}
```

--------------------------------

### Create Puck App with Recipes

Source: https://github.com/puckeditor/puck/blob/main/README.md

Use npx to create a new Puck application using one of the provided recipes. This command bootstraps a new project with a pre-configured setup.

```sh
npx create-puck-app my-app
```

--------------------------------

### Example Custom Rich Text Menu Configuration (TypeScript)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/fields/richtext.mdx

Provides a concrete example of a `renderMenu` configuration for a Puck Editor rich text field. This example includes default menu items and custom controls with icons and click handlers, demonstrating a practical use case.

```tsx
<ConfigPreview
  label="Example"
  componentConfig={{
    fields: {
      body: {
        type: "richtext",
        renderMenu: ({ children }) => (
          <RichTextMenu>
            {children}
            <RichTextMenu.Group>
              <RichTextMenu.Control icon={<Quote />} />
              <RichTextMenu.Control
                icon={<Highlighter />}
                onClick={() => {
                  alert("Highlight clicked");
                }}
              />
            </RichTextMenu.Group>
          </RichTextMenu>
        ),
      },
    },
    defaultProps: {
      body: "<p>Hello, world</p>",
    },
    render: ({ body }) => body,
  }}
>
  <Puck.Preview />
</ConfigPreview>

```

--------------------------------

### Implement granular selectors for usePuck

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/functions/use-puck.mdx

Examples of how to write efficient selector functions for usePuck to minimize re-renders, along with anti-patterns to avoid.

```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 }));
```

--------------------------------

### Configuring Puck Components

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Define available components and their fields using the `config` prop. This example shows a basic `HeadingBlock` component with a `text` field.

```tsx
export function Editor() {
  return (
    <Puck
      config={{
        components: {
          HeadingBlock: {
            fields: {
              children: {
                type: "text",
              },
            },
            render: ({ children }) => {
              return <h1>{children}</h1>;
            },
          },
        },
      }}
      // ...
    />
  );
}
```

--------------------------------

### Server Render Example in Next.js App Router

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/server-components.mdx

Illustrates how to use a server-specific configuration with the `<Render>` component in a Next.js application router context. Ensure server functions are awaited before rendering.

```typescript
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} />;
}
```

--------------------------------

### Basic Component Configuration

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

Defines a 'HeadingBlock' component with a 'title' field and a simple render function. This is a fundamental example of how to structure component configurations.

```tsx
const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
        },
      },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};
```

--------------------------------

### Initialize and Run Puck React Router Project

Source: https://github.com/puckeditor/puck/blob/main/recipes/react-router/README.md

Commands to scaffold a new Puck application using the React Router recipe and start the development server.

```bash
npx create-puck-app my-app
yarn dev
```

--------------------------------

### Configure Custom Viewports

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Define custom viewports for the Puck editor. This example shows how to set a specific width for a viewport.

```tsx
export function Editor() {
  return (
    <Puck
      viewports={[
        {
          width: 1440,
        },
      ]}
      // ...
    />
  );
}
```

--------------------------------

### Basic resolveData Example

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

A simple example of resolveData that resolves a 'resolvedTitle' prop based on the current 'title' prop. This is a fundamental pattern for data transformation.

```tsx
const resolveData = async ({ props }) => {
  return {
    props: { resolvedTitle: props.title },
  };
};
```

--------------------------------

### Render Puck Layout with Custom Behavior (React)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck-layout.mdx

Demonstrates how to use Puck.Layout within a React component to integrate custom behavior using the internal Puck API. This example shows a simple useEffect hook within a custom 'Example' component wrapped around Puck.Layout.

```tsx
import { Puck } from "@puckeditor/core";
import { useEffect } from "react";

const Example = ({ children }) => {
  useEffect(() => console.log("Hello, world"), []);

  return <>{children}</>;
};

export function Editor() {
  return (
    <Puck>
      <Example>
        <Puck.Layout />
      </Example>
    </Puck>
  );
}
```

--------------------------------

### Icon Button React Component Example

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/icon-button.mdx

Example of using the IconButton component in React with custom theming applied via inline styles. This demonstrates how to integrate the CSS variables into a component.

```jsx
<div
    style={{
      "--puck-iconbutton-radius": "9999px",
      "--puck-iconbutton-color-icon": "#1f2937",
      "--puck-iconbutton-color-bg-hover": "#eef2ff",
      "--puck-iconbutton-space": "16px",
    }}
  >
    <IconButton title="Delete">
      <Trash size={24} />
    </IconButton>
  </div>
```

--------------------------------

### Optimizing Permissions Update

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

Example of optimizing the `resolvePermissions` function to only update permissions when a specific prop ('example') has changed. It returns the last permissions if the prop hasn't changed, preventing unnecessary asynchronous operations.

```tsx
const resolvePermissions = async ({ props }, { changed, lastPermissions }) => {
  if (!changed.example) {
    return lastPermissions; // Return the last permissions unless the `example` prop has changed
  }

  return await expensiveAsyncOperation();
};
```

--------------------------------

### Configuring Puck Iframe Behavior

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Control the iframe behavior for the Puck preview using the `iframe` prop. This example disables the iframe.

```tsx
export function Editor() {
  return (
    <Puck
      iframe={{ enabled: false }}
      // ...
    />
  );
}
```

--------------------------------

### Distributing Field Transforms as a Plugin in React

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/field-transforms.mdx

Demonstrates how to package field transforms, along with overrides, into a plugin for distribution in React. This example includes a transform for 'example' fields and an override to define its UI as an input.

```tsx
const plugin = {
  fieldTransforms: {
    example: ({ value }) => <div>{value}</div>, // Wrap all example fields with divs
  },

  // This example combines transforms with overrides
  overrides: {
    fieldTypes: {
      example: () => <input />, // Define a field interface
    },
  },
};

const Example = () => <Puck plugins={[plugin]} />;
```

--------------------------------

### Setting Initial Puck UI State

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

The `ui` prop sets the initial application UI state. For example, use it to hide the left sidebar by default.

```tsx
export function Editor() {
  return (
    <Puck
      // Hide the left side bar by default
      ui={{ leftSideBarVisible: false }}
      // ...
    />
  );
}
```

--------------------------------

### Configure and Use Emotion Cache Plugin with Puck

Source: https://github.com/puckeditor/puck/blob/main/packages/plugin-emotion-cache/README.md

Demonstrates how to import and create an Emotion cache plugin for Puck. The example shows configuration for Chakra UI and how to pass the plugin to the Puck component. It requires the Puck core library and the plugin itself.

```jsx
import { Puck } from "@puckeditor/core";
import createEmotionCache from "@puckeditor/plugin-emotion-cache";

// Create your emotion cache plugin. This example configures it for Chakra.
const chakraEmotionCache = createEmotionCache("cha");

// Render Puck
export function Page() {
  return <Puck config={config} data={data} plugins={[chakraEmotionCache]} />;
}
```

--------------------------------

### Button Component with Theming

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/button.mdx

Demonstrates how to apply theme properties directly to a Button component within a React component. This example uses inline styles to set button theming.

```jsx
<PuckPreview>
  <div
    style={{
      "--puck-button-radius": "9999px",
      "--puck-button-primary-color-bg": "#6d28d9",
      "--puck-button-primary-color-bg-hover": "#5b21b6",
    }}
  >
    <Button>Publish</Button>
  </div>
</PuckPreview>
```

--------------------------------

### Load Custom Font with No-External CSS

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/theming.mdx

Switch Puck to the `no-external.css` runtime bundle to host your own font files instead of loading them from a CDN. This example shows how to import the alternative CSS file.

```css
/* @import "@puckeditor/core/puck.css"; */
@import "@puckeditor/core/no-external.css";
```

--------------------------------

### Setting Permissions for a Specific Instance

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

Dynamically set permissions for a specific component instance based on its data. This example disables deletion for a component with a specific ID.

```tsx
const config = {
  components: {
    MyComponent: {
      resolvePermissions: (data, { permissions }) => {
        if (data.props.id === "MyComponent-1234") {
          return {
            delete: false, // Disable deletion on component with id MyComponent-1234
          };
        }

        return { permissions }; // Fallback to inherited permissions
      },
      // ...
    },
  },
};
```

--------------------------------

### Custom Editor UI with Puck Composition

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/composition.mdx

This example shows how to create a custom editor interface by providing children to the <Puck> component. It renders the drag-and-drop preview and the component list side-by-side using CSS Grid.

```tsx
import { Puck } from "@puckeditor/core";

export function Editor() {
  return (
    <Puck>
      <div
        style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gridGap: 16 }}
      >
        <div>
          {/* Render the drag-and-drop preview */}
          <Puck.Preview />
        </div>
        <div>
          {/* Render the component list */}
          <Puck.Components />
        </div>
      </div>
    </Puck>
  );
}
```

--------------------------------

### Retain backwards-compatible props

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/data-migration.mdx

Demonstrates how to maintain support for both old and new prop names within a component definition to prevent breaking changes.

```tsx
const config = {
  HeadingBlock: ({ title, heading }) => <h1>{heading || title}</h1>,
};
```

--------------------------------

### Customize Component Theme Backgrounds

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/theming.mdx

Override specific component tokens to change elements like the header and plugin bar backgrounds. This example sets a light cream background for both.

```css
.Container {
  --puck-header-color-bg: #fff4e6;
  --puck-pluginbar-color-bg: #fff4e6;
}
```

--------------------------------

### Restrict Components in a Slot using 'allow' (React)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/multi-column-layouts.mdx

This example shows how to use the `allow` parameter within a slot's configuration to specify which component types are permitted to be dragged into that slot. In this case, only components of type 'Card' can be added.

```tsx
const config = {
  components: {
    fields: {
      content: {
        type: "slot",
        allow: ["Card"],
      },
    },
    Example: {
      render: ({ content: Content }) => {
        return <Content />;
      },
    },
  },
};

```

--------------------------------

### Apply Overrides in Plugin

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/plugin.mdx

Shows how to use the `overrides` option in a plugin to customize the rendering of specific UI components within the Puck editor. This example targets `drawerItem` to make them appear in hotpink.

```tsx
const MyPlugin = {
  overrides: {
    // Make all drawer items pink
    drawerItem: ({ name }) => <div style={{ color: "hotpink" }}>{name}</div>,
  },
};
```

--------------------------------

### Organize Puck Components into Categories

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/config.mdx

This example illustrates how to define categories for organizing Puck components. The 'typography' category is created, and the 'HeadingBlock' component is assigned to it. This grouping helps in structuring the component sidebar within the Puck editor.

```tsx
const config = {
  categories: {
    typography: {
      components: ["HeadingBlock"],
    },
  },
  // ...
};
```

--------------------------------

### Configure Number Input

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/fields/number.mdx

This snippet shows the basic configuration for a number input field. It defines the field type as 'number' and includes a render function to display the input's value. This is a fundamental setup for using the Number component.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        myNumber: {
          type: "number",
        },
      },
      render: ({ myNumber }) => {
        return <div>{myNumber}</div>;
      },
    },
  },
};
```

--------------------------------

### Using External Field Type for Data Selection (React)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/external-data-sources.mdx

Demonstrates how to use the 'external' field type in Puck to allow users to select tabular data from a third-party source. This example shows fetching a list of items and rendering them. It assumes a basic setup for fetching data from an API.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        data: {
          type: "external",
          fetchList: async () => {
            // Query an API for a list of items
            const items = await fetch(`/api/items`).then((res) => res.json());
            // [
            //   { title: "Hello, world", description: "Lorem ipsum 1" },
            //   { title: "Goodbye, world", description: "Lorem ipsum 2" },
            // ];

            return items;
          },
        },
      },
      render: ({ data }) => {
        if (!data) {
          return "No data selected";
        }

        return (
          <>
            <b>{data.title}</b>
            <p>{data.description}</p>
          </>
        );
      },
    },
  },
};
```

--------------------------------

### Generate Puck App using yarn

Source: https://github.com/puckeditor/puck/blob/main/packages/create-puck-app/README.md

This snippet shows how to use `yarn create` to execute the `create-puck-app` command, initializing a new Puck application named 'my-app'. This provides an alternative package manager for project initialization.

```shell
yarn create puck-app my-app
```

--------------------------------

### Implement Fixed Layouts with Multiple Slot Fields (TypeScript)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/multi-column-layouts.mdx

This example shows how to create fixed multi-column layouts by defining multiple 'slot' fields within a component. Each slot acts as a distinct area where components can be placed, allowing for structured arrangements like a two-column grid. This approach utilizes CSS Grid for layout.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        leftColumn: {
          type: "slot",
        },
        rightColumn: {
          type: "slot",
        },
      },
      render: ({ leftColumn: LeftColumn, rightColumn: RightColumn }) => {
        return (
          <div
            style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 16 }}
          >
            <LeftColumn />
            <RightColumn />
          </div>
        );
      },
    },
    Card: {
      render: ({ text }) => <div>{text}</div>,
    },
  },
};
```

--------------------------------

### Basic Puck.Preview Rendering

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck-preview.mdx

Demonstrates the fundamental usage of Puck.Preview within a Puck editor context. This snippet shows how to initialize Puck and include the Preview component to display the editor's content.

```tsx
import { Puck } from "@puckeditor/core";

export function Editor() {
  return (
    <Puck>
      <Puck.Preview />
    </Puck>
  );
}
```

--------------------------------

### Install @puckeditor/field-contentful

Source: https://github.com/puckeditor/puck/blob/main/packages/field-contentful/README.md

Installs the @puckeditor/field-contentful package using npm. This is the first step to integrate Contentful data selection into your Puck Editor project.

```sh
npm i @puckeditor/field-contentful
```

--------------------------------

### ui

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Set the initial application UI state, controlling aspects like the visibility of UI elements.

```APIDOC
## `ui`

Set the initial application UI state. See [`AppState.ui`](/docs/api-reference/data-model/app-state#ui).
```

--------------------------------

### Initialize Puck Home Component

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/index.mdx

Imports and renders the Home component for the Puck editor interface.

```jsx
import { Home } from "../components/Home";

<Home />
```

--------------------------------

### Initialize and use the usePuck hook

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/functions/use-puck.mdx

Demonstrates how to create a custom usePuck hook using the factory method and consume it within a React component to access editor state.

```tsx
import { createUsePuck } from "@puckeditor/core";

const usePuck = createUsePuck();

const Example = () => {
  const type = usePuck((s) => s.selectedItem?.type || "Nothing");

  return <h2>{type} selected</h2>;
};
```

--------------------------------

### GET /selectedItem

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/puck-api.mdx

Retrieves the currently selected item from the application state.

```APIDOC
## GET /selectedItem

### Description
Returns the currently selected item, as defined by appState.ui.itemSelector.

### Method
GET

### Response
#### Success Response (200)
- **item** (object) - The selected item object containing type and props.

### Response Example
{
  "type": "Heading",
  "props": { "id": "my-heading" }
}
```

--------------------------------

### Define Slot Field in Puck Editor Configuration (TypeScript)

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/fields/slot.mdx

This snippet demonstrates how to define a 'slot' type field within the Puck Editor configuration. The 'Example' component has a 'content' field of type 'slot', allowing nested components to be rendered within it. The 'Card' component is a simple example of a component that can be placed inside the slot.

```tsx
const config = {
  components: {
    Example: {
      fields: {
        content: {
          type: "slot",
        },
      },
      render: ({ content: Content }) => {
        return <Content />;
      },
    },
    Card: {
      render: () => <div>Hello, world</div>,
    },
  },
};
```

--------------------------------

### Initialize Puck Next.js Project

Source: https://github.com/puckeditor/puck/blob/main/recipes/next-ai/README.md

Commands to scaffold a new Next.js project with Puck AI integration enabled. This process sets up the necessary file structure for the editor and AI capabilities.

```bash
npx create-puck-app my-app
# Select 'Next.js' when prompted
# Select 'Y' for Puck AI integration
cd my-app
yarn dev
```

--------------------------------

### Get Permissions for Root

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/puck-api.mdx

Retrieves the permissions for the root component. This is set via the 'permissions' parameter in the component configuration.

```tsx
getPermissions({ root: true });
// { delete: false }
```

--------------------------------

### Retrieve latest PuckApi with useGetPuck

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/functions/use-get-puck.mdx

This snippet demonstrates how to initialize the useGetPuck hook and use the returned function to access the current appState within a callback. It is useful for scenarios where you need the latest state without triggering re-renders.

```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>;
};
```

--------------------------------

### Define a Puck configuration with client components

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/server-components.mdx

Import client-side components into the Puck configuration and render them within the component definition.

```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} />,
    },
  },
};
```

--------------------------------

### Configure DropZone Restrictions

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/drop-zone.mdx

Examples of using allow and disallow props to control which components can be dropped into a specific zone.

```tsx
const config = {
  components: {
    Example: {
      render: () => {
        return (
          <div>
            <DropZone zone="my-content" allow={["HeadingBlock"]} />
            <DropZone zone="my-content" disallow={["HeadingBlock"]} />
          </div>
        );
      },
    },
  },
};
```

--------------------------------

### Configure Puck API Key

Source: https://github.com/puckeditor/puck/blob/main/recipes/next-ai/README.md

Environment variable configuration required to authenticate with Puck AI services. This should be placed in the project root within a .env.local file.

```text
PUCK_API_KEY=your-api-key
```

--------------------------------

### Get Permissions for Component Type

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/puck-api.mdx

Retrieves the permissions for a given component type. This is configured using the 'permissions' parameter in the component configuration.

```tsx
getPermissions({ type: "HeadingBlock" });
// { delete: false }
```

--------------------------------

### Example Mapping Title to ResolvedTitle

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

Dynamically maps a 'title' prop to a 'resolvedTitle' prop and sets 'resolvedTitle' as read-only. This is useful for transforming or preparing data before rendering.

```tsx
const config = {
  components: {
    HeadingBlock: {
      fields: {
        title: {
          type: "text",
        },
      },
      resolveData: async ({ props }) => {
        return {
          props: { resolvedTitle: props.title },
          readOnly: { resolvedTitle: true },
        };
      },
      render: ({ resolvedTitle }) => <h1>{resolvedTitle}</h1>,
    },
  },
};
```

--------------------------------

### Integrating Puck Plugins

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Enhance Puck's behavior by providing an array of plugins to the `plugins` prop. Ensure the plugin is imported correctly.

```tsx
import headingAnalyzer from "@puckeditor/plugin-heading-analyzer";

export function Editor() {
  return (
    <Puck
      plugins={[headingAnalyzer]}
      // ...
    />
  );
}
```

--------------------------------

### Create a custom plugin with UI

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/plugins.mdx

Shows how to define a plugin object with a name, label, icon, and a render function to display custom UI in the Plugin Rail.

```tsx
import { Coffee } from "lucide-react";

const myPlugin = {
  name: "my-plugin", // Globally unique name
  label: "My Plugin", // Human-readable name shown in the rail
  icon: <Coffee />, // Icon shown in the rail (use lucide to match Puck)
  render: () => <div>My plugin UI</div>, // Component rendered in plugin panel
};
```

--------------------------------

### Drawer Component with Inline Theming

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/drawer.mdx

Demonstrates how to apply drawer theming properties directly using inline styles within a React component. This allows for dynamic theming based on component state or props.

```jsx
<div
  style={{
    "--puck-drawer-item-color-bg": "#1e1e2e",
    "--puck-drawer-item-color-text": "#cdd6f4",
    "--puck-drawer-item-radius": "12px",
  }}>
  <Drawer>
    <Drawer.Item name="Heading" />
    <Drawer.Item name="Paragraph" />
  </Drawer>
</div>
```

--------------------------------

### Customize DropZone Appearance and Behavior

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/drop-zone.mdx

Examples of applying custom CSS classes, collision detection axes, and minimum heights to a DropZone.

```tsx
const config = {
  components: {
    Example: {
      render: () => {
        return (
          <div>
            <DropZone zone="my-content" className="MyComponent" />
            <DropZone zone="my-content" collisionAxis="dynamic" />
            <DropZone zone="my-content" minEmptyHeight="256px" />
          </div>
        );
      },
    },
  },
};
```

--------------------------------

### initialHistory

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Sets the undo/redo Puck history state when using the `usePuck` history API. It allows you to define the initial state of the history stack and the current index.

```APIDOC
## `initialHistory`

Sets the undo/redo Puck history state when using the `usePuck` [history API](/docs/api-reference/puck-api#history).

### Parameters

#### `initialHistory` object

- **`histories`** (Array<History>) - Required - An array of histories to reset the Puck state history state to.
- **`index`** (Number) - Required - The index of the histories to set the user to.
- **`appendData`** (Boolean) - Optional - Append the Puck [`data`](#data) prop onto the end of [`histories`](#histories). Defaults to `true`. When `false`, the Puck `data` prop will be ignored but you must specify at least one item in the `histories` array.
```

--------------------------------

### Configuring Field Transforms in Puck

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

Modify field values before they are passed to the editor canvas using the `fieldTransforms` prop. This example wraps all text field values in a `<div>` element.

```tsx
export function Editor() {
  return (
    <Puck
      fieldTransforms={{
        text: ({ value }) => <div>{value}</div>, // Wrap all text field values in a div
      }}
      // ...
    />
  );
}
```

--------------------------------

### Implement custom controls with editor instance

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/fields/richtext.mdx

Shows how to access the Tiptap editor instance to trigger commands, such as toggling a blockquote, directly from a custom button.

```tsx
import { RichTextMenu } from "@puckeditor/core";

const config = {
  components: {
    Example: {
      fields: {
        description: {
          type: "richtext",
          renderMenu: ({ editor }) => (
            <RichTextMenu>
              <RichTextMenu.Group>
                <button
                  onClick={() =>
                    editor?.chain().focus().toggleBlockquote().run()
                  }
                >
                  Quote
                </button>
              </RichTextMenu.Group>
            </RichTextMenu>
          ),
        },
      },
    },
  },
};
```

--------------------------------

### Basic Component Rendering

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/configuration/component-config.mdx

Defines a simple component with a `render` function that outputs static content.

```tsx
const config = {
  components: {
    HeadingBlock: {
      render: () => <h1>Hello, world</h1>,
    },
  },
};
```

--------------------------------

### Apply Custom Theme with CSS Tokens

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/theming.mdx

Override Puck's default CSS custom properties to apply a custom theme. This example sets an interactive color and a medium radius.

```css
@import "@puckeditor/core/puck.css";

.Container {
  --puck-color-interactive: #0f5fff;
  --puck-radius-m: 8px;
}
```

--------------------------------

### Initialize fieldsPlugin in Puck Editor

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/plugins/fields-plugin.mdx

Demonstrates how to import and register the fieldsPlugin within the Puck editor component. This plugin is included by default but can be explicitly configured.

```tsx
import { Puck, fieldsPlugin } from "@puckeditor/core";

const fields = fieldsPlugin();

export function Editor() {
  return <Puck plugins={[fields]} />;
}
```

--------------------------------

### Action Bar React Component with Theming

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/action-bar.mdx

Demonstrates how to apply theme properties to the ActionBar component using inline styles in a React environment. This allows for dynamic theming.

```jsx
<PuckPreview>
  <div
    style={{
      "--puck-actionbar-color-bg": "darkgreen",
      "--puck-actionbar-color-action-hover": "white",
      "--puck-actionbar-radius": "999px",
    }}
  >
    <ActionBar label="Actions">
      <ActionBar.Group>
        <ActionBar.Action>★</ActionBar.Action>
      </ActionBar.Group>
    </ActionBar>
  </div>
</PuckPreview>
```

--------------------------------

### Customize Global Theme Colors

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/theming.mdx

Modify global theme tokens to adjust interactive colors, focus rings, and selection backgrounds to match your brand. This example uses a teal color palette.

```css
.Container {
  --puck-color-interactive: #0d9488;
  --puck-color-interactive-hover: #0f766e;
  --puck-color-interactive-active: #115e59;
  --puck-color-interactive-subtle: #ccfbf1;
  --puck-color-interactive-soft: #f0fdfa;
  --puck-color-interactive-soft-hover: #ccfbf1;
  --puck-color-focus-ring: #14b8a6;
  --puck-color-selection-bg: color-mix(in srgb, #14b8a6 20%, transparent);
  --puck-color-selection-border: #14b8a6;
  --puck-slot-component-color-placeholder: #99f6e4;
  --puck-slot-component-color-border-dragging: #5eead4;
}
```

--------------------------------

### Puck Utility Functions and Hooks

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/functions.mdx

A collection of utility functions for data migration, tree traversal, and React hooks for accessing the Puck API.

```APIDOC
## migrate

### Description
Migrate a legacy data payload to the latest shape.

## resolveAllData

### Description
Utility function to execute all resolveData methods on a data payload.

## transformProps

### Description
Transform component props stored in the data payload. Use this for migrations, like prop renames.

## useGetPuck

### Description
A hook for accessing the latest PuckApi outside of the React render lifecycle.

## usePuck

### Description
A hook for accessing the PuckApi inside your components.

## walkTree

### Description
Walk the tree recursively, modifying it if necessary.
```

--------------------------------

### Define Render configuration

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/render.mdx

Demonstrates how to define component structures within the Render config prop. This includes defining fields and the render function for custom blocks.

```tsx
export function Example() {
  return (
    <Render
      config={{
        components: {
          HeadingBlock: {
            fields: {
              children: {
                type: "text",
              },
            },
            render: ({ children }) => {
              return <h1>{children}</h1>;
            },
          },
        },
      }}
    />
  );
}
```

--------------------------------

### Action Bar CSS Theming

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/action-bar.mdx

Customize the Action Bar's appearance using CSS custom properties. This example sets the background color, hover color for actions, and border radius.

```css
.Container {
  --puck-actionbar-color-bg: darkgreen;
  --puck-actionbar-color-action-hover: white;
  --puck-actionbar-radius: 999px;
}
```

--------------------------------

### Button Theming CSS Properties

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/button.mdx

Apply these CSS custom properties to a container element to theme Puck's buttons. This example sets the radius, primary background color, and hover background color.

```css
.Container {
  --puck-button-radius: 9999px;
  --puck-button-primary-color-bg: #6d28d9;
  --puck-button-primary-color-bg-hover: #5b21b6;
}
```

--------------------------------

### Inline Style Theming for Outline Panel

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/theming/outline.mdx

Demonstrates applying outline theming directly via inline styles within a React component. This is useful for dynamic theming or when CSS classes are not directly applicable.

```jsx
<div
  style={{
    "--puck-outline-color-bg-selected": "#f0f0f0",
    "--puck-outline-color-border-selected": "#b947ff",
  }}>
  <Puck.Outline />
</div>
```

--------------------------------

### RootData JSON Structure Example

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/data-model/root-data.mdx

This JSON snippet illustrates the basic structure of RootData, including the 'props' object which holds component-specific properties like 'title'.

```json
{
  "props": {
    "title": "Hello, world"
  }
}
```

--------------------------------

### Load a plugin into the Puck editor

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/extending-puck/plugins.mdx

Demonstrates how to register a custom plugin by passing it to the plugins array prop of the Puck component.

```tsx
import { Puck } from "@puckeditor/core";
import myPlugin from "my-puck-plugin";

export function Editor() {
  return (
    <Puck
      // ...
      plugins={[myPlugin]}
    />
  );
}
```

--------------------------------

### Initialize and Use blocksPlugin in PuckEditor

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/plugins/blocks-plugin.mdx

Demonstrates how to import and use the blocksPlugin within a PuckEditor instance. This plugin is essential for the component drawer functionality and is typically included by default.

```tsx
import { Puck, blocksPlugin } from "@puckeditor/core";

const blocks = blocksPlugin();

export function Editor() {
  return <Puck plugins={[blocks]} />;
}
```

--------------------------------

### plugins

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/api-reference/components/puck.mdx

An array of plugins to enhance Puck's behaviour. These plugins can extend Puck's functionality and integrate custom features.

```APIDOC
## `plugins`

An array of plugins to enhance Puck's behaviour. See the [Plugin API reference](/docs/api-reference/plugin).
```

--------------------------------

### Transform component props

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/data-migration.mdx

Utilizes the transformProps utility to map legacy props to new structures within the data payload. This can be applied as a batch operation or during the rendering process.

```tsx
import { transformProps } from "@puckeditor/core";

const config = {
  HeadingBlock: ({ heading }) => <h1>{heading}</h1>,
};

const data = {
  content: [
    { type: "HeadingBlock", props: { title: "Hello, world" } },
  ],
};

const updatedData = transformProps(data, {
  HeadingBlock: ({ title, ...props }) => ({ heading: title, ...props }),
});

console.log(updatedData);
```

```tsx
import { Puck, Render, transformProps } from "@puckeditor/core";

const transforms = {
  HeadingBlock: ({ title, ...props }) => ({ heading: title, ...props }),
};

export const MyEditor = ({ data, config }) => (
  <Puck data={transformProps(data, transforms)} config={config} />
);

export const MyPage = ({ data, config }) => (
  <Render data={transformProps(data, transforms)} config={config} />
);
```

--------------------------------

### Define a basic component in Puck configuration

Source: https://github.com/puckeditor/puck/blob/main/apps/docs/pages/docs/integrating-puck/component-configuration.mdx

Demonstrates how to register a component in the Puck configuration object by providing a render function. This function determines how the component appears in the editor and final output.

```tsx
const config = {
  components: {
    HeadingBlock: {
      render: () => {
        return <h1>Hello, world</h1>;
      },
    },
  },
};
```