: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 { CORE_FILTER_DEFINITIONS_BY_GROUP } from '~/taxonomy/taxonomy'
import { ActionType, EventType } from '~/types'
export function hasTaxonomyPrimaryProperty(eventName: string | null | undefined): boolean {
return !!eventName && !!CORE_FILTER_DEFINITIONS_BY_GROUP.events[eventName]?.primary_property
}
/**
* Resolves the single property whose value a UI should display alongside an event.
*
* Taxonomy-configured defaults (e.g. `$pageview` -> `$pathname`) are immutable and
* always win; team-configured overrides only apply to events that do not have a
* taxonomy default.
*
* This is a pure client-side lookup — both the taxonomy and the overrides map are
* already in memory, so callers can invoke this in tight loops (e.g. selectors
* filtering all events in a session) without n+1 risk.
*/
export function getPrimaryPropertyForEvent(
eventName: string | null | undefined,
overrides?: Record<string, string | null | undefined>
): string | null {
if (!eventName) {
return null
}
const taxonomyDefault = CORE_FILTER_DEFINITIONS_BY_GROUP.events[eventName]?.primary_property
if (taxonomyDefault) {
return taxonomyDefault
}
return overrides?.[eventName] ?? null
}
/**
* Filters a list of events down to those that have a primary property
* (taxonomy default or team override). Pure client-side — wraps
* `getPrimaryPropertyForEvent` so the intent reads as one operation.
*/
export function getEventsWithPrimaryProperty<T extends { event: string }>(
events: T[],
overrides?: Record<string, string | null | undefined>
): T[] {
return events.filter((e) => getPrimaryPropertyForEvent(e.event, overrides) !== null)
}
/**
* The distinct set of primary properties promoted for a list of event names
* (taxonomy default first, then team override). Pure client-side — shared by
* `taxonomicFilterLogic`'s `eventNamesWithPrimaryProperties` selector and
* `useTaxonomicGroupsContext`'s headless equivalent so both express
* "taxonomy default first, then team override, distinct" once.
*/
export function distinctPrimaryPropertiesForEvents(
eventNames: string[],
overrides?: Record<string, string | null | undefined>
): string[] {
const distinct = new Set<string>()
for (const eventName of eventNames) {
const primary = getPrimaryPropertyForEvent(eventName, overrides)
if (primary) {
distinct.add(primary)
}
}
return Array.from(distinct)
}
export function eventToDescription(
event: Pick<EventType, 'elements' | 'event' | 'properties'>,
shortForm: boolean = false
): string {
if (event.event === '$autocapture') {
return autoCaptureEventToDescription(event, shortForm)
}
// For events with a taxonomy-default primary property (e.g. `$pageview` -> `$pathname`,
// `$screen` -> `$screen_name`, `$feature_flag_called` -> `$feature_flag`), use the property's
// value as the description so consumers (notebooks, save-as-action, funnel labels, ...) get
// useful context instead of the bare event name. Returns the event name when the property
// isn't present on the event so callers always get something to display.
const primaryKey = getPrimaryPropertyForEvent(event.event)
if (primaryKey) {
const value = event.properties[primaryKey]
if (value != null && value !== '') {
return String(value)
}
}
return event.event
}
// $event_type to verb map
export const eventTypeToVerb: { [key: string]: string } = {
click: 'clicked',
change: 'changed',
submit: 'submitted',
touch: 'touched a',
value_changed: 'changed value in',
toggle: 'toggled',
menu_action: 'pressed menu',
swipe: 'swiped',
pinch: 'pinched',
pan: 'panned',
rotation: 'rotated',
long_press: 'long pressed',
scroll: 'scrolled in',
}
export function autoCaptureEventToDescription(
event: Pick<EventType, 'elements' | 'event' | 'properties'>,
shortForm: boolean = false
): string {
if (event.event !== '$autocapture') {
return event.event
}
const getVerb = (): string => eventTypeToVerb[event.properties.$event_type] || 'interacted with'
const targetElement = event.elements?.[0]
const describedElement =
event.properties.$event_type === 'click' && targetElement?.tag_name === 'svg'
? (event.elements?.find(({ tag_name }) => tag_name === 'a' || tag_name === 'button') ?? targetElement)
: targetElement
const getTag = (): string => {
if (describedElement?.tag_name === 'a') {
return 'link'
} else if (describedElement?.tag_name === 'img') {
return 'image'
}
return describedElement?.tag_name ?? 'element'
}
const getValue = (): string | null => {
if (event.properties.$el_text) {
return `${shortForm ? '' : 'with text '}"${event.properties.$el_text}"`
} else if (describedElement?.text) {
return `${shortForm ? '' : 'with text '}"${describedElement.text}"`
} else if (describedElement?.attributes?.['attr__aria-label']) {
return `${shortForm ? '' : 'with aria label '}"${describedElement.attributes['attr__aria-label']}"`
} else if (describedElement !== targetElement && targetElement?.text) {
return `${shortForm ? '' : 'with text '}"${targetElement.text}"`
} else if (describedElement !== targetElement && targetElement?.attributes?.['attr__aria-label']) {
return `${shortForm ? '' : 'with aria label '}"${targetElement.attributes['attr__aria-label']}"`
}
return null
}
if (shortForm) {
return [getVerb(), getValue() ?? getTag()].filter((x) => x).join(' ')
}
const value = getValue()
return [getVerb(), getTag(), value].filter((x) => x).join(' ')
}
export function getEventNamesForAction(actionId: string | number, allActions: ActionType[]): string[] {
const id = parseInt(String(actionId))
return allActions
.filter((a) => a.id === id)
.flatMap((a) => a.steps?.filter((step) => step.event).map((step) => String(step.event)) as string[])
}