@puckeditor/plugin-heading-analyzer 0.23.0-canary.fb9392de → 0.24.0-canary.03e660bb

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/dist/index.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" | "fieldTransforms";
+/**
+ * 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;
@@ -216,6 +272,10 @@ interface RadioField extends BaseField {
     type: "radio";
     options: FieldOptions;
 }
+interface CheckboxField extends BaseField {
+    type: "checkbox";
+    options: FieldOptions;
+}
 interface RichtextField<UserSelector extends RichTextSelector = RichTextSelector> extends BaseField {
     type: "richtext";
     contentEditable?: boolean;
@@ -258,6 +318,7 @@ interface ObjectField<Props extends any = {
     [key: string]: any;
 }, UserField extends {} = {}> extends BaseField {
     type: "object";
+    expandable?: boolean;
     objectFields: {
         [SubPropName in keyof Props]: UserField extends {
             type: PropertyKey;
@@ -322,7 +383,7 @@ interface SlotField extends BaseField {
     allow?: string[];
     disallow?: string[];
 }
-type Field<ValueType = any, UserField extends {} = {}> = TextField | RichtextField | NumberField | TextareaField | SelectField | RadioField | ArrayField<ValueType extends {
+type Field<ValueType = any, UserField extends {} = {}> = TextField | RichtextField | NumberField | TextareaField | SelectField | RadioField | CheckboxField | ArrayField<ValueType extends {
     [key: string]: any;
 }[] ? ValueType : never, UserField> | ObjectField<ValueType, UserField> | ExternalField<ValueType> | ExternalFieldWithAdaptor<ValueType> | CustomField<ValueType> | SlotField;
 type Fields<ComponentProps extends DefaultComponentProps = DefaultComponentProps, UserField extends {} = {}> = {
@@ -338,20 +399,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;
@@ -359,6 +411,12 @@ type PuckContext = {
 type DefaultRootFieldProps = {
     title?: string;
 };
+/**
+ * Merge the default root field props into user-provided root props, letting
+ * the user's props take precedence. Using a plain intersection would turn an
+ * overridden `title` (e.g. `number`) into `never` (`number & string`).
+ */
+type WithDefaultRootFieldProps<RootProps> = RootProps & Omit<DefaultRootFieldProps, keyof RootProps>;
 type DefaultComponentProps = {
     [key: string]: any;
 };
@@ -378,7 +436,7 @@ type UserGenerics<UserConfig extends Config = Config, UserParams extends Extract
     UserConfig: UserConfig;
     UserParams: UserParams;
     UserProps: UserParams["props"];
-    UserRootProps: UserParams["rootProps"] & DefaultRootFieldProps;
+    UserRootProps: WithDefaultRootFieldProps<UserParams["rootProps"]>;
     UserData: UserData;
     UserAppState: UserAppState;
     UserPublicAppState: UserPublicAppState;
