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.

16.1 KB
Raw Blame
import { useValues } from 'kea'
import React, { Children, ReactNode, createContext, isValidElement, useContext, useMemo } from 'react'

import { StepProps, StepsProps } from '@posthog/shared-onboarding/steps'
import { StepDefinition, StepModifier } from '@posthog/shared-onboarding/steps'
import { PROSE_LANGUAGE } from '@posthog/shared-onboarding/steps'

import { CodeSnippet, getLanguage } from 'lib/components/CodeSnippet'
import { CopyToClipboardInline } from 'lib/components/CopyToClipboard'
import { LemonBanner } from 'lib/lemon-ui/LemonBanner'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { LemonMarkdown } from 'lib/lemon-ui/LemonMarkdown'
import { LemonTabs } from 'lib/lemon-ui/LemonTabs'
import { LemonTag } from 'lib/lemon-ui/LemonTag'
import { apiHostOrigin } from 'lib/utils/apiHost'
import { domainFor, proxyLogic } from 'scenes/settings/environment/proxyLogic'
import { teamLogic } from 'scenes/teamLogic'

export interface OnboardingComponentsContext {
    Steps: React.ComponentType<StepsProps>
    Step: React.ComponentType<StepProps>
    CodeBlock: React.ComponentType<{
        blocks?: Array<{ language: string; code: string; file?: string }>
        language?: string
        code?: string
        file?: string
    }>
    CalloutBox: React.ComponentType<{
        type: 'action' | 'fyi' | 'caution' | 'info'
        icon?: string
        title?: string
        children: ReactNode
    }>
    ProductScreenshot: React.ComponentType<{
        imageLight: string
        imageDark: string
        alt: string
        classes?: string
        className?: string
        padding?: boolean
    }>
    OSButton: React.ComponentType<any>
    Markdown: React.ComponentType<{ children: string | ReactNode }>
    Blockquote: React.ComponentType<{ children: ReactNode }>
    dedent: (strings: TemplateStringsArray | string, ...values: any[]) => string
    Tab: {
        Group: React.ComponentType<{ tabs: string[]; children: ReactNode }>
        List: React.ComponentType<{ children: ReactNode }>
        Panels: React.ComponentType<{ children: ReactNode }>
        Panel: React.ComponentType<{ children: ReactNode }>
    } & React.ComponentType<{ children: ReactNode }>
    snippets?: Record<string, React.ComponentType<any>>
    selectedFile?: string | null
    setSelectedFile?: (file: string) => void
    apiHost?: string
}

const OnboardingContext = createContext<OnboardingComponentsContext | null>(null)

const SelectedFileContext = createContext<{
    selectedFile: string | null
    setSelectedFile: (file: string) => void
} | null>(null)

/**
 * Keeps the code block file choice (for example Python or Node) outside the content wrapper, so a
 * surface that swaps the whole instruction tree keeps the reader's choice instead of resetting it.
 */
export function OnboardingSelectedFileProvider({ children }: { children: ReactNode }): JSX.Element {
    const [selectedFile, setSelectedFile] = React.useState<string | null>(null)
    const value = useMemo(() => ({ selectedFile, setSelectedFile }), [selectedFile])

    return <SelectedFileContext.Provider value={value}>{children}</SelectedFileContext.Provider>
}

function Steps({ children }: StepsProps): JSX.Element {
    let stepNumber = 0

    const processedChildren = Children.map(children, (child) => {
        if (!isValidElement(child)) {
            return child
        }

        // Only number Step components - check if it's actually a Step component
        const isStep = child.type === Step && 'title' in child.props && typeof child.props.title === 'string'

        if (isStep && !child.props.docsOnly) {
            stepNumber += 1
            return React.cloneElement(child, { stepNumber } as any)
        }

        return child
    })

    return <div className="space-y-6">{processedChildren}</div>
}

