docs(input): input masking examples

docs/api/input.md

@@ -120,6 +120,26 @@ import FilteringData from '@site/static/usage/v7/input/filtering/index.md';
 
 <FilteringData />
 
+## Input Masking
+
+Input masks are expressions that constrain input to support valid input values. Ionic recommends using [Maskito](https://tinkoff.github.io/maskito/getting-started/what-is-maskito) for input masking. Maskito is a lightweight, dependency-free library for masking input fields. It supports a wide range of masks, including phone numbers, credit cards, dates, and more.
+
+To get started with Maskito, install the library:
+
+```bash
+npm install @maskito/core @maskito/{angular,react,vue}
+```
+
+import Masking from '@site/static/usage/v7/input/mask/index.md';
+
+<Masking />
+
+:::note
+
+Please submit bug reports with Maskito to the [Maskito Github repository](https://github.com/Tinkoff/maskito/issues). For technical support, please use the [Ionic Forum](https://forum.ionicframework.com/) or [Ionic Discord](http://chat.ionicframework.com/).
+
+:::
+
 ## Theming
 
 ### Colors

src/components/global/Playground/stackblitz.utils.ts

@@ -183,6 +183,15 @@ const openReactEditor = async (code: string, options?: EditorOptions) => {
     options.version
   );
 
+  const package_json = JSON.parse(defaultFiles[4]);
+
+  if (options?.dependencies) {
+    package_json.dependencies = {
+      ...package_json.dependencies,
+      ...options.dependencies,
+    };
+  }
+
   const appTsx = 'src/App.tsx';
   const files = {
     'public/index.html': defaultFiles[6],
@@ -191,7 +200,7 @@ const openReactEditor = async (code: string, options?: EditorOptions) => {
     'src/main.tsx': code,
     'src/theme/variables.css': defaultFiles[2],
     'tsconfig.json': defaultFiles[3],
-    'package.json': defaultFiles[4],
+    'package.json': JSON.stringify(package_json, null, 2),
     'package-lock.json': defaultFiles[5],
     ...options?.files,
     ...options?.dependencies,
@@ -227,6 +236,15 @@ const openVueEditor = async (code: string, options?: EditorOptions) => {
     options.version
   );
 
+  const package_json = JSON.parse(defaultFiles[0]);
+
+  if (options?.dependencies) {
+    package_json.dependencies = {
+      ...package_json.dependencies,
+      ...options.dependencies,
+    };
+  }
+
   const mainTs = 'src/main.ts';
   const files = {
     'src/App.vue': defaultFiles[6],
@@ -236,7 +254,7 @@ const openVueEditor = async (code: string, options?: EditorOptions) => {
     'src/theme/variables.css': defaultFiles[3],
     'index.html': defaultFiles[2],
     'vite.config.ts': defaultFiles[4],
-    'package.json': defaultFiles[0],
+    'package.json': JSON.stringify(package_json, null, 2),
     'package-lock.json': defaultFiles[1],
     'tsconfig.json': defaultFiles[7],
     'tsconfig.node.json': defaultFiles[8],

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

@@ -0,0 +1,19 @@
+```ts
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { BrowserModule } from '@angular/platform-browser';
+
+import { IonicModule } from '@ionic/angular';
+
+import { AppComponent } from './app.component';
+import { ExampleComponent } from './example.component';
+
+import { MaskitoModule } from '@maskito/angular';
+
+@NgModule({
+  imports: [BrowserModule, FormsModule, MaskitoModule, IonicModule.forRoot({})],
+  declarations: [AppComponent, ExampleComponent],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```

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

@@ -0,0 +1,20 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-input
+      label="Card number"
+      placeholder="0000 0000 0000 0000"
+      [maskito]="cardMask"
+      [maskitoElement]="maskPredicate"
+    ></ion-input>
+  </ion-item>
+  <ion-item>
+    <ion-input
+      label="US phone number"
+      placeholder="+1 (xxx) xxx-xxxx"
+      [maskito]="phoneMask"
+      [maskitoElement]="maskPredicate"
+    ></ion-input>
+  </ion-item>
+</ion-list>
+```

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

@@ -0,0 +1,31 @@
+```ts
+import { Component } from '@angular/core';
+
+import { MaskitoOptions, MaskitoElementPredicateAsync } from '@maskito/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+})
+export class ExampleComponent {
+  readonly phoneMask: MaskitoOptions = {
+    mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
+  };
+
+  readonly cardMask: MaskitoOptions = {
+    mask: [
+      ...Array(4).fill(/\d/),
+      ' ',
+      ...Array(4).fill(/\d/),
+      ' ',
+      ...Array(4).fill(/\d/),
+      ' ',
+      ...Array(4).fill(/\d/),
+      ' ',
+      ...Array(4).fill(/\d/),
+    ],
+  };
+
+  readonly maskPredicate: MaskitoElementPredicateAsync = async (el) => (el as HTMLIonInputElement).getInputElement();
+}
+```

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

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Input</title>
+    <link rel="stylesheet" href="../../../common.css" />
+    <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';
+      window.Maskito = Maskito;
+    </script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
+
+    <style>
+      ion-list {
+        width: 100%;
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-list>
+            <ion-item>
+              <ion-input id="card" label="Card number" placeholder="0000 0000 0000 0000"></ion-input>
+            </ion-item>
+            <ion-item>
+              <ion-input id="phone" label="US phone number" placeholder="+1 (xxx) xxx-xxxx"></ion-input>
+            </ion-item>
+          </ion-list>
+        </div>
+      </ion-content>
+    </ion-app>
+    <script>
+      async function initPhoneMask() {
+        const ionInput = document.querySelector('#phone');
+        const nativeEl = await ionInput.getInputElement();
+
+        new window.Maskito(nativeEl, {
+          mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
+        });
+      }
+
+      async function initCardMask() {
+        const ionInput = document.querySelector('#card');
+        const nativeEl = await ionInput.getInputElement();
+
+        new window.Maskito(nativeEl, {
+          mask: [
+            ...Array(4).fill(/\d/),
+            ' ',
+            ...Array(4).fill(/\d/),
+            ' ',
+            ...Array(4).fill(/\d/),
+            ' ',
+            ...Array(4).fill(/\d/),
+            ' ',
+            ...Array(4).fill(/\d/),
+          ],
+        });
+      }
+
+      window.addEventListener('appload', () => {
+        initCardMask();
+        initPhoneMask();
+      });
+    </script>
+  </body>
+</html>

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

@@ -0,0 +1,58 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript_index_html from './javascript/index_html.md';
+import javascript_index_ts from './javascript/index_ts.md';
+
+import react_main_tsx from './react.md';
+
+import vue_example_vue from './vue.md';
+
+import angular_app_module_ts from './angular/app_module_ts.md';
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  version="7"
+  code={{
+    javascript: {
+      files: {
+        'index.html': javascript_index_html,
+        'index.ts': javascript_index_ts,
+      },
+      dependencies: {
+        '@maskito/core': '^0.16.0',
+      },
+    },
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+      },
+      dependencies: {
+        '@maskito/react': '^0.16.0',
+        '@maskito/core': '^0.16.0',
+      },
+    },
+    vue: {
+      files: {
+        'src/components/Example.vue': vue_example_vue,
+      },
+      dependencies: {
+        '@maskito/vue': '^0.16.0',
+        '@maskito/core': '^0.16.0',
+      },
+    },
+    angular: {
+      files: {
+        'src/app/app.module.ts': angular_app_module_ts,
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+      dependencies: {
+        '@maskito/angular': '^0.16.0',
+        '@maskito/core': '^0.16.0',
+      },
+    },
+  }}
+  src="usage/v7/input/mask/demo.html"
+  size="300px"
+/>

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

@@ -0,0 +1,58 @@
+```html
+<html>
+  <head>
+    <link rel="stylesheet" type="text/css" href="https://cdn.skypack.dev/@ionic/core@7/css/core.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.skypack.dev/@ionic/core@7/css/ionic.bundle.css" />
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content class="ion-padding">
+        <ion-list>
+          <ion-item>
+            <ion-input id="card" label="Card number" placeholder="0000 0000 0000 0000"></ion-input>
+          </ion-item>
+          <ion-item>
+            <ion-input id="phone" label="US phone number" placeholder="+1 (xxx) xxx-xxxx"></ion-input>
+          </ion-item>
+        </ion-list>
+      </ion-content>
+
+      <script>
+        async function initPhoneMask() {
+          const ionInput = document.querySelector('#phone');
+          const nativeEl = await ionInput.getInputElement();
+
+          new window.Maskito(nativeEl, {
+            mask: ['+', '1', ' ', '(', /\d/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/],
+          });
+        }
+
+        async function initCardMask() {
+          const ionInput = document.querySelector('#card');
+          const nativeEl = await ionInput.getInputElement();
+
+          new window.Maskito(nativeEl, {
+            mask: [
+              ...Array(4).fill(/\d/),
+              ' ',
+              ...Array(4).fill(/\d/),
+              ' ',
+              ...Array(4).fill(/\d/),
+              ' ',
+              ...Array(4).fill(/\d/),
+              ' ',
+              ...Array(4).fill(/\d/),
+            ],
+          });
+        }
+
+        window.addEventListener('appload', () => {
+          initCardMask();
+          initPhoneMask();
+        });
+      </script>
+    </ion-app>
+  </body>
+</html>
+```

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

@@ -0,0 +1,28 @@
+```ts
+import { defineCustomElements } from '@ionic/core/loader';
+
+import { Maskito } from '@maskito/core';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/core/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/core/css/normalize.css';
+import '@ionic/core/css/structure.css';
+import '@ionic/core/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/core/css/padding.css';
+import '@ionic/core/css/float-elements.css';
+import '@ionic/core/css/text-alignment.css';
+import '@ionic/core/css/text-transformation.css';
+import '@ionic/core/css/flex-utils.css';
+import '@ionic/core/css/display.css';
+
+/* Theme variables */
+import './theme/variables.css';
+
+defineCustomElements();
+
+(window as any).Maskito = Maskito;
+```