API to prevent refs from being unwrapped

[jfet97]

What problem does this feature solve?

Not unwrappable refs will be able to passed as values to custom directives without loosing their essence

I was building a custom directive that needs a ref as a value, to then perform some changes to that ref in response to some events.
I was just experimenting, nothing too serious, but unfortunately I later realized that the automatic refs unwrapping when a ref is used inside a template will always prevents the creation of this kind of directives.

We are forced to use reactive to create a sort of notUnwrappableRef and for consistency we end up creating a reactive object with only one reactive property: value.

What does the proposed API look like?

Something like the following, but standardized for every user

import { reactive } from "vue"

export function notUnwrappableRef(value) {
    return reactive({ value })
}

[posva]

This should be relevant for you: vuejs/core#1682 (comment)
it explains some upcoming changes and why the unwrapping exists

You didn't explain what use case makes you need a Ref inside the directive

[jfet97]

@posva
Passing a ref to a directive let the directive's hooks change the ref value.

I was trying to create a stream like directive (https://github.com/vuejs/vue-rx/blob/master/src/directives/stream.js) using refs instead of observables. I'm not saying that this example is a good way to do things, but it shows that the union of refs and directives could allow interesting stuff.

[yyx990803]

Maybe we can make markRaw also prevent refs from being unwrapped?

[jfet97]

@yyx990803
It could be an idea, even if, sincerely, I do not associate the term raw with this characteristic.
On the other hand, I understand that "something that is not automatically unwrapped by Vue" is not easy to put inside a word or two.

makeExplicit?

[Bond-Addict]

I would like to add support for this feature. I'm utilizing a library that expects a ref. The way you normally use it is on the actual component itself, but I would like to have the ref come from a parent and then use the function in the child. I cannot accomplish this because the ref is automatically unwrapped which causes value to be undefined which is the property that the library acts on.
Below is an example of how the library expects the code to be:

<template>
    <va-form ref="form"></va-form>
</template>

<script setup lang="ts">
const form = ref()

const { validate } = useForm(form)

validate()
</script>

[KonnorRogers]

I have a similar use case to @Bond-Addict .

I maintain a web component based component system and was trying to make a package for using something like v-model.

I came up with the following, but it would be significantly less annoying if I didn't need to have users make a second function so I can get access to the raw ref.

export default function (options = {}) {
  if (!options) { options = {} }

  if (!options.events) {
    options.events = ["input", "change"]
  }

  if (!options.eventHandler) {
    options.eventHandler = function (el, binding, vnode) {
      return (event) => {
        const model = binding.value
        model.value = event.target.value
      }
    };
  }

  const { events, eventHandler } = options

  return {
    name: 'vue-wa-model',
    install: (app, options) => {
      const wm = new WeakMap();

      app.directive("wa-model", {
        beforeMount(el, binding, vnode) {
          const inputHandler = eventHandler(el, binding, vnode)
          wm.set(el, inputHandler);

          const modelValue = binding.value.value
          el.value = modelValue ?? null;
          el.defaultValue = modelValue ?? null;

          events.forEach((eventName) => {
            el.addEventListener(eventName, inputHandler);
          });
        },

        updated(el, binding) {
          el.value = binding.value.value ?? null;
        },

        unmounted(el, _binding) {
          const inputHandler = wm.get(el);
          events.forEach((eventName) => {
            el.removeEventListener(eventName, inputHandler);
          });
          wm.delete(el);
        },
      });
    },
  }
};

And then here's the "hack" to pass the ref:

<script setup>
  const model = defineModel({ default: "value" })

  // We need to prevent unwrapping of refs when passing to `v-wa-model`
  const waModel = () => model

  function update() {
    model.value += "a"
  }
</script>

<template>
  <div class="outline wa-stack">
    <h2>Options Test</h2>
    <wa-input v-wa-model="waModel()"></wa-input>
    <wa-input v-wa-model="waModel()" readonly></wa-input>
    <div>Value: {{ model }}</div>
    <button @click="update">Add "a"</button>
  </div>
</template>

I may just be holding it wrong, and this may be unrelated, but it would be really nice to pass a directive as a ref rather than always unwrapping it.

[8ctavio]

It is also my impression that template ref auto-unwrapping should be at least optional. I partly wrote about this in other discussion, but I'll outline the overall rationale here.

First, my argument against auto-unwrapping is best summarized in the following statement:

[It seems that directly forwarding] ref objects is a fundamental feature of the Composition API, but this is not possible through props in SFC templates because refs are automatically unwrapped [...] Directly passing ref objects as props to components would be useful in the same way directly passing refs as arguments to composables is useful.

I think the fundamental problem others encountered is that they tried to use the (I'd say, recommended and standard) Composition API pattern in SFC templates, namely, passing ref objects around just like with composables, but failed because of auto-unwrapping. Handling refs in SFC templates tends to be rather different than in other places. Then, two benefits of not auto-unwrapping refs are:

• Consistency: Ref notation becomes consistent between SFC templates and script/composables, and
• Explicitness: Ref behavior in SFC templates becomes more predictable and explicit.

The reasons why the Reactivity Transform was dropped seem to partly support these benefits:

Losing .value makes it harder to tell what is being tracked and which line is triggering a reactive effect. [1]

Currently, a compiled SFC's setupState is simply wrapped with proxyRefs. Perhaps it would be possible to mark SFC setups to opt-out of auto-unwrapping if configured as such; and this could also be first introduced as experimental.

In addition, to further preserve compatibility refs could implement a Symbol.toPrimitive method that simply unwraps them, which would allow omitting .value in common places such as template text interpolation. However, unlike template unwrapping, this would work everywhere. Then, simple arithmetic operations, or string concatenation would work without .value:

const num = ref(1)
console.log(num + 1) // 2

const str = ref('foo')
console.log(`${str} bar`) // foo bar

---

v-model and shallowRef

I have found ref auto-unwrapping particularly limiting for implementing shallowRef support in (form) components whose model values are arrays: Since the received model prop is not the actual ref object, there is no simple or convenient way to notify the consumer about changes made to the model value.

In one project, I chose to create an extendedRef ref-alternative that wraps ref objects so that their "identity" becomes "hidden", rendering ref-unwrapping proxies unable to unwrap them (for more details, see Difference with ref).

Additional context

• Template direct field access core#1227 (comment)