@stack-spot/citric-react 0.1.0

package/src/components/Link.tsx

@@ -0,0 +1,40 @@
+import { useCitricController } from '../context/hooks'
+import { HTMLExtension, TextAppearance, WithColor } from '../types'
+import { applyColor, applyTextAppearance } from '../utils/css'
+import { asCitricProps, CitricComponent } from './CitricComponent'
+
+export interface BaseLinkProps extends WithColor {
+  /**
+   * The text appearance (font and size).
+   * By default, it inherits from the parent element.
+   */
+  appearance?: TextAppearance,
+  /**
+   * Whether or not a click in this link should generate analytics data.
+   * 
+   * This only takes effect if there's a CitricController in React's context. The value of `analytics` is passed to the function
+   * `onClickLink` of the controller.
+   * 
+   * @default false
+   */
+  analytics?: boolean,
+}
+
+export type LinkProps = HTMLExtension<'a', BaseLinkProps>
+
+export const Link = ({ appearance, color, style, className, children, onClick, analytics, ...props }: LinkProps) => {
+  const citric = useCitricController()
+  const linkProps = {
+    component: 'link',
+    style: applyColor(style, color),
+    className: applyTextAppearance(className, appearance),
+    onClick: (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(e)
+      citric?.onClickLink?.(e, analytics ?? false)
+    },
+    ...props,
+  } as const
+  return citric?.renderLink
+    ? citric.renderLink(asCitricProps({ ...linkProps, children }))
+    : <CitricComponent tag="a" {...linkProps}>{children}</CitricComponent>
+}

package/src/components/LoadingPanel.tsx

@@ -0,0 +1,8 @@
+import { Center } from './layout'
+import { ProgressCircular } from './ProgressCircular'
+
+export const LoadingPanel = () => (
+  <Center flex={1} p="80px" data-test-hint="loading">
+    <ProgressCircular />
+  </Center>
+)

package/src/components/MenuOverlay/Menu.tsx

