Implicit parent-child communication is misleading

[mgibas]

Documentations states that this:

app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  template: '<input v-model="todo.text">'
})

should be converted to this:

app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  template: `
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})

Assuming it has same functional goal this is not true - if parent of this component will pass todo through ie v-model then input event will override passed todo model with a string ($event.target.value). If parent is not using v-model but simply :todo="todo" then how would it know that $emit('input', $event.target.value) corresponds to text property of provided model ?

[skirtles-code]

For anyone else reading this, the section of the documentation being referenced by this issue can be found at https://v3.vuejs.org/style-guide/#implicit-parent-child-communication-use-with-caution

[NataliaTepluhina]

@mgibas we were not showing a parent component in examples and it was assumed that the parent component should be listening to input event to make proper changes to todo.text. I would not call the example not true, rather not full.

I am not sure whether we should expand shown examples to make them more clear 🤔

[mgibas]

@NataliaTepluhina so in discussed example parent binds whole object but expects updates on a single property ?
I can understand that this is not a full example but can’t find any scenario that would let me satisfy this recommendation without breaking other patterns.

[skirtles-code]

I've put the example into a JSFiddle to show what it might look like in its entirety:

https://jsfiddle.net/skirtle/arg1z5ec/

I did have to make one change. The example needs the emits option to function correctly. That was missed when it was migrated from Vue 2 to Vue 3. This does need to be fixed but it's not directly related to the problem being discussed here.

I think it's worth reflecting on the trade-offs being made in the example in the documentation. It's trying to show something very specific and it's important that the main point doesn't got lost in a lot of supporting code. Omitting the code for the parent component is just one aspect of that. For such a simple component it doesn't really make sense to pass the prop as an object in the first place. I think it's implicit that the 'real' component contains a lot of other code that justifies that design decision, code that can't be shown without getting in the way.

For the simple example provided it would make sense to use v-model but it's unclear whether that would still make sense for the full, 'real' component. Without knowing what the rest of TodoItem looks like we're left to guess. Having a string emitted by the event would be incompatible with v-model but it might make sense in the full context of that component. The component might emit several other events that can't easily be bundled into a v-model, in which case it might be easier to avoid v-model altogether.

I've had a go at implementing that same example using v-model:

https://jsfiddle.net/skirtle/4zqofkgy/

This uses v-model:todo on the component, as well as v-model on the <input>.

The comparable section to what's currently in the documentation would be:

app.component('TodoItem', {
  emits: ['update:todo'],
  
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  template: `
    <input v-model="text">
  `,
  
  computed: {
    text: {
      get () {
        return this.todo.text
      },
      set (text) {
        this.$emit('update:todo', {
          ...this.todo,
          text
        })
      }
    }
  }
})

There are things I like about this variation of the example. However, it is longer and I'm unsure whether it adds anything relevant to what's currently in the documentation.

It's also worth noting that I had to use a little bit of trickery to get the v-model:todo to work in the parent template: v-model:todo="items[index]". This is required to get v-model to work inside a v-for. If this component is intended to be consumed within a list, which seems likely for TodoItem, then it would arguably be easier to use an event directly instead of v-model to avoid this problem. That takes us right back to the original example.

Just to reiterate, the point being made in that section is that components should not directly mutate objects passed to them as props. There are various different ways of achieving that and the example shows just one of them.

Perhaps just renaming the input event to something else would help? Something like textChange?

[NataliaTepluhina]

Closing an issue as related MR was merged