Add documentation to PNI search related JS files (#12742)

* Added doc to utils.js

* Added doc to pni-sort-dropdown.js and pni-toggle.js

* Added doc to slider-area.js

* Added doc to member-functions.js

* Added doc to history.js

source/js/buyers-guide/search/history.js

@@ -6,10 +6,13 @@ const parentTitle = document.querySelector(`.parent-title`);
 const toggle = document.querySelector(`#product-filter-pni-toggle`);
 
 /**
- * ...
+ * Set up history management
+ *
  * @param {*} instance
- * @param {*} searchBar
- * @param {*} searchInput
+ * @param {Element} searchBar - The search bar element
+ * @param {Element} searchInput - The search input element
+ * @param {Element} mobileSearchBar - The mobile search bar element
+ * @param {Element} mobileSearchInput - The mobile search input element
  */
 export function setupHistoryManagement(
   instance,
@@ -35,10 +38,18 @@ export function setupHistoryManagement(
 }
 
 /**
- * ...
+ * Update History state and update page UI accordingly
+ *
  * @param {*} instance
- * @param {*} searchBar
- * @param {*} searchInput
+ * @param {Element} searchBar - The search bar element
+ * @param {Element} searchInput - The search input element
+ * @param {Element} mobileSearchBar - The mobile search bar element
+ * @param {Element} mobileSearchInput - The mobile search input element
+ *
+ * @todo FIXME. We need to revisit and improve the implementation of this function.
+ *       It's unclear why history.replaceState needs to be called twice.
+ *       It's also unclear why there are repeated if-else statements especially for search parameters.
+ *       Further investigation is needed to understand the purpose of this function.
  */
 export function performInitialHistoryReplace(
   instance,
@@ -120,10 +131,13 @@ export function performInitialHistoryReplace(
 }
 
 /**
- * ...
+ *  Set up the window.popstate event listener
+ *
  * @param {*} instance
- * @param {*} searchBar
- * @param {*} searchInput
+ * @param {Element} searchBar - The search bar element
+ * @param {Element} searchInput - The search input element
+ * @param {Element} mobileSearchBar - The mobile search bar element
+ * @param {Element} mobileSearchInput - The mobile search input element
  */
 export function setupPopStateHandler(
   instance,
@@ -183,7 +197,8 @@ export function setupPopStateHandler(
 }
 
 /**
- * ...
+ * Apply data stored in the history state to the page
+ *
  * @param {*} instance
  */
 export function applyHistory(instance) {

source/js/buyers-guide/search/member-functions.js

@@ -5,7 +5,8 @@ const parentTitle = document.querySelector(`.parent-title`);
 const subcategories = document.querySelectorAll(`.subcategories`);
 
 /**
- * ...
+ * Attach event listeners to the nav links and subcategory links
+ *
  * @param {*} instance
  */
 export function setupNavLinks(instance) {
@@ -116,7 +117,8 @@ export function setupNavLinks(instance) {
 }
 
 /**
- * ...
+ * Attach event listeners to "go back to all" link
+ *
  * @param {*} instance
  */
 export function setupGoBackToAll(instance) {
@@ -153,8 +155,11 @@ export function setupGoBackToAll(instance) {
 }
 
 /**
- * ...
+ * Attach event listeners to the Product Review nav links
+ *
  * @param {*} instance
+ *
+ * @todo See if we can make this DRYer by making use of the toggleProductReviewView function?
  */
 export function setupReviewLinks(instance) {
   const navLinks = document.querySelectorAll(`.product-review-link`);
@@ -179,6 +184,9 @@ export function setupReviewLinks(instance) {
   }
 }
 
+/**
+ * Toggle the Product Review view
+ */
 export function toggleProductReviewView() {
   const editorialContent = document.querySelector(".editorial-content");
   const navLinks = document.querySelectorAll(`.product-review-link`);
@@ -190,6 +198,9 @@ export function toggleProductReviewView() {
   }
 }
 
+/**
+ * Toggle the category related articles section
+ */
 export function toggleCategoryRelatedArticles(category) {
   const relatedArticles = document.querySelectorAll("[data-show-for-category]");
 

source/js/buyers-guide/search/pni-sort-dropdown.js

@@ -4,6 +4,9 @@ const DOWN_ARROW_KEY_CODE = 40;
 const UP_ARROW_KEY_CODE = 38;
 const ESCAPE_KEY_CODE = 27;
 
+/**
+ * Dropdown component for sorting products on PNI
+ */
 export class PNISortDropdown {
   constructor(searchFilter) {
     this.searchFilter = searchFilter;
@@ -81,6 +84,11 @@ export class PNISortDropdown {
     }
   }
 
+  /**
+   * Sets the selected list item and updates the dropdown button content.
+   * @param {Event} e - The event (e.g., click, keydown)
+   * @param {boolean} [pushUpdate=true] - Whether to push the update to the history state.
+   */
   setSelectedListItem(e, pushUpdate = true) {
     this.listItems.forEach((item) => {
       const itemDiv = item.querySelector("div");
@@ -99,12 +107,20 @@ export class PNISortDropdown {
     }
   }
 
+  /**
+   * Closes the dropdown list.
+   */
   closeList() {
     this.listContainer.classList.add("tw-hidden");
     this.dropdownButton.setAttribute("aria-expanded", false);
     this.dropdownButtonArrow.classList.remove("tw-rotate-180");
   }
 
+  /**
+   * Opens the dropdown list.
+   *
+   * @param {boolean} [withFocus=false] - Whether to focus on the first list item.
+   */
   openList(withFocus = false) {
     this.listContainer.classList.remove("tw-hidden");
     this.dropdownButton.setAttribute("aria-expanded", true);
@@ -118,6 +134,11 @@ export class PNISortDropdown {
     }
   }
 
+  /**
+   * Toggle the visibility of the dropdown list
+   *
+   * @param {Event} e The event (e.g., click, keydown)
+   */
   toggleListVisibility(e) {
     const isExpanded =
       this.dropdownButton.getAttribute("aria-expanded") === "true";
@@ -140,6 +161,13 @@ export class PNISortDropdown {
     }
   }
 
+  /**
+   * Focus on the next list item based on the given direction.
+   *
+   * @param {number} direction - They key code of the direction to move the focus (e.g., key code for up arrow / down arrow)
+   *
+   * @todo Consider refactoring this method to make it more readable and maintainable.
+   */
   focusNextListItem(direction) {
     const activeElementId = document.activeElement.id;
     const currentActiveElementIndex = this.listItemIds.indexOf(activeElementId);

source/js/buyers-guide/search/pni-toggle.js

@@ -1,6 +1,9 @@
 import { Utils } from "./utils.js";
 import { gsap } from "gsap";
 
+/**
+ * The control that toggles the "Privacy Not Included" filter on the product list.
+ */
 export class PNIToggle {
   constructor(searchFilter) {
     this.searchFilter = searchFilter;
@@ -51,7 +54,13 @@ export class PNIToggle {
     });
   }
 
+  /**
+   * Toggle the "Privacy Not Included" filter on the product list.
+   *
+   * @param {boolean} doFilter - Whether to filter the list for "Privacy Not Included" products.
+   */
   togglePrivacyOnly(doFilter) {
+    console.log(doFilter);
     const { searchFilter, categoryTitle } = this;
 
     gsap.set("figure.product-box.privacy-ding", { opacity: 1, y: 0 });

source/js/buyers-guide/search/slider-area.js

@@ -1,8 +1,8 @@
 /**
- * mouse/touch scroll functionality for the category area
- * @param {*} event
+ * Mouse/touch scroll functionality for the sub category area on mobile
+ *
+ * @todo Rename this file to something more specific. Maybe something like subcategory-scroll.js
  */
-
 const subcategories = document.querySelectorAll(`.subcategories`);
 const subContainer = document.querySelector(`.subcategory-header`);
 const subClasses = subContainer.classList;
@@ -14,6 +14,11 @@ function stop(evt) {
   evt.stopImmediatePropagation();
 }
 
+/**
+ * A event handler that initiate the scroll functionality on the sub category area
+ *
+ * @param {Event} event The event that triggered the function
+ */
 export function markScrollStart(event) {
   stop(event);
   subClasses.add("cursor-grabbing", "select-none");
@@ -27,6 +32,11 @@ export function markScrollStart(event) {
   document.addEventListener(`mouseup`, markScrollEnd);
 }
 
+/**
+ * A event handler for moving the scorll on the sub category area
+ *
+ * @param {Event} event The event that triggered the function
+ */
 function markScrollMove(event) {
   subcategories.forEach((subcategory) => {
     subcategory.classList.add("pointer-events-none");
@@ -35,6 +45,11 @@ function markScrollMove(event) {
   subContainer.scrollLeft = pos.left - dx;
 }
 
+/**
+ * A event handler for stopping the scorll on the sub category area
+ *
+ * @param {Event} event The event that triggered the function
+ */
 function markScrollEnd(event) {
   stop(event);