From 249a89ecd0acfae950271c24ee098f54528568f6 Mon Sep 17 00:00:00 2001 From: Akira Sudoh Date: Tue, 14 Apr 2020 12:16:34 +0900 Subject: [PATCH 1/2] docs(ui-shell): add JSDoc annotations Closes #5668. --- packages/components/.gitignore | 1 + .../src/components/ui-shell/header-nav.js | 22 ++++++++--- .../src/components/ui-shell/header-submenu.js | 18 ++++++++- .../components/ui-shell/product-switcher.js | 6 ++- .../src/components/ui-shell/side-nav.js | 38 ++++++++++++++++--- 5 files changed, 72 insertions(+), 13 deletions(-) diff --git a/packages/components/.gitignore b/packages/components/.gitignore index f4c23841b590..ecd884402972 100644 --- a/packages/components/.gitignore +++ b/packages/components/.gitignore @@ -9,6 +9,7 @@ demo/hot !demo/index.js !demo/components.js dist +docs/js # Test reports tests/a11y-results diff --git a/packages/components/src/components/ui-shell/header-nav.js b/packages/components/src/components/ui-shell/header-nav.js index 6023bc8d9b63..abbc1577d3c0 100644 --- a/packages/components/src/components/ui-shell/header-nav.js +++ b/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; diff --git a/packages/components/src/components/ui-shell/header-submenu.js b/packages/components/src/components/ui-shell/header-submenu.js index 8d017227e0d3..a9a5b333fd6f 100644 --- a/packages/components/src/components/ui-shell/header-submenu.js +++ b/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 butotn. + * @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 butotn. + * @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; diff --git a/packages/components/src/components/ui-shell/product-switcher.js b/packages/components/src/components/ui-shell/product-switcher.js index 826eb8576e2c..2343c38da45b 100644 --- a/packages/components/src/components/ui-shell/product-switcher.js +++ b/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; diff --git a/packages/components/src/components/ui-shell/side-nav.js b/packages/components/src/components/ui-shell/side-nav.js index 22e6c7f421de..443a0c4e0a94 100644 --- a/packages/components/src/components/ui-shell/side-nav.js +++ b/packages/components/src/components/ui-shell/side-nav.js @@ -15,11 +15,7 @@ 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 @@ -27,6 +23,26 @@ export default class SideNav extends mixin( */ 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 potions 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 potion 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; From f1412352fa5f52ff9a6d92666d60fa3c12f89edc Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Wed, 15 Apr 2020 11:09:30 -0700 Subject: [PATCH 2/2] fix(typo): fix typos in docs Co-Authored-By: emyarod --- packages/components/src/components/ui-shell/header-submenu.js | 4 ++-- packages/components/src/components/ui-shell/side-nav.js | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/components/src/components/ui-shell/header-submenu.js b/packages/components/src/components/ui-shell/header-submenu.js index a9a5b333fd6f..8db6c2a90fbd 100644 --- a/packages/components/src/components/ui-shell/header-submenu.js +++ b/packages/components/src/components/ui-shell/header-submenu.js @@ -28,7 +28,7 @@ class HeaderSubmenu extends mixin( * @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 butotn. + * @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. */ @@ -293,7 +293,7 @@ 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 butotn. + * @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. */ diff --git a/packages/components/src/components/ui-shell/side-nav.js b/packages/components/src/components/ui-shell/side-nav.js index 443a0c4e0a94..8ba847ed567b 100644 --- a/packages/components/src/components/ui-shell/side-nav.js +++ b/packages/components/src/components/ui-shell/side-nav.js @@ -137,13 +137,13 @@ class SideNav extends mixin(createComponent, initComponentBySearch, handles) { * @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 potions in non-nested 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 potion in non-nested nav items. + * 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]',