Merge pull request #303 from Oksydan/jsdocs-changes

Jsdocs changes

Author: Oksydan

_dev/js/theme/components/useAlertToast.js

@@ -18,10 +18,10 @@ const getId = (prefix = 'alert_toast_') => {
  * @param {number} [params.duration=4000] - Duration in milliseconds for which the toast is displayed.
  * @returns {Object} - An object containing methods for showing different types of toasts.
  */
-const useAlertToast = (params) => {
+const useAlertToast = (params = {}) => {
   const {
     duration = 4000,
-  } = params || {};
+  } = params;
 
   const stackTemplateId = 'alert-toast-stack';
   const bodyElement = document.querySelector('body');

_dev/js/theme/core/checkout/checkoutController.js

@@ -15,9 +15,10 @@ import checkoutStepChangeHandler from './handler/process/checkoutStepChangeHandl
 const { on } = useEvent();
 
 /**
- * Checkout controller
- * @returns {object} return
- * @returns {function} return.init initialize checkout controller
+ * Checkout controller.
+ *
+ * @returns {object} The checkout controller object.
+ * @property {function} init - Initializes the checkout controller.
  */
 const checkoutController = () => {
   const {
@@ -29,6 +30,12 @@ const checkoutController = () => {
     confirmationSelector,
   } = prestashop.selectors.checkout;
 
+  /**
+   * Initializes the checkout controller by attaching event handlers.
+   *
+   * @function
+   * @returns {void}
+   */
   const init = () => {
     on(document, 'click', editAddresses, editAddressHandler);
     on(document, 'click', deliveryAddressRadios, changeAddressHandler);

_dev/js/theme/core/checkout/handler/address/editAddressHandler.js

@@ -1,8 +1,10 @@
 import prestashop from 'prestashop';
 
 /**
- * Edit address handler
- * @param event {object} - click event
+ * Handles the click event for editing an address in the Prestashop checkout process.
+ *
+ * @function
+ * @param {object} event - The click event object.
  */
 const editAddressHandler = (event) => {
   const {

_dev/js/theme/core/checkout/handler/address/showAddressErrorMessageHandler.js

@@ -6,7 +6,9 @@ import { isElementVisible } from '../../../../utils/DOMHelpers';
 import getEditAddress from '../../utils/getEditAddress';
 
 /**
- * Show address error message handler
+ * Handles the display of address error messages in the Prestashop checkout process.
+ *
+ * @function
  * @returns {void}
  */
 const showAddressErrorMessageHandler = () => {

_dev/js/theme/core/checkout/handler/delivery/changeDeliveryMethodHandler.js

@@ -6,8 +6,10 @@ import refreshCheckoutPage from '../../utils/refreshCheckoutPage';
 import { each } from '../../../../utils/DOMHelpers';
 
 /**
- * Change delivery method handler
- * @param event {object} - change event
+ * Handles the change of delivery method in the Prestashop checkout process.
+ *
+ * @function
+ * @param {object} event - The change event.
  * @returns {Promise<void>}
  */
 const changeDeliveryMethodHandler = async (event) => {

_dev/js/theme/core/checkout/handler/delivery/editDeliveryStepHandler.js

@@ -2,8 +2,10 @@ import prestashop from 'prestashop';
 import useCheckoutStepsController from '../../components/useCheckoutStepsController';
 
 /**
- * Edit delivery step handler
- * @param event {object} - click event
+ * Handles the click event to edit the delivery step in the Prestashop checkout process.
+ *
+ * @function
+ * @param {object} event - The click event.
  */
 const editDeliveryStepHandler = (event) => {
   event.preventDefault();

_dev/js/theme/core/checkout/handler/payment/confirmOrderHandler.js

@@ -13,6 +13,14 @@ const showNativeFormErrors = () => {
   });
 };
 
+/**
+ * Handles the click event to confirm the order in the Prestashop checkout process.
+ *
+ * @async
+ * @function
+ * @param {object} e - The click event.
+ * @returns {Promise<void>}
+ */
 const confirmOrderHandler = async (e) => {
   e.preventDefault();
 

_dev/js/theme/core/checkout/handler/payment/orderConfirmationErrorsHandler.js

@@ -1,6 +1,10 @@
 /**
- * Redirect to cart page if there are errors on order confirmation
- * @param event {object} - event object
+ * Handles errors on order confirmation by redirecting to the cart page if needed.
+ *
+ * @function
+ * @param {object} event - The event object containing the response information.
+ * @param {object} event.resp - The response object.
+ * @returns {void}
  */
 const orderConfirmationErrorsHandler = ({ resp }) => {
   if (resp?.cartUrl !== '') {

_dev/js/theme/core/checkout/handler/payment/toggleOrderButtonStateHandler.js

@@ -6,6 +6,12 @@ import { each } from '../../../../utils/DOMHelpers';
 
 const { toggle } = useToggleDisplay();
 
+/**
+ * Handles toggling the order button state based on the conditions and emits an event with the updated terms status.
+ *
+ * @function
+ * @returns {void}
+ */
 const toggleOrderButtonStateHandler = () => {
   const { conditionAlertSelector } = prestashop.selectors.checkout;
 

_dev/js/theme/core/checkout/handler/payment/togglePaymentOptionsHandler.js

@@ -7,6 +7,12 @@ import { each } from '../../../../utils/DOMHelpers';
 
 const { show } = useToggleDisplay();
 
+/**
+ * Handles toggling the visibility of payment options based on the selected payment method, and updates the order button state accordingly.
+ *
+ * @function
+ * @returns {void}
+ */
 const togglePaymentOptionsHandler = () => {
   const paymentBtnEnabled = canProceedOrder();
 

_dev/js/theme/core/checkout/handler/process/checkoutFormSubmitHandler.js

@@ -2,8 +2,11 @@ import prestashop from 'prestashop';
 import { each } from '../../../../utils/DOMHelpers';
 
 /**
- * Checkout form submit handler
- * @param event {object} - submit event
+ * Handles the submission of the checkout form, disables submit buttons, and emits a 'submitCheckoutForm' event.
+ *
+ * @function
+ * @param {object} event - The submit event object.
+ * @returns {void}
  */
 const checkoutFormSubmitHandler = (event) => {
   const submitButtons = event.target.querySelectorAll('button[type="submit"]');

_dev/js/theme/core/checkout/handler/process/checkoutStepChangeHandler.js

@@ -2,8 +2,11 @@ import prestashop from 'prestashop';
 import useCheckoutStepsController from '../../components/useCheckoutStepsController';
 
 /**
- * Checkout step change handler
- * @param event {object} - click event
+ * Handles the change of a checkout step, preventing the default click event, updating the step, and emitting a 'changedCheckoutStep' event.
+ *
+ * @function
+ * @param {object} event - The click event object.
+ * @returns {void}
  */
 const checkoutStepChangeHandler = (event) => {
   event.preventDefault();

_dev/js/theme/core/checkout/index.js

@@ -5,7 +5,13 @@ import checkoutController from './checkoutController';
 
 prestashop.checkout = prestashop.checkout || {};
 
-// GLOBAL
+/**
+ * Event handler for checking orderable cart response.
+ *
+ * @param {object} resp - Response object.
+ * @param {object} paymentObject - Payment object.
+ * @returns {boolean} Returns true if there are errors; otherwise, returns false.
+ */
 prestashop.checkout.onCheckOrderableCartResponse = (resp, paymentObject) => {
   if (resp.errors === true) {
     prestashop.emit('orderConfirmationErrors', {
@@ -19,6 +25,11 @@ prestashop.checkout.onCheckOrderableCartResponse = (resp, paymentObject) => {
   return false;
 };
 
+/**
+ * Initializes the checkout process if the page is the checkout page.
+ *
+ * @returns {void}
+ */
 const initCheckout = () => {
   if (prestashop.page.page_name !== 'checkout') {
     return;
@@ -29,6 +40,8 @@ const initCheckout = () => {
   init();
 };
 
+// Event listener for DOM ready event.
 DOMReady(() => {
+  // Initialize the checkout process when the DOM is ready.
   initCheckout();
 });

_dev/js/theme/core/checkout/request/checkCartStillOrderableRequest.js

@@ -2,18 +2,23 @@ import prestashop from 'prestashop';
 import useDefaultHttpRequest from '../../../components/http/useDefaultHttpRequest';
 
 /**
- * @typedef ServerResponse
- * @type {object}
- * @property {string} cartUrl - cart page url
- * @property {boolean} errors - errors flag (true if errors)
+ * Represents the server response from a check cart still orderable request.
+ * @typedef {object} ServerResponse
+ * @property {string} cartUrl - The URL of the cart page.
+ * @property {boolean} errors - A flag indicating whether there are errors (true if there are errors).
  */
 
 /**
- * Check cart still orderable request
+ * Provides a check cart still orderable request with a method to get the request promise.
+ *
+ * @function
  * @returns {{getRequest: (function(): Promise<ServerResponse>)}}
  */
 const checkCartStillOrderableRequest = () => {
-  // payload not typed because it isn't needed
+  /**
+   * Payload not typed because it isn't needed.
+   * @type {object}
+   */
   const payloadToSend = {
     ajax: 1,
     action: 'checkCartStillOrderable',

_dev/js/theme/core/checkout/request/selectDeliveryMethodRequest.js

@@ -1,18 +1,20 @@
 import useDefaultHttpRequest from '../../../components/http/useDefaultHttpRequest';
 
 /**
- * @typedef ServerResponse
- * @type {object}
- * @property {string} preview - checkout summary html content
+ * Represents the server response from a select delivery method request.
+ * @typedef {object} ServerResponse
+ * @property {string} preview - The HTML content of the checkout summary.
  */
 
 /**
- * Select delivery method request
- * @param url {string} - checkout url to send request
- * @param payload {object} - request payload
- * @param payload.delivery_option[id] {string} - delivery option id with id_address_delivery
- * @param payload.ajax {number} - optional
- * @param payload.action {string} - optional
+ * Provides a select delivery method request with a method to get the request promise.
+ *
+ * @function
+ * @param {string} url - The checkout URL to send the request.
+ * @param {object} payload - The request payload.
+ * @param {object} payload.delivery_option[id] - The delivery option ID with id_address_delivery.
+ * @param {number} payload.ajax - An optional parameter.
+ * @param {string} payload.action - An optional parameter.
  * @example
  * const payload = {
  *   'delivery_option[1]': '2,',
@@ -29,7 +31,10 @@ import useDefaultHttpRequest from '../../../components/http/useDefaultHttpReques
  * @returns {{getRequest: (function(): Promise<ServerResponse>)}}
  */
 const selectDeliveryMethodRequest = (url, payload) => {
-  // payload not typed because delivery option parameter is dynamic
+  /**
+   * Payload not typed because the delivery option parameter is dynamic.
+   * @type {object}
+   */
   const payloadToSend = {
     ajax: 1,
     action: 'selectDeliveryOption',

_dev/js/theme/core/checkout/utils/areConditionsAccepted.js

@@ -2,14 +2,42 @@ import prestashop from 'prestashop';
 import { each } from '../../../utils/DOMHelpers';
 
 /**
- * Check if all conditions are accepted
- * @returns {boolean} true if all conditions are accepted or false otherwise
+ * Checks if all conditions are accepted.
+ *
+ * @function
+ * @returns {boolean} True if all conditions are accepted, or false otherwise.
  */
 const areConditionsAccepted = () => {
+  /**
+   * The flag indicating whether all conditions are accepted.
+   * @type {boolean}
+   */
   let accepted = true;
+
+  /**
+   * The selector for conditions.
+   * @type {string}
+   */
   const { conditionsSelector } = prestashop.selectors.checkout;
+
+  /**
+   * The list of conditions.
+   * @type {NodeList<HTMLInputElement>}
+   */
   const conditions = document.querySelectorAll(`${conditionsSelector} input[type="checkbox"]`);
 
+  /**
+   * Iterates through each condition and checks if it is accepted.
+   *
+   * @callback eachCallback
+   * @param {HTMLInputElement} condition - The current condition.
+   * @returns {void}
+   */
+
+  /**
+   * The helper function for iterating through each condition.
+   * @type {eachCallback}
+   */
   each(conditions, (condition) => {
     if (!condition.checked) {
       accepted = false;

_dev/js/theme/core/checkout/utils/canProceedOrder.js

@@ -2,13 +2,28 @@ import areConditionsAccepted from './areConditionsAccepted';
 import getSelectedPaymentOption from './getSelectedPaymentOption';
 
 /**
- * Check if order can be proceeded
- * @returns {boolean} true if order can be proceeded or false otherwise
+ * Checks if the order can be proceeded.
+ *
+ * @function
+ * @returns {boolean} True if the order can be proceeded, or false otherwise.
  */
 const canProceedOrder = () => {
+  /**
+   * The flag indicating whether the conditions are accepted.
+   * @type {boolean}
+   */
   let proceed = areConditionsAccepted();
 
-  if (!getSelectedPaymentOption()) {
+  /**
+   * The selected payment option.
+   * @type {HTMLElement | null}
+   */
+  const selectedPaymentOption = getSelectedPaymentOption();
+
+  /**
+   * Checks if a payment option is selected.
+   */
+  if (!selectedPaymentOption) {
     proceed = false;
   }
 

_dev/js/theme/core/checkout/utils/collapseAllPaymentOptions.js

@@ -3,11 +3,31 @@ import { each } from '../../../utils/DOMHelpers';
 import useToggleDisplay from '../../../components/display/useToggleDisplay';
 
 /**
- * Collapse all payment options additional information blocks and options form
+ * Collapses all payment options' additional information blocks and options forms.
+ *
+ * @function
+ * @returns {void}
  */
 const collapseAllPaymentOptions = () => {
+  /**
+   * The selectors related to payment options.
+   * @type {object}
+   * @property {string} additionalInformatonSelector - Selector for additional information blocks.
+   * @property {string} optionsForm - Selector for options forms.
+   */
   const { additionalInformatonSelector, optionsForm } = prestashop.selectors.checkout;
+
+  /**
+   * All payment-related blocks to be collapsed.
+   * @type {NodeListOf<Element>}
+   */
   const paymentRelatedBlocks = document.querySelectorAll(`${additionalInformatonSelector}, ${optionsForm}`);
+
+  /**
+   * The toggle display utility.
+   * @type {object}
+   * @property {function} hide - Function to hide an element.
+   */
   const { hide } = useToggleDisplay();
 
   each(paymentRelatedBlocks, hide);