@bettercms-ai/kit 0.1.0

package/src/core/components/menu/menu.test.tsx

@@ -0,0 +1,125 @@
+/** @jest-environment jsdom */
+
+/* eslint-disable no-console */
+
+import React, {useCallback, useMemo} from 'react'
+
+import {render} from '../../../../test'
+import {MenuContext, MenuContextValue} from './menuContext'
+import {useMenu} from './useMenu'
+
+describe('components/menu', () => {
+  describe('useMenu', () => {
+    it('should get context value', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        const rootMenu = useMenu()
+
+        log(rootMenu)
+
+        return <>debug</>
+      }
+
+      function Root() {
+        const handleItemMouseEnter = useCallback(
+          (event: React.MouseEvent<HTMLElement>) => console.log(event),
+          [],
+        )
+
+        const handleItemMouseLeave = useCallback(
+          (event: React.MouseEvent<HTMLElement>) => console.log(event),
+          [],
+        )
+
+        const value = useMemo(
+          () =>
+            ({
+              version: 2,
+              activeElement: null,
+              mount: (element: HTMLElement | null) => () => console.log(element),
+              onItemClick: () => undefined,
+              onItemMouseEnter: handleItemMouseEnter,
+              onItemMouseLeave: handleItemMouseLeave,
+            }) satisfies MenuContextValue,
+          [handleItemMouseEnter, handleItemMouseLeave],
+        )
+
+        return (
+          <MenuContext.Provider value={value}>
+            <Debug />
+          </MenuContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      const contextValue = log.mock.calls[0][0]
+
+      expect(contextValue.version).toBe(2)
+      expect(typeof contextValue.mount).toBe('function')
+      expect(typeof contextValue.onItemClick).toBe('function')
+      expect(typeof contextValue.onItemMouseEnter).toBe('function')
+      expect(typeof contextValue.onItemMouseEnter).toBe('function')
+    })
+
+    it('should fail when no context value is provided', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        try {
+          useMenu()
+        } catch (err) {
+          log(err)
+        }
+
+        return null
+      }
+
+      function Root() {
+        const value: any = undefined
+
+        return (
+          <MenuContext.Provider value={value}>
+            <Debug />
+          </MenuContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      expect(log.mock.calls[0][0].message).toEqual('useMenu(): missing context value')
+    })
+
+    it('should fail when context value is not compatible', async () => {
+      const log = jest.fn()
+
+      function Debug() {
+        try {
+          useMenu()
+        } catch (err) {
+          log(err)
+        }
+
+        return null
+      }
+
+      function Root() {
+        // NOTE: we’re testing this because the context value may be a function in the future
+        const value: any = () => {
+          return {version: 1}
+        }
+
+        return (
+          <MenuContext.Provider value={value}>
+            <Debug />
+          </MenuContext.Provider>
+        )
+      }
+
+      render(<Root />)
+
+      expect(log.mock.calls[0][0].message).toEqual('useMenu(): the context value is not compatible')
+    })
+  })
+})

package/src/core/components/menu/menu.tsx