function Step({
    title,
    subtitle,
    badge,
    docsOnly,
    stepNumber,
    children,
}: StepProps & { stepNumber?: number }): JSX.Element | null {
    if (docsOnly) {
        return null
    }

    const numberedTitle = stepNumber ? `${stepNumber}. ${title}` : title

    return (
        <div className="space-y-4">
            <div className="flex items-center gap-2">
                <h3 className="m-0">{numberedTitle}</h3>
                {badge && (
                    <LemonTag
                        type={badge === 'required' ? 'default' : badge === 'recommended' ? 'success' : 'option'}
                        className="text-xs"
                    >
                        {badge}
                    </LemonTag>
                )}
            </div>
            {subtitle && <p className="text-muted text-sm m-0">{subtitle}</p>}
            <div className="space-y-4">{children}</div>
        </div>
    )
}

interface CodeBlockItem {
    language: string
    code: string
    file?: string
}

function CodeBlock({
    blocks,
    language,
    code,
    file,
}: {
    blocks?: Array<{ language: string; code: string; file?: string }>
    language?: string
    code?: string
    file?: string
}): JSX.Element {
    const context = useContext(OnboardingContext)
    const globalSelectedFile = context?.selectedFile
    const globalSetSelectedFile = context?.setSelectedFile
    const { currentTeam } = useValues(teamLogic)
    const host = context?.apiHost ?? apiHostOrigin()

    const replacePlaceholders = (codeString: string): string => {
        return codeString
            .replace(/<ph_project_token>/g, currentTeam?.api_token ?? '<ph_project_token>')
            .replace(/<ph_client_api_host>/g, host)
            .replace(/<team_id>/g, currentTeam?.id?.toString() ?? '<team_id>')
    }

    // If blocks array is provided, use it
    const codeBlocks: CodeBlockItem[] = blocks
        ? blocks.map((block) => ({
              language: block.language,
              code: replacePlaceholders(block.code),
              file: block.file,
          }))
        : // Otherwise, use single block props
          language && code
          ? [
                {
                    language,
                    code: replacePlaceholders(code),
                    file,
                },
            ]
          : []

    // The API host is substituted into the snippet as inert highlighted text, so surface it as a
    // standalone, copyable value — users otherwise try (and fail) to click or copy it in the snippet.
    const rawCodeStrings = blocks ? blocks.map((block) => block.code) : code ? [code] : []
    const hostUsed = rawCodeStrings.some((codeString) => codeString.includes('<ph_client_api_host>'))
    const hostHint = hostUsed ? (
        <div className="flex items-center gap-1 text-xs text-muted mt-1">
            <span>API host:</span>
            <CopyToClipboardInline explicitValue={host} description="API host" iconSize="xsmall" selectable>
                {host}
            </CopyToClipboardInline>
        </div>
    ) : null

    const uniqueFiles = codeBlocks
        .map((block) => block.file || 'default')
        .filter((file, index, self) => self.indexOf(file) === index)

    // Use global selected file if available and it exists in this block's files
    const selectedFile =
        globalSelectedFile && uniqueFiles.includes(globalSelectedFile) ? globalSelectedFile : uniqueFiles[0] || null

    const setSelectedFile = (file: string): void => {
        if (globalSetSelectedFile) {
            globalSetSelectedFile(file)
        }
    }

    if (codeBlocks.length === 0) {
        return <></>
    }

    if (codeBlocks.length === 1) {
        const block = codeBlocks[0]
        return (
            <div className="my-4">
                {block.language === PROSE_LANGUAGE ? (
                    <LemonMarkdown>{block.code}</LemonMarkdown>
                ) : (
                    <CodeSnippet language={getLanguage(block.language)}>{block.code}</CodeSnippet>
                )}
                {hostHint}
            </div>
        )
    }

    // Multiple code blocks - use tabs
    const selectedBlock = codeBlocks.find((block) => (block.file || 'default') === selectedFile)

    if (!selectedBlock) {
        return <></>
    }

    return (
        <div className="space-y-2">
            {uniqueFiles.length > 1 && (
                <LemonTabs
                    activeKey={selectedFile || uniqueFiles[0]}
                    onChange={(key) => setSelectedFile(key as string)}
                    tabs={uniqueFiles.map((file) => ({
                        key: file,
                        label: file,
                    }))}
                />
            )}
            {selectedBlock.language === PROSE_LANGUAGE ? (
                <LemonMarkdown>{selectedBlock.code}</LemonMarkdown>
            ) : (
                <CodeSnippet language={getLanguage(selectedBlock.language)}>{selectedBlock.code}</CodeSnippet>
            )}
            {hostHint}
        </div>
    )
}

