@contentful/experiences-sdk-react 1.5.0 → 1.5.1-beta.0

package/README.md

@@ -1,11 +1,18 @@
 # @contentful/experiences-sdk-react
+### Purpose
+- To bundle up and expose features from other packages to be used by the end user. This is the package that users will install and import into their own React projects.
+- Note that this is a React-specific package. Therefore, unlike the core package, React specific compatibilities are implemented here and support for other frontend frameworks would result in a new package being created under a separate namespace.
 
-This package provides the core SDK for Contentful Studio Experiences. It offers a set of tools and services that enable developers to build, manage, and enhance experiences.
+### Concepts
+- **Experience object**: Generalized typed definition of what an experience is. Contains information about the component tree, unbound values, and data source that are converted from the content entry so that the experiences packages can use the transformed object, handle manipulations to the tree, validate its values, and update the experience object back to the content entry as users trigger and save their changes.
+- **ExperienceRoot**: Main entry point component that users will use in their React project which takes in a experience object as a prop. The experience object can be fetched in a multitude of ways. One common way for Vite React projects for example would be to use the `useFetchBySlug/useFetchById` hooks. However, for SSR they would use the `fetchBySlug/fetchById` functions instead. Additionally, users can create their own experience object using custom transformations they provide for themselves and pass their transformed object as a prop to the `ExperienceRoot` provided that the object complies with the experience type. 
+- **SSR**: Making the SDK compatible with SSR is provided in the SDK package itself. However, there are discussion on moving the logic into the core package in the future.
+- **Breakpoints**: Defines how we separate desktop, tablet, and mobile breakpoints for each viewport.
+- **Preview vs Live vs Editor mode**: Editor mode is what is seen in the Contentful web app for experiences with the Component sidebar, Visual editor, and the Design sidebar where users are allowed to drag and drop components, edit the styles, and publish their changes. Live mode is the ability to view a user's experience with published changes. Preview mode is the ability to see a user's experience with unpublished changes. 
+- **PreviewDeliveryRoot vs VisualEditorRoot**: In the `ExperienceRoot.tsx` file, notice there is logic to either render the `<VisualEditorRoot>` vs the `<PreviewDeliveryRoot>` depending on whether or not the user is in editor mode. Note for both compoments, they have their own way of parsing through the entire component tree and rendering the components to the UI. This is because the Visual editor has to add wrapping divs for drag and drop while the Preview delivery can just print the components to the UI as is. Additionally, the name PreviewDelivery converges the Live and Preview mode concepts into just one idea. In reality, PreviewDeliveryRoot works more as the Live mode concept. There are plans to iterate and to build a third mode for Preview and rename `<PreviewDeliveryRoot>` to just `<DeliveryRoot>` or `<LiveRoot>`.
+- **Preview vs Delivery API**: Each experience object will draw their source of truth from a content entry which is either fetched via Contentful's Delivery or Preview API. The user will define which API is used when setting up experiences. This is not to be confused with "Preview" or "Delivery/Live" mode with respect to experiences as they are separate entities.
+- **Component Registry**: Takes in the component definitions and registers them into the UI where the `enrichComponentDefinition` function will apply styles that are defined by the component themselves as default styles. This will ensure that the user dragging a built-in or structure component will display the default styles defined by Contentful.
 
