feat(customElement): support attachInternals method

[edison1105]

close #10948

Summary by CodeRabbit

• New Features
  • Added useHostInternals() API to access host element internals within custom element components.
  • Introduced support for form-associated custom elements via formAssociated configuration.
  • Enhanced custom element support with ElementInternals integration for improved form control capabilities.

[github-actions[bot]]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	103 kB (+185 B)	39 kB (+62 B)	35 kB (+28 B)
vue.global.prod.js	161 kB (+185 B)	58.9 kB (+53 B)	52.4 kB (+79 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	46.9 kB	18.3 kB	16.8 kB
createApp	55 kB	21.4 kB	19.6 kB
createSSRApp	59.3 kB	23.1 kB	21.1 kB
defineCustomElement	60.8 kB (+120 B)	23.2 kB (+43 B)	21.1 kB (+38 B)
overall	69.3 kB	26.6 kB	24.3 kB

[pkg-pr-new[bot]]

Open in StackBlitz

@vue/compiler-core

npm i https://pkg.pr.new/@vue/compiler-core@12129

@vue/compiler-dom

npm i https://pkg.pr.new/@vue/compiler-dom@12129

@vue/compiler-sfc

npm i https://pkg.pr.new/@vue/compiler-sfc@12129

@vue/compiler-ssr

npm i https://pkg.pr.new/@vue/compiler-ssr@12129

@vue/reactivity

npm i https://pkg.pr.new/@vue/reactivity@12129

@vue/runtime-core

npm i https://pkg.pr.new/@vue/runtime-core@12129

@vue/runtime-dom

npm i https://pkg.pr.new/@vue/runtime-dom@12129

@vue/server-renderer

npm i https://pkg.pr.new/@vue/server-renderer@12129

@vue/shared

npm i https://pkg.pr.new/@vue/shared@12129

vue

npm i https://pkg.pr.new/vue@12129

@vue/compat

npm i https://pkg.pr.new/@vue/compat@12129

commit: 730f088

[lejunyang]

Should we also create a new API like useHostInternals()? As _internal seems to be a private field

[dkniffin]

What's the status of this? I'm starting a component library with vue and I'd like to be able to create elements that can associate with forms, but this seems to be the blocking point.

[coderabbitai[bot]]

Walkthrough

The changes introduce support for form-associated custom elements in Vue's defineCustomElement API. A new useHostInternals() hook allows accessing ElementInternals from component setup functions, a static formAssociated property enables form association declaration, and _internals is initialized during custom element construction.

Changes

Cohort / File(s)	Summary
Public API and Core Implementation packages/runtime-dom/src/apiCustomElement.ts, packages/runtime-dom/src/index.ts	Added static formAssociated property to VueCustomElement for form-association declaration; added _internals property to VueElement initialized via attachInternals() in constructor; introduced new useHostInternals() export function to access internals from setup context; re-exported useHostInternals from public API.
Test Coverage packages/runtime-dom/__tests__/customElement.spec.ts	Added test scaffolding and validations for useHostInternals() API; added test verifying attachInternals method presence on custom element instances.

Sequence Diagram(s)

sequenceDiagram
    participant DefineCustomElement as defineCustomElement()
    participant VueElement as VueElement Constructor
    participant Internals as ElementInternals
    participant Setup as Component Setup()
    participant Hook as useHostInternals()
    
    DefineCustomElement->>VueElement: create instance (formAssociated declared)
    VueElement->>Internals: call attachInternals()
    Internals-->>VueElement: returns ElementInternals instance
    VueElement->>VueElement: store in _internals
    VueElement-->>DefineCustomElement: element ready
    
    Setup->>Hook: access internals from setup
    Hook->>Hook: useHost() to get current element
    Hook-->>Setup: return element._internals
    Setup->>Internals: use (e.g., set form state)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~18 minutes

• Core implementation spans multiple files with consistent patterns (property additions, initialization logic)
• New public API surface requires validation of export correctness and hook implementation
• Constructor initialization logic should be verified for proper ElementInternals lifecycle handling
• Test coverage validates expected behavior but is relatively straightforward

Suggested labels

:sparkles: feature request

Poem

🐰 A bunny's wish fulfilled at last! Forms now bind to elements fast, With internals tucked away so tight, Custom elements shine so bright! The hook lets setup reach within, Where form-associated hearts spin! ✨

Pre-merge checks and finishing touches

✅ 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 accurately describes the main feature addition: support for the attachInternals method in custom elements, which directly addresses the linked issue.
Linked Issues check	✅ Passed	The PR implements the necessary infrastructure to support form-associated custom elements: static formAssociated property, ElementInternals initialization via attachInternals, and the useHostInternals() API for accessing internals within components.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing attachInternals support for custom elements. No unrelated modifications or scope creep detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch edison/feat/ce_attachInternals

---

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