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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/experiments",
-  "version": "0.0.1-alpha.13",
+  "version": "0.0.1-alpha.14",
   "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/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;
+};