Props Directive

[abitwhy]

• Start Date: 2022-03-17
• Target Major Version: 3.x
• Reference Issues: More explicit props core#5586

Summary

Use directive props.

Basic example

<AComponent v-props="props" />

Motivation

Change the bad status quo of the props option.

Ineffective side effects

1. Extra conflict troubles: renaming two things with duplicate names.

   example

   <!-- No duplicate attribute warning -->
   <AComponent
     v-props="{ title: 'duplicate names' }"
     title="title for attributes"
   />
   <!-- Duplicate attribute warning -->
   <AComponent title="title for props" title="title for attributes" />

2. Extra compilation costs(probably here): distinguishing two things with the same syntactic structure.

   example

   [buildProps](https://github.com/vuejs/core/blob/1070f127a78bfe7da6fe550cc272ef11a1f434a0/packages/compiler-core/src/transforms/transformElement.ts#L377)

3. Extra documentation costs: explain two confusing things.(also costs extra compilation).

   example

   • Prop Name Casing
   • Boolean and Boolean Casting
   • Fallthrough Attributes and Unlike props

4. Extra reading costs: reading two things that look like.

   example

   <AComponent x="unkown" />
   <!-- Is it an attribute? -->
   <!-- Or you just want set the attribute, will it work? -->
   <!-- You have to check the component's props. -->

5. Extra code costs: writing and storing more :(abbr of v-bind) and ".

   example

   <AComponent
     v-props="{
       foo: 0,
       bar: 0
     }"
   />
   <AComponent
     :foo="0"
     :bar="0"
   />

Analysis of causes

Use the same flat structure as HTML Attributes.

Vue props and HTML Attributes are expected to be written in a consistent way to reduce user learning costs.

However, the flat structure design does not consider expansion. Trying to expand another similar flat structure on one flat structure needs to solve the conflict by itself. Yes, vuejs did it on props and attributes, but it's not elegant.

Think about it, why don't we put every .vue together in project? instead, separate the / components and / pages directories. (Maybe it was put together at first.) Yes, for clear logic and ease of use.

What we need to do now is to separate a directory, more professionally: create a namespace.

demonstration

Detailed design

This may not be called design, just some ideas, because I haven't carefully read the vuejs source code of relevant parts.(Of course, the same for any other part.)

Code

1. Create a new built-in instruction v-props
2. Pass the value of v-props to $props
3. Remove the original props from $props
4. Pass the original props to $attrs

Document

1. Declare new built-in instruction v-props
2. Provide migration strategy

Experiment

Experiment of 'v-props'

Drawbacks

This is a very basic change with a wide range of impacts.

Alternatives

Not know and not found.

Adoption strategy

Breaking

This is a breaking change to the code, a refactoring of the way to write props; but conceptually, it doesn't change anything, and doesn't affect semantics.

Implement

It is recommended that this built-in directive be implemented in the next major release rather than being adapted to end the confusion completely.

However, if adaptation is necessary, it only needs to retain the existing logic, and the cost is very low.

Migration

1. Component-level projects should be refactored accordingly, but non-destructive and cleanly.
2. Plugin-level projects that only use ` $props' will not be affected.

Unresolved questions

Use v-prop to be shorter?

[leopiccionia]

If I understand correctly, your proposal is about disallowing passing props via v-bind directive, adding a separate v-props directive for that purpose. Is this correct?

When thinking about components, whether a property is handled as a prop or a HTML attribute is, most of the times, an implementation detail. I've changed an implementation from attribute to prop, or vice-versa, dozens (perhaps hundreds) of times over the years.

This behavior enables faster iterations, because you can change component code without changing all the caller sites. It's specially useful for library authors, because it avoids breaking changes.

Separating the code in components (or, more generally, functions) is not just about code reuse, but also about abstracting implementation details. Having to know beforehand which calling convention I have to use for each property is more brittle, and adds another possible source of bugs.

Please remember that this abstraction is not exclusive to Vue, but embraced by the whole component-based front-end community. In some other libraries, like React, the distinction between props and attributes is even more implicit.

I can't remember any time I wanted the same name for an attribute and for an unrelated prop on the same component. But using a more descriptive name is possibly a better solution.

[abitwhy]

@leopiccionia You understand exactly right and more clearly.
If props is used as a preliminary HTML attribute, they are indeed the same concept, which means that it is easier to migrate to Web Components.
In fact, my first focus was on abbreviations. When I learned that v-bind supports binding an object, this problem does not exist.