(chore) document new mobile menu stuff

sites/shared/components/workbench/menus/mobile-menubar.mjs

@@ -5,18 +5,25 @@ import { CloseIcon } from 'shared/components/icons.mjs'
 import { MobileMenubarContext } from 'shared/context/mobile-menubar-context.mjs'
 import { shownHeaderSelector } from 'shared/components/wrappers/header.mjs'
 
+/**
+ * A component to display menu buttons and actions in mobile.
+ * Draws its contents from items added to the {@link MobileMenubarContext}
+ * @returns
+ */
 export const MobileMenubar = () => {
   const { setModal, clearModal, modalContent } = useContext(ModalContext)
   const { menus, actions } = useContext(MobileMenubarContext)
   const [selectedModal, setSelectedModal] = useState(false)
 
+  // get the content of the selected modal because this is what will be changing if there are updates
   const selectedMenu = menus[selectedModal]
 
+  // when the content changes, or the selection changes
   useEffect(() => {
     // there's no selected modal, we're in the clear
     if (!selectedModal) return
 
-    // otherwise, set the modal and keep an internal record of having opened it
+    // generate a new modal with the content
     const Modal = () => {
       const closeModal = () => {
         setSelectedModal(false)
@@ -40,9 +47,11 @@ export const MobileMenubar = () => {
       )
     }
 
+    // set it
     setModal(Modal)
   }, [selectedMenu, selectedModal, clearModal, setModal])
 
+  // clear the selection if the modal was cleared externally
   useEffect(() => {
     if (modalContent === null) {
       setSelectedModal(false)
@@ -52,14 +61,14 @@ export const MobileMenubar = () => {
   return (
     <div
       className={`
-    lg:hidden
-    ${shownHeaderSelector('bottom-16')} 
-    sticky bottom-0 w-20 -ml-20 self-end
-    duration-300 transition-all 
-    flex flex-col-reverse gap-4
-    z-20
-    mobile-menubar
-    `}
+      lg:hidden
+      ${shownHeaderSelector('bottom-16')} 
+      sticky bottom-0 w-20 -ml-20 self-end
+      duration-300 transition-all 
+      flex flex-col-reverse gap-4
+      z-20
+      mobile-menubar
+      `}
     >
       {Object.keys(menus)
         .sort((a, b) => menus[a].order - menus[b].order)

sites/shared/components/workbench/menus/shared/menu-wrapper.mjs

@@ -3,6 +3,17 @@ import { WrenchIcon } from 'shared/components/icons.mjs'
 import { useMobileMenu } from 'shared/context/mobile-menubar-context.mjs'
 
 const defaultClasses = `w-1/3 shrink grow-0 lg:p-4 max-w-2xl h-full overflow-scroll`
+
+/**
+ * a wrapper that displays its contents normally on larger screens
+ * and adds its contents as a menu on the {@link MobileMenubar} for smaller screens
+ * @param {ReactChildren} children
+ * @param {String} wrapperClass - classes to add to the wrapper for larger screens
+ * @param {ReactComponent} Icon - Icon for the menu button on smaller screens
+ * @param {Boolean} [keepOpenOnClick=true] - should the modal for this menu stay open when clicked?
+ * @param {String} [type='settings'] - the type of menu this is. will be used to key the menu in the MobileMenubar
+ * @param {Number} [order=-1] - the order of this menu in the MobileMenubar
+ */
 export const MenuWrapper = ({
   children,
   wrapperClass = defaultClasses,
@@ -16,10 +27,9 @@ export const MenuWrapper = ({
       Icon,
       menuContent: children,
       keepOpenOnClick,
-      type,
       order,
     }),
-    [Icon, children, keepOpenOnClick, type]
+    [Icon, children, keepOpenOnClick, order]
   )
 
   useMobileMenu(type, menuProps)

sites/shared/components/workbench/new.mjs

@@ -76,6 +76,7 @@ export const Workbench = ({ design, Design, DynamicDocs }) => {
 
   const setView = useCallback(
     (newView) => {
+      // hacky little way to scroll to the top but keep the menu hidden if it was hidden
       const endScroll = Math.min(window.scrollY, 21)
       window.scrollTo({ top: 0, behavior: 'instant' })
       _setView(newView)

sites/shared/components/workbench/views/pattern-with-menu.mjs

@@ -4,6 +4,7 @@ import { MenuWrapper } from 'shared/components/workbench/menus/shared/menu-wrapp
 
 export const ns = headerNs
 
+/** a layout for views that include a drafted pattern, a sidebar menu, and the draft view header */
 export const PatternWithMenu = ({
   settings,
   ui,

sites/shared/components/workbench/views/view-header.mjs

@@ -1,4 +1,4 @@
-import { useContext, useEffect, useMemo } from 'react'
+import { useContext, useMemo } from 'react'
 import { PanZoomContext } from 'shared/components/workbench/pattern/pan-zoom-context.mjs'
 import { useMobileAction } from 'shared/context/mobile-menubar-context.mjs'
 import { useTranslation } from 'next-i18next'
@@ -80,10 +80,12 @@ export const ViewHeader = ({ update, settings, ui, control, setSettings }) => {
   const { t } = useTranslation(ns)
   const { zoomFunctions, zoomed } = useContext(PanZoomContext)
 
+  // make the zoom buttons so we can pass them to the mobile menubar
   const headerZoomButtons = useMemo(
     () => <ZoomButtons {...{ t, zoomFunctions, zoomed }} />,
     [zoomed, t, zoomFunctions]
   )
+  // add the zoom buttons as an action on the mobile menubar
   useMobileAction('zoom', { order: 0, actionContent: headerZoomButtons })
 
   return (