0
# Text Mask Addons
1

2
Text Mask Addons provides ready-to-use masks and pipes for the Text Mask input masking library. It offers specialized input formatters for common scenarios including currency/number formatting, email validation, and intelligent date input correction.
3

4
## Package Information
5

6
- **Package Name**: text-mask-addons
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install text-mask-addons`
10

11
## Core Imports
12

13
```javascript
14
import { createNumberMask, emailMask, createAutoCorrectedDatePipe } from "text-mask-addons";
15
```
16

17
For individual imports (recommended for smaller bundle size):
18

19
```javascript
20
import createNumberMask from 'text-mask-addons/dist/createNumberMask';
21
import emailMask from 'text-mask-addons/dist/emailMask';
22
import createAutoCorrectedDatePipe from 'text-mask-addons/dist/createAutoCorrectedDatePipe';
23
```
24

25
CommonJS:
26

27
```javascript
28
const { createNumberMask, emailMask, createAutoCorrectedDatePipe } = require("text-mask-addons");
29
```
30

31
## Basic Usage
32

33
```javascript
34
import { createNumberMask, emailMask, createAutoCorrectedDatePipe } from "text-mask-addons";
35

36
// Currency mask
37
const currencyMask = createNumberMask({
38
  prefix: '$',
39
  includeThousandsSeparator: true,
40
  allowDecimal: true,
41
  decimalLimit: 2
42
});
43

44
// Email mask (use directly)
45
const emailInputMask = emailMask;
46

47
// Date correction pipe
48
const datePipe = createAutoCorrectedDatePipe('mm/dd/yyyy', {
49
  minYear: 1900,
50
  maxYear: 2100
51
});
52
```
53

54
## Capabilities
55

56
### Number/Currency Formatting
57

58
Creates configurable number and currency input masks with support for prefixes, suffixes, thousands separators, decimals, and negative numbers.
59

60
```javascript { .api }
61
/**
62
 * Creates a number/currency formatting mask function
63
 * @param {NumberMaskConfig} config - Configuration options
64
 * @returns {MaskFunction} Mask function that takes rawValue and returns mask array
65
 */
66
function createNumberMask(config = {}): MaskFunction;
67
```
68

69
**Configuration Options:**
70

71
```javascript { .api }
72
interface NumberMaskConfig {
73
  /** Text to display before the amount. Defaults to '$' */
74
  prefix?: string;
75
  /** Text to display after the amount. Defaults to '' */
76
  suffix?: string;
77
  /** Whether to separate thousands. Defaults to true */
78
  includeThousandsSeparator?: boolean;
79
  /** Character for thousands separation. Defaults to ',' */
80
  thousandsSeparatorSymbol?: string;
81
  /** Allow decimal fraction input. Defaults to false */
82
  allowDecimal?: boolean;
83
  /** Character for decimal point. Defaults to '.' */
84
  decimalSymbol?: string;
85
  /** Maximum digits after decimal. Defaults to 2 */
86
  decimalLimit?: number;
87
  /** Always include decimal point. Defaults to false */
88
  requireDecimal?: boolean;
89
  /** Allow negative numbers. Defaults to false */
90
  allowNegative?: boolean;
91
  /** Allow leading zeros. Defaults to false */
92
  allowLeadingZeroes?: boolean;
93
  /** Maximum length of integer part. Defaults to null (unlimited) */
94
  integerLimit?: number | null;
95
}
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
// Basic currency mask
102
const dollarMask = createNumberMask();
103
// Uses default: prefix '$', thousands separator, no decimals
104

105
// European currency format
106
const euroMask = createNumberMask({
107
  prefix: '€ ',
108
  thousandsSeparatorSymbol: '.',
109
  decimalSymbol: ',',
110
  allowDecimal: true
111
});
112

113
// Percentage input
114
const percentMask = createNumberMask({
115
  prefix: '',
116
  suffix: '%',
117
  allowDecimal: true,
118
  decimalLimit: 1
119
});
120

121
// Integer-only with custom limits
122
const integerMask = createNumberMask({
123
  prefix: '',
124
  includeThousandsSeparator: false,
125
  integerLimit: 6,
126
  allowNegative: true
127
});
128
```
129

130
### Email Address Formatting
131

132
Provides email input masking with validation and formatting assistance.
133

134
```javascript { .api }
135
/**
136
 * Email mask object containing both mask and pipe functions
137
 * Used directly with Text Mask - no configuration needed
138
 */
139
const emailMask: {
140
  /** 
141
   * Mask function for email input formatting
142
   * @param {string} rawValue - Current input value
143
   * @param {Object} config - Text Mask configuration object
144
   * @returns {Array} Mask array for input formatting
145
   */
146
  mask: (rawValue: string, config: MaskConfig) => Array<string | RegExp>;
147
  /** 
148
   * Pipe function for email input validation and correction
149
   * @param {string} conformedValue - Value after mask is applied
150
   * @param {Object} config - Text Mask configuration object
151
   * @returns {string | false} Corrected value or false to reject
152
   */  
153
  pipe: (conformedValue: string, config: PipeConfig) => string | false;
154
};
155
```
156

157
**Text Mask Configuration Types:**
158

159
```javascript { .api }
160
interface MaskConfig {
161
  placeholderChar: string;
162
  currentCaretPosition: number;
163
}
164

