web-ui-pack/baseElement.d.ts

/// <reference types="react" />
import { onEventType } from "./helpers/onEvent";
export interface AttributeMap {
    /** One of default types with defined parse */
    type: AttributeTypes;
    /** Option[name] realted to related attribute. Point if attrName !== propName */
    prop?: string;
    /** Custom parser for related attribute */
    parse?: (attrValue: string) => any;
}
export declare const enum AttributeTypes {
    /** Value presented by `true`, `false` or '' (empty string) */
    bool = 0,
    number = 1,
    string = 2,
    reference = 3,
    parsedObject = 4,
    parseCustom = 5,
    /** Element accessed via `document.querySelector` */
    selector = 6
}
declare global {
    /** Translate function that need to replace to translate content according to requirements
     * @param text Text that must be translated
     * @param type Type of related text
     * @returns the same string by default */
    const __wupln: Window["__wupln"];
    interface Window {
        /** Translate function that need to replace to translate content according to requirements
         * @param text Text that must be translated
         * @param type Type of related text
         * @returns the same string by default */
        __wupln: (text: string, type: "aria" | "content" | "validation") => string;
    }
}
/** Basic abstract class for every component in web-ui-pack */
export default abstract class WUPBaseElement<TOptions extends Record<string, any> = Record<string, any>, Events extends WUP.Base.EventMap = WUP.Base.EventMap> extends HTMLElement {
    #private;
    /** Register control in the web to allow to use */
    static $use(): void;
    /** Reference to global style element used by web-ui-pack */
    static get $refStyle(): HTMLStyleElement | null;
    static set $refStyle(v: HTMLStyleElement | null);
    /** StyleContent related to component */
    static get $style(): string;
    /** StyleContent related to component & inherited components */
    static get $styleRoot(): string;
    /** Get unique id for html elements; Every getter returns new id */
    static get $uniqueId(): string;
    /** Returns default class name for visually hidden element */
    static get classNameHidden(): string;
    /** Returns default class name for buttons with icons */
    static get classNameBtnIcon(): string;
    /** Returns map-type based on value */
    static mapAttribute(value: any): AttributeTypes;
    /** Returns map-model based on $defaults for mapping attributes & options */
    static get mappedAttributes(): Record<string, AttributeMap>;
    /** Array of options names to listen for changes; @returns `undefined` if need to observe for every option
     * @defaultValue every option from $defaults` */
    static get observedOptions(): Array<string> | null;
    /** Array of attribute names to listen for changes
     * @defaultValue every option from $defaults (in lowerCase) */
    static get observedAttributes(): Array<string>;
    /** Global default options applied to every element. Change it to configure default behavior OR use `element.$options` to change per item */
    static $defaults: Record<string, any>;
    /** Used to clone single value (from defaults) */
    static cloneValue<T>(v: T): T;
    /** Used to clone defaults to options on init; override it to clone  */
    static cloneDefaults<T extends Record<string, any>>(): T;
    /** Merge options with $defaults; Object.assign merges values 'undefined' by the method replace undefined with defaults */
    static mergeDefaults<T extends Record<string, any>>(opts: T): T;
    /** Raw part of $options for internal usage (.$options is Proxy object and better avoid useless extra-calles via Proxy) */
    protected _opts: TOptions;
    get $options(): Partial<TOptions>;
    /** Options inherited from `static.$defaults` and applied to element. Use this to change behavior per item OR use `$defaults` to change globally */
    set $options(v: Partial<TOptions>);
    static findAllProtos(t: unknown, protos: typeof WUPBaseElement[]): typeof WUPBaseElement[];
    constructor();
    /** Returns true if element is appended (result of setTimeout on connectedCallback) */
    get $isReady(): boolean;
    /** Returns if current element or some nested child is active/focused */
    get $isFocused(): boolean;
    /** Try to focus self or first possible children; returns true if successful */
    focus(): boolean;
    /** Remove focus from element on any nested active element */
    blur(): void;
    /** Called when need to parse attribute */
    parse(text: string): any;
    /** Clear this to prevent autofocus */
    _willFocus?: ReturnType<typeof setTimeout>;
    /** Called when element is added to document (after empty timeout - at the end of call stack) */
    protected gotReady(): void;
    /** Called when element is removed from document */
    protected gotRemoved(): void;
    /** Called on Init and every time as options/attributes changed */
    protected gotChanges(propsChanged: Array<string> | null): void;
    /** Called when element isReady and at least one of observedOptions is changed */
    protected gotOptionsChanged(e: WUP.Base.OptionEvent): void;
    /** Called once on Init */
    protected gotRender(): void;
    /** Browser calls this method when the element is added to the document */
    protected connectedCallback(): void;
    /** Browser calls this method when the element is removed from the document;
     * (can be called many times if an element is repeatedly added/removed) */
    protected disconnectedCallback(): void;
    /** Prevent gotChanges call during the some attribute or options custom changes */
    _isStopChanges: boolean;
    /** Called when any of observedAttributes is changed */
    protected gotAttributeChanged(name: string, value: string | null): void;
    /** Browser calls this method when attrs pointed in observedAttributes is changed */
    protected attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
    addEventListener<K extends keyof Events>(type: K, listener: (this: WUPBaseElement, ev: Events[K]) => any, options?: boolean | AddEventListenerOptions): void;
    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
    removeEventListener<K extends keyof Events>(type: K, listener: (this: WUPBaseElement, ev: Events[K]) => any, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
    /** Inits customEvent & calls dispatchEvent and returns created event; by default `cancelable: false, bubbles: true`
     * @tutorial Troubleshooting
     * * Default event bubbling: el.event.click > el.onclick >>> parent.event.click > parent.onclick etc.
     * * Custom event bubbling: el.$onclick > el.event.$click >>> parent.event.$click otherwise impossible to stop propagation from on['event] of target directly */
    fireEvent<K extends keyof Events, T extends Events[K]["detail"]>(type: K, eventInit?: CustomEventInit<T>): Event;
    /** Array of removeEventListener() that called on remove */
    protected disposeLst: Array<() => void>;
    /** Add event listener and remove after component removed; @options.passive=true by default */
    appendEvent<T extends keyof E, K extends HTMLElement | Document, E extends HTMLElementEventMap & Record<string, Event>>(...args: Parameters<onEventType<T, K, E>>): () => void;
    /** Remove events/functions that was appended */
    protected dispose(): void;
    /** Returns true if el is instance of Node and contains pointed element
     * @tutorial Troubleshooting
     * * if element has position `fixed` or `absolute` then returns false */
    includes(el: unknown): boolean;
    /** Returns true if element contains eventTarget or it's eventTarget
     * @tutorial Troubleshooting
     * * if element has position `fixed` or `absolute` then returns false */
    includesTarget(e: Event): boolean;
    /** Find parent/self according with callback */
    findParent(callback: (el: HTMLElement) => boolean, options?: {
        bubbleCount: number;
    }): HTMLElement | null;
    /** Returns true if contains pointed element or has itself
     * @tutorial Troubleshooting
     * * if element has position `fixed` or `absolute` then returns false */
    itsMe(el: Element | EventTarget | null): boolean;
    /** Returns parsed value according to pointed type OR current value if something wrong;
     * override method for implementation custom parsing OR static method mappedAttributes to redefine map-types */
    parseAttr(type: AttributeTypes, attrValue: string, propName: string, attrName: string): any;
    /** Remove attr if value falseOrEmpty; set '' or 'true' if true for HTMLELement
     * @param isSetEmpty set if need '' instead of 'value' */
    setAttr(attr: string, v: boolean | string | undefined | null, isSetEmpty?: boolean): void;
    /** Remove all children in fastest way */
    removeChildren(): void;
    /** Throws unhandled error via empty setTimeout */
    throwError(err: string | Error | unknown): void;
    /** Removes empty attr [style] */
    removeEmptyStyle(): void;
}
declare global {
    namespace WUP.Base {
        /** Cast not-supported props to optional string */
        type toJSX<T> = {
            [P in keyof T]?: T[P] extends number | boolean | string | undefined ? T[P] : string;
        };
        type OnlyNames<T> = {
            [K in keyof T as K extends string ? `w-${K}` : never]?: unknown;
        };
        type OptionEvent<T extends Record<string, any> = Record<string, any>> = {
            props: Array<Extract<keyof T, string>>;
            target: T;
        };
        type EventMap<T = HTMLElementEventMap> = HTMLElementEventMap & Record<keyof T, Event>;
        type ReactHTML<T> = React.DetailedHTMLProps<Omit<React.HTMLAttributes<T>, "className"> & {
            class?: string | undefined;
            /** @deprecated isn't supported for React & WebComponents; use attr `class` instead
             * @see {@link https://react.dev/reference/react-dom/components#custom-html-elements} */
            className?: never;
        }, T>;
        type JSXProps<T> = React.DetailedHTMLProps<Omit<React.HTMLAttributes<T>, "className"> & {
            class?: string | undefined;
        }, T>;
    }
}