function CalloutBox({
    type,
    title,
    children,
}: {
    type: 'action' | 'fyi' | 'caution' | 'info'
    icon?: string
    title?: string
    children: ReactNode
}): JSX.Element {
    const bannerType = type === 'caution' ? 'warning' : 'info'

    return (
        <LemonBanner type={bannerType} className="my-4 [&>*]:font-normal">
            {title && <strong>{title}</strong>}
            {children}
        </LemonBanner>
    )
}

function ProductScreenshot({
    imageLight,
    alt,
    classes,
    className,
    padding = true,
}: {
    imageLight: string
    imageDark?: string
    alt: string
    classes?: string
    className?: string
    padding?: boolean
}): JSX.Element {
    return (
        <div className={className}>
            <img src={imageLight} alt={alt} className={`${classes || ''} ${padding ? 'p-4' : ''}`} />
        </div>
    )
}

function OSButton(props: any): JSX.Element {
    return <LemonButton {...props} />
}

function Markdown({ children }: { children: string | ReactNode }): JSX.Element {
    const content = typeof children === 'string' ? children : String(children)

    return <LemonMarkdown>{content}</LemonMarkdown>
}

function Blockquote({ children }: { children: ReactNode }): JSX.Element {
    return (
        <LemonBanner type="info" className="my-4 [&>*]:font-normal">
            {children}
        </LemonBanner>
    )
}

const TabContext = createContext<{ activeTab: number; setActiveTab: (index: number) => void } | null>(null)

function TabGroup({ tabs, children }: { tabs: string[]; children: ReactNode }): JSX.Element {
    const [activeTab, setActiveTab] = React.useState(0)

    return (
        <TabContext.Provider value={{ activeTab, setActiveTab }}>
            <div>
                <LemonTabs
                    activeKey={String(activeTab)}
                    onChange={(key) => setActiveTab(Number(key))}
                    tabs={tabs.map((tab, idx) => ({ key: String(idx), label: tab }))}
                />
                {children}
            </div>
        </TabContext.Provider>
    )
}

function TabList(): JSX.Element {
    // Tab.List is not rendered, it's just for compatibility with Website tabs
    return <></>
}

function TabItem(): JSX.Element {
    // Individual Tab items are not rendered, it's just for compatibility with Website tabs
    return <></>
}

function TabPanels({ children }: { children: ReactNode }): JSX.Element {
    const context = useContext(TabContext)
    if (!context) {
        throw new Error('Tab.Panels must be used within Tab.Group')
    }
    const panels = Children.toArray(children)
    return <div className="mt-4">{panels[context.activeTab]}</div>
}

function TabPanel({ children }: { children: ReactNode }): JSX.Element {
    return <>{children}</>
}

const Tab = Object.assign(TabItem, {
    Group: TabGroup,
    List: TabList,
    Panels: TabPanels,
    Panel: TabPanel,
})

function MinimalSteps({ children }: StepsProps): JSX.Element {
    return <div className="space-y-4">{children}</div>
}

function MinimalStep({ title, docsOnly, children }: StepProps): JSX.Element | null {
    if (docsOnly) {
        return null
    }

    return (
        <div className="space-y-2">
            {title && <h4 className="m-0">{title}</h4>}
            <div className="space-y-4">{children}</div>
        </div>
    )
}

