@fast-simon/shopify-hydrogen 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# Fast Simon & Shopify Integration
+Build Search and Discovery experience with Fast Simon, a Shopify Plus Certified Partner
+
+[Getting started guide]('https://instantsearchplus.zendesk.com/hc/en-us/categories/360000839131-Getting-Started-with-Fast-Simon')
+
+
+# Hydrogen App
+Hydrogen is a React framework and SDK that you can use to build fast and dynamic Shopify custom storefronts.
+
+[Getting started guide]('https://shopify.dev/custom-storefronts/hydrogen')
+
+# Fast Simon For Shopify Hydrogen
+React NPM package to support Fast Simon Search and Discovery tools in Shopify Hydrogen Projects.
+
+# What is Fast Simon for Shopify Hydrogen?
+Fast Simon Shopify Hydrogen is a React library to be used in Shopify Hydrogen apps.
+
+By installing this library on your Hydrogen-based React Shopify storefront, you will be able to render Fast Simon Search and Discovery tools in your app.
+
+# Installation Guide
+This document will guide you to:
+* Configure your Shopify store ready for Fast Simon Shopify Hydrogen.
+* Install and use Fast Simon Shopify Hydrogen components in your Shopify Hydrogen app.
+
+### Requirements
+* Shopify store
+* Hydrogen app
+* Fast Simon app installed on your Shopify store
+* Shopify custom app with Storefront access token
+
+### Configure Hydrogen app config
+Update hydrogen.config.js with your shop's domain and Storefront API token.
+
+### Expose Shopify Metafields
+Fast Simon Search and Discovery uses Metafields in order to customize the UI based on Fast Simon No-code editor configuration.
+Metafields need to be exposed so that they can be retrieved by your Hydrogen app.
+
+Unfortunately, Shopify does not have a way of exposing Shop Metafields via their admin UI.
+
+We strongly recommend to contact Fast Simon Support, we will expose the relevant Metafields for you.
+
+# How to Use Fast Simon In Your Hydrogen App
+#### Installation
+
+1. In your Hydrogen app directory, run
+```shell
+npm install @fast-simon/shopify-hydrogen
+```
+2. Create ```fastsimon.config.json``` file in your root directory and fill it with your Fast Simon UUID & store id:
+```json
+{
+    "UUID": "",
+    "storeID": 0
+}
+```
+3. Open ```vite.config.ts``` and import the Fast Simon plugin:
+```typescript
+import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";
+```
+
+4. Add ```fastSimon()```to the list of plugins:
+```typescript
+  /// <reference types="vitest" />
+  import {defineConfig} from 'vite';
+  import hydrogen from '@shopify/hydrogen/plugin';
+  import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";
+  
+  export default defineConfig({
+      plugins: [hydrogen(), fastSimonPlugin()],
+      resolve: {
+          alias: [{find: /^~\/(.*)/, replacement: '/src/$1'}],
+      },
+      optimizeDeps: {
+          include: ['@headlessui/react', 'clsx', 'react-use', 'typographic-base'],
+      },
+      test: {
+          globals: true,
+          testTimeout: 10000,
+          hookTimeout: 10000,
+      },
+      server: {
+          port: 5000
+      },
+  });
+```
+
+5. Open App.server.tsx and import ```FastSimonProviderServer```:
+```typescript
+import fastSimonPlugin from "@fast-simon/shopify-hydrogen/plugin";
+```
+
+6. Include the ```FastSimonProviderServer```, passing through the request object, UUID and store id from your ```fastsimon.config.json file```:
+```jsx
+  function App({request}) {
+      const pathname = new URL(request.normalizedUrl).pathname;
+      const localeMatch = /^\/([a-z]{2})(\/|$)/i.exec(pathname);
+      const countryCode = localeMatch ? localeMatch[1] : undefined;
+      const isHome = pathname === `/${countryCode ? countryCode + '/' : ''}`;
+  
+      return (
+          <Suspense fallback={<HeaderFallback isHome={isHome} />}>
+              <ShopifyProvider countryCode={countryCode}>
+                  <FastSimonProviderServer storeID={fastConfig.storeID} uuid={fastConfig.UUID} request={request}>
+                      <CartProvider countryCode={countryCode}>
+                          <Suspense>
+                              <DefaultSeo />
+                          </Suspense>
+                          <Router>
+                              <FileRoutes
+                                  basePath={countryCode ? `/${countryCode}/` : undefined}
+                              />
+                              <Route path="*" page={<NotFound />} />
+                          </Router>
+                      </CartProvider>
+                      <PerformanceMetrics />
+                      {import.meta.env.DEV && <PerformanceMetricsDebug />}
+                      <ShopifyAnalytics />
+                  </FastSimonProviderServer>
+              </ShopifyProvider>
+          </Suspense>
+      );
+  }
+
+```
+You can also provide your UUID and storeID directly instead of creating the ```fastsimon.config.json```
+
+### Usage
+##### Collections:
+1. Open ```src/routes/collections/[handle].server.jsx``` and import ```FastSimonAppServer```:
+```typescript
+import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";
+```
+2. To the collection handler function, add ```fastSimonProps``` parameter:
+```jsx
+export default function Collection({params, fastSimonProps}) {...}
+```
+
+3. Replace the Shopify Grid component by ```FastSimonAppServer```, pass ```collectionID``` and ```fastSimonProps``` as shown below.
+```jsx
+    <Layout>
+        <Suspense>
+            <Seo type="collection" data={collection} />
+        </Suspense>
+        <PageHeader heading={collection.title}>
+            {collection?.description && (
+                <div className="flex items-baseline justify-between w-full">
+                    <div>
+                        <Text format width="narrow" as="p" className="inline-block">
+                            {collection.description}
+                        </Text>
+                    </div>
+                </div>
+            )}
+        </PageHeader>
+        <Section>
+            <FastSimonAppServer collectionID={collection.id} fastSimonProps={fastSimonProps}/>
+        </Section>
+    </Layout>
+```
+
+##### Search Page:
+1. Open ```src/routes/search.server.jsx``` and import ```FastSimonAppServer```:
+```typescript
+import {FastSimonAppServer} from "@fast-simon/shopify-hydrogen";
+```
+2. To the search handler function, add ```fastSimonProps``` parameter:
+```jsx
+export default function Search({pageBy = PAGINATION_SIZE, params, fastSimonProps}) {...}
+```
+
+3. Replace the Shopify Grid component by ```FastSimonAppServer```, pass ```query``` and ```fastSimonProps``` as shown below.
+```jsx 
+  return (
+    <SearchPage searchTerm={decodeURI(searchTerm)}>
+        <Section>
+            <FastSimonAppServer query={decodeURI(searchTerm)} fastSimonProps={fastSimonProps}/>
+        </Section>
+    </SearchPage>
+);
+```

