@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/extending-puck/custom-fields.md

@@ -0,0 +1,133 @@
+# Custom Fields
+
+Puck can be extended with completely custom fields for different use-cases.
+
+## Creating a custom field
+
+Creating a custom field is possible using the [`custom` field type](/docs/api-reference/fields/custom):
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+              style={{ border: "1px solid black", padding: 4 }}
+            />
+          ),
+        },
+      },
+      render: ({ title }) => {
+        return <p>{title}</p>;
+      },
+    },
+  },
+};
+```
+
+The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) updates the Puck data payload for the field name, in this case "title".
+
+## Adding a label
+
+You can add your own label, but it's recommended to use the [`<FieldLabel>` component](/docs/api-reference/components/field-label) provided by Puck to seamlessly integrate into the Puck field UI.
+
+```tsx
+import { FieldLabel } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          label: "Label Example",
+          render: ({ field }) => (
+            <FieldLabel label={field.label}>
+              <input {/*...*/} />
+            </FieldLabel>
+          ),
+        },
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Rendering Puck fields internally
+
+Use the [`<AutoField>` component](/docs/api-reference/components/auto-field) to render Puck fields within your custom field.
+
+```tsx
+import { AutoField } from "@puckeditor/core";
+
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          label: "Label Example",
+          render: ({ field, value, onChange }) => (
+            <FieldLabel label={field.label}>
+              <AutoField
+                field={{ type: "text" }}
+                onChange={(value) => onChange(value)}
+                value={value}
+              />
+            </FieldLabel>
+          ),
+        },
+        // ...
+      },
+    },
+  },
+};
+```
+
+## Updating the UI state
+
+The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) can also be used to modify the [Puck UI state](/docs/api-reference/data-model/app-state#ui) at the same time as updating the field value:
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) =>
+                onChange(
+                  e.currentTarget.value,
+                  // Close the left side bar when this field is changed
+                  { leftSideBarVisible: false }
+                )
+              }
+              style={{ border: "1px solid black", padding: 4 }}
+            />
+          ),
+        },
+      },
+      render: ({ title }) => {
+        return <p>{title}</p>;
+      },
+    },
+  },
+};
+```
+
+## Further reading
+
+- [The `<AutoField>` API reference](/docs/api-reference/components/auto-field)
+- [The `<FieldLabel>` API reference](/docs/api-reference/components/field-label)
+- [The `custom` field API reference](/docs/api-reference/fields/custom)

package/dist/docs/extending-puck/field-transforms.md

@@ -0,0 +1,89 @@
+# Field Transforms
+
+Puck lets you modify props before rendering in the editor via the [`FieldTransforms` API](/docs/api-reference/field-transforms).
+
+Use this API to implement custom rendering behavior for specific field types, which can be used to implement features such as inline text editing.
+
+> **Note:** Field transforms only apply to components rendered in `<Puck>` and will not be applied to `<Render>`.
+
+## Implementing a transform
+
+Specify a transforms object for the fields you want to modify before rendering:
+
+```tsx
+const fieldTransforms = {
+  text: ({ value }) => value.toUpperCase(), // Transform text fields to uppercase
+};
+
+const Example = () => <Puck fieldTransforms={fieldTransforms} />;
+```
+
+## Making it interactive
+
+Combine transforms with [Overlay Portals](/docs/integrating-puck/overlay-portals) to make them interactive.
+
+```tsx
+import { registerOverlayPortal } from "@puckeditor/core";
+
+const EditableText = ({ value }) => {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    if (ref.current) {
+      // Register the element as an overlay portal
+      registerOverlayPortal(ref.current);
+    }
+  }, [ref.current]);
+
+  return (
+    // Mark the element as editable for inline text editing
+    <p ref={ref} contentEditable>
+      {value}
+    </p>
+  );
+};
+
+const fieldTransforms = {
+  text: (props) => <EditableText {...props} />,
+};
+
+const Example = () => <Puck fieldTransforms={fieldTransforms} />;
+```
+
+Because Puck calls transforms as functions, render components that use hooks from the transform instead of passing them directly.
+
+## Define new fields
+
+As with [field type overrides](/docs/extending-puck/ui-overrides#introducing-new-field-types), field transforms let you define your own field types:
+
+```tsx
+const fieldTransforms = {
+  example: () => <div />,
+};
+```
+
+## Distributing field transforms as plugins
+
+Distribute transforms as plugins to package up custom behavior.
+
+```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]} />;
+```
+
+## Further reading
+
+- [Field Transforms API reference](/docs/api-reference/field-transforms)
+- [Overlay Portals API reference](/docs/integrating-puck/overlay-portals)

package/dist/docs/extending-puck/internal-puck-api.md

@@ -0,0 +1,96 @@
+# Internal Puck API
+
+Puck exposes its internal API as [`PuckApi`](/docs/api-reference/puck-api) for extending Puck with custom functionality within [custom fields](/docs/extending-puck/custom-fields), [compositional interfaces](/docs/extending-puck/composition) or [UI overrides](/docs/extending-puck/ui-overrides).
+
+## Accessing the internal API
+
+You can access [`PuckApi`](/docs/api-reference/puck-api) via two hooks:
+
+- [`usePuck`](/docs/api-reference/functions/use-puck) - returns `PuckApi` as part of your component render lifecycle
+- [`useGetPuck`](/docs/api-reference/functions/use-get-puck) - returns a function to access the latest `PuckApi` at call time
+
+### Within the render lifecycle
+
+To access the API within your render lifecycle, use the `usePuck` hook. You can use a selector to limit re-rendering to a specific part of the API.
+
+```tsx
+import { createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const Example = () => {
+  // Use a selector so you only re-render when the selected type changes
+  const type = usePuck((s) => s.selectedItem?.type || "Nothing");
+
+  return <h2>{type} selected</h2>;
+};
+```
+
+See the [`usePuck`](/docs/api-reference/functions/use-puck) docs for a full API reference.
+
+### Outside of the render lifecycle
+
+Often it's not necessary to re-render your component when the PuckApi changes. Puck provides the `useGetPuck` hook for accessing the latest `PuckApi` at call time.
+
+```tsx
+import { useGetPuck } from "@puckeditor/core";
+
+const Example = () => {
+  const getPuck = useGetPuck();
+
+  const handleClick = useCallback(() => {
+    // Get the latest PuckApi value
+    const { appState } = getPuck();
+
+    console.log(appState);
+  }, [getPuck]);
+
+  return <button onClick={handleClick}>Click me</button>;
+};
+```
+
+See the [`useGetPuck`](/docs/api-reference/functions/use-get-puck) docs for a full API reference.
+
+## Usage in practice
+
+Generally, you'll want to combine this with composition, UI overrides or custom fields.
+
+Here's an example using the internal API to log the page data as JSON while retaining the standard Puck UI:
+
+```tsx
+import { Puck, createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const JSONLogger = ({ children }) => {
+  const appState = usePuck((s) => s.appState);
+
+  useEffect(() => {
+    console.log(appState);
+  }, [appState]);
+
+  return <>{children}</>;
+};
+
+export function Editor() {
+  return (
+    // Render the Puck context
+    <Puck>
+      <JSONLogger>
+        {/* Since we're overriding Puck's children, we restore the standard Puck UI */}
+        <Puck.Layout />
+      </JSONLogger>
+    </Puck>
+  );
+}
+```
+
+## Further reading
+
+- [`PuckApi` API reference](/docs/api-reference/puck-api)
+- [`usePuck` API reference](/docs/api-reference/functions/use-puck)
+- [`useGetPuck` API reference](/docs/api-reference/functions/use-get-puck)
+- [`<Puck.Layout>` API reference](/docs/api-reference/components/puck-layout)
+- [Composition](/docs/extending-puck/composition)
+- [Custom fields](/docs/extending-puck/custom-fields)
+- [UI overrides](/docs/extending-puck/ui-overrides)

package/dist/docs/extending-puck/plugins.md

@@ -0,0 +1,159 @@
+# Plugin API
+
+The [plugin API](/docs/api-reference/plugins) enables developers to share extensions to Puck.
+
+Plugins can display dedicated UI in the **Plugin Rail** on the left-hand side of the screen (bottom on mobile), configure their own [overrides](/docs/extending-puck/ui-overrides), or apply [field transforms](/docs/extending-puck/field-transforms).
+
+## Official plugins
+
+### Core plugins
+
+These plugins are included in the core package:
+
+- [`blocks`](/docs/api-reference/plugins/blocks-plugin): show the component drawer for dragging components onto the canvas
+- [`fields`](/docs/api-reference/plugins/fields-plugin): render the fields for the currently selected component
+- [`outline`](/docs/api-reference/plugins/outline-plugin): display an outline of the current page structure
+- [`legacy-side-bar`](/docs/api-reference/plugins/legacy-side-bar-plugin): disable the plugin rail in favor of stacked "Components" / "Outline" sections
+
+### Enhancements
+
+Puck provides official plugins that can be installed for common use-cases:
+
+- [`ai`](https://puckeditor.com/docs/ai/overview): Use AI to generate pages using your own components.
+- [`emotion-cache`](https://github.com/puckeditor/puck/tree/main/packages/plugin-emotion-cache): Inject emotion cache into the Puck iframe.
+- [`heading-analyzer`](https://github.com/puckeditor/puck/tree/main/packages/plugin-heading-analyzer): Analyze the heading outline of your page and be warned when you're not respecting WCAG 2 accessibility standards.
+
+Please see the [awesome-puck repo](https://github.com/puckeditor/awesome-puck) for a full list of community plugins.
+
+## Loading a Plugin
+
+To load a plugin, provide it to the [`plugins` prop](/docs/api-reference/components/puck#plugins) on the `<Puck>` component.
+
+```tsx
+import { Puck } from "@puckeditor/core";
+import myPlugin from "my-puck-plugin";
+
+export function Editor() {
+  return (
+    <Puck
+      // ...
+      plugins={[myPlugin]}
+    />
+  );
+}
+```
+
+## Developing a Plugin
+
+If you're familiar with Puck, you can likely already build a Puck plugin. See the [Plugin API reference](/docs/api-reference/plugins) for a full breakdown of available APIs.
+
+### Rendering UI in the Plugin Rail
+
+Plugins can render dedicated UI in a panel shown by the Plugin Rail. To add a plugin to the rail, create a new plugin and provide some parameters:
+
+```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
+};
+```
+
+You can leverage the [internal Puck API](/docs/extending-puck/internal-puck-api) to integrate Puck behavior with your plugin:
+
+```tsx
+import { Coffee } from "lucide-react";
+import { createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const myPlugin = {
+  name: "my-plugin",
+  label: "My Plugin",
+  icon: <Coffee />,
+  render: () => {
+    const type = usePuck((s) => s.selectedItem?.type || "Nothing");
+
+    return <h2>{type} selected</h2>;
+  },
+};
+```
+
+### Transforming fields
+
+Plugins support [Field Transforms](/docs/extending-puck/field-transforms), enabling you to modify prop data before it's rendered in the `<Puck>` preview.
+
+```tsx
+const plugin = {
+  fieldTransforms: {
+    // Make all props powered by "text" field pink in the canvas
+    text: ({ value }) => <span style={{ color: "hotpink" }}>{value}</span>,
+  },
+};
+```
+
+### Overriding the UI
+
+Plugins support [UI Overrides](/docs/extending-puck/ui-overrides), enabling you to override discrete section of the Puck interface.
+
+```tsx
+const plugin = {
+  overrides: {
+    // Make all drawer items pink
+    drawerItem: ({ name }) => <div style={{ color: "hotpink" }}>{name}</div>,
+  },
+};
+```
+
+> **Note:** Override currying
+>
+> Plugin overrides are rendered in the order they are defined. Unless otherwise specified, all overrides are _curried_, meaning that the return node of one plugin will be passed as `children` to the next plugin.
+>
+> This may result in some incompatible plugin combinations. To improve your chance of building a widely compatible plugin, consider:
+>
+> 1. Implementing as few override methods as you need
+> 2. Always rendering `children` if possible
+
+### Introducing new field types
+
+Both the field transforms and overrides let you introduce [entirely new field types](/docs/extending-puck/ui-overrides#introducing-new-field-types). Plugins can combine this functionality to bundle up new field behavior in a convenient package.
+
+This example uses [Overlay Portals](/docs/extending-puck/overlay-portals) to create an interactive rich text field that can be modified directly in the editor preview.
+
+```tsx
+import { useCallback } from "react";
+import { registerOverlayPortal } from "@puckeditor/core";
+
+const InlineRichText = ({ value }) => {
+  const handleInput = useCallback(() => {}, []); // Implement your input behavior
+
+  return (
+    // Wrap the value in a span, create an overlay portal, and make it editable
+    <span ref={registerOverlayPortal} contentEditable onInput={handleInput}>
+      {value}
+    </span>
+  );
+};
+
+const plugin = {
+  overrides: {
+    // Add a richText field type
+    fieldTypes: {
+      richText: ({ name, value }) => <input name={name} value={value} />,
+    },
+  },
+  fieldTransforms: {
+    // Make the richText field editable inline
+    richText: (props) => <InlineRichText {...props} />,
+  },
+};
+```
+
+## Further reading
+
+- [Plugin API reference](/docs/api-reference/plugin)
+- [FieldTransforms API reference](/docs/api-reference/field-transforms)
+- [UI Overrides](/docs/extending-puck/ui-overrides)

package/dist/docs/extending-puck/theming.md

@@ -0,0 +1,88 @@
+# Theming
+
+Puck's default interface is styled with CSS custom properties (design tokens). You can override these tokens to create a custom theme that matches your brand or product, or to implement dark mode.
+
+See the theming API reference for the full list of tokens:
+
+- [Global tokens](/docs/api-reference/theming/global): Tokens that restyle the whole interface at once.
+- [Action bar](/docs/api-reference/theming/action-bar): Tokens that style the action bar shown when selecting a component.
+- [Button](/docs/api-reference/theming/button): Tokens that style the text buttons.
+- [Canvas](/docs/api-reference/theming/canvas): Tokens that style the canvas preview area.
+- [Drawer](/docs/api-reference/theming/drawer): Tokens that style the component drawer.
+- [Fields](/docs/api-reference/theming/fields): Tokens that style the puck [fields](/docs/api-reference/fields).
+- [Header](/docs/api-reference/theming/header): Tokens that style the editor header.
+- [Icon button](/docs/api-reference/theming/icon-button): Tokens that style the icon buttons.
+- [Outline](/docs/api-reference/theming/outline): Tokens that style the outline panel.
+- [Plugin bar](/docs/api-reference/theming/plugin-bar): Tokens that style the side navigation for switching plugins.
+- [Sidebar](/docs/api-reference/theming/sidebar): Tokens that style the left and right sidebar panels.
+- [Slot](/docs/api-reference/theming/slot): Tokens that style the slots.
+- [Computed values](/docs/api-reference/theming/computed-values): Tokens that define default computed values for all component-level tokens.
+
+## Applying a theme
+
+To apply a theme override the token you want in any element above the editor in the DOM tree:
+
+```css
+@import "@puckeditor/core/puck.css";
+
+.Container {
+  --puck-color-interactive: #0f5fff;
+  --puck-radius-m: 8px;
+}
+```
+
+## Global tokens
+
+[Global tokens](/docs/api-reference/theming/global) restyle the whole interface at once, covering color, spacing, radius, motion and typography.
+
+For example, to change the palette to match the interactive colors of your brand:
+
+```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;
+}
+```
+
+The [API reference](/docs/api-reference/theming/global) lists where each global token is used.
+
+## Component tokens
+
+When you need finer control, component tokens restyle a single part of the UI and override global tokens.
+
+For example, to set the header and plugin bar background:
+
+```css
+.Container {
+  --puck-header-color-bg: #fff4e6;
+  --puck-pluginbar-color-bg: #fff4e6;
+}
+```
+
+## Load your own font file
+
+By default, Puck loads the [Inter typeface family](https://rsms.me/inter/) from a CDN. To host your own copy of Inter, or load a different font file, switch Puck to the `no-external` runtime bundle:
+
+```css
+/* @import "@puckeditor/core/puck.css"; */
+@import "@puckeditor/core/no-external.css";
+```
+
+## Going further
+
+CSS tokens restyle the default interface. To change its behavior or visuals not covered by tokens, use the [composition](/docs/extending-puck/composition) or [UI overrides](/docs/extending-puck/ui-overrides) APIs.
+
+## Further reading
+
+- [Theming API reference](/docs/api-reference/theming)
+- [Composition](/docs/extending-puck/composition)
+- [UI overrides](/docs/extending-puck/ui-overrides)

package/dist/docs/extending-puck/ui-overrides.md

@@ -0,0 +1,134 @@
+# UI overrides
+
+> **Note:** The overrides API is highly experimental and is likely to experience breaking
+> changes.
+
+Overrides allow you to change how Puck renders its default interface. It can be used with or without [composition](/docs/extending-puck/composition).
+
+There are many different overrides available. See the [`overrides` API reference](/docs/api-reference/overrides) for the full list.
+
+## Implementing an override
+
+Use the [`overrides` prop](/docs/api-reference/components/puck#overrides) to implement an override:
+
+```tsx
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck
+      // ...
+      overrides={{
+        // Render a custom element for each item in the component list
+        drawerItem: ({ name }) => (
+          <div style={{ backgroundColor: "hotpink" }}>{name}</div>
+        ),
+      }}
+    />
+  );
+}
+```
+
+## Overriding field types
+
+You can override all fields of certain type by specifying the [`fieldTypes` override](/docs/api-reference/overrides/field-types).
+
+```tsx
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck
+      // ...
+      overrides={{
+        fieldTypes: {
+          // Override all text fields with a custom input
+          text: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) => onChange(e.currentTarget.value)}
+              style={{ border: "1px solid black", padding: 4 }}
+            />
+          ),
+        },
+      }}
+    />
+  );
+}
+```
+
+## Introducing new field types
+
+Specify new field types to expose new fields to your components.
+
+```tsx
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck
+      // ...
+      overrides={{
+        fieldTypes: {
+          myField: ({ name, onChange, value }) => <div />,
+        },
+      }}
+    />
+  );
+}
+```
+
+> **Note:** TypeScript consideration: When introducing new field types with
+> TypeScript, you'll need to extend the available field types with the `fields`
+> key in your `Config` type generic.
+
+## Examples
+
+### Custom publish button
+
+A common use case is to override the Puck header. You can either use the [`header` override](/docs/api-reference/overrides/header) to change the entire header, or use the [`headerActions` override](/docs/api-reference/overrides/header-actions) to inject new controls into the header and change the publish button.
+
+Here's an example that also leverage the [internal Puck API](/docs/extending-puck/internal-puck-api) to replace the default publish button with a custom one:
+
+```tsx
+import { Puck, createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const save = () => {};
+
+export function Editor() {
+  return (
+    <Puck
+      // ...
+      overrides={{
+        headerActions: ({ children }) => {
+          const appState = usePuck((s) => s.appState);
+
+          return (
+            <>
+              <button
+                onClick={() => {
+                  save(appState.data);
+                }}
+              >
+                Save
+              </button>
+
+              {/* Render default header actions, such as the default Button */}
+              {/*{children}*/}
+            </>
+          );
+        },
+      }}
+    />
+  );
+}
+```
+
+## Further reading
+
+- [`overrides` API reference](/docs/api-reference/overrides)
+- [Composition](/docs/extending-puck/composition)
+- [Internal Puck API](/docs/extending-puck/internal-puck-api)