@@ -391,7 +449,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;
@@ -407,6 +465,9 @@ UserField extends BaseField = {}> = {
     label?: string;
     defaultProps?: FieldProps;
     fields?: Fields<FieldProps, UserField>;
+    renderFields?: RenderFunc<{
+        fields: Partial<Record<keyof FieldProps, ReactNode>>;
+    }>;
     permissions?: Partial<Permissions>;
     inline?: boolean;
     resolveFields?: (data: DataShape, params: {
@@ -462,7 +523,7 @@ type DefaultComponents = Record<string, any>;
 type Config<PropsOrParams extends LeftOrExactRight<PropsOrParams, DefaultComponents, ConfigParams> = DefaultComponents | ConfigParams, RootProps extends DefaultComponentProps = any, CategoryName extends string = string> = PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, never> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number]> : PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, infer ParamFields> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number], ParamFields[keyof ParamFields] & BaseField> : PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, any> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number], {}> : ConfigInternal<PropsOrParams, RootProps, CategoryName>;
 type ExtractConfigParams<UserConfig extends ConfigInternal> = UserConfig extends ConfigInternal<infer PropsOrParams, infer RootProps, infer CategoryName, infer UserField> ? {
     props: PropsOrParams;
-    rootProps: RootProps & DefaultRootFieldProps;
+    rootProps: WithDefaultRootFieldProps<RootProps>;
     categoryNames: CategoryName;
     field: UserField extends {
         type: string;
@@ -545,6 +606,8 @@ type UiState = {
         expanded?: boolean;
     }>;
     isDragging: boolean;
+    /** Outline items whose children are shown, keyed by item id */
+    itemExpanded?: Record<string, boolean>;
     viewports: {
         current: {
             width: number | "100%";
@@ -553,6 +616,7 @@ type UiState = {
         controlsVisible: boolean;
         options: Viewport[];
     };
+    expandedFieldGroups: Record<string, boolean>;
     field: {
         focus?: string | null;
         metadata?: Record<string, any>;
@@ -655,10 +719,12 @@ type Overrides<UserConfig extends Config = Config> = OverridesGeneric<{
         children: ReactNode;
         isLoading: boolean;
         itemSelector?: ItemSelector | null;
+        fields: Partial<Record<string, ReactNode>>;
     }>;
     fieldLabel: RenderFunc<{
         children?: ReactNode;
         icon?: ReactNode;
+        endIcon?: ReactNode;
         label: string;
         el?: "label" | "div";
         readOnly?: boolean;
@@ -690,12 +756,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 DragAxis = "dynamic" | "y" | "x";
 

package/dist/index.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" | "fieldTransforms";
+/**
+ * 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;
@@ -216,6 +272,10 @@ interface RadioField extends BaseField {
     type: "radio";
     options: FieldOptions;
 }
+interface CheckboxField extends BaseField {
+    type: "checkbox";
+    options: FieldOptions;
+}
 interface RichtextField<UserSelector extends RichTextSelector = RichTextSelector> extends BaseField {
     type: "richtext";
     contentEditable?: boolean;
@@ -258,6 +318,7 @@ interface ObjectField<Props extends any = {
     [key: string]: any;
 }, UserField extends {} = {}> extends BaseField {
     type: "object";
+    expandable?: boolean;
     objectFields: {
         [SubPropName in keyof Props]: UserField extends {
             type: PropertyKey;
@@ -322,7 +383,7 @@ interface SlotField extends BaseField {
     allow?: string[];
     disallow?: string[];
 }
-type Field<ValueType = any, UserField extends {} = {}> = TextField | RichtextField | NumberField | TextareaField | SelectField | RadioField | ArrayField<ValueType extends {
+type Field<ValueType = any, UserField extends {} = {}> = TextField | RichtextField | NumberField | TextareaField | SelectField | RadioField | CheckboxField | ArrayField<ValueType extends {
     [key: string]: any;
 }[] ? ValueType : never, UserField> | ObjectField<ValueType, UserField> | ExternalField<ValueType> | ExternalFieldWithAdaptor<ValueType> | CustomField<ValueType> | SlotField;
 type Fields<ComponentProps extends DefaultComponentProps = DefaultComponentProps, UserField extends {} = {}> = {
@@ -338,20 +399,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;
@@ -359,6 +411,12 @@ type PuckContext = {
 type DefaultRootFieldProps = {
     title?: string;
 };
+/**
+ * Merge the default root field props into user-provided root props, letting
+ * the user's props take precedence. Using a plain intersection would turn an
+ * overridden `title` (e.g. `number`) into `never` (`number & string`).
+ */
+type WithDefaultRootFieldProps<RootProps> = RootProps & Omit<DefaultRootFieldProps, keyof RootProps>;
 type DefaultComponentProps = {
     [key: string]: any;
 };
@@ -378,7 +436,7 @@ type UserGenerics<UserConfig extends Config = Config, UserParams extends Extract
     UserConfig: UserConfig;
     UserParams: UserParams;
     UserProps: UserParams["props"];
-    UserRootProps: UserParams["rootProps"] & DefaultRootFieldProps;
+    UserRootProps: WithDefaultRootFieldProps<UserParams["rootProps"]>;
     UserData: UserData;
     UserAppState: UserAppState;
     UserPublicAppState: UserPublicAppState;
@@ -391,7 +449,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;
@@ -407,6 +465,9 @@ UserField extends BaseField = {}> = {
     label?: string;
     defaultProps?: FieldProps;
     fields?: Fields<FieldProps, UserField>;
+    renderFields?: RenderFunc<{
+        fields: Partial<Record<keyof FieldProps, ReactNode>>;
+    }>;
     permissions?: Partial<Permissions>;
     inline?: boolean;
     resolveFields?: (data: DataShape, params: {
@@ -462,7 +523,7 @@ type DefaultComponents = Record<string, any>;
 type Config<PropsOrParams extends LeftOrExactRight<PropsOrParams, DefaultComponents, ConfigParams> = DefaultComponents | ConfigParams, RootProps extends DefaultComponentProps = any, CategoryName extends string = string> = PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, never> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number]> : PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, infer ParamFields> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number], ParamFields[keyof ParamFields] & BaseField> : PropsOrParams extends ConfigParams<infer ParamComponents, infer ParamRoot, infer ParamCategoryName, any> ? ConfigInternal<ParamComponents, ParamRoot, ParamCategoryName[number], {}> : ConfigInternal<PropsOrParams, RootProps, CategoryName>;
 type ExtractConfigParams<UserConfig extends ConfigInternal> = UserConfig extends ConfigInternal<infer PropsOrParams, infer RootProps, infer CategoryName, infer UserField> ? {
     props: PropsOrParams;
-    rootProps: RootProps & DefaultRootFieldProps;
+    rootProps: WithDefaultRootFieldProps<RootProps>;
     categoryNames: CategoryName;
     field: UserField extends {
         type: string;
@@ -545,6 +606,8 @@ type UiState = {
         expanded?: boolean;
     }>;
     isDragging: boolean;
+    /** Outline items whose children are shown, keyed by item id */
+    itemExpanded?: Record<string, boolean>;
     viewports: {
         current: {
             width: number | "100%";
@@ -553,6 +616,7 @@ type UiState = {
         controlsVisible: boolean;
         options: Viewport[];
     };
+    expandedFieldGroups: Record<string, boolean>;
     field: {
         focus?: string | null;
         metadata?: Record<string, any>;
@@ -655,10 +719,12 @@ type Overrides<UserConfig extends Config = Config> = OverridesGeneric<{
         children: ReactNode;
         isLoading: boolean;
         itemSelector?: ItemSelector | null;
+        fields: Partial<Record<string, ReactNode>>;
     }>;
     fieldLabel: RenderFunc<{
         children?: ReactNode;
         icon?: ReactNode;
+        endIcon?: ReactNode;
         label: string;
         el?: "label" | "div";
         readOnly?: boolean;
@@ -690,12 +756,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 DragAxis = "dynamic" | "y" | "x";