@rebuy/rebuy-hydrogen 1.0.3 → 2.1.0

package/README.md

@@ -1,407 +1,24 @@
 # Rebuy + Hydrogen Overview
 
-Rebuy + Hydrogen package is a web development framework used for building Shopify custom storefronts.  It includes providers, components, and tooling you need to get started so you can spend your time creating intelligent shopping experiences.
+Rebuy + Hydrogen package is a web development framework used for building Shopify custom storefronts. It includes providers, components, and tooling you need to get started so you can spend your time creating intelligent shopping experiences.
 
 ## How Rebuy + Hydrogen Works
 
-Rebuy + Hydrogen is a lightweight framework for creating personalized shopping experiences that are lightening fast.  The framework is composed of:
-1. Providers - these components build contextual objects that are used during network calls.
-2. Containers - these components get personalized data from Rebuy and pass the resulting information to children components via props.
-3. Components - these components can be used to render various merchandising UI.
-4. Events - these components automatically track user behaviors.
+Rebuy + Hydrogen is a lightweight framework for creating personalized shopping experiences that are lightening fast. The framework is composed of:
+
+1. **Providers** - these components build contextual objects that are used during network calls.
+2. **Containers** - these components get personalized data from Rebuy and pass the resulting information to children components via props.
+3. **Components** - these components can be used to render various merchandising UI.
+4. **Events** - these components automatically track user behaviors.
 
 ### Data Sources
 
-Rebuy + Hydrogen is powered by Rebuy's Data Sources, which allows for AI-powered product recommendations, custom defined rulesets, or mixture of human and computer derived output.  Data Sources are created in Rebuy's App Admin, and the data source URL is used in your Hydrogen project.  Separating the logic from the codebase allows non-technical team members to manage the merchandising rules without the need for costly code changes or redeployments.
+Rebuy + Hydrogen is powered by Rebuy's Data Sources, which allows for AI-powered product recommendations, custom defined rulesets, or mixture of human and computer derived output. Data Sources are created in Rebuy's App Admin, and the data source URL is used in your Hydrogen project. Separating the logic from the codebase allows non-technical team members to manage the merchandising rules without the need for costly code changes or redeployments.
 
 ### User Interfaces
 
