feat(vue): implement custom event property as source for v-model (#689)

adamczykpiotr · johnjenkins · web-flow · commit bc385bb0794e · 2025-07-24T12:52:38.000+01:00
* feat: implement custom event property as source for v-model

* feat: add `useEventDetail` option

* docs: update README.md &amp; grammar

* style: format code

* test: implement tests for new v-model event attribute use

* feat: refactor code to support path dot syntax &amp; remove `useEventDetail`

* feat: simplify resolve path function

* feat(vue): add nested event to checkbox component to showcase nested v-model support

* test(vue): add e2e tests for checkbox component with nested v-model support

---------

Co-authored-by: John Jenkins &lt;johnljenkins@Hotmail.com&gt;
diff --git a/example-project/component-library-angular/projects/library/src/directives/proxies.ts b/example-project/component-library-angular/projects/library/src/directives/proxies.ts
@@ -106,11 +106,12 @@ export declare interface MyButtonScoped extends Components.MyButtonScoped {
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
   inputs: ['alignment', 'checked', 'color', 'disabled', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'value'],
-  outputs: ['ionChange', 'ionFocus', 'ionBlur'],
+  outputs: ['ionChange', 'ionChangeNested', 'ionFocus', 'ionBlur'],
 })
 export class MyCheckbox {
   protected el: HTMLMyCheckboxElement;
   @Output() ionChange = new EventEmitter<CustomEvent<IMyCheckboxCheckboxChangeEventDetail>>();
+  @Output() ionChangeNested = new EventEmitter<CustomEvent<IMyCheckboxCheckboxChangeNestedEventDetail>>();
   @Output() ionFocus = new EventEmitter<CustomEvent<void>>();
   @Output() ionBlur = new EventEmitter<CustomEvent<void>>();
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
@@ -121,6 +122,7 @@ export class MyCheckbox {
 
 
 import type { CheckboxChangeEventDetail as IMyCheckboxCheckboxChangeEventDetail } from 'component-library/components';
+import type { CheckboxChangeNestedEventDetail as IMyCheckboxCheckboxChangeNestedEventDetail } from 'component-library/components';
 
 export declare interface MyCheckbox extends Components.MyCheckbox {
   /**
@@ -129,6 +131,11 @@ export declare interface MyCheckbox extends Components.MyCheckbox {
 This event will not emit when programmatically setting the `checked` property.
    */
   ionChange: EventEmitter<CustomEvent<IMyCheckboxCheckboxChangeEventDetail>>;
+  /**
+   * Same as `ionChange`, but with a nested object for the value.
+For demonstration purposes to be able to test ways to handle more complex events.
+   */
+  ionChangeNested: EventEmitter<CustomEvent<IMyCheckboxCheckboxChangeNestedEventDetail>>;
   /**
    * Emitted when the checkbox has focus.
    */
diff --git a/example-project/component-library-react/src/components.server.ts b/example-project/component-library-react/src/components.server.ts
@@ -10,7 +10,7 @@ import * as clientComponents from 'component-library-react';
 
 import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { createComponent, type HydrateModule, type ReactWebComponent, type SerializeShadowRootOptions } from '@stencil/react-output-target/ssr';
-import { type CheckboxChangeEventDetail, type IMyComponent, type InputChangeEventDetail, type MyCheckboxCustomEvent, type MyComponentScopedCustomEvent, type MyInputCustomEvent, type MyInputScopedCustomEvent, type MyPopoverCustomEvent, type MyRadioGroupCustomEvent, type MyRangeCustomEvent, type OverlayEventDetail, type RadioGroupChangeEventDetail, type RangeChangeEventDetail } from "component-library";
+import { type CheckboxChangeEventDetail, type CheckboxChangeNestedEventDetail, type IMyComponent, type InputChangeEventDetail, type MyCheckboxCustomEvent, type MyComponentScopedCustomEvent, type MyInputCustomEvent, type MyInputScopedCustomEvent, type MyPopoverCustomEvent, type MyRadioGroupCustomEvent, type MyRangeCustomEvent, type OverlayEventDetail, type RadioGroupChangeEventDetail, type RangeChangeEventDetail } from "component-library";
 import { MyButtonScoped as MyButtonScopedElement } from "component-library/components/my-button-scoped.js";
 import { MyButton as MyButtonElement } from "component-library/components/my-button.js";
 import { MyCheckbox as MyCheckboxElement } from "component-library/components/my-checkbox.js";
@@ -90,6 +90,7 @@ export const MyButtonScoped: StencilReactComponent<MyButtonScopedElement, MyButt
 
 export type MyCheckboxEvents = {
     onIonChange: EventName<MyCheckboxCustomEvent<CheckboxChangeEventDetail>>,
+    onIonChangeNested: EventName<MyCheckboxCustomEvent<CheckboxChangeNestedEventDetail>>,
     onIonFocus: EventName<CustomEvent<void>>,
     onIonBlur: EventName<CustomEvent<void>>
 };
diff --git a/example-project/component-library-react/src/components.ts b/example-project/component-library-react/src/components.ts
@@ -9,7 +9,7 @@
 
 import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { createComponent } from '@stencil/react-output-target/runtime';
-import { type CheckboxChangeEventDetail, type IMyComponent, type InputChangeEventDetail, type MyCheckboxCustomEvent, type MyComponentScopedCustomEvent, type MyInputCustomEvent, type MyInputScopedCustomEvent, type MyPopoverCustomEvent, type MyRadioGroupCustomEvent, type MyRangeCustomEvent, type OverlayEventDetail, type RadioGroupChangeEventDetail, type RangeChangeEventDetail } from "component-library";
+import { type CheckboxChangeEventDetail, type CheckboxChangeNestedEventDetail, type IMyComponent, type InputChangeEventDetail, type MyCheckboxCustomEvent, type MyComponentScopedCustomEvent, type MyInputCustomEvent, type MyInputScopedCustomEvent, type MyPopoverCustomEvent, type MyRadioGroupCustomEvent, type MyRangeCustomEvent, type OverlayEventDetail, type RadioGroupChangeEventDetail, type RangeChangeEventDetail } from "component-library";
 import { MyButtonScoped as MyButtonScopedElement, defineCustomElement as defineMyButtonScoped } from "component-library/components/my-button-scoped.js";
 import { MyButton as MyButtonElement, defineCustomElement as defineMyButton } from "component-library/components/my-button.js";
 import { MyCheckbox as MyCheckboxElement, defineCustomElement as defineMyCheckbox } from "component-library/components/my-checkbox.js";
@@ -68,6 +68,7 @@ export const MyButtonScoped: StencilReactComponent<MyButtonScopedElement, MyButt
 
 export type MyCheckboxEvents = {
     onIonChange: EventName<MyCheckboxCustomEvent<CheckboxChangeEventDetail>>,
+    onIonChangeNested: EventName<MyCheckboxCustomEvent<CheckboxChangeNestedEventDetail>>,
     onIonFocus: EventName<CustomEvent<void>>,
     onIonBlur: EventName<CustomEvent<void>>
 };
@@ -79,6 +80,7 @@ export const MyCheckbox: StencilReactComponent<MyCheckboxElement, MyCheckboxEven
     react: React,
     events: {
         onIonChange: 'ionChange',
+        onIonChangeNested: 'ionChangeNested',
         onIonFocus: 'ionFocus',
         onIonBlur: 'ionBlur'
     } as MyCheckboxEvents,
diff --git a/example-project/component-library-vue/src/index.ts b/example-project/component-library-vue/src/index.ts
@@ -122,14 +122,16 @@ export const MyCheckbox: StencilVueComponent<JSX.MyCheckbox, JSX.MyCheckbox["che
   'justify',
   'alignment',
   'ionChange',
+  'ionChangeNested',
   'ionFocus',
   'ionBlur'
 ], [
   'ionChange',
+  'ionChangeNested',
   'ionFocus',
   'ionBlur'
 ],
-'checked', 'myChange') : defineStencilSSRComponent<JSX.MyCheckbox, JSX.MyCheckbox["checked"]>({
+'checked', 'ionChangeNested', 'detail.nested.checked') : defineStencilSSRComponent<JSX.MyCheckbox, JSX.MyCheckbox["checked"]>({
   tagName: 'my-checkbox',
   hydrateModule: import('component-library/hydrate'),
   props: {
@@ -142,6 +144,7 @@ export const MyCheckbox: StencilVueComponent<JSX.MyCheckbox, JSX.MyCheckbox["che
     'justify': [String, "justify"],
     'alignment': [String, "alignment"],
     'onIonChange': [Function],
+    'onIonChangeNested': [Function],
     'onIonFocus': [Function],
     'onIonBlur': [Function]
   }
@@ -264,7 +267,7 @@ export const MyInput: StencilVueComponent<JSX.MyInput, JSX.MyInput["value"]> = /
   'myBlur',
   'myFocus'
 ],
-'value', 'myChange') : defineStencilSSRComponent<JSX.MyInput, JSX.MyInput["value"]>({
+'value', 'myChange', undefined) : defineStencilSSRComponent<JSX.MyInput, JSX.MyInput["value"]>({
   tagName: 'my-input',
   hydrateModule: import('component-library/hydrate'),
   props: {
@@ -488,7 +491,7 @@ export const MyRadioGroup: StencilVueComponent<JSX.MyRadioGroup, JSX.MyRadioGrou
   'myChange',
   'myValueChange'
 ],
-'value', 'myChange') : defineStencilSSRComponent<JSX.MyRadioGroup, JSX.MyRadioGroup["value"]>({
+'value', 'myChange', undefined) : defineStencilSSRComponent<JSX.MyRadioGroup, JSX.MyRadioGroup["value"]>({
   tagName: 'my-radio-group',
   hydrateModule: import('component-library/hydrate'),
   props: {
@@ -524,7 +527,7 @@ export const MyRange: StencilVueComponent<JSX.MyRange, JSX.MyRange["value"]> = /
   'myFocus',
   'myBlur'
 ],
-'value', 'myChange') : defineStencilSSRComponent<JSX.MyRange, JSX.MyRange["value"]>({
+'value', 'myChange', undefined) : defineStencilSSRComponent<JSX.MyRange, JSX.MyRange["value"]>({
   tagName: 'my-range',
   hydrateModule: import('component-library/hydrate'),
   props: {
diff --git a/example-project/component-library/src/components.d.ts b/example-project/component-library/src/components.d.ts
@@ -6,7 +6,7 @@
  */
 import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
 import { AutocompleteTypes, Color, ComponentProps, ComponentRef, OverlayEventDetail, TextFieldTypes } from "./interfaces";
-import { CheckboxChangeEventDetail } from "./components/my-checkbox/my-checkbox";
+import { CheckboxChangeEventDetail, CheckboxChangeNestedEventDetail } from "./components/my-checkbox/my-checkbox";
 import { Baz, Foo, Grault, Quux, Waldo } from "./components/my-complex-props/my-complex-props";
 import { Baz as Baz1, Foo as Foo1, Grault as Grault1, Quux as Quux1, Waldo as Waldo1 } from "./components/my-complex-props-scoped/my-complex-props-scoped";
 import { IMyComponent } from "./components/helpers";
@@ -16,7 +16,7 @@ import { RadioGroupChangeEventDetail } from "./components/my-radio-group/my-radi
 import { Color as Color1, StyleEventDetail } from "./components/element-interface";
 import { RangeChangeEventDetail, RangeValue } from "./components/my-range/my-range";
 export { AutocompleteTypes, Color, ComponentProps, ComponentRef, OverlayEventDetail, TextFieldTypes } from "./interfaces";
-export { CheckboxChangeEventDetail } from "./components/my-checkbox/my-checkbox";
+export { CheckboxChangeEventDetail, CheckboxChangeNestedEventDetail } from "./components/my-checkbox/my-checkbox";
 export { Baz, Foo, Grault, Quux, Waldo } from "./components/my-complex-props/my-complex-props";
 export { Baz as Baz1, Foo as Foo1, Grault as Grault1, Quux as Quux1, Waldo as Waldo1 } from "./components/my-complex-props-scoped/my-complex-props-scoped";
 export { IMyComponent } from "./components/helpers";
@@ -824,6 +824,7 @@ declare global {
     };
     interface HTMLMyCheckboxElementEventMap {
         "ionChange": CheckboxChangeEventDetail;
+        "ionChangeNested": CheckboxChangeNestedEventDetail;
         "ionFocus": void;
         "ionBlur": void;
     }
@@ -1259,6 +1260,10 @@ declare namespace LocalJSX {
           * Emitted when the checked property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `checked` property.
          */
         "onIonChange"?: (event: MyCheckboxCustomEvent<CheckboxChangeEventDetail>) => void;
+        /**
+          * Same as `ionChange`, but with a nested object for the value. For demonstration purposes to be able to test ways to handle more complex events.
+         */
+        "onIonChangeNested"?: (event: MyCheckboxCustomEvent<CheckboxChangeNestedEventDetail>) => void;
         /**
           * Emitted when the checkbox has focus.
          */
diff --git a/example-project/component-library/src/components/my-checkbox/my-checkbox.tsx b/example-project/component-library/src/components/my-checkbox/my-checkbox.tsx
@@ -1,12 +1,20 @@
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
-import { Component, Element, Event, Host, Method, Prop, h } from '@stencil/core';
+import { Component, Element, Event, h, Host, Method, Prop } from '@stencil/core';
 import { createColorClasses, hasShadowDom, hostContext } from '../helpers';
 
 export interface CheckboxChangeEventDetail<T = any> {
   value: T;
   checked: boolean;
 }
 
+export interface CheckboxChangeNestedEventDetail<T = any> {
+  nested: {
+    value: T;
+    checked: boolean;
+    intermediate: boolean;
+  };
+}
+
 /**
  * @virtualProp {"ios" | "md"} mode - The mode determines which platform styles to use.
  *
@@ -100,6 +108,12 @@ export class Checkbox implements ComponentInterface {
    */
   @Event() ionChange!: EventEmitter<CheckboxChangeEventDetail>;
 
+  /**
+   * Same as `ionChange`, but with a nested object for the value.
+   * For demonstration purposes to be able to test ways to handle more complex events.
+   */
+  @Event() ionChangeNested: EventEmitter<CheckboxChangeNestedEventDetail>;
+
   /**
    * Emitted when the checkbox has focus.
    */
@@ -134,6 +148,14 @@ export class Checkbox implements ComponentInterface {
       checked: isChecked,
       value: this.value,
     });
+
+    this.ionChangeNested.emit({
+      nested: {
+        value: isChecked,
+        checked: isChecked,
+        intermediate: this.indeterminate,
+      },
+    });
   };
 
   private toggleChecked = (ev: Event) => {
diff --git a/example-project/component-library/src/components/my-checkbox/readme.md b/example-project/component-library/src/components/my-checkbox/readme.md
@@ -23,11 +23,12 @@
 
 ## Events
 
-| Event       | Description                                                                                                                                                                 | Type                                          |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| `ionBlur`   | Emitted when the checkbox loses focus.                                                                                                                                      | `CustomEvent<void>`                           |
-| `ionChange` | Emitted when the checked property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `checked` property. | `CustomEvent<CheckboxChangeEventDetail<any>>` |
-| `ionFocus`  | Emitted when the checkbox has focus.                                                                                                                                        | `CustomEvent<void>`                           |
+| Event             | Description                                                                                                                                                                 | Type                                                |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `ionBlur`         | Emitted when the checkbox loses focus.                                                                                                                                      | `CustomEvent<void>`                                 |
+| `ionChange`       | Emitted when the checked property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `checked` property. | `CustomEvent<CheckboxChangeEventDetail<any>>`       |
+| `ionChangeNested` | Same as `ionChange`, but with a nested object for the value. For demonstration purposes to be able to test ways to handle more complex events.                              | `CustomEvent<CheckboxChangeNestedEventDetail<any>>` |
+| `ionFocus`        | Emitted when the checkbox has focus.                                                                                                                                        | `CustomEvent<void>`                                 |
 
 
 ## Slots
diff --git a/example-project/component-library/stencil.config.ts b/example-project/component-library/stencil.config.ts
@@ -45,8 +45,9 @@ const vueComponentModels: ComponentModelConfig[] = [
   },
   {
     elements: ['my-checkbox'],
-    event: 'myChange',
+    event: 'ionChangeNested',
     targetAttr: 'checked',
+    eventAttr: 'detail.nested.checked'
   },
   {
     elements: ['my-range', 'my-radio-group'],
diff --git a/example-project/vue-app/src/components/Checkbox.vue b/example-project/vue-app/src/components/Checkbox.vue
@@ -0,0 +1,41 @@
+<script>
+import { defineComponent, ref } from 'vue';
+import { MyCheckbox } from 'component-library-vue';
+
+export default defineComponent({
+  name: 'Checkbox',
+  components: {
+    MyCheckbox,
+  },
+  setup() {
+    const inputValue = ref(null);
+    const changeEvent = ref(null);
+
+    const handleChange = (ev) => {
+      changeEvent.value = ev.detail.nested.value;
+    };
+
+    return {
+      inputValue,
+      changeEvent,
+      handleChange,
+    };
+  },
+});
+</script>
+
+<style scoped>
+.inputResultCheckbox {
+  color: green;
+}
+</style>
+
+<template>
+  <div>
+    <MyCheckbox v-model="inputValue" @ionChangeNested="handleChange" />
+    <div class="inputResultCheckbox">
+      <p>Input v-model: {{ inputValue }}</p>
+      <p>Change Event: {{ changeEvent }}</p>
+    </div>
+  </div>
+</template>
diff --git a/example-project/vue-app/src/views/BasicComposition.vue b/example-project/vue-app/src/views/BasicComposition.vue
@@ -17,6 +17,7 @@
   />
   <p data-testid="mycomponent-click" v-show="isClicked">MyComponent was clicked</p>
   <Input />
+  <Checkbox />
   <MyCheckbox @ionChange="console.log">Checkbox!!!</MyCheckbox>
   <hr />
   <my-input v-model="input" />
@@ -35,13 +36,17 @@ import { defineComponent, ref } from 'vue'
 import HelloWorld from '../components/HelloWorld.vue'
 // @ts-ignore
 import Input from '../components/Input.vue'
+// @ts-ignore
+import Checkbox from '../components/Checkbox.vue'
 import { MyComponent, MyCheckbox, MyInput, MyRadio, MyRadioGroup } from 'component-library-vue'
 
+
 export default defineComponent({
   name: 'BasicComposition',
   components: {
     HelloWorld,
     Input,
+    Checkbox,
     MyComponent,
     MyCheckbox,
     MyInput,
@@ -64,10 +69,15 @@ export default defineComponent({
       isClicked,
       handleCustomEvent,
       kidsNames,
-      radioGroupValue
-    }
-  }
-})
+      radioGroupValue,
+    };
+  },
+  data() {
+    return {
+      checked: false,
+    };
+  },
+});
 </script>
 
 <style scoped>
diff --git a/example-project/vue-app/src/views/SfcTests.vue b/example-project/vue-app/src/views/SfcTests.vue
@@ -2,9 +2,12 @@
 import HelloWorld from '../components/HelloWorld.vue'
 // @ts-ignore
 import Input from '../components/Input.vue'
+// @ts-ignore
+import Checkbox from '../components/Checkbox.vue';
 import { MyComponent, MyCheckbox, MyInput, MyRadio, MyRadioGroup } from 'component-library-vue'
 import { ref } from 'vue'
 
+
 const input = ref('');
 const isClicked = ref(false)
 const handleCustomEvent = () => {
@@ -34,6 +37,7 @@ const radioGroupValue = ref('option1')
   />
   <p data-testid="mycomponent-click" v-show="isClicked">MyComponent was clicked</p>
   <Input />
+  <Checkbox />
   <MyCheckbox @ionChange="console.log">Checkbox!!!</MyCheckbox>
   <hr />
   <my-input v-model="input" />
diff --git a/example-project/vue-app/tests/test.e2e.ts b/example-project/vue-app/tests/test.e2e.ts
@@ -23,6 +23,14 @@ describe('Stencil Vue Integration', () => {
         ]);
       });
 
+      it('should allow to interact with checkbox element with custom v-model path', async () => {
+        await $('my-checkbox').click();
+        await expect(await $$('.inputResultCheckbox p').map((p) => p.getText())).toEqual([
+          'Input v-model: true',
+          'Change Event: true'
+        ]);
+      });
+
       it.skip('should listen to custom events', async () => {
         await $('my-component').$('div').click();
         await expect(await $('[data-testid="mycomponent-click"]').getText()).toEqual('MyComponent was clicked');
diff --git a/packages/vue/README.md b/packages/vue/README.md
diff --git a/packages/vue/src/generate-vue-component.test.ts b/packages/vue/src/generate-vue-component.test.ts
diff --git a/packages/vue/src/generate-vue-component.ts b/packages/vue/src/generate-vue-component.ts
diff --git a/packages/vue/src/runtime.ts b/packages/vue/src/runtime.ts
diff --git a/packages/vue/src/types.ts b/packages/vue/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -45,8 +45,9 @@ const vueComponentModels: ComponentModelConfig[] = [`
`45`	`45`	`},`
`46`	`46`	`{`
`47`	`47`	`elements: ['my-checkbox'],`
`48`		`- event: 'myChange',`
	`48`	`+ event: 'ionChangeNested',`
`49`	`49`	`targetAttr: 'checked',`
	`50`	`+ eventAttr: 'detail.nested.checked'`
`50`	`51`	`},`
`51`	`52`	`{`
`52`	`53`	`elements: ['my-range', 'my-radio-group'],`