@@ -0,0 +1,157 @@
+import { listToClass } from '@stack-spot/portal-theme'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { createElement, useEffect, useMemo } from 'react'
+import { ValueController } from '../../utils/ValueController'
+import { CitricComponent } from '../CitricComponent'
+import { IconButton } from '../IconBox'
+import { useOverlayController } from '../Overlay/context'
+import { MenuProvider, useMenuController, useMenuState } from './context'
+import { keyboardNavigation } from './keyboard'
+import { ListAction, ListCollapsible, ListItem, ListSection, MenuProps, MenuState } from './types'
+
+// Arbitrary time (ms) to wait before running a function that needs the view to be updated with the next state value.
+const RENDER_DELAY = 20
+
+function Submenu({ children, label, className, icon, iconRight }: ListCollapsible) {
+  const controller = useMenuController()
+  return (
+    <button
+      className={listToClass([className, 'submenu'])}
+      onClick={(e) => {
+        e.stopPropagation()
+        const menu = e.target instanceof HTMLElement ? e.target.closest('[data-citric="menu"]') : undefined
+        controller?.setValue({ items: children, label, parent: controller?.getValue() })
+        const isOpenedWithMouse = e.detail > 0
+        if (!isOpenedWithMouse) {
+          setTimeout(() => {
+            const firstFocusable = menu?.querySelector('a, button')
+            if (firstFocusable instanceof HTMLElement) firstFocusable.focus()
+          }, RENDER_DELAY) 
+        }
+      }}
+    >
+      {icon}
+      <span>{label}</span>
+      {iconRight}
+    </button>
+  )
+}
+
+function MenuSection({ children, label, className }: ListSection) {
+  return (
+    <section className={className}>
+      {label && <h6>{label}</h6>}
+      <nav>
+        <MenuItems items={children} />
+      </nav>
+      {!label && <hr />}
+    </section>
+  )
+}
+
+function MenuAction({ label, active, href, icon, iconRight, className, onClick, ...props }: ListAction) {
+  const overlayController = useOverlayController()
+  const children = <>
+    {icon}
+    {typeof label === 'string' ? <span>{label}</span> : label.element}
+    {iconRight}
+  </>
+  return createElement(
+    href ? 'a' : 'button',
+    {
+      href,
+      'aria-label': typeof label === 'string' ? label : label.id,
+      className: listToClass([className, active && 'active']),
+      onClick: (e) => {
+        overlayController?.close()
+        onClick?.(e)
+      },
+      ...props,
+    },
+    children,
+  )
+}
+
+function hasSections(items: ListItem[]) {
+  return items.some(i => 'children' in i && i.children.length && i.type === 'section')
+}
+
+function hasSubmenus(items: ListItem[]) {
+  return items.some(i => 'children' in i && i.children.length && i.type === 'collapsible')
+}
+
+function MenuItems({ items }: { items: ListItem[] }) {
+  return useMemo(() => items.map((item, index) => {
+    if ('children' in item && item.type === 'section') return <MenuSection key={item.label || index} {...item} />
+    if ('children' in item && item.type === 'collapsible') return <Submenu key={item.label || index} {...item} />
+    return <MenuAction key={(typeof item.label === 'string' ? item.label : item.label?.id) || index} {...item} />
+  }), [items])
+}
+
+/**
+ * TODO: make the height changes animated.
+ */
+export function Menu(
+  { items, appearance, bgLevel, header, roundedItems, showBorders, showShadows, spaced, className, onKeyDown, ...props }: MenuProps,
+) {
+  const controller = useMemo(() => new ValueController<MenuState>({ items }), [])
+  const current = useMenuState(controller)
+  const { sectioned, collapsible } = useMemo(
+    () => ({ sectioned: hasSections(current.items), collapsible: hasSubmenus(current.items) }),
+    [current.items],
+  )
+  const tag = header || sectioned || collapsible ? 'div' : 'nav'
+  const t = useTranslate(dictionary)
+
+  useEffect(() => {
+    if (items !== controller.getValue().items) controller.setValue({ items })
+  }, [items])
+  
+  return (
+    <MenuProvider value={controller}>
+      <CitricComponent
+        tag={tag}
+        component="menu"
+        className={listToClass([
+          className, appearance, roundedItems && 'rounded-items', showBorders && 'bordered', showShadows === false && 'no-shadow',
+          spaced && 'spaced', bgLevel && `bg-${bgLevel}`,
+        ])}
+        onKeyDown={(e: any) => {
+          keyboardNavigation(e)
+          onKeyDown?.(e)
+        }}
+        {...props}
+      >
+        {header && <header>{header}</header>}
+        {current.parent && (
+          <div className="back-button">
+            <IconButton
+              icon="ArrowLeft"
+              aria-label={t.goBack}
+              onClick={(e) => {
+                e.stopPropagation()
+                const menu = e.target instanceof HTMLElement ? e.target.closest('[data-citric="menu"]') : undefined
+                if (current.parent) controller.setValue(current.parent)
+                setTimeout(() => {
+                  const lastItem = Array.from(menu?.querySelectorAll('a, button') ?? []).find(el => el.textContent === current.label)
+                  if (lastItem instanceof HTMLElement) lastItem.focus()
+                }, RENDER_DELAY)
+              }}
+            />
+            <span>{current.label || t.goBack}</span>
+          </div>
+        )}
+        {sectioned ? <MenuItems items={current.items} /> : <nav><MenuItems items={current.items} /></nav>}
+      </CitricComponent>
+    </MenuProvider>
+  )
+}
+
+const dictionary = {
+  en: {
+    goBack: 'Go back',
+  },
+  pt: {
+    goBack: 'Voltar',
+  },
+} satisfies Dictionary

package/src/components/MenuOverlay/context.ts

@@ -0,0 +1,20 @@
+import { createContext, useContext, useEffect, useState } from 'react'
+import { ValueController } from '../../utils/ValueController'
+import { MenuState } from './types'
+
+const context = createContext<ValueController<MenuState> | undefined>(undefined)
+
+export const MenuProvider = context.Provider
+
+export function useMenuController() {
+  return useContext(context)
+}
+
+export function useMenuState(controller?: ValueController<MenuState>) {
+  const controllerFromContext = useMenuController()
+  controller ??= controllerFromContext
+  if (!controller) throw new Error('useMenuState used outside the context of a Menu')
+  const [state, setState] = useState(controller.getValue())
+  useEffect(() => controller.onChange(setState))
+  return state
+}

package/src/components/MenuOverlay/index.tsx

