Directives: support complex state

[jods4]

Just starting a conversation to gather ideas.

Directives can vary in complexity.
The most basic may take no value at all: v-autofocus.
Many take just one value: v-show="false".
And a directive that takes a few (maybe optional) parameters usually uses an object literal: v-tooltip="{ message: "Help!", position: "top" }".

Growing further in complexity, for example having many properties or taking complex objects as parameters, is not great.
A real example of such a directive is vue-motion (from Tahul, not the one from Posva).

Things that work and are not hacks:

• Writing huge literals in the template, possibly over multiple lines.
  Not pretty at all.
• Bind to complex objects built in JS.
  Obscures what parameters are used and what is their source data when reading the template. May warrant an additional computed.
• Use a component instead.
  Much more powerful, but adds layers of wrappers in the template, doesn't always feel like the right solution.

A hack that works (what vue-motion does):
Put your state in attributes and sniff their values in the directive itself.
For example vue-motion puts objects that describe the initial, enter, exit variants (and several others) each in their own bound attribute:

<div 
  v-motion
  :inital="{ x: -100, opacity: 0 }"
  :enter="{ x: 0, opacity: 1 }"
  />

That is clever but it has some drawbacks:

• Element attributes are a global namespace where reserving generic names such as active could lead to clashes between libs.
  (Can be fixed by using more specific names, e.g. motion-initial).
• Technically they're undeclared properties, so they usually would be inherited in the template of a custom component, or just end up on the DOM.

Idea:
Maybe Vue could help split state of heavy-duty directives, e.g. by using the namespace syntax:

<div 
  v-motion:initial="{ x: -100, opacity: 0 }"
  v-motion:enter="{ x: 0, opacity: 1}"
  v-motion:exit="{ x: +100, opacity: 0 }"
  />

And each of those could be made available together (maybe in one object with those keys) to the v-motion directive (and that directive only).

Note that in the case of vue-motion that got rid of the empty v-motion directive, since now the presence of the directive is already implied by the various arguments.

I think that syntax is actually not too bad even for "basic" directives that take some modifier with a value.
For example you could consider:

<input v-model="search" v-model:throttle="300" />

[CyberAP]

For me personally having a component with a clear discrete API is much more readable and reliable than using a directive with many options to configure. Directives don't have any contracts and maintaining complex APIs would be much harder without any contracts. I actually think that custom directives should be replaced with components in almost all cases, since it's just much easier to maintain and especially debug.

To compare with your example:

<div 
  v-motion:initial="{ x: -100, opacity: 0 }"
  v-motion:enter="{ x: 0, opacity: 1}"
  v-motion:exit="{ x: +100, opacity: 0 }"
/>

The component-based variant reads much better to me:

<motion
  :initial="{ x: -100, opacity: 0 }"
  :enter="{ x: 0, opacity: 1}"
  :exit="{ x: +100, opacity: 0 }"
>
  <div />
</motion>

And I think a wrapper component is a reasonable price to pay for significant increase in reliability and readability.

[jods4]

I've recently spotted the "hacky" way used in the wild several times.
To me it means that there is a demand for a feature in this area, developers don't always want a wrapper component.

Some example, in addition to v-motion in original post above:

• v-infinite-scroll from Element+ https://element-plus.org/en-US/component/infinite-scroll.html
• Someone must have been "inspired", here's another v-infinite-scroll with a slightly different set of extra props: https://github.com/ElemeFE/vue-infinite-scroll
• v-animate, a Motion One wrapper https://vue-motion-one.vercel.app/#/api/v-animate

[darrylnoakes]

How would this work with other directives that you can apply multiple times? For example, v-model. Not saying it won't, just wondering how.
As far as I know, applying a custom directive multiple times would make multiple separate instances of that directive on the component. How would it be decided whether to attach multiple directives with a single argument each or a single directive with consolidated arguments?

I have an idea, based on composables:

Define the directive in a scope (e.g. a file) that it uses as a closure, the same as a composable can be used as an app-wide store. An object or array is defined in this closure, which will store data.
Every time a new instance of the directive is attached (mounted directive hook), it does not do anything directly, but rather just updates an object in the data object/array, where the key corresponds to the element the directive is applied to. The update hook does the same.
The argument passed to the directive is used as a key for the per-element object that is updated.
Then, using watchers, work can be done when any of the data changes, as if it was a single directive.

N.B. Written in a hurry before I go out for the day. May be slightly flawed. Will add code example. and maybe try it out.

[jods4]

How would this work with other directives that you can apply multiple times? For example, v-model. Not saying it won't, just wondering how.
As far as I know, applying a custom directive multiple times would make multiple separate instances of that directive on the component. How would it be decided whether to attach multiple directives with a single argument each or a single directive with consolidated arguments?

Not sure, some brainstorming needed :)

My exemple of extending v-model with v-model:threshold="300" was of course a very bad one since the : syntax already has a meaning and is commonly used on multiple instance of the same directive, esp. v-model with v-model:prop1="one" v-model:prop2="two".

That could be a matter of choosing a different separator character, like v-model:prop1,threshold="300" although it's a bit cryptic to my taste. The dot . would actually have perfect meaning but it's already used to mean something different.

A truly identical directive like repeating v-x twice doesn't seem to work, the SFC playground errors with duplicate attribute.

[darrylnoakes]

Hmm...

What about this?

<element
  v-thing*initial="{ a: 0, b: 3 }"
  v-thing*pos="{ x: 50, y: 100 }"
>
</element>

I assume that the solution would require being able to have the same directive applied multiple times to the same element, while still allowing for this splitting.

Directive arguments actually work like namespaces in a way, so a "dummy" argument could be used.

<element
  v-thing:coolName*initial="{ a: 0, b: 3 }"
  v-thing:coolName*pos="{ x: 50, y: 100 }"
  v-thing:secondOne*initial="{ a: 2, b: 1 }"
  v-thing:secondOne*pos="{ x: 23, y: 45 }"
>
</element>

So, end result:

Without "splitting":

<element
  v-thing="{ initial: { a: 0, b: 3 }, pos: { x: 50, y: 100 } }"
>
</element>

With "splitting":

<element
  v-thing*initial="{ a: 0, b: 3 }"
  v-thing*pos="{ x: 50, y: 100 }"
>
</element>

What do you think?

[darrylnoakes]

Actually, this could be generalized to apply across the board:

An asterisk in a bound attribute simply means property setting, so the asterisk is basically corresponding to JS's dot-notation property-access.

E.g.

<element
  v-bind:propName*keyA="{ q: 1, w: 2 }"
  v-bind:propName*keyB="{ o: 3, p: 4 }"
>

would be equivalent to

<element
  v-bind:propName="{ keyA: { q: 1, w: 2 }, keyB: { o: 3, p: 4 } }"
>

N.B. I am rather tired, and should be asleep. Errors may exist. Dunno why I always end up writing these at bad times. :)

[rinodrummer]

I think that maybe these solutions will suite for your idea:

1. Library/plugin should adapt to a convention where all the props starts with a namespace, for example:

<v-motion
    :v-motion-initial="{ ... }"
/>

Web Components use that convention with custom element names to avoid the possibility to overlap native HTML tags, but being a convention means that it's not mandatory.

2. Defining a new prop attribute named _namespace that, when present will let coders tu choose to use it whenever a prop is conflicting with another one, for example:

{
    props: {
        _namespace: "v-motion",
        initial,
        ...
    }
}

And in the HTML should look like like this:

<v-motion
    :v-motion[initial]="{ ... }"
    :exit="{ ... }"
/>