@@ -0,0 +1,178 @@
+import {forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef} from 'react'
+import {styled} from 'styled-components'
+
+import {useClickOutsideEvent, useGlobalKeyDown} from '../../hooks'
+import {Box, Stack} from '../../primitives'
+import {ResponsivePaddingProps} from '../../primitives/types'
+import {useLayer} from '../../utils'
+import {MenuContext, MenuContextValue} from './menuContext'
+import {useMenuController} from './useMenuController'
+
+/**
+ * @public
+ */
+export interface MenuProps extends ResponsivePaddingProps {
+  /**
+   * @deprecated Use `shouldFocus="first"` instead.
+   */
+  'focusFirst'?: boolean
+  /**
+   * @deprecated Use `shouldFocus="last"` instead.
+   */
+  'focusLast'?: boolean
+  'onClickOutside'?: (event: MouseEvent) => void
+  'onEscape'?: () => void
+  'onItemClick'?: () => void
+  'onItemSelect'?: (index: number) => void
+  'originElement'?: HTMLElement | null
+  'registerElement'?: (el: HTMLElement) => () => void
+  'shouldFocus'?: 'first' | 'last' | null
+  'gap'?: number | number[]
+  /**
+   * @deprecated Use `gap` instead. `space` will be removed in v4.
+   */
+  'space'?: number | number[]
+  'aria-labelledby'?: string
+  'onBlurCapture'?: (event: FocusEvent) => void
+}
+
+const StyledMenu = styled(Box)`
+  outline: none;
+  overflow: auto;
+`
+
+/**
+ * The `Menu` component is a building block for application menus.
+ *
+ * @public
+ */
+export const Menu = forwardRef(function Menu(
+  props: MenuProps & Omit<React.HTMLProps<HTMLDivElement>, 'as' | 'height' | 'role' | 'tabIndex'>,
+  forwardedRef: React.ForwardedRef<HTMLDivElement>,
+) {
+  const {
+    children,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    focusFirst,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    focusLast,
+    onClickOutside,
+    onEscape,
+    onItemClick,
+    onItemSelect,
+    onKeyDown,
+    originElement,
+    padding = 1,
+    registerElement,
+    shouldFocus: _shouldFocus,
+    gap,
+    space: deprecated_space = 1,
+    ...restProps
+  } = props
+  const spacing = gap === undefined ? deprecated_space : gap
+  const shouldFocus =
+    _shouldFocus ?? ((props.focusFirst && 'first') || (props.focusLast && 'last') || null)
+
+  const ref = useRef<HTMLDivElement | null>(null)
+
+  useImperativeHandle<HTMLDivElement | null, HTMLDivElement | null>(forwardedRef, () => ref.current)
+
+  const {isTopLayer} = useLayer()
+
+  const {
+    activeElement,
+    activeIndex,
+    handleItemMouseEnter,
+    handleItemMouseLeave,
+    handleKeyDown,
+    mount,
+  } = useMenuController({onKeyDown, originElement, shouldFocus, rootElementRef: ref})
+
+  const unregisterElementRef = useRef<(() => void) | null>(null)
+  const handleRefChange = useCallback(
+    (el: HTMLDivElement | null) => {
+      // Run cleanup of previously registered elements
+      if (unregisterElementRef.current) {
+        // The `registerElement` callback were originally used in a `useEffect`, so it returns a cleanup function that is a bit gnarly to handle in a ref callback.
+        // Since we can't change the `registerElement` implementation itself without making breaking change,
+        // that is explained in the code comments for createGlobalScopedContext.tsx,
+        // we need to handle with a ref that holds on to the cleanup function last returned when the ref callback is called.
+        unregisterElementRef.current()
+        unregisterElementRef.current = null
+      }
+
+      ref.current = el
+
+      // Register root element (for nested menus)
+      if (ref.current && registerElement) {
+        unregisterElementRef.current = registerElement(ref.current)
+      }
+    },
+    [registerElement],
+  )
+
+  // Trigger `onItemSelect` when active index changes
+  useEffect(() => {
+    if (onItemSelect) onItemSelect(activeIndex)
+  }, [activeIndex, onItemSelect])
+
+  // Close menu when clicking outside
+  useClickOutsideEvent(isTopLayer && onClickOutside, () => [ref.current])
+
+  // Close menu when pressing Escape
+  useGlobalKeyDown(
+    useCallback(
+      (event) => {
+        if (!isTopLayer) return
+
+        if (event.key === 'Escape') {
+          event.stopPropagation()
+          if (onEscape) onEscape()
+        }
+      },
+      [isTopLayer, onEscape],
+    ),
+  )
+
+  const value = useMemo(
+    () =>
+      ({
+        version: 2,
+        activeElement,
+        mount,
+        onClickOutside,
+        onEscape,
+        onItemClick,
+        onItemMouseEnter: handleItemMouseEnter,
+        onItemMouseLeave: handleItemMouseLeave,
+        registerElement,
+      }) satisfies MenuContextValue,
+    [
+      activeElement,
+      mount,
+      handleItemMouseEnter,
+      handleItemMouseLeave,
+      onClickOutside,
+      onEscape,
+      onItemClick,
+      registerElement,
+    ],
+  )
+
+  return (
+    <MenuContext.Provider value={value}>
+      <StyledMenu
+        data-ui="Menu"
+        {...restProps}
+        onKeyDown={handleKeyDown}
+        padding={padding}
+        ref={handleRefChange}
+        role="menu"
+        tabIndex={-1}
+      >
+        <Stack gap={spacing}>{children}</Stack>
+      </StyledMenu>
+    </MenuContext.Provider>
+  )
+})
+Menu.displayName = 'ForwardRef(Menu)'

