@contentful/experiences-visual-editor-react 1.5.0 → 1.5.1-beta.1

package/README.md

@@ -1,7 +1,23 @@
 # @contentful/experiences-visual-editor-react
 
-This package provides a visual editor for the [Experiences SDK](https://www.contentful.com/developers/docs/experiences/set-up-experiences-sdk/). It implements drag-and-drop functionality into the canvas, making the creation and editing of experiences more intuitive and user-friendly.
+### Purpose
+- Handles the canvas interaction logic with dragging, hitboxes, dropzones, reparenting, and communicating with the parent frame to ensure a smooth drag and drop experience.
+- Note that this package is framework specific to React.
 
-## Documentation
+### Concepts
+- **Structure components**: Represents components that pertain to the layout of a user's experience such as containers, sections, and columns.
+- **Built-in components**: Contentful-provided components on behalf of the user that are considered universally useful such as an image, text, and the divider component or to get a user quickly started such as a button. Note that these components are not meant to cover every possible component that the user may want to have. Instead users are generally expected to provide their own set of components to build their customized experiences. The exceptions will generally be based on how universally desired such components are, such as Cards or Carousel components in the future.
+- **Custom components**: User-provided components built through a definition provided by the Experiences SDK.
+- **Post messages**: In order for an iFrame to communicate with its parent frame, post messaging is required so that the two frames can communicate with each other. Examples of what information gets shared would be mouse coordinates or what component got picked up and dropped.
+- **Browser limitations**: Currently only Chrome supports both Click/Drag and Drop while Safari and Firefox only allows for Click and Drop.
+- **Trees**: Experiences store their own version of the tree that is separate from the source of truth which is stored as a Contentful entry. This is because by storing its own tree version it can provide UI optimizations and manipulations to the tree to maximize performance-related tasks such as when performing drag and drop or re-ordering of components. A concrete example where this optimization is necessary is when you drop a component onto the canvas. Without its own version, the component would flicker to its original pre-drag spot before being placed on the intended area based on the mouse's location. 
+- **Updating the source of truth**: On drag end, the iFrame will update its own tree before sending a post message to the parent frame in `useCanvasInteractions`. Then the parent frame will update its tree which is the source of truth before sending a post msg back in  `useEditorSubscriber` to the iFrame ensuring that both trees are the same and any discovered discrepancies are resolved.
+- **@hello-pangea/dnd**: Library providing HOC (higher order components) that Experiences leverages for Drag and Drop. The two components being used from this library is the `Droppable` and `Draggable` component.
+- **Dropzones**: Div wrappers that represent areas for other components to be dropped in. Note that only one can be activated at a time via a hitbox and is a separate div from `Draggables`.
+- **Draggables**: Div wrappers that allow component to be picked up and dropped. Note that this is a separate div from `Dropzones`.
+- **SimulateDnD**: Custom-built DND component which is needed as a visual trick for dragging a component from the sidebar onto the iFrame. Since the drag is initiated in the parent frame when clicking and dragging a new component, a simulated action in the iFrame is also triggered so the iFrame is in a drag state just like the parent frame. Then when the mouse crosses over from the parent frame into the iFrame, post messaging is required where the iFrame will send mouse coordinates to the parentFrame so that the dragged component icon is placed in the correct position while the iFrame will trigger the appropriate hitboxes and dropzones since all the hitboxes and dropzones live in the iFrame. 
+- **Component wrapper**: There are several types of div wrappers such as `Dropzones` and `Draggables`. However, there is a third wrapper that is provided as a custom boolean option with `Custom Components`. When this boolean is true, all style options selected from the UI will be applied to this wrapping div. This is done so that the user's CSS styles on their own components are preserved and shielded from the style options chosen in the UI. 
 
-Please refer to our [Documentation](https://www.contentful.com/developers/docs/experiences/) to learn more about it.
+
+### Relevant Contentful documentation links
+- [Contentful entry tree data structure](https://www.contentful.com/developers/docs/experiences/data-structures/)

package/dist/index.js

@@ -2,6 +2,7 @@ import styleInject from 'style-inject';
 import React, { useRef, useMemo, useEffect, useState, useLayoutEffect, forwardRef, useCallback } from 'react';
 import md5 from 'md5';
 import { BLOCKS } from '@contentful/rich-text-types';
+import { z } from 'zod';
 import { isEqual, get as get$1, omit } from 'lodash-es';
 import { Draggable, Droppable, DragDropContext } from '@hello-pangea/dnd';
 import classNames from 'classnames';
@@ -954,6 +955,236 @@ const resolveSimpleDesignToken = (templateString, variableName) => {
     return '0px';
 };
 
+// If more than one version is supported, use z.union
+const SchemaVersions = z.literal('2023-09-28');
+// Keep deprecated versions here just for reference
+z.union([
+    z.literal('2023-08-23'),
+    z.literal('2023-07-26'),
+    z.literal('2023-06-27'),
+]);
+
+const DefinitionPropertyTypeSchema = z.enum([
+    'Text',
+    'RichText',
+    'Number',
+    'Date',
+    'Boolean',
+    'Location',
+    'Media',
+    'Object',
+    'Hyperlink',
+]);
+const DefinitionPropertyKeySchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9-_]{1,32}$/, { message: 'Property needs to match: /^[a-zA-Z0-9-_]{1,32}$/' });
+z.object({
+    id: DefinitionPropertyKeySchema,
+    variables: z.record(DefinitionPropertyKeySchema, z.object({
+        // TODO - extend with definition of validations and defaultValue
+        displayName: z.string().optional(),
+        type: DefinitionPropertyTypeSchema,
+        description: z.string().optional(),
+        group: z.string().optional(),
+    })),
+});
+
+const uuidKeySchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9-_]{1,21}$/, { message: 'Does not match /^[a-zA-Z0-9-_]{1,21}$/' });
+/**
+ * Property keys for imported components have a limit of 32 characters (to be implemented) while
+ * property keys for patterns have a limit of 54 characters (<32-char-variabl-name>_<21-char-nanoid-id>).
+ * Because we cannot distinguish between the two in the componentTree, we will use the larger limit for both.
+ */
+const propertyKeySchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9-_]{1,54}$/, { message: 'Does not match /^[a-zA-Z0-9-_]{1,54}$/' });
+const DataSourceSchema = z.record(uuidKeySchema, z.object({
+    sys: z.object({
+        type: z.literal('Link'),
+        id: z.string(),
+        linkType: z.enum(['Entry', 'Asset']),
+    }),
+}));
+const PrimitiveValueSchema = z.union([
+    z.string(),
+    z.boolean(),
+    z.number(),
+    z.record(z.any(), z.any()),
+    z.undefined(),
+]);
+const ValuesByBreakpointSchema = z.record(z.lazy(() => PrimitiveValueSchema));
+const DesignValueSchema = z
+    .object({
+    type: z.literal('DesignValue'),
+    valuesByBreakpoint: ValuesByBreakpointSchema,
+})
+    .strict();
+const BoundValueSchema = z
+    .object({
+    type: z.literal('BoundValue'),
+    path: z.string(),
+})
+    .strict();
+const HyperlinkValueSchema = z
+    .object({
+    type: z.literal('HyperlinkValue'),
+    linkTargetKey: z.string(),
+    overrides: z.object({}).optional(),
+})
+    .strict();
+const UnboundValueSchema = z
+    .object({
+    type: z.literal('UnboundValue'),
+    key: z.string(),
+})
+    .strict();
+const ComponentValueSchema = z
+    .object({
+    type: z.literal('ComponentValue'),
+    key: z.string(),
+})
+    .strict();
+const ComponentPropertyValueSchema = z.discriminatedUnion('type', [
+    DesignValueSchema,
+    BoundValueSchema,
+    UnboundValueSchema,
+    HyperlinkValueSchema,
+    ComponentValueSchema,
+]);
+const BreakpointSchema = z
+    .object({
+    id: propertyKeySchema,
+    query: z.string().regex(/^\*$|^<[0-9*]+px$/),
+    previewSize: z.string(),
+    displayName: z.string(),
+    displayIconUrl: z.string().optional(),
+})
+    .strict();
+const UnboundValuesSchema = z.record(uuidKeySchema, z.object({
+    value: PrimitiveValueSchema,
+}));
+// Use helper schema to define a recursive schema with its type correctly below
+const BaseComponentTreeNodeSchema = z.object({
+    definitionId: DefinitionPropertyKeySchema,
+    displayName: z.string().optional(),
+    slotId: z.string().optional(),
+    variables: z.record(propertyKeySchema, ComponentPropertyValueSchema),
+});
+const ComponentTreeNodeSchema = BaseComponentTreeNodeSchema.extend({
+    children: z.lazy(() => ComponentTreeNodeSchema.array()),
+});
+const ComponentSettingsSchema = z.object({
+    variableDefinitions: z.record(z.string().regex(/^[a-zA-Z0-9-_]{1,54}$/), // Here the key is <variableName>_<nanoidId> so we need to allow for a longer length
+    z.object({
+        displayName: z.string().optional(),
+        type: DefinitionPropertyTypeSchema,
+        defaultValue: PrimitiveValueSchema.or(ComponentPropertyValueSchema).optional(),
+        description: z.string().optional(),
+        group: z.string().optional(),
+        validations: z
+            .object({
+            required: z.boolean().optional(),
+            format: z.literal('URL').optional(),
+            in: z
+                .array(z.object({
+                value: z.union([z.string(), z.number()]),
+                displayName: z.string().optional(),
+            }))
+                .optional(),
+        })
+            .optional(),
+    })),
+});
+const UsedComponentsSchema = z.array(z.object({
+    sys: z.object({
+        type: z.literal('Link'),
+        id: z.string(),
+        linkType: z.literal('Entry'),
+    }),
+}));
+const breakpointsRefinement = (value, ctx) => {
+    if (!value.length || value[0].query !== '*') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `The first breakpoint should include the following attributes: { "query": "*" }`,
+        });
+    }
+    const hasDuplicateIds = value.some((currentBreakpoint, currentBreakpointIndex) => {
+        // check if the current breakpoint id is found in the rest of the array
+        const breakpointIndex = value.findIndex((breakpoint) => breakpoint.id === currentBreakpoint.id);
+        return breakpointIndex !== currentBreakpointIndex;
+    });
+    if (hasDuplicateIds) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Breakpoint IDs must be unique`,
+        });
+    }
+    // Extract the queries boundary by removing the special characters around it
+    const queries = value.map((bp) => bp.query === '*' ? bp.query : parseInt(bp.query.replace(/px|<|>/, '')));
+    // sort updates queries array in place so we need to create a copy
+    const originalQueries = [...queries];
+    queries.sort((q1, q2) => {
+        if (q1 === '*') {
+            return -1;
+        }
+        if (q2 === '*') {
+            return 1;
+        }
+        return q1 > q2 ? -1 : 1;
+    });
+    if (originalQueries.join('') !== queries.join('')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Breakpoints should be ordered from largest to smallest pixel value`,
+        });
+    }
+};
+const componentSettingsRefinement = (value, ctx) => {
+    const { componentSettings, usedComponents } = value;
+    if (!componentSettings || !usedComponents) {
+        return;
+    }
+    const localeKey = Object.keys(componentSettings ?? {})[0];
+    if (componentSettings[localeKey] !== undefined && usedComponents[localeKey] !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `'componentSettings' field cannot be used in conjunction with 'usedComponents' field`,
+            path: ['componentSettings', localeKey],
+        });
+    }
+};
+const ComponentTreeSchema = z
+    .object({
+    breakpoints: z.array(BreakpointSchema).superRefine(breakpointsRefinement),
+    children: z.array(ComponentTreeNodeSchema),
+    schemaVersion: SchemaVersions,
+})
+    .strict();
+const localeWrapper = (fieldSchema) => z.record(z.string(), fieldSchema);
+z
+    .object({
+    componentTree: localeWrapper(ComponentTreeSchema),
+    dataSource: localeWrapper(DataSourceSchema),
+    unboundValues: localeWrapper(UnboundValuesSchema),
+    usedComponents: localeWrapper(UsedComponentsSchema).optional(),
+    componentSettings: localeWrapper(ComponentSettingsSchema).optional(),
+})
+    .superRefine(componentSettingsRefinement);
+
+var CodeNames;
+(function (CodeNames) {
+    CodeNames["Type"] = "type";
+    CodeNames["Required"] = "required";
+    CodeNames["Unexpected"] = "unexpected";
+    CodeNames["Regex"] = "regex";
+    CodeNames["In"] = "in";
+    CodeNames["Size"] = "size";
+    CodeNames["Custom"] = "custom";
+})(CodeNames || (CodeNames = {}));
+
 const MEDIA_QUERY_REGEXP = /(<|>)(\d{1,})(px|cm|mm|in|pt|pc)$/;
 const toCSSMediaQuery = ({ query }) => {
     if (query === '*')
@@ -1729,6 +1960,7 @@ const SCROLL_STATES = {
 const OUTGOING_EVENTS = {
     Connected: 'connected',
     DesignTokens: 'registerDesignTokens',
+    RegisteredBreakpoints: 'registeredBreakpoints',
     HoveredSection: 'hoveredSection',
     MouseMove: 'mouseMove',
     NewHoveredElement: 'newHoveredElement',
@@ -2209,7 +2441,7 @@ function getStyle$2(style, snapshot) {
         transitionDuration: `0.001s`,
     };
 }
-const DraggableComponent = ({ children, id, index, isAssemblyBlock = false, isSelected = false, onClick = () => null, onMouseOver = () => null, coordinates, userIsDragging, style, wrapperProps, isContainer, blockId, isDragDisabled = false, placeholder, definition, ...rest }) => {
+const DraggableComponent = ({ children, id, index, isAssemblyBlock = false, isSelected = false, onClick = () => null, onMouseOver = () => null, coordinates, userIsDragging, style, wrapperProps, isContainer, blockId, isDragDisabled = false, placeholder, definition, displayName, ...rest }) => {
     const ref = useRef(null);
     const setDomRect = useDraggedItemStore((state) => state.setDomRect);
     const isHoveredComponent = useDraggedItemStore((state) => state.hoveredComponentId === id);
@@ -2237,7 +2469,7 @@ const DraggableComponent = ({ children, id, index, isAssemblyBlock = false, isSe
             e.stopPropagation();
             setDomRect(e.currentTarget.getBoundingClientRect());
         }, onMouseOver: onMouseOver, onClick: onClick },
-        React.createElement(Tooltip, { id: id, coordinates: coordinates, isAssemblyBlock: isAssemblyBlock, isContainer: isContainer, label: definition.name || 'No label specified' }),
+        React.createElement(Tooltip, { id: id, coordinates: coordinates, isAssemblyBlock: isAssemblyBlock, isContainer: isContainer, label: displayName || definition.name || 'No label specified' }),
         React.createElement(Placeholder, { ...placeholder, id: id }),
         children))));
 };
