@sanity/ui 3.1.13 → 4.0.0-beta.0

package/src/components/menu/Menu.tsx

@@ -0,0 +1,174 @@
+import {menu, type PaddingStyleProps, type ResponsiveProp} from '@sanity/ui-css'
+import type {Space} from '@sanity/ui-tokens'
+import {useCallback, useEffect, useImperativeHandle, useMemo, useRef} from 'react'
+
+import type {ComponentType, Props} from '../../core/types'
+import {useClickOutsideEvent} from '../../hooks/useClickOutsideEvent'
+import {useGlobalKeyDown} from '../../hooks/useGlobalKeyDown'
+import {Box} from '../../primitives/box/Box'
+import {useLayer} from '../../primitives/layer/useLayer'
+import {Stack} from '../../primitives/stack/Stack'
+import {MenuContext, type MenuContextValue} from './MenuContext'
+import {useMenuController} from './useMenuController'
+
+/** @public */
+export const DEFAULT_MENU_ELEMENT = 'div'
+
+/** @public */
+export type MenuOwnProps = PaddingStyleProps & {
+  'gap'?: ResponsiveProp<Space>
+  'onClickOutside'?: (event: MouseEvent) => void
+  'onEscape'?: () => void
+  'onItemClick'?: (event: React.MouseEvent<HTMLButtonElement>) => void
+  'onItemSelect'?: (index: number) => void
+  'originElement'?: HTMLElement | null
+  'registerElement'?: (el: HTMLElement) => () => void
+  'shouldFocus'?: 'first' | 'last' | null
+  'aria-labelledby'?: string
+}
+
+/** @public */
+export type MenuElementType = 'div' | 'span' | ComponentType
+
+/** @public */
+export type MenuProps<E extends MenuElementType = MenuElementType> = Props<MenuOwnProps, E>
+
+/**
+ * The `Menu` component is a building block for application menus.
+ *
+ * @public
+ */
+export function Menu<E extends MenuElementType = typeof DEFAULT_MENU_ELEMENT>(
+  props: MenuProps<E>,
+): React.JSX.Element {
+  const {
+    as = DEFAULT_MENU_ELEMENT,
+    children,
+    className,
+    gap = 1,
+    onClickOutside,
+    onEscape,
+    onItemClick,
+    onItemSelect,
+    onKeyDown,
+    originElement,
+    padding = 1,
+    ref: forwardedRef,
+    registerElement,
+    shouldFocus: _shouldFocus,
+    ...rest
+  } = props as MenuProps<typeof DEFAULT_MENU_ELEMENT>
+
+  const shouldFocus = _shouldFocus ?? 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 value={value}>
+      <Box
+        data-ui="Menu"
+        {...rest}
+        ref={handleRefChange}
+        as={as}
+        className={menu({className})}
+        outline="none"
+        overflow="auto"
+        padding={padding}
+        role="menu"
+        tabIndex={-1}
+        onKeyDown={handleKeyDown}
+      >
+        <Stack gap={gap}>{children}</Stack>
+      </Box>
+    </MenuContext>
+  )
+}

package/src/components/menu/MenuButton.tsx

