chore: cleaning up docs and comments

Author: tespin

client/components/Menubar/Menubar.jsx

@@ -11,16 +11,12 @@ import { MenuOpenContext, MenubarContext } from './contexts';
 import usePrevious from '../../common/usePrevious';
 
 /**
- * @component
- * @param {object} props
+ * Menubar manages a collection of menu items and their submenus. It provides keyboard navigation,
+ * focus and state management, and other accessibility features for the menu items and submenus.
+ *
  * @param {React.ReactNode} props.children - Menu items that will be rendered in the menubar
  * @param {string} [props.className='nav__menubar'] - CSS class name to apply to the menubar
  * @returns {JSX.Element}
- */
-
-/**
- * Menubar manages a collection of menu items and their submenus. It provides keyboard navigation,
- * focus and state management, and other accessibility features for the menu items and submenus.
  *
  * @example
  * <Menubar>
@@ -31,20 +27,16 @@ import usePrevious from '../../common/usePrevious';
  */
 
 function Menubar({ children, className }) {
-  // core state for menu management
   const [menuOpen, setMenuOpen] = useState('none');
   const [activeIndex, setActiveIndex] = useState(0);
   const prevIndex = usePrevious(activeIndex);
   const [hasFocus, setHasFocus] = useState(false);
 
-  // refs for menu items and their ids
   const menuItems = useRef(new Set()).current;
   const menuItemToId = useRef(new Map()).current;
 
-  // ref for hiding submenus
   const timerRef = useRef(null);
 
-  // get the id of a menu item by its index
   const getMenuId = useCallback(
     (index) => {
       const items = Array.from(menuItems);
@@ -54,9 +46,6 @@ function Menubar({ children, className }) {
     [menuItems, menuItemToId, activeIndex]
   );
 
-  /**
-   * navigation functions
-   */
   const prev = useCallback(() => {
     const newIndex = (activeIndex - 1 + menuItems.size) % menuItems.size;
     setActiveIndex(newIndex);
@@ -85,8 +74,6 @@ function Menubar({ children, className }) {
     setActiveIndex(menuItems.size - 1);
   }, []);
 
-  // closes the menu and returns focus to the active menu item
-  // is called on Escape key press
   const close = useCallback(() => {
     if (menuOpen === 'none') return;
 
@@ -96,27 +83,17 @@ function Menubar({ children, className }) {
     activeNode.focus();
   }, [activeIndex, menuItems, menuOpen]);
 
-  // toggle the open state of a submenu
   const toggleMenuOpen = useCallback((id) => {
     setMenuOpen((prevState) => (prevState === id ? 'none' : id));
   });
 
-  /**
-   * Register top level menu items. Stores both the DOM node and the id of the submenu.
-   * Access to the DOM node is needed for focus management and tabindex control,
-   * while the id is needed to toggle the submenu open and closed.
-   *
-   * @param {React.RefObject} ref - a ref to the DOM node of the menu item
-   * @param {string} submenuId - the id of the submenu that the menu item opens
-   *
-   */
   const registerTopLevelItem = useCallback(
     (ref, submenuId) => {
       const menuItemNode = ref.current;
 
       if (menuItemNode) {
         menuItems.add(menuItemNode);
-        menuItemToId.set(menuItemNode, submenuId); // store the id of the submenu
+        menuItemToId.set(menuItemNode, submenuId);
       }
 
       return () => {
@@ -127,9 +104,6 @@ function Menubar({ children, className }) {
     [menuItems, menuItemToId]
   );
 
-  /**
-   * focus and blur management
-   */
   const clearHideTimeout = useCallback(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
@@ -164,7 +138,6 @@ function Menubar({ children, className }) {
     [nodeRef]
   );
 
-  // keyboard navigation
   const keyHandlers = {
     ArrowLeft: (e) => {
       e.preventDefault();
@@ -183,7 +156,6 @@ function Menubar({ children, className }) {
     },
     Tab: (e) => {
       e.stopPropagation();
-      // close
     },
     Home: (e) => {
       e.preventDefault();
@@ -195,17 +167,15 @@ function Menubar({ children, className }) {
       e.stopPropagation();
       last();
     }
-    // to do: support direct access keys
+    // TO DO: support direct access keys
   };
 
-  // focus the active menu item and set its tabindex
   useEffect(() => {
     if (activeIndex !== prevIndex) {
       const items = Array.from(menuItems);
       const activeNode = items[activeIndex];
       const prevNode = items[prevIndex];
 
-      // roving tabindex
       prevNode?.setAttribute('tabindex', '-1');
       activeNode?.setAttribute('tabindex', '0');
 
@@ -219,7 +189,6 @@ function Menubar({ children, className }) {
     clearHideTimeout();
   }, [clearHideTimeout]);
 
-  // context value for dropdowns and menu items
   const contextValue = useMemo(
     () => ({
       createMenuHandlers: (menu) => ({

client/components/Menubar/MenubarItem.jsx

@@ -4,29 +4,26 @@ import { MenubarContext, SubmenuContext, ParentMenuContext } from './contexts';
 import ButtonOrLink from '../../common/ButtonOrLink';
 
 /**
+ * MenubarItem wraps a button or link in an accessible list item that
+ * integrates with keyboard navigation and other submenu behaviors.
+ *
+ * TO DO: how to document props passed through spread operator?
  * @component
  * @param {object} props
  * @param {string} [props.className='nav__dropdown-item'] - CSS class name to apply to the list item
  * @param {string} props.id - The id of the list item
  * @param {string} [props.role='menuitem'] - The role of the list item
- * @param {boolean} [props.isDisabled=false] - Whether to hide the item
+ * @param {boolean} [props.isDisabled=false] - Whether to disable the item
  * @param {boolean} [props.selected=false] - Whether the item is selected
  * @returns {JSX.Element}
- */
-
-/**
- * MenubarItem wraps a button or link in an accessible list item that
- * integrates with keyboard navigation and other submenu behaviors.
  *
- * @example
- * ```jsx
- * // basic MenubarItem with click handler and keyboard shortcut
+ * @example <caption>Basic MenubarItem with click handler and keyboard shortcut</caption>
  * <MenubarItem id="sketch-run" onClick={() => dispatch(startSketch())}>
  *   Run
  *   <span className="nav__keyboard-shortcut">{metaKeyName}+Enter</span>
  * </MenubarItem>
  *
- * // as an option in a listbox
+ * @example <caption>as an option in a listbox</caption>
  * <MenubarItem
  *   id={key}
  *   key={key}
@@ -37,7 +34,6 @@ import ButtonOrLink from '../../common/ButtonOrLink';
  * >
  *   {languageKeyToLabel(key)}
  * </MenubarItem>
- * ```
  */
 
 function MenubarItem({
@@ -48,7 +44,6 @@ function MenubarItem({
   selected,
   ...rest
 }) {
-  // core context and state management
   const { createMenuItemHandlers, hasFocus } = useContext(MenubarContext);
   const {
     setSubmenuActiveIndex,
@@ -57,17 +52,13 @@ function MenubarItem({
   } = useContext(SubmenuContext);
   const parent = useContext(ParentMenuContext);
 
-  // ref for the list item
   const menuItemRef = useRef(null);
 
-  // handlers from parent menu
   const handlers = createMenuItemHandlers(parent);
 
-  // role and aria-selected
   const role = customRole || 'menuitem';
   const ariaSelected = role === 'option' ? { 'aria-selected': selected } : {};
 
-  // focus submenu item on mouse enter
   const handleMouseEnter = () => {
     if (hasFocus) {
       const items = Array.from(submenuItems);
@@ -78,7 +69,6 @@ function MenubarItem({
     }
   };
 
-  // register with parent submenu for keyboard navigation
   useEffect(() => {
     const unregister = registerSubmenuItem(menuItemRef);
     return unregister;
@@ -107,25 +97,21 @@ function MenubarItem({
 
 MenubarItem.propTypes = {
   ...ButtonOrLink.propTypes,
+  className: PropTypes.string,
   id: PropTypes.string,
-  onClick: PropTypes.func,
-  value: PropTypes.string,
   /**
    * Provides a way to deal with optional items.
    */
-  isDisabled: PropTypes.bool,
-  className: PropTypes.string,
   role: PropTypes.oneOf(['menuitem', 'option']),
+  isDisabled: PropTypes.bool,
   selected: PropTypes.bool
 };
 
 MenubarItem.defaultProps = {
-  onClick: null,
-  value: null,
-  isDisabled: false,
   className: 'nav__dropdown-item',
-  role: 'menuitem',
   id: undefined,
+  role: 'menuitem',
+  isDisabled: false,
   selected: false
 };