Masked input - IgniteUI/igniteui-webcomponents GitHub Wiki
- Masked input specification
Team: Codex
Radoslav Karaivanov
Stefan Ivanov
- Diyan Dimitrov | Date:
- Stefan Ivanov | Date:
- Product Owner: Radoslav Mirchev | Date:
- Platform Architect: Damyan Petev | Date: 2022-04-11
| Version | Author | Date | Notes |
|---|---|---|---|
| 1 | Radoslav Karaivanov | 21-Feb-2022 | First draft |
| 2 | Damyan Petev & R.K. | 11-Apr-2022 | Finalize |
A masked input is an input field where a developer can control user input and format the visible value, based on configurable rules.
- Should provide a mask pattern for guiding user input and for display value format
- The following built-in pattern rules should be supported:
Mask character Description 0 Digit character [0-9]. Entry is required. 9 Digit character [0-9]. Entry is optional. # Digit character [0-9], plus (+), or minus (-) sign. Entry is required. L Letter character. Entry is required. ? Letter character. Entry is optional. A Alphanumeric (letter or digit) character. Entry is required. a Alphanumeric (letter or digit) character. Entry is optional. & Any keyboard character. Entry is required. C Any keyboard character. Entry is optional. \ Escapes a mask flag and turns it into a literal. - Should support static symbols (literals) in the mask pattern
- Should provide a prompt symbol for customizing the unfilled parts of the masked pattern
- Should provide a way to get the control value verbatim (with literals included) or parsed and striped from literals/formatting
- Should support all the properties/API surface of the igc-input element where applicable.
- Should correctly manage and report its validation state, if any validation constraints or required positions are applied
- Should be supported as a component which participates in an igc-form submission
Developer stories:
As a developer I expect to be able to:
- set a name attribute so that the control is identifiable in the context of a web form
- set a value so that the control can be programmatically initialized or updated
- set a required attribute so that the controls becomes mandatory in the context of a web form
- set a disabled attribute so that the control can't be modified or interacted with
- set a readonly attribute so that the control value can't be modified but the user can still interact with it
- set an invalid attribute so that I can deterministically mark the control as invalid
- set an autofocus attribute so that the field can become focused on initial page load
- add a label attribute so that the user would know what to enter and easily differentiate between several inputs placed on the same page
- set a placeholder attribute so that the user has an example of the expected input value. A placeholder can be used without or with a label
- add a prefix and/or suffix content so that I can make compound, padded input fields comprised of icons and text
- add a **helper text **(left or/and right aligned) so that the user would have more details and updates (hints/errors) about this field
- have states and corresponding design styles (enabled: idle & empty, hover, press, focus, idle & filled, error, disabled, read-only, valid/invalid, empty/filled) applied to all input parts (label, placeholder, helper text, prefix, suffix, etc.) so that the user would know the state of the input and act accordingly
- alter between filled and outlined styles for material-styled inputs so that I can have differently styled material inputs
End user stories:
As an end user, I want to:
- enter characters in a field so that I can provide data to a web form or other parts of an application
- have a visual indicator, such as outline so that I will know which input field is currently on focus
- have different visual states so that I know how to interact with the input field
- a label so that I can identify the input
- see helper text so that I get updates about my input such as counters, error/success messages, etc
- have an asterisk glyph in the label so that I would know that the input is required
- have prefix and/or suffix in the input so that I would have more context
- have the actionable prefix and/or suffix in the input so that I can perform quick action on the input (example: clear input suffix icon)
A masked input is a text field where user input is controlled and filtered by a predefined masked pattern. The masked input can be validated. Helper text, placeholders, and visual states can be updated accordingly upon string input/interaction and data can be submitted.
The mask pattern required flags participate in the component validation - i.e. the input should become invalid when there are some positions filled but not all required ones are (no positions filled/empty value is still responsibility of required). This applies in general - to both stand-alone inputs and when in form.
- Input masks add formatting characters to user input, and prevent users from typing input that doesn't match the mask.
- The control should match the behavior of the standard browser input as close as possible (behavior/accessibility) while still enforcing the mask rules.
- By default, the mask string is applied in the input field when there is a value regardless of the focus state.
- For empty inputs a placeholder is applied - by default using the mask pattern if the same attribute isn't set. The mask string is shown only in focused state or when dragging text over the input.
- Inputting a character will advance the current caret position as long as the character matches the underlying mask rule (it is valid). Otherwise, the caret will remain at its current position.
- Pressing Backspace will delete a character from the string, moving the caret to the previous non-literal index and replacing the deleted character with the mask placeholder symbol.
- Pressing Delete will delete a character from the string, moving the caret to the next non-literal index and replacing the deleted character with the mask placeholder symbol.
- Users can copy and paste text into the mask input field. When the texts are pasted, they take on the format defined for the mask. Copying from a mask input field, always returns the formatted string.
- Users can drag and drop text into the mask input field. When the texts are dropped, they take on the format defined for the mask.
- The mask supports entering text through an input method editor (IME). While in composition mode, the pattern is not enforced, and it is applied upon exiting composition mode when the user commits the value.
- Text selection behaviors:
- focusing the mask control with Tab will select the text inside the input field
- clicking inside an empty mask will select the text in the input field
- clicking at the end of the input field will select the text, regardless of the current value state
- By default, when retrieving the value of the mask input, it will be a stripped of all formatting and literals. If a developer needs the verbatim formatted value, make sure to set the value-mode attribute on the component.
A masked input is an input field where a developer can control user input and format the visible value, based on configurable rules
Mixins: SizableMixin, EventEmitterMixin
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
dir |
dir |
"ltr" | "rtl" | "auto" |
"auto" | The direction attribute of the control. |
disabled |
disabled |
boolean |
false | Makes the control a disabled field. |
invalid |
invalid |
boolean |
false | Controls the validity of the control. |
label |
label |
string |
The label for the control. | |
mask |
mask |
string |
The mask pattern to apply on the input. | |
name |
name |
string |
The name attribute of the control. | |
outlined |
outlined |
boolean |
false | |
placeholder |
placeholder |
string |
The placeholder attribute of the control. | |
prompt |
prompt |
string |
The prompt symbol to use for unfilled parts of the mask. | |
readonly |
readonly |
boolean |
false | Makes the control a readonly field. |
required |
required |
boolean |
false | Makes the control a required field. |
size |
size |
"small" | "medium" | "large" |
"medium" | Determines the size of the component. |
value |
value |
string |
The value of the input. Regardless of the currently set value-mode, an empty value will return an empty string. |
|
valueMode |
value-mode |
"raw" | "withFormatting" |
"raw" | Dictates the behavior when retrieving the value of the control: - raw will return the clean user input.- withFormatting will return the value with all literals and prompts. |
| Method | Type | Description |
|---|---|---|
blur |
(): void |
Removes focus from the control. |
focus |
(options?: FocusOptions | undefined): void |
Sets focus on the control. |
reportValidity |
(): boolean |
Checks for validity of the control and shows the browser message if it's invalid. |
select |
(): void |
Selects all text within the input. |
setCustomValidity |
(message: string): void |
Sets a custom validation message for the control. As long as message is not empty, the control is considered invalid. |
setRangeText |
(replacement: string, start: number, end: number, _selectMode?: "select" | "start" | "end" | "preserve"): void |
Replaces the selected text in the control and re-applies the mask |
setSelectionRange |
(start: number, end: number, direction?: "none" | "backward" | "forward" | undefined): void |
Sets the text selection range of the control |
| Event | Description |
|---|---|
igcBlur |
Emitted when the control loses focus |
igcChange |
Emitted when an alteration of the control's value is committed by the user |
igcFocus |
Emitted when the control gains focus |
igcInput |
Emitted when the control receives user input |
| Name | Description |
|---|---|
helper-text |
Renders content below the input |
prefix |
Renders content before the input |
suffix |
Renders content after the input |
| Part | Description |
|---|---|
container |
The main wrapper that holds all main input elements |
helper-text |
The helper text wrapper |
input |
The native input element |
label |
The native label element |
prefix |
The prefix wrapper |
suffix |
The suffix wrapper |
- The masked input does not expose a type attribute since it is always an input of type text
- Undo/redo behavior is currently unsupported.
- Should correctly initialize and update the prompt character for the mask.
- Should correctly initialize and update the mask pattern of the component.
- Should correctly reflect the placeholder attribute if present.
- Should correctly set & get the value of the component with and without literal symbols included.
- Should correctly reflect validity status based on attributes and DOM API calls.
- Should render proper ARIA attributes.
- Should correctly reflect the mask pattern application on focus/blur states.
- Should correctly reflect the mask state when dragging text over the input of the component.
- Should correctly update the state of the input on pressing Backspace.
- Should correctly update the state of the input on pressing Delete.
- Should correctly update the state of the input on Cut.
- Should correctly update the state of the input on Copy.
- Should correctly update the state of the input on Paste.
- Should correctly update the state of the input when dragging/dropping text.
- Should correctly update the state of the input when inputting text through and IME.
The encapsulated native input is the de facto focusable and interactive element. The input can be labeled using the label attribute, which utilizes the native <label> element to provide a semantically correct label that is fully accessible.
- Have an input that is focusable.
- Handle events like blur, focus, change and input.
- Provide label, hint text and a placeholder.
- Corresponding styles, animations and interactions (as per the material guidelines)