chore: Merge branch 'beta'

Author: RonaldJerez

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## Description
+A few sentences describing the overall goals of the pull request's commits.
+
+## Checklist
+- [ ] Tests
+- [ ] Documentation
+- [ ] Used commitizen and followed [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+- [ ] Commit footer references issue num. If applicable.

README.md

@@ -84,15 +84,35 @@ See the [token source file](https://github.com/RonaldJerez/vue-input-facade/blob
 <input type="text" v-facade="'##/##/##'" />
 ```
 
-See [demo page](https://ronaldjerez.github.io/vue-input-facade) for more usage examples
+### Migrating existing projects
 
-## Thanks
+If you are migrating an existing project to vue-input-facade from another plugin and dont want to touch the whole codebase.  You may pass options during plugin installation to override the default tokens or directive name.
 
-Thanks to [Marcos Neves](https://vuejs-tips.github.io/) for the vue-the-mask component of which this vue-input-facade was originally forked from.
+```javascript
+import InputFacade from 'vue-input-facade'
+
+// migrating from v-mask
+const options = {
+  // rename the directive from: v-facade to: v-mask
+  name: 'mask',
+
+  // use these tokens instead of the default
+  tokens: {
+    '#': { pattern: /\d/ },
+    'A': { pattern: /[a-z]/i },
+    'N': { pattern: /[0-9a-z]/i },
+    'X': { pattern: /./ }
+  }
+}
+
+Vue.use(InputFacade, options)
+```
+
+See [demo page](https://ronaldjerez.github.io/vue-input-facade) for more usage examples
 
 ## Contribution
 
-You're free to contribute to this project by submitting Issues and/or pull requests. This project is test-driven, so keep in mind that every change and new feature should be covered by tests.
+You're free to contribute to this project by submitting issues and/or pull requests. This project is test-driven, so keep in mind that every change and new feature should be covered by tests.  The project uses [semantic-release](https://github.com/semantic-release/semantic-release) to release new versions, therefore all commit messages should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary), we are using [commitizen](https://github.com/commitizen/cz-cli) to facilitate writting the commit messages.
 
 ## License
 

docs/advanced.md

@@ -6,10 +6,11 @@ If you are migrating an existing project to vue-input-facade from another plugin
 import InputFacade from 'vue-input-facade'
 
 // migrating from v-mask
-// the directive will now be v-mask instead of v-facade
-// and all the tokens will be replaced globally by the following
 const options = {
+  // rename the directive from: v-facade to: v-mask
   name: 'mask',
+
+  // use these tokens instead of the default
   tokens: {
     '#': { pattern: /\d/ },
     'A': { pattern: /[a-z]/i },

docs/component.md

@@ -17,20 +17,27 @@ let masked = false
 Accepts an array of masking pattern and dynamically chooses the appropriate one based on the number of characters in the field.
 
 ```js
-let value = ''
-let masked = true
+let USPostal = ''
+let UKPostal = ''
 
+let masked = true
 <example label="US Zip Code">
-  <input-facade v-model="value" :mask="['#####', '#####-####']" :masked="masked" />
+  <input-facade v-model="USPostal" :mask="['#####', '#####-####']" :masked="masked" />
+</example>
+
+<example label="UK Postal Code">
+  <input-facade v-model="UKPostal" :mask="['A# #AA', 'AXX #AA', 'AA#X #AA']" :masked="masked" />
 </example>
 
 <checkbox v-model="masked" />
-<display :value="value" />
+<display label="Zip Code" :value="USPostal" />
+<display label="Postal Code" :value="UKPostal" />
 ```
 
 ### Custom Tokens
 
 You can override the tokens on a per field basis. Just pass in your own token definition to the field.
+This can also be used to add internatilization support.
 
 ```js
 let value = ''
@@ -50,3 +57,52 @@ let hexTokens = {
 <checkbox v-model="masked" />
 <display :value="value" />
 ```
+
+### Post masking input formatter
+
+Returning a string in the format function will re-run that value through the masker routine, Ensuring that the end result still confirms to the mask.
+
+```js
+const date = (value, event) => {
+  // do not format on deletion, this could leave the input in bad state
+  // but allows user to delete the leading 0 if needed for some reason
+  if (event.inputType !== 'deleteContentBackward') {
+    const [ month ] = value.masked.split('/')
+
+    if (month > 12) {
+      return '0' + value.unmasked
+    }
+  }
+}
+
+let value = ''
+
+<example label="Date as MM/YY">
+  <input-facade v-model="value" mask="##/##" :formatter="date" />
+</example>
+
+<display :value="value" />
+```
+
+Returning a boolean `true` will leave the masked or unmasked value as is, the value is passed by reference so if you modify them here, that will be their final value.  However if a `false` is returned, the user's input will be ignored and the value will remain as it was prior.
+
+```js
+const evenMoney = (value, event) => {
+  if (event.data && event.data % 2 !== 0) {
+    // odd number, ignore it
+    return false
+  } else if (value.unmasked) {
+    const formatted = value.unmasked.match(/\d{1,3}/g).join(',')
+    value.masked = `\$${formatted}`
+    return true
+  }
+}
+
+let value = ''
+
+<example label="Enter an even num">
+  <input-facade v-model="value" mask="#########" :formatter="evenMoney" masked />
+</example>
+
+<display :value="value" />
+```

docs/directive.md

@@ -1,9 +1,9 @@
-For times when you cannot use the component, you may use the directive instead. The directive has all the same features as the component, however the interface may not be as straight forward as using a component.
+For times when you cannot use the component, you may use the directive instead. The directive has all the same features as the component, however the interface may not be as straight forward as using a component.  The `prefill` and `short` features may passed in to the directive as modifiers.
 
 ### Basic usage
 
 ```js
-let value = ''
+let value = '12A789MM'
 
 <example label="Order number">
   <input type="text" v-model="value" v-facade="'XXX-###-AA'">
@@ -16,11 +16,13 @@ let value = ''
 
 You have access to the unmasked value via the input event.  The `unmaskedValue` property can be found as part of the `target` property of the input event.
 
+> Note: Some 3rd party components may not pass the `event` parameter when emitting input, such is the case with vuetify's v-text-input.  In this case you can listen to the native event so you can still access the unmasked value.  ex: `v-on:input.native="handler"`.
+
 ```js
 let event = ''
 
 <example label="Enter your phone number">
-  <input type="tel" v-facade="'(###) ### - ####'" @input="event = $event">
+  <input type="tel" v-facade="'(###) ### - ####'" v-on:input="event = $event">
 </example>
 
 <display :value="event" />