165
interface PipeConfig {
166
  currentCaretPosition: number;
167
  rawValue: string;
168
  previousConformedValue: string;
169
  placeholderChar: string;
170
}
171
```
172

173
**Usage Example:**
174

175
```javascript
176
import emailMask from 'text-mask-addons/dist/emailMask';
177

178
// Use directly with Text Mask component
179
// emailMask is a special object containing both mask and pipe functions
180
// Text Mask automatically separates them internally
181
// The mask handles @ and . positioning automatically
182
// The pipe validates email format and prevents invalid input
183
```
184

185
### Date Input Auto-Correction
186

187
Creates intelligent date input pipes that auto-correct user input, prevent invalid dates, and assist with date formatting.
188

189
```javascript { .api }
190
/**
191
 * Creates a date auto-correction pipe function
192
 * @param {string} dateFormat - Date format pattern. Defaults to 'mm dd yyyy'
193
 * @param {DatePipeConfig} config - Configuration options
194
 * @returns {DatePipeFunction} Pipe function for date correction
195
 */
196
function createAutoCorrectedDatePipe(dateFormat = 'mm dd yyyy', config = {}): DatePipeFunction;
197
```
198

199
**Configuration Options:**
200

201
```javascript { .api }
202
interface DatePipeConfig {
203
  /** Minimum allowed year. Defaults to 1 */
204
  minYear?: number;
205
  /** Maximum allowed year. Defaults to 9999 */
206
  maxYear?: number;
207
}
208
```
209

210
**Date Format Patterns:**
211

212
The `dateFormat` string supports these components:
213
- `mm` - Month (01-12)
214
- `dd` - Day (01-31, validated against month)
215
- `yy` - Two-digit year (00-99)
216
- `yyyy` - Four-digit year
217
- `HH` - Hours (00-23)
218
- `MM` - Minutes (00-59)
219
- `SS` - Seconds (00-59)
220

221
**Pipe Return Type:**
222

223
```javascript { .api }
224
interface DatePipeResult {
225
  /** Corrected date value */
226
  value: string;
227
  /** Array of character positions that were auto-corrected */
228
  indexesOfPipedChars: number[];
229
}
230

231
/** 
232
 * Date correction pipe function
233
 * @param {string} conformedValue - Date value after mask is applied
234
 * @returns {DatePipeResult | false} Corrected result or false if invalid
235
 */
236
type DatePipeFunction = (conformedValue: string) => DatePipeResult | false;
237
```
238

239
**Usage Examples:**
240

241
```javascript
242
// Basic date pipe
243
const datePipe = createAutoCorrectedDatePipe('mm/dd/yyyy');
244

245
// Custom format with time
246
const dateTimePipe = createAutoCorrectedDatePipe('dd.mm.yyyy HH:MM');
247

248
// Limited year range
249
const modernDatePipe = createAutoCorrectedDatePipe('mm/dd/yyyy', {
250
  minYear: 1900,
251
  maxYear: 2030
252
});
253

254
// European format
255
const europeanDatePipe = createAutoCorrectedDatePipe('dd/mm/yyyy');
256
```
257

258
**Auto-Correction Behavior:**
259

260
- **Single-digit optimization**: Typing "4" in month position becomes "04"
261
- **Invalid date prevention**: Prevents "32/13/2023" or "31/02/2023"
262
- **Smart year handling**: Validates years within the specified range
263
- **Component validation**: Each date/time component is validated against realistic limits
264
- **Caret positioning**: Provides information about auto-corrected positions for UI feedback
265

266
**Important Note:**
267

268
For `createAutoCorrectedDatePipe` to work properly, the Text Mask component must be configured with `keepCharPositions: true`.
269

270
## Types and Constants
271

272
```javascript { .api }
273
/** RegExp for matching single digits (/\d/) - used internally by mask functions */
274
const digitRegExp: RegExp;
275

276
/** Special character for caret positioning in masks ('[]') - used internally by mask functions */
277
const caretTrap: string;
278

279
/** 
280
 * Mask function type - takes raw input and returns formatting mask
281
 * @param {string} rawValue - Current input value
282
 * @returns {Array<string | RegExp>} Array of strings and RegExp patterns for masking
283
 */
284
type MaskFunction = (rawValue: string) => Array<string | RegExp>;
285

286
/**
287
 * Pipe function type - takes formatted value and returns corrected value
288
 * @param {string} conformedValue - Value after mask is applied
289
 * @param {PipeConfig} config - Text Mask configuration
290
 * @returns {string | false} Corrected value or false to reject input
291
 */  
292
type PipeFunction = (conformedValue: string, config: PipeConfig) => string | false;
293
```