feat(alternations): add support for alternations / pipe

Use a pipe character to indicate alternative static characters
ie: A|B-###

BREAKING CHANGE: The pipe character must be escaped if used as a static string.

Author: RonaldJerez

README.md

@@ -65,6 +65,7 @@ export default {
 + `\` = escape any of the above characters
 + `?` = mark the preceding character as optional [0 or 1]
 + `*` = mark the preceding character as optional & repeating [0 or more]
++ `|` = used for alternative static characters: A|B|C will accept A or B or C
 
 See the [token source file](https://github.com/RonaldJerez/vue-input-facade/blob/master/src/tokens.js) for definition signature
 

docs/component.md

@@ -56,6 +56,23 @@ let masked = true
 <display :value="value" />
 ```
 
+### Alternation (Pipe)
+
+Use a pipe symbol to indicate altarnative **static** values that can be used in the mask. This is case insensitive and can match letters irregarless of accents. For example å = A. Android webview and Opera dont fully support that type of matching.
+> *Note that because this only works with static values there is no need to escape characters that are also used as tokens.*
+
+```js
+let value = ''
+let masked = true
+
+<example label="ID Code">
+  <input-facade mask="A|B|C-####" v-model="value" :masked="masked" />
+</example>
+
+<checkbox v-model="masked" />
+<display :value="value" />
+```
+
 ### Dynamic Masks
 
 Accepts an array of masking pattern and dynamically chooses the appropriate one based on the number of characters in the field.

src/masker.js

@@ -3,6 +3,14 @@ import defaultTokens from './tokens'
 
 let tokenDefinitions = defaultTokens
 
+let isLocaleCompareSupported = false
+try {
+  // if supported this will throw a RangeError because 'i' is not a valid locale
+  'a'.localeCompare('b', 'i')
+} catch (e) {
+  isLocaleCompareSupported = e.name === 'RangeError'
+}
+
 /**
  * Overrides the default global token definitions
  *
@@ -81,7 +89,13 @@ export function formatter(value, config) {
     return {
       escape: !!masker?.escape,
       optional: !!nextMasker?.optional,
-      repeat: !!nextMasker?.repeat
+      repeat: !!nextMasker?.repeat,
+      ...(nextMasker?.pipe && {
+        pipe: mask
+          .substring(maskIndex)
+          .match(/^(.\|)+./g)[0]
+          .split('|')
+      })
     }
   }
 
@@ -90,9 +104,9 @@ export function formatter(value, config) {
     const masker = tokens[maskChar]
     let char = value[valueIndex]
 
-    if (masker && !escaped) {
-      const meta = getMetaData(masker)
+    const meta = getMetaData(masker)
 
+    if (masker && !escaped && !meta.pipe) {
       // when is escape char, do not mask, just continue
       if (meta.escape) {
         escaped = true
@@ -118,10 +132,24 @@ export function formatter(value, config) {
         continue
       }
 
+      valueIndex++
+    } else if (meta.pipe) {
+      if (!char) break
+
+      const pipeMatch = meta.pipe.find(looselyStringMatch.bind(null, char))
+
+      if (pipeMatch) {
+        output.unmasked += pipeMatch
+        output.masked += accumulator + pipeMatch
+
+        maskIndex += meta.pipe.length * 2 - 1
+        accumulator = ''
+      }
+
       valueIndex++
     } else {
       accumulator += maskChar
-      if (char?.toLocaleLowerCase() === maskChar?.toLocaleLowerCase()) {
+      if (looselyStringMatch(char, maskChar)) {
         // user typed the same char as static mask char
         valueIndex++
         output.masked += accumulator
@@ -142,6 +170,26 @@ export function formatter(value, config) {
   return output
 }
 
+/**
+ * Loosely compare two strings and returns if they are equal ignoring case and locale
+ * specific accents. Some browsers do not fully support this (Android webview and opera)
+ * so we fallback to just ignoring casing in those cases.
+ *
+ * @see [MDM - LocaleCompare](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)
+ *
+ * @param {String} str1 String one
+ * @param {String} str2 String two
+ * @returns Boolean
+ */
+export function looselyStringMatch(str1, str2) {
+  /* istanbul ignore else */
+  if (isLocaleCompareSupported) {
+    return str1?.localeCompare(str2, undefined, { sensitivity: 'base' }) === 0
+  } else {
+    return str1?.toLocaleLowerCase() === str2?.toLocaleLowerCase()
+  }
+}
+
 /**
  * Facade to formatter/dynamic when mask is String or Array
  *

src/tokens.js

@@ -6,5 +6,6 @@ export default {
   a: { pattern: /[a-z]/i, transform: (v) => v.toLocaleLowerCase() },
   '\\': { escape: true },
   '?': { optional: true },
-  '*': { repeat: true }
+  '*': { repeat: true },
+  '|': { pipe: true }
 }

tests/formatter.test.js

@@ -146,3 +146,21 @@ test('France IBAN', () => {
     unmasked: '7630006000011234567890189'
   })
 })
+
+describe('Alternations', () => {
+  test('When matching an alternation', () => {
+    expect(formatter('df1234', { mask: 'A|D###' })).toMatchObject({ masked: 'D123', unmasked: 'D123' })
+  })
+
+  test('When not matching an alternation', () => {
+    expect(formatter('1234', { mask: 'A|D###' })).toMatchObject({ masked: '', unmasked: '' })
+  })
+
+  test('When having multiple alternations', () => {
+    expect(formatter('D123455F', { mask: 'A|D###D|F|G' })).toMatchObject({ masked: 'D123F', unmasked: 'D123F' })
+  })
+
+  test('When having characters with accents or different casing', () => {
+    expect(formatter('é123455F', { mask: 'A|E###e|f' })).toMatchObject({ masked: 'E123f', unmasked: 'E123f' })
+  })
+})