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.

15.1 KB
Raw Blame
import { MakeLogicType, actions, connect, events, kea, listeners, path, reducers, selectors } from 'kea'
import { loaders } from 'kea-loaders'

import { lemonToast } from 'lib/lemon-ui/LemonToast'

import { inferSelector } from '~/toolbar/shared/product-tours/elementInference'
import { toolbarApi } from '~/toolbar/shared/toolbarApi'
import { toolbarConfigLogic } from '~/toolbar/shared/toolbarConfigLogic'
import { toolbarLogger } from '~/toolbar/shared/toolbarLogger'
import { captureToolbarException, toolbarPosthogJS } from '~/toolbar/shared/toolbarPosthogJS'
import { isToolbarRequestError } from '~/toolbar/shared/toolbarRequestError'
import { ElementRect } from '~/toolbar/shared/types'
import { TOOLBAR_ID, elementToActionStep, getRectForElement, joinWithUiHost } from '~/toolbar/shared/utils'
import { captureAndUploadElementScreenshot } from '~/toolbar/shared/utils/screenshot'

export interface PageContext {
    url: string
    host: string
    pathname: string
    viewport: { width: number; height: number }
}

function capturePageContext(): PageContext {
    // Drop the query string and fragment — they can carry one-time tokens (reset, OAuth, session)
    // that would otherwise be persisted and surfaced to anyone with field note read access.
    return {
        url: `${window.location.origin}${window.location.pathname}`,
        host: window.location.host,
        pathname: window.location.pathname,
        viewport: { width: window.innerWidth, height: window.innerHeight },
    }
}

export interface FieldNote {
    id: string
    comment: string
    field_note_status: 'pending' | 'acknowledged' | 'resolved' | 'dismissed'
    resolution: string | null
    url: string
    host: string
    pathname: string | null
    selector: string
    element_text: string | null
    screenshot_url: string | null
    created_at: string
}

