feat(QInput): new prop -> mask-tokens #18114 #12759

Author: rstoenescu

docs/src/examples/QInput/MaskCustomTokens.vue

@@ -0,0 +1,32 @@
+<template>
+  <div class="q-pa-md" style="max-width: 300px">
+    <div class="q-gutter-md">
+      <q-input
+        filled
+        v-model="id"
+        label="Special ID"
+        mask="AA-CC-XX-CC"
+        :mask-tokens="customTokens"
+        hint="Mask: AA-CC-XX-CC, example: BC-12-56-E2"
+      />
+
+      <div>C (0-4a-eA-E to uppercase), X override (5-8)</div>
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+
+export default {
+  setup () {
+    return {
+      id: ref(null),
+      customTokens: {
+        C: { pattern: '[0-4a-eA-E]', negate: '[^0-4a-eA-E]', transform: v => v.toLocaleUpperCase() },
+        X: { pattern: '[5-8]', negate: '[^5-8]' }
+      }
+    }
+  }
+}
+</script>

docs/src/pages/vue-components/input.md

@@ -163,7 +163,7 @@ You can force/help the user to input a specific format with help from `mask` pro
 Mask is only available if the `type` is one of 'text' (default), 'search', 'url', 'tel', or 'password'.
 :::
 
-Below are mask tokens:
+Below are the default mask tokens. To add your own, see the next section.
 
 | Token | Description |
 | --- | --- |
@@ -189,6 +189,14 @@ The `reverse-fill-mask` is useful if you want to force the user to fill the mask
 
 <DocExample title="Filling the mask in reverse" file="MaskFillReverse" />
 
