@hellotext/hellotext 2.3.9 → 2.4.0

package/lib/core/configuration/webchat.js

@@ -33,13 +33,13 @@ var strategies = {
 };
 
 /**
- * @typedef {'modal' | 'popover'} Behaviour
+ * @typedef {'modal' | 'popover'} Mode
  */
 
 /**
- * @enum {Behaviour}
+ * @enum {Mode}
  */
-var behaviors = {
+var modes = {
   MODAL: 'modal',
   POPOVER: 'popover'
 };
@@ -51,6 +51,20 @@ var behaviors = {
  * @property {string} typography - The typography style (e.g., font family).
  */
 
+/**
+ * @typedef {Object} Appearance
+ * @property {Object} [header] - Header appearance overrides.
+ * @property {string} [header.name] - Business name shown in the webchat header.
+ * @property {Object} [launcher] - Launcher appearance overrides.
+ * @property {string} [launcher.iconUrl] - Image URL used for the launcher icon.
+ */
+
+/**
+ * @typedef {Object} WhatsApp
+ * @property {string} [number] - WhatsApp number used by the handoff configuration.
+ * @property {boolean} [restrictToChannel] - Whether handoff should be restricted to the configured channel.
+ */
+
 /**
  * @class Webchat
  * @classdesc
@@ -58,10 +72,11 @@ var behaviors = {
  * @property {String} id - the id of the webchat.
  * @property {String} container - the container to append the webchat to, defaults to 'body'
  * @property {Placement} placement - the placement of the webchat within the container, defaults to "bottom-right".
- * @property {String} classes - additional classes to apply to the webchat popup.
- * @property {String} triggerClasses - additional classes to apply to the webchat popup trigger.
- * @property {Behaviour} behaviour - the behaviour of the webchat, defaults to 'popover'.
+ * @property {Mode} mode - how the webchat behaves while open, defaults to 'popover'.
+ * @property {Object} behaviour - runtime opening behaviour for the webchat.
  * @property {Style} style - the style of the webchat.
+ * @property {Appearance} appearance - appearance overrides.
+ * @property {WhatsApp} whatsapp - WhatsApp handoff overrides.
  * @property {Strategy} strategy - the strategy used to position the webchat. Defaults to 'absolute'
  */
 var Webchat = /*#__PURE__*/function () {
@@ -87,36 +102,6 @@ var Webchat = /*#__PURE__*/function () {
       }
       this._placement = value;
     }
-  }, {
-    key: "classes",
-    get: function get() {
-      if (typeof this._classes === 'string') {
-        return this._classes.split(',').map(c => c.trim());
-      } else {
-        return this._classes;
-      }
-    },
-    set: function set(value) {
-      if (!Array.isArray(value) && typeof value !== 'string') {
-        throw new Error('classes must be an array or a string');
-      }
-      this._classes = value;
-    }
-  }, {
-    key: "triggerClasses",
-    get: function get() {
-      if (typeof this._triggerClasses === 'string') {
-        return this._triggerClasses.split(',').map(c => c.trim());
-      } else {
-        return this._triggerClasses;
-      }
-    },
-    set: function set(value) {
-      if (!Array.isArray(value) && typeof value !== 'string') {
-        throw new Error('triggerClasses must be an array or a string');
-      }
-      this._triggerClasses = value;
-    }
   }, {
     key: "id",
     get: function get() {
@@ -153,17 +138,103 @@ var Webchat = /*#__PURE__*/function () {
       });
       this._style = value;
     }
+  }, {
+    key: "appearance",
+    get: function get() {
+      return this._appearance;
+    },
+    set: function set(value) {
+      if (!this.isPlainObject(value)) {
+        throw new Error('Appearance must be an object');
+      }
+      Object.entries(value).forEach(_ref2 => {
+        var [key, nestedValue] = _ref2;
+        if (!['header', 'launcher'].includes(key)) {
+          throw new Error("Invalid appearance property: ".concat(key));
+        }
+        if (!this.isPlainObject(nestedValue)) {
+          throw new Error("Appearance ".concat(key, " must be an object"));
+        }
+        Object.entries(nestedValue).forEach(_ref3 => {
+          var [nestedKey, propertyValue] = _ref3;
+          if (key === 'header' && nestedKey !== 'name') {
+            throw new Error("Invalid appearance header property: ".concat(nestedKey));
+          }
+          if (key === 'launcher' && nestedKey !== 'iconUrl') {
+            throw new Error("Invalid appearance launcher property: ".concat(nestedKey));
+          }
+          if (propertyValue == null) {
+            return;
+          }
+          if (typeof propertyValue !== 'string') {
+            throw new Error("Invalid appearance ".concat(key, ".").concat(nestedKey, " value: ").concat(propertyValue));
+          }
+        });
+      });
+      this._appearance = value;
+    }
+  }, {
+    key: "whatsapp",
+    get: function get() {
+      return this._whatsapp;
+    },
+    set: function set(value) {
+      if (!this.isPlainObject(value)) {
+        throw new Error('WhatsApp must be an object');
+      }
+      Object.entries(value).forEach(_ref4 => {
+        var [key, nestedValue] = _ref4;
+        if (!['number', 'restrictToChannel'].includes(key)) {
+          throw new Error("Invalid WhatsApp property: ".concat(key));
+        }
+        if (nestedValue == null) {
+          return;
+        }
+        if (key === 'number' && typeof nestedValue !== 'string') {
+          throw new Error("Invalid WhatsApp number value: ".concat(nestedValue));
+        }
+        if (key === 'restrictToChannel' && typeof nestedValue !== 'boolean') {
+          throw new Error("Invalid WhatsApp restrictToChannel value: ".concat(nestedValue));
+        }
+      });
+      this._whatsapp = value;
+    }
+  }, {
+    key: "mode",
+    get: function get() {
+      return this._mode;
+    },
+    set: function set(value) {
+      if (!Object.values(modes).includes(value)) {
+        throw new Error("Invalid mode value: ".concat(value));
+      }
+      this._mode = value;
+    }
   }, {
     key: "behaviour",
     get: function get() {
       return this._behaviour;
     },
     set: function set(value) {
-      if (!Object.values(behaviors).includes(value)) {
+      if (value == null) {
+        this._behaviour = value;
+        return;
+      }
+      if (typeof value !== 'object' || Array.isArray(value)) {
         throw new Error("Invalid behaviour value: ".concat(value));
       }
       this._behaviour = value;
     }
+  }, {
+    key: "hasBehaviourOverride",
+    get: function get() {
+      return this._hasBehaviourOverride;
+    }
+  }, {
+    key: "behaviourOverride",
+    set: function set(value) {
+      this._hasBehaviourOverride = !!value;
+    }
   }, {
     key: "strategy",
     get: function get() {
@@ -182,8 +253,8 @@ var Webchat = /*#__PURE__*/function () {
     key: "assign",
     value: function assign(props) {
       if (props) {
-        Object.entries(props).forEach(_ref2 => {
-          var [key, value] = _ref2;
+        Object.entries(props).forEach(_ref5 => {
+          var [key, value] = _ref5;
           this[key] = value;
         });
       }
@@ -194,15 +265,22 @@ var Webchat = /*#__PURE__*/function () {
     value: function isHexOrRgba(value) {
       return /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(value) || /^rgba?\(\s*\d{1,3},\s*\d{1,3},\s*\d{1,3},?\s*(0|1|0?\.\d+)?\s*\)$/.test(value);
     }
+  }, {
+    key: "isPlainObject",
+    value: function isPlainObject(value) {
+      return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
   }]);
   return Webchat;
 }();
 Webchat._id = void 0;
 Webchat._container = 'body';
 Webchat._placement = 'bottom-right';
-Webchat._classes = [];
-Webchat._triggerClasses = [];
 Webchat._style = {};
-Webchat._behaviour = behaviors.POPOVER;
+Webchat._appearance = {};
+Webchat._whatsapp = {};
+Webchat._mode = modes.POPOVER;
+Webchat._behaviour = null;
+Webchat._hasBehaviourOverride = false;
 Webchat._strategy = null;
-export { behaviors, Webchat };
+export { modes, Webchat };

package/lib/hellotext.cjs

@@ -35,10 +35,9 @@ let Hellotext = /*#__PURE__*/function () {
       this.forms = new _models.FormCollection();
       this.query = new _models.Query();
       const businessData = await this.business.hydrate();
-      const webchatConfig = config.webchat === false ? false : {
-        ...(businessData && businessData.webchat || {}),
-        ...(config.webchat || {})
-      };
+      const webchatConfig = config.webchat === false ? false : this.mergeWebchatConfig(businessData && businessData.webchat || {}, config.webchat || {});
+      const hasExplicitBehaviourOverride = config.webchat && config.webchat !== false && Object.prototype.hasOwnProperty.call(config.webchat, 'behaviour');
+      _core.Configuration.webchat.behaviourOverride = hasExplicitBehaviourOverride;
       if (webchatConfig && webchatConfig.id) {
         _core.Configuration.webchat.assign(webchatConfig);
         this.webchat = await _models.Webchat.load(webchatConfig.id);
@@ -47,6 +46,31 @@ let Hellotext = /*#__PURE__*/function () {
         this.forms.collectExistingFormsOnPage();
       }
     }
+  }, {
+    key: "mergeWebchatConfig",
+    value: function mergeWebchatConfig(dashboardConfig, localConfig) {
+      return this.deepMergePlainObjects(dashboardConfig, localConfig);
+    }
+  }, {
+    key: "deepMergePlainObjects",
+    value: function deepMergePlainObjects(base, override) {
+      const result = {
+        ...base
+      };
+      Object.entries(override).forEach(([key, value]) => {
+        if (this.isPlainObject(value) && this.isPlainObject(result[key])) {
+          result[key] = this.deepMergePlainObjects(result[key], value);
+        } else {
+          result[key] = value;
+        }
+      });
+      return result;
+    }
+  }, {
+    key: "isPlainObject",
+    value: function isPlainObject(value) {
+      return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
 
     /**
      * Tracks an action that has happened on the page

package/lib/hellotext.js

@@ -34,7 +34,9 @@ var Hellotext = /*#__PURE__*/function () {
         this.forms = new FormCollection();
         this.query = new Query();
         var businessData = yield this.business.hydrate();
-        var webchatConfig = config.webchat === false ? false : _objectSpread(_objectSpread({}, businessData && businessData.webchat || {}), config.webchat || {});
+        var webchatConfig = config.webchat === false ? false : this.mergeWebchatConfig(businessData && businessData.webchat || {}, config.webchat || {});
+        var hasExplicitBehaviourOverride = config.webchat && config.webchat !== false && Object.prototype.hasOwnProperty.call(config.webchat, 'behaviour');
+        Configuration.webchat.behaviourOverride = hasExplicitBehaviourOverride;
         if (webchatConfig && webchatConfig.id) {
           Configuration.webchat.assign(webchatConfig);
           this.webchat = yield Webchat.load(webchatConfig.id);
@@ -48,6 +50,31 @@ var Hellotext = /*#__PURE__*/function () {
       }
       return initialize;
     }()
+  }, {
+    key: "mergeWebchatConfig",
+    value: function mergeWebchatConfig(dashboardConfig, localConfig) {
+      return this.deepMergePlainObjects(dashboardConfig, localConfig);
+    }
+  }, {
+    key: "deepMergePlainObjects",
+    value: function deepMergePlainObjects(base, override) {
+      var result = _objectSpread({}, base);
+      Object.entries(override).forEach(_ref => {
+        var [key, value] = _ref;
+        if (this.isPlainObject(value) && this.isPlainObject(result[key])) {
+          result[key] = this.deepMergePlainObjects(result[key], value);
+        } else {
+          result[key] = value;
+        }
+      });
+      return result;
+    }
+  }, {
+    key: "isPlainObject",
+    value: function isPlainObject(value) {
+      return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+
     /**
      * Tracks an action that has happened on the page
      *

package/lib/models/business.cjs

@@ -20,6 +20,8 @@ function _toPrimitive(input, hint) { if (typeof input !== "object" || input ===
 /**
  * @typedef {Object} BusinessWebchat
  * @property {String} [id] - Dashboard webchat id configured for the business.
+ * @property {Object} [appearance] - Dashboard appearance defaults for the webchat.
+ * @property {Object} [whatsapp] - Dashboard WhatsApp handoff defaults for the webchat.
  */
 /**
  * Public business metadata returned by `public/businesses/:id`.

package/lib/models/business.js

@@ -17,6 +17,8 @@ import BusinessesAPI from '../api/businesses';
 /**
  * @typedef {Object} BusinessWebchat
  * @property {String} [id] - Dashboard webchat id configured for the business.
+ * @property {Object} [appearance] - Dashboard appearance defaults for the webchat.
+ * @property {Object} [whatsapp] - Dashboard WhatsApp handoff defaults for the webchat.
  */
 
 /**

package/lib/models/webchat.cjs

@@ -21,8 +21,33 @@ let Webchat = /*#__PURE__*/function () {
   _createClass(Webchat, [{
     key: "render",
     value: function render() {
+      this.applyBehaviourOverride();
       this.containerToAppendTo.appendChild(this.data.html);
     }
+  }, {
+    key: "applyBehaviourOverride",
+    value: function applyBehaviourOverride() {
+      if (!_core.Configuration.webchat.hasBehaviourOverride || !_core.Configuration.webchat.behaviour) return;
+      this.data.html.setAttribute('data-hellotext--webchat-behaviour-value', JSON.stringify(this.serializedBehaviour));
+    }
+  }, {
+    key: "serializedBehaviour",
+    get: function () {
+      const behaviour = _core.Configuration.webchat.behaviour;
+      return {
+        trigger: this.serializeTrigger(behaviour.trigger),
+        delay_seconds: behaviour.delaySeconds,
+        first_visit_only: behaviour.firstVisitOnly,
+        once_per_session: behaviour.oncePerSession
+      };
+    }
+  }, {
+    key: "serializeTrigger",
+    value: function serializeTrigger(trigger) {
+      if (trigger === 'onLoad') return 'on_load';
+      if (trigger === 'onClick') return 'on_click';
+      return trigger;
+    }
   }, {
     key: "containerToAppendTo",
     get: function () {

package/lib/models/webchat.js

@@ -16,8 +16,33 @@ var Webchat = /*#__PURE__*/function () {
   _createClass(Webchat, [{
     key: "render",
     value: function render() {
+      this.applyBehaviourOverride();
       this.containerToAppendTo.appendChild(this.data.html);
     }
+  }, {
+    key: "applyBehaviourOverride",
+    value: function applyBehaviourOverride() {
+      if (!Configuration.webchat.hasBehaviourOverride || !Configuration.webchat.behaviour) return;
+      this.data.html.setAttribute('data-hellotext--webchat-behaviour-value', JSON.stringify(this.serializedBehaviour));
+    }
+  }, {
+    key: "serializedBehaviour",
+    get: function get() {
+      var behaviour = Configuration.webchat.behaviour;
+      return {
+        trigger: this.serializeTrigger(behaviour.trigger),
+        delay_seconds: behaviour.delaySeconds,
+        first_visit_only: behaviour.firstVisitOnly,
+        once_per_session: behaviour.oncePerSession
+      };
+    }
+  }, {
+    key: "serializeTrigger",
+    value: function serializeTrigger(trigger) {
+      if (trigger === 'onLoad') return 'on_load';
+      if (trigger === 'onClick') return 'on_click';
+      return trigger;
+    }
   }, {
     key: "containerToAppendTo",
     get: function get() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellotext/hellotext",
-  "version": "2.3.9",
+  "version": "2.4.0",
   "description": "Hellotext JavaScript Client",
   "source": "src/index.js",
   "main": "lib/index.cjs",

package/src/api/webchats.js

@@ -16,6 +16,8 @@ class WebchatsAPI {
       url.searchParams.append(`style[${key}]`, value)
     })
 
+    this.appendWebchatOverrides(url)
+
     url.searchParams.append('placement', Configuration.webchat.placement)
 
     const response = await fetch(url, {
@@ -32,6 +34,21 @@ class WebchatsAPI {
 
     return new DOMParser().parseFromString(data.html, 'text/html').querySelector('article')
   }
+
+  static appendWebchatOverrides(url) {
+    const { appearance, whatsapp } = Configuration.webchat
+
+    this.appendIfSupplied(url, 'webchat[appearance][header][name]', appearance.header?.name)
+    this.appendIfSupplied(url, 'webchat[appearance][launcher][icon_url]', appearance.launcher?.iconUrl)
+    this.appendIfSupplied(url, 'webchat[handoff][identifier]', whatsapp.number)
+    this.appendIfSupplied(url, 'webchat[handoff][restrict_to_channel]', whatsapp.restrictToChannel)
+  }
+
+  static appendIfSupplied(url, key, value) {
+    if (value === undefined || value === null) return
+
+    url.searchParams.append(key, String(value))
+  }
 }
 
 export default WebchatsAPI

package/src/controllers/mixins/usePopover.js

@@ -4,20 +4,22 @@ import { Configuration } from '../../core'
 export const usePopover = controller => {
   Object.assign(controller, {
     show() {
+      this.cancelBehaviourOpen?.()
       this.openValue = true
     },
     hide() {
       this.openValue = false
     },
     toggle() {
+      this.cancelBehaviourOpen?.()
       this.openValue = !this.openValue
     },
-    setupFloatingUI({ trigger, popover }) {
+    setupFloatingUI({ trigger, popover, strategy }) {
       this.floatingUICleanup = autoUpdate(trigger, popover, () => {
         computePosition(trigger, popover, {
           placement: this.placementValue,
           middleware: this.middlewares,
-          strategy: Configuration.webchat.strategy,
+          strategy: strategy || Configuration.webchat.strategy,
         }).then(({ x, y, strategy }) => {
           const newStyle = {
             left: `${x}px`,

package/src/controllers/webchat/emoji_picker_controller.js

@@ -1,11 +1,6 @@
 import { autoPlacement, offset, shift } from '@floating-ui/dom'
 import { Controller } from '@hotwired/stimulus'
 
-import en from '@emoji-mart/data/i18n/en.json'
-import es from '@emoji-mart/data/i18n/es.json'
-
-import { Picker } from 'emoji-mart'
-
 import { usePopover } from '../mixins/usePopover'
 
 export default class extends Controller {
@@ -22,19 +17,29 @@ export default class extends Controller {
 
   initialize() {
     this.onEmojiSelect = this.onEmojiSelect.bind(this)
+    this.pickerLoaded = false
+    this.pickerLoadPromise = null
+    this.connected = false
     super.initialize()
   }
 
   connect() {
+    this.connected = true
+
     usePopover(this)
 
-    this.setupFloatingUI({ trigger: this.buttonTarget, popover: this.popoverTarget })
-    this.popoverTarget.appendChild(this.pickerObject)
+    this.setupFloatingUI({
+      trigger: this.buttonTarget,
+      popover: this.popoverTarget,
+      strategy: 'absolute',
+    })
 
     super.connect()
   }
 
   disconnect() {
+    this.connected = false
+    this.pickerLoadPromise = null
     this.floatingUICleanup()
     super.disconnect()
   }
@@ -53,7 +58,44 @@ export default class extends Controller {
     }
   }
 
-  get pickerObject() {
+  async onPopoverOpened() {
+    await this.loadPicker()
+  }
+
+  async loadPicker() {
+    if (this.pickerLoaded) return
+
+    this.pickerLoadPromise ||= this.loadPickerDependencies()
+
+    const { Picker, i18n } = await this.pickerLoadPromise
+
+    if (!this.connected || this.pickerLoaded) return
+
+    this.popoverTarget.appendChild(this.buildPicker(Picker, i18n))
+    this.pickerLoaded = true
+  }
+
+  async loadPickerDependencies() {
+    const [pickerModule, i18nModule] = await Promise.all([
+      import(/* webpackChunkName: "webchat-emoji" */ 'emoji-mart'),
+      this.loadI18n(),
+    ])
+
+    return {
+      Picker: pickerModule.Picker,
+      i18n: i18nModule.default || i18nModule,
+    }
+  }
+
+  loadI18n() {
+    if (Hellotext.business.locale === 'es') {
+      return import(/* webpackChunkName: "webchat-emoji-es" */ '@emoji-mart/data/i18n/es.json')
+    }
+
+    return import(/* webpackChunkName: "webchat-emoji-en" */ '@emoji-mart/data/i18n/en.json')
+  }
+
+  buildPicker(Picker, i18n) {
     return new Picker({
       onEmojiSelect: this.onEmojiSelect,
       theme: 'light',
@@ -62,7 +104,7 @@ export default class extends Controller {
       skinTonePosition: 'none',
       emojiSize: this.sizeValue,
       perLine: this.perLineValue,
-      i18n: Hellotext.business.locale === 'es' ? es : en,
+      i18n,
     })
   }
 

package/src/controllers/webchat/useBehaviour.js

@@ -0,0 +1,81 @@
+// This mixin owns automatic opening only. The webchat controller still owns the
+// Stimulus lifecycle and `usePopover` still owns the mechanics of opening and
+// closing the popover. Keeping this policy here gives the configured behaviour
+// value one place to translate into timers, storage gates, and cleanup.
+export const useBehaviour = controller => {
+  Object.assign(controller, {
+    // Called from `connect` after the controller has wired channels, targets,
+    // and popover state. Even a zero-second delay goes through a timeout so the
+    // automatic open happens after the mount pass rather than during setup.
+    scheduleBehaviourOpen() {
+      if (!this.shouldAutoOpenFromBehaviour()) return
+
+      const delay = Number(this.behaviourValue.delay_seconds || 0) * 1000
+
+      this.behaviourOpenTimeout = window.setTimeout(() => {
+        this.behaviourOpenTimeout = null
+
+        if (this.openValue) return
+
+        this.openValue = true
+        this.markBehaviourAutoOpened()
+      }, delay)
+    },
+
+    // This is the shared escape hatch for lifecycle teardown and manual user
+    // intent. `disconnect` calls it to avoid orphaned timers; `usePopover`
+    // calls it before show/toggle so a delayed behaviour cannot reopen the chat
+    // or consume gates after the user has already acted.
+    cancelBehaviourOpen() {
+      window.clearTimeout(this.behaviourOpenTimeout)
+      this.behaviourOpenTimeout = null
+    },
+
+    // Eligibility is deliberately read-only. A visit should only be marked as
+    // auto-opened after the timer opens the widget, not when we merely discover
+    // that it would be allowed. That keeps blocked, cancelled, and manually
+    // opened visits from being counted as behaviour-driven opens.
+    shouldAutoOpenFromBehaviour() {
+      const behaviour = this.behaviourValue
+
+      if (!behaviour || behaviour.trigger !== 'on_load') return false
+
+      if (behaviour.first_visit_only && localStorage.getItem(this.firstVisitKey())) {
+        return false
+      }
+
+      if (behaviour.once_per_session && sessionStorage.getItem(this.sessionKey())) {
+        return false
+      }
+
+      return true
+    },
+
+    // The gates are independent because they answer different product
+    // questions. `first_visit_only` is a long-lived visitor gate in
+    // localStorage; `once_per_session` is intentionally softer and resets with
+    // sessionStorage.
+    markBehaviourAutoOpened() {
+      if (this.behaviourValue.first_visit_only) {
+        localStorage.setItem(this.firstVisitKey(), '1')
+      }
+
+      if (this.behaviourValue.once_per_session) {
+        sessionStorage.setItem(this.sessionKey(), '1')
+      }
+    },
+
+    // Records that this widget has already used its long-lived first-visit
+    // automatic open. This is the durable gate behind `first_visit_only`.
+    firstVisitKey() {
+      return `hellotext--webchat--${this.idValue}--auto-opened`
+    },
+
+    // Records that this widget has already used its automatic open during the
+    // current browser session. This is the shorter-lived gate behind
+    // `once_per_session`.
+    sessionKey() {
+      return `hellotext--webchat--${this.idValue}--auto-opened-session`
+    },
+  })
+}