package/dist/esnext/@types/Tab.d.ts

@@ -0,0 +1,9 @@
+export declare enum TabType {
+    Products = 0,
+    Articles = 1
+}
+export interface Tab {
+    label: string;
+    value: TabType;
+    totalResults: number;
+}

package/dist/esnext/@types/Tab.js

@@ -0,0 +1,5 @@
+export var TabType;
+(function (TabType) {
+    TabType[TabType["Products"] = 0] = "Products";
+    TabType[TabType["Articles"] = 1] = "Articles";
+})(TabType || (TabType = {}));

package/dist/esnext/@types/appServerProps.d.ts

@@ -0,0 +1,12 @@
+import type { SortBy } from "./sortBy";
+import type { Narrow } from "./narrow";
+export interface AppServerProps {
+    page?: number;
+    sortBy?: SortBy;
+    narrow?: Narrow;
+    searchWithinSearch?: string;
+    query?: string;
+    collectionID?: string;
+    narrowString?: string;
+    deviceMode?: string;
+}

package/dist/esnext/@types/appServerProps.js

@@ -0,0 +1 @@
+export {};

package/dist/esnext/@types/articles.d.ts

@@ -0,0 +1,12 @@
+export declare type ArticleServerItem = [ArticleTitle, ArticleURL, ArticleDescription, null, ArticleImage];
+declare type ArticleTitle = string;
+declare type ArticleURL = string;
+declare type ArticleDescription = string | null;
+declare type ArticleImage = string | null;
+export interface Article {
+    title: string;
+    url: string;
+    description: string;
+    image: string;
+}
+export {};

package/dist/esnext/@types/articles.js

@@ -0,0 +1 @@
+export {};

package/dist/esnext/@types/categories.d.ts

@@ -0,0 +1,10 @@
+export declare type AncestorCategory = [string, string, string];
+export interface Category {
+    d: string;
+    id: string;
+    l: string;
+    p_id: string;
+    t: string;
+    u: string;
+    parent_name?: string;
+}

package/dist/esnext/@types/categories.js

