PowerSearch typeahead: label-only matching vs key — intentional?

[nynexman4464]

Observation

usePowerSearchSource matches user typeahead queries against field.label and (via consumer-supplied) field.typeaheadAliases, not against field.key. Same for operators — matched by op.label, never by op.key.

Concretely, in packages/core/src/PowerSearch/usePowerSearchSource.ts:

const fieldMatches =
  field.label.toLowerCase().includes(lower) ||
  field.typeaheadAliases?.some(alias =>
    alias.toLowerCase().includes(lower),
  );

The intuition, and the uncertainty

Intuition: key is the source of truth (stable identifier, consumer-chosen, doesn't change with locale) and label is derived (display string, potentially translated). It's a little surprising that search compares against the derived string only.

But typeaheadAliases already exists as a hook for "additional strings that should match this field." I don't know the history here — maybe that's the intended escape hatch, and consumers who want key-based matching are expected to put their key in there. Or maybe typeaheadAliases was designed for something entirely different (synonyms, user-friendly shortcuts, etc.).

Rather than propose a fix, I wanted to raise the shape here and see if anyone with context can chime in on whether this is intentional, what typeaheadAliases was actually designed for, and whether there's a real gap or not.

Surfaced during the PowerSearch i18n migration follow-up to #3765. The i18n work itself doesn't depend on this — flagging it separately.

[cixzhang]

I think assumption here is that key is not user facing so perhaps end users might not know what the key is but the builder might know and use it for identification. We could attempt to match both key and label but it's unclear whether callsites would have key as something relatively human readable like we have internally. Perhaps matching just label with aliases is sufficient for now since there's not an easy way to exclude key from matching if we decide to add it.

I'm definitely curious how people are treating these externally though.