From 71c55c8b38a3a66d9e911b88ebd98eb4180152fb Mon Sep 17 00:00:00 2001
From: Nikita Barsukov <nikita.s.barsukov@gmail.com>
Date: Wed, 26 Jun 2024 12:18:33 +0300
Subject: [PATCH] chore(demo): add documentation for `maskitoChangeEventPlugin`

---
 .../examples/4-change-event/component.ts      | 31 +++++++++++++++
 .../plugins/examples/4-change-event/mask.ts   | 15 +++++++
 .../plugins/plugins.component.ts              |  8 ++++
 .../plugins/plugins.template.html             | 39 +++++++++++++++++++
 4 files changed, 93 insertions(+)
 create mode 100644 projects/demo/src/pages/documentation/plugins/examples/4-change-event/component.ts
 create mode 100644 projects/demo/src/pages/documentation/plugins/examples/4-change-event/mask.ts

diff --git a/projects/demo/src/pages/documentation/plugins/examples/4-change-event/component.ts b/projects/demo/src/pages/documentation/plugins/examples/4-change-event/component.ts
new file mode 100644
index 000000000..5ee28e2d1
--- /dev/null
+++ b/projects/demo/src/pages/documentation/plugins/examples/4-change-event/component.ts
@@ -0,0 +1,31 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {FormsModule} from '@angular/forms';
+import {MaskitoDirective} from '@maskito/angular';
+import {TuiInputModule} from '@taiga-ui/kit';
+
+import mask from './mask';
+
+@Component({
+    standalone: true,
+    selector: 'plugins-change-event-doc-example-4',
+    imports: [FormsModule, MaskitoDirective, TuiInputModule],
+    template: `
+        <tui-input
+            [maskito]="maskitoOptions"
+            [style.max-width.rem]="20"
+            [(ngModel)]="value"
+        >
+            Enter number
+
+            <input
+                tuiTextfield
+                [maskito]="maskitoOptions"
+            />
+        </tui-input>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class PluginsDocExample4 {
+    protected readonly maskitoOptions = mask;
+    protected value = '';
+}
diff --git a/projects/demo/src/pages/documentation/plugins/examples/4-change-event/mask.ts b/projects/demo/src/pages/documentation/plugins/examples/4-change-event/mask.ts
new file mode 100644
index 000000000..e577b5d1f
--- /dev/null
+++ b/projects/demo/src/pages/documentation/plugins/examples/4-change-event/mask.ts
@@ -0,0 +1,15 @@
+import type {MaskitoOptions} from '@maskito/core';
+import {maskitoChangeEventPlugin} from '@maskito/core';
+import {maskitoNumberOptionsGenerator} from '@maskito/kit';
+
+const numberOptions = maskitoNumberOptionsGenerator({
+    precision: 2,
+});
+
+export default {
+    ...numberOptions,
+    plugins: [
+        ...numberOptions.plugins,
+        maskitoChangeEventPlugin(), // <--- Enable it
+    ],
+} as MaskitoOptions;
diff --git a/projects/demo/src/pages/documentation/plugins/plugins.component.ts b/projects/demo/src/pages/documentation/plugins/plugins.component.ts
index a989b4f0d..16ac384ca 100644
--- a/projects/demo/src/pages/documentation/plugins/plugins.component.ts
+++ b/projects/demo/src/pages/documentation/plugins/plugins.component.ts
@@ -9,6 +9,7 @@ import {NextStepsComponent} from '../next-steps/next-steps.component';
 import {PluginsDocExample1} from './examples/1-reject/component';
 import {PluginsDocExample2} from './examples/2-initial-calibration/component';
 import {PluginsDocExample3} from './examples/3-strict-composition/component';
+import {PluginsDocExample4} from './examples/4-change-event/component';
 
 @Component({
     standalone: true,
@@ -22,6 +23,7 @@ import {PluginsDocExample3} from './examples/3-strict-composition/component';
         PluginsDocExample1,
         PluginsDocExample2,
         PluginsDocExample3,
+        PluginsDocExample4,
     ],
     templateUrl: './plugins.template.html',
     changeDetection: ChangeDetectionStrategy.OnPush,
@@ -47,4 +49,10 @@ export default class PluginsDocPageComponent {
             './examples/3-strict-composition/mask.ts?raw'
         ),
     };
+
+    protected readonly changeEventExample: TuiDocExample = {
+        [DocExamplePrimaryTab.MaskitoOptions]: import(
+            './examples/4-change-event/mask.ts?raw'
+        ),
+    };
 }
diff --git a/projects/demo/src/pages/documentation/plugins/plugins.template.html b/projects/demo/src/pages/documentation/plugins/plugins.template.html
index c812da449..2a2de4e66 100644
--- a/projects/demo/src/pages/documentation/plugins/plugins.template.html
+++ b/projects/demo/src/pages/documentation/plugins/plugins.template.html
@@ -82,5 +82,44 @@
         <plugins-strict-composition-doc-example-3 />
     </tui-doc-example>
 
+    <tui-doc-example
+        id="change-event"
+        heading="Built-in plugin for change event"
+        [content]="changeEventExample"
+        [description]="changeEventDescription"
+    >
+        <ng-template #changeEventDescription>
+            Native
+            <a
+                href="https://developer.mozilla.org/en-US/docs/Web/API/Element/beforeinput_event"
+                target="_blank"
+                tuiLink
+            >
+                <code>beforeinput</code>
+            </a>
+            event default behavior is cancelled to process user entered invalid value. This causes native
+            <a
+                href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event"
+                target="_blank"
+                tuiLink
+            >
+                <code>change</code>
+            </a>
+            event to
+            <strong>NOT</strong>
+            be dispatched by browser. A
+            <code>change</code>
+            event, as opposed to
+            <code>input</code>
+            , is triggered only when user left the field and value was changed during interaction. If you rely on this
+            behavior, add
+            <code>maskitoChangeEventPlugin</code>
+            to your mask configuration. It will dispatch synthetic
+            <code>change</code>
+            event using the same logic.
+        </ng-template>
+        <plugins-change-event-doc-example-4 />
+    </tui-doc-example>
+
     <next-steps />
 </tui-doc-page>