@@ -0,0 +1,35 @@
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { useMemo } from 'react'
+import { IconButton } from '../IconBox'
+import { Overlay } from '../Overlay'
+import { Menu } from './Menu'
+import { MenuOverlayProps } from './types'
+
+export const MenuOverlay = ({
+  id, items, appearance, bgLevel, header, roundedItems, showBorders, showShadows, spaced, menuClass, menuStyle, children, ...props
+}: MenuOverlayProps) => {
+  const t = useTranslate(dictionary)
+  const randomId = useMemo(() => `${Math.random()}`, [])
+  const menuProps = {
+    items, appearance, bgLevel, roundedItems, showBorders, showShadows, spaced, header, className: menuClass, style: menuStyle,
+  }
+  return (
+    <Overlay
+      content={<Menu {...menuProps} />}
+      attributes={{ id: id || randomId, style: { margin: '8px' } }}
+      triggerOn="click"
+      {...props}
+    >
+      {children ?? <IconButton icon="EllipsisVertical" aria-label={t.open} />}
+    </Overlay>
+  )
+}
+
+const dictionary = {
+  en: {
+    open: 'Open menu',
+  },
+  pt: {
+    open: 'Abrir menu',
+  },
+} satisfies Dictionary

package/src/components/MenuOverlay/keyboard.ts

@@ -0,0 +1,60 @@
+// TODO: scroll the element into view when it's focused. Very important for accessibility in scrollable menus.
+
+function getCurrent(element: Element | undefined | null) {
+  return element instanceof HTMLElement
+    ? element.querySelector('button:focus, a:focus') as HTMLElement | null
+    : null
+}
+
+function getMenuItems(element: Element | undefined | null) {
+  return element instanceof HTMLElement ? element.querySelectorAll('button, a') : undefined
+}
+
+function focusFirst(element: Element | undefined | null) {
+  const first = getMenuItems(element)?.[0]
+  if (first instanceof HTMLElement) first.focus()
+}
+
+function focusLast(element: Element | undefined | null) {
+  const all = getMenuItems(element)
+  const last = all?.[all.length]
+  if (last instanceof HTMLElement) last.focus()
+}
+
+function indexOf(elements: NodeListOf<Element>, element: Element | undefined | null) {
+  for (let i = 0; i < elements.length; i++) {
+    if (elements[i] === element) return i
+  }
+  return -1
+}
+
+function focusPrevious(element: Element | undefined | null, current: HTMLElement) {
+  const all = getMenuItems(element)
+  const index = all ? indexOf(all, current) : -1
+  if (!all || index === -1) return
+  const prev = index === 0 ? all[all.length - 1] : all[index - 1]
+  if (prev instanceof HTMLElement) prev.focus()
+}
+
+function focusNext(element: Element | undefined | null, current: HTMLElement) {
+  const all = getMenuItems(element)
+  const index = all ? indexOf(all, current) : -1
+  if (!all || index === -1) return
+  const next = index >= all.length - 1 ? all[0] : all[index + 1]
+  if (next instanceof HTMLElement) next.focus()
+}
+
+export function keyboardNavigation(event: React.KeyboardEvent) {
+  if (!['ArrowUp', 'ArrowDown'].includes(event.key)) return
+  event.stopPropagation()
+  event.preventDefault()
+  const menu = event.target instanceof HTMLElement ? event.target.closest('[data-citric="menu"]') : undefined
+  const current = getCurrent(menu)
+  if (event.key === 'ArrowUp') {
+    if (current) focusPrevious(menu, current)
+    else focusLast(menu)
+  } else {
+    if (current) focusNext(menu, current)
+    else focusFirst(menu)
+  }
+}

package/src/components/MenuOverlay/types.ts