function isToolbarElement(element: HTMLElement): boolean {
    const toolbar = document.getElementById(TOOLBAR_ID)
    return toolbar?.contains(element) ?? false
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface fieldNotesLogicValues {
    dataAttributes: string[] // toolbarConfigLogic
    uiHost: string // toolbarConfigLogic
    buttonFieldNotesVisible: boolean
    comment: string
    deletingId: string | null
    fieldNotes: FieldNote[]
    fieldNotesLoading: boolean
    hasOpenedFieldNotes: boolean
    hoverElement: HTMLElement | null
    hoverElementRect: ElementRect | null
    isFieldNoting: boolean
    pageContext: PageContext | null
    rectUpdateCounter: number
    screenshotUrl: string | null
    selectedElement: HTMLElement | null
    selectedElementRect: ElementRect | null
    submitResult: FieldNote | null
    submitResultLoading: boolean
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface fieldNotesLogicActions {
    clearSelection: () => {
        value: true
    }
    deleteFieldNote: (id: string) => {
        id: string
    }
    hideButtonFieldNotes: () => {
        value: true
    }
    loadFieldNotes: () => any
    loadFieldNotesFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    loadFieldNotesSuccess: (
        fieldNotes: FieldNote[],
        payload?: any
    ) => {
        fieldNotes: FieldNote[]
        payload?: any
    }
    selectElement: (element: HTMLElement) => {
        element: HTMLElement
        page: PageContext
    }
    setComment: (comment: string) => {
        comment: string
    }
    setHoverElement: (element: HTMLElement | null) => {
        element: HTMLElement | null
    }
    setScreenshotUrl: (url: string | null) => {
        url: string | null
    }
    showButtonFieldNotes: () => {
        value: true
    }
    startFieldNote: () => {
        value: true
    }
    stopFieldNote: () => {
        value: true
    }
    submitFieldNote: () => any
    submitFieldNoteFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    submitFieldNoteSuccess: (
        submitResult: FieldNote | null,
        payload?: any
    ) => {
        submitResult: FieldNote | null
        payload?: any
    }
    updateRects: () => {
        value: true
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface fieldNotesLogicMeta {
    __keaTypeGenInternalSelectorTypes: {
        hoverElementRect: (hoverElement: HTMLElement | null, rectUpdateCounter: number) => ElementRect | null
        selectedElementRect: (selectedElement: HTMLElement | null, rectUpdateCounter: number) => ElementRect | null
    }
}

export type fieldNotesLogicType = MakeLogicType<
    fieldNotesLogicValues,
    fieldNotesLogicActions,
    Record<string, any>,
    fieldNotesLogicMeta
>

export const fieldNotesLogic = kea<fieldNotesLogicType>([
    path(['toolbar', 'field-notes', 'fieldNotesLogic']),

    connect(() => ({
        values: [toolbarConfigLogic, ['dataAttributes', 'uiHost']],
    })),

    actions({
        showButtonFieldNotes: true,
        hideButtonFieldNotes: true,
        startFieldNote: true,
        stopFieldNote: true,
        setHoverElement: (element: HTMLElement | null) => ({ element }),
        // Snapshot the page context at select time — on an SPA the URL can change before save.
        selectElement: (element: HTMLElement) => ({ element, page: capturePageContext() }),
        clearSelection: true,
        setComment: (comment: string) => ({ comment }),
        setScreenshotUrl: (url: string | null) => ({ url }),
        deleteFieldNote: (id: string) => ({ id }),
        updateRects: true,
    }),

    loaders(({ values }) => ({
        fieldNotes: [
            [] as FieldNote[],
            {
                loadFieldNotes: async () => {
                    const result = await toolbarApi.fieldNotes.listPending<{ results?: FieldNote[] } | FieldNote[]>({
                        context: 'load_field_notes',
                    })
                    if (!result.ok) {
                        return values.fieldNotes
                    }
                    return Array.isArray(result.data) ? result.data : (result.data.results ?? [])
                },
            },
        ],
    })),

    reducers({
        buttonFieldNotesVisible: [
            false,
            {
                showButtonFieldNotes: () => true,
                hideButtonFieldNotes: () => false,
            },
        ],
        isFieldNoting: [
            false,
            {
                startFieldNote: () => true,
                stopFieldNote: () => false,
                selectElement: () => false,
                hideButtonFieldNotes: () => false,
            },
        ],
        hoverElement: [
            null as HTMLElement | null,
            {
                setHoverElement: (_, { element }) => element,
                stopFieldNote: () => null,
                selectElement: () => null,
                hideButtonFieldNotes: () => null,
            },
        ],
        selectedElement: [
            null as HTMLElement | null,
            {
                selectElement: (_, { element }) => element,
                clearSelection: () => null,
                // Closing/switching the menu closes the comment box (no cascade: select no longer calls setVisibleMenu).
                hideButtonFieldNotes: () => null,
            },
        ],
        comment: [
            '',
            {
                setComment: (_, { comment }) => comment,
                clearSelection: () => '',
                hideButtonFieldNotes: () => '',
                submitFieldNoteSuccess: () => '',
            },
        ],
        pageContext: [
            null as PageContext | null,
            {
                selectElement: (_, { page }) => page,
                clearSelection: () => null,
                hideButtonFieldNotes: () => null,
            },
        ],
        screenshotUrl: [
            null as string | null,
            {
                setScreenshotUrl: (_, { url }) => url,
                selectElement: () => null,
                clearSelection: () => null,
                hideButtonFieldNotes: () => null,
            },
        ],
        rectUpdateCounter: [
            0,
            {
                updateRects: (state) => state + 1,
            },
        ],
        // Drives the "new" badge on the toolbar button — dismissed (persistently) once the menu is first opened.
        hasOpenedFieldNotes: [
            false,
            { persist: true },
            {
                showButtonFieldNotes: () => true,
            },
        ],
        // Id of the field note currently being deleted, to disable its row button (no double-submit).
        deletingId: [
            null as string | null,
            {
                deleteFieldNote: (_, { id }) => id,
                loadFieldNotesSuccess: () => null,
                loadFieldNotesFailure: () => null,
            },
        ],
    }),

    selectors({
        hoverElementRect: [
            (s) => [s.hoverElement, s.rectUpdateCounter],
            (hoverElement: HTMLElement | null): ElementRect | null =>
                hoverElement ? getRectForElement(hoverElement) : null,
        ],
        selectedElementRect: [
            (s) => [s.selectedElement, s.rectUpdateCounter],
            (selectedElement: HTMLElement | null): ElementRect | null =>
                selectedElement ? getRectForElement(selectedElement) : null,
        ],
    }),

    loaders(({ values, actions }) => ({
        submitResult: [
            null as FieldNote | null,
            {
                submitFieldNote: async () => {
                    const { selectedElement, comment, dataAttributes, pageContext, screenshotUrl } = values
                    if (!selectedElement || !comment.trim()) {
                        return null
                    }
                    const selector = elementToActionStep(selectedElement, dataAttributes).selector ?? ''
                    const inferred = inferSelector(selectedElement)?.selector
                    const elementText = (selectedElement.textContent ?? '').trim().slice(0, 500) || null
                    const page = pageContext ?? capturePageContext()

                    const payload = {
                        comment: comment.trim(),
                        url: page.url,
                        host: page.host,
                        pathname: page.pathname,
                        selector,
                        element_text: elementText,
                        element_context: inferred ? { inferred } : {},
                        viewport: page.viewport,
                        ...(screenshotUrl ? { screenshot_url: screenshotUrl } : {}),
                    }

                    const result = await toolbarApi.fieldNotes.create<FieldNote>(payload, {
                        context: 'save_field_note',
                        toastOnError: 'Failed to save field note',
                    })
                    if (!result.ok) {
                        return null
                    }
                    lemonToast.success('Field note saved')
                    actions.clearSelection()
                    actions.loadFieldNotes()
                    return result.data
                },
            },
        ],
    })),

    listeners(({ actions, values }) => ({
        showButtonFieldNotes: () => {
            toolbarPosthogJS.capture('toolbar mode triggered', { mode: 'field-notes', enabled: true })
            actions.loadFieldNotes()
        },
        hideButtonFieldNotes: () => {
            toolbarPosthogJS.capture('toolbar mode triggered', { mode: 'field-notes', enabled: false })
        },
        // Capture a screenshot in the background while the user types — best-effort, never blocks save.
        selectElement: async ({ element }) => {
            try {
                const { mediaId } = await captureAndUploadElementScreenshot(element)
                actions.setScreenshotUrl(joinWithUiHost(values.uiHost, `/uploaded_media/${mediaId}`))
            } catch (e: any) {
                toolbarLogger.warn('field-notes', 'Failed to capture screenshot')
                // A failed upload request (ToolbarRequestError) is expected; only a bug in
                // the screenshot capture itself is worth an exception.
                if (!isToolbarRequestError(e)) {
                    captureToolbarException(e, 'field_note_screenshot')
                }
            }
        },
        deleteFieldNote: async ({ id }) => {
            await toolbarApi.fieldNotes.delete(id, {
                context: 'delete_field_note',
                toastOnError: 'Failed to delete field note',
            })
            actions.loadFieldNotes()
        },
    })),

    events(({ actions, values, cache }) => ({
        afterMount: () => {
            cache.onMouseOver = (e: MouseEvent): void => {
                if (!values.isFieldNoting) {
                    return
                }
                const target = e.target as HTMLElement
                if (target && !isToolbarElement(target)) {
                    actions.setHoverElement(target)
                }
            }
            cache.onClick = (e: MouseEvent): void => {
                if (!values.isFieldNoting) {
                    return
                }
                const target = e.target as HTMLElement
                if (!target || isToolbarElement(target)) {
                    return
                }
                e.preventDefault()
                e.stopPropagation()
                actions.selectElement(target)
            }
            cache.onScroll = (): void => {
                if (values.hoverElement || values.selectedElement) {
                    actions.updateRects()
                }
            }
            cache.onResize = (): void => {
                if (values.hoverElement || values.selectedElement) {
                    actions.updateRects()
                }
            }
            cache.onKeyDown = (e: KeyboardEvent): void => {
                if (e.key === 'Escape' && values.isFieldNoting) {
                    actions.stopFieldNote()
                }
            }
            document.addEventListener('mouseover', cache.onMouseOver, true)
            document.addEventListener('click', cache.onClick, true)
            document.addEventListener('scroll', cache.onScroll, { capture: true, passive: true })
            window.addEventListener('resize', cache.onResize)
            window.addEventListener('keydown', cache.onKeyDown)
        },
        beforeUnmount: () => {
            if (cache.onMouseOver) {
                document.removeEventListener('mouseover', cache.onMouseOver, true)
            }
            if (cache.onClick) {
                document.removeEventListener('click', cache.onClick, true)
            }
            if (cache.onScroll) {
                document.removeEventListener('scroll', cache.onScroll, { capture: true })
            }
            if (cache.onResize) {
                window.removeEventListener('resize', cache.onResize)
            }
            if (cache.onKeyDown) {
                window.removeEventListener('keydown', cache.onKeyDown)
            }
        },
    })),
])