@adyen/eslint-plugin-bento 2.14.0 → 2.16.0

package/rules/deprecation-components-input-emit/README.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-The `input` emit in the following components is deprecated:
+The `@input` event listener in the following components is deprecated:
 
 - `bento-date-picker`
 - `bento-date-range-picker`
@@ -21,11 +21,28 @@ The `input` emit in the following components is deprecated:
 - `bento-selection-card-group`
 - `bento-textarea`
 
-Please use `update:model-value` instead.
+Please use `@update:model-value` instead.
+
+| Deprecated event | Replacement event     | Autofix available          |
+| ---------------- | --------------------- | -------------------------- |
+| `@input`         | `@update:model-value` | Yes (opt-in via `autofix`) |
+
+> **⚠️ Caveat — `v-model` combined with `@input`**
+>
+> Bento Vue 2 components emit **both** `input` (deprecated) and `update:model-value` on every value change for backward
+> compatibility. In Vue 2, `v-model` internally listens to `@input`. If you autofix `@input` to `@update:model-value`
+> while keeping `v-model`, you end up with `v-model` listening to `@input` **and** an explicit `@update:model-value`
+> handler — both of which fire on every change. This causes race conditions because the handler may read the model value
+> before `v-model`'s `@input` listener has propagated the update.
+>
+> In this case, **do not rely on autofix alone**. You must also replace `v-model` with an explicit `:model-value`
+> binding so that a single `@update:model-value` handler controls both the model update and any side effects. See the
+> [Migration Examples](#migration-examples) below.
 
 ## Rule Details
 
-This rule reports usages of the deprecated item.
+This rule reports usages of the deprecated `@input` event and can optionally autofix them to `@update:model-value`.
+Autofix is disabled by default and can be enabled with the `autofix` option.
 
 ### ❌ Incorrect
 
@@ -93,6 +110,18 @@ This rule reports usages of the deprecated item.
 <bento-textarea @input="handler" />
 ```
 
+```html
+<!-- v-on:input directive syntax is also reported -->
+<bento-input-field v-on:input="handler" />
+```
+
+```html
+<!-- ⚠️ v-model + @input — autofix alone is NOT safe -->
+<bento-input-field v-model="email" @input="onEmailChange" />
+
+<bento-dropdown v-model="country" @input="onCountryChange" :items="items" />
+```
+
 ### ✅ Correct
 
 ```html
@@ -158,3 +187,141 @@ This rule reports usages of the deprecated item.
 ```html
 <bento-textarea @update:model-value="handler" />
 ```
+
+```html
+<!-- v-model without a separate handler — no change needed -->
+<bento-input-field v-model="email" />
+```
+
+```html
+<!-- v-model + @input migrated: split v-model into explicit binding + handler -->
+<bento-input-field :model-value="email" @update:model-value="onEmailChange" />
+
+<bento-dropdown :model-value="country" @update:model-value="onCountryChange" :items="items" />
+```
+
+## Migration Examples
+
+If `v-model` is used alongside `@input`, you must also replace `v-model` with `:model-value` — see Case 2. Otherwise,
+renaming `@input` to `@update:model-value` is sufficient — see Cases 1 and 3.
+
+### Case 1 — standalone `@input` (safe to autofix)
+
+The simplest case: `@input` is used without `v-model`. Rename it to `@update:model-value`.
+
+#### Before
+
+```html
+<template>
+    <bento-dropdown @input="onSelect" :items="countries" label="Country" />
+</template>
+
+<script setup lang="ts">
+    const onSelect = (value: string) => {
+        console.log('Selected:', value);
+    };
+</script>
+```
+
+#### After
+
+```html
+<template>
+    <bento-dropdown @update:model-value="onSelect" :items="countries" label="Country" />
+</template>
+
+<script setup lang="ts">
+    const onSelect = (value: string) => {
+        console.log('Selected:', value);
+    };
+</script>
+```
+
+### Case 2 — `v-model` + `@input` (autofix NOT safe — requires manual split)
+
+When `v-model` is used alongside `@input`, autofix alone will cause a dual-emission race condition. You must replace
+`v-model` with an explicit `:model-value` binding and merge the update logic into a single `@update:model-value`
+handler.
+
+#### Before — `v-model` + `@input`
+
+```html
+<template>
+    <bento-dropdown v-model="country" @input="onCountryChange" :items="countries" label="Country" />
+</template>
+
+<script setup lang="ts">
+    const country = ref('');
+
+    const onCountryChange = (value: string) => {
+        fetchCities(value);
+    };
+</script>
+```
+
+#### ❌ Broken — after autofix only (dual-emission race condition)
+
+```html
+<template>
+    <!-- v-model internally listens to @input, while @update:model-value listens to the new event.
+    The component emits BOTH events on every change, causing a race condition:
+    onCountryChange may read `country` before v-model's @input handler has updated it. -->
+    <bento-dropdown v-model="country" @update:model-value="onCountryChange" :items="countries" label="Country" />
+</template>
+```
+
+#### ✅ Correct — split `v-model` and merge handlers
+
+Replace `v-model` with `:model-value` and merge the update logic into one handler:
+
+```html
+<template>
+    <bento-dropdown :model-value="country" @update:model-value="onCountryChange" :items="countries" label="Country" />
+</template>
+
+<script setup lang="ts">
+    const country = ref('');
+
+    const onCountryChange = (value: string) => {
+        country.value = value;
+        fetchCities(value);
+    };
+</script>
+```
+
+### Case 3 — explicit `:model-value` + `@input` (safe to autofix)
+
+When `:model-value` is already used instead of `v-model`, there is no dual-emission conflict. Rename `@input` to
+`@update:model-value`.
+
+#### Before — `:model-value` + `@input`
+
+```html
+<template>
+    <bento-checkbox-group :model-value="selected" @input="onSelect" :items="items" label="Toppings" />
+</template>
+
+<script setup lang="ts">
+    const selected = ref([]);
+
+    const onSelect = (value: string[]) => {
+        selected.value = value;
+    };
+</script>
+```
+
+#### After — rename to `@update:model-value`
+
+```html
+<template>
+    <bento-checkbox-group :model-value="selected" @update:model-value="onSelect" :items="items" label="Toppings" />
+</template>
+
+<script setup lang="ts">
+    const selected = ref([]);
+
+    const onSelect = (value: string[]) => {
+        selected.value = value;
+    };
+</script>
+```

package/rules/deprecation-components-input-emit/deprecation-components-input-emit.integration.test.ts

@@ -25,7 +25,15 @@ describe('@adyen/bento/deprecation-components-input-emit', () => {
             severity: 1,
 
             messageId: 'deprecation',
-            message: `The "input" emit is deprecated. Please use "update:model-value" instead.`,
+            message: `The \`input\` emit is deprecated. Please use \`update:model-value\` instead.
+            
+Be wary of undesired side effects and race conditions if \`v-model\` is used in conjunction with \`@input\`.
+
+Incorrect:
+<bento-component v-model="text" @input="onInput" />
+
+Correct:
+<bento-component :model-value="text" @update:model-value="onInput" />`,
 
             fix: expect.objectContaining({
                 text: expect.stringContaining('update:model-value'),

package/rules/deprecation-components-input-emit/deprecation-components-input-emit.js

@@ -19,7 +19,15 @@ module.exports = {
             recommended: true,
         },
         messages: {
-            deprecation: `The "input" emit is deprecated. Please use "update:model-value" instead.`,
+            deprecation: `The \`input\` emit is deprecated. Please use \`update:model-value\` instead.
+            
+Be wary of undesired side effects and race conditions if \`v-model\` is used in conjunction with \`@input\`.
+
+Incorrect:
+<bento-component v-model="text" @input="onInput" />
+
+Correct:
+<bento-component :model-value="text" @update:model-value="onInput" />`,
         },
         fixable: 'code',
         schema: [