@dotcms/experiments 0.0.1-alpha.13 → 0.0.1-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/experiments",
-  "version": "0.0.1-alpha.13",
+  "version": "0.0.1-alpha.15",
   "description": "Official JavaScript library to use Experiments with DotCMS.",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@dotcms/client": "0.0.1-alpha.13"
+    "@dotcms/client": "0.0.1-alpha.14"
   },
   "module": "./index.esm.js",
   "type": "module",

package/src/index.d.ts

@@ -1,3 +1 @@
-export * from './lib/hooks/useExperiments';
-export * from './lib/components/DotExperimentsProvider';
-export * from './lib/contexts/DotExperimentsContext';
+export * from './lib/components/withExperiments';

package/src/lib/components/DotExperimentHandlingComponent.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="react" />
+import { DotcmsPageProps } from '@dotcms/react';
+interface ExperimentHandlingProps extends DotcmsPageProps {
+    WrappedComponent: React.ComponentType<DotcmsPageProps>;
+}
+/**
+ * A React functional component that conditionally renders a WrappedComponent based on the
+ * experiment variant state. It uses the `useExperimentVariant` hook to determine if there's a
+ * variant mismatch. If the current variant does not match the assigned variant, it temporarily
+ * hides the WrappedComponent by rendering it with `visibility: hidden`. Once the correct variant
+ * is confirmed, it renders the WrappedComponent normally.
+ *
+ * @param {React.ComponentType<DotcmsPageProps>} WrappedComponent - The React component that will be
+ *        conditionally rendered based on the experiment variant.
+ * @param {DotcmsPageProps} props - Props expected by the WrappedComponent, along with any additional
+ *        props that extend from DotcmsPageProps.
+ * @returns {React.ReactElement} A React element that either renders the WrappedComponent hidden or visible
+ *          based on the experiment variant.
+ */
+export declare const DotExperimentHandlingComponent: React.FC<ExperimentHandlingProps>;
+export {};

package/src/lib/components/withExperiments.d.ts

@@ -0,0 +1,20 @@
+import React, { ReactNode } from 'react';
+import { DotcmsPageProps } from '@dotcms/react';
+import { DotExperimentConfig } from '../shared/models';
+export interface PageProviderProps {
+    readonly entity: any;
+    readonly children: ReactNode;
+}
+/**
+ * Wraps a given component with experiment handling capabilities using the 'useExperimentVariant' hook.
+ * This HOC checks if the entity's assigned experiment variant differs from the currently displayed variant.
+ * If they differ, the content is hidden until the correct variant is displayed. Once the assigned variant
+ * matches the displayed variant, the content of the WrappedComponent is shown.
+ *
+ * @param {React.ComponentType<DotcmsPageProps>} WrappedComponent - The component to be enhanced.
+ * @param {DotExperimentConfig} config - Configuration for experiment handling, including any necessary
+ *        redirection functions or other settings.
+ * @returns {React.FunctionComponent<DotcmsPageProps>} A component that wraps the original component,
+ *          adding experiment handling based on the specified configuration.
+ */
+export declare const withExperiments: (WrappedComponent: React.ComponentType<DotcmsPageProps>, config: DotExperimentConfig) => (props: DotcmsPageProps) => import("react/jsx-runtime").JSX.Element;

package/src/lib/contexts/DotExperimentsContext.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { DotExperiments } from '../dot-experiments';
 /**
  * `DotExperimentsContext` is a React context that is designed to provide an instance of

package/src/lib/dot-experiments.d.ts

@@ -1,4 +1,4 @@
-import { DotExperimentConfig, Experiment, Variant } from './shared/models';
+import { DotExperimentConfig, Experiment, Variant } from "./shared/models";
 /**
  * `DotExperiments` is a Typescript class to handles all operations related to fetching, storing, parsing, and navigating
  * data for Experiments (A/B Testing).
@@ -197,13 +197,23 @@ export declare class DotExperiments {
      */
     private initialize;
     /**
-     * Fetches experiments from the server.
+     * Fetches experiments from the server and merge if not ended the excluded requested.
      *
      * @private
      * @returns {Promise<AssignedExperiments>} - The entity object returned from the server.
      * @throws {Error} - If an HTTP error occurs or an error occurs during the fetch request.
      */
     private getExperimentsFromServer;
