@stack-spot/portal-layout 0.0.64 → 1.0.0

package/src/components/error/ErrorManager.ts

@@ -1,31 +1,47 @@
-export interface ErrorDescription {
-  code?: number,
-  message?: string,
-  debug?: boolean,
-}
+import { ErrorDescription } from '@stack-spot/portal-components/ErrorFeedback'
 
 export type DescriptionFn = (error: any) => ErrorDescription
 export type ErrorHandler = (error: any) => void
 
+/**
+ * Setup how the Error Boundaries deal with errors.
+ */
 export class ErrorManager {
   private static descriptionFunction: DescriptionFn = error => ({
     message: error.message || `${error}`,
   })
   private static errorHandler: ErrorHandler | undefined
 
+  /**
+   * Sets a custom logic for generating error messages and codes. Also setups the environment (debug or not).
+   * @param fn a function that, given an error, generates its description.
+   */
   static setDescriptionFunction(fn: DescriptionFn) {
     this.descriptionFunction = fn
   }
 
+  /**
+   * Sets a custom error handler, i.e. a function to run every time an error is catch by an ErrorBoundary.
+   * @param fn a function that receives the error.
+   */
   static setErrorHandler(handler: ErrorHandler) {
     this.errorHandler = handler
   }
 
+  /**
+   * Uses the error descriptor to describe an error.
+   * @param error the error
+   * @returns the error description
+   */
   static describe(error: any) {
     return this.descriptionFunction(error)
   }
 
+  /**
+   * Runs the error handler, if any has been setup.
+   * @param error the error
+   */
   static runErrorHandler(error: any) {
-    return this.errorHandler?.(error)
+    this.errorHandler?.(error)
   }
 }

package/src/components/error/SilentErrorBoundary.tsx

@@ -1,16 +1,26 @@
+import { ErrorDescription } from '@stack-spot/portal-components/ErrorFeedback'
 import { theme } from '@stack-spot/portal-theme'
 import { Component } from 'react'
-import { ErrorDescription, ErrorManager } from './ErrorManager'
+import { ErrorManager } from './ErrorManager'
 
 interface State extends ErrorDescription {
   hasError: boolean,
-  message?: string,
 }
 
 interface Props {
   children: React.ReactNode,
 }
 
+/**
+ * An Error Boundary that doesn't render anything if any of its children throws. If the environment is not production, a small error icon
+ * is rendered instead of nothing.
+ * 
+ * To customize how the error is logged, setup an error descriptor for the ErrorManager class. If you're using the component `Layout` or
+ * `RawLayout`, you can use the property `errorDescriptor`.
+ * 
+ * To run an error handler every time an error is catch by this boundary, setup an error handler for the ErrorManager class. If you're
+ * using the component `Layout` or `RawLayout`, you can use the property `onError`.
+ */
 export class SilentErrorBoundary extends Component<Props, State> {
   constructor(props: Props) {
     super(props)

package/src/components/menu/MenuContent.tsx

@@ -1,17 +1,15 @@
-/* eslint-disable react-refresh/only-export-components */
-/* eslint-disable @typescript-eslint/no-unused-vars */
 import { Flex, IconBox, Text } from '@citric/core'
 import { ArrowLeft, ChevronDown } from '@citric/icons'
 import { LoadingCircular } from '@citric/ui'
+import { useCheckTextOverflow } from '@stack-spot/portal-components'
+import { useAnchorTag } from '@stack-spot/portal-components/anchor'
 import { listToClass, theme } from '@stack-spot/portal-theme'
 import { useMemo, useState } from 'react'
 import { styled } from 'styled-components'
-import { useAnchorTag } from '../../layout-context'
 import { hideOverlayImmediately } from './MenuSections'
 import { PageSelector } from './PageSelector'
 import { MENU_CONTENT_ITEM_PADDING as ITEM_PADDING, MENU_CONTENT_PADDING as PADDING } from './constants'
 import { ItemGroup, MenuAction, MenuItem, MenuSectionContent } from './types'
-import { useCheckTextOverflow } from './use-check-text-overflow'
 
 const BackLink = styled.a`
   display: flex;
@@ -22,6 +20,9 @@ const BackLink = styled.a`
   gap: 6px;
 `
 
+/**
+ * The list (<ul>) used for grouping items in a menu.
+ */
 export const MenuGroup = styled.ul`
   padding: 0 0 0 16px;
   display: flex;
@@ -33,30 +34,18 @@ export const MenuGroup = styled.ul`
     padding: 0;
   }
 
-  .item-row-group > a {
-    padding: 0 16px;
-    margin: 0;
-    border-radius: 0;
-  }
-
-  .item-row-group > a::before {
-    content: '';
-    position: absolute;
-    top: 0;
-    left: 0;
-    right: 0;
-    bottom: 0;
-    background-color: var(--light-300);
-    opacity: 0.24;
-    border-radius: inherit;
-  }
-
   .item-row {
     display: flex;
     flex-direction: row;
     gap: 8px;
     align-items: center;
 
+    &.root {
+      padding: 0 16px;
+      margin-top: 16px;
+      border-radius: 0;
+    }
+
     .label {
       flex: 1;
       &.hidden, &.ellipsis {
@@ -68,10 +57,6 @@ export const MenuGroup = styled.ul`
       }
     }
   }
