@bikematrix/web-components 1.0.18 → 1.1.1

package/README.md

@@ -1,9 +1,14 @@
 # Bike Matrix Web Components
 
-A web component library for integrating bike matrix compatibility checking into your e-commerce platform.
+Our Mission is to transform the bicycle industry by offering a comprehensive compatibility solution to all retailers, service providers, manufacturers, and riders, by seamlessly connecting replacement parts to a specific bike.
+
+Using the Bike Matrix Web Components allows any web application to provide its users the accurate selection of a bike from our database of over 50,000 Bikes by Brand, Model, Spec, Year and Size. The web application can then run a series of complex compatibility algorithms over the nominated EAN, UPC or Manufacturer Part Number, returning a Compatibility Result with messages for display to your users for the selected bike and component.
+
+![Bike Matrix Compatibility](https://raw.githubusercontent.com/bikematrix/assets/main/files/compatibility_indicator.jpg)
 
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
 - [Configuration](#configuration)
@@ -17,6 +22,48 @@ A web component library for integrating bike matrix compatibility checking into
 - [Framework Integration](#framework-integration)
 - [Common Scenarios](#common-scenarios)
 
+## Introduction
+
+Bike Matrix is a compatibility solution that answers the question, which parts fit this bike?
+We provide the ability for a user to select a bike and see which parts, from your available products, are suitable replacement or upgrades by processing mechanic-led, component-level compatibility assessment on the products being viewed, searched or filtered.
+
+The Web Components are pre-built Javascript components that can quickly be placed on your website and can provide you with the list of bikes that we have in our database and, along with images, can allow a user to easily select their bike. We have over 50,000 Bikes by Brand, Make, Model, Spec, Year and Size and are currently working to enrich the data of the remaining 100,000+ bikes in our dataset.
+
+We have built up a comprehensive database of components such as Brake Pads, Tyres, Tubes, Brake Rotors, Wheels, Chains, Cassettes, Headsets and many more.
+
+As part of the Onboarding process, it is important to talk to us to check that the products on your website that you would like to show compatibility for, are in our database. If the product does not exist in our database just provide us with the information we might need to get the product set up.
+
+We use internationally recognised EAN or UPC barcodes, or the Original Manufacturer’s Part Number to identify products being assessed for compatibility. It is imperative that one of these three product identifiers is used. We use this product SKU to determine the Product Category, and therefore the compatibility logic to apply.
+
+![Product Result](https://raw.githubusercontent.com/bikematrix/assets/main/files/product_result.jpg)
+
+To check if a product is compatible with a specific Bike we first need to guide the user towards finding the exact bike, via our Bike Selector using the following taxonomy: Brand, Model Family, Model Spec, Bike Spec, Year and Size.
+
+* Brand is the Bike Brand that makes the Bike.
+* Model Family refers to the high-level name of the Model within the Brand’s portfolio, such as Domane (Trek), Trance (Giant) or Scultura (Merida).
+* Model Spec (sometimes referred to as Frame Spec) is the name for the different frame specifications within a Model Family. It could be that there is only AL(alloy), or perhaps there is Alloy and Carbon or it could be AL, CF, CF SL and CF SLX (eg Canyon).
+* Bike Spec is the ‘spec level’ of each specific Models and can take many forms and include groupset names. It usually contains a number such as 3, 2, 1, and 0 or 200, 400, 500 or it can have Comp, Expert, Pro labels depending on the Brand and Model Family.
+* Year is an obvious one, but the selection of year can change the list of Bike Spec or Model Spec that were available for a given Model Family.
+* Size will depend on the bike brand model and year and can take several forms, S, M, L in some cases, 15”, 16”, 17” in others. Sometimes it’s Short and Long, or S1, S2, S3, S4 (eg Specialized) and for kids bikes we tend to refer to the wheelsize.
+
+![Bike Selector](https://raw.githubusercontent.com/bikematrix/assets/main/files/bike_selector.jpg)
+
+We’ve put considerable effort into designing a Bike Selector that we think guides the user to the correct bike in an easy to understand manner. Unfortunately, some bikes are just confusing, and some customers don’t immediately know which bike they have. 
+
+![Bike Selector](https://raw.githubusercontent.com/bikematrix/assets/main/files/bike_selector2.jpg)
+
+The other consideration that is very important to us is our Brand Representation. A condition of signing a licence to use Bike Matrix APIs, is the requirement to incorporate our Compatibility Indicators and the “Powered by Bike Matrix” link.
+
+The Compatibility Indicators are the graphic representations of Green (Compatible), Amber (Compatible with Conditions) and Red (Not Compatible) on both the Collection or Product Landing Page (PLP), and also on the Product Details Page (PDP). Again, these are all built into the Bike Matrix Web Components.
+
+By standardising the look and feel of the compatibility results across all websites, trust is built and confidence is increased, which results in increased conversions. This is also why we recommend locating the Compatibility Indicators close to the Buy Now or Add to Cart buttons, as it will form an important part of the buying journey.
+
+![Compatibility Indicators](https://raw.githubusercontent.com/bikematrix/assets/main/files/compatibility_indicators.jpg)
+
+## Obtaining API Credentials
+
+The Web Components require access to the Bike Matrix API. To request access to the Bike Matrix API send us an email at adamb@bikematrix.io and we will create your subscription and provide you with access to our staging APIs allowing you to explore and test functionality. When you’re ready, we can activate your licence and provide access to the entire bike database through the Production API. Depending on your deployment scenario we will provide an API Key or we will add your environments information to our whitelist.
+
 ## Installation
 
 You can install Bike Matrix Web Components using either npm or by including it directly via CDN.
@@ -40,10 +87,12 @@ Alternatively, include the script directly in your HTML:
 ```html
 <script
   type="text/javascript"
-  src="https://cdn.jsdelivr.net/npm/@bikematrix/web-components/dist/bm_core.js"
+  src="https://cdn.jsdelivr.net/npm/@bikematrix/web-components@1.1/dist/bm_core.js"
 ></script>
 ```
 
+Note: Replace version `1.1` in the above URL with the latest version number, or the specific version you want to use.
+
 ## Getting Started
 
 Follow these steps to quickly integrate BikeMatrix into your website:
@@ -71,10 +120,12 @@ Include the script directly in your HTML:
 ```html
 <script
   type="text/javascript"
-  src="https://cdn.jsdelivr.net/npm/@bikematrix/web-components/dist/bm_core.js"
+  src="https://cdn.jsdelivr.net/npm/@bikematrix/web-components@1.1/dist/bm_core.js"
 ></script>
 ```
 
+Note: Replace version `1.1` in the above URL with the latest version number, or the specific version you want to use.
+
 ### 2. Configure BikeMatrix
 
 Add the core configuration block to your HTML:

package/dist/bm_core.es.js

@@ -1236,9 +1236,9 @@ function Ga(t) {
     return de(t);
   }, []);
 }
-const Gt = de(!1), M = de(null), De = de([]), re = de(!1), Ee = de([]), oe = de(!1), Ka = () => {
+const Gt = de(!1), M = de(null), Se = de([]), re = de(!1), Ee = de([]), oe = de(!1), Ka = () => {
   Ma(() => {
-    M.value = null, De.value = [], re.value = !1, Ee.value = [], oe.value = !1;
+    M.value = null, Se.value = [], re.value = !1, Ee.value = [], oe.value = !1;
   });
 }, zo = "bm_currentBike", Ja = "v2", Ya = "https://cdn.bikematrix.io", Pr = {
   // Shopify specific
@@ -3746,7 +3746,10 @@ class St {
         body: JSON.stringify(r),
         method: "POST",
         headers: {
-          "Content-Type": "application/json"
+          "Content-Type": "application/json",
+          ...this._apiKey && {
+            "bm-subscription-key": this._apiKey
+          }
         },
         ...a
       });
@@ -3932,7 +3935,7 @@ const Io = class Me {
     this.currentBike === null ? (e = window.bm_selectBikeButton) == null || e.classList.remove("show-selected") : (r = window.bm_selectBikeButton) == null || r.classList.add("show-selected");
   }
   ChangeBike() {
-    this.config.logLevel === "verbose" && console.log("ChangeBike() Method Called"), !(re.value === !0 || oe.value === !0) && (re.value = !0, oe.value = !0, De.value = [], Ee.value = [], console.log("ChangeBike updateBikeSignal..."), this.updateBikeSignal().then(() => {
+    this.config.logLevel === "verbose" && console.log("ChangeBike() Method Called"), !(re.value === !0 || oe.value === !0) && (re.value = !0, oe.value = !0, Se.value = [], Ee.value = [], console.log("ChangeBike updateBikeSignal..."), this.updateBikeSignal().then(() => {
       this.config.logLevel === "verbose" && console.log("Bike Signal Updated: ", JSON.stringify(M.value, null, 2)), this.ResetSelectedBikeIndicator(), this.RefreshCompatibleSkus().then(() => {
         document.dispatchEvent(new Event("RefreshCompatibility", {
           bubbles: !0,
@@ -3977,7 +3980,7 @@ const Io = class Me {
     var a, i;
     var r = JSON.parse(sessionStorage.getItem(e));
     if (r)
-      this.config.logLevel === "verbose" && console.log("Refresh Collection SKUs from Session: ", JSON.stringify(r), null, 2), De.value = r;
+      this.config.logLevel === "verbose" && console.log("Refresh Collection SKUs from Session: ", JSON.stringify(r), null, 2), Se.value = r;
     else {
       const n = Object.values(this.config.products || {}).map((p) => p.skus).flat();
       this.config.logLevel === "verbose" && console.log("Refresh Collection SKUs from API. SKUs: ", JSON.stringify(n), null, 2);
@@ -3994,7 +3997,7 @@ const Io = class Me {
           console.log("function RefreshCompatibleSkus() operation aborted");
           return;
         }
-        sessionStorage.setItem(e, JSON.stringify(p)), De.value = p;
+        sessionStorage.setItem(e, JSON.stringify(p)), Se.value = p;
       } catch (p) {
         p.name === "AbortError" ? console.log("function RefreshCompatibleSkus() fetch aborted") : console.error("function RefreshCompatibleSkus() fetch error", p);
       } finally {
@@ -5332,7 +5335,7 @@ function Ko({
     })]
   }) : d(q, {});
 }
-const Se = {
+const Be = {
   unavailable: {
     heading: ""
   },
@@ -5354,7 +5357,7 @@ const Yi = async (t, e, r) => {
   if (!r || !Ee.value) {
     ie = {
       type: "unavailable",
-      ...Se.unavailable
+      ...Be.unavailable
     };
     return;
   }
@@ -5367,16 +5370,16 @@ const Yi = async (t, e, r) => {
   const a = o.every((s) => (s == null ? void 0 : s.compatible) === !1), i = o.some((s) => (s == null ? void 0 : s.compatible) === !0 && s.warning === !0), n = o.some((s) => (s == null ? void 0 : s.compatible) === !0);
   o.some((s) => (s == null ? void 0 : s.compatible) === null), i ? ie = {
     type: "warning",
-    ...Se.warning
+    ...Be.warning
   } : n ? ie = {
     type: "compatible",
-    ...Se.compatible
+    ...Be.compatible
   } : a ? ie = {
     type: "incompatible",
-    ...Se.incompatible
+    ...Be.incompatible
   } : ie = {
     type: "unavailable",
-    ...Se.unavailable
+    ...Be.unavailable
   };
 }, Wi = function(t, e, r, o, a, i, n) {
   var u;
@@ -5400,7 +5403,7 @@ function Zi({
   const a = window.BikeMatrix, i = a.getConfig(), [n, s] = Q(!1), u = !!a.getActiveSubscription();
   ie = {
     type: "unavailable",
-    ...Se.unavailable
+    ...Be.unavailable
   };
   const {
     currentCollectionHandle: l,
@@ -5659,15 +5662,14 @@ function nn({
       i(!1);
       return;
     }
-    console.log("CompatibleCollectionSkusSignal.value", De.value);
-    const B = rn(De.value).map(x);
+    const B = rn(Se.value).map(x);
     c(B);
     const z = on(y, B);
     l(z), i(!0);
   }, [
     _,
     M.value,
-    De.value,
+    Se.value,
     re.value,
     // compatibleProducts,
     y
@@ -5997,7 +5999,7 @@ const Ue = () => {
   for (const o in e)
     o !== "__proto__" && o !== "constructor" && (o in t ? typeof t[o] == "string" || t[o] instanceof String || typeof e[o] == "string" || e[o] instanceof String ? r && (t[o] = e[o]) : Yo(t[o], e[o], r) : t[o] = e[o]);
   return t;
-}, Ae = (t) => t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&");
+}, De = (t) => t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&");
 var hn = {
   "&": "&",
   "<": "&lt;",
@@ -6695,7 +6697,7 @@ class Bn {
       maxReplaces: k,
       alwaysFormat: b
     } = e.interpolation;
-    this.escape = r !== void 0 ? r : bn, this.escapeValue = o !== void 0 ? o : !0, this.useRawValueToEscape = a !== void 0 ? a : !1, this.prefix = i ? Ae(i) : n || "{{", this.suffix = s ? Ae(s) : u || "}}", this.formatSeparator = l || ",", this.unescapePrefix = p ? "" : c || "-", this.unescapeSuffix = this.unescapePrefix ? "" : p || "", this.nestingPrefix = g ? Ae(g) : f || Ae("$t("), this.nestingSuffix = _ ? Ae(_) : m || Ae(")"), this.nestingOptionsSeparator = y || ",", this.maxReplaces = k || 1e3, this.alwaysFormat = b !== void 0 ? b : !1, this.resetRegExp();
+    this.escape = r !== void 0 ? r : bn, this.escapeValue = o !== void 0 ? o : !0, this.useRawValueToEscape = a !== void 0 ? a : !1, this.prefix = i ? De(i) : n || "{{", this.suffix = s ? De(s) : u || "}}", this.formatSeparator = l || ",", this.unescapePrefix = p ? "" : c || "-", this.unescapeSuffix = this.unescapePrefix ? "" : p || "", this.nestingPrefix = g ? De(g) : f || De("$t("), this.nestingSuffix = _ ? De(_) : m || De(")"), this.nestingOptionsSeparator = y || ",", this.maxReplaces = k || 1e3, this.alwaysFormat = b !== void 0 ? b : !1, this.resetRegExp();
   }
   reset() {
     this.options && this.init(this.options);
@@ -6811,7 +6813,7 @@ const Sn = (t) => {
     formatName: e,
     formatOptions: r
   };
-}, Be = (t) => {
+}, Ae = (t) => {
   const e = {};
   return (r, o, a) => {
     let i = a;
@@ -6828,32 +6830,32 @@ class En {
   constructor() {
     let e = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     this.logger = ue.create("formatter"), this.options = e, this.formats = {
-      number: Be((r, o) => {
+      number: Ae((r, o) => {
         const a = new Intl.NumberFormat(r, {
           ...o
         });
         return (i) => a.format(i);
       }),
-      currency: Be((r, o) => {
+      currency: Ae((r, o) => {
         const a = new Intl.NumberFormat(r, {
           ...o,
           style: "currency"
         });
         return (i) => a.format(i);
       }),
-      datetime: Be((r, o) => {
+      datetime: Ae((r, o) => {
         const a = new Intl.DateTimeFormat(r, {
           ...o
         });
         return (i) => a.format(i);
       }),
-      relativetime: Be((r, o) => {
+      relativetime: Ae((r, o) => {
         const a = new Intl.RelativeTimeFormat(r, {
           ...o
         });
         return (i) => a.format(i, o.range || "day");
       }),
-      list: Be((r, o) => {
+      list: Ae((r, o) => {
         const a = new Intl.ListFormat(r, {
           ...o
         });
@@ -6871,7 +6873,7 @@ class En {
     this.formats[e.toLowerCase().trim()] = r;
   }
   addCached(e, r) {
-    this.formats[e.toLowerCase().trim()] = Be(r);
+    this.formats[e.toLowerCase().trim()] = Ae(r);
   }
   format(e, r, o) {
     let a = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : {};