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.

25.3 KB
Raw Blame
import clsx from 'clsx'
import { ReactNode, type CSSProperties, useEffect, useRef } from 'react'

import {
    IconCode,
    IconCursor,
    IconDatabase,
    IconFunnels,
    IconLifecycle,
    IconList,
    IconPencil,
    IconPeople,
    IconRetention,
    IconRewindPlay,
    IconSparkles,
    IconStickiness,
    IconTrends,
    IconUserPaths,
} from '@posthog/icons'

import { Scene } from 'scenes/sceneTypes'

import { ProductKey } from '~/queries/schema/schema-general'

import {
    INSERT_MENU_GAP,
    INSERT_MENU_MAX_HEIGHT,
    INSERT_MENU_MIN_HEIGHT,
    INSERT_MENU_VIEWPORT_PADDING,
    INSERT_MENU_WIDTH,
    InsertCommand,
    InsertMenuPosition,
    InsertMenuSelectionDirection,
} from './editorTypes'
import { makeEmptyParagraph } from './markdown'
import { getMarkdownNotebookComponentDefaultProps } from './registry'
import {
    NotebookBlockNode,
    NotebookComponentBlockNode,
    NotebookComponentDefinition,
    NotebookComponentProps,
    NotebookComponentRegistry,
} from './types'

/** DOM id of a command's option element, referenced by the editor's `aria-activedescendant`. */
export function getInsertMenuOptionDomId(menuId: string, commandKey: string): string {
    return `${menuId}-option-${commandKey}`
}

/** Exported so a caller whose registry supersedes the built-in SQL command can hide it by key
 * without hard-coding the string, which would silently stop matching if the key were renamed. */
export const QUERY_SQL_INSERT_COMMAND_KEY = 'query-sql'

/** The menu's top group. Exported so a registry component can place its insert command here
 * without hard-coding the label, which would split into a second group if this were renamed. */
export const COMMON_INSERT_COMMAND_CATEGORY = 'Common'

/** The menu's last group, sorted by label rather than by insertion order. Exported so a caller
 * merging product commands in can name it without hard-coding the label. */
export const PRODUCTS_INSERT_COMMAND_CATEGORY = 'Products'

export function omitInsertCommands(commands: InsertCommand[], hiddenKeys: string[] | undefined): InsertCommand[] {
    if (!hiddenKeys?.length) {
        return commands
    }
    return commands.filter((command) => !hiddenKeys.includes(command.key))
}

export function InsertMenu({
    id,
    query,
    commands,
    targetNodeId,
    position,
    selectedIndex,
    onClose,
}: {
    id?: string
    query: string
    commands: InsertCommand[]
    targetNodeId: string
    position: InsertMenuPosition | null
    selectedIndex: number
    onClose: () => void
}): JSX.Element {
    const selectedItemRef = useRef<HTMLButtonElement | null>(null)
    const filteredCommands = getFilteredInsertCommands(commands, query)
    const commandsByCategory = groupInsertCommandsByCategory(filteredCommands)
    const selectedCommandIndex = getClampedInsertMenuSelectedIndex(selectedIndex, filteredCommands.length)
    const selectedCommand = filteredCommands[selectedCommandIndex]
    const selectedCommandKey = selectedCommand?.key
    const menuStyle = position
        ? ({
              '--markdown-notebook-insert-menu-left': `${position.left}px`,
              '--markdown-notebook-insert-menu-max-height': `${position.maxHeight}px`,
              '--markdown-notebook-insert-menu-top': `${position.top}px`,
              '--markdown-notebook-insert-menu-width': `${position.width}px`,
          } as CSSProperties)
        : undefined

    useEffect(() => {
        selectedItemRef.current?.scrollIntoView({ block: 'nearest', inline: 'nearest' })
    }, [selectedCommandKey])

    return (
        <div
            className={clsx(
                'MarkdownNotebook__insert-menu',
                position && 'MarkdownNotebook__insert-menu--positioned',
                position && `MarkdownNotebook__insert-menu--${position.placement}`
            )}
            contentEditable={false}
            style={menuStyle}
            id={id}
            role="listbox"
            aria-label="Insert block"
        >
            {/* Focus stays in the editor while the menu is open, so screen readers may miss the
                aria-activedescendant change — announce the selection explicitly. */}
            <div className="sr-only" aria-live="polite">
                {selectedCommand
                    ? `${selectedCommand.label}, ${selectedCommandIndex + 1} of ${filteredCommands.length}`
                    : 'No components found'}
            </div>
            {Object.entries(commandsByCategory).map(([category, categoryCommands]) => (
                <div className="MarkdownNotebook__insert-category" key={category} role="group" aria-label={category}>
                    <h5 aria-hidden="true">{category}</h5>
                    <div className="MarkdownNotebook__insert-grid">
                        {categoryCommands.map((command) => (
                            <button
                                ref={command.key === selectedCommandKey ? selectedItemRef : null}
                                className={clsx(
                                    'MarkdownNotebook__insert-item',
                                    command.key === selectedCommandKey && 'MarkdownNotebook__insert-item--selected'
                                )}
                                key={command.key}
                                id={id ? getInsertMenuOptionDomId(id, command.key) : undefined}
                                role="option"
                                aria-selected={command.key === selectedCommandKey}
                                disabled={command.disabled}
                                type="button"
                                onClick={() => {
                                    if (command.disabled) {
                                        return
                                    }
                                    command.run(targetNodeId)
                                    if (command.closeOnRun !== false) {
                                        onClose()
                                    }
                                }}
                            >
                                {command.icon ? (
                                    <span className="MarkdownNotebook__insert-item-icon">{command.icon}</span>
                                ) : null}
                                <span>{renderHighlightedInsertCommandLabel(command.label, query)}</span>
                                {command.badge ? (
                                    <span className="MarkdownNotebook__insert-item-badge">{command.badge}</span>
                                ) : null}
                            </button>
                        ))}
                    </div>
                </div>
            ))}
            {!filteredCommands.length ? <div className="MarkdownNotebook__empty-menu">No components found</div> : null}
        </div>
    )
}

export function renderHighlightedInsertCommandLabel(label: string, query: string): ReactNode {
    const normalizedQuery = query.trim().toLowerCase()
    const matchIndex = normalizedQuery ? label.toLowerCase().indexOf(normalizedQuery) : -1
    if (matchIndex === -1) {
        return label
    }

    const matchEndIndex = matchIndex + normalizedQuery.length
    return (
        <>
            {label.slice(0, matchIndex)}
            <mark className="MarkdownNotebook__insert-item-highlight">{label.slice(matchIndex, matchEndIndex)}</mark>
            {label.slice(matchEndIndex)}
        </>
    )
}

export function getFilteredInsertCommands(commands: InsertCommand[], query: string): InsertCommand[] {
    const normalizedQuery = query.trim().toLowerCase()
    const filteredCommands = normalizedQuery
        ? commands.filter((command) => getInsertCommandSearchText(command).includes(normalizedQuery))
        : commands

    return Object.values(groupInsertCommandsByCategory(filteredCommands)).flat()
}

export function getInsertCommandSearchText(command: InsertCommand): string {
    return `${command.label} ${command.category} ${command.description ?? ''} ${(command.aliases ?? []).join(' ')}`
        .trim()
        .toLowerCase()
}

export function groupInsertCommandsByCategory(commands: InsertCommand[]): Record<string, InsertCommand[]> {
    return commands.reduce<Record<string, InsertCommand[]>>((accumulator, command) => {
        accumulator[command.category] = [...(accumulator[command.category] ?? []), command]
        return accumulator
    }, {})
}

export function getClampedInsertMenuSelectedIndex(selectedIndex: number, commandCount: number): number {
    if (commandCount <= 0) {
        return 0
    }
    return Math.max(0, Math.min(selectedIndex, commandCount - 1))
}

export function getNextInsertMenuSelectedIndex(
    selectedIndex: number,
    commandCount: number,
    direction: InsertMenuSelectionDirection
): number {
    if (commandCount <= 0) {
        return 0
    }

    const clampedIndex = getClampedInsertMenuSelectedIndex(selectedIndex, commandCount)
    return direction === 'next' ? (clampedIndex + 1) % commandCount : (clampedIndex - 1 + commandCount) % commandCount
}

export function buildInsertCommands(
    registry: NotebookComponentRegistry,
    replaceNodeWithInsertedComponent: (nodeId: string, nextNode: NotebookComponentBlockNode) => void,
    replaceNode: (nodeId: string, nextNode: NotebookBlockNode) => void,
    focusInsertedText: (nodeId: string) => void,
    focusInsertedTable: (nodeId: string) => void,
    focusInsertedCode: (nodeId: string) => void,
    openAIPrompt?: (nodeId: string) => void,
    isAskAIDisabled?: boolean,
    extraCommands: InsertCommand[] = [],
    openBtw?: (nodeId: string) => void
): InsertCommand[] {
    const commonCategory = COMMON_INSERT_COMMAND_CATEGORY

    const insertComponent = (targetNodeId: string, tagName: string, props: NotebookComponentProps): void => {
        const node: NotebookComponentBlockNode = {
            id: makeEmptyParagraph(`component-${tagName}`).id,
            type: 'component',
            tagName,
            props,
        }

        replaceNodeWithInsertedComponent(targetNodeId, node)
    }

    const insertRegisteredComponent = (targetNodeId: string, tagName: string, props?: NotebookComponentProps): void => {
        const definition = registry.components[tagName]
        if (!definition) {
            return
        }

        insertComponent(targetNodeId, tagName, props ?? getMarkdownNotebookComponentDefaultProps(definition))
    }

    const getRegisteredComponentInsertProps = (definition: NotebookComponentDefinition): NotebookComponentProps => {
        const insertDefaultProps = definition.insertCommand?.defaultProps
        if (typeof insertDefaultProps === 'function') {
            return insertDefaultProps()
        }
        return insertDefaultProps ?? getMarkdownNotebookComponentDefaultProps(definition)
    }

    const insertTable = (targetNodeId: string): void => {
        const nodeId = makeEmptyParagraph('table').id
        replaceNode(targetNodeId, {
            id: nodeId,
            type: 'table',
            headers: [
                { children: [{ type: 'text', text: 'Column 1' }] },
                { children: [{ type: 'text', text: 'Column 2' }] },
            ],
            rows: [[{ children: [] }, { children: [] }]],
        })
        focusInsertedTable(nodeId)
    }

    const insertCode = (targetNodeId: string): void => {
        replaceNode(targetNodeId, {
            id: targetNodeId,
            type: 'code',
            text: '',
        })
        focusInsertedCode(targetNodeId)
    }

    const aiCommands: InsertCommand[] = openAIPrompt
        ? [
              {
                  key: 'ai-ask',
                  label: 'Ask AI',
                  category: commonCategory,
                  description: 'Ask AI to write or edit this notebook',
                  aliases: ['ai', 'ask', 'posthog ai'],
                  icon: <IconSparkles />,
                  closeOnRun: false,
                  disabled: isAskAIDisabled,
                  run: openAIPrompt,
              },
          ]
        : []

    const queryCommands: InsertCommand[] = [
        {
            key: 'query-trend',
            label: 'Trend',
            category: 'Insight',
            icon: <IconTrends />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: {
                            kind: 'TrendsQuery',
                            series: [{ kind: 'EventsNode', name: '$pageview', event: '$pageview', math: 'total' }],
                        },
                    },
                }),
        },
        {
            key: 'query-funnel',
            label: 'Funnel',
            category: 'Insight',
            icon: <IconFunnels />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: {
                            kind: 'FunnelsQuery',
                            series: [
                                { kind: 'EventsNode', name: '$pageview', event: '$pageview' },
                                { kind: 'EventsNode', name: '$pageleave', event: '$pageleave' },
                            ],
                        },
                    },
                }),
        },
        {
            key: 'query-retention',
            label: 'Retention',
            category: 'Insight',
            icon: <IconRetention />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: {
                            kind: 'RetentionQuery',
                            retentionFilter: {
                                period: 'Day',
                                totalIntervals: 11,
                                targetEntity: { id: '$pageview', name: '$pageview', type: 'events' },
                                returningEntity: { id: '$pageview', name: '$pageview', type: 'events' },
                            },
                        },
                    },
                }),
        },
        {
            key: 'query-paths',
            label: 'Paths',
            category: 'Insight',
            aliases: ['user paths'],
            icon: <IconUserPaths />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: { kind: 'PathsQuery', pathsFilter: { includeEventTypes: ['$pageview'] } },
                    },
                }),
        },
        {
            key: 'query-stickiness',
            label: 'Stickiness',
            category: 'Insight',
            icon: <IconStickiness />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: {
                            kind: 'StickinessQuery',
                            series: [{ kind: 'EventsNode', name: '$pageview', event: '$pageview', math: 'total' }],
                            stickinessFilter: {},
                        },
                    },
                }),
        },
        {
            key: 'query-lifecycle',
            label: 'Lifecycle',
            category: 'Insight',
            icon: <IconLifecycle />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'InsightVizNode',
                        source: {
                            kind: 'LifecycleQuery',
                            series: [{ kind: 'EventsNode', name: '$pageview', event: '$pageview', math: 'total' }],
                        },
                    },
                }),
        },
    ]

    const sqlCommands: InsertCommand[] = [
        {
            key: QUERY_SQL_INSERT_COMMAND_KEY,
            label: 'SQL',
            category: commonCategory,
            icon: <IconDatabase />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'DataTableNode',
                        source: {
                            kind: 'HogQLQuery',
                            query: 'select event, count() from events where timestamp >= now() - interval 7 day group by event',
                        },
                    },
                }),
        },
    ]

    const dataCommands: InsertCommand[] = [
        {
            key: 'query-events',
            label: 'Events',
            category: 'Data',
            icon: <IconCursor />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'DataTableNode',
                        source: { kind: 'EventsQuery', select: ['*', 'event', 'person', 'timestamp'] },
                    },
                }),
        },
        {
            key: 'data-people',
            label: 'People',
            category: 'Data',
            icon: <IconPeople />,
            run: (targetNodeId) =>
                insertComponent(targetNodeId, 'Query', {
                    query: {
                        kind: 'DataTableNode',
                        source: {
                            kind: 'ActorsQuery',
                            select: ['person_display_name -- Person', 'id', 'created_at'],
                            // ActorsQuery hits ClickHouse, which requires a product query tag.
                            // Match the notebook query tagging convention (see NotebookSQLEditor).
                            tags: { productKey: ProductKey.NOTEBOOKS, scene: Scene.Notebook },
                        },
                    },
                }),
        },
    ]

    // Sorted and moved after every other category on the way out, so "Products" renders as the
    // last group (grouping preserves first-occurrence order); scene-supplied commands merge in.
    const productCommands: InsertCommand[] = [
        {
            key: 'data-session-recordings',
            label: 'Session recordings',
            category: PRODUCTS_INSERT_COMMAND_CATEGORY,
            aliases: ['replay', 'playlist'],
            icon: <IconRewindPlay />,
            run: (targetNodeId) => insertRegisteredComponent(targetNodeId, 'RecordingPlaylist'),
        },
    ]

    const mediaCommands: InsertCommand[] = [
        {
            key: 'media-image',
            label: 'Image',
            category: 'Media',
            icon: <IconList />,
            run: (targetNodeId) => insertRegisteredComponent(targetNodeId, 'Image'),
        },
        {
            key: 'media-table',
            label: 'Table',
            category: 'Media',
            icon: <IconList />,
            run: insertTable,
        },
        {
            key: 'media-iframe',
            label: 'Iframe',
            category: 'Media',
            icon: <IconList />,
            run: (targetNodeId) => insertRegisteredComponent(targetNodeId, 'Embed'),
        },
        {
            key: 'media-latex',
            label: 'LaTeX',
            category: 'Media',
            icon: <IconList />,
            run: (targetNodeId) => insertRegisteredComponent(targetNodeId, 'Latex'),
        },
    ]

    const componentCommands: InsertCommand[] = Object.values(registry.components).flatMap((definition) => {
        const insertCommand = definition.insertCommand
        if (!insertCommand) {
            return []
        }

        return [
            {
                key: `component-${definition.tagName}`,
                label: insertCommand.label ?? definition.label,
                category: insertCommand.category ?? definition.category,
                description: insertCommand.description ?? definition.description,
                aliases: insertCommand.aliases ?? definition.aliases,
                icon: insertCommand.icon ?? definition.icon,
                badge: insertCommand.badge,
                run: (targetNodeId) =>
                    insertRegisteredComponent(
                        targetNodeId,
                        definition.tagName,
                        getRegisteredComponentInsertProps(definition)
                    ),
            },
        ]
    })

    const textCommands: InsertCommand[] = [
        {
            key: 'text-paragraph',
            label: 'Text',
            category: commonCategory,
            aliases: ['paragraph', 'plain text'],
            icon: <IconPencil />,
            run: (targetNodeId) => {
                replaceNode(targetNodeId, {
                    id: targetNodeId,
                    type: 'paragraph',
                    children: [],
                })
                focusInsertedText(targetNodeId)
            },
        },
    ]

    const textStyleCommands: InsertCommand[] = [
        {
            key: 'text-quote',
            label: 'Blockquote',
            category: 'Text',
            aliases: ['quote'],
            icon: <IconPencil />,
            run: (targetNodeId) =>
                replaceNode(targetNodeId, {
                    id: targetNodeId,
                    type: 'blockquote',
                    children: [],
                }),
        },
        {
            key: 'text-code',
            label: 'Code',
            category: 'Text',
            aliases: ['code block', 'fenced code'],
            icon: <IconCode />,
            run: insertCode,
        },
        {
            key: 'text-heading-1',
            label: 'Heading 1',
            category: 'Text',
            aliases: ['h1'],
            icon: <IconPencil />,
            run: (targetNodeId) =>
                replaceNode(targetNodeId, {
                    id: targetNodeId,
                    type: 'heading',
                    level: 1,
                    children: [],
                }),
        },
        {
            key: 'text-heading-2',
            label: 'Heading 2',
            category: 'Text',
            aliases: ['h2'],
            icon: <IconPencil />,
            run: (targetNodeId) =>
                replaceNode(targetNodeId, {
                    id: targetNodeId,
                    type: 'heading',
                    level: 2,
                    children: [],
                }),
        },
        {
            key: 'text-heading-3',
            label: 'Heading 3',
            category: 'Text',
            aliases: ['h3'],
            icon: <IconPencil />,
            run: (targetNodeId) =>
                replaceNode(targetNodeId, {
                    id: targetNodeId,
                    type: 'heading',
                    level: 3,
                    children: [],
                }),
        },
    ]

    return sortProductInsertCommandsLast([
        ...aiCommands,
        ...(openBtw
            ? [
                  {
                      key: 'ai-btw',
                      label: 'BTW',
                      category: commonCategory,
                      description: 'Ask a side question about this notebook',
                      aliases: ['btw', 'by the way', 'question'],
                      icon: <IconSparkles />,
                      disabled: isAskAIDisabled,
                      run: openBtw,
                  },
              ]
            : []),
        ...textCommands,
        ...sqlCommands,
        ...queryCommands,
        ...dataCommands,
        ...mediaCommands,
        ...componentCommands,
        ...textStyleCommands,
        ...productCommands,
        ...extraCommands,
    ])
}

/** Every other category is hand-ordered, but products arrive in widget-catalog key order, which
 * reads as arbitrary. Sorting here rather than at render time keeps the order the arrow keys walk
 * in step with the order the menu paints. */
function sortProductInsertCommandsLast(commands: InsertCommand[]): InsertCommand[] {
    const products = commands.filter((command) => command.category === PRODUCTS_INSERT_COMMAND_CATEGORY)
    const rest = commands.filter((command) => command.category !== PRODUCTS_INSERT_COMMAND_CATEGORY)
    return [...rest, ...products.sort((a, b) => a.label.localeCompare(b.label))]
}

export function getInsertMenuPosition(anchorElement: HTMLElement): InsertMenuPosition {
    const anchorRect = anchorElement.getBoundingClientRect()
    const viewportWidth = window.innerWidth || document.documentElement.clientWidth
    const viewportHeight = window.innerHeight || document.documentElement.clientHeight
    const availableViewportWidth = Math.max(0, viewportWidth - INSERT_MENU_VIEWPORT_PADDING * 2)
    const width = Math.min(INSERT_MENU_WIDTH, availableViewportWidth)
    const maxLeft = viewportWidth - INSERT_MENU_VIEWPORT_PADDING - width
    const left = Math.min(
        Math.max(INSERT_MENU_VIEWPORT_PADDING, anchorRect.left),
        Math.max(INSERT_MENU_VIEWPORT_PADDING, maxLeft)
    )
    const availableBelow = Math.max(
        0,
        viewportHeight - anchorRect.bottom - INSERT_MENU_GAP - INSERT_MENU_VIEWPORT_PADDING
    )
    const availableAbove = Math.max(0, anchorRect.top - INSERT_MENU_GAP - INSERT_MENU_VIEWPORT_PADDING)
    const placement = availableBelow >= INSERT_MENU_MIN_HEIGHT || availableBelow >= availableAbove ? 'below' : 'above'
    const availableHeight = placement === 'below' ? availableBelow : availableAbove

    return {
        placement,
        top: placement === 'below' ? anchorRect.bottom + INSERT_MENU_GAP : anchorRect.top - INSERT_MENU_GAP,
        left,
        width,
        maxHeight: Math.min(INSERT_MENU_MAX_HEIGHT, availableHeight),
    }
}