Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

14.9 KB
Raw Blame
import { useMergeRefs } from '@floating-ui/react'
import React, { FunctionComponent, ReactNode, cloneElement, useCallback, useMemo } from 'react'

import { KeyboardShortcut, KeyboardShortcutProps } from 'lib/lemon-ui/KeyboardShortcut/KeyboardShortcut'

import { LemonButton, LemonButtonProps } from '../LemonButton'
import { LemonDivider } from '../LemonDivider'
import { LemonDropdown, LemonDropdownProps } from '../LemonDropdown'
import { LemonTag } from '../LemonTag'
import { TooltipProps } from '../Tooltip'
import { useKeyboardNavigation } from './useKeyboardNavigation'

type KeyboardShortcut = Array<keyof KeyboardShortcutProps>

export interface LemonMenuItemBase extends Pick<
    LemonButtonProps,
    | 'icon'
    | 'sideIcon'
    | 'sideAction'
    | 'disabled'
    | 'disabledReason'
    | 'tooltip'
    | 'tooltipDocLink'
    | 'tooltipPlacement'
    | 'active'
    | 'status'
    | 'data-attr'
    | 'size'
> {
    label: string | JSX.Element
    key?: React.Key
    /** @deprecated You're probably doing something wrong if you're setting per-item classes. */
    className?: string
    /** True if the item is a custom element. */
    custom?: boolean
}
export interface LemonMenuItemNode extends LemonMenuItemBase {
    items: (LemonMenuItem | false | null)[]
    placement?: LemonDropdownProps['placement']
    closeOnClickInside?: boolean
    closeParentPopoverOnClickInside?: boolean
    keyboardShortcut?: never
}

export interface LemonMenuItemLeafCallback extends LemonMenuItemBase {
    onClick?: (e: React.MouseEvent) => void
    items?: never
    placement?: never
    closeOnClickInside?: never
    closeParentPopoverOnClickInside?: never
    keyboardShortcut?: KeyboardShortcut
}
export interface LemonMenuItemLeafLink extends LemonMenuItemBase {
    onClick?: (e: React.MouseEvent) => void
    to: string
    disableClientSideRouting?: boolean
    targetBlank?: boolean
    items?: never
    placement?: never
    closeOnClickInside?: never
    closeParentPopoverOnClickInside?: never
    keyboardShortcut?: KeyboardShortcut
}

export type LemonMenuItemLeaf = LemonMenuItemLeafCallback | LemonMenuItemLeafLink

export interface LemonMenuItemCustom {
    /** A label that's a component means it will be rendered directly, and not wrapped in a button. */
    label: () => JSX.Element
    key?: React.Key
    active?: never
    items?: never
    keyboardShortcut?: never

    /** True if the item is a custom element. */
    custom?: boolean
    placement?: never
    closeOnClickInside?: never
    closeParentPopoverOnClickInside?: never
}
export type LemonMenuItem = (LemonMenuItemLeaf | LemonMenuItemCustom | LemonMenuItemNode) & {
    tag?: 'alpha' | 'beta' | 'new'
}

export interface LemonMenuSection {
    title?: string | React.ReactNode
    key?: React.Key
    items: (LemonMenuItem | false | null)[]
    footer?: string | React.ReactNode
}

export type LemonMenuItems = (LemonMenuItem | LemonMenuSection | false | null)[]

export interface LemonMenuProps
    extends
        Pick<
            LemonDropdownProps,
            | 'placement'
            | 'fallbackPlacements'
            | 'matchWidth'
            | 'maxContentWidth'
            | 'visible'
            | 'onVisibilityChange'
            | 'closeOnClickInside'
            | 'closeParentPopoverOnClickInside'
            | 'className'
            | 'onClickOutside'
            | 'middleware'
            | 'startVisible'
            | 'trigger'
        >,
        LemonMenuOverlayProps {
    /** Must support `ref`, `onFocus`, and `onKeyDown` for keyboard navigation. */
    children: React.ReactElement
    /** Index of the active (e.g. selected) item, if there is a specific one. */
    activeItemIndex?: number
    /**
     * If focus-based keyboard navigation is disabled, you must implement your own.
     * This is for cases of purpose-specific keyboard navigation, e.g. for a command palette.
     * `activeItemIndex` will still be used, but only to visually highlight the active item.
     * @default true
     */
    focusBasedKeyboardNavigation?: boolean
}

