feat(component): adds a pipe prop that allows for custom formatting on the input

Author: RonaldJerez

docs/component.md

@@ -51,3 +51,27 @@ let hexTokens = {
 <checkbox v-model="masked" />
 <display :value="value" />
 ```
+
+### Pipe through another function
+
+```js
+const piper = (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="##/##" :pipe="piper" />
+</example>
+
+<display :value="value" />
+```

src/component.vue

@@ -45,6 +45,17 @@ export default {
       type: Boolean,
       default: false
     },
+    /**
+     * A function to pipe the value through before commiting the value to the input element. The function
+     * will receipt an object with the masked and unmasked value after passing through the masker function.
+     * The result of this pipe function will determine what happens with the value.
+     * <br />
+     * If a string is returned, then that string will pass through the masker function once more and its value
+     * will be set to the input.  If false (boolean) is returned, the input will be rejected and the
+     * previous value will be restored.  Otherwise the facade logic will continue as usual.
+     * @since v1.2
+     */
+    pipe: Function,
     /**
      * Token object to override the defaults with
      */
@@ -85,7 +96,8 @@ export default {
     config() {
       return {
         mask: this.mask,
-        tokens: this.tokens
+        tokens: this.tokens,
+        pipe: this.pipe
       }
     },
     emittedValue() {

src/core.js

@@ -2,7 +2,7 @@ import masker from './masker'
 export const CONFIG_KEY = '__input-facade__'
 
 export function FacadeValue(val = '') {
-  this.masked = this.raw = val
+  this.masked = this.unmasked = val
 }
 
 /**
@@ -39,8 +39,8 @@ export function normalizeConfig(config = {}) {
 export function getInputElement(el) {
   const inputElement = el instanceof HTMLInputElement ? el : el.querySelector('input')
 
+  /* istanbul ignore next */
   if (!inputElement) {
-    /* istanbul ignore next */
     throw new Error('facade directive requires an input element')
   }
 
@@ -68,7 +68,7 @@ export function inputHandler(event) {
   const originalPosition = target.selectionEnd
   const { oldValue } = target[CONFIG_KEY]
 
-  updateValue(target, { emit: false })
+  updateValue(target, { emit: false }, event)
   updateCursor(event, originalValue, originalPosition)
 
   if (oldValue !== target.value) {
@@ -128,19 +128,31 @@ export function updateCursor(event, originalValue, originalPosition) {
  * Updates the element's value and unmasked value based on the masking config rules
  *
  * @param {HTMLInputElement} el The input element to update
- * @param {object} options
+ * @param {object} [options]
  * @param {Boolean} options.emit Wether to dispatch a new InputEvent or not
  * @param {Boolean} options.force Forces the update even if the old value and the new value are the same
+ * @param {Event} [event] The event that triggered this this update, null if not triggered by an input event
  */
-export function updateValue(el, { emit = true, force = false } = {}) {
+export function updateValue(el, { emit = true, force = false } = {}, event) {
   const { config, oldValue } = el[CONFIG_KEY]
 
   if (force || oldValue !== el.value) {
-    const newValue = masker(el.value, config)
+    let newValue = masker(el.value, config)
+
+    if (event && typeof config.pipe === 'function') {
+      const pipeValue = config.pipe(newValue, event)
+
+      if (typeof pipeValue === 'string') {
+        newValue = masker(pipeValue, config)
+      } else if (pipeValue === false) {
+        el.value = oldValue
+        return
+      }
+    }
 
     el[CONFIG_KEY].oldValue = newValue.masked
     el.value = newValue.masked
-    el.unmaskedValue = newValue.raw
+    el.unmaskedValue = newValue.unmasked
     emit && el.dispatchEvent(FacadeInputEvent())
   }
 }

src/masker.js

@@ -84,7 +84,7 @@ export function formatter(value = '', config = {}) {
 
       if (masker.pattern.test(char)) {
         char = masker.transform ? masker.transform(char) : char
-        output.raw += char
+        output.unmasked += char
         output.masked += accumulator + char
 
         accumulator = ''
@@ -100,9 +100,9 @@ export function formatter(value = '', config = {}) {
     }
   }
 
-  // if there is no raw value, set masked to empty to avoid
+  // if there is no unmasked value, set masked to empty to avoid
   // showing masking characters in an otherwise empty input
-  if (output.raw && !short) {
+  if (output.unmasked && !short) {
     output.masked += accumulator
   }
 

tests/component.test.js

@@ -61,4 +61,34 @@ describe('Component', () => {
     input.trigger('change')
     expect(wrapper.emitted().input).toBeTruthy()
   })
+
+  test('Adding a pipe function should call that function on input', async () => {
+    const piper = jest.fn()
+    const wrapper = createWrapper({ pipe: piper})
+
+    wrapper.element.value = '5555'
+    wrapper.find('input').trigger('input')
+
+    expect(piper).toHaveBeenCalled()
+  })
+
+  test('When pipe function returns false, do not change input value', async () => {
+    const piper = jest.fn().mockReturnValue(false)
+    const wrapper = createWrapper({ value: '1234', pipe: piper })
+
+    wrapper.element.value = '5555'
+    wrapper.find('input').trigger('input')
+
+    expect(wrapper.vm.maskedValue).toBe('1234')
+  })
+
+  test('When pipe function returns string, set value to masked string', async () => {
+    const piper = jest.fn().mockReturnValue('3344')
+    const wrapper = createWrapper({ mask: '##-##', pipe: piper })
+
+    wrapper.element.value = '5555'
+    wrapper.find('input').trigger('input')
+
+    expect(wrapper.vm.maskedValue).toBe('33-44')
+  })
 })

tests/dynamic.test.js

@@ -2,49 +2,49 @@ import { dynamic } from '../src/masker'
 
 test('empty', () => {
   var masks = []
-  expect(dynamic('12345', { masks })).toMatchObject({ masked: '', raw: '' })
+  expect(dynamic('12345', { masks })).toMatchObject({ masked: '', unmasked: '' })
 })
 
 test('single', () => {
   var masks = ['#.#']
-  expect(dynamic('12', { masks })).toMatchObject({ masked: '1.2', raw: '12' })
-  expect(dynamic('321', { masks })).toMatchObject({ masked: '3.2', raw: '32' })
+  expect(dynamic('12', { masks })).toMatchObject({ masked: '1.2', unmasked: '12' })
+  expect(dynamic('321', { masks })).toMatchObject({ masked: '3.2', unmasked: '32' })
 })
 
 test('CEP USA/BR', () => {
   var masks = ['#####', '#####-###']
-  expect(dynamic('12345', { masks })).toMatchObject({ masked: '12345', raw: '12345' })
-  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', raw: '123456' })
-  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '12345-678', raw: '12345678' })
+  expect(dynamic('12345', { masks })).toMatchObject({ masked: '12345', unmasked: '12345' })
+  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', unmasked: '123456' })
+  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '12345-678', unmasked: '12345678' })
 })
 
 test('Reverse CEP USA/BR', () => {
   var masks = ['#####-###', '#####']
-  expect(dynamic('12345', { masks })).toMatchObject({ masked: '12345', raw: '12345' })
-  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', raw: '123456' })
-  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '12345-678', raw: '12345678' })
+  expect(dynamic('12345', { masks })).toMatchObject({ masked: '12345', unmasked: '12345' })
+  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', unmasked: '123456' })
+  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '12345-678', unmasked: '12345678' })
 })
 
 test('cpf/cnpj', () => {
   var masks = ['###.###.###-##', '##.###.###/####-##']
-  expect(dynamic('12345678901', { masks })).toMatchObject({ masked: '123.456.789-01', raw: '12345678901' })
-  expect(dynamic('123456789012', { masks })).toMatchObject({ masked: '12.345.678/9012-', raw: '123456789012' })
+  expect(dynamic('12345678901', { masks })).toMatchObject({ masked: '123.456.789-01', unmasked: '12345678901' })
+  expect(dynamic('123456789012', { masks })).toMatchObject({ masked: '12.345.678/9012-', unmasked: '123456789012' })
 })
 
 test('bank agency', () => {
   var masks = ['####', '####-#', '####-##']
-  expect(dynamic('1234', { masks })).toMatchObject({ masked: '1234', raw: '1234' })
-  expect(dynamic('1234a', { masks })).toMatchObject({ masked: '1234', raw: '1234' })
-  expect(dynamic('12345', { masks })).toMatchObject({ masked: '1234-5', raw: '12345' })
-  expect(dynamic('123456', { masks })).toMatchObject({ masked: '1234-56', raw: '123456' })
+  expect(dynamic('1234', { masks })).toMatchObject({ masked: '1234', unmasked: '1234' })
+  expect(dynamic('1234a', { masks })).toMatchObject({ masked: '1234', unmasked: '1234' })
+  expect(dynamic('12345', { masks })).toMatchObject({ masked: '1234-5', unmasked: '12345' })
+  expect(dynamic('123456', { masks })).toMatchObject({ masked: '1234-56', unmasked: '123456' })
 })
 
 test('bank account', () => {
   //            12345      123456      1234567      12345678      123456789
   var masks = ['#####-#', '######-#', '#######-#', '########-#', '#########-#']
-  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', raw: '123456' })
-  expect(dynamic('1234567', { masks })).toMatchObject({ masked: '123456-7', raw: '1234567' })
-  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '1234567-8', raw: '12345678' })
-  expect(dynamic('123456789', { masks })).toMatchObject({ masked: '12345678-9', raw: '123456789' })
-  expect(dynamic('1234567890', { masks })).toMatchObject({ masked: '123456789-0', raw: '1234567890' })
+  expect(dynamic('123456', { masks })).toMatchObject({ masked: '12345-6', unmasked: '123456' })
+  expect(dynamic('1234567', { masks })).toMatchObject({ masked: '123456-7', unmasked: '1234567' })
+  expect(dynamic('12345678', { masks })).toMatchObject({ masked: '1234567-8', unmasked: '12345678' })
+  expect(dynamic('123456789', { masks })).toMatchObject({ masked: '12345678-9', unmasked: '123456789' })
+  expect(dynamic('1234567890', { masks })).toMatchObject({ masked: '123456789-0', unmasked: '1234567890' })
 })

tests/formatter.test.js

@@ -1,63 +1,66 @@
 import { formatter } from '../src/masker'
 
 test('default vals', () => {
-  expect(formatter('123')).toMatchObject({ masked: '', raw: '' })
+  expect(formatter('123')).toMatchObject({ masked: '', unmasked: '' })
 })
 
 test('12 -> #.#', () => {
-  expect(formatter('12', { mask: '#.#' })).toMatchObject({ masked: '1.2', raw: '12' })
+  expect(formatter('12', { mask: '#.#' })).toMatchObject({ masked: '1.2', unmasked: '12' })
 })
 
 test('1 -> (#)', () => {
   // placeholder at the end
-  expect(formatter('1', { mask: '(#)' })).toMatchObject({ masked: '(1)', raw: '1' })
+  expect(formatter('1', { mask: '(#)' })).toMatchObject({ masked: '(1)', unmasked: '1' })
 })
 
 test('1 -> [(#)]', () => {
   // two placeholder at the end
-  expect(formatter('1', { mask: '[(#)]' })).toMatchObject({ masked: '[(1)]', raw: '1' })
+  expect(formatter('1', { mask: '[(#)]' })).toMatchObject({ masked: '[(1)]', unmasked: '1' })
 })
 
 test('1 -> #..#', () => {
-  expect(formatter('1', { mask: '#..#', short: true })).toMatchObject({ masked: '1', raw: '1' })
+  expect(formatter('1', { mask: '#..#', short: true })).toMatchObject({ masked: '1', unmasked: '1' })
 })
 
 test('1 -> #.#', () => {
-  expect(formatter('1', { mask: '#.#' })).toMatchObject({ masked: '1.', raw: '1' })
+  expect(formatter('1', { mask: '#.#' })).toMatchObject({ masked: '1.', unmasked: '1' })
 })
 
 test('1. -> #.#', () => {
-  expect(formatter('1.', { mask: '#.#' })).toMatchObject({ masked: '1.', raw: '1' })
+  expect(formatter('1.', { mask: '#.#' })).toMatchObject({ masked: '1.', unmasked: '1' })
 })
 
 test('123 -> #.#', () => {
-  expect(formatter('123', { mask: '#.#' })).toMatchObject({ masked: '1.2', raw: '12' })
+  expect(formatter('123', { mask: '#.#' })).toMatchObject({ masked: '1.2', unmasked: '12' })
 })
 
 test('abc1234567 -> AAa-####', () => {
-  expect(formatter('abc1234567', { mask: 'AAa-####' })).toMatchObject({ masked: 'ABc-1234', raw: 'ABc1234' })
+  expect(formatter('abc1234567', { mask: 'AAa-####' })).toMatchObject({ masked: 'ABc-1234', unmasked: 'ABc1234' })
 })
 
 test('a5-12-34 -> (XX) - ## - ##', () => {
-  expect(formatter('a5-12-34', { mask: '(XX) - ## - ##' })).toMatchObject({ masked: '(a5) - 12 - 34', raw: 'a51234' })
+  expect(formatter('a5-12-34', { mask: '(XX) - ## - ##' })).toMatchObject({
+    masked: '(a5) - 12 - 34',
+    unmasked: 'a51234'
+  })
 })
 
 test('123 -> ##(#)', () => {
-  expect(formatter('123', { mask: '##(#)' })).toMatchObject({ masked: '12(3)', raw: '123' })
+  expect(formatter('123', { mask: '##(#)' })).toMatchObject({ masked: '12(3)', unmasked: '123' })
 })
 
 test('123 -> ##(#)', () => {
-  expect(formatter('12', { mask: '#\\#(#)' })).toMatchObject({ masked: '1#(2)', raw: '12' })
+  expect(formatter('12', { mask: '#\\#(#)' })).toMatchObject({ masked: '1#(2)', unmasked: '12' })
 })
 
 test('12 -> +1 #', () => {
-  expect(formatter('12', { mask: '+1 #' })).toMatchObject({ masked: '+1 2', raw: '2' })
+  expect(formatter('12', { mask: '+1 #' })).toMatchObject({ masked: '+1 2', unmasked: '2' })
 })
 
 test('2 -> +1 #', () => {
-  expect(formatter('2', { mask: '+1 #' })).toMatchObject({ masked: '+1 2', raw: '2' })
+  expect(formatter('2', { mask: '+1 #' })).toMatchObject({ masked: '+1 2', unmasked: '2' })
 })
 
 test('2 -> +1 # 5', () => {
-  expect(formatter('2', { mask: '+1 # 5' })).toMatchObject({ masked: '+1 2 5', raw: '2' })
+  expect(formatter('2', { mask: '+1 # 5' })).toMatchObject({ masked: '+1 2 5', unmasked: '2' })
 })

tests/masker.test.js

@@ -5,24 +5,24 @@ const tokens = {
 }
 
 test('no mask given', () => {
-  expect(masker('123')).toMatchObject({ masked: '123', raw: '123' })
+  expect(masker('123')).toMatchObject({ masked: '123', unmasked: '123' })
 })
 
 test('single mask given', () => {
-  expect(masker('12', { mask: '#.#' })).toMatchObject({ masked: '1.2', raw: '12' })
+  expect(masker('12', { mask: '#.#' })).toMatchObject({ masked: '1.2', unmasked: '12' })
 })
 
 test('multiple mask given', () => {
   const config = { mask: ['#.#', '##.#'] }
-  expect(masker('12', config)).toMatchObject({ masked: '1.2', raw: '12' })
-  expect(masker('123', config)).toMatchObject({ masked: '12.3', raw: '123' })
+  expect(masker('12', config)).toMatchObject({ masked: '1.2', unmasked: '12' })
+  expect(masker('123', config)).toMatchObject({ masked: '12.3', unmasked: '123' })
 })
 
 test('should just append to the tokens when passing them in locally', () => {
-  expect(masker('456DDS', { mask: '###-FFFF', tokens })).toMatchObject({ masked: '456-DD', raw: '456DD' })
+  expect(masker('456DDS', { mask: '###-FFFF', tokens })).toMatchObject({ masked: '456-DD', unmasked: '456DD' })
 })
 
 test('should override default tokens globally', () => {
   setTokens(tokens)
-  expect(masker('456DDS', { mask: '###-FFFF' })).toMatchObject({ masked: '###-456D', raw: '456D' })
+  expect(masker('456DDS', { mask: '###-FFFF' })).toMatchObject({ masked: '###-456D', unmasked: '456D' })
 })