web-ui-pack
Version:
Web package with UI elements
175 lines (174 loc) • 8.2 kB
TypeScript
import MaskTextInput from "./text.mask";
import WUPBaseControl, { SetValueReasons } from "./baseControl";
import TextHistory from "./text.history";
declare const tagName = "wup-text";
declare global {
namespace WUP.Text {
interface EventMap extends WUP.BaseControl.EventMap {
}
interface ValidityMap extends WUP.BaseControl.ValidityMap {
/** If textLength < pointed shows message 'Min length is {x} characters` */
min: number;
/** If textLength > pointed shows message 'Max length is {x} characters` */
max: number;
/** If $value doesn't match email-pattern shows message 'Invalid email address` */
email: boolean;
}
interface NewOptions {
/** Debounce time to wait for user finishes typing to start validate and provide $change event
* @defaultValue 0; */
debounceMs: number;
/** Select whole text when input got focus (when input is not readonly and not disabled);
* @defaultValue false */
selectOnFocus: boolean;
/** Show/hide clear button
* @see {@link ClearActions} from `web-ui-pack/baseControl`
* @defaultValue true */
clearButton: boolean;
/** Make input masked
* @rules when mask is pointed and contains only numeric vars
* * inputmode='numeric' so mobile device show numeric-keyboard
* * enables validation 'mask' with error message 'Incomplete value'
* @example
* "0000-00-00" // for date in format yyyy-mm-dd
* "##0.##0.##0.##0" // IPaddress
* "+1(000) 000-0000" // phoneNumber
* "00:00 /[AP]/M" // time hh:mm AM/PM
* '0' // required digit
* '#' // optional digit
* '*' // any char
* '*{1,5}' // - any 1..5 chars
* '//[a-zA-Z]//' // regex: 1 letter (WARN: regex must be pointed for check-in only 1 char at once)
* '//[a-zA-Z]//{1,5}' // regex: 1..5 letters
* '|0' // or '\x00' - static char '0'
* '|#' // or '\x01' - static char '#'
* '|*' // or '\x02' - static char '*'
* '|/' // or '\x03' - static char '/' */
mask?: string | null | undefined;
/** Placeholder for mask. By default it inherits from mask. To disabled it set `false`;
* for date maskholder can be 'yyyy-mm-dd' */
maskholder?: string | false | null | undefined;
/** Part before input; for example for value "$ 123 USD" prefix is "$ " */
prefix?: string | null | undefined;
/** Part after input; for example for value "$ 123 USD" postfix is " USD" */
postfix?: string | null | undefined;
}
interface Options<T = string, VM = ValidityMap> extends WUP.BaseControl.Options<T, VM>, NewOptions {
}
interface JSXProps<C = WUPTextControl> extends WUP.BaseControl.JSXProps<C>, WUP.Base.OnlyNames<NewOptions> {
"w-debounceMs"?: number;
"w-selectOnFocus"?: boolean | "";
"w-clearButton"?: boolean | "";
"w-mask"?: string;
"w-maskholder"?: string | false;
"w-prefix"?: string;
"w-postfix"?: string;
}
interface GotInputEvent extends InputEvent {
target: HTMLInputElement;
}
}
interface HTMLElementTagNameMap {
[]: WUPTextControl;
}
}
declare module "react" {
namespace JSX {
interface IntrinsicElements {
/** Form-control with text input
* @see {@link WUPTextControl} */
[]: WUP.Base.ReactHTML<WUPTextControl> & WUP.Text.JSXProps;
}
}
}
declare module "preact/jsx-runtime" {
namespace JSX {
interface HTMLAttributes<RefType> {
}
interface IntrinsicElements {
/** Form-control with text input
* @see {@link WUPTextControl} */
[]: HTMLAttributes<WUPTextControl> & WUP.Text.JSXProps;
}
}
}
/** Form-control with text-input
* @see demo {@link https://yegorich555.github.io/web-ui-pack/control/text}
* @example
const el = document.createElement("wup-text");
el.$options.name = "email";
el.$options.validations = { required: true, max: 100, email: true };
const form = document.body.appendChild(document.createElement("wup-form"));
form.appendChild(el);
// or HTML
<wup-form>
<wup-text w-name="firstName" w-initvalue="Donny" w-validations="myValidations"/>
</wup-form>;
* @tutorial innerHTML @example
* <label>
* <span> // extra span requires to use with icons via label:before, label:after without adjustments
* <input/>
* <strong>{$options.label}</strong>
* </span>
* <button clear/>
* </label>
* @tutorial Troubleshooting @see {@link https://yegorich555.github.io/web-ui-pack/control/text#troubleshooting} */
export default class WUPTextControl<ValueType = string, TOptions extends WUP.Text.Options = WUP.Text.Options, EventMap extends WUP.Text.EventMap = WUP.Text.EventMap> extends WUPBaseControl<ValueType, TOptions, EventMap> {
static get $styleRoot(): string;
static get $style(): string;
static $errorParse: string;
static $errorMask: string;
static $defaults: WUP.Text.Options;
$refBtnClear?: HTMLButtonElement;
$refMaskholder?: HTMLSpanElement;
$refPrefix?: HTMLSpanElement;
$refPostfix?: HTMLSpanElement;
constructor();
parse(text: string): ValueType | undefined;
/** Called before parseInput on gotInput event */
canParseInput(_text: string): boolean;
/** Called to parse/prettify input text to value (related to locale or pointed format)
* @throws {RangeError} if value out of possible range (for DateControl value.month > 12 for example) */
parseInput(text: string): ValueType | undefined;
/** Returns true if need to use custom undo/redo (required when input somehow formatted/masked) */
protected canHandleUndo(): boolean;
protected get validations(): WUP.Text.Options["validations"];
protected renderControl(): void;
/** Create & append element to control */
protected renderBtnClear(): HTMLButtonElement;
/** Add/update/remove prefix part */
protected renderPrefix(text: string | undefined | null): void;
/** Add/update or remove prefix part */
protected renderPostfix(text: string | undefined | null): void;
/** Custom history undo/redo */
_refHistory?: TextHistory;
protected gotFocus(ev: FocusEvent): Array<() => void>;
protected gotFocusLost(): void;
protected gotChanges(propsChanged: Array<keyof WUP.Text.Options> | null): void;
protected gotKeyDown(e: KeyboardEvent): void;
/** Value-text before input changed - used with declineInput */
_beforeSnap?: string;
/** Handler of 'beforeinput' event */
protected gotBeforeInput(e: WUP.Text.GotInputEvent): void;
_inputError?: string;
/** Called when user types text OR when need to apply/reset mask (on focusGot, focusLost) */
protected gotInput(e: WUP.Text.GotInputEvent): void;
/** Mask object to proccess mask on input */
refMask?: MaskTextInput;
/** Called to apply mask-behavior (on "input" event) */
protected maskInputProcess(e: WUP.Text.GotInputEvent | null): string;
/** Add/update maskholder or skip if it's not defined */
private renderMaskHolder;
/** Make undo for input after 100ms when user types not allowed chars
* point nextCaret for custom undo value
* @tutorial Troubleshooting
* * declineInput doesn't trigger beforeinput & input events (do it manually if required) */
protected declineInput(nextCaret?: number, nextValue?: string): void;
protected setValue(v: ValueType | undefined, reason: SetValueReasons, skipInput?: boolean): boolean | null;
/** Called to update/reset value for <input/> */
protected setInputValue(v: string, reason: SetValueReasons): void;
protected setClearState(): ValueType | undefined;
focus(): boolean;
}
export {};