package/src/core/components/menu/menuButton.tsx

@@ -0,0 +1,268 @@
+import {ThemeColorSchemeKey} from '@bettercms-ai/kit/theme'
+import {
+  cloneElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import {Popover, PopoverProps} from '../../primitives'
+import {Placement, Radius} from '../../types'
+import {MenuProps} from './menu'
+
+/**
+ * @public
+ */
+export interface MenuButtonProps {
+  /**
+   * @beta Do not use in production.
+   */
+  __unstable_disableRestoreFocusOnClose?: boolean
+  /**
+   * @deprecated Use `popover={{boundaryElement: element}}` instead.
+   */
+  boundaryElement?: HTMLElement
+  button: React.JSX.Element
+  id: string
+  menu?: React.JSX.Element
+  onClose?: () => void
+  onOpen?: () => void
+  /**
+   * @deprecated Use `popover={{placement: 'top'}}` instead.
+   */
+  placement?: Placement
+  popover?: Omit<PopoverProps, 'content' | 'open'>
+  /**
+   * @deprecated Use `popover={{scheme: 'dark'}}` instead.
+   */
+  popoverScheme?: ThemeColorSchemeKey
+  /**
+   * @deprecated Use `popover={{radius: 2}}` instead.
+   */
+  popoverRadius?: Radius | Radius[]
+  /**
+   * @beta Do not use in production.
+   * @deprecated Use `popover={{portal: true}}` instead.
+   */
+  portal?: boolean
+  /**
+   * @deprecated Use `popover={{preventOverflow: true}}` instead.
+   */
+  preventOverflow?: boolean
+}
+
+/**
+ * The `MenuButton` component follows the WAI-ARIA specification for menu buttons.
+ *
+ * @public
+ */
+export const MenuButton = forwardRef(function MenuButton(
+  props: MenuButtonProps,
+  forwardedRef: React.ForwardedRef<HTMLButtonElement | null>,
+) {
+  const {
+    __unstable_disableRestoreFocusOnClose: disableRestoreFocusOnClose = false,
+    boundaryElement: deprecated_boundaryElement,
+    button: buttonProp,
+    id,
+    menu: menuProp,
+    onClose,
+    onOpen,
+    placement: deprecated_placement,
+    popoverScheme: deprecated_popoverScheme,
+    portal: deprecated_portal = true,
+    popover,
+    popoverRadius: deprecated_popoverRadius,
+    preventOverflow: deprecated_preventOverflow,
+  } = props
+  const [open, setOpen] = useState(false)
+  const [shouldFocus, setShouldFocus] = useState<'first' | 'last' | null>(null)
+  const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+  const [menuElements, setChildMenuElements] = useState<HTMLElement[]>([])
+  const openRef = useRef<boolean>(open)
+
+  // Notify consumers when the menu opens
+  useEffect(() => {
+    if (onOpen && open && !openRef.current) {
+      onOpen()
+    }
+  }, [onOpen, open])
+
+  // Notify consumers when the menu closes
+  useEffect(() => {
+    if (onClose && !open && openRef.current) {
+      onClose()
+    }
+  }, [onClose, open])
+
+  useEffect(() => {
+    openRef.current = open
+  }, [open])
+
+  const handleButtonClick = useCallback(() => {
+    setOpen((v) => !v)
+    setShouldFocus(null)
+  }, [])
+
+  // Prevent mouse event propagation when the menu is open.
+  // This is to ensure that `handleBlur` isn't triggered when clicking the menu button whilst open,
+  // which can lead to `setOpen` being triggered multiple times (once by `handleBlur`, and again by `handleButtonClick`).
+  const handleMouseDown = useCallback(
+    (event: PointerEvent) => {
+      if (open) event.preventDefault()
+    },
+    [open],
+  )
+
+  const handleButtonKeyDown = useCallback((event: React.KeyboardEvent<HTMLButtonElement>) => {
+    // On `ArrowDown`, `Enter` and `Space`
+    // - Opens menu and moves focus to first menuitem
+    if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      setOpen(true)
+      setShouldFocus('first')
+
+      return
+    }
+
+    // On `ArrowUp`
+    // - 	Opens menu and moves focus to last menuitem
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      setOpen(true)
+      setShouldFocus('last')
+
+      return
+    }
+  }, [])
+
+  const handleMenuClickOutside = useCallback(
+    (event: MouseEvent) => {
+      const target = event.target
+
+      if (!(target instanceof Node)) {
+        return
+      }
+
+      if (buttonElement && (target === buttonElement || buttonElement.contains(target))) {
+        return
+      }
+
+      for (const el of menuElements) {
+        if (target === el || el.contains(target)) {
+          return
+        }
+      }
+
+      setOpen(false)
+    },
+    [buttonElement, menuElements],
+  )
+
+  const handleMenuEscape = useCallback(() => {
+    setOpen(false)
+    if (disableRestoreFocusOnClose) return
+    if (buttonElement) buttonElement.focus()
+  }, [buttonElement, disableRestoreFocusOnClose])
+
+  const handleBlur = useCallback(
+    (event: FocusEvent) => {
+      const target = event.relatedTarget
+
+      if (!(target instanceof Node)) {
+        return
+      }
+
+      for (const el of menuElements) {
+        if (el === target || el.contains(target)) {
+          return
+        }
+      }
+
+      setOpen(false)
+    },
+    [menuElements],
+  )
+
+  const handleItemClick = useCallback(() => {
+    setOpen(false)
+    if (disableRestoreFocusOnClose) return
+    if (buttonElement) buttonElement.focus()
+  }, [buttonElement, disableRestoreFocusOnClose])
+
+  const registerElement = useCallback((el: HTMLElement) => {
+    setChildMenuElements((els) => els.concat([el]))
+
+    return () => setChildMenuElements((els) => els.filter((_el) => _el !== el))
+  }, [])
+
+  const menuProps: MenuProps = {
+    'aria-labelledby': id,
+    'onBlurCapture': handleBlur,
+    'onClickOutside': handleMenuClickOutside,
+    'onEscape': handleMenuEscape,
+    'onItemClick': handleItemClick,
+    'originElement': buttonElement,
+    registerElement,
+    shouldFocus,
+  }
+
+  const menu = menuProp && cloneElement(menuProp, menuProps)
+
+  const button = useMemo(
+    () =>
+      buttonProp &&
+      cloneElement(buttonProp, {
+        'data-ui': 'MenuButton',
+        id,
+        'onClick': handleButtonClick,
+        'onKeyDown': handleButtonKeyDown,
+        'onMouseDown': handleMouseDown,
+        'aria-haspopup': true,
+        'aria-expanded': open,
+        'ref': setButtonElement,
+        'selected': buttonProp.props.selected ?? open,
+      }),
+    [buttonProp, handleButtonClick, handleButtonKeyDown, handleMouseDown, id, open],
+  )
+
+  // Forward button ref to parent
+  useImperativeHandle<HTMLButtonElement | null, HTMLButtonElement | null>(
+    forwardedRef,
+    () => buttonElement,
+    [buttonElement],
+  )
+
+  const popoverProps: MenuButtonProps['popover'] = useMemo(
+    () => ({
+      boundaryElement: deprecated_boundaryElement,
+      overflow: 'auto',
+      placement: deprecated_placement,
+      portal: deprecated_portal,
+      preventOverflow: deprecated_preventOverflow,
+      radius: deprecated_popoverRadius,
+      scheme: deprecated_popoverScheme,
+      ...(popover || {}),
+    }),
+    [
+      deprecated_boundaryElement,
+      deprecated_placement,
+      deprecated_popoverRadius,
+      deprecated_popoverScheme,
+      deprecated_portal,
+      deprecated_preventOverflow,
+      popover,
+    ],
+  )
+
+  return (
+    <Popover data-ui="MenuButton__popover" {...popoverProps} content={menu} open={open}>
+      {button || <></>}
+    </Popover>
+  )
+})
+MenuButton.displayName = 'ForwardRef(MenuButton)'