@@ -0,0 +1,178 @@
+import { HTMLExtension } from '../../types'
+import { BaseOverlayProps } from '../Overlay/types'
+
+interface CustomLabel {
+  /**
+   * A unique identifier for this label. This is also used to read this label to screen readers.
+   */
+  id: string,
+  /**
+   * A custom label that can be made up of any React component.
+   */
+  element: React.ReactNode,
+}
+
+interface Action {
+  /**
+   * The label of the action.
+   */
+  label: string | CustomLabel,
+  /**
+   * Function to run on a click.
+   */
+  onClick?: (event?: React.MouseEvent) => void,
+  /**
+   * URL to open on a click.
+   */
+  href?: string,
+  /**
+   * Target of the URL to open.
+   */
+  target?: React.AnchorHTMLAttributes<HTMLAnchorElement>['target'],
+  /**
+   * Language of the linked document.
+   */
+  lang?: React.AnchorHTMLAttributes<HTMLAnchorElement>['lang'],
+  /**
+   * Language of the destination URL.
+   */
+  hrefLang?: React.AnchorHTMLAttributes<HTMLAnchorElement>['hrefLang'],
+  /**
+   * The title of the action. 
+   */
+  title?: string,
+  /**
+   * Whether or not this link/button is disabled.
+   * 
+   * @default false
+   */
+  disabled?: boolean,
+}
+
+interface ItemWithIcon {
+  /**
+   * An Icon to appear at the left of the item.
+   */
+  icon?: React.ReactElement,
+  /**
+   * An Icon to appear at the right of the item.
+   */
+  iconRight?: React.ReactElement,
+}
+
+export interface ListAction extends ItemWithIcon, Action {
+  /**
+   * Whether or not this option is currently active.
+   */
+  active?: boolean,
+  /**
+   * A class to be added to this item.
+   */
+  className?: string,
+}
+
+interface ListGroup {
+  /**
+   * If this group is rendered as a section with its items right below it or a collapsible, which requires a click to open a submenu.
+   */
+  type?: 'section' | 'collapsible',
+  /**
+   * The items of this group.
+   */
+  children: ListItem[],
+  /**
+  * A class to be added to this item.
+  */
+  className?: string,
+}
+
+export interface ListSection extends ListGroup {
+  type: 'section',
+  /**
+   * The section's title.
+   */
+  label?: string,
+}
+
+export interface ListCollapsible extends ListGroup, ItemWithIcon {
+  type?: 'collapsible',
+  /**
+   * The title of the collapsible menu.
+   */
+  label: string,
+}
+
+export type ListItem = ListSection | ListCollapsible | ListAction
+
+export interface MenuState {
+  items: ListItem[],
+  parent?: MenuState,
+  label?: string,
+}
+
+export interface BaseMenuProps {
+  /**
+   * The options in the selection list.
+   */
+  items: ListItem[],
+  /**
+   * A header for the menu.
+   */
+  header?: React.ReactNode,
+  /**
+   * Whether or not to render spaces between the items and the sides of the menu.
+   * 
+   * @default false
+   */
+  spaced?: boolean,
+  /**
+   * Wheter or not to render borders.
+   * 
+   * @default false
+   */
+  showBorders?: boolean,
+  /**
+   * Whether or not to use rounded corners for each menu item.
+   * 
+   * @default false
+   */
+  roundedItems?: boolean,
+  /**
+   * Use 'square' for sharp corners and 'circle' for rounded corners.
+   * 
+   * @default 'circle'
+   */
+  appearance?: 'square' | 'circle',
+  /**
+   * The level of the background color. Use this to lighten or darken the background.
+   * 
+   * @default 300
+   */
+  bgLevel?: 300 | 400 | 500 | 600,
+  /**
+   * Whether or not to render shadows behind the menu.
+   * 
+   * @default true
+   */
+  showShadows?: boolean,
+  /**
+   * A class for the menu element.
+   */
+  menuClass?: string,
+  /**
+   * Styles for the menu element.
+   */
+  menuStyle?: React.CSSProperties,
+}
+
+export type MenuProps = HTMLExtension<'div', BaseMenuProps, 'children'>
+
+export interface BaseMenuOverlayProps extends
+  BaseMenuProps, Omit<BaseOverlayProps<'div'>, 'tag' | 'onRenderChild' | 'content' | 'triggerOn' | 'reference'> {
+  /**
+   * A unique id for this menu. If not provided, a random number will be used.
+   */
+  id?: string,
+}
+
+export type MenuOverlayProps = HTMLExtension<'div', BaseMenuOverlayProps>

package/src/components/Overlay/context.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react'
+import { OverlayController } from './types'
+
+const context = createContext<OverlayController | undefined>(undefined)
+
+export const OverlayProvider = context.Provider
+
+export function useOverlayController() {
+  return useContext(context)
+}

