docs(ui-shell): add JSDoc annotations (#5862)

Closes #5668.

packages/components/.gitignore

@@ -9,6 +9,7 @@ demo/hot
 !demo/index.js
 !demo/components.js
 dist
+docs/js
 
 # Test reports
 tests/a11y-results

packages/components/src/components/ui-shell/header-nav.js

@@ -14,11 +14,18 @@ import settings from '../../globals/js/settings';
 
 const toArray = arrayLike => Array.prototype.slice.call(arrayLike);
 
-export default class HeaderNav extends mixin(
-  createComponent,
-  initComponentBySearch,
-  handles
-) {
+class HeaderNav extends mixin(createComponent, initComponentBySearch, handles) {
+  /**
+   * Header nav.
+   * @extends CreateComponent
+   * @extends InitComponentBySearch
+   * @extends Handles
+   * @param {HTMLElement} element The element working as an header nav.
+   * @param {object} [options] The component options.
+   * @param {string} [options.selectorSubmenu] The CSS selector to find sub menus.
+   * @param {string} [options.selectorSubmenuLink] The CSS selector to find the trigger buttons of sub menus.
+   * @param {string} [options.selectorSubmenuItem] The CSS selector to find the sub menu items.
+   */
   constructor(element, options) {
     super(element, options);
     this.manage(on(this.element, 'keydown', this._handleKeyDown));
@@ -92,6 +99,9 @@ export default class HeaderNav extends mixin(
    * @member HeaderNav.options
    * @type {object}
    * @property {string} selectorInit The data attribute to find side navs.
+   * @property {string} [selectorSubmenu] The CSS selector to find sub menus.
+   * @property {string} [selectorSubmenuLink] The CSS selector to find the trigger buttons of sub menus.
+   * @property {string} [selectorSubmenuItem] The CSS selector to find the sub menu items.
    */
   static get options() {
     const { prefix } = settings;
@@ -117,3 +127,5 @@ export default class HeaderNav extends mixin(
     FORWARD: 1,
   };
 }
+
+export default HeaderNav;

packages/components/src/components/ui-shell/header-submenu.js

@@ -16,11 +16,22 @@ import eventMatches from '../../globals/js/misc/event-matches';
 const forEach = /* #__PURE__ */ (() => Array.prototype.forEach)();
 const toArray = arrayLike => Array.prototype.slice.call(arrayLike);
 
-export default class HeaderSubmenu extends mixin(
+class HeaderSubmenu extends mixin(
   createComponent,
   initComponentBySearch,
   handles
 ) {
+  /**
+   * Sub menus in header nav.
+   * @extends CreateComponent
+   * @extends InitComponentBySearch
+   * @extends Handles
+   * @param {HTMLElement} element The element working as a submenu in header nav.
+   * @param {object} [options] The component options.
+   * @param {string} [options.selectorTrigger] The CSS selector to find the trigger button.
+   * @param {string} [options.selectorItem] The CSS selector to find the menu items.
+   * @param {string} [options.attribExpanded] The attribute that represents the expanded/collapsed state.
+   */
   constructor(element, options) {
     super(element, options);
     const hasFocusOut = 'onfocusout' in window;
@@ -282,6 +293,9 @@ export default class HeaderSubmenu extends mixin(
    * @member HeaderSubmenu.options
    * @type {object}
    * @property {string} selectorInit The data attribute to find side navs.
+   * @property {string} [selectorTrigger] The CSS selector to find the trigger button.
+   * @property {string} [selectorItem] The CSS selector to find the menu items.
+   * @property {string} [attribExpanded] The attribute that represents the expanded/collapsed state.
    */
   static get options() {
     const { prefix } = settings;
@@ -306,3 +320,5 @@ export default class HeaderSubmenu extends mixin(
     FORWARD: 1,
   };
 }
+
+export default HeaderSubmenu;

packages/components/src/components/ui-shell/product-switcher.js

@@ -5,9 +5,9 @@ import onFocusOutByKeyboard from '../../globals/js/misc/on-focus-by-keyboard';
 
 let seq = 0;
 
-export default class ProductSwitcher extends NavigationMenuPanel {
+class ProductSwitcher extends NavigationMenuPanel {
   /**
-   * A navigation menu
+   * A navigation menu.
    * @extends NavigationMenuPanel
    * @param {HTMLElement} element The element working as a selector.
    * @param {object} [options] The component options.
@@ -195,3 +195,5 @@ export default class ProductSwitcher extends NavigationMenuPanel {
     });
   }
 }
+
+export default ProductSwitcher;

packages/components/src/components/ui-shell/side-nav.js

@@ -15,18 +15,34 @@ import eventMatches from '../../globals/js/misc/event-matches';
 
 const { prefix } = settings;
 
-export default class SideNav extends mixin(
-  createComponent,
-  initComponentBySearch,
-  handles
-) {
+class SideNav extends mixin(createComponent, initComponentBySearch, handles) {
   /**
    * The map associating DOM element and copy button UI instance.
    * @member SideNav.components
    * @type {WeakMap}
    */
   static components /* #__PURE_CLASS_PROPERTY__ */ = new WeakMap();
 
+  /**
+   * Side nav.
+   * @extends CreateComponent
+   * @extends InitComponentBySearch
+   * @extends Handles
+   * @param {HTMLElement} element The element working as a side nav.
+   * @param {object} [options] The component options.
+   * @param {string} [options.selectorSideNavToggle]
+   *   The CSS selector to find the toggle button.
+   * @param {string} [options.selectorSideNavSubmenu] The CSS selector to find the trigger buttons for sub nav items.
+   * @param {string} [options.selectorSideNavItem] The CSS selector to find the nav items.
+   * @param {string} [options.selectorSideNavLink] The CSS selector to find the interactive potions in non-nested nav items.
+   * @param {string} [options.selectorSideNavLinkCurrent]
+   *   The CSS selector to find the interactive potion in active non-nested nav item.
+   * @param {string} [options.classSideNavExpanded] The CSS class for the expanded state.
+   * @param {string} [options.classSideNavItemActive]
+   *   The CSS class for the active/inactive state for nav items.
+   * @param {string} [options.classSideNavLinkCurrent]
+   *   The CSS class for the active/inactive state of the interactive potion in non-nested nav items.
+   */
   constructor(element, options) {
     super(element, options);
     this.manage(on(element, 'click', this._handleClick));
@@ -118,6 +134,16 @@ export default class SideNav extends mixin(
    * @member SideNav.options
    * @type {object}
    * @property {string} selectorInit The data attribute to find side navs.
+   * @property {string} [selectorSideNavToggle] The CSS selector to find the toggle button.
+   * @property {string} [selectorSideNavSubmenu] The CSS selector to find the trigger buttons for sub nav items.
+   * @property {string} [selectorSideNavItem] The CSS selector to find the nav items.
+   * @property {string} [selectorSideNavLink] The CSS selector to find the interactive portions in non-nested nav items.
+   * @property {string} [selectorSideNavLinkCurrent]
+   *   The CSS selector to find the interactive potion in active non-nested nav item.
+   * @property {string} [classSideNavExpanded] The CSS class for the expanded state.
+   * @property {string} [classSideNavItemActive] The CSS class for the active/inactive state for nav items.
+   * @property {string} [classSideNavLinkCurrent]
+   *   The CSS class for the active/inactive state of the interactive portion in non-nested nav items.
    */
   static options /* #__PURE_CLASS_PROPERTY__ */ = {
     selectorInit: '[data-side-nav]',
@@ -131,3 +157,5 @@ export default class SideNav extends mixin(
     classSideNavLinkCurrent: `${prefix}--side-nav__link--current`,
   };
 }
+
+export default SideNav;