igniteui-webcomponents
Version:
Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.
146 lines (145 loc) • 5.41 kB
TypeScript
/** Options for the {@link MaskParser} */
interface MaskOptions {
/**
* The mask format string (e.g., '00/00/0000' for dates, 'AAA-000' for custom IDs).
*
* Supported flags: a, A, C, L, 0, 9, #, &, ?.
*
* Use `'\'` to escape a flag character if it should be treated as a literal.
* @default 'CCCCCCCCCC'
*/
format?: string;
/**
* The character used to prompt for input in unfilled mask positions.
* Must be a single character.
* @default '_'
*/
promptCharacter?: string;
}
/** Internal options with all required fields */
interface MaskOptionsInternal {
format: string;
promptCharacter: string;
}
/**
* Result type for the replace operation, containing the new masked value and the
* ideal cursor position.
*/
type MaskReplaceResult = {
value: string;
end: number;
};
/**
* A class for parsing and applying masks to strings, typically for input fields.
* It handles mask definitions, literals, character validation, and cursor positioning.
*/
export declare class MaskParser {
protected readonly _options: MaskOptionsInternal;
/** Stores literal characters and their original positions in the mask (e.g., '(', ')', '-'). */
protected readonly _literals: Map<number, string>;
/** A Set of positions where literals occur in the `_escapedMask`. */
protected _literalPositions: Set<number>;
/** The mask format after processing escape characters */
protected _escapedMask: string;
/** Cached array of required non-literal positions for validation */
protected _requiredPositions: number[];
/**
* Returns a set of the all the literal positions in the mask.
* These positions are fixed characters that are not part of the input.
*/
get literalPositions(): ReadonlySet<number>;
/**
* Returns the escaped mask string.
* This is the mask after processing any escape sequences.
*/
get escapedMask(): string;
/**
* Returns the result of applying an empty string over the mask pattern.
*/
get emptyMask(): string;
/**
* Gets the unescaped mask string (the original format string).
* If the mask has no escape sequences, then `mask === escapedMask`.
*/
get mask(): string;
/**
* Sets the mask of the parser.
* When the mask is set, it triggers a re-parsing of the mask literals and escaped mask.
*/
set mask(value: string);
/**
* Gets the prompt character used for unfilled mask positions.
*/
get prompt(): string;
/**
* Sets the prompt character. Only the first character of the provided string is used.
* @remarks The prompt character cannot be a mask flag character.
*/
set prompt(value: string);
constructor(options?: MaskOptions);
private _isEscapedFlag;
/**
* Parses the mask format string to identify literal characters and
* create the escaped mask. This method is called whenever the mask format changes.
*/
protected _parseMaskLiterals(): void;
/**
* Computes an array of positions in the escaped mask that correspond to
* required input flags (e.g., '0', 'L') and are not literal characters.
*
* These positions must be filled for the masked string to be valid.
*/
protected _computeRequiredPositions(): number[];
/**
* Finds the closest non-literal position in the mask *before* the given start position.
* Useful for backward navigation (e.g., backspace).
*
* @remarks
* If no non-literal is found before `start`, return 0.
*/
getPreviousNonLiteralPosition(start: number): number;
/**
* Finds the closest non-literal position in the mask *after* the given start position.
* Useful for forward navigation (e.g., arrow keys, delete key or initial cursor placement).
*
* @remarks
* If no non-literal is found after `start`, return the mask length.
*/
getNextNonLiteralPosition(start: number): number;
/**
* Replaces a segment of the masked string with new input, simulating typing or pasting.
* It handles clearing the selected range and inserting new characters according to the mask.
*
* @example
* ```ts
* const parser = new MaskParser({ format: '00/00/0000' });
* const current = '__/__/____';
* const result = parser.replace(current, '12', 0, 0);
* // result.value = '12/__/____', result.end = 2
* ```
*/
replace(maskString: string, value: string, start: number, end: number): MaskReplaceResult;
/**
* Parses the masked string, extracting only the valid input characters.
* This effectively "unmasks" the string, removing prompts and literals.
*/
parse(masked?: string): string;
/**
* Checks if the masked string is valid, specifically if all required mask positions are filled
* with valid, non-prompt characters.
*/
isValidString(input?: string): boolean;
/**
* Applies the mask format to an input string. This attempts to fit the input
* into the mask from left to right, filling valid positions and skipping invalid
* input characters.
*
* @example
* ```ts
* const parser = new MaskParser({ format: '00/00/0000' });
* parser.apply('12252023'); // Returns '12/25/2023'
* ```
*/
apply(input?: string): string;
}
export {};