// This is a wrapper to share certain onboarding instructions with the main website repo.
export function OnboardingDocsContentWrapper({
    children,
    snippets,
    createSnippets,
    minimal,
    useReverseProxy,
}: {
    children: ReactNode
    snippets?: Record<string, React.ComponentType<any>>
    createSnippets?: (components: OnboardingComponentsContext) => Record<string, React.ComponentType<any>>
    minimal?: boolean
    /** When true, code snippets show the reverse proxy domain (if one exists) instead of the default API host. */
    useReverseProxy?: boolean
}): JSX.Element {
    const [localSelectedFile, setLocalSelectedFile] = React.useState<string | null>(null)
    const { selectedFile, setSelectedFile } = useContext(SelectedFileContext) ?? {
        selectedFile: localSelectedFile,
        setSelectedFile: setLocalSelectedFile,
    }
    const { proxyRecords } = useValues(proxyLogic)

    const apiHost = useMemo(() => {
        if (useReverseProxy) {
            return domainFor(proxyRecords.find((r) => r.status === 'valid'))
        }

        return apiHostOrigin()
    }, [useReverseProxy, proxyRecords])

    const baseComponents = useMemo<Omit<OnboardingComponentsContext, 'snippets'>>(
        () => ({
            Steps: minimal ? MinimalSteps : Steps,
            Step: minimal ? MinimalStep : Step,
            CodeBlock,
            CalloutBox,
            ProductScreenshot,
            OSButton,
            Markdown,
            Blockquote,
            dedent,
            Tab,
            selectedFile,
            setSelectedFile,
            apiHost,
        }),
        [selectedFile, minimal, apiHost]
    )

    const finalSnippets = useMemo(() => {
        if (createSnippets) {
            return createSnippets(baseComponents as OnboardingComponentsContext)
        }
        return snippets
    }, [createSnippets, snippets, baseComponents])

    const components = useMemo<OnboardingComponentsContext>(
        () =>
            ({
                ...baseComponents,
                snippets: finalSnippets,
            }) as OnboardingComponentsContext,
        [baseComponents, finalSnippets]
    )

    return (
        <OnboardingContext.Provider value={components}>
            <div className="w-full">{children}</div>
        </OnboardingContext.Provider>
    )
}

export function useMDXComponents(): OnboardingComponentsContext {
    const context = useContext(OnboardingContext)
    if (!context) {
        throw new Error('useMDXComponents must be used within OnboardingDocsContentWrapper')
    }
    return context
}

/**
 * Removes leading indentation from a template literal string.
 * Useful for formatting code blocks and markdown content in JSX.
 *
 * @param strings - Template literal strings
 * @param values - Interpolated values
 * @returns Dedented string
 */
export function dedent(strings: TemplateStringsArray | string, ...values: any[]): string {
    const str =
        typeof strings === 'string'
            ? strings
            : Array.isArray(strings)
              ? strings.reduce((acc, s, i) => acc + s + (values[i] || ''), '')
              : String(strings)
    const lines = str.split('\n')
    const firstNonEmptyLine = lines.find((line) => line.trim())
    if (!firstNonEmptyLine) {
        return str.trim()
    }
    const indent = firstNonEmptyLine.match(/^(\s*)/)?.[1]?.length || 0
    return lines
        .map((line) => (line.length >= indent ? line.slice(indent) : line))
        .join('\n')
        .trim()
}

/**
 * Creates an Installation component from a steps function.
 */
export function createInstallation(
    getSteps: (ctx: OnboardingComponentsContext) => StepDefinition[]
): React.ComponentType<StepModifier> {
    return function Installation({ modifySteps }: StepModifier = {}) {
        const components = useMDXComponents()
        const { Steps, Step } = components

        let steps = getSteps(components)
        if (modifySteps) {
            steps = modifySteps(steps)
        }

        return (
            <Steps>
                {steps.map((step, index) => (
                    <Step key={index} title={step.title} badge={step.badge}>
                        {step.content}
                    </Step>
                ))}
            </Steps>
        )
    }
}