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.

11.6 KB
Raw Blame
import './Link.scss'

import { router } from 'kea-router'
import React from 'react'

import { IconExternal, IconSend } from '@posthog/icons'

import { ButtonPrimitiveProps, buttonPrimitiveVariants } from 'lib/ui/Button/ButtonPrimitives'
import { cn } from 'lib/utils/css-classes'
import { getCurrentTeamId } from 'lib/utils/getAppContext'
import { addProjectIdIfMissing, removeProjectIdIfPresent } from 'lib/utils/kea-router'
import { hasDangerousScheme, isExternalLink } from 'lib/utils/url'
import { urlToResource } from 'scenes/urls'

import { Tooltip, TooltipProps } from '../Tooltip'
import { useLinkDrag } from './useLinkDrag'

type RoutePart = string | Record<string, any>

/**
 * Behavior-only props — the routing surface shared by `LinkPrimitive` and `Link`.
 */
export type LinkPrimitiveProps = Pick<
    React.HTMLProps<HTMLAnchorElement>,
    'target' | 'className' | 'children' | 'title'
> & {
    /** The location to go to. This can be a kea-location or a "href"-like string */
    to?: string | [string, RoutePart?, RoutePart?]
    /** If true, in-app navigation will not be used and the link will navigate with a page load */
    disableClientSideRouting?: boolean
    preventClick?: boolean
    onClick?: (event: React.MouseEvent<HTMLElement>) => void
    onAuxClick?: (event: React.MouseEvent<HTMLElement>) => void
    onDoubleClick?: (event: React.MouseEvent<HTMLElement>) => void
    onMouseDown?: (event: React.MouseEvent<HTMLElement>) => void
    onMouseEnter?: (event: React.MouseEvent<HTMLElement>) => void
    onMouseLeave?: (event: React.MouseEvent<HTMLElement>) => void
    onKeyDown?: (event: React.KeyboardEvent<HTMLElement>) => void
    onFocus?: (event: React.FocusEvent<HTMLElement>) => void
    /** Disables the rendered control. Only meaningful with no `to` (renders a `<button>`). */
    disabled?: boolean
    /** Accessibility role of the link. */
    role?: string
    /** Accessibility tab index of the link. */
    tabIndex?: number
}

export type LinkProps = LinkPrimitiveProps & {
    /** Like plain `disabled`, except we enforce a reason to be shown in the tooltip. */
    disabledReason?: string | null | false
    /**
     * Whether an "open in new" icon should be shown if target is `_blank`.
     * This is true by default if `children` is a string.
     */
    targetBlankIcon?: boolean
    /** If true, the default color will be as normal text with only a link color on hover */
    subtle?: boolean

    /**
     * Button props to pass to the button primitive.
     * If provided, the link will be rendered as the "new" button primitive.
     *
     * @deprecated `buttonProps` renders via the legacy button primitive, which is being
     * phased out. For a link styled as a quill button, render a `LinkPrimitive` as the
     * `render` target of quill's `Button`: `<Button render={<LinkPrimitive to="…" />}>`.
     */
    buttonProps?: Omit<ButtonPrimitiveProps, 'tooltip' | 'tooltipDocLink' | 'tooltipPlacement' | 'children'>

    /** @deprecated WARNING, tooltip prop on Link breaks the auto-show of subsequent tooltips. Use Tooltip component instead for long lists that require tooltips. */
    tooltip?: TooltipProps['title']
    tooltipDocLink?: TooltipProps['docLink']
    tooltipPlacement?: TooltipProps['placement']
    tooltipCloseDelayMs?: TooltipProps['closeDelayMs']
}

const shouldForcePageLoad = (input: any): boolean => {
    if (!input || typeof input !== 'string') {
        return false
    }

    // If the link is to a different team, force a page load to ensure the proper team switch happens
    const matches = input.match(/\/project\/(\d+)/)

    return !!matches && matches[1] !== `${getCurrentTeamId()}`
}

const isPostHogDomain = (url: string): boolean => {
    return /^https:\/\/((www|app|eu)\.)?posthog\.com/.test(url)
}

// Any scheme-qualified target belongs to the browser, not to the app router. A target the router
// claims gets the project prefix, and `/project/<id>/chrome-extension://…` matches no route.
const isDirectLink = (url: string): boolean => {
    return /^([a-zA-Z][a-zA-Z\d+\-.]*:|:\/\/)/.test(url)
}

/** Resolve a `to` target into a concrete href string. */
function resolveHref(to: LinkPrimitiveProps['to'], disableClientSideRouting?: boolean): string | undefined {
    if (!to) {
        return undefined
    }
    if (typeof to !== 'string') {
        return '#'
    }
    // Never let a javascript:/vbscript: target become an href, not even when
    // disableClientSideRouting would otherwise skip the routing rewrite below.
    if (hasDangerousScheme(to)) {
        return '#'
    }
    return isDirectLink(to) || disableClientSideRouting ? to : addProjectIdIfMissing(to)
}

export type PostHogComDocsURL = `https://${'www.' | ''}posthog.com/docs/${string}`

