Merge pull request #102 from goodguyry/feature/jsdoc-cleanup

JS docs cleanup

.jest/setupFile.js

@@ -1,7 +1,7 @@
 /**
  * Get the event detail object from the latest call.
  *
- * @param  {function} handler The event callback.
+ * @param {function} handler The event callback.
  * @return {object}
  */
 global.getEventDetails = (handler) => {

jest.config.js

@@ -4,6 +4,6 @@ module.exports = {
     '<rootDir>/.jest/setupFile.js',
   ],
   moduleNameMapper: {
-    '^@/(\.jest)/(.*)$': '<rootDir>/$1/$2',
+    '^@/(.jest)/(.*)$': '<rootDir>/$1/$2',
   },
 };

src/AriaComponent.js

@@ -16,8 +16,8 @@ export default class AriaComponent {
    * Create a passably unique `id` attribute.
    * @static
    *
-   * @param {Number} radix An optional base for converting the Number to a String.
-   * @returns {String}
+   * @param {number} radix An optional base for converting the Number to a String.
+   * @returns {string}
    */
   static getUniqueId(radix = 36) {
     const [, attr] = Math.random().toString(radix).split('.');
@@ -27,7 +27,7 @@ export default class AriaComponent {
   /**
    * Returns the first and last items from an Array or NodeList.
    *
-   * @param  {array|NodeList} items The Array or NodeList from which to retrieve the items.
+   * @param {array|NodeList} items The Array or NodeList from which to retrieve the items.
    * @return {array}                The first and last items.
    */
   static getFirstAndLastItems(items) {
@@ -76,9 +76,9 @@ export default class AriaComponent {
     /**
      * The component parameters.
      *
-     * @type {Object} {
+     * @type {object} {
      *   @param {HTMLElement} element The component element.
-     *   @param {Object}.     options The original options.
+     *   @param {object}      options The original options.
      * }
      */
     this.params = {
@@ -96,14 +96,14 @@ export default class AriaComponent {
     /**
      * Track attributes added by this script.
      *
-     * @type {Object}
+     * @type {object}
      */
     this.__trackedAttributes = {};
 
     /**
      * Track installed modules.
      *
-     * @type {Array}
+     * @type {array}
      */
     this.__includedModules = [];
 
@@ -151,7 +151,7 @@ export default class AriaComponent {
   /**
    * Returns tracked attributes for the given element after ensuring it has the required ID attribute.
    *
-   * @param  {HTMLElement} element The element for which attributes are being retrieved.
+   * @param {HTMLElement} element The element for which attributes are being retrieved.
    * @return {array}
    */
   getTrackedAttributesFor = (element) => {
@@ -221,8 +221,8 @@ export default class AriaComponent {
   /**
    * Dispatch event.
    *
-   * @param  {string} name   The event name.
-   * @param  {object} detail The event detail object.
+   * @param {string} name   The event name.
+   * @param {object} detail The event detail object.
    */
   dispatch = (name, detail) => {
     const event = new CustomEvent(
@@ -303,7 +303,7 @@ export default class AriaComponent {
   /**
    * Run the module function, which returns a cleanup function.
    *
-   * @param  {Funciton} mod The module initializing function.
+   * @param {Function} mod The module initializing function.
    * @return {Functions} The cleanup function.
    */
   start = (mod) => {

src/Dialog/Dialog.js

@@ -10,7 +10,7 @@ export default class Dialog extends AriaComponent {
    * Initial state.
    * @private
    *
-   * @type {Boolean}
+   * @type {bool}
    */
   #expanded = false;
 
@@ -68,7 +68,7 @@ export default class Dialog extends AriaComponent {
   /**
    * Set expanded state and update attributes.
    *
-   * @param {Object} state The component state.
+   * @param {object} state The component state.
    */
   set expanded(newState) {
     // Update state.

src/Dialog/modules/useLegacyDialog.js

@@ -2,9 +2,9 @@
  * Dialog module to use `aria-hidden` to hide outside content rather than using
  * the `aria-model` attribute.
  *
- * @param  {Dialog} arg.component The Dialog component instance.
- * @param  {object} arg.options   The options passed to the component instance.
- * @return {Function} The cleanup function.
+ * @param {Dialog} arg.component The Dialog component instance.
+ * @param {object} arg.options   The options passed to the component instance.
+ * @return {function} The cleanup function.
  */
 export default function UseLegacyDialog({ component, options }) {
   let { content } = {

src/Disclosure/Disclosure.js

@@ -13,7 +13,7 @@ export default class Disclosure extends AriaComponent {
    * Initial expanded state.
    * @private
    *
-   * @type {Boolean}
+   * @type {bool}
    */
   #expanded = false;
 
@@ -51,7 +51,7 @@ export default class Disclosure extends AriaComponent {
   /**
    * Set expanded state and update attributes.
    *
-   * @param {Object} state The component state.
+   * @param {object} state The component state.
    */
   set expanded(newState) {
     // Update state.

src/Listbox/Listbox.js

@@ -17,7 +17,7 @@ export default class ListBox extends AriaComponent {
    * Initial expanded state.
    * @private
    *
-   * @type {Boolean}
+   * @type {bool}
    */
   #expanded = false;
 
@@ -35,8 +35,8 @@ export default class ListBox extends AriaComponent {
    *
    * @param {HTMLElement} lement The component element.
    */
-  constructor(element) {
-    super(element);
+  constructor(element, options = {}) {
+    super(element, options);
 
     /**
      * The string description for this object.
@@ -56,7 +56,7 @@ export default class ListBox extends AriaComponent {
        * Whether the Listbox options are horizonally or vertically oriented.
        * Options: 'horizontal', 'vertical'.
        *
-       * @type {String}
+       * @type {string}
        */
       orientation: this.#orientation,
 
@@ -71,7 +71,7 @@ export default class ListBox extends AriaComponent {
     /**
      * Saves the initial button label.
      *
-     * @type {String}
+     * @type {string}
      */
     this.buttonLabel = this.controller.textContent;
 
@@ -128,6 +128,15 @@ export default class ListBox extends AriaComponent {
     );
   }
 
+  /**
+   * Get expanded state.
+   *
+   * @return {bool}
+   */
+  get expanded() {
+    return this.#expanded;
+  }
+
   /**
    * Set the Listbox orientation.
    *
@@ -149,15 +158,6 @@ export default class ListBox extends AriaComponent {
     return this.#orientation;
   }
 
-  /**
-   * Get expanded state.
-   *
-   * @return {bool}
-   */
-  get expanded() {
-    return this.#expanded;
-  }
-
   /**
    * Set the active descendant and update attributes accordingly.
    * https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant

src/Listbox/Search.js

@@ -35,7 +35,7 @@ export default class Search {
    * Select the item that matches a search string.
    * If a match is found, return it so that it can be selected.
    *
-   * @param {Number} key A keyCode value.
+   * @param {number} key A keyCode value.
    * @return {HTMLElement|null} The matched element or null if no match.
    */
   getItem(key) {

src/Listbox/Search.test.js

@@ -6,7 +6,7 @@ import Search from './Search';
  * @todo This is maintained from the previous event setup because typing with
  * user.keyboard is taking so long the tests error out.
  *
- * @param  {string} character The character to type.
+ * @param {string} character The character to type.
  * @return {KeyboardEvent}
  */
 function typeCharacter(character) {

src/Menu/Menu.js

@@ -115,8 +115,8 @@ export default class Menu extends AriaComponent {
   /**
    * Initialize and save a submenu Disclosure.
    *
-   * @param  {array}         disclosures The array of previous disclosures.
-   * @param  {HTMLLIElement} menuChild   The menu item.
+   * @param {array}         disclosures The array of previous disclosures.
+   * @param {HTMLLIElement} menuChild   The menu item.
    * @return {array} A collection of submenu Disclosures.
    */
   initSubmenuDisclosure = (disclosures, menuChild) => {
@@ -187,7 +187,7 @@ export default class Menu extends AriaComponent {
    * Update attributes based on expanded state.
    *
    * @param {object} disclosure The Disclosure to update.
-   * @param {boolean} expanded  The expected updated Disclosure state.
+   * @param {bool} expanded  The expected updated Disclosure state.
    */
   setDisclosureState = (disclosure, expanded) => {
     if (undefined !== disclosure) {
@@ -215,9 +215,7 @@ export default class Menu extends AriaComponent {
   controllerHandleKeydown = (event) => {
     const { target, key } = event;
 
-    if (
-      [' ', 'Enter'].includes(key)
-    ) {
+    if ([' ', 'Enter'].includes(key)) {
       event.preventDefault();
       event.stopPropagation();
 

src/Popup/Popup.js

@@ -11,15 +11,15 @@ export default class Popup extends AriaComponent {
    * Initial expanded state.
    * @private
    *
-   * @type {Boolean}
+   * @type {bool}
    */
   #expanded = false;
 
   /**
    * Initial `type` option value.
    * @private
    *
-   * @type {Boolean}
+   * @type {bool}
    */
   #optionType = 'true'; // 'true' === 'menu' in UAs that don't support WAI-ARIA 1.1
 

src/Tablist/Tablist.js

@@ -17,14 +17,14 @@ export default class Tablist extends AriaComponent {
   /**
    * The initial active index.
    *
-   * @type {Number}
+   * @type {number}
    */
   #activeIndex = 0;
 
   /**
    * The previously-active index.
    *
-   * @type {Number}
+   * @type {number}
    */
   #switchedFrom = null;
 
@@ -72,7 +72,7 @@ export default class Tablist extends AriaComponent {
        * Whether the tabs are horizonally or vertically oriented.
        * Options: 'horizontal', 'vertical'.
        *
-       * @type {String}
+       * @type {string}
        */
       orientation: this.#orientation,
 
@@ -121,7 +121,7 @@ export default class Tablist extends AriaComponent {
   /**
    * Set the last-active index and update attributes accordingly.
    *
-   * @param {Number} previousIndex The previous index.
+   * @param {number} previousIndex The previous index.
    */
   set #previousIndex(previousIndex) {
     this.#switchedFrom = previousIndex;
@@ -141,7 +141,7 @@ export default class Tablist extends AriaComponent {
   /**
    * Get the previously-avtive index.
    *
-   * @return {Number}
+   * @return {number}
    */
   get previousIndex() {
     return this.#switchedFrom;
@@ -150,7 +150,7 @@ export default class Tablist extends AriaComponent {
   /**
    * Set the active index and update attributes accordingly.
    *
-   * @param {Number} newIndex The index to set as active.
+   * @param {number} newIndex The index to set as active.
    */
   set activeIndex(newIndex) {
     // Deactivate the previous tab-panel pair.
@@ -180,7 +180,7 @@ export default class Tablist extends AriaComponent {
   /**
    * Get the active index.
    *
-   * @return {Number}
+   * @return {number}
    */
   get activeIndex() {
     return this.#activeIndex;
@@ -286,8 +286,8 @@ export default class Tablist extends AriaComponent {
   /**
    * Returns the next index based on the key pressed.
    *
-   * @param  {string} key          The key name.
-   * @param  {number} currentIndex The currently event target.
+   * @param {string} key          The key name.
+   * @param {number} currentIndex The currently event target.
    * @return {number}              The index to which focus should move.
    */
   getNextIndex = (key, currentIndex) => {

src/Tablist/modules/automaticActivation.js

@@ -1,8 +1,8 @@
 /**
  * Tablist module for automatically activating tabs when moving focus.
  *
- * @param  {Tablist} arg.component An instance of Tablist.
- * @return {Function} The cleanup function.
+ * @param {Tablist} arg.component An instance of Tablist.
+ * @return {function} The cleanup function.
  */
 export default function AutomaticActivation({ component }) {
   /**

src/Tablist/modules/manageTabIndex.js

@@ -3,8 +3,8 @@ import { interactiveChildren } from '../../shared/interactiveChildren';
 /**
  * Tablist module for managing tabIndex for target interactive children.
  *
- * @param  {Tablist} arg.component An instance of Tablist.
- * @return {Function} The cleanup function.
+ * @param {Tablist} arg.component An instance of Tablist.
+ * @return {function} The cleanup function.
  */
 export default function ManageTabIndex({ component }) {
   /*

src/Tablist/modules/useHiddenAttribute.js

@@ -1,8 +1,8 @@
 /**
  * Tablist module to use the hidden attribute to hide hidden content :)
  *
- * @param  {Tablist} arg.component An instance of Tablist.
- * @return {Function} The cleanup function.
+ * @param {Tablist} arg.component An instance of Tablist.
+ * @return {function} The cleanup function.
  */
 export default function UseHiddenAttribute({ component }) {
   /**

src/shared/getElementPair.js

@@ -3,7 +3,7 @@
 /**
  * Get the controller and target elements based on the given element's attributes.
  *
- * @param  {HTMLElement} element Either the controller or target element.
+ * @param {HTMLElement} element Either the controller or target element.
  * @return {object} The controller and target elements.
  */
 const getElementPair = (element) => {