npm package: @ionited/mask
Description: Create your masks easily
Author: Ion
Latest version: 0.7.0

# Mask

> Create your masks easily

Mask comes with three basic implementations MaskDefault, MaskNumber and MaskDate, but you can use MaskCore to do your own masks implementation easily.

## Quick start

Choose your favorite option below:

### Install with NPM

```
npm i @ionited/mask
```

### Get from UNPKG

[https://unpkg.com/@ionited/mask@latest/dist/mask.js](https://unpkg.com/@ionited/mask@latest/dist/mask.js)

---

## Usage

To basic usage you can simply call:

```js
Mask(document.querySelector('#input1'), { mask: '(99) 9999-9999' }); // To use MaskDefault
Mask(document.querySelector('#input2'), { number: true }); // To use MaskNumber
Mask(document.querySelector('#input3'), { date: 'DD/MM/YYYY' }); // To use MaskDate
```

### MaskDefault

A mask that receives a regex or a string with numbers, letters or other symbols

```ts
Mask(el: HTMLElement, { mask: RegExp | string | MaskDefaultOptions });

interface MaskDefaultOptions {
  allowEmpty?: boolean;
  mask: RegExp | string;
}
```

| Symbol   | Pattern          | Description
|:--------:|------------------|-------------
| 9        | `/^[0-9]$/`      | Only numbers
| A        | `/^[A-Za-zÀ-ÿ]$/`| Only letters

Any other symbol is fixed.

### MaskNumber

A mask for monetary and decimal values

```ts
Mask(el: HTMLElement, { number: true | MaskNumberOptions });

interface MaskNumberOptions {
  allowEmpty: boolean;
  allowNegative: boolean;
  decimal: number;
  decimalPoint: string;
  end: boolean;
  prefix: string;
  suffix: string;
  thousandPoint: string;
}
```

### MaskDate

A mask for date and time values

```ts
Mask(el: HTMLElement, { date: string | MaskDateOptions });

interface MaskDateOptions {
  format: string;
  placeholders: { [key: string]: string };
}
```

| Format    | Pattern | Description
|:---------:|---------|-------------
| YYYY      | 0000-∞  | Year
| MM        | 01-12   | Month
| DD        | 01-31   | Day
| hh        | 00-23   | Hour
| mm        | 00-59   | Minutes
| ss        | 00-59   | Seconds

Any other symbol is fixed.

### MaskCore

You can create your own mask logic easily, you only need `register` a mask and use:

```ts
Mask.register(name: string, mask: any): void;
```

The recommended way to do a new mask is writing a class that extends `MaskOptions`

```ts
interface MaskOptions {
  instance: MaskCore;
  init?(data: MaskData): void;
  input?(data: MaskData): void;
  format(data: MaskData): void;
  focus?(data: MaskData): void;
  blur?(data: MaskData): void;
  mouseover?(data: MaskData): void;
  mouseout?(data: MaskData): void;
}

interface MaskData {
  cursorPosition: number;
  delete: boolean;
  focus: boolean;
  input: string;
  output: string;
  outputRaw: any;
}
```

MyMask example (only accept numbers):

```ts
import { MaskData, MaskCore, MaskOptions } from '@ionited/mask/core';

export class MyMask implements MaskOptions {
  instance: MaskCore;

  constructor(el: HTMLInputElement) {
    this.instance = new MaskCore(el, this);
  }

  init(data: MaskData) {
    this.format(data);
  }

  format(data: MaskData) {
    data.output = data.input.replace(/[^0-9]/g, ''); 
  }
}
```

Register and use:

```ts
Mask.register('myMask', MyMask); // Register

Mask(document.querySelector('#myMask'), { myMask: true }); // Enjoy your own mask!
```

## License

Copyright (c) 2021 Ion. Licensed under [MIT License](LICENSE).

[https://ionited.io](https://ionited.io)