const isPostHogComDocs = (url: string): url is PostHogComDocsURL => {
    return /^https:\/\/(www\.)?posthog\.com\/docs(\/|$|[?#])/.test(url)
}

/**
 * LinkPrimitive — styling-neutral routing core.
 *
 * Owns only href resolution and kea-router navigation, and renders a bare `<a>`
 * (or a bare `<button>` when there's no `to`). It adds NO cosmetic styling, no
 * external-link icon, and no Tooltip / ContextMenu wrappers.
 *
 * Use it as the `render` target of a styled control so the two concerns compose
 * cleanly — e.g. `<Button render={<LinkPrimitive to="…" />}>`: quill's `Button`
 * supplies styling (and `data-quill`), `LinkPrimitive` supplies navigation.
 *
 * For a standalone, cosmetically-styled text link, use `Link` instead.
 */
export const LinkPrimitive: React.FC<LinkPrimitiveProps & React.RefAttributes<HTMLElement>> = React.forwardRef(
    (
        {
            to,
            target,
            disableClientSideRouting,
            preventClick = false,
            onClick: onClickRaw,
            onAuxClick,
            className,
            children,
            disabled,
            role,
            tabIndex,
            ...props
        },
        ref
    ) => {
        // `isExternalLink` knows http and mailto only, and `router.actions.push` rejects any other
        // scheme with a `SecurityError`, so the scheme test widens the same exclusion.
        const browserOwnedLink = isExternalLink(to) || (typeof to === 'string' && isDirectLink(to))
        const { elementProps: draggableProps } = useLinkDrag(typeof to === 'string' ? to : undefined)

        const onClick = (event: React.MouseEvent<HTMLElement>): void => {
            if (event.metaKey || event.ctrlKey) {
                event.stopPropagation()
                return
            }

            onClickRaw?.(event)

            if (event.isDefaultPrevented()) {
                event.preventDefault()
                return
            }

            if (!target && to && !browserOwnedLink && !disableClientSideRouting && !shouldForcePageLoad(to)) {
                event.preventDefault()
                if (to && to !== '#' && !preventClick) {
                    if (Array.isArray(to)) {
                        router.actions.push(...to)
                    } else {
                        router.actions.push(to)
                    }
                }
            }
        }

        if (!to) {
            return (
                <button
                    ref={ref as any}
                    className={className}
                    onClick={onClick}
                    type="button"
                    disabled={disabled}
                    {...props}
                >
                    {children}
                </button>
            )
        }

        const rel = typeof to === 'string' && isPostHogDomain(to) ? 'noopener' : 'noopener noreferrer'
        const href = resolveHref(to, disableClientSideRouting)
        const resource = href && href.startsWith('/') ? urlToResource(removeProjectIdIfPresent(href)) : null

        return (
            // eslint-disable-next-line react/forbid-elements
            <a
                ref={ref as any}
                className={className}
                onClick={onClick}
                onAuxClick={onAuxClick}
                href={href}
                target={target}
                rel={target === '_blank' ? rel : undefined}
                role={role}
                tabIndex={tabIndex}
                {...props}
                {...draggableProps}
                {...(resource ? { 'data-resource-type': resource.type, 'data-resource-ref': resource.ref } : undefined)}
            >
                {children}
            </a>
        )
    }
)
LinkPrimitive.displayName = 'LinkPrimitive'

/**
 * Link
 *
 * A standalone, cosmetically-styled text link. Layers the `.Link` look (and the
 * external-link icon, auto Tooltip, and right-click ContextMenu) on top of
 * `LinkPrimitive`, which does the actual href resolution and routing.
 *
 * For a link that should look like a button, do NOT use `Link` — render a
 * `LinkPrimitive` inside quill's `Button` (see `LinkPrimitive` docs).
 */
export const Link: React.FC<LinkProps & React.RefAttributes<HTMLElement>> = React.forwardRef(
    (
        {
            to,
            target: targetRaw,
            subtle,
            disableClientSideRouting,
            preventClick = false,
            onClick: onClickRaw,
            onAuxClick,
            className,
            children,
            disabled,
            disabledReason,
            targetBlankIcon = typeof children === 'string',
            buttonProps,
            tooltip,
            tooltipDocLink,
            tooltipPlacement,
            tooltipCloseDelayMs,
            role,
            tabIndex,
            ...props
        },
        ref
    ) => {
        const href = resolveHref(to, disableClientSideRouting)
        // Docs open in a new tab so that a click does not unload the app and lose unsaved edits.
        const target = targetRaw ?? (typeof to === 'string' && isPostHogComDocs(to) ? '_blank' : undefined)

        const elementClasses = buttonProps
            ? buttonPrimitiveVariants(buttonProps)
            : `Link ${subtle ? 'Link--subtle' : ''}`

        let element = (
            <LinkPrimitive
                ref={ref}
                to={to}
                target={target}
                disableClientSideRouting={disableClientSideRouting}
                preventClick={preventClick}
                onClick={onClickRaw}
                onAuxClick={onAuxClick}
                className={cn(elementClasses, className)}
                disabled={disabled || !!disabledReason}
                role={role}
                tabIndex={tabIndex}
                {...props}
            >
                {children}
                {targetBlankIcon &&
                    (href?.startsWith('mailto:') ? (
                        <IconSend />
                    ) : target === '_blank' ? (
                        <IconExternal className={buttonProps ? 'size-3' : ''} />
                    ) : null)}
            </LinkPrimitive>
        )

        // Wrap with tooltip first (before context menu) so trigger props can be applied to the element
        if ((tooltip && to) || tooltipDocLink) {
            element = (
                <Tooltip
                    title={tooltip}
                    docLink={tooltipDocLink}
                    placement={tooltipPlacement}
                    closeDelayMs={tooltipCloseDelayMs}
                >
                    {element}
                </Tooltip>
            )
        }

        if (!to) {
            element = (
                <Tooltip
                    title={disabledReason ? <span className="italic">{disabledReason}</span> : tooltip || undefined}
                    placement={tooltipPlacement}
                    closeDelayMs={tooltipCloseDelayMs}
                >
                    <span>{element}</span>
                </Tooltip>
            )
        }

        return element
    }
)
Link.displayName = 'Link'