docs(input): examples for setting an initial value with maskito (#3597)

* add examples for setting an initial value when using maskito (using maskitoTransform)

* chore: prettier formatting

* input-masking: add maskitoTransform reference to demo.html

---------

Co-authored-by: Sean Perkins <[email protected]>

Author: marlon-ionic

static/usage/v7/input/mask/angular/example_component_html.md

@@ -12,6 +12,7 @@
     <ion-input
       label="US phone number"
       placeholder="+1 (xxx) xxx-xxxx"
+      [(ngModel)]="myPhoneNumber"
       [maskito]="phoneMask"
       [maskitoElement]="maskPredicate"
     ></ion-input>

static/usage/v7/input/mask/angular/example_component_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { Component } from '@angular/core';
 
-import { MaskitoOptions, MaskitoElementPredicate } from '@maskito/core';
+import { MaskitoOptions, MaskitoElementPredicate, maskitoTransform } from '@maskito/core';
 
 @Component({
   selector: 'app-example',
@@ -12,6 +12,9 @@ export class ExampleComponent {
     mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
   };
 
+  //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  myPhoneNumber = maskitoTransform('5555551212', this.phoneMask);
+
   readonly cardMask: MaskitoOptions = {
     mask: [
       ...Array(4).fill(/\d/),

static/usage/v7/input/mask/demo.html

@@ -8,8 +8,9 @@
     <script src="../../common.js"></script>
     <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
     <script type="module">
-      import { Maskito } from 'https://cdn.jsdelivr.net/npm/@maskito/core/index.esm.js';
+      import { Maskito, maskitoTransform } from 'https://cdn.jsdelivr.net/npm/@maskito/core/index.esm.js';
       window.Maskito = Maskito;
+      window.maskitoTransform = maskitoTransform;
     </script>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
 
@@ -39,10 +40,13 @@
       async function initPhoneMask() {
         const ionInput = document.querySelector('#phone');
         const nativeEl = await ionInput.getInputElement();
-
-        new window.Maskito(nativeEl, {
+        const phoneMaskOptions = {
           mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-        });
+        };
+        new window.Maskito(nativeEl, phoneMaskOptions);
+
+        //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+        ionInput.value = window.maskitoTransform('5555551212', phoneMaskOptions);
       }
 
       async function initCardMask() {

static/usage/v7/input/mask/javascript/index_html.md

@@ -12,10 +12,13 @@
   async function initPhoneMask() {
     const ionInput = document.querySelector('#phone');
     const nativeEl = await ionInput.getInputElement();
-
-    new window.Maskito(nativeEl, {
+    const phoneMaskOptions = {
       mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-    });
+    };
+    new window.Maskito(nativeEl, phoneMaskOptions);
+
+    //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+    ionInput.value = window.maskitoTransform('5555551212', phoneMaskOptions);
   }
 
   async function initCardMask() {

static/usage/v7/input/mask/javascript/index_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { defineCustomElements } from '@ionic/core/loader';
 
-import { Maskito } from '@maskito/core';
+import { Maskito, maskitoTransform } from '@maskito/core';
 
 /* Core CSS required for Ionic components to work properly */
 import '@ionic/core/css/core.css';
@@ -25,4 +25,5 @@ import './theme/variables.css';
 defineCustomElements();
 
 (window as any).Maskito = Maskito;
+(window as any).maskitoTransform = maskitoTransform;
 ```

static/usage/v7/input/mask/react.md

@@ -1,7 +1,8 @@
 ```tsx
-import React from 'react';
+import { useState } from 'react';
 import { IonInput, IonItem, IonList } from '@ionic/react';
 import { useMaskito } from '@maskito/react';
+import { MaskitoOptions, maskitoTransform } from '@maskito/core';
 
 function Example() {
   const cardMask = useMaskito({
@@ -20,11 +21,13 @@ function Example() {
     },
   });
 
-  const phoneMask = useMaskito({
-    options: {
-      mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-    },
-  });
+  const phoneMaskOptions: MaskitoOptions = {
+    mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
+  };
+  const phoneMask = useMaskito({ options: phoneMaskOptions });
+
+  //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  const [myPhoneNumber, setMyPhoneNumber] = useState(maskitoTransform('5555551212', phoneMaskOptions));
 
   return (
     <IonList>
@@ -48,6 +51,8 @@ function Example() {
               phoneMask(input);
             }
           }}
+          value={myPhoneNumber}
+          onIonInput={(e) => setMyPhoneNumber(e.detail.value || '')}
           label="US phone number"
           placeholder="+1 (xxx) xxx-xxxx"
         ></IonInput>

static/usage/v7/input/mask/vue.md

@@ -5,14 +5,21 @@
       <ion-input label="Card number" placeholder="0000 0000 0000 0000" v-maskito="cardOptions"></ion-input>
     </ion-item>
     <ion-item>
-      <ion-input label="US phone number" placeholder="+1 (xxx) xxx-xxxx" v-maskito="phoneOptions"></ion-input>
+      <ion-input
+        label="US phone number"
+        placeholder="+1 (xxx) xxx-xxxx"
+        v-model="myPhoneNumber"
+        v-maskito="phoneOptions"
+      ></ion-input>
     </ion-item>
   </ion-list>
 </template>
 
 <script setup lang="ts">
+  import { ref } from 'vue';
   import { IonInput, IonItem, IonList } from '@ionic/vue';
   import { maskito as vMaskito } from '@maskito/vue';
+  import { maskitoTransform } from '@maskito/core';
 
   const cardOptions = {
     mask: [
@@ -47,5 +54,7 @@
       });
     },
   };
+  // If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  const myPhoneNumber = ref(maskitoTransform('5555551212', phoneOptions));
 </script>
 ```

static/usage/v8/input/mask/angular/example_component_html.md

@@ -12,6 +12,7 @@
     <ion-input
       label="US phone number"
       placeholder="+1 (xxx) xxx-xxxx"
+      [(ngModel)]="myPhoneNumber"
       [maskito]="phoneMask"
       [maskitoElement]="maskPredicate"
     ></ion-input>

static/usage/v8/input/mask/angular/example_component_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { Component } from '@angular/core';
 
-import { MaskitoOptions, MaskitoElementPredicateAsync } from '@maskito/core';
+import { MaskitoOptions, MaskitoElementPredicateAsync, maskitoTransform } from '@maskito/core';
 
 @Component({
   selector: 'app-example',
@@ -12,6 +12,9 @@ export class ExampleComponent {
     mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
   };
 
+  //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  myPhoneNumber = maskitoTransform('5555551212', this.phoneMask);
+
   readonly cardMask: MaskitoOptions = {
     mask: [
       ...Array(4).fill(/\d/),

static/usage/v8/input/mask/demo.html

@@ -8,8 +8,9 @@
     <script src="../../common.js"></script>
     <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@8/dist/ionic/ionic.esm.js"></script>
     <script type="module">
-      import { Maskito } from 'https://cdn.jsdelivr.net/npm/@maskito/core/index.esm.js';
+      import { Maskito, maskitoTransform } from 'https://cdn.jsdelivr.net/npm/@maskito/core/index.esm.js';
       window.Maskito = Maskito;
+      window.maskitoTransform = maskitoTransform;
     </script>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@8/css/ionic.bundle.css" />
 
@@ -39,10 +40,13 @@
       async function initPhoneMask() {
         const ionInput = document.querySelector('#phone');
         const nativeEl = await ionInput.getInputElement();
-
-        new window.Maskito(nativeEl, {
+        const phoneMaskOptions = {
           mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-        });
+        };
+        new window.Maskito(nativeEl, phoneMaskOptions);
+
+        //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+        ionInput.value = window.maskitoTransform('5555551212', phoneMaskOptions);
       }
 
       async function initCardMask() {

static/usage/v8/input/mask/javascript/index_html.md

@@ -12,10 +12,13 @@
   async function initPhoneMask() {
     const ionInput = document.querySelector('#phone');
     const nativeEl = await ionInput.getInputElement();
-
-    new window.Maskito(nativeEl, {
+    const phoneMaskOptions = {
       mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-    });
+    };
+    new window.Maskito(nativeEl, phoneMaskOptions);
+
+    //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+    ionInput.value = window.maskitoTransform('5555551212', phoneMaskOptions);
   }
 
   async function initCardMask() {

static/usage/v8/input/mask/javascript/index_ts.md

@@ -1,7 +1,7 @@
 ```ts
 import { defineCustomElements } from '@ionic/core/loader';
 
-import { Maskito } from '@maskito/core';
+import { Maskito, maskitoTransform } from '@maskito/core';
 
 /* Core CSS required for Ionic components to work properly */
 import '@ionic/core/css/core.css';
@@ -25,4 +25,5 @@ import './theme/variables.css';
 defineCustomElements();
 
 (window as any).Maskito = Maskito;
+(window as any).maskitoTransform = maskitoTransform;
 ```

static/usage/v8/input/mask/react.md

@@ -20,11 +20,13 @@ function Example() {
     },
   });
 
-  const phoneMask = useMaskito({
-    options: {
-      mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
-    },
-  });
+  const phoneMaskOptions: MaskitoOptions = {
+    mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
+  };
+  const phoneMask = useMaskito({ options: phoneMaskOptions });
+
+  //If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  const [myPhoneNumber, setMyPhoneNumber] = useState(maskitoTransform('5555551212', phoneMaskOptions));
 
   return (
     <IonList>
@@ -48,6 +50,8 @@ function Example() {
               phoneMask(input);
             }
           }}
+          value={myPhoneNumber}
+          onIonInput={(e) => setMyPhoneNumber(e.detail.value || '')}
           label="US phone number"
           placeholder="+1 (xxx) xxx-xxxx"
         ></IonInput>

static/usage/v8/input/mask/vue.md

@@ -5,14 +5,21 @@
       <ion-input label="Card number" placeholder="0000 0000 0000 0000" v-maskito="cardOptions"></ion-input>
     </ion-item>
     <ion-item>
-      <ion-input label="US phone number" placeholder="+1 (xxx) xxx-xxxx" v-maskito="phoneOptions"></ion-input>
+      <ion-input
+        label="US phone number"
+        placeholder="+1 (xxx) xxx-xxxx"
+        v-model="myPhoneNumber"
+        v-maskito="phoneOptions"
+      ></ion-input>
     </ion-item>
   </ion-list>
 </template>
 
 <script setup lang="ts">
+  import { ref } from 'vue';
   import { IonInput, IonItem, IonList } from '@ionic/vue';
   import { maskito as vMaskito } from '@maskito/vue';
+  import { maskitoTransform } from '@maskito/core';
 
   const cardOptions = {
     mask: [
@@ -47,5 +54,7 @@
       });
     },
   };
+  // If you need to set an initial value, you can use maskitoTransform to ensure the value is valid
+  const myPhoneNumber = ref(maskitoTransform('5555551212', phoneOptions));
 </script>
 ```