package/src/core/components/menu/menuContext.ts

@@ -0,0 +1,18 @@
+import {createGlobalScopedContext} from '../../lib/createGlobalScopedContext'
+
+export interface MenuContextValue {
+  version: 2
+  activeElement: HTMLElement | null
+  mount: (element: HTMLElement | null, selected?: boolean) => () => void
+  onClickOutside?: (event: MouseEvent) => void
+  onEscape?: () => void
+  onItemClick?: () => void
+  onItemMouseEnter: (event: React.MouseEvent<HTMLElement>) => void
+  onItemMouseLeave: (event: React.MouseEvent<HTMLElement>) => void
+  registerElement?: (el: HTMLElement) => () => void
+}
+
+export const MenuContext = createGlobalScopedContext<MenuContextValue | null>(
+  '@bettercms-ai/kit/context/menu',
+  null,
+)

package/src/core/components/menu/menuDivider.ts

@@ -0,0 +1,23 @@
+import {styled} from 'styled-components'
+
+import {ElementType, EmptyProps, Props} from '../../types'
+
+const StyledMenuDivider = styled.hr`
+  height: 1px;
+  border: 0;
+  background: var(--card-hairline-soft-color);
+  margin: 0;
+`
+StyledMenuDivider.displayName = 'MenuDivider'
+
+/**
+ * @public
+ */
+export type MenuDividerProps<E extends ElementType = 'hr'> = Props<EmptyProps, E>
+
+/**
+ * @public
+ */
+export const MenuDivider = StyledMenuDivider as unknown as <E extends ElementType = 'hr'>(
+  props: MenuDividerProps<E>,
+) => React.JSX.Element

