@nosto/nosto-react 0.3.0 → 0.4.0

package/src/components/Category/index.client.tsx

@@ -1,7 +1,32 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoCategory: React.FC<{ category: string }> = ({ category }) => {
+/**
+ * You can personalise your category and collection pages by using the NostoCategory component.
+ * The component requires that you provide it the the slash-delimited slug representation of the current category.
+ *
+ * By default, your account, when created, has two category placements named `categorypage-nosto-1` and `categorypage-nosto-2`.
+ * You may omit these and use any identifier you need. The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="category-page">
+ *   <NostoPlacement id="categorypage-nosto-1" />
+ *   <NostoPlacement id="categorypage-nosto-2" />
+ *   <NostoCategory category={category.name} />
+ * </div>
+ * ```
+ *
+ * **Note:** Be sure to pass in the correct category representation.
+ * If the category being viewed is `Mens >> Jackets`, you must provide the name as `/Mens/Jackets`.
+ * You must ensure that the category path provided here matches that of the categories tagged in your products.
+ *
+ * @group Personalisation Components
+ */
+export default function NostoCategory(props: {
+  category: string;
+}): JSX.Element {
+  const { category } = props;
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +38,8 @@ const NostoCategory: React.FC<{ category: string }> = ({ category }) => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("home");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +47,7 @@ const NostoCategory: React.FC<{ category: string }> = ({ category }) => {
           .viewCategory(category)
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -46,6 +70,4 @@ const NostoCategory: React.FC<{ category: string }> = ({ category }) => {
       </div>
     </>
   );
-};
-
-export default NostoCategory;
+}

package/src/components/Checkout/index.client.tsx

@@ -1,7 +1,27 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoCheckout: React.FC = () => {
+/**
+ * You can personalise your cart and checkout pages by using the NostoCheckout component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has two cart-page placements named `categorypage-nosto-1` and `categorypage-nosto-2`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="checkout-page">
+ *   <NostoPlacement id="checkout-nosto-1" />
+ *   <NostoPlacement id="checkout-nosto-2" />
+ *   <NostoCheckout />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+
+export default function NostoCheckout(): JSX.Element {
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +33,8 @@ const NostoCheckout: React.FC = () => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("checkout");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +42,7 @@ const NostoCheckout: React.FC = () => {
           .viewCart()
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -42,6 +61,4 @@ const NostoCheckout: React.FC = () => {
       </div>
     </>
   );
-};
-
-export default NostoCheckout;
+}

package/src/components/Fohofo/index.client.tsx

@@ -1,7 +1,27 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoFohofo: React.FC = () => {
+/**
+ * You can personalise your cart and checkout pages by using the `Nosto404` component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has three 404-page placements named `notfound-nosto-1`, `notfound-nosto-2` and `notfound-nosto-3`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="notfound-page">
+ *   <NostoPlacement id="notfound-nosto-1" />
+ *   <NostoPlacement id="notfound-nosto-2" />
+ *   <NostoPlacement id="notfound-nosto-3" />
+ *   <Nosto404 />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function Nosto404(): JSX.Element {
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +33,8 @@ const NostoFohofo: React.FC = () => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("404");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +42,7 @@ const NostoFohofo: React.FC = () => {
           .viewNotFound()
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -42,6 +61,4 @@ const NostoFohofo: React.FC = () => {
       </div>
     </>
   );
-};
-
-export default NostoFohofo;
+}

package/src/components/Home/index.client.tsx

@@ -1,7 +1,30 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoHome: React.FC = () => {
+/**
+ * The `NostoHome` component must be used to personalise the home page. The component does not require any props.
+ *
+ * By default, your account, when created, has four front-page placements named `frontpage-nosto-1`, `frontpage-nosto-2`, `frontpage-nosto-3` and `frontpage-nosto-4`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * The `<NostoHome \>` component needs to be added after the placements.
+ * Content and recommendations will be rendered through this component.
+ *
+ * @example
+ * ```
+ *  <div className="front-page">
+ *   <NostoPlacement id="frontpage-nosto-1" />
+ *   <NostoPlacement id="frontpage-nosto-2" />
+ *   <NostoPlacement id="frontpage-nosto-3" />
+ *   <NostoPlacement id="frontpage-nosto-4" />
+ *   <NostoHome />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoHome(): JSX.Element {
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +36,8 @@ const NostoHome: React.FC = () => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("home");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +45,7 @@ const NostoHome: React.FC = () => {
           .viewFrontPage()
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -42,6 +64,4 @@ const NostoHome: React.FC = () => {
       </div>
     </>
   );
-};
-
-export default NostoHome;
+}

package/src/components/Order/index.client.tsx

@@ -1,13 +1,31 @@
 import { Purchase } from "../../types";
-import React, { useEffect } from "react";
-import snakeize from "snakeize";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
+import { snakeize } from "../../utils/snakeize";
 
-export interface OrderProps {
-  purchase: Purchase;
-}
-
-const NostoOrder: React.FC<{ order: OrderProps }> = ({ order }) => {
+/**
+ * You can personalise your order-confirmation/thank-you page by using the `NostoOrder` component.
+ * The component requires that you provide it with the details of the order.
+ *
+ * By default, your account, when created, has one other-page placement named `thankyou-nosto-1`.
+ * You may omit this and use any identifier you need. The identifier used here is simply provided to illustrate the example.
+ *
+ * The order prop requires a value that adheres to the type `Purchase`.
+ *
+ * @example
+ * ```
+ * <div className="thankyou-page">
+ *     <NostoPlacement id="thankyou-nosto-1" />
+ *     <NostoOrder order={{ purchase: toOrder(order) }} />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoOrder(props: {
+  order: { purchase: Purchase };
+}): JSX.Element {
+  const { order } = props;
   const {
     clientScriptLoaded,
     currentVariation,
@@ -19,9 +37,8 @@ const NostoOrder: React.FC<{ order: OrderProps }> = ({ order }) => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("order");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -29,7 +46,7 @@ const NostoOrder: React.FC<{ order: OrderProps }> = ({ order }) => {
           .addOrder(snakeize(order))
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -51,6 +68,4 @@ const NostoOrder: React.FC<{ order: OrderProps }> = ({ order }) => {
       </div>
     </>
   );
-};
-
-export default NostoOrder;
+}

package/src/components/Other/index.client.tsx

@@ -1,7 +1,26 @@
 import React, { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoOther: React.FC = () => {
+/**
+ * You can personalise your miscellaneous pages by using the NostoOther component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has two other-page placements named `other-nosto-1` and `other-nosto-2`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="other-page">
+ *     <NostoPlacement id="other-nosto-1" />
+ *     <NostoPlacement id="other-nosto-2" />
+ *     <NostoOther />
+ * </div>;
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoOther(): JSX.Element {
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +32,8 @@ const NostoOther: React.FC = () => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("other");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +41,7 @@ const NostoOther: React.FC = () => {
           .viewOther()
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -42,6 +60,4 @@ const NostoOther: React.FC = () => {
       </div>
     </>
   );
-};
-
-export default NostoOther;
+}

package/src/components/Placement/index.client.tsx

@@ -1,12 +1,22 @@
 import React from "react";
 
-export interface PlacementProps {
+/**
+ * Nosto React has a special component called NostoPlacement.
+ * The component is a simply a hidden `<div>` placeholder into which Nosto injects recommendations or personalises the content between the tags.
+ *
+ * We recommend adding as many placements across your views as needed as these are hidden and only populated when a corresponding campaign (targeting that placement) is configured.
+ *
+ * @example
+ * ```
+ * <NostoPlacement id="frontpage-nosto-1" />
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoPlacement(props: {
   id: string;
-  pageType: string;
+  pageType?: string;
+}): JSX.Element {
+  const { id, pageType } = props;
+  return <div className="nosto_element" id={id} key={id + (pageType || "")} />;
 }
-
-const NostoPlacement: React.FC<PlacementProps> = ({ id, pageType }) => {
-  return <div className="nosto_element" id={id} key={id + pageType} />;
-};
-
-export default NostoPlacement;

package/src/components/Product/index.client.tsx

@@ -1,11 +1,36 @@
 import { Product } from "../../types";
-import React, { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
+import { useDeepCompareEffect } from "../../utils/hooks";
 
-const NostoProduct: React.FC<{ product: string; tagging: Product }> = ({
-  product,
-  tagging,
-}) => {
+/**
+ * The NostoProduct component must be used to personalise the product page.
+ * The component requires that you provide it the identifier of the current product being viewed.
+ *
+ * By default, your account, when created, has three product-page placements named `productpage-nosto-1`, `productpage-nosto-2` and `productpage-nosto-3`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * The `<NostoProduct \>` component needs to be added after the placements.
+ * Content and recommendations will be rendered through this component.
+ * Pass in the product ID via the product prop to pass this information back to Nosto.
+ *
+ * @example
+ * ```
+ * <div className="product-page">
+ *   <NostoPlacement id="productpage-nosto-1" />
+ *   <NostoPlacement id="productpage-nosto-2" />
+ *   <NostoPlacement id="productpage-nosto-3" />
+ *   <NostoProduct product={product.id} />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoProduct(props: {
+  product: string;
+  tagging?: Product;
+}): JSX.Element {
+  const { product, tagging } = props;
   const {
     clientScriptLoaded,
     currentVariation,
@@ -16,31 +41,27 @@ const NostoProduct: React.FC<{ product: string; tagging: Product }> = ({
 
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("product");
 
-  useEffect(() => {
-    // @ts-ignore
+  useDeepCompareEffect(() => {
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs(
-        (api: any) => {
-          api
-            .defaultSession()
-            .setResponseMode(responseMode)
-            .viewProduct(product)
-            .setPlacements(api.placements.getPlacements())
-            .load()
-            .then((data: object) => {
-              renderCampaigns(data, api);
-            });
-        },
-        [
-          clientScriptLoaded,
-          currentVariation,
-          product,
-          recommendationComponent,
-          pageTypeUpdated,
-        ]
-      );
+      window.nostojs((api) => {
+        api
+          .defaultSession()
+          .setResponseMode(responseMode)
+          .viewProduct(product)
+          .setPlacements(api.placements.getPlacements())
+          .load()
+          .then((data) => {
+            renderCampaigns(data, api);
+          });
+      });
     }
-  });
+  }, [
+    clientScriptLoaded,
+    currentVariation,
+    product,
+    recommendationComponent,
+    pageTypeUpdated,
+  ]);
 
   return (
     <>
@@ -162,6 +183,4 @@ const NostoProduct: React.FC<{ product: string; tagging: Product }> = ({
       </div>
     </>
   );
-};
-
-export default NostoProduct;
+}

package/src/components/Provider/context.client.ts

@@ -1,26 +1,40 @@
-import { createContext, useContext, ReactComponentElement } from "react";
+import { createContext, useContext } from "react";
+import { Recommendation } from "../../types";
 
-export interface NostoInterface {
+/**
+ * @group Types
+ */
+export interface NostoContextType {
   account: string;
   clientScriptLoaded: boolean;
   currentVariation: string;
   renderFunction?: Function;
   responseMode: string;
-  recommendationComponent?: any;
+  recommendationComponent?: React.ReactElement<{
+    nostoRecommendation: Recommendation;
+  }>;
   useRenderCampaigns: Function;
   pageType: string;
 }
 
-/* tslint:disable:no-empty */
-export const NostoContext = createContext<NostoInterface>({
-  // @ts-ignore
-  account: undefined,
+/**
+ * @group Essential Functions
+ */
+export const NostoContext = createContext<NostoContextType>({
+  account: "",
   currentVariation: "",
-  renderFunction: undefined,
+  pageType: "",
+  responseMode: "HTML",
+  clientScriptLoaded: false,
+  useRenderCampaigns: () => undefined,
 });
 
-/* tslint:enable:no-empty */
-export function useNostoContext() {
+/**
+ * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
+ *
+ * @group Essential Functions
+ */
+export function useNostoContext(): NostoContextType {
   const context = useContext(NostoContext);
 
   if (!context) {