export const LemonMenu = React.forwardRef<HTMLElement, LemonMenuProps>(function LemonMenu(
    {
        items,
        activeItemIndex,
        tooltipPlacement,
        onVisibilityChange,
        focusBasedKeyboardNavigation = true,
        children,
        ...dropdownProps
    },
    ref
): JSX.Element {
    const { referenceRef, itemsRef, onTriggerFocus, onTriggerKeyDown, onItemsKeyDown } =
        useKeyboardNavigation<HTMLButtonElement>(
            items.flatMap((item) => (item && isLemonMenuSection(item) ? item.items : item)).length,
            activeItemIndex,
            { enabled: focusBasedKeyboardNavigation }
        )

    const _onVisibilityChange = useCallback(
        (visible: boolean) => {
            onVisibilityChange?.(visible)
            if (visible && activeItemIndex && activeItemIndex > -1) {
                // Scroll the active item into view once the menu is open (i.e. in the next tick)
                setTimeout(() => itemsRef?.current?.[activeItemIndex]?.current?.scrollIntoView({ block: 'center' }), 0)
            }
        },
        // no need to update this when itemsRef changes
        // eslint-disable-next-line react-hooks/exhaustive-deps
        [onVisibilityChange, activeItemIndex]
    )

    // LemonMenu renders no DOM itself — only the trigger child does. Forward an externally-provided
    // ref (e.g. from <Shortcut />) onto that child so it lands on a real DOM node, otherwise consumers
    // attaching a ref to LemonMenu silently get nothing.
    const triggerRef = useMergeRefs([ref, (children as { ref?: React.Ref<HTMLElement> }).ref])

    return (
        <LemonDropdown
            overlay={
                <LemonMenuOverlay
                    buttonSize={dropdownProps.buttonSize || 'small'}
                    items={items}
                    tooltipPlacement={tooltipPlacement}
                    itemsRef={itemsRef}
                    onKeyDown={onItemsKeyDown}
                />
            }
            closeOnClickInside
            referenceRef={referenceRef}
            onVisibilityChange={_onVisibilityChange}
            {...dropdownProps}
        >
            {cloneElement(children, {
                ref: triggerRef,
                onFocus: (e: React.FocusEvent<HTMLElement>) => {
                    children.props.onFocus?.(e)
                    onTriggerFocus(e)
                },
                onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => {
                    children.props.onKeyDown?.(e)
                    onTriggerKeyDown(e)
                },
            })}
        </LemonDropdown>
    )
})
LemonMenu.displayName = 'LemonMenu'

export interface LemonMenuOverlayProps {
    items: LemonMenuItems
    tooltipPlacement?: TooltipProps['placement']
    itemsRef?: React.RefObject<React.RefObject<HTMLButtonElement>[]>
    onKeyDown?: React.KeyboardEventHandler<HTMLElement>
    /** @default 'small' */
    buttonSize?: 'xsmall' | 'small' | 'medium'
}

export function LemonMenuOverlay({
    items,
    tooltipPlacement = 'right',
    itemsRef,
    buttonSize = 'small',
    onKeyDown,
}: LemonMenuOverlayProps): JSX.Element {
    const sectionsOrItems = useMemo(() => normalizeItems(items), [items])

    return sectionsOrItems.length > 0 && isLemonMenuSection(sectionsOrItems[0]) ? (
        <LemonMenuSectionList
            sections={sectionsOrItems as LemonMenuSection[]}
            buttonSize={buttonSize}
            tooltipPlacement={tooltipPlacement}
            itemsRef={itemsRef}
            onKeyDown={onKeyDown}
        />
    ) : (
        <LemonMenuItemList
            items={sectionsOrItems as LemonMenuItem[]}
            buttonSize={buttonSize}
            tooltipPlacement={tooltipPlacement}
            itemsRef={itemsRef}
            onKeyDown={onKeyDown}
            itemIndexOffset={0}
        />
    )
}

interface LemonMenuSectionListProps {
    sections: LemonMenuSection[]
    buttonSize: 'xsmall' | 'small' | 'medium'
    tooltipPlacement: TooltipProps['placement'] | undefined
    itemsRef: React.RefObject<React.RefObject<HTMLButtonElement>[]> | undefined
    onKeyDown?: React.KeyboardEventHandler<HTMLElement>
}

export function LemonMenuSectionList({
    sections,
    buttonSize,
    tooltipPlacement,
    itemsRef,
    onKeyDown,
}: LemonMenuSectionListProps): JSX.Element {
    let rollingItemIndex = 0

    return (
        <ul onKeyDown={onKeyDown}>
            {sections.map((section, i) => {
                const sectionElement = (
                    <li key={section.key || i}>
                        <section className="deprecated-space-y-px">
                            {section.title ? (
                                typeof section.title === 'string' ? (
                                    <h5 className="mx-2 my-1">{section.title}</h5>
                                ) : (
                                    section.title
                                )
                            ) : null}
                            <LemonMenuItemList
                                items={section.items.filter(Boolean) as LemonMenuItem[]}
                                buttonSize={buttonSize}
                                tooltipPlacement={tooltipPlacement}
                                itemsRef={itemsRef}
                                itemIndexOffset={rollingItemIndex}
                            />
                            {section.footer ? <div>{section.footer}</div> : null}
                        </section>
                        {i < sections.length - 1 ? (
                            <LemonDivider className={buttonSize === 'small' ? 'my-1' : 'my-2'} />
                        ) : null}
                    </li>
                )
                rollingItemIndex += section.items.length
                return sectionElement
            })}
        </ul>
    )
}

