feat: add slider event types, JSDoc and typings tests (#10967)

Author: web-padawan

packages/slider/src/vaadin-range-slider.d.ts

@@ -8,19 +8,54 @@ import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { SliderMixin } from './vaadin-slider-mixin.js';
 
+/**
+ * Fired when the user commits a value change.
+ */
+export type RangeSliderChangeEvent = Event & {
+  target: RangeSlider;
+};
+
+/**
+ * Fired when the `value` property changes.
+ */
+export type RangeSliderValueChangedEvent = CustomEvent<{ value: number[] }>;
+
+export interface RangeSliderCustomEventMap {
+  'value-changed': RangeSliderValueChangedEvent;
+}
+
+export interface RangeSliderEventMap extends HTMLElementEventMap, RangeSliderCustomEventMap {
+  change: RangeSliderChangeEvent;
+}
+
 /**
  * `<vaadin-range-slider>` is a web component that represents a range slider
  * for selecting a subset of the given range.
  *
  * ```html
  * <vaadin-range-slider min="0" max="100" step="1"></vaadin-range-slider>
  * ```
+ *
+ * @fires {Event} change - Fired when the user commits a value change.
+ * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  */
 declare class RangeSlider extends SliderMixin(FocusMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
   /**
    * The value of the slider.
    */
   value: number[];
+
+  addEventListener<K extends keyof RangeSliderEventMap>(
+    type: K,
+    listener: (this: RangeSlider, ev: RangeSliderEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof RangeSliderEventMap>(
+    type: K,
+    listener: (this: RangeSlider, ev: RangeSliderEventMap[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
 }
 
 declare global {

packages/slider/src/vaadin-range-slider.js

@@ -24,6 +24,9 @@ import { SliderMixin } from './vaadin-slider-mixin.js';
  * <vaadin-range-slider min="0" max="100" step="1"></vaadin-range-slider>
  * ```
  *
+ * @fires {Event} change - Fired when the user commits a value change.
+ * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin

packages/slider/src/vaadin-slider-mixin.js

@@ -111,4 +111,10 @@ export const SliderMixin = (superClass) =>
     __onChange(event) {
       event.stopPropagation();
     }
+
+    /**
+     * Fired when the user commits a value change.
+     *
+     * @event change
+     */
   };

packages/slider/src/vaadin-slider.d.ts

@@ -8,19 +8,54 @@ import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { SliderMixin } from './vaadin-slider-mixin.js';
 
+/**
+ * Fired when the user commits a value change.
+ */
+export type SliderChangeEvent = Event & {
+  target: Slider;
+};
+
+/**
+ * Fired when the `value` property changes.
+ */
+export type SliderValueChangedEvent = CustomEvent<{ value: number }>;
+
+export interface SliderCustomEventMap {
+  'value-changed': SliderValueChangedEvent;
+}
+
+export interface SliderEventMap extends HTMLElementEventMap, SliderCustomEventMap {
+  change: SliderChangeEvent;
+}
+
 /**
  * `<vaadin-slider>` is a web component that represents a range slider
  * for selecting numerical values within a defined range.
  *
  * ```html
  * <vaadin-slider min="0" max="100" step="1"></vaadin-slider>
  * ```
+ *
+ * @fires {Event} change - Fired when the user commits a value change.
+ * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  */
 declare class Slider extends SliderMixin(FocusMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
   /**
    * The value of the slider.
    */
   value: number;
+
+  addEventListener<K extends keyof SliderEventMap>(
+    type: K,
+    listener: (this: Slider, ev: SliderEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof SliderEventMap>(
+    type: K,
+    listener: (this: Slider, ev: SliderEventMap[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
 }
 
 declare global {

packages/slider/src/vaadin-slider.js

@@ -23,6 +23,9 @@ import { SliderMixin } from './vaadin-slider-mixin.js';
  * <vaadin-slider min="0" max="100" step="1"></vaadin-slider>
  * ```
  *
+ * @fires {Event} change - Fired when the user commits a value change.
+ * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin

packages/slider/test/typings/range-slider.types.ts

@@ -0,0 +1,34 @@
+import '../../vaadin-range-slider.js';
+import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
+import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
+import type { ThemableMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import type { SliderMixinClass } from '../../src/vaadin-slider-mixin.js';
+import type { RangeSlider, RangeSliderChangeEvent, RangeSliderValueChangedEvent } from '../../vaadin-range-slider.js';
+
+const assertType = <TExpected>(actual: TExpected) => actual;
+
+const slider = document.createElement('vaadin-range-slider');
+
+assertType<RangeSlider>(slider);
+
+slider.addEventListener('value-changed', (event) => {
+  assertType<RangeSliderValueChangedEvent>(event);
+  assertType<number[]>(event.detail.value);
+});
+
+slider.addEventListener('change', (event) => {
+  assertType<RangeSliderChangeEvent>(event);
+  assertType<RangeSlider>(event.target);
+});
+
+// Properties
+assertType<number>(slider.max);
+assertType<number>(slider.min);
+assertType<number>(slider.step);
+assertType<number[]>(slider.value);
+
+// Mixins
+assertType<ElementMixinClass>(slider);
+assertType<FocusMixinClass>(slider);
+assertType<ThemableMixinClass>(slider);
+assertType<SliderMixinClass>(slider);

packages/slider/test/typings/slider.types.ts

@@ -0,0 +1,34 @@
+import '../../vaadin-slider.js';
+import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
+import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
+import type { ThemableMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import type { SliderMixinClass } from '../../src/vaadin-slider-mixin.js';
+import type { Slider, SliderChangeEvent, SliderValueChangedEvent } from '../../vaadin-slider.js';
+
+const assertType = <TExpected>(actual: TExpected) => actual;
+
+const slider = document.createElement('vaadin-slider');
+
+assertType<Slider>(slider);
+
+slider.addEventListener('value-changed', (event) => {
+  assertType<SliderValueChangedEvent>(event);
+  assertType<number>(event.detail.value);
+});
+
+slider.addEventListener('change', (event) => {
+  assertType<SliderChangeEvent>(event);
+  assertType<Slider>(event.target);
+});
+
+// Properties
+assertType<number>(slider.max);
+assertType<number>(slider.min);
+assertType<number>(slider.step);
+assertType<number>(slider.value);
+
+// Mixins
+assertType<ElementMixinClass>(slider);
+assertType<FocusMixinClass>(slider);
+assertType<ThemableMixinClass>(slider);
+assertType<SliderMixinClass>(slider);