@@ -0,0 +1,231 @@
+import {
+  cloneElement,
+  type FocusEvent,
+  type ForwardedRef,
+  type KeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
+  type ReactElement,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import type {Props} from '../../core/types'
+import type {ButtonProps} from '../../primitives/button/Button'
+import {Popover, type PopoverProps} from '../../primitives/popover/Popover'
+import type {MenuProps} from './Menu'
+
+/** @public */
+export type MenuButtonProps = {
+  /**
+   * @beta Do not use in production.
+   */
+  __unstable_disableRestoreFocusOnClose?: boolean
+  button: ReactElement<ButtonProps>
+  id: string
+  menu?: ReactElement
+  onClose?: () => void
+  onOpen?: () => void
+  popover?: Omit<PopoverProps, 'content' | 'open'>
+
+  ref?: ForwardedRef<HTMLButtonElement | null>
+}
+
+/**
+ * The `MenuButton` component follows the WAI-ARIA specification for menu buttons.
+ *
+ * @public
+ */
+export function MenuButton(props: MenuButtonProps): React.JSX.Element {
+  const {
+    __unstable_disableRestoreFocusOnClose: disableRestoreFocusOnClose = false,
+    button: buttonProp,
+    id,
+    menu: menuProp,
+    onClose,
+    onOpen,
+    popover,
+    ref: forwardedRef,
+  } = 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((event: ReactMouseEvent<HTMLElement>) => {
+    event.preventDefault()
+    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: ReactMouseEvent<HTMLElement>) => {
+      if (open) event.preventDefault()
+    },
+    [open],
+  )
+
+  const handleButtonKeyDown = useCallback((event: 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<HTMLDivElement>) => {
+      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(
+    (e: ReactMouseEvent<HTMLButtonElement>) => {
+      if (e.defaultPrevented) return
+
+      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: Props<MenuProps, 'div'> = {
+    'aria-labelledby': id,
+    'onBlurCapture': handleBlur,
+    'onClickOutside': handleMenuClickOutside,
+    'onEscape': handleMenuEscape,
+    'onItemClick': handleItemClick,
+    'originElement': buttonElement,
+    registerElement,
+    shouldFocus,
+  }
+
+  const menu = menuProp && cloneElement(menuProp, menuProps)
+
+  const button = useMemo(() => {
+    if (!buttonProp) return null
+
+    const buttonProps: ButtonProps = {
+      'data-ui': 'MenuButton',
+      id,
+      'onClick': handleButtonClick,
+      'onKeyDown': handleButtonKeyDown,
+      'onMouseDown': handleMouseDown,
+      'aria-haspopup': true,
+      'aria-expanded': open,
+      'ref': setButtonElement,
+      'selected': buttonProp.props.selected ?? open,
+      'tooltip': open ? undefined : buttonProp.props.tooltip,
+    }
+
+    return cloneElement(buttonProp, buttonProps)
+  }, [buttonProp, handleButtonClick, handleButtonKeyDown, handleMouseDown, id, open])
+
+  // Forward button ref to parent
+  useImperativeHandle<HTMLButtonElement | null, HTMLButtonElement | null>(
+    forwardedRef,
+    () => buttonElement,
+    [buttonElement],
+  )
+
+  return (
+    <Popover
+      data-ui="MenuButton__popover"
+      overflow="auto"
+      placement="bottom-start"
+      {...popover}
+      content={menu}
+      open={open}
+    >
+      {button || <></>}
+    </Popover>
+  )
+}

package/src/components/menu/MenuContext.ts

@@ -0,0 +1,19 @@
+import {type Context, type MouseEvent as ReactMouseEvent} from 'react'
+
+import {createGlobalScopedContext} from '../../core/lib/createGlobalScopedContext'
+
+/** @internal */
+export interface MenuContextValue {
+  version: 2
+  activeElement: HTMLElement | null
+  mount: (element: HTMLElement | null, selected?: boolean) => () => void
+  onClickOutside?: (event: MouseEvent) => void
+  onEscape?: () => void
+  onItemClick?: (event: ReactMouseEvent<HTMLButtonElement>) => void
+  onItemMouseEnter?: (event: ReactMouseEvent<HTMLElement>) => void
+  onItemMouseLeave?: (event: ReactMouseEvent<HTMLElement>) => void
+  registerElement?: (el: HTMLElement) => () => void
+}
+
+export const MenuContext: Context<MenuContextValue | null> =
+  createGlobalScopedContext<MenuContextValue | null>('@sanity/ui/v4/menu', null)

package/src/components/menu/MenuDivider.tsx

@@ -0,0 +1,32 @@
+import {menu_divider} from '@sanity/ui-css'
+
+import type {ComponentType, Props} from '../../core/types'
+
+/** @public */
+export const DEFAULT_MENU_DIVIDER_ELEMENT = 'hr'
+
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type MenuDividerOwnProps = {}
+
+/** @public */
+export type MenuDividerElementType = 'div' | 'hr' | 'span' | ComponentType
+
+/** @public */
+export type MenuDividerProps<E extends MenuDividerElementType = MenuDividerElementType> = Props<
+  MenuDividerOwnProps,
+  E
+>
+
+/** @public */
+export function MenuDivider<E extends MenuDividerElementType = typeof DEFAULT_MENU_DIVIDER_ELEMENT>(
+  props: MenuDividerProps<E>,
+): React.JSX.Element {
+  const {
+    as: Element = DEFAULT_MENU_DIVIDER_ELEMENT,
+    className,
+    ...rest
+  } = props as MenuDividerProps<typeof DEFAULT_MENU_DIVIDER_ELEMENT>
+
+  return <Element {...rest} className={menu_divider({className})} />
+}

package/src/components/menu/MenuGroup.tsx

@@ -0,0 +1,240 @@
+import {ChevronRightIcon} from '@sanity/icons'
+import type {RadiusStyleProps, ResponsiveProp} from '@sanity/ui-css'
+import type {ElementTone, FontTextSize, Space} from '@sanity/ui-tokens'
+import {
+  type ElementType,
+  isValidElement,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useState,
+} from 'react'
+import {isValidElementType} from 'react-is'
+
+import type {ComponentType, Props} from '../../core/types'
+import {Box} from '../../primitives/box/Box'
+import {Flex} from '../../primitives/flex/Flex'
+import {Popover, type PopoverProps} from '../../primitives/popover/Popover'
+import {Selectable} from '../../primitives/selectable/Selectable'
+import {Text} from '../../primitives/text/Text'
+import {DEFAULT_MENU_ELEMENT, Menu, type MenuProps} from './Menu'
+import {useMenu} from './useMenu'
+
+/** @public */
+export const DEFAULT_MENU_GROUP_ELEMENT = 'button'
+
+/** @public */
+export type MenuGroupOwnProps = RadiusStyleProps & {
+  disabled?: boolean
+  fontSize?: ResponsiveProp<FontTextSize>
+  gap?: ResponsiveProp<Space>
+  icon?: ElementType | ReactNode
+  menu?: Omit<
+    MenuProps<typeof DEFAULT_MENU_ELEMENT>,
+    | 'onClickOutside'
+    | 'onEscape'
+    | 'onItemClick'
+    | 'onKeyDown'
+    | 'onMouseEnter'
+    | 'registerElement'
+    | 'shouldFocus'
+    | 'onBlurCapture'
+  >
+  padding?: ResponsiveProp<Space>
+  popover?: Omit<PopoverProps, 'content' | 'open'>
+  text?: ReactNode
+  tone?: ElementTone
+}
+
+/** @public */
+export type MenuGroupElementType = 'button' | ComponentType
+
+/** @public */
+export type MenuGroupProps<E extends MenuGroupElementType = MenuGroupElementType> = Props<
+  MenuGroupOwnProps,
+  E
+>
+
+/** @public */
+export function MenuGroup<E extends MenuGroupElementType = typeof DEFAULT_MENU_GROUP_ELEMENT>(
+  props: MenuGroupProps<E>,
+): React.JSX.Element {
+  const {
+    as = DEFAULT_MENU_GROUP_ELEMENT,
+    children,
+    fontSize = 1,
+    gap = 3,
+    icon: IconComponent,
+    menu: menuProps,
+    onClick,
+    padding = 3,
+    popover,
+    radius = 2,
+    text,
+    tone = 'default',
+    ...rest
+  } = props as MenuGroupProps<typeof DEFAULT_MENU_GROUP_ELEMENT>
+
+  const {
+    activeElement,
+    mount,
+    onClickOutside,
+    onEscape,
+    onItemClick,
+    onItemMouseEnter,
+    registerElement,
+  } = useMenu()
+
+  const [rootElement, setRootElement] = useState<HTMLButtonElement | HTMLDivElement | null>(null)
+  const [open, setOpen] = useState(false)
+  const [shouldFocus, setShouldFocus] = useState<'first' | 'last' | null>(null)
+  const active = Boolean(activeElement) && activeElement === rootElement
+  const [withinMenu, setWithinMenu] = useState(false)
+
+  const handleMouseEnter = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      setWithinMenu(false)
+      onItemMouseEnter?.(event)
+      setOpen(true)
+    },
+    [onItemMouseEnter],
+  )
+
+  const handleMenuKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'ArrowLeft') {
+        event.stopPropagation()
+
+        setOpen(false)
+
+        requestAnimationFrame(() => {
+          rootElement?.focus()
+        })
+      }
+    },
+    [rootElement],
+  )
+
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => {
+      onClick?.(event)
+
+      setShouldFocus('first')
+      setOpen(true)
+    },
+    [onClick],
+  )
+
+  const handleChildItemClick = useCallback(
+    (e: MouseEvent<HTMLButtonElement>) => {
+      setOpen(false)
+      onItemClick?.(e)
+    },
+    [onItemClick],
+  )
+
+  const handleMenuMouseEnter = useCallback(() => setWithinMenu(true), [])
+
+  // Register the menu item element
+  useEffect(() => mount(rootElement), [mount, rootElement])
+
+  // Close child menu when a sibling item becomes active
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    if (!active) setOpen(false)
+  }, [active])
+
+  // Update state when child menu is no longer open
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    if (!open) setWithinMenu(false)
+  }, [open])
+
+  // Reset the shouldFocus state after it has been used
+  useEffect(() => {
+    if (!shouldFocus) return
+    // The useMenuController effect that handles `shouldFocus` schedules a request animation frame where it's processed.
+    // By doing the same here, we ensure that the reset is processed after the focus change.
+    const rafId = requestAnimationFrame(() => setShouldFocus(null))
+
+    return () => cancelAnimationFrame(rafId)
+  }, [shouldFocus])
+
+  const childMenu = (
+    <Menu
+      {...menuProps}
+      registerElement={registerElement}
+      shouldFocus={shouldFocus}
+      onClickOutside={onClickOutside}
+      onEscape={onEscape}
+      onItemClick={handleChildItemClick}
+      onKeyDown={handleMenuKeyDown}
+      onMouseEnter={handleMenuMouseEnter}
+    >
+      {children}
+    </Menu>
+  )
+
+  const handleKeyDown = useCallback((event: KeyboardEvent<HTMLButtonElement>) => {
+    const target = event.currentTarget
+
+    if (document.activeElement !== target) {
+      return
+    }
+
+    if (event.key === 'ArrowRight') {
+      setShouldFocus('first')
+      setOpen(true)
+      setWithinMenu(true)
+
+      return
+    }
+  }, [])
+
+  return (
+    <Popover
+      __unstable_shift={-4}
+      data-ui="MenuGroup__popover"
+      {...popover}
+      content={childMenu}
+      open={open}
+    >
+      <Selectable
+        data-ui="MenuGroup"
+        {...rest}
+        ref={setRootElement}
+        aria-pressed={as === 'button' ? withinMenu : undefined}
+        as={as}
+        radius={radius}
+        selected={withinMenu}
+        tabIndex={-1}
+        tone={tone}
+        type={as === 'button' ? 'button' : undefined}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        onMouseEnter={handleMouseEnter}
+      >
+        <Flex gap={gap} padding={padding}>
+          {IconComponent && (
+            <Text size={fontSize}>
+              {isValidElement(IconComponent) && IconComponent}
+              {isValidElementType(IconComponent) && <IconComponent />}
+            </Text>
+          )}
+
+          <Box flex={1}>
+            <Text size={fontSize} textOverflow="ellipsis" weight="medium">
+              {text}
+            </Text>
+          </Box>
+
+          <Text size={fontSize}>
+            <ChevronRightIcon />
+          </Text>
+        </Flex>
+      </Selectable>
+    </Popover>
+  )
+}