interface LemonMenuItemListProps {
    items: LemonMenuItem[]
    buttonSize?: 'xsmall' | 'small' | 'medium'
    tooltipPlacement?: TooltipProps['placement'] | undefined
    itemsRef?: React.RefObject<React.RefObject<HTMLButtonElement>[]> | undefined
    itemIndexOffset?: number
    onKeyDown?: React.KeyboardEventHandler<HTMLElement>
}

export function LemonMenuItemList({
    items,
    buttonSize = 'small',
    itemIndexOffset = 0,
    tooltipPlacement = 'right',
    itemsRef,
    onKeyDown,
}: LemonMenuItemListProps): JSX.Element {
    return (
        <ul className="deprecated-space-y-px" onKeyDown={onKeyDown}>
            {items.map((item, itemIndex) => (
                <li key={item.key || itemIndex}>
                    <LemonMenuItemButton
                        item={item}
                        size={buttonSize}
                        tooltipPlacement={tooltipPlacement}
                        ref={itemsRef?.current?.[itemIndexOffset + itemIndex]}
                        tag={item.tag}
                        active={item.active}
                    />
                </li>
            ))}
        </ul>
    )
}

interface LemonMenuItemButtonProps {
    item: LemonMenuItem
    size: 'xsmall' | 'small' | 'medium'
    tooltipPlacement: TooltipProps['placement'] | undefined
    tag?: 'alpha' | 'beta' | 'new'
    active?: boolean
}

const LemonMenuItemButton: FunctionComponent<LemonMenuItemButtonProps & React.RefAttributes<HTMLButtonElement>> =
    React.forwardRef(
        (
            {
                item: {
                    label,
                    items,
                    placement,
                    keyboardShortcut,
                    tag,
                    custom,
                    closeOnClickInside,
                    closeParentPopoverOnClickInside,
                    ...buttonProps
                },
                size,
                tooltipPlacement,
                active,
            },
            ref
        ): JSX.Element => {
            const Label = typeof label === 'function' ? label : null
            const button = Label ? (
                <Label key="x" />
            ) : (
                // @ts-expect-error - We don't have a type-level guarantee that `sideAction` won't be present
                // alongside `sideIcon` in one menu item, but that's fine. It'd be horribly complex to implement here.
                <LemonButton
                    ref={ref}
                    tooltipPlacement={tooltipPlacement}
                    fullWidth
                    role="menuitem"
                    size={size}
                    {...buttonProps}
                    active={active}
                >
                    {label as ReactNode}
                    {keyboardShortcut && (
                        <div className="-mr-0.5 inline-flex grow justify-end">
                            {/* Show the keyboard shortcut on the right */}
                            <KeyboardShortcut {...Object.fromEntries(keyboardShortcut.map((key) => [key, true]))} />
                        </div>
                    )}
                    {tag && (
                        <LemonTag
                            type={tag === 'alpha' ? 'completion' : tag === 'beta' ? 'warning' : 'success'}
                            size="small"
                            className="ml-2"
                        >
                            {tag.toUpperCase()}
                        </LemonTag>
                    )}
                </LemonButton>
            )

            return items ? (
                <LemonMenu
                    items={items}
                    tooltipPlacement={tooltipPlacement}
                    placement={placement || 'right-start'}
                    closeOnClickInside={closeOnClickInside ?? !custom}
                    closeParentPopoverOnClickInside={closeParentPopoverOnClickInside ?? !custom}
                    buttonSize={size}
                >
                    {button}
                </LemonMenu>
            ) : (
                button
            )
        }
    )
LemonMenuItemButton.displayName = 'LemonMenuItemButton'

function normalizeItems(sectionsAndItems: LemonMenuItems): LemonMenuItem[] | LemonMenuSection[] {
    const sections: LemonMenuSection[] = []
    let implicitSection: LemonMenuSection = { items: [] }
    for (const sectionOrItem of sectionsAndItems) {
        if (!sectionOrItem) {
            continue // Ignore falsy items
        }
        if (isLemonMenuSection(sectionOrItem)) {
            if (implicitSection.items.length > 0) {
                sections.push(implicitSection)
                implicitSection = { items: [] }
            }
            sections.push(sectionOrItem)
        } else {
            implicitSection.items.push(sectionOrItem)
        }
    }
    if (implicitSection.items.length > 0) {
        sections.push(implicitSection)
    }

    if (sections.length === 1 && !sections[0].title && !sections[0].footer) {
        return sections[0].items.filter(Boolean) as LemonMenuItem[]
    }
    return sections
}

export function isLemonMenuSection(candidate: LemonMenuSection | LemonMenuItem): candidate is LemonMenuSection {
    return candidate && 'items' in candidate && !('label' in candidate)
}