feat(types): provide internal options for using refs type in language tools (#11492)

Author: jh-leong

packages/dts-test/defineComponent.test-d.tsx

@@ -1593,6 +1593,7 @@ describe('expose typing', () => {
 import type {
   AllowedComponentProps,
   ComponentCustomProps,
+  ComponentInstance,
   ComponentOptionsMixin,
   DefineComponent,
   Directive,
@@ -1756,6 +1757,24 @@ describe('__typeEmits backdoor, call signature syntax', () => {
   c.$emit('update', 123)
 })
 
+describe('__typeRefs backdoor, object syntax', () => {
+  type Refs = {
+    foo: number
+  }
+
+  const Parent = defineComponent({
+    __typeRefs: {} as { child: ComponentInstance<typeof Child> },
+  })
+  const Child = defineComponent({
+    __typeRefs: {} as Refs,
+  })
+  const c = new Parent()
+  const refs = c.$refs
+
+  expectType<ComponentInstance<typeof Child>>(refs.child)
+  expectType<number>(refs.child.$refs.foo)
+})
+
 defineComponent({
   props: {
     foo: [String, null],

packages/runtime-core/src/apiDefineComponent.ts

@@ -67,6 +67,7 @@ export type DefineComponent<
   Exposed extends string = string,
   Provide extends ComponentProvideOptions = ComponentProvideOptions,
   MakeDefaultsOptional extends boolean = true,
+  TypeRefs extends Record<string, unknown> = {},
 > = ComponentPublicInstanceConstructor<
   CreateComponentPublicInstanceWithMixins<
     Props,
@@ -84,7 +85,8 @@ export type DefineComponent<
     S,
     LC & GlobalComponents,
     Directives & GlobalDirectives,
-    Exposed
+    Exposed,
+    TypeRefs
   >
 > &
   ComponentOptionsBase<
@@ -209,6 +211,7 @@ export function defineComponent<
       : { [key in RuntimePropsKeys]?: any }
     : TypeProps,
   ResolvedProps = Readonly<InferredProps & EmitsToProps<ResolvedEmits>>,
+  TypeRefs extends Record<string, unknown> = {},
 >(
   options: {
     props?: (RuntimePropsOptions & ThisType<void>) | RuntimePropsKeys[]
@@ -220,6 +223,10 @@ export function defineComponent<
      * @private for language-tools use only
      */
     __typeEmits?: TypeEmits
+    /**
+     * @private for language-tools use only
+     */
+    __typeRefs?: TypeRefs
   } & ComponentOptionsBase<
     ResolvedProps,
     SetupBindings,
@@ -279,7 +286,8 @@ export function defineComponent<
   Provide,
   // MakeDefaultsOptional - if TypeProps is provided, set to false to use
   // user props types verbatim
-  unknown extends TypeProps ? true : false
+  unknown extends TypeProps ? true : false,
+  TypeRefs
 >
 
 // implementation, close to no-op

packages/runtime-core/src/componentPublicInstance.ts

@@ -232,6 +232,7 @@ export type CreateComponentPublicInstanceWithMixins<
   LC extends Record<string, Component> = {},
   Directives extends Record<string, Directive> = {},
   Exposed extends string = string,
+  TypeRefs extends Data = {},
   Provide extends ComponentProvideOptions = ComponentProvideOptions,
   // mixin inference
   PublicMixin = IntersectionMixin<Mixin> & IntersectionMixin<Extends>,
@@ -275,7 +276,8 @@ export type CreateComponentPublicInstanceWithMixins<
   >,
   I,
   S,
-  Exposed
+  Exposed,
+  TypeRefs
 >
 
 export type ExposedKeys<
@@ -299,14 +301,15 @@ export type ComponentPublicInstance<
   I extends ComponentInjectOptions = {},
   S extends SlotsType = {},
   Exposed extends string = '',
+  TypeRefs extends Data = {},
 > = {
   $: ComponentInternalInstance
   $data: D
   $props: MakeDefaultsOptional extends true
     ? Partial<Defaults> & Omit<Prettify<P> & PublicProps, keyof Defaults>
     : Prettify<P> & PublicProps
   $attrs: Data
-  $refs: Data
+  $refs: Data & TypeRefs
   $slots: UnwrapSlotsType<S>
   $root: ComponentPublicInstance | null
   $parent: ComponentPublicInstance | null