@ui-toolkit/directives/README.md

Directives for Vue.

# directives

## Installation

```sh
npm i @ui-toolkit/directives
```

```js
import Vue from 'vue';
import { mask } from '@ui-toolkit/directives';

const directives = { mask };

Object.keys(directives).forEach(key => {
  Vue.directive(key, directives[key]);
});
```

may also be installed locally to a component

```js
import { mask } from '@ui-toolkit/directives';

export default {
  directives: {
    mask,
  },
};
```

## Mask

**A vue.js package that provides a directive to apply a mask to input tags**

### TL;DR;

A`"mask"`directive for Vue.js that sets the **masked** and **unmasked** value of an`"input"`component (eg the `"v-text-field"` component from vuetify)

- "v-model" will always contain the masked value, the directive may also set the unmasked value to a specified variable (see below)
- provides predefined masks (see below)
- allows setting custom tokens for flexibility

### Usage

there are two ways to set the variable used for the unmasked value. You can specify the variable name in a config object, or you can use an argument to name the variable.

config:

```vue
<input
  v-model="expirationDate"
  v-mask="{ mask: '##/##', unmaskedVar: 'unmaskedExpirationDate' }"
/>
```

Argument:

```vue
<input v-model="expirationDate" v-mask:unmaskedExpirationDate="'##/##'" />
```

in this example, unmaskedExpirationDate is a value in the data object of the component for the unmasked value to bind to.

more usage examples:

```vue
<v-text-field v-model="..." v-mask="{ mask: 'A##', unmaskedVar: 'myVar' }" />
<v-text-field v-model="..." v-mask="'A#'" />
<v-text-field v-mask:unmaskedVar="'A#'" />
<v-text-field v-model="..." v-mask.number="{ mask: '##', unmaskedVar: 'myVar' }" />
<v-text-field v-model="..." v-mask="{ mask: '##', unmaskedVar: 'myVar', number: true }" />
```

**v-mask** may be:

- a mask (string) made of "tokens" (listed below)
- the name of a predefined mask (from the ones listed below)
- an "object" with the following attributes:

  - `mask`: same as above
  - `unmaskedVar`: name of a variable defined in the "data" section of the component that will receive the "unmasked" text. It may be a structure (eg`"a.bc.d"`), but the first "level" must exists
  - `nullIfEmpty` (Defaults to **false** ): Set `"unmaskedVar"` to null if the input value is empty.
  - `number` (Defaults to **false**): Try to cast the valof of `"unmaskedVar"` to a numbe (see below)
  - `tokens` (Defaults to the default ones below): An array of token objects that will replace the default ones. eg `tokens="[{ 'Y': {pattern: /[0-9]/ }]"`

### Tokens (From vue-the-mask)

- `'#': {pattern: /\d/}`
- `'X': {pattern: /[0-9a-zA-Z]/}`
- `'S': {pattern: /[a-zA-Z]/}`
- `'A': {pattern: /[a-zA-Z]/, transform: v => v.toLocaleUpperCase()}`
- `'a': {pattern: /[a-zA-Z]/, transform: v => v.toLocaleLowerCase()}`
- `'!': {escape: true}`

### Predefined masks (Most from vuetify v1.5.x)

- `credit-card: '#### - #### - #### - ####'`
- `credit-card2: '#### #### #### ####'`
- `date: '##/##/####'`
- `date-iso: '####-##-##'`
- `date-with-time: '##/##/#### ##:##'`
- `phone: '(###) ###-####'`
- `phone2: '### ###-####'`
- `intlPhone: ['(###) ###-####', '+# (###) ###-####', '+## (###) ###-####', '+### (###) ###-####',]`
- `social: '###-##-####'`
- `time: '##:##'`
- `time-with-seconds: '##:##:##'`
- `postalcode-ca: 'A#A #A#'`

### Modifiers

`.number`: The value set to`unmaskedVar`is typecast as a number. If the value cannot be parsed with parseFloat(), then the original value is returned.

### Dynamic Masks

You can use an array of masks, the value will default to the shortest matching mask.

```vue
<v-text-field v-model="..." v-mask="['####', '##-###', '#-####-#']" /> // 1234 -> 1234 //
12345 -> 12-345 // 123456 -> 1-2345-6
```

### Credits?

This package was forked from @titou10/v-mask.

Most of the credit goes to:

- [vuetify v1.5.x code](https://github.com/vuetifyjs/vuetify/blob/v1.5.18/packages/vuetify/src/util/mask.ts)
- [vue-the-mask](https://github.com/vuejs-tips/vue-the-mask)
- [RonaldJerez/vue-the-mask](https://github.com/RonaldJerez/vue-the-mask)
- [@titou10/v-mask](https://github.com/titou10titou10/v-mask)