-Rebuy + Hydrogen uses a React container pattern to separate the data fetching logic and state managment from the presentional components.  As such, container components do not render user interface elements.  They simply pass their own properties, as well as data received from Rebuy, to their children components for consumption.  This allows you to build your own user interface with your existing components, or use Rebuy's out of the box components to get up and running quickly.
-
-
-# Getting Started
-
-In this tutorial, you'll extend your Hydrogen app with the Rebuy + Hydrogen framework.  After completing this tutorial you'll have accomplished the following:
-
-- Installed the Rebuy + Hydrogen framework
-- Configured your environment
-- Generated AI-powered product recommendations
-
-## Requirements
-
-In order to complete this tutorial, you will need the following:
-- [Shopify](https://www.shopify.com/) account
-- [Rebuy](https://www.rebuyengine.com/) installed in your Shopify store
-- [Hydrogen App](https://shopify.dev/custom-storefronts/hydrogen/getting-started/create#step-1-create-a-new-hydrogen-storefront)
-
-### Install Dependencies
-Additionally, you will need the following dependencies:
-- [npm](https://www.npmjs.com/)
-- [Node.js](https://nodejs.org/en/) (version 16.5.0 or higher)
-
-
-# Step 1: Create a new Hydrogen app
-
-You can create a Hydrogen app locally using `yarn`, `npm`, or `npx`.
-
-If you want to [integrate with an existing React framework](https://shopify.dev/custom-storefronts/hydrogen/framework/integrate-react-frameworks), like [Next.js](https://nextjs.org/) or [Gatsby](https://www.gatsbyjs.com/), then you can add the [@shopify/hydrogen](https://www.npmjs.com/package/@shopify/hydrogen) `npm` package to your project.
-
-#### 1. Navigate to your working directoy
-Navigate to the directory where you want to create your project and run the following command:
-```bash
-cd <directory>
-```
-
-#### 2. Create your project
-Create a new Hydrogen project with a default template linked to a demo-store with the following command:
-```bash
-npm init @shopify/hydrogen -- --template demo-store
-```
-
-#### 3. Name your project
-Follow the prompts to name your new Hydrogen application.
-
-
-# Step 2: Link your Shopify Storefront
-Connect your Hydrogen app to your Shopify storefront by updating the properties in the `hydrogen.config.js` file.  You will need to [generate a Storefront API access token](https://help.shopify.com/en/manual/apps/custom-apps?shpxid=5ef5d325-B992-4F4F-3A6D-0FACECA2B482#install-the-app-and-get-the-api-access-tokens) for your Hydrogen app to communicate with your Shopify store.
-
-#### 1. Open your `hydrogen.config.js` file
-Open `hydrogen.config.js` file located in the root of your project directory.
-
-#### 2. Update your config file
-Edit your `hydrogen.config.js` file with the following changes and save the file:
-- Update `storeDomain` to specify your store's domain name.
-- Update `storefrontToken` to specify your Storefront API access token.
-- Update `storefrontApiVersion` to specify the Storefront API version that you want to use.
-
-```javascript
-export default defineConfig({
-  shopify: {
-    defaultCountryCode: 'US',
-    defaultLanguageCode: 'EN',
-    storeDomain: 'YOUR_STORE_NAME.myshopify.com',
-    storefrontToken: 'YOUR_STOREFRONT_ACCESS_TOKEN',
-    storefrontApiVersion: '2022-07',
-  },
-});
-```
-
-
-# Step 3: Start a development server
-Create a new local development server to start testing your changes.
-
-#### 1. Navigate to your project directoy
-Navigate to the root of your project directory:
-```bash
-cd <directory>
-```
-
-#### 2. Start the development server
-Start up a new local development server on `localhost`:
-```bash
-npm run dev
-```
-
-The development environment will open automatically at [http://localhost:3000](http://localhost:3000).
-
-
-# Step 4: Install Rebuy + Hydrogen Package
-Once you have successfully created your new Hydrogen app and linked it to your Shopify store, it's now time to install the Rebuy + Hydrogen package.  If you currently have your development server running, you can terminate the server with the following command `Ctrl` + `C`.
-
-#### 1. Navigate to your project directoy
-Navigate to the root of your project directory:
-```bash
-cd <directory>
-```
-
-#### 2. Install the Rebuy + Hydrogen package
-Install the Rebuy + Hydrogen package from [npm](https://www.npmjs.com/) with the following command:
-```bash
-npm install @rebuy/rebuy-hydrogen
-```
-
-#### 3. Update your `.env` with your Rebuy public API key
-You can find your [Rebuy public API key](https://rebuyengine.com/account/keys) in Rebuy admin > Account > API Keys. Once located, update your `.env` with the following:
-```
-PUBLIC_REBUY_API_KEY=yourRebuyAPIKey
-```
-*If your project does not have an `.env` file, you can create a new one and save it in the project root directory.*
-
-
-# Step 5: Build Personalized Shopping Experiences
-Once you have included Rebuy + Hydrogen in your project, it's time to start building dynamic, personalized shopping experiences!  In this tutorial, we will accomplish the following:
-
-- Customize the product details page
-- Display a list of AI-powered product recommendations
-- Display a list of recently viewed products
-
-#### 1. Create a Recommended Products Component
-Create a new file in `src/components` called `ProductRecommendations.jsx`, and add the following to the file:
-
-```javascript
-import {
-  ProductOptionsProvider,
-  AddToCartButton,
-} from '@shopify/hydrogen';
-import ProductCard from './ProductCard';
-import {
-  BUTTON_PRIMARY_CLASSES,
-} from './Button.client';
-
-function AddToCartMarkup({product}) {
-  const selectedVariant = product.variants.nodes[0];
-  const isOutOfStock = !selectedVariant.availableForSale;
-
-  return (
-    <div className="space-y-2 mb-8">
-      <AddToCartButton
-        className={BUTTON_PRIMARY_CLASSES}
-        disabled={isOutOfStock}
-        product={product}
-        variantId={selectedVariant.id}
-        attributes={[
-          {key: '_source', value: 'Rebuy'},
-          {key: '_attribution', value: 'Product Recommendations'
-        }]}
-      >
-        {isOutOfStock ? 'Out of stock' : 'Add to bag'}
-      </AddToCartButton>
-    </div>
-  );
-}
-
-export default function ProductRecommendations(props) {
-  const {product, products, metadata} = props;
-
-  console.log('ProductRecommendations component properties:', props);
-
-  return(
-    <>
-      <h1 className="font-bold text-4xl md:text-5xl text-gray-900 mb-6 mt-6">If you like {product.title}, you'll also love these</h1>
-      <ul className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 mb-16">
-        {products.map((product) => (
-          <li key={product.id}>
-            <ProductOptionsProvider data={product} initialVariantId={product.variants.nodes[0].id}>
-              <ProductCard product={product} />
-              <AddToCartMarkup product={product} />
-            </ProductOptionsProvider>
-          </li>
-        ))}
-      </ul>
-    </>
-  )
-}
-```
-
-#### 2. Create a Recently Viewed Products Component
-Create a new file in `src/components` called `RecentlyViewedProducts.jsx`, and add the following to the file:
-
-```javascript
-import {
-  ProductOptionsProvider,
-  AddToCartButton,
-} from '@shopify/hydrogen';
-import ProductCard from './ProductCard';
-import {
-  BUTTON_PRIMARY_CLASSES,
-} from './Button.client';
-
-function AddToCartMarkup({product}) {
-  const selectedVariant = product.variants.nodes[0];
-  const isOutOfStock = !selectedVariant.availableForSale;
-
-  return (
-    <div className="space-y-2 mb-8">
-      <AddToCartButton
-        className={BUTTON_PRIMARY_CLASSES}
-        disabled={isOutOfStock}
-        product={product}
-        variantId={selectedVariant.id}
-        attributes={[
-          {key: '_source', value: 'Rebuy'},
-          {key: '_attribution', value: 'Recently Viewed Product'
-        }]}
-      >
-        {isOutOfStock ? 'Out of stock' : 'Add to bag'}
-      </AddToCartButton>
-    </div>
-  );
-}
-
-export default function RecentlyViewedProducts(props) {
-  const {product, products, metadata} = props;
-
-  console.log('RecentlyViewedProducts component properties:', props);
-
-  return(
-    <>
-      <h1 className="font-bold text-4xl md:text-5xl text-gray-900 mb-6 mt-6">Recently Viewed</h1>
-      <ul className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 mb-16">
-        {products.map((product) => (
-          <li key={product.id}>
-            <ProductOptionsProvider data={product} initialVariantId={product.variants.nodes[0].id}>
-              <ProductCard product={product} />
-              <AddToCartMarkup product={product} />
-            </ProductOptionsProvider>
-          </li>
-        ))}
-      </ul>
-    </>
-  )
-}
-```
-
-#### 3. Install the RebuyContextProvider
-Open `/src/App.server.jsx` file and install the `RebuyContextProvider`, so all Rebuy API calls are enriched with contextual information.  Open the file and make the following edits:
-
-##### Import the provider
-```javascript
-import {RebuyContextProvider} from '@rebuy/rebuy-hydrogen/RebuyContextProvider.client';
-```
-
-##### Add RebuyContextProvider component
-Wrap the `<Route>` component with the `RebuyContextProvider`, as follows:
-```html
-<RebuyContextProvider>
-  <Route path="*" page={<NotFound />} />
-</RebuyContextProvider>
-```
-
-#### 4. Customize the Product Details Page
-Let's include our new components to the `ProductDetails` client component, located in `src/components/ProductDetails.client.jsx`. We will be wrapping our new components with a `RebuyWidgetContainer` components, which will give us an interface to request data from Rebuy.
-
-##### Import your new UI components
-Import the `ProductRecommendations` and `RecentlyViewedProducts` components in to the `ProductDetails.client.jsx` file.
-```javascript
-import ProductRecommendations from './ProductRecommendations';
-import RecentlyViewedProducts from './RecentlyViewedProducts';
-```
-
-##### Import Rebuy components
-Import the `RebuyWidgetContainer` and `RebuyProductViewed` components in to the `ProductDetails.client.jsx` file.
-```javascript
-import RebuyWidgetContainer from '@rebuy/rebuy-hydrogen/RebuyWidgetContainer.client';
-import RebuyProductViewed from '@rebuy/rebuy-hydrogen/RebuyProductViewed.client';
-```
-
-##### Add imported components in to the `ProductDetails` functional component
-Before the closing `</ProductOptionsProvider>` tag, insert our imported components:
-```html
-<RebuyWidgetContainer product={product} dataSource="/api/v1/products/recommended" limit="6">
-  <ProductRecommendations />
-</RebuyWidgetContainer>
-
-<RebuyWidgetContainer product={product} dataSource="/api/v1/products/viewed" limit="6">
-  <RecentlyViewedProducts />
-</RebuyWidgetContainer>
-
-<RebuyProductViewed product={product} />
-```
-
-##### Review your changes
-When you look at the product details page, you should now see two new sections:
-1. AI-powered product recommendations
-2. Recently viewed products
-
-Additionally, we included the `<RebuyProductViewed product={product} />` component, which will automatically send a `user -> viewed -> product` event to Rebuy.  This event is powering the recently viewed component in real-time!  As you navigate the site, your browsing history will be tracked and display for easy navigation to previous product pages!
-
-
-# Documentation
-Below you will find documentation on each of the components included in the Rebuy + Hydrogen package.
-
-## RebuyContextProvider
-The `RebuyContextProvider` is a React provider component.  It is responsible for collecting environment and state-based information as a `RebuyContext`.  It will gather information about the current URL, session UTM parameters, as well as cart information such as the cart token, subtotal, line items, etc.  As a provider component, no UI is rendered, it simply creates a React context value that can be requested by any child component.
-
-The `RebuyContextProvider` is a client component, which means it renders in the browser.  It has two dependencies, which are `useUrl` and `useCart`, so the component should be located high up in the component tree but **below** the `ShopifyProvider` and `CartProvider`.
-
-The recommended location is in `src/App.server.jsx` inside `<Router>` and wrapping **both** `<FileRoutes>` and the `<Route>` components, which makes the `RebuyContext` automatically available on all pages across the site.
-
-#### Import the RebuyContextProvider
-```javascript
-import {RebuyContextProvider} from '@rebuy/rebuy-hydrogen/RebuyContextProvider.client';
-```
-
-#### Wrap the Route compontent with RebuyContextProvider
-```html
-<Router>
-  <RebuyContextProvider>
-    <FileRoutes
-      basePath={countryCode ? `/${countryCode}/` : undefined}
-      routes={routes}
-    />
-    <Route path="*" page={<NotFound />} />
-  </RebuyContextProvider>
-</Router>
-```
-
-#### Access RebuyContext
-Rebuy + Hydrogen components will automatically include and use `RebuyContext`, but if you would like to use this context information in your own components, you certainly can!
-
-```javascript
-import React from 'react';
-import {RebuyContext} from '@rebuy/rebuy-hydrogen/RebuyContextProvider.client';
-
-// Access context parameters with React's useContext method
-const contextParameters = React.useContext(RebuyContext);
-```
-
-## RebuyWidgetContainer
-The `RebuyWidgetContainer` is a React container component. This component is responsible for fetching data and state management.  It does not render any UI components, and will pass along its properties and data received from Rebuy to all of their children components.  This abstraction allows you to use your existing application components or Rebuy's out of the box components.
-
-#### Component properties
-The component accepts argments via props to allow for different API responses.  All props listed below are optional, if no `dataSource` prop is provided then `'/api/v1/products/recommended'` will be used.
-
-| Property | Value |
-| -------- | ----- |
-| dataSource | `{String}` A relative URL path of your Rebuy data source (i.e. '/api/v1/products/recommended) |
-| product | `{Object}` A product object with an `id` |
-| productId | `{String}` A product ID string in graphQL URL format |
-| variant | `{Object}` A variant object with an `id` |
-| variantId | `{String}` A variant ID string in graphQL URL format |
-| collection | `{Object}` A collection object with an `id` |
-| collectionId | `{String}` A collection ID string in graphQL URL format |
-| limit | `{Number}` A number of products to return from Rebuy's API |
-| options | `{Object}` An object with key, value pairs of Rebuy REST API arguments (i.e. metafields: yes) |
-
-#### Children components properties
-All child components will inherit the container props, in addition to two container generated props `products` and `metadata`.  So if you've provided a `product={product}` prop to the container, then each child compontent will have the following properties `product`, `products`, and `metadata`.
-
-| Property | Value |
-| -------- | ----- |
-| products | `{Array}` An array of product objects returned from Rebuy's API |
-| metadata | `{Object}` An object with metadata about the input data, rules matched, rules not matched, excluded products, and cache info |
-
-#### Example implementation
-In the following example, we are using an example compontent called `ProductRecommendations` which is a UI component used to render data provided to it via props by the `RebuyWidgetContainer` component.
-
-When the components are rendered, it will display `6` products powered by Rebuy's AI algorithm based on the provided input `product`.  So if the input product was ketchup, you would likely see recommended products like mustard, mayo, or other condiments.
-
-```javascript
-import ProductRecommendations from './ProductRecommendations';
-import RebuyWidgetContainer from '@rebuy/rebuy-hydrogen/RebuyWidgetContainer.client';
-
- <RebuyWidgetContainer product={product} dataSource="/api/v1/products/recommended" limit="6">
-   <ProductRecommendations />
-</RebuyWidgetContainer>
-```
-
-## RebuyProductViewed
-The `RebuyProductViewed` is a client component, which helps automate customer browsing behavior.  This behavior is used to train the AI as well as power recently viewed products.  This component would typically live in your `ProductDetails` component, so as a customer is browsing your site we automatically record the product pages they are viewing.
-
-#### Component properties
-The component accepts argments via props to allow for registering different products that have been viewed. One of the following properties are required to fire the event.
-
-| Property | Value |
-| -------- | ----- |
-| product | `{Object}` A product object with an `id` |
-| productId | `{String}` A product ID string in graphQL URL format |
-| productHandle | `{String}` A product handle string |
-
-#### Example implementation
-The following example would be included in the `ProductDetails.client.jsx` component to automatically register customer product view events.  The current product displayed is passed to the `RebuyProductViewed` component via props as `product={product}`.
+Rebuy + Hydrogen uses a React container pattern to separate the data fetching logic and state management from the presentational components. As such, container components do not render user interface elements. They simply pass their own properties, as well as data received from Rebuy, to their children components for consumption. This allows you to build your own user interface with your existing components, or use Rebuy's out of the box components to get up and running quickly.
 
-```javascript
-import RebuyProductViewed from '@rebuy/rebuy-hydrogen/RebuyProductViewed.client';
+### Getting Started
 
-<RebuyProductViewed product={product} />
-```
+To get started, please visit our [Rebuy + Shopify Hydrogen documentation](https://developers.rebuyengine.com/reference/shopify-hydrogen-getting-started).

package/RebuyCompleteTheLook.client.jsx

@@ -0,0 +1,188 @@
+import {
+    AddToCartButton,
+    Image,
+    Link,
+    Money,
+    ProductOptionsProvider,
+    useMoney,
+} from '@shopify/hydrogen';
+import clsx from 'clsx';
+import { useState } from 'react';
+import { Section, Text } from '~/components';
+import { Button } from '~/components/elements';
+import { isDiscounted } from '~/lib/utils';
+
+const CompareAtPrice = ({ data, className }) => {
+    const { currencyNarrowSymbol, withoutTrailingZerosAndCurrency } =
+        useMoney(data);
+
+    const styles = clsx('strike', className);
+
+    return (
+        <span className={styles}>
+            {currencyNarrowSymbol}
+            {withoutTrailingZerosAndCurrency}
+        </span>
+    );
+};
+
+const AddToCartMarkup = ({
+    product,
+    selectedVariant = product.variants.nodes[0],
+}) => {
+    const isOutOfStock = !selectedVariant.availableForSale;
+
+    return (
+        <AddToCartButton
+            disabled={isOutOfStock}
+            variantId={selectedVariant?.id}
+            quantity={1}
+            accessibleAddingToCartLabel="Adding item to your cart"
+            type="button"
+            attributes={[
+                { key: '_source', value: 'Rebuy' },
+                { key: '_attribution', value: 'Product Recommendations' },
+            ]}
+        >
+            <Button
+                width="full"
+                variant={isOutOfStock ? 'secondary' : 'primary'}
+                as="span"
+                className="px-0"
+            >
+                {isOutOfStock ? 'Out of stock' : 'Add'}
+            </Button>
+        </AddToCartButton>
+    );
+};
+
+const RebuyProductPrice = ({ selectedVariant = {} }) => {
+    const { priceV2: price, compareAtPriceV2: compareAtPrice } =
+        selectedVariant;
+
+    return (
+        price && (
+            <div className="gap-4">
+                <Text className="flex gap-2">
+                    <Money withoutTrailingZeros data={price} />
+                    {isDiscounted(price, compareAtPrice) && (
+                        <CompareAtPrice
+                            className={'opacity-50'}
+                            data={compareAtPrice}
+                        />
+                    )}
+                </Text>
+            </div>
+        )
+    );
+};
+
+const VariantSelector = ({ product, handleSelectedVariant }) => {
+    return (
+        product?.variants.nodes.length > 1 && (
+            <div className="">
+                <select
+                    className="w-full py-1 rounded"
+                    name=""
+                    onChange={(e) =>
+                        handleSelectedVariant(product, e.target.value)
+                    }
+                >
+                    <optgroup label={getOptionsLabel(product)}>
+                        {product.variants.nodes.map(({ id, title }) => (
+                            <option key={id + '-variant'} value={id}>
+                                {title}
+                            </option>
+                        ))}
+                    </optgroup>
+                </select>
+            </div>
+        )
+    );
+};
+
+const getOptionsLabel = (product) => {
+    const options = product.variants.nodes[0].selectedOptions;
+    const optionsFromKeys = Object.keys(options[0]);
+    const optionsFromValues = options.map((option) => option.name);
+    const useValues = optionsFromKeys.every((key) =>
+        ['name', 'value'].includes(key)
+    );
+
+    // Return delimited label for available option(s) e.g. Color / Size, Scent, etc
+    return (useValues ? optionsFromValues : optionsFromKeys).join(' / ');
+};
+
+const RebuyProductCard = ({ product }) => {
+    const [selectedVariant, setSelectedVariant] = useState(
+        product.variants.nodes[0]
+    );
+    const { image } = selectedVariant;
+    const handleSelectedVariant = (product, variant_id) => {
+        const updatedVariant = product.variants.nodes.find(
+            (variant) => variant.id === variant_id
+        );
+
+        setSelectedVariant(updatedVariant);
+    };
+
+    return (
+        <div className="grid grid-cols-2 grid-rows-1 gap-6">
+            <Link to={`/products/${product.handle}`}>
+                {image && (
+                    <Image
+                        className="w-full object-cover fadeIn"
+                        data={image}
+                        alt={image.altText || `Picture of ${product.title}`}
+                    />
+                )}
+            </Link>
+            <div className="grid gap-1 items-start">
+                <Link to={`/products/${product.handle}`}>
+                    <Text>{product.title}</Text>
+                </Link>
+                <RebuyProductPrice selectedVariant={selectedVariant} />
+                <VariantSelector
+                    product={product}
+                    handleSelectedVariant={handleSelectedVariant}
+                />
+                <AddToCartMarkup
+                    product={product}
+                    selectedVariant={selectedVariant}
+                />
+            </div>
+        </div>
+    );
+};
+
+export const RebuyCompleteTheLook = ({
+    product = {},
+    products = [],
+    // eslint-disable-next-line no-unused-vars
+    metadata = {},
+    title = `These pair with ${product.title}`,
+    className = '',
+}) => {
+    const styles = clsx('', className);
+
+    return (
+        products.length > 0 && (
+            <Section heading={title} padding="n" className={styles}>
+                <ul className="grid gap-8">
+                    {products.map((product) => (
+                        <li key={product.id}>
+                            <ProductOptionsProvider
+                                data={product}
+                                initialVariantId={product.variants.nodes[0].id}
+                            >
+                                <RebuyProductCard product={product} />
+                            </ProductOptionsProvider>
+                        </li>
+                    ))}
+                </ul>
+            </Section>
+        )
+    );
+};
+
+export default RebuyCompleteTheLook;