@@ -54,14 +54,64 @@ export interface UseMaskOptions {
5454}
5555
5656export interface UseMaskExposes {
57+ /**
58+ * Handles input events for the masked input field.
59+ * Processes character input and composition events while applying the mask pattern.
60+ * @param event - The form or composition event from the input element
61+ */
5762 onMaskInput : ( event : React . FormEvent < HTMLInputElement > | React . CompositionEvent < HTMLInputElement > ) => void ;
63+ /**
64+ * Handles keydown events for special key operations.
65+ * Manages backspace, delete, escape, and enter key behaviors.
66+ * @param event - The keyboard event from the input element
67+ */
5868 onMaskKeyDown : ( event : React . KeyboardEvent < HTMLInputElement > ) => void ;
69+ /**
70+ * Handles keypress events for character input validation.
71+ * Validates and places characters according to the mask pattern.
72+ * @param event - The keyboard event from the input element
73+ */
5974 onMaskKeyPress : ( event : React . KeyboardEvent < HTMLInputElement > ) => void ;
75+ /**
76+ * Handles focus events when the input gains focus.
77+ * Initializes the mask display and sets the cursor position.
78+ * @param event - The focus event from the input element
79+ */
6080 onMaskFocus : ( event : React . FocusEvent < HTMLInputElement > ) => void ;
81+ /**
82+ * Handles blur events when the input loses focus.
83+ * Validates the final value and triggers change events if needed.
84+ * @param event - The focus event from the input element
85+ */
6186 onMaskBlur : ( event : React . FocusEvent < HTMLInputElement > ) => void ;
87+ /**
88+ * Handles paste events for clipboard content insertion.
89+ * Processes pasted content according to the mask pattern.
90+ * @param event - The clipboard event from the input element
91+ */
6292 onMaskPaste : ( event : React . ClipboardEvent < HTMLInputElement > ) => void ;
6393}
6494
95+ /**
96+ * useMask hook is used to enter input in a certain format such as numeric, date, currency, email and phone.
97+ *
98+ * @param {UseMaskOptions } options - The options for the mask.
99+ * @returns {UseMaskExposes } - The exposed methods for the mask.
100+ *
101+ * @example
102+ * ```tsx
103+ * const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
104+ * mask: '99/99/9999',
105+ * onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
106+ * inputRef: ref
107+ * });
108+ *
109+ * return (
110+ * <div className="card flex justify-center">
111+ * <InputText ref={ref} value={value} placeholder="99/99/9999" onInput={onMaskInput} onKeyDown={onMaskKeyDown} onKeyPress={onMaskKeyPress} onFocus={onMaskFocus} onBlur={onMaskBlur} onPaste={onMaskPaste} />
112+ * </div>
113+ * );
114+ */
65115export function useMask ( options : UseMaskOptions ) : UseMaskExposes {
66116 const { mask, unmask, slotChar = '_' , autoClear = true , readOnly = false , onMaskChange, inputRef } = options ;
67117
0 commit comments