-## Installation
-
-Please follow the guide to [Set up Experiences SDK](https://www.contentful.com/developers/docs/experiences/set-up-experiences-sdk/).
-
-## Documentation
-
-Please refer to our [Documentation](https://www.contentful.com/developers/docs/experiences/) to learn more about it.
+### Relevant Contentful documentation links
+- [Component definition schema](https://www.contentful.com/developers/docs/experiences/component-definition-schema/)
+- [Data structures](https://www.contentful.com/developers/docs/experiences/data-structures/)

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _contentful_experiences_core from '@contentful/experiences-core';
 import { EntityStore, VisualEditorMode } from '@contentful/experiences-core';
-export { VisualEditorMode, createExperience, defineDesignTokens, fetchById, fetchBySlug } from '@contentful/experiences-core';
+export { VisualEditorMode, createExperience, defineBreakpoints, defineDesignTokens, fetchById, fetchBySlug } from '@contentful/experiences-core';
 import { Experience, ComponentRegistration, ComponentRegistrationOptions } from '@contentful/experiences-core/types';
 export { ComponentDefinition, ExternalSDKMode } from '@contentful/experiences-core/types';
 import { ContentfulClientApi } from 'contentful';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
-import { containerDefinition, sectionDefinition, columnsDefinition, singleColumnDefinition, dividerDefinition, builtInStyles, optionalBuiltInStyles, sendMessage, designTokensRegistry, buildCfStyles, isEmptyStructureWithRelativeHeight, buildStyleTag, checkIsAssemblyNode, resolveHyperlinkPattern, transformBoundContentValue, mediaQueryMatcher, getFallbackBreakpointIndex, getActiveBreakpointIndex, getValueForBreakpoint, doesMismatchMessageSchema, tryParseMessage, fetchById, fetchBySlug, validateExperienceBuilderConfig, VisualEditorMode, toCSSAttribute } from '@contentful/experiences-core';
-export { VisualEditorMode, createExperience, defineDesignTokens, fetchById, fetchBySlug } from '@contentful/experiences-core';
+import { containerDefinition, sectionDefinition, columnsDefinition, singleColumnDefinition, dividerDefinition, builtInStyles, optionalBuiltInStyles, sendMessage, breakpointsRegistry, designTokensRegistry, buildCfStyles, isEmptyStructureWithRelativeHeight, buildStyleTag, checkIsAssemblyNode, resolveHyperlinkPattern, transformBoundContentValue, mediaQueryMatcher, getFallbackBreakpointIndex, getActiveBreakpointIndex, getValueForBreakpoint, doesMismatchMessageSchema, tryParseMessage, fetchById, fetchBySlug, runBreakpointsValidation, validateExperienceBuilderConfig, VisualEditorMode, toCSSAttribute } from '@contentful/experiences-core';
+export { VisualEditorMode, createExperience, defineBreakpoints, defineDesignTokens, fetchById, fetchBySlug } from '@contentful/experiences-core';
 import React, { useState, useLayoutEffect, useMemo, useEffect, useCallback, useRef, Suspense } from 'react';
 import { omit } from 'lodash-es';
 import { INTERNAL_EVENTS, CONTENTFUL_COMPONENTS, OUTGOING_EVENTS, ASSEMBLY_DEFAULT_CATEGORY, EMPTY_CONTAINER_HEIGHT, HYPERLINK_DEFAULT_PATTERN, CF_STYLE_ATTRIBUTES, INCOMING_EVENTS, VISUAL_EDITOR_EVENTS } from '@contentful/experiences-core/constants';
@@ -10,7 +10,7 @@ import { ContentfulContainer, Columns, SingleColumn } from '@contentful/experien
 import styleInject from 'style-inject';
 import md5 from 'md5';
 
-const SDK_VERSION = '1.5.0-beta.0';
+const SDK_VERSION = '1.5.0';
 
 var util;
 (function (util) {
@@ -4132,6 +4132,7 @@ const BreakpointSchema = z
     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({
@@ -4177,10 +4178,21 @@ const UsedComponentsSchema = z.array(z.object({
     }),
 }));
 const breakpointsRefinement = (value, ctx) => {
-    if (!value.length || value[0].id !== 'desktop' || value[0].query !== '*') {
+    if (!value.length || value[0].query !== '*') {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: `The first breakpoint should include the following attributes: { "id": "desktop", "query": "*" }`,
+            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
@@ -4591,6 +4603,9 @@ const sendConnectedEventWithRegisteredComponents = () => {
         sdkVersion: SDK_VERSION,
         definitions: registeredDefinitions,
     });
+    sendMessage(OUTGOING_EVENTS.RegisteredBreakpoints, {
+        breakpoints: breakpointsRegistry,
+    });
     sendMessage(OUTGOING_EVENTS.DesignTokens, {
         designTokens: designTokensRegistry,
         resolvedCssVariables: resolveCssVariables(designTokensRegistry),
@@ -5068,6 +5083,7 @@ const useInitializeVisualEditor = (params) => {
     useEffect(() => {
         if (!hasConnectEventBeenSent.current) {
             runRegisteredComponentValidations();
+            runBreakpointsValidation();
             // sending CONNECT but with the registered components now
             sendConnectedEventWithRegisteredComponents();
             hasConnectEventBeenSent.current = true;
@@ -5094,6 +5110,7 @@ const useInitializeVisualEditor = (params) => {
                 detail: {
                     componentRegistry,
                     designTokens: designTokensRegistry,
+                    breakpoints: breakpointsRegistry,
                     locale,
                     entities: initialEntities ?? [],
                 },