jsdocs

_theme_dev/src/js/theme/handler/closePreviewDropdownHandler.js

@@ -1,14 +1,34 @@
+/**
+ * Handles the event to close the preview dropdown.
+ *
+ * @function
+ * @name closePreviewDropdownHandler
+ * @param {Event} e - The event object representing the triggered event.
+ */
 const closePreviewDropdownHandler = (e) => {
   e.preventDefault();
   e.stopPropagation();
 
+  /**
+   * The target selector for the preview dropdown to be closed.
+   * @type {string|undefined}
+   */
   const target = e.delegateTarget?.dataset?.target;
 
   if (target) {
+    /**
+     * The DOM element representing the preview dropdown.
+     * @type {HTMLElement|null}
+     */
     const dropdown = document.querySelector(target);
 
     if (dropdown) {
-      bootstrap.Dropdown.getOrCreateInstance(dropdown).hide();
+      /**
+       * The instance of the Bootstrap Dropdown associated with the preview dropdown.
+       * @type {bootstrap.Dropdown}
+       */
+      const dropdownInstance = bootstrap.Dropdown.getOrCreateInstance(dropdown);
+      dropdownInstance.hide();
     }
   }
 };

_theme_dev/src/js/theme/handler/openNotificationHandler.js

@@ -3,6 +3,13 @@ import { parseToHtml } from '@js/utils/DOM/DOMHelpers';
 import { one } from '@js/utils/event/eventHandler';
 import selectorsMap from '../selectors/selectorsMap';
 
+/**
+ * Handles the display of modal notifications with the provided content.
+ *
+ * @function
+ * @name handleModalNotification
+ * @param {string} notificationContent - The content to be displayed in the modal notification.
+ */
 const handleModalNotification = (notificationContent) => {
   if (!notificationContent) {
     return;
@@ -30,6 +37,13 @@ const handleModalNotification = (notificationContent) => {
   });
 };
 
