feat(core): allow passing explicit refs via props

packages/reactivity/__tests__/readonly.spec.ts

@@ -9,7 +9,8 @@ import {
   lock,
   unlock,
   effect,
-  ref
+  ref,
+  readonlyProps
 } from '../src'
 import { mockWarn } from '@vue/runtime-test'
 
@@ -442,4 +443,32 @@ describe('reactivity/readonly', () => {
       `Set operation on key "value" failed: target is readonly.`
     ).toHaveBeenWarned()
   })
+
+  describe('readonlyProps', () => {
+    test('should not unwrap root-level refs', () => {
+      const props = readonlyProps({ n: ref(1) })
+      expect(props.n.value).toBe(1)
+    })
+
+    test('should unwrap nested refs', () => {
+      const props = readonlyProps({ foo: { bar: ref(1) } })
+      expect(props.foo.bar).toBe(1)
+    })
+
+    test('should make properties readonly', () => {
+      const props = readonlyProps({ n: ref(1) })
+      props.n.value = 2
+      expect(props.n.value).toBe(1)
+      expect(
+        `Set operation on key "value" failed: target is readonly.`
+      ).toHaveBeenWarned()
+
+      // @ts-ignore
+      props.n = 2
+      expect(props.n.value).toBe(1)
+      expect(
+        `Set operation on key "n" failed: target is readonly.`
+      ).toHaveBeenWarned()
+    })
+  })
 })

packages/reactivity/src/baseHandlers.ts

@@ -11,16 +11,17 @@ const builtInSymbols = new Set(
     .filter(isSymbol)
 )
 
-function createGetter(isReadonly: boolean) {
+function createGetter(isReadonly: boolean, unwrap: boolean = true) {
   return function get(target: object, key: string | symbol, receiver: object) {
-    const res = Reflect.get(target, key, receiver)
+    let res = Reflect.get(target, key, receiver)
     if (isSymbol(key) && builtInSymbols.has(key)) {
       return res
     }
-    if (isRef(res)) {
-      return res.value
+    if (unwrap && isRef(res)) {
+      res = res.value
+    } else {
+      track(target, OperationTypes.GET, key)
     }
-    track(target, OperationTypes.GET, key)
     return isObject(res)
       ? isReadonly
         ? // need to lazy access readonly and reactive here to avoid
@@ -141,3 +142,11 @@ export const readonlyHandlers: ProxyHandler<object> = {
   has,
   ownKeys
 }
+
+// props handlers are special in the sense that it should not unwrap top-level
+// refs (in order to allow refs to be explicitly passed down), but should
+// retain the reactivity of the normal readonly object.
+export const readonlyPropsHandlers: ProxyHandler<object> = {
+  ...readonlyHandlers,
+  get: createGetter(true, false)
+}

packages/reactivity/src/index.ts

@@ -4,6 +4,7 @@ export {
   isReactive,
   readonly,
   isReadonly,
+  readonlyProps,
   toRaw,
   markReadonly,
   markNonReactive

packages/reactivity/src/reactive.ts

@@ -1,5 +1,9 @@
 import { isObject, toRawType } from '@vue/shared'
-import { mutableHandlers, readonlyHandlers } from './baseHandlers'
+import {
+  mutableHandlers,
+  readonlyHandlers,
+  readonlyPropsHandlers
+} from './baseHandlers'
 import {
   mutableCollectionHandlers,
   readonlyCollectionHandlers
@@ -80,6 +84,23 @@ export function readonly<T extends object>(
   )
 }
 
+// @internal
+// Return a readonly-copy of a props object, without unwrapping refs at the root
+// level. This is intended to allow explicitly passing refs as props.
+// Technically this should use different global cache from readonly(), but
+// since it is only used on internal objects so it's not really necessary.
+export function readonlyProps<T extends object>(
+  target: T
+): Readonly<{ [K in keyof T]: UnwrapNestedRefs<T[K]> }> {
+  return createReactiveObject(
+    target,
+    rawToReadonly,
+    readonlyToRaw,
+    readonlyPropsHandlers,
+    readonlyCollectionHandlers
+  )
+}
+
 function createReactiveObject(
   target: unknown,
   toProxy: WeakMap<any, any>,