web-ui-pack/baseElement.d.ts

/// <reference types="react" />
import { onEventType } from "./helpers/onEvent";
/** 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;
    /** 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;
    static get classNameHidden(): string;
    static get observedOptions(): Array<string> | undefined;
    static get observedAttributes(): Array<string> | undefined;
    /** 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>;
    /** Raw part of $options for internal usage (.$options is Proxy object and better avoid useless extra-calles via Proxy) */
    protected _opts: TOptions;
    get $options(): TOptions;
    /** Options inherited from `static.$defauls` and applied to element. Use this to change behavior per item OR use `$defaults` to change globally */
    set $options(v: 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;
    /** Try to focus self or first possible children; returns true if succesful */
    focus(): boolean;
    /** Remove focus from element on any nested active element */
    blur(): void;
    /** Called when need to parse attribute */
    parse(text: string): any;
    /** 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;
    _isStopChanges: boolean;
    /** Called when element isReady and one of observedAttributes is changed */
    protected gotAttributeChanged(name: string, oldValue: string, newValue: string): void;
    /** Browser calls this method when attrs pointed in observedAttributes is changed */
    protected attributeChangedCallback(name: string, oldValue: string, newValue: string): 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
     * @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>(type: K, eventInit?: CustomEventInit): 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;
    /** Parse attribute and return result; if attr missed or invalid => returns pointed alt value OR $options[attr] */
    getAttr(attr: string, type?: "string", alt?: string): string | undefined;
    /** Returns `bool if attr is `false` or `true`, `true` if "" or string if exists */
    getAttr(attr: string, type: "boolOrString", alt?: string | boolean): string | boolean | undefined;
    getAttr(attr: string, type: "bool", alt?: boolean): boolean | undefined;
    getAttr(attr: string, type: "number", alt?: number): number | undefined;
    /** Returns value from window[key] according to [attr]="key"; if attr missed or invalid => returns pointed alt value OR $options[attr] */
    getAttr<T>(attr: string, type: "obj", alt?: T): T;
    /** Returns value according to this.parse(); if attr missed or invalid => returns pointed alt value OR $options[attr] */
    getAttr<T>(attr: string, type: "ref", alt?: T): T;
    /** 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 unhanled error via empty setTimeout */
    throwError(err: string | Error | unknown): 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 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 JSXProps<T, Opts extends Record<string, any> = any> = React.DetailedHTMLProps<Omit<React.HTMLAttributes<T>, "className"> & {
            class?: string | undefined;
        }, T> & toJSX<Opts>;
    }
}