listing jsdocs

_dev/js/theme/core/listing/handler/updateFacetsHandler.js

@@ -2,9 +2,9 @@ import prestashop from 'prestashop';
 import updateListingFacetsRequest from '../request/updateListingFacetsRequest';
 
 /**
- * Build new facets url - add from-xhr param
- * @param {string} url - current url
- * @returns {string} - new url with from-xhr param
+ * Builds a new facets URL by adding the 'from-xhr' parameter.
+ * @param {string} url - The current URL.
+ * @returns {string} - The new URL with the 'from-xhr' parameter.
  */
 const buildNewFacetsUrl = (url) => {
   const urlObject = new URL(url);
@@ -14,16 +14,29 @@ const buildNewFacetsUrl = (url) => {
   return `${urlObject.origin}${urlObject.pathname}?${params.toString()}`;
 };
 
+/**
+ * Handles the update of facets by making a request to the updated URL.
+ * @param {string} url - The current URL.
+ * @returns {Promise<void>} - A promise resolving to void.
+ */
 const updateFacetsHandler = async (url) => {
+  // Build a new URL with the 'from-xhr' parameter
   const newUrl = buildNewFacetsUrl(url);
+
+  // Get the request function for updating facets
   const { getRequest } = updateListingFacetsRequest(newUrl);
 
   try {
+    // Make the request and get the data
     const data = await getRequest();
 
+    // Emit an event to update the product list
     prestashop.emit('updateProductList', data);
+
+    // Update the browser history with the new URL
     window.history.pushState(data, document.title, data.current_url);
   } catch (error) {
+    // Handle errors by emitting an error event
     prestashop.emit('handleError', {
       eventType: 'updateFacets',
       resp: {},

_dev/js/theme/core/listing/listingController.js

@@ -1,7 +1,15 @@
 import prestashop from 'prestashop';
 import updateFacetsHandler from './handler/updateFacetsHandler';
 
+/**
+ * Listing controller for handling facet updates.
+ * @returns {Object} An object with an initialization function.
+ * @returns {Function} init - Initializes the listing controller.
+ */
 const listingController = () => {
+  /**
+   * Initializes the listing controller by subscribing to the 'updateFacets' event.
+   */
   const init = () => {
     prestashop.on('updateFacets', updateFacetsHandler);
   };

_dev/js/theme/core/listing/request/updateListingFacetsRequest.js

@@ -5,62 +5,69 @@ import GenericHttpRequestError from '../../../components/http/error/GenericHttpR
 const { dispatch, abortAll } = useHttpController();
 
 /**
- * @typedef ServerResponse
- * @type {object}
- * @property {string} current_url - new url
- * @property {boolean} js_enabled - is js enabled
- * @property {string} label - listing label
- * @property {object} pagination - pagination object
- * @property {number} pagination.current_page - pagination current page
- * @property {number} pagination.items_shown_from - pagination items shown from
- * @property {number} pagination.items_shown_to - pagination items shown to
- * @property {array} pagination.pages - pagination pages array
- * @property {object[]} products - array of front representations of products
- * @property {string} rendered_active_filters - active filters html content
- * @property {string} rendered_facets - facets html content
- * @property {string} rendered_products - listing products html content
- * @property {string} rendered_products_bottom - listing products bottom html content
- * @property {string} rendered_products_header - listing products header html content
- * @property {string} rendered_products_top - listing products top html content
- * @property {object} result - result empty object
- * @property {object[]} sort_orders - available sort orders
- * @property {string} sort_selected - selected sort order
+ * @typedef {Object} ServerResponse
+ * @property {string} current_url - The new URL.
+ * @property {boolean} js_enabled - Indicates whether JavaScript is enabled.
+ * @property {string} label - The listing label.
+ * @property {Object} pagination - Pagination information.
+ * @property {number} pagination.current_page - The current page in pagination.
+ * @property {number} pagination.items_shown_from - The number of items shown from.
+ * @property {number} pagination.items_shown_to - The number of items shown to.
+ * @property {number[]} pagination.pages - Array of pagination pages.
+ * @property {Object[]} products - Array of front representations of products.
+ * @property {string} rendered_active_filters - HTML content for active filters.
+ * @property {string} rendered_facets - HTML content for facets.
+ * @property {string} rendered_products - HTML content for listing products.
+ * @property {string} rendered_products_bottom - HTML content for listing products bottom.
+ * @property {string} rendered_products_header - HTML content for listing products header.
+ * @property {string} rendered_products_top - HTML content for listing products top.
+ * @property {Object} result - Empty result object.
+ * @property {Object[]} sort_orders - Available sort orders.
+ * @property {string} sort_selected - The selected sort order.
  */
 
 /**
- * Update listing facets request
- * @param url {string} - new url with from-xhr param
+ * Generates an update listing facets request.
+ * @param {string} url - The new URL with the 'from-xhr' parameter.
  * @example
- *  const { getRequest } = updateListingFacetsRequest(url);
+ * const { getRequest } = updateListingFacetsRequest(url);
  *
- *  try {
- *    const resp = await getRequest();
- *  } catch (error) {
- *    console.error(error);
- *  }
+ * try {
+ *   const resp = await getRequest();
+ * } catch (error) {
+ *   console.error(error);
+ * }
  * @returns {{getRequest: (function(): Promise<ServerResponse>)}}
  */
 const updateListingFacetsRequest = (url) => {
+  // Create an HTTP request with the specified URL and headers
   const { request, controller } = useHttpRequest(url, {
     headers: {
       accept: 'application/json',
     },
   });
 
+  /**
+   * Sends an asynchronous GET request to update listing facets.
+   * @returns {Promise<ServerResponse>} - A promise resolving to the server response.
+   */
   const getRequest = () => new Promise((resolve, reject) => {
+    // Abort all previous requests
     abortAll();
 
+    // Dispatch the request and use the controller
     dispatch(request, controller)(() => request
       .get()
       .json((resp) => {
         resolve(resp);
       })
       .catch((e) => {
-        // IF ABORTED
+        // Handle abort (DOMException)
         if (e instanceof DOMException) {
           return;
         }
 
+        // Reject with a generic HTTP request error
         reject(new GenericHttpRequestError('Error while sending request'));
       }));
   });