@tulipnpm/timekit_project_selector 2.0.5 → 2.0.8-rc.0

package/README.md

@@ -1,6 +1,6 @@
-# TimeKit Project Selector
+# Tulip Appointments Web Widget
 
-The TimeKit Project Selector is a library that extends the functionality of [TimeKit's Booking Widget](https://developers.timekit.io/docs/booking-widget-v2). This library allows users to set up selectors based on project metadata, which will filter down a list of TimeKit projects for a customer to book with. The library has a default UI that embeds on an e-commerce site that can either be customized or overwritten.
+The Tulip Appointments Web Widget is a library that extends the functionality of [TimeKit's Booking Widget](https://developers.timekit.io/docs/booking-widget-v2). This library allows users to set up selectors based on project metadata, which will filter down a list of TimeKit projects for a customer to book with. The library has a default UI that embeds on an e-commerce site that can either be customized or overwritten.
 
 ## Installation
 
@@ -12,7 +12,7 @@ The TimeKit Project Selector is a library that extends the functionality of [Tim
 
 ## Initialization
 
-To initialize the TimeKit Project Selector on your site, you first need to import all required libraries onto your webpage (see above). After the library is installed, set up is as easy as running a single function:
+To initialize the Tulip Appointments Web Widget on your site, you first need to import all required libraries onto your webpage (see above). After the library is installed, set up is as easy as running a single function:
 
 ```js
 timekit_project_selector.init({
@@ -29,20 +29,90 @@ This will connect to TimeKit's API and load in all the required data. Once the i
 
 ## Configurations
 
-TimeKit Project Selector has many configuration options:
+Tulip Appointments Web Widget has many configuration options:
 
 | Option | Optional? | Default value | Description |
 |--------|-----------|---------------|-------------|
 | app_key | No | | Token required to connect to TimeKit API. Can be found at **https://admin.timekit.io/a/apps/<app_slug>/apisettings/keys** |
-| api_base_url | Yes | https://api.timekit.io | Timekit API url pointing to production environment. For staging env change it to staging url.
-| defaultUI | Yes | true | When true, will create the default user interface for the project selector. More details below |
-| embed | Yes | false | When true, the user interface will not be shown in the  widget, it will be placed inside of a specified div. More details below |
+| api_base_url | Yes | https://api.timekit.io | Timekit API url pointing to production environment. For staging environments point to `https://api-staging.timekit.io`.
+| defaultUI | Yes | true | When true, will create the default user interface for the project selector. See [Widget Modes](#widget-modes) below |
+| embed | Yes | false | When true, the user interface will be configured for Page Mode. It will be placed inside of a specified div. See [Widget Modes](#widget-modes) below |
 | includePrivateAppointments | Yes | false | When true, private appointment types will be fetched from the TimeKit API |
 | region | Yes | | Initial filter applied when getting default list of projects. Any project that does not have the same **t_region** metadata value will not be shown on initialization |
 | selectorOptions | No | | See below for details |
 | widgetImageUrl | Yes | Tulip Appointments Icon | When using the default widget UI, change this value to your desired image URL to replace widget image |
 | duplicateCustomerCheck | Yes | false | When a new booking is created, a call is made to check for potential duplicate Timekit customers. Requires the following webhook to be configured via Timekit: **/api/customers/timekit_webhook_connect_client**|
 
+### Widget Modes
+
+There are three modes of UI the Tulip Appointments Web Widget:
+
+- Popup Mode
+    - Automatically creates a button that will open the widget in a popup
+- Page Mode
+    - Injects itself onto the page given a destination HTML element
+- Custom UI
+    - No UI is created, you have to create UI for all steps up to the calendar view
+
+Whichever mode you choose is determined by the `defaultUI` and `embed` properties. Refer to the matrix below to see which mode is configured for each possible value of `defaultUI ` and `embed`.
+
+
+|  | embed=true | embed=false |
+|-|-|-|
+| defaultUI=true | Page Mode |  Popup Mode |
+| defaultUI=false| Custom UI | Custom UI |
+
+#### Popup Mode Widget
+
+![image](https://github.com/user-attachments/assets/7b04ed86-f724-4927-a86a-c95b4f299774)
+
+When enabled on initialization of the library the default user interface will be built on the web page as a widget. To disable the default UI from appearing, simply set the **defaultUI** configuration to `false`.
+
+NOTE: If you are using the widget view, you cannot have a div with ID **timekit-project-selector-container** on your DOM.
+
+```js
+timekit_project_selector.init({
+    app_key: <timekit_app_key>,
+    defaultUI: true,
+});
+```
+
+#### Page Mode Widget
+
+![image](https://github.com/user-attachments/assets/e92b7b9b-fae8-4d96-a503-86f053382b37)
+
+To use the Page Mode Widget, change the **embed** configuration to `true`. This will build the widget into a container div with the id **timekit-project-selector-container**. This allows you control of the positioning, size and style of the interface.
+
+```html
+<div id="timekit-project-selector-container"></div>
+<script>
+    timekit_project_selector.init({
+        app_key: <timekit_app_key>,
+        defaultUI: true,
+        embed: true,
+    });
+</script>
+```
+
+#### Custom UI
+
+If you do not want to use the Page Mode or Popup Mode widget and want to create your own UI, change the **defaultUI** configuration to `false`. This will not show the Popup or Page Widget UIs. When the store and appointment type is selected, a calendar UI will be populated in the HTML element with id `bookingjs`.
+
+For a more in-depth example, see [Example Custom UI](#example-custom-ui)
+
+
+```html
+<!-- Container div for the calendar to display-->
+<div id="bookingjs"></div>
+<script>
+    timekit_project_selector.init({
+        app_key: <timekit_app_key>,
+        defaultUI: false,
+    });
+</script>
+```
+
+
 ### Selector Options
 
 The selector options are how you can set the metadata fields that you want the user to select from. The order that the keys are placed in the object is the order the customer will see the selector options. If you are using the default UI, you will also need to specify the selector option copyright fields for each option. If you are not using the default UI, simply assign the keys to have value `true`.
@@ -67,7 +137,7 @@ When using the default UI, you must set the selector display values for each sel
 
 #### Selector Option Strategy (Optional)
 
-This parameter is used for defining the logic of rendering projects. The **strategy** field is used for rendering either Stores having Appointment Types belonging to them, or Appointment Types having Stores belonging to them. By default, strategy is set to `store_project` (Appointment Type > Store) 
+This parameter is used for defining the logic of rendering projects. The **strategy** field is used for rendering either Stores having Appointment Types belonging to them, or Appointment Types having Stores belonging to them. By default, strategy is set to `store_project` (Appointment Type > Store)
 
 ```
 strategy: 'store_project',
@@ -75,7 +145,7 @@ strategy: 'store_project',
 
 #### Selector Option Search Bar
 
-In addition to allowing for customization of the text on the widget, the Timekit Project Selector also allows for the addition of a search bar to allow a user to search for certain text inside of a card.
+In addition to allowing for customization of the text on the widget, the Tulip Appointments Web Widget also allows for the addition of a search bar to allow a user to search for certain text inside of a card.
 
 To enable this search bar, you can include the following inside of a Selector Option.
 
@@ -86,7 +156,7 @@ search_bar: {
 }
 ```
 
-By default, the search bar feature is not enabled if this configuration is missing from a selector option. If this configuration is present, then the **enabled** field is required. The **enabled** field must either be `true` or `false`, where `true` indicates that the search bar will show up in the default UI, and `false` indicates that it will not be present. 
+By default, the search bar feature is not enabled if this configuration is missing from a selector option. If this configuration is present, then the **enabled** field is required. The **enabled** field must either be `true` or `false`, where `true` indicates that the search bar will show up in the default UI, and `false` indicates that it will not be present.
 
 The **placeholder** field is optional and is not required for the search bar. If this field is missing, the placeholder text inside the search bar will default to `Please enter your search term`. Otherwise, the text can be replaced following the specifications below.
 
@@ -164,42 +234,7 @@ timekit_project_selector.init({
 });
 ```
 
-### Default UI
-
-When enabled on initialization of the library the default user interface will be built on the web page as a widget. To disable the default UI from appearing, simply set the **defaultUI** configuration to `false`.
 
-NOTE: If you are using the widget view, you cannot have a div with ID **timekit-project-selector-container** on your DOM.
-
-```js
-timekit_project_selector.init({
-    app_key: <timekit_app_key>,
-    defaultUI: true,
-});
-```
-
-### Embedding UI
-
-With the default UI there are two options: Widget Mode and Embedded Mode. By default, the UI will build a widget. To use the embedded mode, change the **embed** configuration to `true`. This will not build the widget, but will build in interface into a container div with the id **timekit-project-selector-container**. This allows you control of the positioning, size and style of the interface.
-
-```js
-// Requires a div with ID 'timekit-project-selector-container'. This is where the UI will render.
-timekit_project_selector.init({
-    app_key: <timekit_app_key>,
-    defaultUI: true,
-    embed: true,
-});
-```
-
-### Custom UI
-
-If you do not want to use the default UI and want to create your own UI, change the **defaultUI** configuration to `false`. This will not show the widget or embedded UI.
-
-```js
-timekit_project_selector.init({
-    app_key: <timekit_app_key>,
-    defaultUI: false,
-});
-```
 
 ### Including Private Appointment Types (Optional)
 
@@ -250,11 +285,11 @@ See below for how to use the exposed methods.
 
 ## Exposed Methods
 
-The TimeKit Project Selector library exposes the methods that are used to create our default user interface. This gives you the tools to build custom interfaces that are branded for your company to have customers select the correct TimeKit project to book with.
+The Tulip Appointments Web Widget library exposes the methods that are used to create our default user interface. This gives you the tools to build custom interfaces that are branded for your company to have customers select the correct TimeKit project to book with.
 
 ### init
 
-Asynchronous method that initiate the TimeKit Project Selector.
+Asynchronous method that initiate the Tulip Appointments Web Widget.
 
 ```js
 timekit_project_selector.init({
@@ -381,27 +416,30 @@ timekit_project_selector.selectProject(timekitProject);
 ```
 
 ## Example Custom UI
+
 ```html
 <!DOCTYPE html>
+
 <html lang="en">
 
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Custom UI - TimeKit Project Selector Example</title>
+    <title>Custom UI - Tulip Appointments Web Widget Example</title>
 
     <!-- Booking.js minified dependency -->
     <link rel="stylesheet" href="https://cdn.timekit.io/booking-js/v3/booking.min.css" />
-    <script type="text/javascript" src="//cdn.timekit.io/booking-js/v3/booking.min.js" defer></script>
+    <script type="text/javascript" src="https://cdn.timekit.io/booking-js/v3/booking.min.js"></script>
+
     <!-- Tulip Project selector -->
-    <script src="./../dist/timekit_project_selector.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@tulipnpm/timekit_project_selector@latest/dist/timekit_project_selector.min.js"></script>
 </head>
 
 <body>
-    <h1>Custom UI - TimeKit Project Selector Example</h1>
+    <h1>Custom UI - Tulip Appointments Web Widget Example</h1>
 
     <!-- Placeholder div for TK Projects of t_project_type = service_project -->
-    <ul class="global_projects"></ul>
+    <ul class="services"></ul>
 
     <!-- Placeholder div for TK Projects of t_project_type = store_project -->
     <ul class="stores"></ul>
@@ -410,79 +448,86 @@ timekit_project_selector.selectProject(timekitProject);
     <div id="bookingjs"></div>
 
     <script>
-        $(document).ready(function () {
-
-            const tps = timekit_project_selector;
-
-            tps.init({
-                // Insert widget key provided via TK admin panel
-                app_key: '',
-                // Set defaultUI to false as we are using a custom UI
-                defaultUI: false,
-                // Selector options still prvided but values are set to true
-                selectorOptions: {
-                    // Step 1: Is to select the service_project
-                    service_project: true,
-                    // Step 2: Is to select the store project
-                    store_project: true,
-                }
-            }).then(async () => {
-                // You could use simple array instead of using the steps factor.
-                // This factory makes it simple to track which TK project uuids were selected
-                let stepsFactory = tps.getStepsFactory();
-                
-                // Fetch the service_project
-                let globalProjects = await tps.getStrategy('service_project').getProjects({ 
-                    t_private: 0,
-                    t_disabled: 0
-                });
+        const tps = timekit_project_selector;
+
+        tps.init({
+            // Insert widget key provided via TK admin panel
+            app_key: 'live_widget_key_xj4RMO93SIXSS9EbZiw286Fs0epKDnN6',
+            api_base_url: 'https://api-staging.timekit.io',
+            // If you need to filter by country
+            // region: 'USA',
+            // Set defaultUI to false as we are using a custom UI
+            defaultUI: false,
+            // Selector options still prvided but values are set to true
+            selectorOptions: {
+                // Step 1: Is to select the service_project
+                service_project: true,
+                // Step 2: Is to select the store project
+                store_project: true,
+            }
+        }).then(async () => {
+            let serviceHtml = '';
+            let locationHtml = '';
+
+            // You could use simple array instead of using the steps factor.
+            // This factory makes it simple to track which TK project uuids were selected
+            let stepsFactory = tps.getStepsFactory();
+
+            // Fetch the service_project
+            let globalProjects = await tps.getStrategy('service_project').getProjects({ t_private: 0, t_disabled: 0 });
+
+            // Render out links for each service_project
+            globalProjects.forEach((globalProject) => {
+                serviceHtml += "<a href=\"#\" class=\"service\" id=\"" + globalProject.id + "\"> <li>" + globalProject.name + "</li></a>";
+            })
+
+            document.querySelector('.services').innerHTML = serviceHtml;
 
-                // Render out links for each service_project
-                globalProjects.forEach((globalProject) => {
-                    let link = "<a href=\"#\" class=\"global_appointment\" id=\"" + globalProject.id + "\"> <li>'" + globalProject.name + "'</li></a>";
-                    $('.global_projects').append(link);
-                })
+            var services = document.querySelectorAll('a.service'), i;
 
+            for (i = 0; i < services.length; ++i) {
                 // Register an event listener on the newly generated link
-                $("a.global_appointment").click(function (event) {
-                    stepsFactory.nextStep();
-
-                    const service_project_id  = $(this).attr('id');
-                    let storeProjects = await tps.getStrategy('store_project').getProjects({ 
-                        service_project_id,
-                        t_disabled: 0,
-                        t_private: 0
+                services[i].addEventListener("click", async function (event) {
+
+                    let service_project_id = event.target.parentNode.id;
+                    let storeProjects = await tps.getStrategy('store_project').getProjects({
+                        // t_private: 0, t_disabled: 0,
+                        service_project_id: service_project_id
                     });
-                    
+
                     // Render out links for each store_project
                     storeProjects.forEach((project) => {
-                        let link = "<a href=\"#\" class=\"store_project\" id=\"" + project.id + "\"> <li>'" + project.name + "'</li></a>";
-                        $('.stores').append(link);
+                        locationHtml += "<a href=\"#\" class=\"store_project\" id=\"" + project.id + "\"> <li>" + project.name + "</li></a>";
                     })
 
-                    // Register an event listener on the newly generated store link
-                    $("a.store_project").click(function (event) {
+                    document.querySelector('.stores').innerHTML = locationHtml;
 
-                        stepsFactory.nextStep();
+                    var locations = document.querySelectorAll('a.store_project'), j;
 
-                        const store_project_id = $(this).attr('id');
-                        const project = await tps.getStrategy().getProjects({
-                            store_project_id,
-                            service_project_id
-                        });
+                    for (j = 0; j < locations.length; ++j) {
+                        // Register an event listener on the newly generated store link
+                        locations[j].addEventListener("click", async function (e) {
+                            let store_project_id = e.target.parentNode.id;
 
-                        // Render Booking.js
-                        tps.selectProject(project);
-                    });
-                });
+                            const projects = await tps.getStrategy().getProjects({
+                                store_project_id: store_project_id,
+                                service_project_id: service_project_id
+                            });
 
-            }).catch((error) => {
-                console.log(error.message);
-            });
+                            const selectedProject = projects.find(project => project.meta?.t_service_id === service_project_id);
+                            // Render Booking.js
+                            tps.selectProject(selectedProject);
+                        });
+                    }
+                });
+            }
 
+        }).catch((error) => {
+            console.log(error.message);
         });
     </script>
 </body>
 
 </html>
+
 ```

package/dist/timekit_project_selector.js

@@ -20564,9 +20564,11 @@ var TimekitApiClient = /*#__PURE__*/function () {
   function TimekitApiClient() {
     var appKey = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
     var baseURL = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : '';
+    var region = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '';
     _classCallCheck(this, TimekitApiClient);
     this.appKey = appKey;
     this.appBaseURL = baseURL;
+    this.regionFilter = region;
     this.cachedItems = new CacheItems();
     this.instance = axios_default().create({
       baseURL: this.appBaseURL + '/v2'
@@ -20574,9 +20576,10 @@ var TimekitApiClient = /*#__PURE__*/function () {
   }
   _createClass(TimekitApiClient, [{
     key: "setAppKey",
-    value: function setAppKey(appKey, appUrl) {
+    value: function setAppKey(appKey, appUrl, region) {
       this.appKey = appKey;
       this.appBaseURL = appUrl;
+      this.regionFilter = region;
       this.instance = axios_default().create({
         baseURL: this.appBaseURL + '/v2'
       });
@@ -20819,16 +20822,22 @@ var TimekitApiClient = /*#__PURE__*/function () {
     value: function () {
       var _getLocations = _asyncToGenerator( /*#__PURE__*/regenerator_default().mark(function _callee6() {
         var filters,
+          query,
           _args6 = arguments;
         return regenerator_default().wrap(function _callee6$(_context6) {
           while (1) switch (_context6.prev = _context6.next) {
             case 0:
               filters = _args6.length > 0 && _args6[0] !== undefined ? _args6[0] : [];
-              _context6.next = 3;
-              return this.getLocationsByMetaQuery(this.filtersToQuery(this.getMetaQueryForLocations(), filters));
-            case 3:
+              // Add region to query 
+              query = this.getMetaQueryForLocations();
+              if (this.regionFilter != '') {
+                query += ";meta.t_store_country:".concat(this.regionFilter);
+              }
+              _context6.next = 5;
+              return this.getLocationsByMetaQuery(this.filtersToQuery(query, filters));
+            case 5:
               return _context6.abrupt("return", _context6.sent);
-            case 4:
+            case 6:
             case "end":
               return _context6.stop();
           }
@@ -21166,7 +21175,7 @@ var ProjectsStore = /*#__PURE__*/function () {
   _createClass(ProjectsStore, [{
     key: "init",
     value: function init(configManager) {
-      this.apiClient.setAppKey(configManager.app_key, configManager.api_base_url);
+      this.apiClient.setAppKey(configManager.app_key, configManager.api_base_url, configManager.region);
     }
   }, {
     key: "getApiClient",
@@ -21332,12 +21341,13 @@ var Step = /*#__PURE__*/function () {
   _createClass(Step, [{
     key: "init",
     value: function init() {
-      var _data$filters, _data$strategy;
+      var _data$filters, _data$strategy, _data$stepFilters;
       var data = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
       this.options = new StepOptions(data);
       this.dataOptions = new StepDataOptions(data);
       this.defaultFilters = (_data$filters = data['filters']) !== null && _data$filters !== void 0 ? _data$filters : [];
       this.strategy = (_data$strategy = data['strategy']) !== null && _data$strategy !== void 0 ? _data$strategy : null;
+      this.stepFilters = (_data$stepFilters = data['stepFilters']) !== null && _data$stepFilters !== void 0 ? _data$stepFilters : [];
     }
   }, {
     key: "setProjectType",
@@ -21346,7 +21356,7 @@ var Step = /*#__PURE__*/function () {
       if (!this.strategy) {
         this.strategy = projectType;
       }
-      if (projectType === 'global_appointment_type_project') {
+      if (projectType === 'store_appointment_type_project' || projectType === 'global_appointment_type_project') {
         this.strategy = 'service_project';
         this.projectType = 'service_project';
       }
@@ -21511,6 +21521,11 @@ var ConfigurationManager = /*#__PURE__*/function () {
     value: function isEmbedded() {
       return this.embed;
     }
+  }, {
+    key: "getRegion",
+    value: function getRegion() {
+      return this.region;
+    }
   }, {
     key: "getSelectorOptions",
     value: function getSelectorOptions() {
@@ -21558,6 +21573,7 @@ var StoreProjectsStrategy = /*#__PURE__*/function () {
         var _this = this;
         var filters,
           mainFilters,
+          newFilters,
           locations,
           storeIds,
           defaultFilters,
@@ -21567,25 +21583,26 @@ var StoreProjectsStrategy = /*#__PURE__*/function () {
             case 0:
               filters = _args.length > 0 && _args[0] !== undefined ? _args[0] : [];
               mainFilters = _args.length > 1 && _args[1] !== undefined ? _args[1] : [];
-              if (filters !== null && filters !== void 0 && filters.service_project_id) {
-                mainFilters['services.uuid'] = filters === null || filters === void 0 ? void 0 : filters.service_project_id;
-                Reflect.deleteProperty(filters, 'service_project_id');
+              newFilters = structuredClone(filters);
+              if (newFilters !== null && newFilters !== void 0 && newFilters.service_project_id) {
+                mainFilters['services.uuid'] = newFilters === null || newFilters === void 0 ? void 0 : newFilters.service_project_id;
+                Reflect.deleteProperty(newFilters, 'service_project_id');
               }
-              _context.next = 5;
+              _context.next = 6;
               return this.store.getApiClient().getLocations(mainFilters).then(function (projects) {
                 return _this.store.setProjects(projects);
               });
-            case 5:
+            case 6:
               locations = _context.sent;
               storeIds = [];
               defaultFilters = StepsFactory_instance.currentStep() ? StepsFactory_instance.currentStep().getDefaultFilters() : [];
               locations.forEach(function (project) {
                 storeIds.push(project.meta[_this.storeProjectIdKey]);
               });
-              return _context.abrupt("return", this.store.getProjects(LocationsStrategy_objectSpread(LocationsStrategy_objectSpread({}, filters), defaultFilters)).filter(function (project) {
+              return _context.abrupt("return", this.store.getProjects(LocationsStrategy_objectSpread(LocationsStrategy_objectSpread({}, newFilters), defaultFilters)).filter(function (project) {
                 return storeIds.includes(project.meta[_this.storeProjectIdKey]);
               }));
-            case 10:
+            case 11:
             case "end":
               return _context.stop();
           }
@@ -22616,6 +22633,7 @@ var UI = /*#__PURE__*/function () {
     this.is_embedded = is_embedded;
     this.userSelectionArray = [];
     this.navigator.setCount(this.cm.getSelectorOptionsCount() + 1); // Account for 1 extra dot for bookingJS
+    this.region = this.cm.getRegion();
   }
   _createClass(UI, [{
     key: "setup",