[Documentation] v-slot:activator="{ on }"

https://vuetifyjs.com/en/components/tooltips#usage

<v-tooltip bottom>
      <template v-slot:activator="{ on }">
        <v-icon color="primary" dark v-on="on">home</v-icon>
      </template>
      <span>Tooltip</span>
</v-tooltip>

So I’m guessing that the activator slot in the component binds the data object from the render function so that its available in the parent scope. The data object contains an on property which includes the event listeners.

It’d be nice for the doc to provide some pointers to the logic and syntax used. A brief comment in the activator slot description with a link to the below url would be nice.

https://vuejs.org/v2/guide/render-function.html#The-Data-Object-In-Depth

_Originally posted by @YuqiaoS in https://github.com/vuetifyjs/vuetify/issues/6823#issuecomment-476560266_

[nccurry]

If we’re looking at this syntax:

<v-dialog v-model="visible">
  <template v-slot:activator="{ on }">
    <v-btn v-on="on">

and we look at the following

The documentation for scoped slots

Now when we use the <todo-list> component, we can optionally define an alternative <template> for todo items, but with access to data from the child

<todo-list v-bind:todos="todos">
  <template v-slot:todo="{ todo }">
    <span v-if="todo.isComplete">✓</span>
    {{ todo.text }}
  </template>
</todo-list>

The documentation for the v-on api

<!-- object syntax (2.4.0+) -->
<button v-on="{ mousedown: doThis, mouseup: doThat }"></button>

The documentation for vm.$listeners

Contains parent-scope v-on event listeners (without .native modifiers). This can be passed down to an inner component via v-on=“$listeners” - useful when creating transparent wrapper components.

The source code for the v-dialog component

        genActivator: function genActivator() {
            var _this3 = this;

            if (!this.hasActivator) return null;
            var listeners = this.disabled ? {} : {
                click: function click(e) {
                    e.stopPropagation();
                    _this3.getActivator(e);
                    if (!_this3.disabled) _this3.isActive = !_this3.isActive;
                }
            };
            if ((0, _helpers.getSlotType)(this, 'activator') === 'scoped') {
                var activator = this.$scopedSlots.activator({ on: listeners });
                this.activatorNode = activator;
                return activator;
            }
            return this.$createElement('div', {
                staticClass: 'v-dialog__activator',
                class: {
                    'v-dialog__activator--disabled': this.disabled
                },
                ref: 'activator',
                on: listeners
            }, this.$slots.activator);
        }

I read the above syntax as saying

Expose the on event listeners object from the parent v-dialog component’s activator slot to the child template. Using the v-on object syntax bind all the fields of the on event listeners object to the v-btn component’s events. When the v-btn component is clicked, the function associated with the click field of the on event listeners object will be called, causing the v-dialog component to become visible.

What I think is causing the confusion with the syntax

The combination of the following

• v-slot:activator="{ on }" is exposing the object on via object destructuring.
  • It is not intuitive that on is itself an object and not something else.
  • It is not intuitive where on is coming from
• v-on="on" is leveraging the new v-on object syntax to automatically assign events on the v-btn component to functions associated with fields of the on object

If we rearrange the syntax slightly it is a bit more intuitive what is going on as it only requires knowledge of how slot scopes can pass data to their children by automatically communicating that on is an object with a click field that is getting associated with the v-btn click event.

  <v-dialog v-model="visible">
    <template v-slot:activator="{ on: { click } }">
      <v-btn v-on:click="click">

[YuqiaoS]

This isn’t clear at all. You should add doc to explain what the syntax means.