@@ -2867,7 +3099,7 @@ const useComponent = ({ node: rawNode, resolveDesignValue, renderDropzone, userI
  * component.
  */
 const DraggableChildComponent = (props) => {
-    const { elementToRender, id, index, isAssemblyBlock = false, isSelected = false, onClick = () => null, onMouseOver = () => null, coordinates, userIsDragging, style, isContainer, blockId, isDragDisabled = false, wrapperProps, definition, } = props;
+    const { elementToRender, id, index, isAssemblyBlock = false, isSelected = false, onClick = () => null, onMouseOver = () => null, coordinates, userIsDragging, style, isContainer, blockId, isDragDisabled = false, wrapperProps, definition, displayName, } = props;
     const isHoveredComponent = useDraggedItemStore((state) => state.hoveredComponentId === id);
     return (React.createElement(Draggable, { key: id, draggableId: id, index: index, isDragDisabled: isDragDisabled }, (provided, snapshot) => elementToRender({
         ['data-ctfl-draggable-id']: id,
@@ -2889,7 +3121,7 @@ const DraggableChildComponent = (props) => {
         },
         onClick,
         onMouseOver,
-        Tooltip: (React.createElement(Tooltip, { id: id, coordinates: coordinates, isAssemblyBlock: isAssemblyBlock, isContainer: isContainer, label: definition.name || 'No label specified' })),
+        Tooltip: (React.createElement(Tooltip, { id: id, coordinates: coordinates, isAssemblyBlock: isAssemblyBlock, isContainer: isContainer, label: displayName || definition.name || 'No label specified' })),
     })));
 };
 
@@ -3415,6 +3647,7 @@ const EditorBlock = ({ node: rawNode, resolveDesignValue, renderDropzone, index,
         userIsDragging,
     });
     const coordinates = useSelectedInstanceCoordinates({ node });
+    const displayName = node.data.displayName;
     const isContainer = node.data.blockId === CONTENTFUL_COMPONENTS.container.id;
     const isSingleColumn = node.data.blockId === CONTENTFUL_COMPONENTS.singleColumn.id;
     const isAssemblyBlock = node.type === ASSEMBLY_BLOCK_NODE_TYPE;
@@ -3447,9 +3680,9 @@ const EditorBlock = ({ node: rawNode, resolveDesignValue, renderDropzone, index,
         });
     };
     if (isSingleColumn) {
-        return (React.createElement(DraggableChildComponent, { elementToRender: elementToRender, id: componentId, index: index, isAssemblyBlock: isAssembly || isAssemblyBlock, isDragDisabled: true, isSelected: selectedNodeId === componentId, userIsDragging: userIsDragging, isContainer: isContainer, blockId: node.data.blockId, coordinates: coordinates, wrapperProps: wrapperProps, onClick: onClick, onMouseOver: onMouseOver, definition: definition }));
+        return (React.createElement(DraggableChildComponent, { elementToRender: elementToRender, id: componentId, index: index, isAssemblyBlock: isAssembly || isAssemblyBlock, isDragDisabled: true, isSelected: selectedNodeId === componentId, userIsDragging: userIsDragging, isContainer: isContainer, blockId: node.data.blockId, coordinates: coordinates, wrapperProps: wrapperProps, onClick: onClick, onMouseOver: onMouseOver, definition: definition, displayName: displayName }));
     }
-    return (React.createElement(DraggableComponent, { placeholder: placeholder, definition: definition, id: componentId, index: index, isAssemblyBlock: isAssembly || isAssemblyBlock, isDragDisabled: isAssemblyBlock, isSelected: selectedNodeId === componentId, userIsDragging: userIsDragging, isContainer: isContainer, blockId: node.data.blockId, coordinates: coordinates, wrapperProps: wrapperProps, onClick: onClick, onMouseOver: onMouseOver },
+    return (React.createElement(DraggableComponent, { placeholder: placeholder, definition: definition, id: componentId, index: index, isAssemblyBlock: isAssembly || isAssemblyBlock, isDragDisabled: isAssemblyBlock, isSelected: selectedNodeId === componentId, userIsDragging: userIsDragging, isContainer: isContainer, blockId: node.data.blockId, coordinates: coordinates, wrapperProps: wrapperProps, onClick: onClick, onMouseOver: onMouseOver, displayName: displayName },
         elementToRender(),
         isStructureComponent && userIsDragging && (React.createElement(Hitboxes, { parentZoneId: zoneId, zoneId: componentId, isEmptyZone: isEmptyZone }))));
 };