@puckeditor/cli 0.24.0-canary.301a0304

package/dist/docs/integrating-puck/feature-toggling.md

@@ -0,0 +1,121 @@
+# Feature Toggling
+
+Feature toggling is enabled by Puck's [Permissions API](/docs/api-reference/permissions). This enables you to toggle behavior like:
+
+- Deletion
+- Dragging
+- Duplication
+- Editing (setting all fields to read-only)
+- etc
+
+See the [supported permissions reference](/docs/api-reference/permissions#supported-permissions) for a complete list.
+
+## Toggling features globally
+
+Toggling features across the entire Puck instance can be done with global permissions. These can be set by the [`permissions` prop](/docs/api-reference/components/puck#permissions) on the Puck component:
+
+```tsx
+export function Editor() {
+  return (
+    <Puck
+      permissions={{
+        delete: false, // Disable delete function on all components
+      }}
+      // ...
+    />
+  );
+}
+```
+
+## Toggling features per component
+
+Toggling feature for all instance of a component can be done using component permissions. This is controlled by the [`permissions` parameter](/docs/api-reference/configuration/component-config#permissions) on the component config, and inherits the global permissions.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      permissions: {
+        delete: false, // Disable delete function on all HeadingBlock instances
+      },
+      // ...
+    },
+  },
+};
+```
+
+Component permissions can also be applied to the `root` config.
+
+## Toggling features dynamically
+
+Dynamic permissions enable runtime calculation of permissions based on the component data, enabling instance-specific permissions. This is controlled by the [`resolvePermissions` parameter](/docs/api-reference/configuration/component-config#resolvepermissionsdata-params) on the component config.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      resolvePermissions: (data, { permissions }) => {
+        if (data.props.locked) {
+          return {
+            delete: false, // Disable delete function when HeadingBlock `locked` prop is set
+          };
+        }
+
+        return permissions; // Return inherited permissions (component or global)
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Asynchronous feature toggling
+
+Permissions can be resolved asynchronously, enabling powerful patterns like querying permissions from an endpoint whenever the data changes.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      resolvePermissions: async (data) => {
+        const serverPermissions = await myPermissionsApi(data.props.id); // Query permissions from a server
+
+        return serverPermissions;
+      },
+      // ...
+    },
+  },
+};
+```
+
+### Preventing duplicate calls
+
+Permission resolvers are cached based on the component props. If none of the props change, then the resolver won't be called. This prevents duplicate calls to expensive asynchronous operations.
+
+However, it's possible that you may want to avoid making an expensive operation unless a _specific_ prop has changed, rather than any prop.
+
+This can be restricted by checking the [`changed` param](/docs/api-reference/configuration/component-config#paramschanged-2) before calling any expensive operations.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      // ...
+      resolvePermissions: async (data, { changed, lastPermissions }) => {
+        if (!changed.locked) return lastPermissions; // Return last permissions if `locked` hasn't changed
+
+        return await myExpensivePermissionsApi(data),
+      },
+      // ...
+    },
+  },
+};
+```
+
+## Further reading
+
+- [Permissions API reference](/docs/api-reference/permissions)
+- [Supported permissions reference](/docs/api-reference/permissions#supported-permissions)
+- [Global `permissions` prop API reference](/docs/api-reference/components/puck#permissions)
+- [Component `permissions` param API reference](/docs/api-reference/configuration/component-config#permissions)
+- [Component `resolvePermissions` param API reference](/docs/api-reference/configuration/component-config#resolvepermissionsdata-params)

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

@@ -0,0 +1,228 @@
+# Localization
+
+Puck's default UI uses US English. Use the [`dictionary`](/docs/api-reference/dictionary) prop to translate or reword Puck-owned strings.
+
+See the [Dictionary API reference](/docs/api-reference/dictionary) for the full list of strings and their defaults.
+
+## Translating Puck strings
+
+To translate strings, provide a dictionary object with the keys you want to change and their corresponding translations.
+
+```tsx
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  return (
+    <Puck
+      dictionary={{
+        "header-publish": "Publicar", // "Publish" button
+        "field-richtext-bold": "Negrita", // "Bold" rich text control
+        "viewport-switch": "Cambiar a {label}", // Viewport tooltip
+      }}
+      config={config}
+      data={data}
+    />
+  );
+}
+```
+
+## Switching languages at runtime
+
+Puck reacts to any changes in the `dictionary` prop, so you can swap the object at runtime to change the language of the UI.
+
+```tsx
+import { useState } from "react";
+import { Puck } from "@puckeditor/core";
+
+const dictionaries = {
+  en: {},
+  es: { "header-publish": "Publicar" },
+};
+
+export function Editor() {
+  const [locale, setLocale] = useState<"en" | "es">("en");
+
+  return (
+    <>
+      <button onClick={() => setLocale(locale === "en" ? "es" : "en")}>
+        Toggle language
+      </button>
+      <Puck dictionary={dictionaries[locale]} config={config} data={data} />
+    </>
+  );
+}
+```
+
+If you already use a library like [`react-i18next`](https://react.i18next.com/) or [`next-intl`](https://next-intl.dev/), resolve your strings into a plain object and feed that object into `dictionary`.
+
+```tsx
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+
+export function Editor() {
+  const { t } = useTranslation();
+
+  const dictionary = useMemo(
+    () => ({
+      "header-publish": t("header-publish"),
+      "field-richtext-bold": t("field-richtext-bold"),
+    }),
+    [t]
+  );
+
+  return <Puck dictionary={dictionary} config={config} data={data} />;
+}
+```
+
+## Translating user-defined labels
+
+The dictionary only covers strings owned by the editor. Labels defined by your app should be translated where they are configured:
+
+- Custom plugin labels via the plugin [`label`](/docs/api-reference/plugin#label)
+- Viewport labels via the [`viewports.label`](/docs/api-reference/components/puck#label) prop
+- Component labels, root label, category titles and field labels via the [`config`](/docs/api-reference/components/puck#config) prop
+
+### Plugins
+
+Your own plugins define their own [`label`](/docs/api-reference/plugin#label); translate it before passing the plugin to Puck.
+
+```tsx
+import { useMemo } from "react";
+import { Puck } from "@puckeditor/core";
+
+export function Editor({ locale }) {
+  const labels = translations[locale];
+
+  const plugins = useMemo(
+    () => [
+      {
+        name: "my-plugin",
+        icon: <SomeIcon />,
+        label: labels.plugins.myPlugin,
+        render: () => <MyPanel />,
+      },
+    ],
+    [labels]
+  );
+
+  return <Puck config={config} data={data} plugins={plugins} />;
+}
+```
+
+### Viewports
+
+Viewport names are labels in the [`viewports`](/docs/api-reference/components/puck#viewports) prop.
+
+```tsx
+import { useMemo } from "react";
+import { Puck, type Viewports } from "@puckeditor/core";
+
+export function Editor({ locale }) {
+  const labels = translations[locale];
+
+  const viewports: Viewports = useMemo(
+    () => [
+      { width: 360, icon: "Smartphone", label: labels.viewports.small },
+      { width: 768, icon: "Tablet", label: labels.viewports.medium },
+      { width: 1280, icon: "Monitor", label: labels.viewports.large },
+    ],
+    [labels]
+  );
+
+  return <Puck config={config} data={data} viewports={viewports} />;
+}
+```
+
+### Config
+
+Component labels, root label, category titles and field labels come from your [`config`](/docs/api-reference/components/puck#config) prop. Update the config when the locale changes, in the same way you update the dictionary.
+
+```tsx
+import { useMemo } from "react";
+import { Puck } from "@puckeditor/core";
+
+export function Editor() {
+  const labels = translations["en"];
+
+  const localizedConfig = useMemo(
+    () => {
+      components: {
+        HeadingBlock: {
+          label: labels.components.HeadingBlock,
+          fields: {
+            title: { label: labels.fields.title },
+          },
+          render: (props) => <h1>{props.title}</h1>,
+        },
+      }
+    },
+    [labels]
+  );
+
+  return <Puck config={localizedConfig} data={data} />;
+}
+```
+
+## Interpolating values
+
+Some messages have dynamic values that can be interpolated into the string.
+
+Use `{key}` in the string to interpolate a value supplied by Puck.
+
+```tsx
+// Interpolates the viewport `label` value into the string.
+<Puck dictionary={{ "viewport-switch": "Cambiar a {label}" }} />
+```
+
+See the [Dictionary API reference](/docs/api-reference/dictionary) for the full list of strings that support interpolation and their corresponding keys.
+
+## Hiding a string
+
+Set a key to an empty string to render nothing for that message.
+
+```tsx
+// Hides the page label entirely.
+<Puck dictionary={{ "label-page": "" }} />
+```
+
+## Custom strings
+
+Puck supports adding your own keys to the dictionary to use them through the [internal Puck API](/docs/api-reference/puck-api#dictionary).
+
+```tsx
+import { Puck, createUsePuck } from "@puckeditor/core";
+
+const usePuck = createUsePuck();
+
+const HeaderActions = ({ children }) => {
+  const savedMsg = usePuck((s) => s.dictionary["saved-state"]);
+
+  return (
+    <div>
+      <span>{savedMsg}</span>
+      {children}
+    </div>
+  );
+};
+
+export function Editor() {
+  return (
+    <Puck
+      dictionary={{ "saved-state": "Saved" }}
+      overrides={{
+        fieldTypes: {
+          headerActions: { render: HeaderActions },
+        },
+      }}
+      config={config}
+      data={data}
+    />
+  );
+}
+```
+
+## Further reading
+
+- [`Dictionary` API reference](/docs/api-reference/dictionary)
+- [`dictionary` prop](/docs/api-reference/components/puck#dictionary)
+- [`PuckApi.dictionary`](/docs/api-reference/puck-api#dictionary)

package/dist/docs/integrating-puck/multi-column-layouts.md

@@ -0,0 +1,226 @@
+# Multi-column Layouts
+
+Puck supports nested and multi-column layouts across any CSS layout using the [`slot` field](/docs/api-reference/fields/slot).
+
+Slots replace the [`<DropZone>` component](/docs/api-reference/components/drop-zone) component, which will soon be deprecated and removed. For migration notes, see [these docs](/docs/guides/migrations/dropzones-to-slots).
+
+## Nested components
+
+Add the [`slot`](/docs/api-reference/fields/slot) field to your component to create a zone that you can drop components into.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      render: ({ content: Content }) => {
+        return <Content />;
+      },
+    },
+    Card: {
+      render: () => <div>Hello, world</div>,
+    },
+  },
+};
+```
+
+## Fixed layouts
+
+Combine multiple DropZones to achieve fixed layouts. By default, components inside a DropZone are arranged along the vertical (`block`) axis.
+
+```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>,
+    },
+  },
+};
+```
+
+## Fluid layouts
+
+Apply the [CSS display](https://developer.mozilla.org/en-US/docs/Web/CSS/display) property to a slot via the [`style`](/docs/api-reference/components/drop-zone#style) or [`className`](/docs/api-reference/components/drop-zone#className) props to arrange your components in different layouts. Puck supports drag-and-drop for all `display` values, including `grid` and `flex`.
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      render: ({ content: Content }) => (
+        <Content
+          style={{
+            // Use CSS grid in this slot
+            display: "grid",
+            gridTemplateColumns: "2fr 1fr",
+            gap: 16,
+          }}
+        />
+      ),
+    },
+    Card: {
+      render: ({ text }) => <div>{text}</div>,
+    },
+  },
+};
+```
+
+## Removing the wrapper
+
+By default, Puck will wrap your components in a `div` element. For some layouts, you may need to eliminate the wrapping element and treat the child component as a direct descendant of its' parent slot.
+
+For example, this is required if you wish to use CSS rules like `flex-grow`, `grid-column`, or `grid-row`.
+
+Use the [`inline`](/docs/api-reference/configuration/component-config#inline) component parameter to remove the wrapping element. **When using this API, you must also specify which element is draggable by passing the [`puck.dragRef` prop](/docs/api-reference/configuration/component-config#puckdragref) to your element's `ref` prop.**
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      render: ({ content: Content }) => (
+        <Content
+          style={{
+            display: "grid",
+            gridTemplateColumns: "1fr 1fr 1fr 1fr",
+            gridTemplateRows: "1fr 1fr 1fr 1fr",
+            gap: 16,
+          }}
+        />
+      ),
+    },
+    Card: {
+      inline: true, // Enable inline mode, removing the Puck wrapper
+      render: ({ text, spanCol, spanRow, puck }) => (
+        <div
+          ref={puck.dragRef} // Let Puck know this element is draggable
+          style={{
+            gridColumn: `span ${spanCol}`,
+            gridRow: `span ${spanRow}`,
+          }}
+        >
+          {text}
+        </div>
+      ),
+    },
+  },
+};
+```
+
+## Restricting components
+
+Use the [`allow`](/docs/api-reference/fields/slot#allow) and [`disallow`](/docs/api-reference/fields/slot#disallow) parameters to restrict which components can be dragged into a slot.
+
+```tsx
+const config = {
+  components: {
+    fields: {
+      content: {
+        type: "slot",
+        allow: ["Card"],
+      },
+    },
+    Example: {
+      render: ({ content: Content }) => {
+        return <Content />;
+      },
+    },
+  },
+};
+```
+
+Combine this with [categories](/docs/integrating-puck/categories) to restrict behavior based on your existing groups.
+
+```tsx
+const config = {
+  categories: {
+    typography: {
+      components: ["Card"],
+    },
+  },
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+          allow: categories.typography.components,
+        },
+      },
+      render: ({ content: Content }) => {
+        return <Content />;
+      },
+    },
+  },
+};
+```
+
+Alternatively, you can provide `allow` and `disallow` [to your render function](/docs/api-reference/fields/slot#allow-1).
+
+## Setting default props
+
+Use slots with [`defaultProps`](/docs/api-reference/configuration/component-config#defaultprops) to pre-populate it when the component is inserted with an array of [`ComponentData`](/docs/api-reference/data-model/component-data).
+
+```tsx
+const config = {
+  components: {
+    Example: {
+      fields: {
+        content: {
+          type: "slot",
+        },
+      },
+      defaultProps: {
+        content: [
+          {
+            type: "Card",
+            props: {
+              text: "Pre-populated",
+            },
+          },
+        ],
+      },
+      render: ({ content: Content }) => <Content />,
+    },
+    Card: {
+      render: ({ text }) => <div>{text}</div>,
+    },
+  },
+};
+```
+
+## Further reading
+
+- [The `slot` field API](/docs/api-reference/fields/slot)
+- [The `inline` component config](/docs/api-reference/configuration/component-config#inline)

package/dist/docs/integrating-puck/overlay-portals.md

@@ -0,0 +1,25 @@
+# Overlay Portals
+
+Overlay Portals enable you to disable the Puck overlay when hovering over specific elements, making them interactive in the editor.
+
+Use the [`registerOverlayPortal` API](/docs/api-reference/functions/register-overlay-portal) to mark an element as a portal.
+
+```tsx
+import { registerOverlayPortal } from "@puckeditor/core";
+
+const Example = () => {
+  const ref = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => registerOverlayPortal(ref.current), [ref.current]);
+
+  return (
+    <button ref={ref} onClick={() => alert("Click")}>
+      Clickable
+    </button>
+  );
+};
+```
+
+Portals can be used to create interactive functionality for previewing, such as to paginate through tabs, or combined with [`usePuck()`](/docs/extending-puck/internal-puck-api) to create an inline form input.
+
+## Example: Tabs