fix(types): allow narrower HTMLElement types in function refs

[7inspire]

Problem

Fixes #13969.

VNodeRef function refs are currently typed with a callback parameter of:

Element | ComponentPublicInstance | null

Under TypeScript function parameter variance, this rejects callbacks that use a narrower DOM type, e.g.:

<form ref={(el: HTMLFormElement | null) => {}} />
This is unintuitive for function refs on concrete elements and causes unnecessary type errors.

Solution
Adjust VNodeRef callback typing in runtime-core to use the standard bivariant callback pattern (bivarianceHack), so narrower element parameter types are accepted where appropriate.

This is a type-only change and does not affect runtime behavior.

Tests
Added a dts regression case:

tsx.test-d.tsx
verifies <form ref={(el: HTMLFormElement | null) => {}} /> type-checks
Validation run locally:

pnpm build-dts
pnpm test-dts-only
Both passed.

Scope / Risk
Minimal, focused change (2 files)
Type-level only
No runtime logic changes

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

## Release Notes

* **Tests**
  * Added test assertion verifying form element ref callback support.

* **Refactor**
  * Improved TypeScript type handling for ref callbacks to support narrower element types.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 26a17319-5595-4be5-8894-05ecf12c4ff7

📥 Commits

Reviewing files that changed from the base of the PR and between e725a67 and 123d928.

📒 Files selected for processing (2)

• packages-private/dts-test/tsx.test-d.tsx
• packages/runtime-core/src/vnode.ts

---

📝 Walkthrough

Walkthrough

This PR fixes TypeScript type checking for function refs by introducing a bivarianceHack pattern to the VNodeRef type, allowing refs to accept specific element types like HTMLFormElement instead of just the generic Element type. A test assertion verifies the fix works correctly.

Changes

Cohort / File(s)	Summary
Test Assertion packages-private/dts-test/tsx.test-d.tsx	Adds test assertion validating that a form element can accept a ref callback with type HTMLFormElement | null.
VNodeRef Type Definition packages/runtime-core/src/vnode.ts	Updates VNodeRef type to support bivariance for function refs by replacing direct function union with a bivarianceHack object pattern, enabling narrower element types like HTMLFormElement to be accepted while maintaining compatibility.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

ready to merge, scope: types

Poem

🐰 A bivarianceHack so clever and fine,
Makes function refs work with types so divine,
HTMLFormElement now finds its place,
TypeScript errors vanish without a trace!
The ref now accepts what it's meant to be,
Specific and true, wild and free! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(types): allow narrower HTMLElement types in function refs' is a concise and clear description of the main change—adjusting TypeScript typings for VNodeRef to accept narrower element types in function refs.
Linked Issues check	✅ Passed	The pull request fully addresses issue #13969 by implementing the bivarianceHack pattern to allow function refs with narrower HTMLElement types, and includes a test case verifying this behavior.
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objective: VNodeRef type refinement and a regression test case. No unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}