+/**
+ * Handles the display of toast notifications with the provided content.
+ *
+ * @function
+ * @name handleToastNotification
+ * @param {string} notificationContent - The content to be displayed in the toast notification.
+ */
 const handleToastNotification = (notificationContent) => {
   if (!notificationContent) {
     return;
@@ -42,6 +56,12 @@ const handleToastNotification = (notificationContent) => {
   showToast(notificationContent);
 };
 
+/**
+ * Opens the preview dropdown element.
+ *
+ * @function
+ * @name openPreviewDropdown
+ */
 const openPreviewDropdown = () => {
   const {
     cartPreviewBtn,
@@ -57,6 +77,12 @@ const openPreviewDropdown = () => {
   dropdownInstance.show();
 };
 
+/**
+ * Opens the preview offcanvas element.
+ *
+ * @function
+ * @name openPreviewOffcanvas
+ */
 const openPreviewOffcanvas = () => {
   const {
     cartPreviewOffcanvas,
@@ -72,6 +98,13 @@ const openPreviewOffcanvas = () => {
   offcanvasInstance.show();
 };
 
+/**
+ * Handles the opening of different types of previews based on the previewType.
+ *
+ * @function
+ * @name handleOpenPreview
+ * @param {string} previewType - The type of preview to be opened ('dropdown' or 'offcanvas').
+ */
 const handleOpenPreview = (previewType) => {
   switch (previewType) {
     case 'dropdown':
@@ -85,6 +118,15 @@ const handleOpenPreview = (previewType) => {
   }
 };
 
+/**
+ * Handles the opening of different types of notifications.
+ *
+ * @function
+ * @name openNotificationHandler
+ * @param {string} notificationType - The type of notification ('modal', 'toast', or 'open_preview').
+ * @param {string} notificationContent - The content to be displayed in the notification.
+ * @param {string} previewType - The type of preview to be opened when notificationType is 'open_preview'.
+ */
 const openNotificationHandler = (notificationType, notificationContent, previewType) => {
   switch (notificationType) {
     case 'modal':

_theme_dev/src/js/theme/handler/updateCartHandler.js

@@ -1,10 +1,31 @@
 import updatePreviewCartRequest from '../request/updatePreviewCartRequest';
 
+/**
+ * Handles the update of the shopping cart based on an event.
+ *
+ * @function
+ * @name updateCartHandler
+ * @param {Object} event - The event triggering the shopping cart update.
+ * @param {Object} event.reason - The reason for the shopping cart update.
+ * @param {Number} event.reason.idCustomization - The ID of the customization related to the update.
+ * @param {Number} event.reason.idProductAttribute - The ID of the product attribute related to the update.
+ * @param {Number} event.reason.idProduct - The ID of the product related to the update.
+ * @param {string} event.reason.linkAction - The action associated with the shopping cart update.
+ * @param {Object} event.resp - The response object related to the update.
+ */
 const updateCartHandler = (event) => {
   if (!event?.reason || !event?.resp || event?.resp?.hasError) {
     return;
   }
 
+  /**
+   * Payload for the shopping cart update request.
+   * @typedef {Object} CartUpdatePayload
+   * @property {Number} id_customization - The ID of the customization.
+   * @property {Number} id_product_attribute - The ID of the product attribute.
+   * @property {Number} id_product - The ID of the product.
+   * @property {string} cart-action - The action to be performed on the shopping cart.
+   */
   const payload = {
     id_customization: event.reason.idCustomization,
     id_product_attribute: event.reason.idProductAttribute,
@@ -15,6 +36,14 @@ const updateCartHandler = (event) => {
   // refreshCartPreviewUrl is defined as a global variable in the module
   const { getRequest } = updatePreviewCartRequest(window.refreshCartPreviewUrl, payload);
 
+  /**
+   * Executes the shopping cart update request and emits events based on the response.
+   *
+   * @function
+   * @name getRequest
+   * @memberof updateCartHandler
+   * @return {Promise<Object>} A Promise that resolves with the response data.
+   */
   getRequest()
     .then((resp) => {
       prestashop.emit('updatedCartPreview', resp);

_theme_dev/src/js/theme/handler/updateCartPreviewHandler.js

@@ -1,22 +1,41 @@
 import { parseToHtml, each } from '@js/utils/DOM/DOMHelpers';
 import selectorsMap from '../selectors/selectorsMap';
 
-const {
-  cartPreviewBtn,
-  cartPreviewContent,
-} = selectorsMap;
-
+/**
+ * Updates the cart preview elements with new HTML content.
+ *
+ * @function
+ * @name updateCartPreviewHandler
+ * @param {string} previewBtnHtmlString - The HTML string to replace the cart preview button with.
+ * @param {string} previewContentHtmlString - The HTML string to replace the content within the cart preview with.
+ */
 const updateCartPreviewHandler = (previewBtnHtmlString, previewContentHtmlString) => {
-  if (previewBtnHtmlString) {
-    each(cartPreviewBtn, (previewBtn) => {
-      previewBtn.replaceWith(parseToHtml(previewBtnHtmlString));
+  const {
+    cartPreviewBtn,
+    cartPreviewContent,
+  } = selectorsMap;
+
+  /**
+   * Replaces the specified cart preview elements with the provided HTML string.
+   *
+   * @function
+   * @name replaceCartPreviewElement
+   * @memberof updateCartPreviewHandler
+   * @param {string} selector - The selector for the cart preview element to be replaced.
+   * @param {string} htmlString - The HTML string to replace the corresponding cart preview element with.
+   */
+  const replaceCartPreviewElement = (selector, htmlString) => {
+    each(selector, (element) => {
+      element.replaceWith(parseToHtml(htmlString));
     });
+  };
+
+  if (previewBtnHtmlString) {
+    replaceCartPreviewElement(cartPreviewBtn, previewBtnHtmlString);
   }
 
   if (previewContentHtmlString) {
-    each(cartPreviewContent, (previewContent) => {
-      previewContent.replaceWith(parseToHtml(previewContentHtmlString));
-    });
+    replaceCartPreviewElement(cartPreviewContent, previewContentHtmlString);
   }
 };
 

_theme_dev/src/js/theme/index.js

@@ -6,21 +6,57 @@ import updateCartHandler from './handler/updateCartHandler';
 import updateCartPreviewHandler from './handler/updateCartPreviewHandler';
 import openNotificationHandler from './handler/openNotificationHandler';
 
+/**
+ * Controller for managing the cart preview functionality.
+ *
+ * @function
+ * @name cartPreviewController
+ * @returns {Object} An object with an initialization function.
+ */
 const cartPreviewController = () => {
   const {
     cartDropdownClose,
   } = selectorsMap;
 
+  /**
+   * Initializes the cart preview controller by setting up event listeners and handlers.
+   *
+   * @function
+   * @name init
+   */
   const init = () => {
     prestashop.on('updateCart', updateCartHandler);
+
+    /**
+     * Handles the updated cart preview and triggers relevant actions.
+     *
+     * @function
+     * @param {Object} res - The response object containing updated cart preview data.
+     * @param {string} res.previewBtn - The HTML string for updating the cart preview button.
+     * @param {string} res.previewContent - The HTML string for updating the cart preview content.
+     * @param {string} res.notificationType - The type of notification to be displayed.
+     * @param {string} res.notificationContent - The content of the notification.
+     * @param {string} res.previewType - The type of preview to be opened.
+     */
     prestashop.on('updatedCartPreview', (res) => {
       updateCartPreviewHandler(res.previewBtn, res.previewContent);
       openNotificationHandler(res.notificationType, res.notificationContent, res.previewType);
     });
 
-    each(cartDropdownClose, (el) => {
-      on(el, 'click', closePreviewDropdownHandler);
-    });
+    /**
+     * Attaches click event handlers to close buttons in the cart preview dropdown.
+     *
+     * @function
+     * @name attachCloseHandlers
+     */
+    const attachCloseHandlers = () => {
+      each(cartDropdownClose, (el) => {
+        on(el, 'click', closePreviewDropdownHandler);
+      });
+    };
+
+    // Attach close handlers on initialization
+    attachCloseHandlers();
   };
 
   return {

_theme_dev/src/js/theme/request/updatePreviewCartRequest.js

@@ -1,11 +1,25 @@
 import useHttpRequest from '@js/utils/http/useHttpRequest';
 
+/**
+ * Factory function for creating an object to handle preview cart update requests.
+ *
+ * @function
+ * @name updatePreviewCartRequest
+ * @param {string} url - The URL for the preview cart update request.
+ * @param {Object} payload - Optional payload data to be sent with the request.
+ * @param {Number} payload.id_product - The ID of the product to update.
+ * @param {Number} payload.id_product_attribute - The ID of the product attribute to update.
+ * @param {Number} payload.id_customization - The ID of the customization to update.
+ * @param {String} payload.cart-action - The action to perform on the cart.
+ */
 const updatePreviewCartRequest = (url, payload = {}) => {
   const { request } = useHttpRequest(url);
 
   /**
-   * Executes the request to get the preview cart.
+   * Executes the request to update the preview cart.
+   *
    * @function
+   * @name getRequest
    * @memberof updatePreviewCartRequest
    * @return {Promise<Object>} A Promise that resolves with the response data.
    */

_theme_dev/src/js/theme/selectors/selectorsMap.js

@@ -1,3 +1,19 @@
+/**
+ * Object representing selectors for various elements in the application.
+ * @typedef {Object} SelectorsMap
+ * @property {string} cartPreviewBtn - Selector for the cart preview button.
+ * @property {string} cartPreview - Selector for the cart preview container.
+ * @property {string} cartPreviewContent - Selector for the content within the cart preview.
+ * @property {string} cartDropdownClose - Selector for the close button in the cart dropdown.
+ * @property {string} cartPreviewOffcanvas - Selector for the offcanvas element in the cart preview.
+ * @property {string} cartPreviewDropdown - Selector for the dropdown within the cart preview.
+ * @property {string} notificationModal - Selector for the notification modal related to the cart.
+ */
+
+/**
+ * Map of selectors used in the application for easy access and consistency.
+ * @type {SelectorsMap}
+ */
 const selectorsMap = {
   cartPreviewBtn: '.js-cart-preview-btn',
   cartPreview: '.js-cart-preview',