igniteui-angular-sovn/src/lib/directives/mask/README.md

Ignite UI for Angular is a dependency-free Angular toolkit for building modern web apps

# igxMask

The **igxMask** directive is intended to provide means for controlling user input and formatting the visible value based on a configurable mask rules.

The following built-in mask rules should be supported:

    0: requires a digit (0-9).
    9: requires a digit (0-9) or a space.
    #: requires a digit (0-9), plus (+), or minus (-) sign.
    L: requires a letter (a-Z).
    ?: Requires a letter (a-Z) or a space.
    A: requires an alphanumeric (0-9, a-Z).
    a: requires an alphanumeric (0-9, a-Z) or a space.
    &: any keyboard character (excluding space).
    C: any keyboard character.

Static symbols (literals) in the mask pattern are also supported.

# Usage

```typescript
import { IgxMaskModule } from "igniteui-angular-sovn";
```

Use the `igxMask` input property on an input element to apply a mask. The **igxMask** directive is fully supported only on an input element of type **text**.

```html
<input type="text" igxInput [(ngModel)]="1234567890" [igxMask]="'(000) 0000-000'" />
```

Use the `includeLiterals` input property to include/exclude the mask literals from the raw value.

```typescript
public myValue = "1234567890";
public myMask = "(000) 0000-000";
public includeLiterals = true;
```

```html
<input type="text" igxInput [(ngModel)]="myValue" [igxMask]="myMask" [includeLiterals]="includeLiterals" />
```

Attach to the `valueChanged` event to implement custom logic when the value changes. Both, raw and formatted value, are accessible through the event payload.

```typescript
let raw: string;
let formatted: string;

handleValueChanged(event) {
  this.raw = event.rawValue;
  this.formatted = event.formattedValue;
}
```

```html
<input type="text" igxInput [(ngModel)]="1234567890" [igxMask]="'(000) 0000-000'" (valueChanged)="handleValueChanged($event)" />
```

Use the `placeholder` input property to specify the placeholder attribute of the host input element that the `igxMask` is applied on.

```typescript
placeholder = "hello";
```

```html
<input type="text" igxInput [igxMask]="'CCCCCC'" [placeholder]="placeholder" />
```

Use the `focusedValuePipe` and `displayValuePipe` input properties to additionally transform the value on focus and blur.

```typescript
@Pipe({ name: "displayFormat" })
export class DisplayFormatPipe implements PipeTransform {
    transform(value: any): string {
        return value.toLowerCase();
    }
}

displayFormat = new DisplayFormatPipe();
```

```html
<input type="text" igxInput [igxMask]="'CCCCCC'" [displayValuePipe]="displayFormat" />
```

### API

### Inputs

|        Name        | Type            | Description                                               |
| :----------------: | :-------------- | :-------------------------------------------------------- |
|       `mask`       | `String`        | Represents the current mask.                              |
|    `promptChar`    | `String`        | Character representing a fillable spot in the mask.       |
| `includeLiterals`  | `Boolean`       | Include or exclude literals in the raw value.             |
|   `placeholder`    | `string`        | Specifies a short hint that describes the expected value. |
| `displayValuePipe` | `PipeTransform` | A pipe to transform the input value on blur.              |
| `focusedValuePipe` | `PipeTransform` | A pipe to transform the input value on focus.             |

### Outputs

|      Name      | Return Type | Description                        |
| :------------: | :---------- | :--------------------------------- |
| `valueChanged` | `void`      | Fires each time the value changes. |