package/src/components/Overlay/index.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useRef } from 'react'
+import { showOverlay } from '../../overlay'
+import { focusFirstChild } from '../../utils/acessibility'
+import { OverlayProvider } from './context'
+import { OverlayController, OverlayProps } from './types'
+
+/**
+ * These todos are in order of priority.
+ * 
+ * TODO: update position when the size changes. Currently, the top position seems out of place whenever the height changes. The same is
+ * probably true for the left position if the width changes.
+ * TODO: hoverDelayMS
+ * TODO: reposition the overlay when it's under a scrollable element other then the body and this element is scrolled.
+ * TODO: close the overlay when it's under a scrollable element other then the body and the element that triggered the tooltip becomes
+ * hidden by the scroll.
+ * TODO: use React Portal to implement overlays. The current implementation will lose every React context in the tree.
+ */
+export function Overlay<T extends keyof React.JSX.IntrinsicElements>({
+  tag,
+  children,
+  content,
+  position = 'top',
+  triggerOn = 'hover',
+  attributes,
+  onRenderChild,
+  autoFocusBehavior = 'keyboard',
+  ...props
+}: OverlayProps<T>,
+) {
+  const controller = useRef<OverlayController>({ close: () => Promise.resolve() })
+  const wrapper = useRef<HTMLDivElement | null>(null)
+  // props that don't require removing and reattaching the event listeners
+  const dynamic = useRef({ tag, content, position, attributes })
+
+  useEffect(() => {
+    dynamic.current = { tag, content, position, attributes }
+  }, [tag, content, position, attributes])
+
+  useEffect(() => {
+    let visible = false
+    let hideOnClickOutside: ((event: Event) => void) | undefined
+    let hideOnEsc: ((event: Event) => void) | undefined
+    let hideOverlay: (() => Promise<void>) | undefined
+    let removeRefocusTargetListener: (() => void) | undefined
+
+    function getTarget() {
+      const target = wrapper.current?.firstChild
+      return target instanceof HTMLElement ? target : undefined
+    }
+
+    if (onRenderChild) {
+      const target = getTarget()
+      if (target) onRenderChild(target)
+    }
+
+    async function show(event: Event) {
+      if (visible) return
+      visible = true
+      const target = getTarget()
+      if (!target) return
+      const { overlay, hide: hideFn } = showOverlay({
+        tag: dynamic.current.tag,
+        content: ['string', 'number', 'boolean'].includes(typeof dynamic.current.content)
+          ? dynamic.current.content
+          : <OverlayProvider value={controller.current}>{dynamic.current.content}</OverlayProvider>,
+        target,
+        position: dynamic.current.position,
+        attributes: dynamic.current.attributes,
+      })
+      hideOverlay = hideFn
+
+      function onHide(condition: (event: Event) => boolean) {
+        return (event: Event) => {
+          if (condition(event)) controller.current.close()
+        }
+      }
+
+      if (event.type === 'click') {
+        event.stopPropagation()
+        hideOnClickOutside = onHide(e => e instanceof MouseEvent && e.button === 0 && !overlay.contains(e.target as HTMLElement))
+        hideOnEsc = onHide(e => e instanceof KeyboardEvent && e.key === 'Escape')
+        document.addEventListener('click', hideOnClickOutside)
+        document.addEventListener('keydown', hideOnEsc)
+      }
+
+      //focus target when the last overlay element loses focus
+      function refocusTarget(e: KeyboardEvent) {
+        if (e.key === 'Tab' && e.target instanceof HTMLElement) {
+          const allItems = Array.from(e.target.closest('[data-citric="menu"]')?.querySelectorAll('a, button') ?? [])
+          if (e.target === allItems[allItems.length - 1]) {
+            getTarget()?.focus()
+            e.preventDefault()
+          }
+        }
+      }
+      overlay.addEventListener('keydown', refocusTarget)
+      removeRefocusTargetListener = () => overlay.removeEventListener('keydown', refocusTarget)
+
+      // auto-focus
+      const openedWithMouse = event instanceof MouseEvent && event.detail > 0
+      if (autoFocusBehavior === 'always' || (autoFocusBehavior === 'keyboard' && !openedWithMouse)) {
+        setTimeout(() => focusFirstChild(overlay), 20)
+      }
+    }
+
+    controller.current.close = async () => {
+      visible = false
+      if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
+      if (hideOnEsc) document.removeEventListener('keydown', hideOnEsc)
+      removeRefocusTargetListener?.()
+      await hideOverlay?.()
+    }
+
+    if (triggerOn === 'hover') {
+      getTarget()?.addEventListener('mouseenter', show)
+      getTarget()?.addEventListener('mouseleave', controller.current.close)
+      getTarget()?.addEventListener('focus', show)
+      getTarget()?.addEventListener('blur', controller.current.close)
+      return () => {
+        getTarget()?.removeEventListener('mouseenter', show)
+        getTarget()?.removeEventListener('mouseleave', controller.current.close)
+        getTarget()?.removeEventListener('focus', show)
+        getTarget()?.removeEventListener('blur', controller.current.close)
+      }
+    }
+
+    if (triggerOn === 'click') {
+      getTarget()?.addEventListener('click', show)
+      return () => {
+        getTarget()?.removeEventListener('click', show)
+        if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
+      }
+    }
+  }, [wrapper.current, triggerOn])
+
+  return <div ref={wrapper} {...props}>{children}</div>
+}