feat(popover): add composable Base UI parts

[mattrothenberg]

Summary

• add Popover.Root, Portal, Backdrop, Positioner, Popup, Arrow, and Viewport so Kumo mirrors Base UI's composition API
• keep Popover.Content as a deprecated, backwards-compatible wrapper with the opacity-only transition shipped in fix(popover): follow Base UI popup composition #817
• restore scale and opacity animation on the canonical Popover.Popup, using Base UI's positioned transform origin
• update every Popover demo and the API documentation, including deprecated fade-only compatibility, canonical inner scrolling, and --available-height popup sizing examples

Why

#817 safely removed scaling from Popover.Content because downstream callers put overflow directly on that element. This follow-up makes the Base UI structure available without breaking those callers: new code can use the canonical parts and scale animation, while existing Content usages keep their safe fade-only behavior until they migrate.

Validation

• pnpm --filter @cloudflare/kumo lint

• pnpm --filter @cloudflare/kumo typecheck

• focused Popover browser tests: 2/2 passing

• pnpm --filter @cloudflare/kumo build

• pnpm --filter @cloudflare/kumo-docs-astro typecheck

• local docs verification at /components/popover/

• Reviews

• bonk has reviewed the change

• automated review not possible because: review runs after the PR is opened

• Tests

• Tests included/updated

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

• Additional testing not necessary because:

[github-actions]

Visual contracts

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

1 curated contract

truncating text trigger

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

Posted 2 inline findings with suggestions.

Review notes

• Confirming the target is PR feat(popover): add composable Base UI parts #818 and inspecting its changed files, package guidance, prior reviews, and the complete diff before evaluating behavior.
• PR metadata confirms the requested target: cloudflare/kumo PR feat(popover): add composable Base UI parts #818 at head 8c65c11719bb293d139d1bb3befeee67a664969d; no prior reviews exist. Repository guidance for both affected packages has been read. The local checkout lacks the referenced base commit, so I am retrieving the PR diff from GitHub and comparing it with the checked-out sources.
• The complete one-commit diff was inspected and passes git diff --check. The checkout is at the PR head. The requested package validation could not be run because pnpm is unavailable in the action environment; I am continuing with static API and compatibility analysis against the installed source.
• Static API checks against Base UI 1.8 confirm that the newly exposed Popup and Arrow accept state-based className callbacks. Their wrappers pass those callbacks to cnfast, whose declared inputs exclude functions, so the callbacks are neither type-safe nor preserved. I will post two inline suggestions, one for each independently exposed component.
• The live PR head changed during review from the execution-context SHA to 69ca46ab9ab524469d5e38c306538b618e5af79d. No review was submitted against the stale checkout. I am rechecking the current remote diff and affected implementation before deciding whether the findings still apply.
• The current PR diff was rechecked at 69ca46ab9ab524469d5e38c306538b618e5af79d; the two implementation findings still apply. A single COMMENT review with two inline suggestions was published successfully.

github run

[pkg-pr-new]

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

commit: 72cc3cf

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://codex-base-ui-popover-parts-kumo-docs.design-engineering.workers.dev (commit 72cc3cf)

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://ad97e030-kumo-docs.design-engineering.workers.dev	72cc3cf	2026-09-21T22:34:20.786Z	Visit the dashboard ↗
Build: In progress 🔵 View logs ↗		71f81fd	2026-09-21T22:23:22.829Z	View logs ↗

[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.8 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.96 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: 72cc3cfd