fix(popover): follow Base UI popup composition

[mattrothenberg]

Summary

• preserve Base UI's canonical Positioner → Popup → Arrow structure
• use an opacity-only popup transition so scaling does not change the arrow's containing block during animation
• preserve existing callers that apply overflow-auto or overflow-hidden directly to Popover.Content
• add a browser regression test covering a scrolling Popover.Content while the opening transition is active

This is a compatibility-safe alternative to #814. Keep #814 open until this replacement is manually verified; once verified, this PR can supersede it.

Why opacity only

Some existing consumers use Popover.Content as their scroll container. A scale transform temporarily makes the popup the arrow's containing block, allowing popup overflow to clip the arrow during the transition. Opacity does not change containing-block behavior, so the arrow remains visible without changing existing consumer markup.

A future breaking migration can introduce a dedicated nested scroll viewport and then restore scale animation.

Validation

• pnpm --filter @cloudflare/kumo test:browser --run src/components/popover/popover.visual.browser.test.tsx

• pnpm --filter @cloudflare/kumo lint

• pnpm --filter @cloudflare/kumo typecheck

• pnpm --filter @cloudflare/kumo test --run (1,190 passed, 208 skipped)

• git diff --check

• Reviews

• bonk has reviewed the change

• automated review not possible because: compatibility behavior requires validation in a real browser

• Tests

• Tests included/updated

• Automated tests not possible - manual testing has been completed as follows: not applicable

• Additional testing not necessary because: not applicable

[ask-bonk]

LGTM!

Review notes

• Confirmed the review target is PR fix(popover): follow Base UI popup composition #817, fix(popover): follow Base UI popup composition. I will inspect the component guidance, complete diff, surrounding implementation, existing reviews, and focused test coverage before determining whether inline feedback is warranted.
• The PR head SHA matches the requested target and there are no prior reviews or review comments to avoid duplicating. The complete diff changes the popup to a relative containing block, adds usage guidance, a patch changeset, and one browser test; git diff --check reports no whitespace errors.
• I inspected the full Popover implementation and its documented usages. The change preserves Base UI’s Positioner → Popup → Arrow hierarchy; existing first-party Popover.Content call sites do not put overflow on the popup, and the new test places scrolling on a nested element as intended. The local environment lacks pnpm, so the browser test cannot be executed here.
• Base UI v1.8 documentation and source confirm the exact popup composition used here, with the arrow as a direct popup child and transition state applied to that popup. I also verified the browser-test configuration includes this new file and uses Chromium; no actionable behavior, accessibility, or compatibility regression was identified from the changed code.

github run

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@817

commit: 7733a9a

[github-actions]

📐 Bundle Size

Consumer fixtures bundled against packages/kumo/dist (peers external, minified ESM).

Fixture	Raw	Gzip	Brotli
Button (root)	174.6 KB	49.9 KB	43.1 KB
Button (components/button)	174.5 KB	49.9 KB	43.1 KB
Button + Dialog + Select (root)	299.5 KB	85.8 KB	71.9 KB
Button + Dialog + Select (component subpaths)	299.5 KB	85.9 KB	71.9 KB
Chart (root)	247.1 KB	71.1 KB	60.8 KB
Chart (components/chart)	247.0 KB	71.1 KB	60.8 KB
Badge (components/badge)	44.7 KB	11.7 KB	10.1 KB
Flow (components/flow)	208.9 KB	58.3 KB	50.5 KB
Button (primitives/button)	12.2 KB	4.4 KB	3.9 KB
Primitives barrel	635.8 KB	176.9 KB	139.3 KB
Code highlighting (code)	2.08 MB	468.0 KB	349.3 KB

npm tarball: 544 files, 1.49 MB packed, 6.95 MB unpacked.

⚠️ 23 flagged files in tarball (tests / raw scripts)

• dist/blocks-source/resource-list/resource-list.test.tsx
• scripts/component-registry/cache.ts
• scripts/component-registry/discovery.ts
• scripts/component-registry/example-cleanup.ts
• scripts/component-registry/index.test.ts
• scripts/component-registry/index.ts
• scripts/component-registry/markdown-generator.ts
• scripts/component-registry/metadata.ts
• scripts/component-registry/props-filter.ts
• scripts/component-registry/schema-generator.ts
• scripts/component-registry/sub-components.ts
• scripts/component-registry/types.ts
• scripts/component-registry/utils.ts
• scripts/component-registry/variant-parser.ts
• scripts/css-build.ts
• scripts/generate-globe-land-mask.mjs
• scripts/generate-primitives.ts
• scripts/theme-generator/config.ts
• scripts/theme-generator/generate-css.test.ts
• scripts/theme-generator/generate-css.ts
• scripts/theme-generator/index.ts
• scripts/theme-generator/migrate.ts
• scripts/theme-generator/types.ts

Report-only: no size thresholds are enforced yet.

Commit: 7733a9a6

[github-actions]

Visual contracts

Linux Chromium references exercised by the PR's visual-contracts job.

1 curated contract

truncating text trigger

[github-actions]

Visual Regression Report — 0 changed, 8 unchanged

No visual changes detected.

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://codex-fix-popover-arrow-overflow-kumo-docs.design-engineering.workers.dev (commit 7733a9a)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://f30aa8a2-kumo-docs.design-engineering.workers.dev	7733a9a	2026-09-21T13:22:07.977Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://4a6df8db-kumo-docs.design-engineering.workers.dev	f72577a	2026-09-21T12:55:41.048Z	Visit the dashboard ↗