+    /**
+     * Filters out experiments that are not yet ended from already assigned.
+     *
+     * @param {Array} excludedExperimentIdsEnded - The IDs of experiments to be excluded because they have ended.
+     *
+     * @return {Array} Experiments that are not in the list of those that have ended.
+     *
+     * @private
+     */
+    private getExperimentsNotEndedFromAlreadyAssigned;
     /**
      * This method is responsible for retrieving and persisting experiment data from the server to the local indexDB database.
      *

package/src/lib/hooks/useExperimentVariant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A React Hook that determines whether to wait for the correct variant in an A/B testing scenario.
+ * This is used to avoid flickering - showing the original content before redirecting to the assigned variant.
+ *
+ * The hook uses the running experiment id and viewAs (containing variantId) from the provided data.
+ * It then works with the DotExperimentsContext to synchronize between the assigned variant and the one requested.
+ * If the hook is executed inside an editor or if no running experiment id is provided, it immediately signals not to wait for the variant.
+ * Similarly, if the assigned variant matches the requested one, it signals not to wait for the variant.
+ * By default, the hook signals to wait for the variant.
+ *
+ * @param {Object} data - An object containing the runningExperimentId and viewAs (containing variantId).
+ * @returns {Object} An object with a function `shouldWaitForVariant` that, when called, returns `true` if it should wait for the correct variant, `false` otherwise.
+ */
+export declare const useExperimentVariant: (data: {
+    runningExperimentId?: string;
+    viewAs: {
+        variantId: string;
+    };
+}) => {
+    shouldWaitForVariant: boolean;
+};

package/src/lib/shared/mocks/mock.d.ts

@@ -1,4 +1,4 @@
-import { Experiment, ExperimentEvent, IsUserIncludedApiResponse } from '../models';
+import { Experiment, ExperimentEvent, IsUserIncludedApiResponse } from "../models";
 /**
  * Represents the response object for the IsUserIncluded API.
  * @typedef {Object} IsUserIncludedResponse
@@ -9,6 +9,7 @@ import { Experiment, ExperimentEvent, IsUserIncludedApiResponse } from '../model
  */
 export declare const IsUserIncludedResponse: IsUserIncludedApiResponse;
 export declare const NewIsUserIncludedResponse: IsUserIncludedApiResponse;
+export declare const After15DaysIsUserIncludedResponse: IsUserIncludedApiResponse;
 export declare const MOCK_CURRENT_TIMESTAMP = 1704096000000;
 export declare const TIME_15_DAYS_MILLISECONDS: number;
 export declare const TIME_5_DAYS_MILLISECONDS: number;

package/src/lib/shared/models.d.ts

@@ -128,7 +128,15 @@ export interface AssignedExperiments {
      * The ids of the experiments included in the assignment.
      */
     includedExperimentIds: string[];
+    /**
+     * The ids of the experiments that are excluded in the request and have ended.
+     */
+    excludedExperimentIdsEnded: string[];
 }
+/**
+ * Represents the response from the backend when fetching an experiment.
+ */
+export type FetchExperiments = Pick<AssignedExperiments, 'excludedExperimentIdsEnded' | 'experiments'>;
 /**
  * Represents the response from backend holding information about running experiments and variant assignment.
  *

package/src/lib/shared/parser/parser.d.ts

@@ -1,4 +1,4 @@
-import { Experiment, ExperimentParsed } from '../models';
+import { Experiment, ExperimentParsed, FetchExperiments } from "../models";
 /**
  * This arrow function parses a given set of assigned experiments for analytics.
  *
@@ -44,7 +44,7 @@ export declare const verifyRegex: (regexToCheck: string | null, href: string) =>
  *
  * There could be scenarios where none of these conditions are met, in that case, dataToStorage will be the default empty object.
  */
-export declare const parseData: (fetchExperiments: Experiment[] | undefined, storedExperiments: Experiment[] | undefined) => Experiment[];
+export declare const parseData: (fetchExperiments: FetchExperiments, storedExperiments: Experiment[] | undefined) => Experiment[];
 /**
  * Retrieves the array of experiment IDs from the given AssignedExperiments..
  *