vue 3 event modifiers

[lidlanca]

emit / native event / case sensitive configurable event binding.

Summary

add modifiers syntax to event binding

a different syntax could have solved for some ambiguity, but for simplicity we can utilize dot modifiers.
with dynamic event name for some edge cases( see how we can support dot in event name itself) .

• emit only (handles vue emitted events )
  -- will solve Custom events should not be permeable core#6086

• native event only ( handles native events )
  -- will solve lack of .native

• case sensitive

  • when provided event name will be set as-is, without any normalization
    will solve Vue 3's v-on syntax does not support listening to custom events with capital letters core#5401
  • will also allow more flexible naming for event names

  <!--  bind Do.Something.Cool event   --> 
  <comp @\Do.Something.Cool="handler" />

for case sensitive event name and vue emitted events, we need to be mindful that emit also provide a way to emit case sensitive.

controlling the type of event binding, will provide greater control and flexibility, on the higher order component.
where it can't explicitly subscribe to a specific type of event, and any format/case of event naming.

Drawbacks

vue currently does not allow . in even binding.
there is currently a workaround to use . in the actual event name, using dynamic event binding.
it is expected that this notation will also work with the .modifiers

<div @[`do.on.click`]="handler"></div>

Examples

event .modifiers

evolved from #451 (comment)

  <!-- auto -->
  <div @Click=handler>1</div>
  
  <!-- auto + case sensitive -->
  <div @Click.custom=handler>2</div>
  
  <!-- emit only -->
  <div @Click.emit=handler>3</div>
  
  <!-- emit only + case sensitive -->
  <div @Click.emit.custom=handler>4</div>
  
  <!-- native only -->
  <div @Click.native=handler>5</div>
  
  <!-- native + case sensitive -->
  <div @Click.native.custom=handler>6</div>

older syntax based

a syntax based proposal, . modifiers have a better dx. ```html

1

2

3

4

5

6

```

[edison1105]

IMO, I feel that this approach adds to the user's burden of use and is not friendly enough.

[lidlanca]

The burdon of use is for the specialized cases.
Where the default is not sufficient.

Do you find the suggested syntax problematic.
Or in general the idea of the additional control.

The example syntax is just a suggestion to start the conversation
There are different direction we can explore

[lidlanca]

For example dot . Modifiers are ok too if we can find away to support event names with dot and seperate modifiers from actual event name.

[lidlanca]

alternatively we can add . modifiers

• .custom (custom / case sensitive )
• .emit (only listen for vue emit)
• .native (only listen for native event)

exiting vue event modifiers

examples of usage

  <!-- auto -->
  <div @Click=handler>1</div>
  
  <!-- auto + case sensitive -->
  <div @Click.custom=handler>2</div>
  
  <!-- emit only -->
  <div @Click.emit=handler>3</div>
  
  <!-- emit only + case sensitive -->
  <div @Click.emit.custom=handler>4</div>
  
  <!-- native only -->
  <div @Click.native=handler>5</div>
  
  <!-- native + case sensitive -->
  <div @Click.native.custom=handler>6</div>

generally vue does not allow . dot in event name binding,
however it is possible to work around that limitation using

<div @[`do.on.click`]="handler"></div>

so this can be used if we don't want to introduce a new syntax that can solve for ambiguity
with the current template parsing rules.

   <!-- bind "click.on.me"   auto normalized by vue to lower case --> 
  <div @[`Click.On.Me`]=handler>7</div>

  <!-- bind "Click.On.Me"  case sensitive --> 
  <div @[`Click.On.Me`].custom=handler>7</div>

   <!-- bind "Click.On.Me"  emit only --> 
  <Comp @[`Click.On.Me`].custom.emit=handler>7</Comp>

[aztalbot]

@lidlanca The two main issues referenced here feel kind of separate to me. What do you think about having two separate discussions? I think the CustomEvent (case-sensitive) issue is more common than the other issue, so may be more critical.

On the CustomEvent issue, I'd start from what we expect the raw prop to look like. Currently onfooBar is interpreted as a prop because events must be an ^on[^a-z] pattern. on:caseSensitive matches that pattern but currently adds a listener to the element as :case-sensitive. It seems Vue could check for : or whatever special character (perhaps \ like you have above), avoid the lowercase hyphenate conversion, and remove the special character.

I think any modifier for case sensitivity should be for compile-time transformation. @caseSensitive.custom wouldn't work with existing logic without a compile-time transformation since the existing behavior transforms it to onCaseSensitive and keeping it lowercase wouldn't match the expected pattern. So a compile-time transformation could make @caseSensitive.custom become @:caseSensitive to mark the custom treatment needed.

To summarize I'm thinking it should look like below (mostly what you have above)

<my-comp @caseSensitive.custom="handler" />
<!-- becomes and is the same as -->
<my-comp @:caseSensitive="handler" />
<!-- compiles roughly to _createElementVNode("my-comp", { "on:caseSensitive": handler }, null, 32 /* HYDRATE_EVENTS */) -->

My preference on special character is : because it sort of follows the pattern of onUpdate:.

Also kind of wondering if all events on custom elements should automatically get this treatment; not sure if it would cause problems or not. That's most likely where this is needed and the compiler already knows which elements are custom, so most people wouldn't even need to be aware of the custom caveat and could just write <my-comp @caseSensitive=handler />, or maybe that should be an option in the compiler, not sure.

[lidlanca]

my initial direction was to introduce a new syntax to solve event names ambiguities.
I simplified the direction of this discussion based on feedback from Vue's core member/s and re focused around modifiers.
since it is an existing syntax, and might be more user friendly, it is more likely to get accepted.

I initially didn't go with modifiers because of some of its downsides.

modifiers in vue are compiled as a prop suffixed to the handler name.
if custom was an actual modifier you would expect this:

<div @DoSomethig.custom />

to be compiled to onDoSomethingCustom prop name

and attach a listener for DoSomething

however
if your element dispatches an event name that ends with any of the known modifiers capitalized
it will not be possible to declaratively add a listener for it

<div @DoPassiveCustom="fn" /> will essentially bind listener for do

and for that you will need the directive workaround

I suppose modifiers need to be encapsulated in the event name for lack of a better alternative is for object binding to work. as well.

<div v-bind=listeners/ >

there is also the problem that vue does not allow . notations in event names
but that can actually be fixed in the compiler with the custom modifier on.