@puckeditor/core 0.23.0 → 0.24.0-canary.301a0304

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) The Puck Contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -82,6 +82,34 @@ export function Page() {
 }
 ```
 
+## CLI
+
+Set up Puck and Puck Cloud in a new or existing Next.js, React Router, TanStack Start, vinext, Vite or Astro app, or a Hono or Express server. Built for coding agents, friendly for humans:
+
+```sh
+npx @puckeditor/cli init
+```
+
+See the [CLI docs](https://puckeditor.com/docs/cli) for agent usage.
+
+## For agents
+
+Puck is built to be set up and used by coding agents as well as people. The CLI sets up Puck without prompting, and ships with the docs for its release, so agents can read the docs for the version a project uses:
+
+```sh
+npx @puckeditor/cli init --yes --json
+npx @puckeditor/cli docs find "dynamic fields"
+npx @puckeditor/cli docs cat api-reference/fields/text
+```
+
+Agents with skill support can install the [Puck skill](https://github.com/puckeditor/skills):
+
+```sh
+npx skills add puckeditor/skills --skill puck
+```
+
+The latest docs are indexed at [llms.txt](https://puckeditor.com/llms.txt), and any page is available as markdown by adding `.md` to its URL.
+
 ## Recipes
 
 Use `create-puck-app` to quickly spin up a a pre-configured app based on our provided [recipes](https://github.com/puckeditor/puck/tree/main/recipes):
@@ -94,6 +122,11 @@ Available recipes include:
 
 - [**next**](https://github.com/puckeditor/puck/tree/main/recipes/next): Next.js example, using App Router and static page generation
 - [**react-router**](https://github.com/puckeditor/puck/tree/main/recipes/react-router): React Router v7 app example, using dynamic routes to create pages at any level
+- [**tanstack-start**](https://github.com/puckeditor/puck/tree/main/recipes/tanstack-start): [TanStack Start](https://tanstack.com/start) example, using a splat route and server functions to create pages at any level
+- [**hono**](https://github.com/puckeditor/puck/tree/main/recipes/hono) and [**express**](https://github.com/puckeditor/puck/tree/main/recipes/express): Hono and Express servers exposing a pages API, and Puck AI in the `-ai` variants, for an editor in another app
+- [**astro**](https://github.com/puckeditor/puck/tree/main/recipes/astro): Astro example, rendering Puck pages on the server with the Node adapter
+- [**vite**](https://github.com/puckeditor/puck/tree/main/recipes/vite): Vite React app example, with a small Hono server for pages
+- [**vinext**](https://github.com/puckeditor/puck/tree/main/recipes/vinext): [vinext](https://github.com/cloudflare/vinext) example, running the Next.js App Router on Vite
 
 ## Community
 

package/dist/{Editor-44C53YAG.mjs → Editor-IOB6CBHE.mjs}

@@ -4,19 +4,19 @@ import {
 import {
   EditorInner,
   LoadedRichTextMenu
-} from "./chunk-WF6I3XOL.mjs";
+} from "./chunk-3CZRCHCU.mjs";
 import "./chunk-H635BA2V.mjs";
-import "./chunk-GNR2HNTB.mjs";
-import "./chunk-67Y7M4OJ.mjs";
-import "./chunk-4P4VZS4P.mjs";
-import "./chunk-NJTGWYYH.mjs";
+import "./chunk-3OECBDNE.mjs";
+import "./chunk-6MVGICFW.mjs";
+import "./chunk-3YSLTDRT.mjs";
+import "./chunk-3USGHYFG.mjs";
 import {
   useAppStore,
   useAppStoreApi
-} from "./chunk-K2LNXU54.mjs";
+} from "./chunk-MVHLONPE.mjs";
 import "./chunk-Z2MS6UIF.mjs";
 import "./chunk-ZRAERXB4.mjs";
-import "./chunk-Y2EFNT5P.mjs";
+import "./chunk-OT7NKYY4.mjs";
 import "./chunk-H65MT2JK.mjs";
 import {
   __spreadProps,

package/dist/{Render-DQXAYUBI.mjs → Render-KIF7JWS4.mjs}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-H635BA2V.mjs";
 import {
   get_class_name_factory_default
-} from "./chunk-Y2EFNT5P.mjs";
+} from "./chunk-OT7NKYY4.mjs";
 import {
   init_react_import
 } from "./chunk-M6W7YEVX.mjs";

package/dist/{actions-DA1J5F56.d.mts → actions-DzP_zhsF.d.mts}

@@ -1,4 +1,4 @@
-import { ReactElement, CSSProperties, ReactNode, ElementType, Ref, JSX } from 'react';
+import { ElementType, CSSProperties, Ref, ComponentPropsWithoutRef, ReactElement, ReactNode, JSX } from 'react';
 import { EditorStateSnapshot, Editor, Extensions } from '@tiptap/react';
 import { BlockquoteOptions } from '@tiptap/extension-blockquote';
 import { BoldOptions } from '@tiptap/extension-bold';
@@ -20,6 +20,62 @@ type ItemSelector = {
     zone?: string;
 };
 
+/**
+ * Props consumed by Puck internally that are shared between DropZones and slots.
+ */
+type DropZoneSharedProps<ComponentType extends ElementType = "div"> = {
+    allow?: string[];
+    disallow?: string[];
+    style?: CSSProperties;
+    minEmptyHeight?: CSSProperties["minHeight"] | number;
+    className?: string;
+    collisionAxis?: DragAxis;
+    ref?: Ref<any>;
+    as?: ComponentType;
+};
+/**
+ * All props consumed by Puck for a DropZone component. `zone` lives here only.
+ *
+ * On slots `zone` is injected internally, so slots use {@link SlotProps} instead.
+ */
+type DropZoneOwnProps<ComponentType extends ElementType = "div"> = DropZoneSharedProps<ComponentType> & {
+    zone: string;
+};
+/**
+ * Unsupported additional props that are never forwarded to `as`.
+ *
+ * Omitted from the public types AND stripped at runtime.
+ */
+type NonForwardableProps = {
+    children?: unknown;
+    dangerouslySetInnerHTML?: unknown;
+};
+/**
+ * Keys internally consumed by Puck and never forwarded to `as`.
+ */
+type ConsumedPropKey = keyof DropZoneOwnProps | "as" | "content" | "config" | "metadata";
+/**
+ * Additional props forwarded to the element or component provided via `as`,
+ * typed against it.
+ *
+ * Puck-internal/unsupported props are stripped so they don't leak onto the DOM.
+ */
+type ForwardedProps<ComponentType extends ElementType> = Omit<ComponentPropsWithoutRef<ComponentType>, ConsumedPropKey | keyof NonForwardableProps>;
+/**
+ * Props for a `DropZone` component.
+ *
+ * Any additional props not consumed by Puck are forwarded to the element or
+ * component provided via `as` (defaulting to a `div`), typed against it.
+ */
+type DropZoneProps<ComponentType extends ElementType = "div"> = DropZoneOwnProps<ComponentType> & ForwardedProps<ComponentType>;
+/**
+ * Props for a `slot` render component.
+ *
+ * Any additional props not consumed by Puck are forwarded to the element or
+ * component provided via `as` (defaulting to a `div`), typed against it.
+ */
+type SlotProps<ComponentType extends ElementType = "div"> = DropZoneSharedProps<ComponentType> & ForwardedProps<ComponentType>;
+
 declare const defaultEditorState: (ctx: EditorStateSnapshot, readOnly: boolean) => {
     isAlignLeft?: undefined;
     canAlignLeft?: undefined;
@@ -338,20 +394,11 @@ type FieldProps<F = Field<any>, ValueType = any> = {
     readOnly?: boolean;
 };
 
-type DropZoneProps = {
-    zone: string;
-    allow?: string[];
-    disallow?: string[];
-    style?: CSSProperties;
-    minEmptyHeight?: CSSProperties["minHeight"] | number;
-    className?: string;
-    collisionAxis?: DragAxis;
-    as?: ElementType;
-    ref?: Ref<any>;
-};
-
 type PuckContext = {
-    renderDropZone: (props: DropZoneProps) => React.ReactNode;
+    /**
+     * @deprecated Use {@link https://puckeditor.com/docs/api-reference/fields/slot Slots} instead.
+     */
+    renderDropZone: <ComponentType extends ElementType = "div">(props: DropZoneProps<ComponentType>) => React.ReactNode;
     metadata: Metadata;
     isEditing: boolean;
     dragRef: ((element: Element | null) => void) | null;
@@ -399,7 +446,7 @@ type ExtractField<UserField extends {
     type: T;
 }>;
 
-type SlotComponent = (props?: Omit<DropZoneProps, "zone">) => ReactNode;
+type SlotComponent = <ComponentType extends ElementType = "div">(props?: SlotProps<ComponentType>) => ReactNode;
 type PuckComponent<Props> = (props: WithId<WithPuckProps<{
     [K in keyof Props]: WithDeepSlots<Props[K], SlotComponent>;
 }>>) => JSX.Element;
@@ -713,12 +760,12 @@ type Overrides<UserConfig extends Config = Config> = OverridesGeneric<{
 }>;
 type FieldRenderFunctions<UserConfig extends Config = Config, G extends UserGenerics<UserConfig> = UserGenerics<UserConfig>, UserField extends {
     type: string;
-} = Field | G["UserField"]> = Omit<{
+} = Field | G["UserField"]> = {
     [Type in UserField["type"]]: React.FunctionComponent<FieldProps<ExtractField<UserField, Type>, any> & {
         children: ReactNode;
         name: string;
-    }>;
-}, "custom">;
+    }> | null;
+};
 
 type Direction = "left" | "right" | "up" | "down" | null;
 type DragAxis = "dynamic" | "y" | "x";

package/dist/{actions-DA1J5F56.d.ts → actions-DzP_zhsF.d.ts}

@@ -1,4 +1,4 @@
-import { ReactElement, CSSProperties, ReactNode, ElementType, Ref, JSX } from 'react';
+import { ElementType, CSSProperties, Ref, ComponentPropsWithoutRef, ReactElement, ReactNode, JSX } from 'react';
 import { EditorStateSnapshot, Editor, Extensions } from '@tiptap/react';
 import { BlockquoteOptions } from '@tiptap/extension-blockquote';
 import { BoldOptions } from '@tiptap/extension-bold';
@@ -20,6 +20,62 @@ type ItemSelector = {
     zone?: string;
 };
 
+/**
+ * Props consumed by Puck internally that are shared between DropZones and slots.
+ */
+type DropZoneSharedProps<ComponentType extends ElementType = "div"> = {
+    allow?: string[];
+    disallow?: string[];
+    style?: CSSProperties;
+    minEmptyHeight?: CSSProperties["minHeight"] | number;
+    className?: string;
+    collisionAxis?: DragAxis;
+    ref?: Ref<any>;
+    as?: ComponentType;
+};
+/**
+ * All props consumed by Puck for a DropZone component. `zone` lives here only.
+ *
+ * On slots `zone` is injected internally, so slots use {@link SlotProps} instead.
+ */
+type DropZoneOwnProps<ComponentType extends ElementType = "div"> = DropZoneSharedProps<ComponentType> & {
+    zone: string;
+};
+/**
+ * Unsupported additional props that are never forwarded to `as`.
+ *
+ * Omitted from the public types AND stripped at runtime.
+ */
+type NonForwardableProps = {
+    children?: unknown;
+    dangerouslySetInnerHTML?: unknown;
+};
+/**
+ * Keys internally consumed by Puck and never forwarded to `as`.
+ */
+type ConsumedPropKey = keyof DropZoneOwnProps | "as" | "content" | "config" | "metadata";
+/**
+ * Additional props forwarded to the element or component provided via `as`,
+ * typed against it.
+ *
+ * Puck-internal/unsupported props are stripped so they don't leak onto the DOM.
+ */
+type ForwardedProps<ComponentType extends ElementType> = Omit<ComponentPropsWithoutRef<ComponentType>, ConsumedPropKey | keyof NonForwardableProps>;
+/**
+ * Props for a `DropZone` component.
+ *
+ * Any additional props not consumed by Puck are forwarded to the element or
+ * component provided via `as` (defaulting to a `div`), typed against it.
+ */
+type DropZoneProps<ComponentType extends ElementType = "div"> = DropZoneOwnProps<ComponentType> & ForwardedProps<ComponentType>;
+/**
+ * Props for a `slot` render component.
+ *
+ * Any additional props not consumed by Puck are forwarded to the element or
+ * component provided via `as` (defaulting to a `div`), typed against it.
+ */
+type SlotProps<ComponentType extends ElementType = "div"> = DropZoneSharedProps<ComponentType> & ForwardedProps<ComponentType>;
+
 declare const defaultEditorState: (ctx: EditorStateSnapshot, readOnly: boolean) => {
     isAlignLeft?: undefined;
     canAlignLeft?: undefined;
@@ -338,20 +394,11 @@ type FieldProps<F = Field<any>, ValueType = any> = {
     readOnly?: boolean;
 };
 
-type DropZoneProps = {
-    zone: string;
-    allow?: string[];
-    disallow?: string[];
-    style?: CSSProperties;
-    minEmptyHeight?: CSSProperties["minHeight"] | number;
-    className?: string;
-    collisionAxis?: DragAxis;
-    as?: ElementType;
-    ref?: Ref<any>;
-};
-
 type PuckContext = {
-    renderDropZone: (props: DropZoneProps) => React.ReactNode;
+    /**
+     * @deprecated Use {@link https://puckeditor.com/docs/api-reference/fields/slot Slots} instead.
+     */
+    renderDropZone: <ComponentType extends ElementType = "div">(props: DropZoneProps<ComponentType>) => React.ReactNode;
     metadata: Metadata;
     isEditing: boolean;
     dragRef: ((element: Element | null) => void) | null;
@@ -399,7 +446,7 @@ type ExtractField<UserField extends {
     type: T;
 }>;
 
-type SlotComponent = (props?: Omit<DropZoneProps, "zone">) => ReactNode;
+type SlotComponent = <ComponentType extends ElementType = "div">(props?: SlotProps<ComponentType>) => ReactNode;
 type PuckComponent<Props> = (props: WithId<WithPuckProps<{
     [K in keyof Props]: WithDeepSlots<Props[K], SlotComponent>;
 }>>) => JSX.Element;
@@ -713,12 +760,12 @@ type Overrides<UserConfig extends Config = Config> = OverridesGeneric<{
 }>;
 type FieldRenderFunctions<UserConfig extends Config = Config, G extends UserGenerics<UserConfig> = UserGenerics<UserConfig>, UserField extends {
     type: string;
-} = Field | G["UserField"]> = Omit<{
+} = Field | G["UserField"]> = {
     [Type in UserField["type"]]: React.FunctionComponent<FieldProps<ExtractField<UserField, Type>, any> & {
         children: ReactNode;
         name: string;
-    }>;
-}, "custom">;
+    }> | null;
+};
 
 type Direction = "left" | "right" | "up" | "down" | null;
 type DragAxis = "dynamic" | "y" | "x";

package/dist/{chunk-WF6I3XOL.mjs → chunk-3CZRCHCU.mjs}

@@ -3,14 +3,14 @@ import {
 } from "./chunk-H635BA2V.mjs";
 import {
   LoadedRichTextMenuInner
-} from "./chunk-GNR2HNTB.mjs";
+} from "./chunk-3OECBDNE.mjs";
 import {
   useAppStore,
   useAppStoreApi
-} from "./chunk-K2LNXU54.mjs";
+} from "./chunk-MVHLONPE.mjs";
 import {
   get_class_name_factory_default
-} from "./chunk-Y2EFNT5P.mjs";
+} from "./chunk-OT7NKYY4.mjs";
 import {
   __spreadValues,
   init_react_import
@@ -100,7 +100,7 @@ init_react_import();
 import { lazy, Suspense } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 var LoadedRichTextMenuFull = lazy(
-  () => import("./full-7ZJV44EE.mjs").then((m) => ({
+  () => import("./full-G3HMYLKK.mjs").then((m) => ({
     default: m.LoadedRichTextMenuFull
   }))
 );

package/dist/{chunk-GNR2HNTB.mjs → chunk-3OECBDNE.mjs}

@@ -1,12 +1,12 @@
 import {
   useAlignOptions
-} from "./chunk-67Y7M4OJ.mjs";
+} from "./chunk-6MVGICFW.mjs";
 import {
   useHeadingOptions
-} from "./chunk-4P4VZS4P.mjs";
+} from "./chunk-3YSLTDRT.mjs";
 import {
   useListOptions
-} from "./chunk-NJTGWYYH.mjs";
+} from "./chunk-3USGHYFG.mjs";
 import {
   Action,
   AlignCenter,
@@ -29,10 +29,10 @@ import {
   Underline,
   useControlContext,
   useMessage
-} from "./chunk-K2LNXU54.mjs";
+} from "./chunk-MVHLONPE.mjs";
 import {
   get_class_name_factory_default
-} from "./chunk-Y2EFNT5P.mjs";
+} from "./chunk-OT7NKYY4.mjs";
 import {
   init_react_import
 } from "./chunk-M6W7YEVX.mjs";
@@ -204,7 +204,7 @@ function AlignSelectFallback() {
 // components/RichTextMenu/controls/AlignSelect/index.tsx
 import { jsx as jsx7 } from "react/jsx-runtime";
 var AlignSelectLoaded = lazy(
-  () => import("./loaded-SMPR6KZF.mjs").then((m) => ({
+  () => import("./loaded-O7MEOBEX.mjs").then((m) => ({
     default: m.AlignSelectLoaded
   }))
 );
@@ -445,7 +445,7 @@ function HeadingSelectFallback() {
 // components/RichTextMenu/controls/HeadingSelect/index.tsx
 import { jsx as jsx19 } from "react/jsx-runtime";
 var HeadingSelectLoaded = lazy2(
-  () => import("./loaded-JKA25A3T.mjs").then((m) => ({
+  () => import("./loaded-2R7Z7VD4.mjs").then((m) => ({
     default: m.HeadingSelectLoaded
   }))
 );
@@ -477,7 +477,7 @@ function ListSelectFallback() {
 // components/RichTextMenu/controls/ListSelect/index.tsx
 import { jsx as jsx21 } from "react/jsx-runtime";
 var ListSelectLoaded = lazy3(
-  () => import("./loaded-36WRJPBT.mjs").then((m) => ({
+  () => import("./loaded-4W6LSSFR.mjs").then((m) => ({
     default: m.ListSelectLoaded
   }))
 );

package/dist/{chunk-NJTGWYYH.mjs → chunk-3USGHYFG.mjs}

@@ -2,7 +2,7 @@ import {
   List,
   ListOrdered,
   useMessage
-} from "./chunk-K2LNXU54.mjs";
+} from "./chunk-MVHLONPE.mjs";
 import {
   init_react_import
 } from "./chunk-M6W7YEVX.mjs";