: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import clsx from 'clsx'
import React, { Suspense } from 'react'
import { CardMeta } from 'lib/components/Cards/CardMeta'
import { CardTopHeadingRow } from 'lib/components/Cards/CardTopHeadingRow'
import { More, MoreProps } from 'lib/lemon-ui/LemonButton/More'
import { LemonMarkdown } from 'lib/lemon-ui/LemonMarkdown'
import { LemonTableLoader } from 'lib/lemon-ui/LemonTable/LemonTableLoader'
import { Link } from 'lib/lemon-ui/Link'
import { Spinner } from 'lib/lemon-ui/Spinner'
import { dateFilterToText } from 'lib/utils/dateFilters'
import { DashboardPlacement } from '~/types'
import type { DashboardWidgetHeaderLayout, DashboardWidgetHeaderMeta } from '../../widget_types/catalog'
import { LiveWidgetIndicator } from '../../widgets/live/components'
import type { DashboardWidgetSlot } from '../../widgets/registry'
/** Props a widget type's optional TopHeading override receives so it can compose its own
* CardTopHeadingRow — e.g. resolving a saved filter's name the generic header can't derive from config. */
export type DashboardWidgetTopHeadingProps = {
config: Record<string, unknown>
widgetTypeLabel?: string
showWidgetType: boolean
dateText?: string | null
}
export type WidgetCardHeaderProps = {
layout: DashboardWidgetHeaderLayout
title: string
defaultTitle?: string
titleHref?: string
/** Explicit top heading node — used by story fixtures. Otherwise derived from catalog fields below. */
topHeading?: React.ReactNode
widgetTypeLabel?: string
config?: Record<string, unknown>
headerMeta?: DashboardWidgetHeaderMeta
/** Optional per-widget-type top heading row; falls back to the type + date range when absent.
* A `DashboardWidgetSlot` so the registry can code-split it (rendered inside a Suspense below). */
TopHeading?: DashboardWidgetSlot<DashboardWidgetTopHeadingProps>
description?: string
showDescription?: boolean
loading?: boolean
/** Live (self-updating) widget type — shows a pulsing "Live" marker where the date range would go. */
isLive?: boolean
showEditingControls?: boolean
/** When true, title is plain text so drag on the header does not compete with navigation. */
isDashboardEditMode?: boolean
shouldHideMoreButton?: boolean
moreButtonOverlay?: MoreProps['overlay']
/** Refresh control revealed on tile hover (dashboard_tile layout only); forwarded to CardMeta. */
refreshControl?: JSX.Element | null
onDragHandleMouseDown?: React.MouseEventHandler<HTMLDivElement>
}
type WidgetCardHeaderTitleProps = {
title: string
defaultTitle?: string
titleHref?: string
loading?: boolean
isDashboardEditMode?: boolean
headingLevel?: 'h3' | 'h4'
className?: string
}
function WidgetCardHeaderTitle({
title,
defaultTitle,
titleHref,
loading,
isDashboardEditMode,
headingLevel = 'h4',
className,
}: WidgetCardHeaderTitleProps): JSX.Element {
const displayTitle = title || defaultTitle || 'Untitled'
const Heading = headingLevel
const linkTitle = !!titleHref && !isDashboardEditMode
const titleContent = (
<>
<span className={clsx('truncate', linkTitle && 'text-primary')}>{displayTitle}</span>
{loading && (
<span className={clsx('text-sm font-medium ml-1.5', loading ? 'text-accent' : 'text-muted')}>
<Spinner className="mr-1.5 text-base" textColored />
Loading
</span>
)}
</>
)
const titleEl = linkTitle ? (
<Link to={titleHref} className="max-w-full truncate">
{titleContent}
</Link>
) : (
titleContent
)
return (
<Heading
title={displayTitle}
data-attr="widget-card-title"
data-slot="widget-card-header-title"
className={clsx(
linkTitle && 'inline-flex items-center overflow-visible',
headingLevel === 'h3' && 'truncate text-sm font-semibold m-0',
className
)}
>
{titleEl}
</Heading>
)
}
type WidgetCardHeaderDescriptionProps = {
description?: string
showDescription?: boolean
/** Compact CardMeta header — extra spacing above markdown description. */
compact?: boolean
}
export function WidgetCardHeaderDescription({
description,
showDescription = true,
compact = false,
}: WidgetCardHeaderDescriptionProps): JSX.Element | null {
if (!showDescription || !description) {
return null
}
return (
<div
className={clsx(
'min-w-0 max-h-24 w-full max-w-full self-stretch overflow-y-auto break-words [overflow-wrap:anywhere]',
compact && 'mt-1'
)}
data-slot="widget-card-header-description"
>
<LemonMarkdown className="CardMeta__description" lowKeyHeadings>
{description}
</LemonMarkdown>
</div>
)
}
type WidgetCardHeaderActionsProps = {
loading?: boolean
shouldHideMoreButton?: boolean
moreButtonOverlay?: MoreProps['overlay']
showLoadingSpinner?: boolean
}
function WidgetCardHeaderActions({
loading,
shouldHideMoreButton,
moreButtonOverlay,
showLoadingSpinner,
}: WidgetCardHeaderActionsProps): JSX.Element {
return (
<div data-slot="widget-card-header-actions" className="flex items-center gap-1">
{showLoadingSpinner && loading && <Spinner />}
{!shouldHideMoreButton && moreButtonOverlay && <More overlay={moreButtonOverlay} />}
</div>
)
}
export function WidgetCardHeader({
layout,
title,
defaultTitle,
titleHref,
topHeading,
widgetTypeLabel,
config,
headerMeta,
TopHeading,
description,
showDescription = true,
loading,
isLive,
showEditingControls,
isDashboardEditMode,
shouldHideMoreButton,
moreButtonOverlay,
refreshControl,
onDragHandleMouseDown,
}: WidgetCardHeaderProps): JSX.Element {
const showWidgetType = headerMeta?.showWidgetType ?? true
const showDateRange = headerMeta?.showDateRange ?? false
const dateText =
widgetTypeLabel && showDateRange
? widgetDateRangeToText(config?.dateRange as Record<string, unknown> | null | undefined)
: null
const derivedTopHeading =
widgetTypeLabel && (showWidgetType || dateText || isLive) ? (
// A widget type can supply its own top heading row (e.g. session replay surfaces the active
// saved filter name in place of the now-overridden date range); otherwise fall back to the
// type + date range (or the live marker — live widgets have no date range).
TopHeading ? (
<Suspense fallback={null}>
<TopHeading
config={config ?? {}}
widgetTypeLabel={widgetTypeLabel}
showWidgetType={showWidgetType}
dateText={dateText}
/>
</Suspense>
) : (
<CardTopHeadingRow
typeLabel={widgetTypeLabel}
showTypeLabel={showWidgetType}
dateText={dateText}
separateChildren
>
{isLive ? <LiveWidgetIndicator /> : null}
</CardTopHeadingRow>
)
) : null
const resolvedTopHeading = topHeading !== undefined ? topHeading : derivedTopHeading
const titleEl = (
<WidgetCardHeaderTitle
title={title}
defaultTitle={defaultTitle}
titleHref={titleHref}
loading={loading}
isDashboardEditMode={isDashboardEditMode}
headingLevel="h4"
/>
)
const descriptionEl = (
<WidgetCardHeaderDescription
description={description}
showDescription={showDescription}
compact={layout === 'dashboard_tile'}
/>
)
const actions = (
<WidgetCardHeaderActions
loading={loading}
shouldHideMoreButton={shouldHideMoreButton}
moreButtonOverlay={moreButtonOverlay}
showLoadingSpinner={layout === 'simple'}
/>
)
if (layout === 'dashboard_tile') {
return (
<CardMeta
compact
className="WidgetCard__header rounded-b-none"
showEditingControls={!shouldHideMoreButton && !!moreButtonOverlay}
topHeading={(resolvedTopHeading as JSX.Element | null) ?? null}
onMouseDown={showEditingControls ? onDragHandleMouseDown : undefined}
moreButtons={moreButtonOverlay as JSX.Element | undefined}
refreshControl={refreshControl}
content={
<>
{titleEl}
{descriptionEl}
<LemonTableLoader loading={loading} />
</>
}
/>
)
}
return (
<div
data-slot="widget-card-header"
className="WidgetCard__header flex flex-col p-4 pb-2 min-w-0 overflow-hidden"
>
<div className="flex flex-row items-center gap-2">
<div
className={clsx('drag-handle cursor-move flex-1 min-w-0', !showEditingControls && 'hidden')}
onMouseDown={onDragHandleMouseDown}
>
<WidgetCardHeaderTitle
title={title}
defaultTitle={defaultTitle}
titleHref={titleHref}
loading={loading}
isDashboardEditMode={isDashboardEditMode}
headingLevel="h3"
/>
</div>
{!showEditingControls && (
<WidgetCardHeaderTitle
title={title}
defaultTitle={defaultTitle}
titleHref={titleHref}
loading={loading}
isDashboardEditMode={isDashboardEditMode}
headingLevel="h3"
className="flex-1"
/>
)}
{actions}
</div>
{descriptionEl}
</div>
)
}
function widgetDateRangeToText(
dateRange: Record<string, unknown> | null | undefined,
defaultValue: string | null = 'Last 7 days'
): string | null {
if (!dateRange || typeof dateRange !== 'object') {
return defaultValue
}
const dateFrom = 'date_from' in dateRange ? (dateRange.date_from as string | null | undefined) : undefined
const dateTo = 'date_to' in dateRange ? (dateRange.date_to as string | null | undefined) : undefined
if (!dateFrom && !dateTo) {
return defaultValue
}
return dateFilterToText(dateFrom, dateTo, defaultValue)
}
export function widgetCardShouldHideMoreButton(placement: DashboardPlacement, showEditingControls?: boolean): boolean {
return placement === DashboardPlacement.Public || showEditingControls === false
}