@@ -0,0 +1 @@
+export {};

package/dist/esnext/@types/currency.d.ts

@@ -0,0 +1 @@
+export declare type Currency = string | 'USD' | 'CRC' | 'AUD' | 'AZN' | 'NZD' | 'CAD' | 'VES' | 'SGD' | 'COP' | 'GBP' | 'BRL' | 'ILS' | 'AED' | 'JMD' | 'MYR' | 'THB' | 'DKK' | 'EGP' | 'NOK' | 'SEK' | 'HKD' | 'ZAR' | 'CHF' | 'HRK' | 'INR' | 'UAH' | 'RUB' | 'BYR' | 'IRR' | 'MXN' | 'TWD' | 'TRY' | 'TRL' | 'TL' | 'PLN' | 'HUF' | 'BGN' | 'EUR' | 'NGN' | 'RON' | 'VND' | 'BDT' | 'XOF' | 'JPY' | 'CNY' | 'KRW' | 'ARS';

package/dist/esnext/@types/currency.js

@@ -0,0 +1 @@
+export {};

package/dist/esnext/@types/device.d.ts

@@ -0,0 +1 @@
+export declare type Device = 'mobile' | 'desktop' | 'tablet';

package/dist/esnext/@types/device.js

@@ -0,0 +1 @@
+export {};

package/dist/esnext/@types/editor.d.ts