+### Custom mask tokens <q-badge label="v2.18.4+" />
+
+You can also define custom mask tokens on top of the default ones or even override some/all of the [default ones](https://github.com/quasarframework/quasar/blob/dev/ui/src/components/input/use-mask.js#L15).
+
+The custom mask tokens must have the same syntax as the [default ones](https://github.com/quasarframework/quasar/blob/dev/ui/src/components/input/use-mask.js#L15). Please note that the `transform` property is optional.
+
+<DocExample title="Custom tokens" file="MaskCustomTokens" />
+
 ### Using third party mask processors
 
 You can easily use any third party mask processor by doing a few small adjustments to your QInput.

ui/playground/src/pages/form/input-mask.vue

@@ -5,7 +5,7 @@
 
       <div>Model: {{ text1 }} | {{ maskedOrNotValue }}</div>
       <q-toggle v-model="maskedOrNot" @update:model-value="toggleMask" label="Masked or not" />
-      <q-input :mask="maskedOrNotValue" v-model="text1" filled hint="Date ####/##/##" label="Label" />
+      <q-input :mask="maskedOrNotValue" v-model="text1" filled hint="Date ##/##/####" label="Label" />
       <q-input
         filled
         v-model="id"
@@ -62,6 +62,17 @@
         hint="Mask: NNNN - NNNN"
       />
 
+      <div>Custom tokens ((C: 0-4a-eA-E, X override: 5-8))</div>
+      <q-input
+        filled
+        v-model="text10"
+        label="Custom tokens"
+        mask="AA-CC-XX-CC"
+        :mask-tokens="customTokens"
+        clearable
+        hint="Mask: AA-CC-XX-CC"
+       />
+
       <div class="text-h6">
         Live mask test: {{ textMask }}
       </div>
@@ -128,6 +139,7 @@ export default {
       text7: '',
       text8: '',
       text9: '',
+      text10: 'KK-A4-76-1A',
       variableMaskValue1: '',
       variableMaskValue2: '',
       variableMaskValue3: '',
@@ -139,7 +151,12 @@ export default {
       fillRight: true,
       fillMask: true,
       fillUnmask: false,
-      fillMaskText: '0'
+      fillMaskText: '0',
+
+      customTokens: {
+        C: { pattern: '[0-4a-eA-E]', negate: '[^0-4a-eA-E]', transform: v => v.toLocaleUpperCase() },
+        X: { pattern: '[5-8]', negate: '[^5-8]' }
+      }
     }
   },
 

ui/src/components/input/use-mask.js

@@ -1,4 +1,4 @@
-import { ref, watch, nextTick } from 'vue'
+import { ref, computed, watch, nextTick } from 'vue'
 
 import { shouldIgnoreKey } from '../../utils/private.keyboard/key-composition.js'
 
@@ -12,7 +12,7 @@ const NAMED_MASKS = {
   card: '#### #### #### ####'
 }
 
-const TOKENS = {
+const { tokenMap: DEFAULT_TOKEN_MAP, tokenKeys: DEFAULT_TOKEN_MAP_KEYS } = getTokenMap({
   '#': { pattern: '[\\d]', negate: '[^\\d]' },
 
   S: { pattern: '[a-zA-Z]', negate: '[^a-zA-Z]' },
@@ -23,29 +23,62 @@ const TOKENS = {
 
   X: { pattern: '[0-9a-zA-Z]', negate: '[^0-9a-zA-Z]', transform: v => v.toLocaleUpperCase() },
   x: { pattern: '[0-9a-zA-Z]', negate: '[^0-9a-zA-Z]', transform: v => v.toLocaleLowerCase() }
-}
-
-const KEYS = Object.keys(TOKENS)
-KEYS.forEach(key => {
-  TOKENS[ key ].regex = new RegExp(TOKENS[ key ].pattern)
 })
 
-const
-  tokenRegexMask = new RegExp('\\\\([^.*+?^${}()|([\\]])|([.*+?^${}()|[\\]])|([' + KEYS.join('') + '])|(.)', 'g'),
-  escRegex = /[.*+?^${}()|[\]\\]/g
+function getTokenMap (tokens) {
+  const tokenKeys = Object.keys(tokens)
+  const tokenMap = {}
+
+  tokenKeys.forEach(key => {
+    const entry = tokens[ key ]
+    tokenMap[ key ] = {
+      ...entry,
+      regex: new RegExp(entry.pattern)
+    }
+  })
+
+  return { tokenMap, tokenKeys }
+}
+
+function getTokenRegexMask (keys) {
+  return new RegExp('\\\\([^.*+?^${}()|([\\]])|([.*+?^${}()|[\\]])|([' + keys.join('') + '])|(.)', 'g')
+}
 
+const escRegex = /[.*+?^${}()|[\]\\]/g
+const DEFAULT_TOKEN_REGEX_MASK = getTokenRegexMask(DEFAULT_TOKEN_MAP_KEYS)
 const MARKER = String.fromCharCode(1)
 
 export const useMaskProps = {
   mask: String,
   reverseFillMask: Boolean,
   fillMask: [ Boolean, String ],
-  unmaskedValue: Boolean
+  unmaskedValue: Boolean,
+  maskTokens: Object
 }
 
 export default function (props, emit, emitValue, inputRef) {
   let maskMarked, maskReplaced, computedMask, computedUnmask, pastedTextStart, selectionAnchor
 
+  const tokens = computed(() => {
+    if (props.maskTokens === void 0 || props.maskTokens === null) {
+      return {
+        tokenMap: DEFAULT_TOKEN_MAP,
+        tokenRegexMask: DEFAULT_TOKEN_REGEX_MASK
+      }
+    }
+
+    const { tokenMap: customTokens } = getTokenMap(props.maskTokens)
+    const tokenMap = {
+      ...DEFAULT_TOKEN_MAP,
+      ...customTokens
+    }
+
+    return {
+      tokenMap,
+      tokenRegexMask: getTokenRegexMask(Object.keys(tokenMap))
+    }
+  })
+
   const hasMask = ref(null)
   const innerValue = ref(getInitialMaskedValue())
 
@@ -137,9 +170,9 @@ export default function (props, emit, emitValue, inputRef) {
       unmaskChar = '',
       negateChar = ''
 
-    localComputedMask.replace(tokenRegexMask, (_, char1, esc, token, char2) => {
+    localComputedMask.replace(tokens.value.tokenRegexMask, (_, char1, esc, token, char2) => {
       if (token !== void 0) {
-        const c = TOKENS[ token ]
+        const c = tokens.value.tokenMap[ token ]
         mask.push(c)
         negateChar = c.negate
         if (firstMatch === true) {

ui/src/components/input/use-mask.json

@@ -6,26 +6,34 @@
       "examples": [
         "'###-##'", "'date'", "'datetime'", "'time'", "'fulltime'", "'phone'", "'card'"
       ],
-      "category": "behavior"
+      "category": "mask"
     },
 
     "fill-mask": {
       "type": [ "Boolean", "String" ],
       "desc": "Fills string with specified characters (or underscore if value is not string) to fill mask's length",
       "examples": [ "true", "'0'", "'_'" ],
-      "category": "behavior"
+      "category": "mask"
     },
 
     "reverse-fill-mask": {
       "type": "Boolean",
       "desc": "Fills string from the right side of the mask",
-      "category": "behavior"
+      "category": "mask"
     },
 
     "unmasked-value": {
       "type": "Boolean",
       "desc": "Model will be unmasked (won't contain tokens/separation characters)",
-      "category": "behavior"
+      "category": "mask"
+    },
+
+    "mask-tokens": {
+      "type": "Object",
+      "desc": "Object of custom mask tokens to be added on top of the default ones; Can also override any of the default ones; The 'transform' function is optional",
+      "examples": [ "{ C: { pattern: '[0-4a-eA-E]', negate: '[^0-4a-eA-E]', transform: v => v.toLocaleUpperCase() } }" ],
+      "category": "mask",
+      "addedIn": "v2.18.4"
     }
   }
 }