: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 { InsightQueryNode, InsightVizNode, NodeKind } from '~/queries/schema/schema-general'
import { AccessControlLevel, DashboardTile, FunnelVizType, InsightShortId, InsightModel } from '~/types'
import {
BreakdownColorConfig,
BreakdownValueAndType,
MULTI_BREAKDOWN_SEPARATOR,
applyAutoBreakdownColors,
buildSharedBreakdownValueLookup,
computeTileFallbackTokens,
extractBreakdownValues,
extractBreakdownValuesByTile,
findBreakdownColorConfig,
getBreakdownPropertyKey,
groupBreakdownValuesByProperty,
hasUnresolvedBreakdownTiles,
mergeBreakdownColorConfigs,
} from './dashboardBreakdownColors'
describe('dashboardBreakdownColors', () => {
const createTestTile = (overrides: Partial<InsightModel> = {}): DashboardTile => ({
id: 1,
layouts: {},
color: null,
insight: {
short_id: 'abc123' as InsightShortId,
id: 1,
name: 'Test Insight',
order: null,
result: [],
deleted: false,
saved: true,
created_at: '2023-01-01T00:00:00Z',
created_by: null,
is_sample: false,
dashboard_tiles: null,
updated_at: '2023-01-01T00:00:00Z',
last_modified_at: '2023-01-01T00:00:00Z',
last_modified_by: null,
query: null,
last_refresh: null,
user_access_level: AccessControlLevel.None,
...overrides,
},
})
const trendsTile = (result: any[], breakdownFilter?: Record<string, any>): DashboardTile =>
createTestTile({
result,
query: {
kind: NodeKind.InsightVizNode,
source: { kind: NodeKind.TrendsQuery, ...(breakdownFilter ? { breakdownFilter } : {}) },
} as InsightVizNode<InsightQueryNode>,
})
describe('getBreakdownPropertyKey', () => {
it.each([
['no filter', undefined, null],
['a filter without a breakdown', { breakdown_type: 'event' }, null],
['a single event breakdown', { breakdown: '$browser', breakdown_type: 'event' }, 'event::$browser'],
['a single breakdown with the type defaulted', { breakdown: '$browser' }, 'event::$browser'],
[
'a one-entry multi breakdown',
{ breakdowns: [{ property: '$browser', type: 'event' }] },
'event::$browser',
],
[
'a one-entry multi breakdown with the type defaulted',
{ breakdowns: [{ property: '$browser' }] },
'event::$browser',
],
['a person property', { breakdown: '$browser', breakdown_type: 'person' }, 'person::$browser'],
[
'a group property, keyed by its group type index',
{ breakdown: 'industry', breakdown_type: 'group', breakdown_group_type_index: 2 },
'group:2:industry',
],
[
'a stale group type index on a non-group breakdown',
{ breakdown: '$browser', breakdown_type: 'event', breakdown_group_type_index: 2 },
'event::$browser',
],
[
'a cohort breakdown, regardless of its cohort ids',
{ breakdown: [1, 2], breakdown_type: 'cohort' },
'cohort',
],
[
'display options, which stay out of the key',
{
breakdown: '$current_url',
breakdown_type: 'event',
breakdown_normalize_url: true,
breakdown_histogram_bin_count: 10,
breakdown_limit: 25,
},
'event::$current_url',
],
[
'a multi breakdown, joining parts in order',
{ breakdowns: [{ property: '$browser' }, { property: '$os', type: 'person' }] },
`event::$browser${MULTI_BREAKDOWN_SEPARATOR}person::$os`,
],
] as const)('normalizes %s', (_name, breakdownFilter, expected) => {
expect(getBreakdownPropertyKey(breakdownFilter as any)).toEqual(expected)
})
})
describe('extractBreakdownValues', () => {
it('returns empty array for null input', () => {
expect(extractBreakdownValues(null)).toEqual([])
})
it('handles funnel insights with steps visualization', () => {
const tiles = [
createTestTile({
result: [{ breakdown_value: ['Chrome'] }, { breakdown_value: ['Firefox'] }],
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.FunnelsQuery,
funnelsFilter: {
funnelVizType: FunnelVizType.Steps,
},
},
} as InsightVizNode<InsightQueryNode>,
}),
createTestTile({
result: [{ breakdown_value: 'Safari' }],
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.FunnelsQuery,
funnelsFilter: {
funnelVizType: FunnelVizType.Steps,
},
},
} as InsightVizNode<InsightQueryNode>,
}),
]
// Baseline is on both tiles, so it outranks the single-tile values; Chrome and
// Safari tie on chart position and fall back to value order
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Baseline', breakdownType: 'event' },
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Safari', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
])
})
it('handles trends insights', () => {
const tiles = [
trendsTile([
{ order: 0, breakdown_value: ['Chrome'], compare_label: 'previous' },
{ order: 0, breakdown_value: ['Firefox'], compare_label: 'previous' },
]),
trendsTile([{ order: 0, breakdown_value: 'Safari' }]),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Safari', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
])
})
it('orders values by assignment rank, most re-used first', () => {
const tiles = [
trendsTile([
{ order: 0, breakdown_value: ['Apple'] },
{ order: 0, breakdown_value: ['Zebra'] },
]),
trendsTile([{ order: 0, breakdown_value: ['Zebra'] }]),
]
// Zebra is on two charts vs Apple's one, so the modal lists it first even
// though it trails the first chart and sorts later as a value
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Zebra', breakdownType: 'event' },
{ breakdownValue: 'Apple', breakdownType: 'event' },
])
})
it('deduplicates repeated breakdown values across tiles', () => {
const tiles = [
trendsTile([
{ order: 0, breakdown_value: ['Chrome'] },
{ order: 1, breakdown_value: ['Firefox'] },
]),
trendsTile([
{ order: 0, breakdown_value: ['Chrome'] },
{ order: 1, breakdown_value: ['Safari'] },
]),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
{ breakdownValue: 'Safari', breakdownType: 'event' },
])
})
it('stringifies numeric values so trends and funnels tiles share one entry', () => {
const tiles = [
// trends keys wrap scalars in an array; funnels keep them bare
trendsTile([{ order: 0, breakdown_value: [123] }]),
createTestTile({
result: [{ breakdown_value: 123 }],
query: {
kind: NodeKind.InsightVizNode,
source: { kind: NodeKind.FunnelsQuery },
} as InsightVizNode<InsightQueryNode>,
}),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: '123', breakdownType: 'event' },
{ breakdownValue: 'Baseline', breakdownType: 'event' },
])
})
it('handles funnel insights with trends visualization, without a baseline row', () => {
const tiles = [
createTestTile({
result: [{ breakdown_value: ['Chrome'] }, { breakdown_value: ['Firefox'] }],
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.FunnelsQuery,
funnelsFilter: {
funnelVizType: FunnelVizType.Trends,
},
},
} as InsightVizNode<InsightQueryNode>,
}),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
])
})
it('handles retention insights with a breakdown', () => {
const retentionTile = (result: any[]): DashboardTile =>
createTestTile({
result,
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.RetentionQuery,
breakdownFilter: { breakdown: '$browser', breakdown_type: 'event' },
},
} as InsightVizNode<InsightQueryNode>,
})
const tiles = [
retentionTile([
{ breakdown_value: 'Chrome' },
{ breakdown_value: 'Chrome' },
{ breakdown_value: '$$_posthog_breakdown_other_$$' },
{ breakdown_value: null },
]),
retentionTile([{ breakdown_value: 'Firefox' }]),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' },
{ breakdownValue: 'Firefox', breakdownType: 'event', breakdownProperty: 'event::$browser' },
{
breakdownValue: '$$_posthog_breakdown_other_$$',
breakdownType: 'event',
breakdownProperty: 'event::$browser',
},
])
})
it.each([
[
'paths insight',
createTestTile({
result: [{ breakdown_value: 'Chrome' }],
query: {
kind: NodeKind.InsightVizNode,
source: { kind: NodeKind.PathsQuery },
} as InsightVizNode<InsightQueryNode>,
}),
],
[
'time-to-convert funnel',
createTestTile({
result: [{ breakdown_value: 'Chrome' }],
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.FunnelsQuery,
funnelsFilter: { funnelVizType: FunnelVizType.TimeToConvert },
},
} as InsightVizNode<InsightQueryNode>,
}),
],
[
'retention insight without a breakdown filter',
createTestTile({
result: [{ breakdown_value: 'Chrome' }],
query: {
kind: NodeKind.InsightVizNode,
source: { kind: NodeKind.RetentionQuery },
} as InsightVizNode<InsightQueryNode>,
}),
],
])('ignores %s', (_name, tile) => {
expect(extractBreakdownValues([tile])).toEqual([])
})
it('handles cohort breakdowns, keying them all to the shared cohort property', () => {
const cohortTile = (values: number[][]): DashboardTile =>
createTestTile({
result: values.map((breakdown_value) => ({ order: 0, breakdown_value })),
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.TrendsQuery,
breakdownFilter: {
breakdown: values.flat(),
breakdown_type: 'cohort',
},
},
} as InsightVizNode<InsightQueryNode>,
})
// cohorts 1 and 3 lead their charts and tie, so value order decides; 2 trails its chart
expect(extractBreakdownValues([cohortTile([[1], [2]]), cohortTile([[3]])])).toEqual([
{ breakdownValue: '1', breakdownType: 'cohort', breakdownProperty: 'cohort' },
{ breakdownValue: '3', breakdownType: 'cohort', breakdownProperty: 'cohort' },
{ breakdownValue: '2', breakdownType: 'cohort', breakdownProperty: 'cohort' },
])
})
it('unifies single and multi form of one property into one scoped entry', () => {
const tiles = [
trendsTile([{ order: 0, breakdown_value: ['Chrome'] }], {
breakdown: '$browser',
breakdown_type: 'event',
}),
trendsTile(
[
{ order: 0, breakdown_value: ['Chrome'] },
{ order: 0, breakdown_value: ['Firefox'] },
],
{ breakdowns: [{ property: '$browser' }] }
),
]
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' },
{ breakdownValue: 'Firefox', breakdownType: 'event', breakdownProperty: 'event::$browser' },
])
})
it('clusters values by property in tile order before ranking within each property', () => {
const tiles = [
trendsTile([{ order: 0, breakdown_value: ['Mac OS X'] }], { breakdown: '$os' }),
trendsTile([{ order: 0, breakdown_value: ['Mac OS X'] }], { breakdown: '$os' }),
trendsTile([{ order: 0, breakdown_value: ['Chrome'] }], { breakdown: '$browser' }),
trendsTile([{ order: 0, breakdown_value: ['Chrome'] }], { breakdown: '$browser' }),
trendsTile([{ order: 0, breakdown_value: ['Chrome'] }], { breakdown: '$browser' }),
]
// Chrome is on more tiles, but $os tiles come first on the dashboard
expect(extractBreakdownValues(tiles)).toEqual([
{ breakdownValue: 'Mac OS X', breakdownType: 'event', breakdownProperty: 'event::$os' },
{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' },
])
})
})
describe('extractBreakdownValuesByTile', () => {
it('keeps values grouped by tile and deduplicates within a tile', () => {
const tiles = [
trendsTile([
{ order: 0, breakdown_value: ['Chrome'] },
// second series over the same breakdown repeats the value within the tile
{ order: 1, breakdown_value: ['Chrome'] },
{ order: 0, breakdown_value: ['Firefox'] },
]),
trendsTile([{ order: 0, breakdown_value: 'Chrome' }]),
trendsTile([]),
]
expect(extractBreakdownValuesByTile(tiles)).toEqual([
[
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
],
[{ breakdownValue: 'Chrome', breakdownType: 'event' }],
])
})
it('keeps the funnel baseline property-less while the funnel values are scoped', () => {
const tile = createTestTile({
result: [{ breakdown_value: ['Chrome'] }],
query: {
kind: NodeKind.InsightVizNode,
source: {
kind: NodeKind.FunnelsQuery,
funnelsFilter: { funnelVizType: FunnelVizType.Steps },
breakdownFilter: { breakdown: '$browser', breakdown_type: 'event' },
},
} as InsightVizNode<InsightQueryNode>,
})
// one baseline pin must keep covering every funnel tile, whatever it breaks down by
expect(extractBreakdownValuesByTile([tile])).toEqual([
[
{ breakdownValue: 'Baseline', breakdownType: 'event' },
{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' },
],
])
})
})
describe('groupBreakdownValuesByProperty', () => {
it('clusters values into property groups, with property-less values last', () => {
const baseline = { breakdownValue: 'Baseline', breakdownType: 'event' as const }
const macOs = {
breakdownValue: 'Mac OS X',
breakdownType: 'event' as const,
breakdownProperty: 'event::$os',
}
const chrome = {
breakdownValue: 'Chrome',
breakdownType: 'event' as const,
breakdownProperty: 'event::$browser',
}
const firefox = {
breakdownValue: 'Firefox',
breakdownType: 'event' as const,
breakdownProperty: 'event::$browser',
}
// extractBreakdownValues emits property-less rows first; the modal shows them
// as the closing section instead, after the property groups in dashboard order
expect(groupBreakdownValuesByProperty([baseline, macOs, chrome, firefox])).toEqual([
{ breakdownProperty: 'event::$os', values: [macOs] },
{ breakdownProperty: 'event::$browser', values: [chrome, firefox] },
{ values: [baseline] },
])
})
})
describe('hasUnresolvedBreakdownTiles', () => {
const breakdownFilter = { breakdown: '$browser', breakdown_type: 'event' }
const vizQuery = (source: Record<string, any>): InsightVizNode<InsightQueryNode> =>
({ kind: NodeKind.InsightVizNode, source }) as InsightVizNode<InsightQueryNode>
it.each([
[
'trends tile with a breakdown and no results',
createTestTile({ result: null, query: vizQuery({ kind: NodeKind.TrendsQuery, breakdownFilter }) }),
true,
],
[
'trends tile with a breakdown and empty results',
createTestTile({ result: [], query: vizQuery({ kind: NodeKind.TrendsQuery, breakdownFilter }) }),
false,
],
[
'trends tile without a breakdown and no results',
createTestTile({ result: null, query: vizQuery({ kind: NodeKind.TrendsQuery }) }),
false,
],
[
'funnel steps tile with a breakdown and no results',
createTestTile({
result: null,
query: vizQuery({
kind: NodeKind.FunnelsQuery,
funnelsFilter: { funnelVizType: FunnelVizType.Steps },
breakdownFilter,
}),
}),
true,
],
[
'time-to-convert funnel tile with a breakdown and no results',
createTestTile({
result: null,
query: vizQuery({
kind: NodeKind.FunnelsQuery,
funnelsFilter: { funnelVizType: FunnelVizType.TimeToConvert },
breakdownFilter,
}),
}),
false,
],
[
'retention tile with a breakdown and no results',
createTestTile({ result: null, query: vizQuery({ kind: NodeKind.RetentionQuery, breakdownFilter }) }),
true,
],
[
'non insight-viz tile with no results',
createTestTile({ result: null, query: { kind: NodeKind.DataTableNode } as any }),
false,
],
])('%s', (_name, tile, expected) => {
expect(hasUnresolvedBreakdownTiles([tile])).toBe(expected)
})
})
describe('applyAutoBreakdownColors', () => {
const value = (breakdownValue: string): { breakdownValue: string; breakdownType: 'event' } => ({
breakdownValue,
breakdownType: 'event',
})
// most cases want values shared by two tiles, since single-tile values are not assigned
const sharedTiles = (...breakdownValues: string[]): { breakdownValue: string; breakdownType: 'event' }[][] => [
breakdownValues.map(value),
breakdownValues.map(value),
]
const autoConfig = (
breakdownValue: string,
colorToken: BreakdownColorConfig['colorToken']
): BreakdownColorConfig => ({ breakdownValue, breakdownType: 'event', colorToken, source: 'auto' })
it('assigns only values that appear on two or more tiles', () => {
const result = applyAutoBreakdownColors([[value('Chrome'), value('Firefox')], [value('Chrome')]], [])
// Firefox is unique to one tile, so it keeps position-based colors instead
expect(result).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-1', source: 'auto' },
])
})
it('fills free slots in chart order when re-use ties, appending after existing configs', () => {
const existing: BreakdownColorConfig[] = [
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-3', source: 'manual' },
]
const result = applyAutoBreakdownColors(sharedTiles('Google', 'Alibaba', 'Chrome'), existing)
// both tiles list Google before Alibaba, so Google leads despite sorting later
expect(result).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-3', source: 'manual' },
{ breakdownValue: 'Google', breakdownType: 'event', colorToken: 'preset-1', source: 'auto' },
{ breakdownValue: 'Alibaba', breakdownType: 'event', colorToken: 'preset-2', source: 'auto' },
])
})
it('gives the first slots to the values re-used across the most charts', () => {
const result = applyAutoBreakdownColors(
[[value('Apple'), value('Zebra')], [value('Apple'), value('Zebra')], [value('Zebra')]],
[]
)
// Zebra is on three charts vs Apple's two, which outranks Apple leading the
// shared charts and sorting first as a value
expect(result).toEqual([autoConfig('Zebra', 'preset-1'), autoConfig('Apple', 'preset-2')])
})
it("breaks re-use ties by the values' ranking across their own charts", () => {
const result = applyAutoBreakdownColors(
[
[value('Apple'), value('Zebra')],
[value('Zebra'), value('Apple')],
[value('Zebra'), value('Apple')],
],
[]
)
// Zebra leads two of the three charts, so summed across charts it ranks ahead
// of Apple despite trailing on one chart and sorting first as a value
expect(result).toEqual([autoConfig('Zebra', 'preset-1'), autoConfig('Apple', 'preset-2')])
})
it('returns non-colliding configs unchanged, by reference, in their original order', () => {
const existing: BreakdownColorConfig[] = [
autoConfig('Google', 'preset-2'),
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-3', source: 'manual' },
autoConfig('Alibaba', 'preset-1'),
]
const result = applyAutoBreakdownColors(sharedTiles('Google', 'Alibaba', 'Chrome'), existing)
// an unchanged dashboard must round-trip deep-equal, or every load looks like an edit to save
expect(result).toHaveLength(3)
result.forEach((config, index) => expect(config).toBe(existing[index]))
})
it('keeps covered values stable when a lexically-middle value appears', () => {
const persistedAuto: BreakdownColorConfig[] = [
autoConfig('Alibaba', 'preset-1'),
autoConfig('Google', 'preset-2'),
]
const result = applyAutoBreakdownColors(sharedTiles('Alibaba', 'Bing', 'Google'), persistedAuto)
// Bing sorts between the two covered values but only takes a free slot
expect(result).toEqual([...persistedAuto, autoConfig('Bing', 'preset-3')])
})
it('skips sentinel values', () => {
const result = applyAutoBreakdownColors(
sharedTiles('Baseline', '$$_posthog_breakdown_other_$$', '$$_posthog_breakdown_null_$$', 'Chrome'),
[]
)
expect(result).toEqual([autoConfig('Chrome', 'preset-1')])
})
it('assigns a value again when its pin was cleared with a null token', () => {
const result = applyAutoBreakdownColors(sharedTiles('Chrome'), [
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: null, source: 'manual' },
])
expect(result).toEqual([autoConfig('Chrome', 'preset-1')])
})
it('sizes slots to the given palette instead of the default 15 colors', () => {
const existing: BreakdownColorConfig[] = [
{ breakdownValue: 'Pinned', breakdownType: 'event', colorToken: 'preset-7', source: 'manual' },
]
const result = applyAutoBreakdownColors(sharedTiles('A', 'B', 'C', 'D', 'E'), existing, 5)
// preset-7 renders as the second color of a five-color theme, so that slot is taken.
// E exhausts the palette, and since the pinned value is not on E's tiles, reusing the
// pin's slot is a cross-tile duplicate instead of a within-tile one.
expect(result.slice(1).map((c) => c.colorToken)).toEqual([
'preset-1',
'preset-3',
'preset-4',
'preset-5',
'preset-2',
])
})
it('spreads within-tile duplicates evenly once every slot is on the tile', () => {
const breakdownValues = Array.from({ length: 17 }, (_, i) => `value-${String(i + 1).padStart(2, '0')}`)
const result = applyAutoBreakdownColors(sharedTiles(...breakdownValues), [])
expect(result).toHaveLength(17)
expect(result[14].colorToken).toBe('preset-15')
// values 16 and 17 must collide within the tile, but on the least-used slots
expect(result[15].colorToken).toBe('preset-1')
expect(result[16].colorToken).toBe('preset-2')
})
it('prefers a globally-used slot its own tiles do not show over a within-tile duplicate', () => {
const tiles = [...sharedTiles('A', 'B'), ...sharedTiles('Z')]
const result = applyAutoBreakdownColors(tiles, [], 2)
// A and Z both lead their charts, so they take the two slots and exhaust the
// palette; B's own tiles don't show Z's slot, so B reuses it rather than
// duplicating a color on its own charts
expect(result).toEqual([
autoConfig('A', 'preset-1'),
autoConfig('Z', 'preset-2'),
autoConfig('B', 'preset-2'),
])
})
it('re-slots the lower-ranked persisted auto entry of a within-tile collision, in place', () => {
const existing: BreakdownColorConfig[] = [autoConfig('Bravo', 'preset-1'), autoConfig('Alpha', 'preset-1')]
const result = applyAutoBreakdownColors(sharedTiles('Alpha', 'Bravo'), existing)
// both entries came out of the pre-collision-aware wrap; Alpha leads the charts and keeps the slot
expect(result).toEqual([autoConfig('Bravo', 'preset-2'), autoConfig('Alpha', 'preset-1')])
})
it('keeps the entry re-used across more charts when two persisted auto entries collide', () => {
const existing: BreakdownColorConfig[] = [autoConfig('Alpha', 'preset-1'), autoConfig('Zulu', 'preset-1')]
const result = applyAutoBreakdownColors(
[[value('Alpha'), value('Zulu')], [value('Alpha'), value('Zulu')], [value('Zulu')]],
existing
)
// Zulu is shared across more charts, so it keeps its color even though Alpha
// leads the shared charts and sorts first
expect(result).toEqual([autoConfig('Alpha', 'preset-2'), autoConfig('Zulu', 'preset-1')])
})
it('re-slots a persisted auto entry that collides with a manual pin', () => {
const existing: BreakdownColorConfig[] = [
autoConfig('Alpha', 'preset-3'),
{ breakdownValue: 'Pinned', breakdownType: 'event', colorToken: 'preset-3', source: 'manual' },
]
const result = applyAutoBreakdownColors(sharedTiles('Alpha', 'Pinned'), existing)
expect(result).toEqual([autoConfig('Alpha', 'preset-1'), existing[1]])
})
it('never moves manual pins, even when two of them collide on one tile', () => {
const pins: BreakdownColorConfig[] = [
{ breakdownValue: 'One', breakdownType: 'event', colorToken: 'preset-5', source: 'manual' },
{ breakdownValue: 'Two', breakdownType: 'event', colorToken: 'preset-5', source: 'manual' },
]
const result = applyAutoBreakdownColors(sharedTiles('One', 'Two', 'Three'), pins)
expect(result).toEqual([...pins, autoConfig('Three', 'preset-1')])
})
const scopedValue = (breakdownValue: string, breakdownProperty: string): BreakdownValueAndType => ({
breakdownValue,
breakdownType: 'event',
breakdownProperty,
})
const scopedTiles = (breakdownProperty: string, ...breakdownValues: string[]): BreakdownValueAndType[][] => [
breakdownValues.map((v) => scopedValue(v, breakdownProperty)),
breakdownValues.map((v) => scopedValue(v, breakdownProperty)),
]
const scopedAutoConfig = (
breakdownValue: string,
breakdownProperty: string,
colorToken: BreakdownColorConfig['colorToken']
): BreakdownColorConfig => ({
breakdownValue,
breakdownType: 'event',
breakdownProperty,
colorToken,
source: 'auto',
})
it('starts each property over from the first palette slot', () => {
const result = applyAutoBreakdownColors(
[
...scopedTiles('event::$browser', 'Chrome', 'Firefox'),
...scopedTiles('event::$os', 'Mac OS X', 'Windows'),
],
[]
)
// properties are independent color worlds like standalone insights: their tiles
// never meet, so reusing slots across them is invisible and stretches the palette
expect(result).toEqual([
scopedAutoConfig('Chrome', 'event::$browser', 'preset-1'),
scopedAutoConfig('Mac OS X', 'event::$os', 'preset-1'),
scopedAutoConfig('Firefox', 'event::$browser', 'preset-2'),
scopedAutoConfig('Windows', 'event::$os', 'preset-2'),
])
})
it('gives one value the same color under every property it appears under', () => {
const result = applyAutoBreakdownColors(
[...scopedTiles('event::is_admin', 'true'), ...scopedTiles('event::is_mobile', 'true')],
[]
)
// "true" reads as one value wherever it shows up, so each property keeps its own
// entry, free to diverge via pinning, but both land on one color
expect(result).toEqual([
scopedAutoConfig('true', 'event::is_admin', 'preset-1'),
scopedAutoConfig('true', 'event::is_mobile', 'preset-1'),
])
})
it('counts a value on single tiles of two different properties as shared', () => {
const result = applyAutoBreakdownColors(
[[scopedValue('true', 'event::is_admin')], [scopedValue('true', 'event::is_mobile')]],
[]
)
// one tile each is a value the reader meets twice, and per-property counting is
// what used to leave it with no dashboard color and a position color that flips
expect(result).toEqual([
scopedAutoConfig('true', 'event::is_admin', 'preset-1'),
scopedAutoConfig('true', 'event::is_mobile', 'preset-1'),
])
})
it('ranks a value by its charts across properties, so the wider one claims first', () => {
const result = applyAutoBreakdownColors(
[
[scopedValue('Chrome', 'event::$browser'), scopedValue('Firefox', 'event::$browser')],
[scopedValue('Chrome', 'event::$browser'), scopedValue('Firefox', 'event::$browser')],
[scopedValue('Firefox', 'event::browser_name')],
],
[]
)
// Firefox trails Chrome on both $browser charts, but it is on three charts against
// Chrome's two, so it claims the first slot and carries it into browser_name
expect(result).toEqual([
scopedAutoConfig('Firefox', 'event::$browser', 'preset-1'),
scopedAutoConfig('Firefox', 'event::browser_name', 'preset-1'),
scopedAutoConfig('Chrome', 'event::$browser', 'preset-2'),
])
})
it('copies the color a value was pinned to under another property', () => {
const pin: BreakdownColorConfig = {
breakdownValue: 'Chrome',
breakdownType: 'event',
breakdownProperty: 'event::$browser',
colorToken: 'preset-6',
source: 'manual',
}
const result = applyAutoBreakdownColors(
[[scopedValue('Chrome', 'event::$browser')], [scopedValue('Chrome', 'event::browser_name')]],
[pin]
)
// pins claim before auto entries, so the pinned color is the one that spreads
// instead of the palette's first free slot
expect(result).toEqual([pin, scopedAutoConfig('Chrome', 'event::browser_name', 'preset-6')])
})
it('gives up copying a color when the slot is taken within the other property', () => {
const pin: BreakdownColorConfig = {
breakdownValue: 'Opera',
breakdownType: 'event',
breakdownProperty: 'event::browser_name',
colorToken: 'preset-1',
source: 'manual',
}
const result = applyAutoBreakdownColors(
[
[scopedValue('Chrome', 'event::$browser')],
[scopedValue('Chrome', 'event::browser_name'), scopedValue('Opera', 'event::browser_name')],
],
[pin]
)
// Chrome takes the first slot under $browser, but Opera's pin holds it under
// browser_name, and sharing a chart with Opera is worse than a second color
expect(result).toEqual([
pin,
scopedAutoConfig('Chrome', 'event::$browser', 'preset-1'),
scopedAutoConfig('Chrome', 'event::browser_name', 'preset-2'),
])
})
it('lets a property-less pin cover its value and claim its slot under every property', () => {
const pin: BreakdownColorConfig = {
breakdownValue: 'Chrome',
breakdownType: 'event',
colorToken: 'preset-1',
source: 'manual',
}
const result = applyAutoBreakdownColors(
[
...scopedTiles('event::$browser', 'Chrome', 'Firefox'),
...scopedTiles('event::browser_name', 'Chrome', 'Opera'),
],
[pin]
)
// the legacy pin matches Chrome under both properties, so neither property
// assigns Chrome again and both hand out slots around the pinned one
expect(result).toEqual([
pin,
scopedAutoConfig('Firefox', 'event::$browser', 'preset-2'),
scopedAutoConfig('Opera', 'event::browser_name', 'preset-2'),
])
})
it('keeps a property-less auto entry covering its value, without a scoped duplicate', () => {
const legacy = autoConfig('Chrome', 'preset-2')
const result = applyAutoBreakdownColors(scopedTiles('event::$browser', 'Chrome'), [legacy])
// dashboards saved before property scoping keep their colors byte-for-byte
expect(result).toHaveLength(1)
expect(result[0]).toBe(legacy)
})
it('re-slots a displaced property-less auto entry off the slots its tiles already show', () => {
const existing: BreakdownColorConfig[] = [
scopedAutoConfig('Alpha', 'event::$browser', 'preset-1'),
autoConfig('Zulu', 'preset-1'),
]
const result = applyAutoBreakdownColors(scopedTiles('event::$browser', 'Alpha', 'Zulu'), existing)
// the displaced legacy entry has no property of its own, but its tiles belong to
// $browser, whose used slots it must avoid to stay distinct on those charts
expect(result).toEqual([existing[0], autoConfig('Zulu', 'preset-2')])
})
})
describe('buildSharedBreakdownValueLookup', () => {
it('is true only for values appearing on two or more tiles', () => {
const isShared = buildSharedBreakdownValueLookup([
[
{ breakdownValue: 'Chrome', breakdownType: 'event' },
{ breakdownValue: 'Firefox', breakdownType: 'event' },
],
[{ breakdownValue: 'Chrome', breakdownType: 'event' }],
])
expect(isShared({ breakdownValue: 'Chrome', breakdownType: 'event' })).toBe(true)
expect(isShared({ breakdownValue: 'Firefox', breakdownType: 'event' })).toBe(false)
expect(isShared({ breakdownValue: 'Chrome', breakdownType: 'person' })).toBe(false)
})
it('counts a value across the properties it appears under', () => {
const isShared = buildSharedBreakdownValueLookup([
[
{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' },
{ breakdownValue: 'true', breakdownType: 'event', breakdownProperty: 'event::$browser' },
],
[{ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' }],
[{ breakdownValue: 'true', breakdownType: 'event', breakdownProperty: 'event::is_admin' }],
])
expect(
isShared({ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::$browser' })
).toBe(true)
// "true" is on one tile of each of two properties, which is still a value the
// reader meets twice, so both entries qualify and aim for one color
expect(
isShared({ breakdownValue: 'true', breakdownType: 'event', breakdownProperty: 'event::$browser' })
).toBe(true)
expect(
isShared({ breakdownValue: 'true', breakdownType: 'event', breakdownProperty: 'event::is_admin' })
).toBe(true)
// property-less legacy entries read the same count, wherever the value appears
expect(isShared({ breakdownValue: 'true', breakdownType: 'event' })).toBe(true)
expect(isShared({ breakdownValue: 'Chrome', breakdownType: 'event' })).toBe(true)
// a value on one tile only still keeps its insight's own colors
expect(
isShared({ breakdownValue: 'Chrome', breakdownType: 'event', breakdownProperty: 'event::is_admin' })
).toBe(false)
})
})
describe('computeTileFallbackTokens', () => {
it('returns an empty map for a tile without overrides, keeping plain position colors', () => {
const tokens = computeTileFallbackTokens(
[
{ position: 0, overrideToken: null },
{ position: 1, overrideToken: null },
],
15
)
expect(tokens.size).toBe(0)
})
it('fills the slots the tile overrides do not use, in position order', () => {
const tokens = computeTileFallbackTokens(
[
{ position: 0, overrideToken: null },
{ position: 1, overrideToken: 'preset-1' },
{ position: 2, overrideToken: null },
{ position: 3, overrideToken: 'preset-4' },
{ position: 4, overrideToken: null },
],
15
)
expect(tokens).toEqual(
new Map([
[0, 'preset-2'],
[2, 'preset-3'],
[4, 'preset-5'],
])
)
})
it('assigns one slot per position when compare pairs repeat a position', () => {
const tokens = computeTileFallbackTokens(
[
{ position: 0, overrideToken: null },
{ position: 0, overrideToken: null },
{ position: 1, overrideToken: 'preset-1' },
],
15
)
expect(tokens).toEqual(new Map([[0, 'preset-2']]))
})
it('cycles the free slots once exhausted instead of reusing an override slot', () => {
const tokens = computeTileFallbackTokens(
[
{ position: 0, overrideToken: 'preset-1' },
{ position: 1, overrideToken: null },
{ position: 2, overrideToken: null },
{ position: 3, overrideToken: null },
{ position: 4, overrideToken: null },
],
3
)
expect(tokens).toEqual(
new Map([
[1, 'preset-2'],
[2, 'preset-3'],
[3, 'preset-2'],
[4, 'preset-3'],
])
)
})
it('returns an empty map when overrides cover the whole palette', () => {
const tokens = computeTileFallbackTokens(
[
{ position: 0, overrideToken: 'preset-1' },
{ position: 1, overrideToken: 'preset-2' },
{ position: 2, overrideToken: null },
],
2
)
expect(tokens.size).toBe(0)
})
})
describe('mergeBreakdownColorConfigs', () => {
it('lets earlier lists win and deduplicates by value and type', () => {
const merged = mergeBreakdownColorConfigs(
[{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-5', source: 'manual' }],
[
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-1' },
{ breakdownValue: 'Firefox', breakdownType: 'event', colorToken: 'preset-2' },
]
)
expect(merged).toEqual([
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-5', source: 'manual' },
{ breakdownValue: 'Firefox', breakdownType: 'event', colorToken: 'preset-2' },
])
})
it('normalizes legacy non-string values', () => {
const merged = mergeBreakdownColorConfigs([
{ breakdownValue: 123 as any, breakdownType: 'event', colorToken: 'preset-1' },
])
expect(merged).toEqual([{ breakdownValue: '123', breakdownType: 'event', colorToken: 'preset-1' }])
})
it('keeps scoped and property-less entries for one value separate, deduplicating within each scope', () => {
const scopedPin: BreakdownColorConfig = {
breakdownValue: 'Chrome',
breakdownType: 'event',
breakdownProperty: 'event::$browser',
colorToken: 'preset-2',
source: 'manual',
}
const merged = mergeBreakdownColorConfigs(
[scopedPin],
[
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-1' },
{ ...scopedPin, colorToken: 'preset-3' },
]
)
// the scoped pin shadows its persisted version but not the legacy one, which
// still colors Chrome under other properties
expect(merged).toEqual([
scopedPin,
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-1' },
])
})
})
describe('findBreakdownColorConfig', () => {
const configs: BreakdownColorConfig[] = [
{ breakdownValue: '123', breakdownType: 'event', colorToken: 'preset-1' },
{ breakdownValue: 'a::b', breakdownType: 'event', colorToken: 'preset-2' },
{ breakdownValue: 'Chrome', breakdownType: 'person', colorToken: 'preset-3' },
{
breakdownValue: ['a', 'b'].join(MULTI_BREAKDOWN_SEPARATOR),
breakdownType: 'event',
colorToken: 'preset-4',
},
]
it.each([
['numeric dataset value matches a stringified config', 123, 'event', 'preset-1'],
[
'multi-breakdown array matches its own entry, not a scalar containing "::"',
['a', 'b'],
'event',
'preset-4',
],
['scalar containing "::" matches its own entry, not a multi-breakdown array', 'a::b', 'event', 'preset-2'],
['breakdown type must match', 'Chrome', 'event', undefined],
['type defaults to event when not provided', '123', undefined, 'preset-1'],
] as const)('%s', (_name, breakdownValue, breakdownType, expectedToken) => {
expect(findBreakdownColorConfig(configs, breakdownValue, breakdownType as any)?.colorToken).toEqual(
expectedToken
)
})
it('returns undefined for null or undefined dataset values', () => {
expect(findBreakdownColorConfig(configs, undefined, 'event')).toBeUndefined()
expect(findBreakdownColorConfig(configs, null, 'event')).toBeUndefined()
})
// Separate configs, because giving the shared list an untyped entry would satisfy the
// 'breakdown type must match' case above and remove what it checks.
it.each([
['an entry with no type matches an event series', undefined, 'event', 'preset-9'],
['an entry with no type matches a series with no type', undefined, undefined, 'preset-9'],
['a null type reads the same as an omitted one', null, 'event', 'preset-9'],
// The default is `event`, not a wildcard, so an untyped entry must not colour a person
// series that happens to share the value.
['an entry with no type does not match a person series', undefined, 'person', undefined],
] as const)('%s', (_name, configType, seriesType, expectedToken) => {
const untypedConfigs = [
{ breakdownValue: 'Chrome', breakdownType: configType, colorToken: 'preset-9' },
] as BreakdownColorConfig[]
expect(findBreakdownColorConfig(untypedConfigs, 'Chrome', seriesType as any)?.colorToken).toEqual(
expectedToken
)
})
it('prefers a property-scoped entry and falls back to a property-less one', () => {
const scopedConfigs: BreakdownColorConfig[] = [
{ breakdownValue: 'Chrome', breakdownType: 'event', colorToken: 'preset-1' },
{
breakdownValue: 'Chrome',
breakdownType: 'event',
breakdownProperty: 'event::$browser',
colorToken: 'preset-2',
},
]
// the scoped entry wins for its own property even though the legacy one is listed first
expect(findBreakdownColorConfig(scopedConfigs, 'Chrome', 'event', 'event::$browser')?.colorToken).toBe(
'preset-2'
)
// under any other property, and without property context, the legacy entry applies
expect(findBreakdownColorConfig(scopedConfigs, 'Chrome', 'event', 'event::browser_name')?.colorToken).toBe(
'preset-1'
)
expect(findBreakdownColorConfig(scopedConfigs, 'Chrome', 'event')?.colorToken).toBe('preset-1')
})
})
})