docs(PowerSearch): define readable popover placement

[cixzhang]

Why

PowerSearch editor popovers currently stretch to the outer search width, which makes the small field/operator/value task harder to scan on wide filter bars. The editor also needs to stay near the exact control that opened it without adding callsite positioning API.

What

Records the accepted, current PowerSearch contract:

• the editor prefers the outer PowerSearch width clamped to 400–720 CSS px; viewport collision remains authoritative
• full-width and floor-expanded editors stay aligned to the outer PowerSearch
• only a 720-capped editor chooses the nearer outer edge from the stable opening control: the inner input for add, or the activated token/control for edit; pointer and keyboard use the same control geometry
• placement reads geometry once at open, commits while hidden, shows next frame, and stays latched until close
• no public width, max-width, input-ref, or positioning prop is added; existing menuWidth remains the exact pixel width for the main field menu only

The contract depends on the current component:Tokenizer/DEC-1 authority landed by #5810 for the package-internal stable opening-control descriptor and safe fallback semantics.

Status

The contract is accepted and current (approved_by: cixzhang, approved_at: 2026-08-31), but this is not shipped behavior. Implementation remains pending, including real-Chromium story evidence for the 400/720 boundaries, start/end/tie controls, pointer and keyboard activation, LTR/RTL, narrow-viewport collision, opposite-side reopen, and no first-frame flash.

Risk

Documentation only. No runtime or public API changes. No Changeset.

Testing

• pnpm check:knowledge
• pnpm check:repo
• pnpm exec prettier --check packages/core/src/PowerSearch/PowerSearch.spec.md
• pnpm exec vitest run packages/core/src/PowerSearch/PowerSearch.test.tsx packages/core/src/PowerSearch/PowerSearchEditPopover.test.tsx packages/core/src/Tokenizer/Tokenizer.test.tsx packages/core/src/Typeahead/Typeahead.test.tsx (170 tests)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 1, 2026 1:54pm UTC

[cixzhang]

/approve-spec 4784728