@@ -0,0 +1,416 @@
+import type { SortBy } from "./sortBy";
+export interface GridPosition {
+    row: number;
+    numOfCols: number;
+    areaName: string;
+}
+export interface FontSettings {
+    fontSize: string;
+    fontWeight: string;
+    font: string;
+    textAlign: string;
+    lineHeight: string;
+    letterSpacing: string;
+}
+export interface DimensionsSettings {
+    x: string;
+    y: string;
+    width: string;
+    height: string;
+}
+export interface ProductTitleSettings {
+    isActive: boolean;
+    font: FontSettings;
+    dimensions: DimensionsSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    numberOfLines: string;
+    color: string;
+    saveSpaceForLineClamp: boolean;
+}
+export interface ProductPriceSettings {
+    isActive: boolean;
+    font: FontSettings;
+    dimensions: DimensionsSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    colorIfCompareEnable: string;
+    color: string;
+    shadow: string;
+    alignIfCompare: 'left' | 'center' | 'right';
+    currency: string;
+}
+export interface ProductComparePriceSettings {
+    isActive: boolean;
+    font: FontSettings;
+    dimensions: DimensionsSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    color: string;
+    shadow: string;
+}
+export interface ProductReviewsSettings {
+    isActive: boolean;
+    font: FontSettings;
+    size: string;
+    margin: string;
+    color: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    reviewsCount: boolean;
+    shadow: string;
+    widgetForNoReview: boolean;
+    noReviewsStarsColor: string;
+}
+export interface ProductAddToCartSettings {
+    isActive: boolean;
+    margin: string;
+    gridPosition: GridPosition;
+    addToCartType: 'product level' | 'variant level';
+    font: FontSettings;
+    text: string;
+    dimensions: DimensionsSettings;
+    ajaxAnimation: boolean;
+    backgroundColor: string;
+    color: string;
+    border: string;
+    borderRadius: string;
+    shadow: string;
+    showOnHover: boolean;
+    changeColorsOnHover: boolean;
+    backgroundColorOnHover: string;
+    textColorsOnHover: string;
+    borderColorOnHover: string;
+    addToCartPosition: 'product bottom' | 'image bottom';
+    quantitySelector: boolean;
+}
+export interface ProductBackInStockSettings {
+    isActive: boolean;
+    margin: string;
+    gridPosition: GridPosition;
+    font: FontSettings;
+    text: string;
+    dimensions: DimensionsSettings;
+    backgroundColor: string;
+    color: string;
+    border: string;
+    borderRadius: string;
+    shadow: string;
+    showOnHover: boolean;
+    changeColorsOnHover: boolean;
+    backgroundColorOnHover: string;
+    textColorsOnHover: string;
+    borderColorOnHover: string;
+    backInStockPosition: 'product bottom' | 'image bottom';
+}
+export interface ProductSKUSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    color: string;
+    shadow: string;
+}
+export interface ProductDescriptionSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    numberOfLines: string;
+    color: string;
+    shadow: string;
+    saveSpaceForLineClamp: boolean;
+}
+export interface ProductStockBadgeSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    text: string;
+    border: string;
+    borderRadius: string;
+    dimensions: DimensionsSettings;
+    color: string;
+    backgroundColor: string;
+    shadow: string;
+}
+export interface ProductVendorSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    color: string;
+    shadow: string;
+}
+export interface ProductWishlistSettings {
+    isActive: boolean;
+    size: string;
+    margin: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    location: 'on-image' | 'in-info';
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    padding: string;
+    notCheckedColor: string;
+    checkedColor: string;
+    isCustomIcon: boolean;
+    checkedIconName: string;
+    notCheckedIconName: string;
+}
+export interface ProductQuickViewSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    text: string;
+    border: string;
+    borderRadius: string;
+    dimensions: DimensionsSettings;
+    theme: 'modern' | 'classic';
+    color: string;
+    backgroundColor: string;
+}
+export interface ProductLookALikeSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    gridPosition: GridPosition;
+    text: string;
+    border: string;
+    borderRadius: string;
+    dimensions: DimensionsSettings;
+    color: string;
+    backgroundColor: string;
+}
+export declare enum SwatchType {
+    Color = 0,
+    Image = 1,
+    Text = 2
+}
+export interface ProductColorSwatchesSettings {
+    isActive: boolean;
+    margin: string;
+    gridPosition: GridPosition;
+    dimensions: DimensionsSettings;
+    maxSwatches: number;
+    swatchesType: SwatchType;
+    changeVariantOnHover: boolean;
+}
+export interface ProductStyles {
+    border: string;
+    backgroundColor: string;
+    shadow: string;
+}
+export interface PageTitleSettings {
+    isActive: boolean;
+    font: FontSettings;
+    margin: string;
+    dimensions: DimensionsSettings;
+    numberOfLines: string;
+    color: string;
+}
+export interface ProductInfo {
+    padding: string;
+    gridAreas: string;
+}
+export interface ProductSettings {
+    border: string;
+    borderRadius: string;
+    backgroundColor: string;
+    shadow: string;
+    imageRatio: number;
+    imageFit: string;
+    padding: string;
+    imageLoadingType: string;
+    imageCarousel: 'auto' | 'arrows' | false;
+    isCustomCarouselIcons: boolean;
+    leftArrowIconName: string;
+    leftArrowSlideDirection: 'left' | 'right';
+    rightArrowSlideDirection: 'left' | 'right';
+    rightArrowIconName: string;
+    showBorderOnHover: boolean;
+    info: ProductInfo;
+    dimensions: DimensionsSettings;
+    title: ProductTitleSettings;
+    price: ProductPriceSettings;
+    compare: ProductComparePriceSettings;
+    reviews: ProductReviewsSettings;
+    addToCart: ProductAddToCartSettings;
+    description: ProductDescriptionSettings;
+    inStock: ProductStockBadgeSettings;
+    outOfStock: ProductStockBadgeSettings;
+    vendor: ProductVendorSettings;
+    wishList: ProductWishlistSettings;
+    quickView: ProductQuickViewSettings;
+    lookALike: ProductLookALikeSettings;
+    colorSwatches: ProductColorSwatchesSettings;
+    sku: ProductSKUSettings;
+    backInStock: ProductBackInStockSettings;
+}
+export interface Pagination {
+    paginationType: 'pagination' | 'infinite scroll';
+    loadMore: boolean;
+    loadMoreAfter: number;
+    paginationProgress: boolean;
+    progressBarColor: string;
+    isCustomIcon: boolean;
+    leftArrowIcon: string;
+    rightArrowIcon: string;
+}
+export interface ScrollToTopSettings {
+    active: boolean;
+    text: string;
+    backgroundColor: string;
+    textColor: string;
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+    isCustomIcon: boolean;
+    iconName: string;
+    iconPosition: 'left' | 'right';
+}
+export interface ProductsGridSettings {
+    product: ProductSettings;
+    pageTitle: PageTitleSettings;
+    pagination: Pagination;
+    quickViewModal: QuickViewModalSettings;
+    numberOfColumns: string;
+    numberOfRows: string;
+    backgroundColor: string;
+    font: FontSettings;
+    gridColumnGap: string;
+    gridRowGap: string;
+    pagePadding: string;
+    gridViewButton: boolean;
+    isGridViewCustomIcon: boolean;
+    gridViewIcon: string;
+    listViewIcon: string;
+    scrollToTopSettings?: ScrollToTopSettings;
+}
+export interface RemovableTagsSettings {
+    isActive: boolean;
+    font: FontSettings;
+    dimensions: DimensionsSettings;
+    color: string;
+    backgroundColor: string;
+    shadow: string;
+    border: string;
+    borderRadius: string;
+    onTopPage: boolean;
+    inFilters: boolean;
+}
+export interface SearchWithinFiltersSettings {
+    isActive: boolean;
+    border: string;
+    borderRadius: string;
+    placeHolder: string;
+    dimensions: DimensionsSettings;
+    color: string;
+    backgroundColor: string;
+    shadow: string;
+}
+export interface SearchWithinResultsSettings {
+    isActive: boolean;
+    border: string;
+    borderRadius: string;
+    placeHolder: string;
+    dimensions: DimensionsSettings;
+    color: string;
+    backgroundColor: string;
+    shadow: string;
+}
+export interface ShowHideFiltersButtonSettings {
+    isActive: boolean;
+    border: string;
+    borderRadius: string;
+    text: string;
+    color: string;
+    dimensions: DimensionsSettings;
+    backgroundColor: string;
+    shadow: string;
+    font: FontSettings;
+}
+export declare type FiltersLayout = 'classic' | 'modern' | 'vertical' | 'dropdown' | 'collapsed';
+export interface FiltersSettings {
+    isActive: boolean;
+    layout: FiltersLayout;
+    optionsColor: string;
+    titlesColor: string;
+    optionsFont: FontSettings;
+    titlesFont: FontSettings;
+    titlesBackground: string;
+    backgroundColor: string;
+    priceFilterSlider: boolean;
+    showMoreButton: boolean;
+    colorsFilter: 'swatches' | 'checkboxes';
+    removableTags: RemovableTagsSettings;
+    searchWithinFilters: SearchWithinFiltersSettings;
+    searchWithinResults: SearchWithinResultsSettings;
+    showHideFiltersButton: ShowHideFiltersButtonSettings;
+    filtersTopBar: boolean;
+    numberOfOpenFacets: number | "all";
+    isCustomIcon: boolean;
+    filtersButtonCustomIconName: string;
+}
+export interface SearchBoxSettings {
+    isActive: boolean;
+    border: string;
+    borderRadius: string;
+    placeHolder: string;
+    dimensions: DimensionsSettings;
+}
+export interface SortingOption {
+    backendName: SortBy;
+    customName: string;
+    active: boolean;
+}
+export interface SearchResultsSortingSettings {
+    isActive: boolean;
+    sortOptions: SortBy[];
+    defaultOption: SortBy;
+    dimensions: DimensionsSettings;
+    sortingOptions: SortingOption[];
+    mobileLayout: "classic" | "modern" | "in-filters";
+    optionsFont: FontSettings;
+    optionsColor: string;
+    optionsHeight: string;
+    selectedBackground: string;
+    titleFont: FontSettings;
+    titleColor: string;
+    titleHeight: string;
+    modalHeight: string;
+    modalBorderRadius: string;
+    modalBackground: string;
+    isCustomIcon: boolean;
+    sortingButtonCustomIconName: string;
+}
+export interface CollectionsSettings {
+    categoriesWheelsOnSerp: boolean;
+    categoriesWheelsOnCollections: boolean;
+    wheelSize: number;
+    numberOfWheelTitleLines: number;
+    isCustomCarouselIcons: boolean;
+    leftArrowIconName: string;
+    rightArrowIconName: string;
+}
+export interface QuickViewModalSettings {
+    openingDirection: "top to bottom" | "left to right" | "bottom to top" | "right to left";
+    animationInY: number;
+    animationInX: number;
+    animationOutY: number;
+    animationOutX: number;
+    animationDuration: number;
+    width: string;
+    height: string;
+    imagesBar: boolean;
+}
+export interface ProductGridEditorSettings {
+    productGrid: ProductsGridSettings;
+    filters: FiltersSettings;
+    searchBox: SearchBoxSettings;
+    sorting: SearchResultsSortingSettings;
+    collections: CollectionsSettings;
+}

package/dist/esnext/@types/editor.js

@@ -0,0 +1,6 @@
+export var SwatchType;
+(function (SwatchType) {
+    SwatchType[SwatchType["Color"] = 0] = "Color";
+    SwatchType[SwatchType["Image"] = 1] = "Image";
+    SwatchType[SwatchType["Text"] = 2] = "Text";
+})(SwatchType || (SwatchType = {}));