-  
-  .item-row-group {
-    margin-top: 16px;
-  }
 
   li a {
     position: relative;
@@ -129,7 +114,7 @@ export const MenuGroup = styled.ul`
   &.open {
     visibility: visible;
     transition: unset;
-    & > li > a, & > li > .item-row-group > a  {
+    & > li > a  {
       height: 40px;
     }
   }
@@ -158,12 +143,19 @@ export const MenuGroup = styled.ul`
   }
 `
 
+/**
+ * The header (<header>) for a group of items in a menu. Contains the title of the group.
+ */
 export const Title = styled.header`
   display: flex;
   flex-direction: column;
   margin: ${PADDING}px 0 24px ${PADDING}px;
 `
 
+/**
+ * A menu item that performs an action.
+ * @param props the props for the component {@link MenuAction}.
+ */
 export const ActionItem = ({ label, onClick, href, active, icon, badge, overflow = 'wrap' }: MenuAction) => {
   const Link = useAnchorTag()
   const { ref, overflow: textOverflow } = useCheckTextOverflow()
@@ -189,6 +181,11 @@ export const ActionItem = ({ label, onClick, href, active, icon, badge, overflow
   )
 }
 
+/**
+ * A menu item that is actually a subgroup and can be collapsed/expanded.
+ * @param props the props for the component {@link ItemGroup} & { root: boolean }. Pass root=true to style this group as a root group.
+ * Root groups have slightly different visuals.
+ */
 const CollapsibleGroupItem = ({ label, open: initiallyOpened, children, icon, badge, root, overflow = 'wrap' }:
   ItemGroup & { root?: boolean }) => {
   const [open, setOpen] = useState(initiallyOpened ?? children?.some(c => 'active' in c && c.active) ?? false)
@@ -200,7 +197,7 @@ const CollapsibleGroupItem = ({ label, open: initiallyOpened, children, icon, ba
       <a
         onClick={() => setOpen(!open)}
         onKeyDown={e => e.key === 'Enter' && setOpen(!open)}
-        className="item-row"
+        className={listToClass(['item-row', root && 'root'])}
         tabIndex={0}
         aria-controls={id}
         aria-expanded={open}
@@ -223,38 +220,22 @@ const CollapsibleGroupItem = ({ label, open: initiallyOpened, children, icon, ba
   )
 }
 
-const RootGroupItem = (props: ItemGroup) => {
-  const items = useMemo(() => props.children?.filter(i => !i.hidden).map(renderOption), [props.children])
-
-  return <>
-    {items.length ? <div className="item-row-group">
-      <CollapsibleGroupItem {...props} open={true} root={true} />
-    </div> :
-      <>
-        <div className="item-row">
-          {props.icon}
-          <Text appearance="overheader2" colorScheme="light.700" className={`group-title label ${props.overflow}`}>{props.label}</Text>
-          {props.badge}
-        </div>
-        <MenuGroup className="open no-indentation">{items}</MenuGroup>
-      </>
-    }
-  </>
-}
-
-const GroupItem = ({ root, ...item }: ItemGroup & { root?: boolean }) => (
-  root ? <RootGroupItem {...item} /> : <CollapsibleGroupItem {...item} />
-)
-
 function renderOption({ root, ...option }: MenuItem & { root?: boolean }) {
   const labelText = typeof option.label === 'string' ? option.label : option.label.id
   return (
     <li key={labelText} role="menuitem" aria-selected={'children' in option ? undefined : option.active}>
-      {'children' in option ? <GroupItem root={root} {...option} /> : <ActionItem {...option} />}
+      {'children' in option ? <CollapsibleGroupItem {...option} root={root} open={option.open ?? root} /> : <ActionItem {...option} />}
     </li >
   )
 }
 
+/**
+ * Renders a menu-content interface.
+ * 
+ * Considering the Stackspot UI, this is the "menu content", not the "menu sections", i.e. it's the second menu from left to right, the
+ * one that changes according to section selected. 
+ * @param props the props for the component {@link MenuSectionContent}.
+ */
 export const MenuContent = ({ pageSelector, goBack, title, subtitle, afterTitle, options = [], loading, error }: MenuSectionContent) => {
   const items = useMemo(() => options.filter(o => !o.hidden).map(o => renderOption({ ...o, root: true })), [options])
 

package/src/components/menu/MenuSections.tsx

@@ -1,32 +1,54 @@
 import { Flex, IconBox, Text } from '@citric/core'
 import { ChevronRight, Cog, Collapse, Expand } from '@citric/icons'
+import { useKeyboardControls } from '@stack-spot/portal-components'
+import { useAnchorTag } from '@stack-spot/portal-components/anchor'
 import { Dictionary, interpolate, useTranslate } from '@stack-spot/portal-translate'
 import { useCallback, useMemo, useState } from 'react'
 import { elementIds, getLayoutElements } from '../../elements'
-import { useAnchorTag } from '../../layout-context'
 import { MenuContent } from './MenuContent'
 import { MenuProps, MenuSection } from './types'
-import { useKeyboardControls } from './use-keyboard-controls'
 
+/**
+ * Amount of time to wait before hiding the menu overlay once the mouse leaves its area.
+ */
 const HIDE_OVERLAY_DELAY_MS = 400
 const MENU_OVERLAY_ID = 'menuContentOverlay'
 
+/**
+ * Pointer to the latest "hideOverlay" task. This allows the operation to be cancelled.
+ */
 let hideOverlayTask: number | undefined
 
-// fixme: this should definitely not be handled like this...
+/**
+ * Accessibility. Makes the menu overlay accessible through the keyboard.
+ */
 let attachKeyboardListenersForOverlay: () => void
+/**
+ * Accessibility. Makes the menu overlay invisible to the keyboard.
+ */
 let detachKeyboardListenersForOverlay: () => void
 
+/**
+ * Hides the menu overlay after HIDE_OVERLAY_DELAY_MS. This operation may be canceled.
+ * 
+ * This gives the user some time to move the mouse outside the overlay for while before it disappears. If the user moves the mouse out of
+ * the overlay and, before HIDE_OVERLAY_DELAY_MS, moves the mouse back, we want the overlay to keep showing.
+ */
 function hideOverlay() {
   if (hideOverlayTask !== undefined) return
   hideOverlayTask = window.setTimeout(hideOverlayImmediately, HIDE_OVERLAY_DELAY_MS)
 }
 
+/**
+ * Accessibility. Returns the accessibility button of the section with the preview (overlay) currently active. 
+ */
 function getAccessibilityButtonOfSectionWithActiveOverlay(): HTMLElement | null | undefined {
   return document.getElementById(elementIds.menuSections)?.querySelector('button[aria-expanded="true"]')
 }
 
-// eslint-disable-next-line react-refresh/only-export-components
+/**
+ * Hides the menu overlay without waiting for anything. This is not cancellable.
+ */
 export function hideOverlayImmediately() {
   detachKeyboardListenersForOverlay?.()
   const overlay = document.getElementById(MENU_OVERLAY_ID)
@@ -36,12 +58,18 @@ export function hideOverlayImmediately() {
   getAccessibilityButtonOfSectionWithActiveOverlay()?.setAttribute('aria-expanded', 'false')
 }
 
+/**
+ * If `hideOverlay` was called and not fulfilled yet, this cancels the task, preventing the overlay from closing.
+ */
 function cancelHideOverlayTask() {
   if (hideOverlayTask === undefined) return
   clearTimeout(hideOverlayTask)
   hideOverlayTask = undefined
 }
 
+/**
+ * Shows the menu overlay.
+ */
 function showOverlay() {
   cancelHideOverlayTask()
   const overlay = document.getElementById(MENU_OVERLAY_ID)
@@ -51,10 +79,23 @@ function showOverlay() {
   attachKeyboardListenersForOverlay?.()
 }
 
+/**
+ * Checks if the menu content (2nd menu list from left to right) is visible or not.
+ * The menu content is visible if:
+ * 1. The menu is not compact (the button at the end of the section list compacts/expands the menu);
+ * 2. If the current section has any menu content.
+ */
 function isMenuContentVisible() {
   return !!document.getElementById('layout')?.classList?.contains('menu-content-visible')
 }
 
+/**
+ * A section in the the menu-sections.
+ * 
+ * A section in the menu is responsible for rendering the section icon, label, accessibility button and controlling the menu overlay.
+ * @param props React props for the component {@link MenuSection} & { id, setCurrentOverlay }. Id identifies the current section and
+ * setCurrentOverlay controls the overlay (preview) content.
+ */
 const Section = ({
   icon,
   label,
@@ -64,7 +105,6 @@ const Section = ({
   active,
   content,
   customContent,
-  onOpen,
   setCurrentOverlay,
   id,
   hasContent,
@@ -88,7 +128,6 @@ const Section = ({
 
   function prepareShowOverlay(event: React.MouseEvent<HTMLAnchorElement, MouseEvent> | React.KeyboardEvent<any>) {
     if (!shouldShowOverlay()) return
-    onOpen?.()
     const anchorElement = event.target as HTMLElement
     const accessibilityButton = anchorElement?.parentElement?.querySelector('button') as HTMLElement
     accessibilityButton?.setAttribute('aria-expanded', 'true')
@@ -104,58 +143,69 @@ const Section = ({
   const labelText = typeof label === 'string' ? label : label.id
 
   return (
-    <>
-      <li
-        role="menuitem"
-        key={labelText}
+    <li
+      role="menuitem"
+      key={labelText}
+      title={labelText}
+      className={`section-submenu ${className || ''} ${active ? 'active' : ''}`}
+      aria-selected={active}>
+      <Link
+        href={href}
+        target={target}
+        onClick={click}
+        onMouseEnter={prepareShowOverlay}
+        onMouseLeave={() => shouldShowOverlay() && hideOverlay()}
         title={labelText}
-        className={`section-submenu ${className || ''} ${active ? 'active' : ''}`}
-        aria-selected={active}>
-        <Link
-          href={href}
-          target={target}
-          onClick={click}
-          onMouseEnter={prepareShowOverlay}
-          onMouseLeave={() => shouldShowOverlay() && hideOverlay()}
-          title={labelText}
-          aria-label={labelText}
-          onKeyDown={onClick ? e => e.key === 'Enter' && onClick() : undefined}
-          {...(active ? { 'aria-current': 'page' } : undefined)}
-          {...(!href ? { 'tabIndex': 0 } : undefined)}
-        >
-          <Flex alignItems="center" justifyContent="center" px={5}>
-            <IconBox>{icon}</IconBox>
-            {typeof label === 'string' ? <Text appearance="microtext1" className="section-label" ml={3}>{label}</Text> : label.element}
-          </Flex>
-        </Link>
-        {shouldShowOverlay() &&
-          <IconBox size="sm" className="section-submenu-icon"
-            as="button"
-            aria-label={interpolate(t.menuOptions, label)}
-            aria-controls={MENU_OVERLAY_ID}
-            aria-expanded={false}
-            onKeyDown={(event) => {
-              if (event.key === 'Enter') {
-                prepareShowOverlay(event)
-              }
-            }}>
-            <ChevronRight />
-          </IconBox>
-        }
-      </li>
-    </>
+        aria-label={labelText}
+        onKeyDown={onClick ? e => e.key === 'Enter' && onClick() : undefined}
+        {...(active ? { 'aria-current': 'page' } : undefined)}
+        {...(!href ? { 'tabIndex': 0 } : undefined)}
+      >
+        <Flex alignItems="center" justifyContent="center" px={5}>
+          <IconBox>{icon}</IconBox>
+          {typeof label === 'string' ? <Text appearance="microtext1" className="section-label" ml={3}>{label}</Text> : label.element}
+        </Flex>
+      </Link>
+      {shouldShowOverlay() &&
+        <IconBox size="sm" className="section-submenu-icon"
+          as="button"
+          aria-label={interpolate(t.menuOptions, label)}
+          aria-controls={MENU_OVERLAY_ID}
+          aria-expanded={false}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') {
+              prepareShowOverlay(event)
+            }
+          }}>
+          <ChevronRight />
+        </IconBox>
+      }
+    </li>
   )
 }
 
+/**
+ * Renders the overlay content.
+ * @param props the content of the overlay, can be either customized (react component), a config object or a function that creates the
+ * config object.
+ * @returns the content
+ */
 const OverlayRenderer = ({ content, customContent }: Pick<MenuSection, 'content' | 'customContent'>) => {
   if (customContent) {
-    return <div id="custom-selectable-item"> {customContent} </div>
+    return <div id="custom-selectable-item">{customContent}</div>
   }
 
   const data = typeof content === 'function' ? content() : content
   return <MenuContent {...data} />
 }
 
+/**
+ * Renders a menu-sections interface.
+ * 
+ * Considering the Stackspot UI, this is the "menu sections", not the "menu content", i.e. it's the first menu from left to right, the
+ * one with the icons and section names: the main menu. 
+ * @param props the props for the component {@link MenuProps}.
+ */
 export const MenuSections = ({ sections = [], ...props }: MenuProps) => {
   const Link = useAnchorTag()
   const t = useTranslate(dictionary)
@@ -199,7 +249,8 @@ export const MenuSections = ({ sections = [], ...props }: MenuProps) => {
     querySelectors: 'li a.action, #custom-selectable-item button, #custom-selectable-item input',
   })
 
-  // fixme: this should definitely not be handled like this...
+  // this only works because we have a single section menu in the site. This workaround was created since the keyboard controls were
+  // transformed into a hook. This is not ideal and it would be a good idea to rewrite this code without the need for this.
   attachKeyboardListenersForOverlay = attachKeyboardListeners
   detachKeyboardListenersForOverlay = detachKeyboardListeners
 
@@ -246,7 +297,6 @@ export const MenuSections = ({ sections = [], ...props }: MenuProps) => {
 
       <div id={MENU_OVERLAY_ID} onMouseEnter={showOverlay} onMouseLeave={hideOverlay} ref={overlayRef}>
         {renderMenuOverlay()}
-        <div className="arrow"></div>
       </div>
     </>
   )
@@ -264,7 +314,7 @@ const dictionary = {
     toggle: 'Visualizar ou esconder o menu',
     menuOptions: 'Visualizar opções do menu $0',
     settings: 'Configurações',
-    settingsIcon: 'Icone de configurações',
+    settingsIcon: 'Ícone de configurações',
     hide: 'Esconder',
   },
 } satisfies Dictionary

package/src/components/menu/PageSelector.tsx

@@ -1,15 +1,15 @@
 import { IconBox, Text } from '@citric/core'
 import { ArrowRight, Select } from '@citric/icons'
 import { LoadingCircular } from '@citric/ui'
+import { useCheckTextOverflow } from '@stack-spot/portal-components'
+import { ListAction, SelectionList } from '@stack-spot/portal-components/SelectionList'
+import { useAnchorTag } from '@stack-spot/portal-components/anchor'
 import { theme } from '@stack-spot/portal-theme'
 import { Dictionary, interpolate, useTranslate } from '@stack-spot/portal-translate'
 import { KeyboardEvent, useMemo, useRef, useState } from 'react'
 import { styled } from 'styled-components'
-import { useAnchorTag } from '../../layout-context'
-import { ListAction, SelectionList } from '../SelectionList'
 import { MENU_CONTENT_PADDING as PADDING } from './constants'
 import { Selector } from './types'
-import { useCheckTextOverflow } from './use-check-text-overflow'
 
 const SelectorBox = styled.div`
   position: relative;
@@ -81,6 +81,11 @@ const SelectorBox = styled.div`
   }
 `
 
+/**
+ * A selector component to render inside a menu-content. Allows the user to select another page.
+ * 
+ * @param props the React props for the component {@link Selector}.
+ */
 export const PageSelector = ({ options, value, button, loading, title }: Selector) => {
   const Link = useAnchorTag()
   const t = useTranslate(dictionary)