package/src/core/components/menu/menuGroup.spacing.test.tsx

@@ -0,0 +1,63 @@
+/** @jest-environment jsdom */
+
+import {render} from '../../../../test'
+import {Flex} from '../../primitives'
+import {MenuContext, MenuContextValue} from './menuContext'
+import {MenuGroup} from './menuGroup'
+import {MenuItem} from './menuItem'
+
+jest.mock('../../primitives', () => {
+  const actual = jest.requireActual('../../primitives')
+
+  return {
+    ...actual,
+    Flex: jest.fn((props: Record<string, unknown>) => (actual.Flex as any).render(props, null)),
+    Popover: jest.fn(({children}: {children?: React.ReactNode}) => children),
+  }
+})
+
+const menuContextValue: MenuContextValue = {
+  version: 2,
+  activeElement: null,
+  mount: () => () => undefined,
+  onItemMouseEnter: () => undefined,
+  onItemMouseLeave: () => undefined,
+}
+
+function renderMenuGroup(props: Partial<React.ComponentProps<typeof MenuGroup>> = {}) {
+  return render(
+    <MenuContext.Provider value={menuContextValue}>
+      <MenuGroup id="menu-group" text="Menu group" {...props}>
+        <MenuItem id="submenu-item" text="Submenu item" />
+      </MenuGroup>
+    </MenuContext.Provider>,
+  )
+}
+
+describe('components/menuGroup spacing', () => {
+  const mockedFlex = jest.mocked(Flex)
+
+  beforeEach(() => {
+    mockedFlex.mockClear()
+  })
+
+  it('should support `space` and `gap` with the same behavior', () => {
+    renderMenuGroup({space: 2})
+    expect(mockedFlex.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({gap: 2}),
+    )
+
+    mockedFlex.mockClear()
+    renderMenuGroup({gap: 2})
+    expect(mockedFlex.mock.calls.map(([props]) => props)).toContainEqual(
+      expect.objectContaining({gap: 2}),
+    )
+  })
+
+  it('should prefer `gap` over `space` when both are provided', () => {
+    renderMenuGroup({gap: 3, space: 1})
+    const propsList = mockedFlex.mock.calls.map(([props]) => props)
+    expect(propsList).toContainEqual(expect.objectContaining({gap: 3}))
+    expect(propsList).not.toContainEqual(expect.objectContaining({gap: 1}))
+  })
+})