: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 { SearchItem, filterNewItems } from 'lib/components/Search/searchItems'
import { SETTINGS_THEME_ITEM_ID, filterSearchItems } from 'lib/components/Search/utils'
import type { SearchCorrection } from './commandKCorrection'
import { CursorContext, FilterDefinition, FilterOptions, ValueOption, matchValueOptions } from './commandKQuery'
import { buildRankedResults } from './commandKRankedResults'
import {
FILTER_TOKEN,
MAX_LOCAL_QUERY_LENGTH,
freeWords,
searchWords,
strictLocalMatches,
tokenTypos,
} from './commandKRanking'
import { REMOTE_SOURCES, RESULTS_LIMIT, RemoteSource, SECONDARY_LIMIT } from './commandKSources'
export const RECENTS_LIMIT = 5
export const SUGGESTIONS_LIMIT = 8
export const DEFAULT_SKELETON_ROWS = 3
const TRAILING_SOURCES: RemoteSource[] = ['persons', 'groups']
/** Lists that filter in memory on every keystroke, in the order they render in Search mode. */
const LOCAL_SOURCES = [
'products',
'data-management',
'people',
'health',
'actions',
'shortcuts',
'settings',
'create',
] as const
type LocalSource = (typeof LOCAL_SOURCES)[number]
export type CommandKMode = 'empty' | 'key' | 'value' | 'search'
export type CommandKSectionKey =
| 'filters'
| 'suggestions'
| 'recents'
| 'starred'
| LocalSource
| RemoteSource
| 'ask-ai'
| 'notice'
| 'loading-more'
| 'best-matches'
| `group-${string}`
export type CommandKRow =
| { kind: 'filter-key'; key: string; filter: FilterDefinition; negated: boolean }
| { kind: 'filter-value'; key: string; filter: FilterDefinition; option: ValueOption; negated: boolean }
| { kind: 'message'; key: string; text: string }
| { kind: 'skeleton'; key: string }
| {
kind: 'item'
key: string
item: SearchItem
section: CommandKSectionKey
duplicates?: number
highlightWords?: string[]
ranked?: boolean
showCreator?: boolean
showType?: boolean
}
| { kind: 'ask-ai'; key: string; question: string }
| { kind: 'scope'; key: string; type: string; label: string }
| { kind: 'expand'; key: string; group: string; label: string }
| { kind: 'notice'; key: string; reason: 'partial' | 'typos' | 'corrected'; missing: string[]; shown: string[] }
| { kind: 'loading-more'; key: string }
export interface CommandKSection {
key: CommandKSectionKey
label: string
rows: CommandKRow[]
count?: number
countIsLowerBound?: boolean
/** `stale` keeps the previous query's rows on screen until the new ones land. */
state: 'ready' | 'loading' | 'stale'
}
export interface ViewAll {
item: SearchItem
placement: 'lead' | 'trail'
}
/** What a remote section can render. Which request is in flight lives elsewhere, so starting one never re-renders. */
export interface RemoteSlot {
cache: Record<string, SearchItem[]>
failed?: Record<string, true>
}
export type RemoteSlots = Record<RemoteSource, RemoteSlot>
export const emptyRemoteSlots = (): RemoteSlots =>
Object.fromEntries(REMOTE_SOURCES.map((source) => [source, { cache: {} }])) as RemoteSlots
const SECTION_LABELS: Record<Exclude<CommandKSectionKey, `group-${string}`>, string> = {
filters: 'Filters',
suggestions: 'Suggestions',
recents: 'Recents',
starred: 'Starred',
results: 'Results',
products: 'Products',
'data-management': 'Data management',
people: 'People',
health: 'Health',
actions: 'Actions',
shortcuts: 'Shortcuts',
settings: 'Settings',
create: 'Create new',
events: 'Events',
properties: 'Properties',
workflows: 'Workflows',
accounts: 'Accounts',
tickets: 'Support tickets',
persons: 'Persons',
groups: 'Groups',
'ask-ai': 'PostHog AI',
'best-matches': 'Best matches',
notice: '',
'loading-more': '',
}
export const isSelectable = (row: CommandKRow): boolean =>
row.kind !== 'message' && row.kind !== 'skeleton' && row.kind !== 'notice' && row.kind !== 'loading-more'
const itemIdentity = (item: SearchItem): string => {
const type = item.record?.type
const ref = item.record?.ref
return typeof type === 'string' && typeof ref === 'string' && ref ? `${type}:${ref}` : item.id
}
/**
* The file system can hold more than one entry for the same object, so a list can repeat an item.
* Row keys must be unique, because the highlight and the row DOM ids follow the key. Only the first
* row for each key stays, and the limit applies after that.
*/
const itemRows = (section: CommandKSectionKey, items: SearchItem[], limit = Infinity): CommandKRow[] => {
const rows: CommandKRow[] = []
const seen = new Set<string>()
for (const item of items) {
if (rows.length >= limit) {
break
}
const key = `${section}/${itemIdentity(item)}`
if (!seen.has(key)) {
seen.add(key)
rows.push({ kind: 'item', key, item, section })
}
}
return rows
}
const readySection = (key: Exclude<CommandKSectionKey, `group-${string}`>, rows: CommandKRow[]): CommandKSection => ({
key,
label: SECTION_LABELS[key],
rows,
state: 'ready',
})
const skeletonRows = (key: Exclude<CommandKSectionKey, `group-${string}`>): CommandKRow[] =>
Array.from({ length: DEFAULT_SKELETON_ROWS }, (_, index) => ({ kind: 'skeleton', key: `${key}/skeleton-${index}` }))
const loadingSection = (key: Exclude<CommandKSectionKey, `group-${string}`>): CommandKSection => ({
...readySection(key, skeletonRows(key)),
state: 'loading',
})
const isSettled = (slot: RemoteSlot, query: string | undefined): boolean => !query || query in slot.cache
function remoteSection(
source: RemoteSource,
items: SearchItem[],
state: CommandKSection['state']
): CommandKSection | null {
const limit = source === 'results' ? RESULTS_LIMIT : SECONDARY_LIMIT
return items.length > 0 ? { ...readySection(source, itemRows(source, items, limit)), state } : null
}
export interface SuggestionsLoading {
members: boolean
folders: boolean
}
/** Value suggestions for the `key:` under the cursor. */
export function buildSuggestions(
context: Extract<CursorContext, { kind: 'value' }>,
options: FilterOptions,
loading: SuggestionsLoading
): CommandKSection {
const { filter, partial, negated } = context
const valueRow = (option: ValueOption): CommandKRow => ({
kind: 'filter-value',
key: `suggestions/${negated ? '-' : ''}${filter.key}:${option.value}`,
filter,
option,
negated,
})
const message = (key: string, text: string): CommandKSection =>
readySection('suggestions', [{ kind: 'message', key: `suggestions/${key}`, text }])
if (filter.key === 'name') {
return partial
? readySection('suggestions', [valueRow({ value: partial, label: partial })])
: message('name-hint', 'Type part of a name')
}
if ((filter.key === 'createdBy' && loading.members) || (filter.key === 'in' && loading.folders)) {
return loadingSection('suggestions')
}
const matches = matchValueOptions(options[filter.key], partial, { allowSubstring: filter.key !== 'createdBy' })
if (matches.length === 0) {
return filter.key === 'is'
? message('no-match', `No type called ${partial}`)
: message('no-match', `No match for "${partial}". Press Space to search anyway.`)
}
// `is:` is a short fixed list, so every type shows. Other keys can have hundreds of values.
return readySection(
'suggestions',
(filter.key === 'is' ? matches : matches.slice(0, SUGGESTIONS_LIMIT)).map(valueRow)
)
}
export type LocalLists = Record<LocalSource | 'recents' | 'starred', SearchItem[]>
export interface SectionsQuery {
/** The query each remote source searches for this input. Sources missing here do not apply. */
remoteQueries: Partial<Record<RemoteSource, string>>
/** The free text the in-memory lists filter on. Empty while a filter limits the palette to objects. */
localQuery: string
/** Leads the Settings section when the query asks about the theme. */
themeItem: SearchItem | null
askAiQuestion: string | null
viewAll: ViewAll | null
}
export interface SectionsInput extends SectionsQuery {
mode: CommandKMode
context: CursorContext
suggestions: CommandKSection | null
local: LocalLists
remote: RemoteSlots
stale: boolean
personsFirst: boolean
searchCorrection: SearchCorrection | null
expandedGroups?: string[]
}
const isRanked = (query: SectionsQuery): boolean =>
!!query.remoteQueries.results && freeWords(query.remoteQueries.results).length > 0
export const resultsSettled = (query: SectionsQuery, remote: RemoteSlots): boolean =>
isSettled(remote.results, query.remoteQueries.results) &&
(!isRanked(query) || isSettled(remote.accounts, query.remoteQueries.accounts))
export function pickDisplayedQuery(
current: SectionsQuery,
shown: SectionsQuery | null,
remote: RemoteSlots
): { query: SectionsQuery; stale: boolean } {
if (!shown?.remoteQueries.results || resultsSettled(current, remote)) {
return { query: current, stale: false }
}
if (isRanked(current) && !isRanked(shown)) {
return { query: current, stale: false }
}
return { query: shown, stale: true }
}
const exactSettingsMatches = (settings: SearchItem[], localQuery: string): SearchItem[] =>
localQuery ? matchLocal('settings', settings, localQuery, true) : []
const matchesWord = (words: string[]) => (token: string) => words.some((word) => tokenTypos(token, word) === 0)
function settingsMatches(items: SearchItem[], fullQuery: string): SearchItem[] {
const query = fullQuery.trim().replace(/\s+/g, ' ').slice(0, MAX_LOCAL_QUERY_LENGTH)
const tokens = searchWords(query)
if (!tokens.length) {
return []
}
const byNameOrAlias = strictLocalMatches(items, query)
const named = new Set(byNameOrAlias.map((item) => item.id))
const acrossFields = items.filter((item) => {
if (named.has(item.id)) {
return false
}
const own = matchesWord(
[String(item.displayName || item.name), ...(item.searchKeywords ?? [])].flatMap(searchWords)
)
const context = matchesWord([item.parentName ?? '', ...(item.contextKeywords ?? [])].flatMap(searchWords))
return tokens.some(own) && tokens.every((token) => own(token) || context(token))
})
return [...byNameOrAlias, ...acrossFields]
}
const LOCAL_MATCH_CACHE_SIZE = 50
const localMatchCache = new WeakMap<SearchItem[], Map<string, SearchItem[]>>()
function matchLocal(source: LocalSource, items: SearchItem[], query: string, ranked: boolean): SearchItem[] {
const strict = ranked && source !== 'create'
const key = `${strict ? 'strict' : 'fuzzy'}:${query}`
let byQuery = localMatchCache.get(items)
if (!byQuery) {
byQuery = new Map()
localMatchCache.set(items, byQuery)
}
const cached = byQuery.get(key)
if (cached) {
return cached
}
const matches =
strict && source === 'settings'
? settingsMatches(items, query)
: strict
? strictLocalMatches(items, query)
: source === 'create'
? filterNewItems(items, query)
: filterSearchItems(items, query)
if (byQuery.size >= LOCAL_MATCH_CACHE_SIZE) {
byQuery.delete(byQuery.keys().next().value!)
}
byQuery.set(key, matches)
return matches
}
function withViewAll(results: CommandKSection | null, viewAll: ViewAll | null): CommandKSection | null {
if (!viewAll) {
return results
}
const row: CommandKRow = { kind: 'item', key: `results/${viewAll.item.id}`, item: viewAll.item, section: 'results' }
const rows = results?.rows ?? []
return {
...(results ?? readySection('results', [])),
rows: viewAll.placement === 'lead' ? [row, ...rows] : [...rows, row],
}
}
const plainName = (item: SearchItem): string =>
String(item.displayName || item.name)
.toLowerCase()
.replace(/\s*\([^)]*\)\s*$/, '')
.trim()
export function rankableSettings(local: LocalLists, localQuery: string): SearchItem[] {
const productDestinations = new Set(
local.products.filter((item) => !item.parentName).map((item) => `${plainName(item)}|${item.href ?? ''}`)
)
return exactSettingsMatches(local.settings, localQuery).filter(
(item) => !productDestinations.has(`${plainName(item)}|${item.href ?? ''}`)
)
}
function rankedResultsSections(
results: SearchItem[],
query: string,
local: LocalLists,
localQuery: string,
state: CommandKSection['state'],
persons: SearchItem[],
accounts: SearchItem[],
themeItem: SearchItem | null,
expandedGroups: string[]
): CommandKSection[] {
const words = freeWords(query)
// The scorer splits words on underscores, so the settings it ranks are matched the same way.
const rankedSettingsQuery = localQuery.replace(/_/g, ' ')
const rankable = rankableSettings(local, rankedSettingsQuery)
// The scorer reads punctuation, so a domain or an email address keeps it.
const freeText = query.replace(FILTER_TOKEN, ' ').replace(/\s+/g, ' ').trim()
return buildRankedResults({
persons,
accounts,
settings: [...(themeItem ? [themeItem] : []), ...rankable],
unrankedSettings: exactSettingsMatches(local.settings, rankedSettingsQuery).filter(
(item) => !rankable.some((ranked) => ranked.id === item.id)
),
expandedGroups,
query: freeText,
highlightWords: words,
results,
products: localQuery ? local.products : [],
state,
scoped: (query.match(FILTER_TOKEN) ?? []).some((token) => token.trim().startsWith('type:')),
})
}
function lowerSections(
input: SectionsInput,
ranked: boolean,
state: CommandKSection['state'],
shown: Set<string>,
settingsRanked: boolean
): CommandKSection[] {
const { local, remote, remoteQueries, localQuery } = input
const sections: (CommandKSection | null)[] = []
const loaded = (): CommandKSection[] => sections.filter((section): section is CommandKSection => section !== null)
const loadingMore = (): CommandKSection[] =>
state === 'stale'
? loaded()
: [...loaded(), readySection('loading-more', [{ kind: 'loading-more', key: 'loading-more/row' }])]
const appendInOrder = (sources: RemoteSource[]): boolean => {
for (const source of sources) {
const query = remoteQueries[source]
if (!isSettled(remote[source], query)) {
return false
}
sections.push(
query
? remoteSection(
source,
remote[source].cache[query].filter((item) => !shown.has(item.id)),
state
)
: null
)
}
return true
}
if (localQuery) {
for (const source of LOCAL_SOURCES) {
const themeItem =
source === 'settings' && input.themeItem && !shown.has(input.themeItem.id) ? input.themeItem : null
if (ranked && (source === 'products' || (source === 'settings' && settingsRanked && !themeItem))) {
continue
}
const filtered =
ranked && source === 'settings' && settingsRanked
? []
: matchLocal(source, local[source], localQuery, ranked).filter((item) => !shown.has(item.id))
const rows = themeItem
? itemRows(source, [themeItem, ...filtered], SECONDARY_LIMIT + 1)
: itemRows(source, filtered, SECONDARY_LIMIT)
sections.push(rows.length > 0 ? { ...readySection(source, rows), state } : null)
}
}
if (!appendInOrder(REMOTE_SOURCES.filter((source) => source !== 'results' && !TRAILING_SOURCES.includes(source)))) {
return loadingMore()
}
const hasItems = shown.size > 0 || loaded().some((section) => section.rows.some((row) => row.kind === 'item'))
if (input.askAiQuestion && !hasItems) {
sections.push({
...readySection('ask-ai', [{ kind: 'ask-ai', key: 'ask-ai/ask', question: input.askAiQuestion }]),
state,
})
}
if (!appendInOrder(TRAILING_SOURCES)) {
return loadingMore()
}
const all = loaded()
return all.some((section) => section.key !== 'ask-ai' && section.rows.some((row) => row.kind === 'item'))
? all.filter((section) => section.key !== 'ask-ai')
: all
}
function withCorrectionNotice(sections: CommandKSection[], correction: SearchCorrection | null): CommandKSection[] {
if (!correction || !sections.some((section) => section.rows.some((row) => row.kind === 'item'))) {
return sections
}
const row: CommandKRow = {
kind: 'notice',
key: 'notice/corrected',
reason: 'corrected',
missing: [correction.from],
shown: [correction.to],
}
const notice = sections.find((section) => section.key === 'notice')
if (notice) {
return sections.map((section) => (section === notice ? { ...section, rows: [row, ...section.rows] } : section))
}
const index = sections.findIndex((section) => section.key !== 'filters' && section.key !== 'suggestions')
const at = index < 0 ? sections.length : index
return [...sections.slice(0, at), readySection('notice', [row]), ...sections.slice(at)]
}
export function buildSections(input: SectionsInput): CommandKSection[] {
return withCorrectionNotice(buildSectionsForQuery(input), input.searchCorrection)
}
function buildSectionsForQuery(input: SectionsInput): CommandKSection[] {
const { mode, context, local, remote, remoteQueries, localQuery } = input
if (mode === 'empty') {
return [
readySection('recents', itemRows('recents', local.recents, RECENTS_LIMIT)),
readySection('starred', itemRows('starred', local.starred)),
// Tab rows ("Dashboards / Templates") only appear for a search, as in the current palette.
readySection(
'products',
itemRows(
'products',
local.products.filter((item) => !item.parentName)
)
),
readySection('shortcuts', itemRows('shortcuts', local.shortcuts)),
].filter((section) => section.rows.length > 0)
}
const state: CommandKSection['state'] = input.stale ? 'stale' : 'ready'
const sections: (CommandKSection | null)[] = []
if (context.kind === 'key') {
sections.push(
readySection(
'filters',
context.matches.map((filter) => ({
kind: 'filter-key',
key: `filters/${context.negated ? '-' : ''}${filter.key}`,
filter,
negated: context.negated,
}))
)
)
}
sections.push(input.suggestions)
const resultsQuery = remoteQueries.results
const results = resultsQuery ? remote.results.cache[resultsQuery] : undefined
const ranked = isRanked(input)
const personsQuery = input.personsFirst && mode !== 'value' ? remoteQueries.persons : undefined
const accountsQuery = ranked && mode !== 'value' ? remoteQueries.accounts : undefined
if (
(resultsQuery && !results) ||
(personsQuery && !isSettled(remote.persons, personsQuery)) ||
(accountsQuery && !isSettled(remote.accounts, accountsQuery))
) {
sections.push(withViewAll(loadingSection('results'), input.viewAll))
return sections.filter((section): section is CommandKSection => section !== null)
}
const leadingPersons = personsQuery ? remote.persons.cache[personsQuery] : []
if (!ranked && leadingPersons.length) {
sections.push(remoteSection('persons', leadingPersons, state))
}
if (ranked && results && resultsQuery) {
const rankedSections = rankedResultsSections(
results,
resultsQuery,
local,
localQuery,
state,
leadingPersons,
accountsQuery ? remote.accounts.cache[accountsQuery] : [],
input.themeItem,
input.expandedGroups ?? []
)
sections.push(
...(rankedSections.some((section) => section.key === 'results')
? rankedSections.map((section) =>
section.key === 'results' ? withViewAll(section, input.viewAll) : section
)
: [...rankedSections, withViewAll(null, input.viewAll)])
)
} else {
sections.push(withViewAll(results ? remoteSection('results', results, state) : null, input.viewAll))
}
if (mode !== 'value') {
const themeItem = input.themeItem
const settingsGroupIndex = sections.findIndex((section) => section?.key === 'group-settings')
const settingsGroup = sections[settingsGroupIndex]
if (
ranked &&
themeItem &&
settingsGroup &&
!sections.some((section) =>
section?.rows.some((row) => row.kind === 'item' && row.item.id === themeItem.id)
)
) {
sections[settingsGroupIndex] = {
...settingsGroup,
rows: [
{
kind: 'item',
key: `group-settings/${themeItem.id}`,
item: themeItem,
section: 'settings',
ranked: true,
highlightWords: freeWords(localQuery),
},
...settingsGroup.rows,
],
}
}
const shown = new Set(
sections.flatMap(
(section) => section?.rows.flatMap((row) => (row.kind === 'item' ? [row.item.id] : [])) ?? []
)
)
const settingsRanked = sections.some(
(section) => section?.rows.some((row) => row.kind === 'item' && row.item.category === 'settings') ?? false
)
sections.push(...lowerSections(input, ranked, state, shown, settingsRanked))
}
return sections.filter((section): section is CommandKSection => section !== null)
}
const THEME_QUERY_WORDS = ['dark', 'light', 'theme', 'appearance']
/**
* A settings row that switches the theme straight from search. "dark" or "light" sets that mode;
* "theme" or "appearance" toggles away from the current one.
*/
export function themeSearchItem(
query: string,
isDarkModeOn: boolean,
{ setTheme, toggleTheme }: { setTheme: (mode: 'dark' | 'light') => void; toggleTheme: () => void }
): SearchItem | null {
const normalized = query.trim().toLowerCase()
if (!normalized || !THEME_QUERY_WORDS.some((word) => normalized.includes(word))) {
return null
}
const requested = normalized.includes('dark') ? 'dark' : normalized.includes('light') ? 'light' : null
const target = requested ?? (isDarkModeOn ? 'light' : 'dark')
const name = target === 'dark' ? 'Dark mode' : 'Light mode'
return {
id: SETTINGS_THEME_ITEM_ID,
name,
displayName: name,
category: 'settings',
itemType: 'settings',
searchKeywords: THEME_QUERY_WORDS,
onSelect: requested ? () => setTheme(requested) : toggleTheme,
record: { type: 'settings', ref: 'theme' },
}
}