web-ui-pack/baseElement.js

/* eslint-disable @typescript-eslint/no-empty-function */
/* eslint-disable @typescript-eslint/no-unused-vars */
// eslint-disable-next-line max-classes-per-file
import focusFirst from "./helpers/focusFirst";
import nestedProperty from "./helpers/nestedProperty";
import observer from "./helpers/observer";
import onEvent from "./helpers/onEvent";
import objectClone from "./helpers/objectClone";
import { WUPcssHidden } from "./styles";
// theoritcally such single appending is faster than using :host inside shadowComponent
const appendedStyles = new Set();
const appendedRootStyles = new Set();
let lastUniqueNum = 0;
const allObservedOptions = new WeakMap();
/** Basic abstract class for every component in web-ui-pack */
export default class WUPBaseElement extends HTMLElement {
    /** Returns this.constructor // watch-fix: https://github.com/Microsoft/TypeScript/issues/3841#issuecomment-337560146 */
    #ctr = this.constructor;
    /** Reference to global style element used by web-ui-pack */
    static get $refStyle() {
        return window.WUPrefStyle || null;
    }
    static set $refStyle(v) {
        window.WUPrefStyle = v || undefined;
    }
    /** StyleContent related to component */
    static get $style() {
        return "";
    }
    /** StyleContent related to component & inherited components */
    static get $styleRoot() {
        return `:root {
          --base-bg: #fff;
          --base-text: #232323;
          --base-focus: #00778d;
          --base-btn-bg: #009fbc;
          --base-btn-text: #fff;
          --base-btn-focus: #005766;
          --base-btn2-bg: var(--base-btn-text);
          --base-btn2-text: var(--base-btn-bg);
          --base-btn3-bg: var(--base-bg);
          --base-btn3-text: inherit;
          --base-sep: #e4e4e4;
          --border-radius: 6px;
          --anim-time: 200ms;
          --anim: var(--anim-time) cubic-bezier(0, 0, 0.2, 1) 0ms;
        }`;
    }
    /** Get unique id for html elements; Every getter returns new id */
    static get $uniqueId() {
        return `wup${++lastUniqueNum}`;
    }
    static get classNameHidden() {
        return "wup-hidden";
    }
    /* Array of options names to listen for changes */
    static get observedOptions() {
        return undefined;
    }
    /* Array of attribute names to listen for changes */
    static get observedAttributes() {
        return undefined;
    }
    /** Global default options applied to every element. Change it to configure default behavior OR use `element.$options` to change per item */
    static $defaults = {};
    /** Raw part of $options for internal usage (.$options is Proxy object and better avoid useless extra-calles via Proxy) */
    // @ts-expect-error - TS doesn't see that init happens via constructor.$options = null;
    _opts; // = objectClone(this.#ctr.$defaults) as TOptions;
    /* Observed part of $options */
    #optsObserved;
    #removeObserved;
    get $options() {
        // return observed options
        if (this.$isReady) {
            if (!this.#optsObserved) {
                // get from cache
                let o = allObservedOptions.get(this.#ctr);
                if (o === undefined) {
                    const arr = this.#ctr.observedOptions;
                    o = arr?.length ? new Set(arr) : null;
                    allObservedOptions.set(this.#ctr, o);
                }
                const watched = o;
                if (!watched?.size) {
                    return this._opts;
                }
                // cast to observed only if option was retrieved: to optimize init-performance
                this.#optsObserved = observer.make(this._opts, { excludeNested: true });
                this.#removeObserved = observer.onChanged(this.#optsObserved, (e) => {
                    this.#isReady && e.props.some((p) => watched.has(p)) && this.gotOptionsChanged(e);
                });
            }
            return this.#optsObserved;
        }
        // OR return original options if element no appended to body - in this case we don't need to track changes
        return this._opts;
    }
    /** 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) {
        if (this._opts === v) {
            return;
        }
        const prev = this._opts;
        if (!v) {
            v = objectClone(this.#ctr.$defaults);
        }
        this._opts = v;
        if (this.$isReady) {
            // unsubscribe from previous events here
            this.#removeObserved?.call(this);
            this.#optsObserved = undefined;
            this.#removeObserved = undefined;
            const watched = allObservedOptions.get(this.#ctr);
            if (!watched?.size) {
                return; // don't call event if there is nothing to watchFor
            }
            // shallow comparison with filter watched options
            if (prev.valueOf() !== v.valueOf()) {
                const props = [];
                // eslint-disable-next-line no-restricted-syntax
                for (const [k] of watched.entries()) {
                    if (this._opts[k] !== prev[k]) {
                        props.push(k);
                    }
                }
                props.length && this.gotOptionsChanged({ props, target: this._opts });
            }
        }
    }
    /* Return all prototypes till HTMLElement */
    static findAllProtos(t, protos) {
        const p = Object.getPrototypeOf(t);
        if (p !== HTMLElement.prototype) {
            protos.push(p.constructor);
            // Object.getOwnPropertyNames(p).forEach((s) => {
            //   const k = s as keyof Omit<WUPBaseElement, keyof HTMLElement | "$isReady">;
            //   const desc = Object.getOwnPropertyDescriptor(p, s) as PropertyDescriptor;
            //   if (typeof desc.value === "function" && s !== "constructor") {
            //     this[k] = (this[k] as Function).bind(this);
            //   }
            // });
            this.findAllProtos(p, protos);
        }
        return protos;
    }
    constructor() {
        super();
        // @ts-expect-error - TS doesn't see that init happens in this way;
        this.$options = null;
        if (!this.#ctr.$refStyle) {
            this.#ctr.$refStyle = document.createElement("style");
            /* from https://snook.ca/archives/html_and_css/hiding-content-for-accessibility  */
            this.#ctr.$refStyle.append(`.${this.#ctr.classNameHidden}, [${this.#ctr.classNameHidden}] {${WUPcssHidden}}`);
            document.head.prepend(this.#ctr.$refStyle);
        }
        const refStyle = this.#ctr.$refStyle;
        // setup styles
        if (!appendedStyles.has(this.tagName)) {
            appendedStyles.add(this.tagName);
            // NiceToHave refactor to append styles via CDN or somehow else
            const protos = this.#ctr.findAllProtos(this, []);
            protos.reverse().forEach((p) => {
                // append $styleRoot
                if (!appendedRootStyles.has(p)) {
                    appendedRootStyles.add(p);
                    if (Object.prototype.hasOwnProperty.call(p, "$styleRoot")) {
                        const s = p.$styleRoot;
                        s && refStyle.append(s);
                    }
                }
            });
            const c = protos[protos.length - 1].$style;
            refStyle.append(c.replace(/:host/g, `${this.tagName}`));
        }
    }
    /** Returns true if element is appended (result of setTimeout on connectedCallback) */
    get $isReady() {
        return this.#isReady;
    }
    /** Try to focus self or first possible children; returns true if succesful */
    focus() {
        return focusFirst(this);
    }
    /** Remove focus from element on any nested active element */
    blur() {
        const ae = document.activeElement;
        if (ae === this) {
            super.blur();
        }
        else if (ae instanceof HTMLElement && this.includes(ae)) {
            ae.blur();
        }
    }
    /** Called when need to parse attribute */
    parse(text) {
        return text;
    }
    #isReady = false;
    /** Called when element is added to document (after empty timeout - at the end of call stack) */
    gotReady() {
        this.#readyTimeout = undefined;
        this.#isReady = true;
        this._isStopChanges = true;
        this.gotChanges(null);
        this._isStopChanges = false;
        this.#readyTimeout = setTimeout(() => {
            (this.autofocus || this._opts.autoFocus) && this.focus();
            this.#readyTimeout = undefined;
        }); // timeout to wait for options
    }
    /** Called when element is removed from document */
    gotRemoved() {
        this.#isReady = false;
        this.dispose();
    }
    /** Called on Init and every time as options/attributes changed */
    gotChanges(propsChanged) { }
    /** Called when element isReady and at least one of observedOptions is changed */
    gotOptionsChanged(e) {
        this._isStopChanges = true;
        e.props.forEach((p) => this.removeAttribute(p)); // remove related attributes otherwise impossible to override
        this.gotChanges(e.props);
        this._isStopChanges = false;
    }
    /** Called once on Init */
    gotRender() { }
    #isFirstConn = true;
    #readyTimeout;
    /** Browser calls this method when the element is added to the document */
    connectedCallback() {
        // async requires otherwise attributeChangedCallback doesn't set immediately
        this.#readyTimeout = setTimeout(() => this.gotReady.call(this));
        if (this.#isFirstConn) {
            this.#isFirstConn = false;
            this.gotRender();
        }
    }
    /** Browser calls this method when the element is removed from the document;
     * (can be called many times if an element is repeatedly added/removed) */
    disconnectedCallback() {
        this.#readyTimeout && clearTimeout(this.#readyTimeout);
        this.#readyTimeout = undefined;
        this.gotRemoved();
    }
    _isStopChanges = true;
    #attrTimer;
    #attrChanged;
    /** Called when element isReady and one of observedAttributes is changed */
    gotAttributeChanged(name, oldValue, newValue) {
        // debounce filter
        if (this.#attrTimer) {
            this.#attrChanged.push(name);
            return;
        }
        this.#attrChanged = [name];
        this.#attrTimer = setTimeout(() => {
            this.#attrTimer = undefined;
            this._isStopChanges = true;
            const keys = Object.keys(this._opts);
            const keysNormalized = []; // cache to boost performance via exlcuding extra-lowerCase
            this.#attrChanged.forEach((a) => {
                keys.some((k, i) => {
                    let kn = keysNormalized[i];
                    if (!kn) {
                        kn = k.toLowerCase();
                        keysNormalized.push(kn);
                    }
                    if (kn === a) {
                        delete this._opts[k];
                        return true;
                    }
                    return false;
                });
            }); // otherwise attr can't override option if attribute removed
            this.gotChanges(this.#attrChanged);
            this._isStopChanges = false;
            this.#attrChanged = undefined;
        });
    }
    /** Browser calls this method when attrs pointed in observedAttributes is changed */
    attributeChangedCallback(name, oldValue, newValue) {
        this.#isReady &&
            !this._isStopChanges &&
            oldValue !== newValue &&
            this.gotAttributeChanged(name, oldValue, newValue);
    }
    addEventListener(type, listener, options) {
        return super.addEventListener(type, listener, options);
    }
    removeEventListener(type, listener, options) {
        return super.removeEventListener(type, listener, options);
    }
    /* eslint-enable max-len */
    /** 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(type, eventInit) {
        const ev = new CustomEvent(type, eventInit);
        let sip = false;
        const isCustom = type.startsWith("$");
        if (isCustom) {
            ev.stopImmediatePropagation = () => {
                sip = true;
                CustomEvent.prototype.stopImmediatePropagation.call(ev);
            };
            const str = type.substring(1, 2).toUpperCase() + type.substring(2);
            this[`$on${str}`]?.call(this, ev);
        }
        !sip && super.dispatchEvent(ev);
        return ev;
    }
    /** Array of removeEventListener() that called on remove */
    disposeLst = [];
    /** Add event listener and remove after component removed; @options.passive=true by default */
    appendEvent(...args) {
        // self-removing when option.once
        if (args[3]?.once) {
            const listener = args[2];
            args[2] = function wrapper(...args2) {
                const v = listener.call(this, ...args2);
                remove();
                return v;
            };
        }
        // @ts-ignore - different TS versions can throw here
        const r = onEvent(...args);
        this.disposeLst.push(r);
        const remove = () => {
            const i = this.disposeLst.indexOf(r);
            if (i !== -1) {
                r();
                this.disposeLst.splice(i, 1);
            }
        };
        return remove;
    }
    /** Remove events/functions that was appended */
    dispose() {
        this.disposeLst.forEach((f) => f()); // remove possible previous event listeners
        this.disposeLst.length = 0;
    }
    /** 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) {
        return el instanceof Node && this.contains(el);
    }
    /** Returns true if element contains eventTarget or it's eventTarget
     * @tutorial Troubleshooting
     * * if element has position `fixed` or `absolute` then returns false */
    includesTarget(e) {
        const t = e.target;
        return this === t || this.includes(t);
    }
    getAttr(attr, type, alt) {
        const a = this.getAttribute(attr);
        const nullResult = alt !== undefined ? alt : this._opts[attr];
        if (a == null) {
            return nullResult;
        }
        switch (type) {
            case "bool":
                return a !== "false";
            case "number": {
                const v = +a;
                if (Number.isNaN(v)) {
                    this.throwError(`Expected number for attribute [${attr}] but pointed '${a}'`);
                    return nullResult;
                }
                return v;
            }
            case "ref": {
                const v = nestedProperty.get(window, a);
                if (v === undefined) {
                    this.throwError(`Value not found according to attribute [${attr}] in '${a.startsWith("window.") ? a : `window.${a}`}'`);
                    return nullResult;
                }
                return v;
            }
            case "obj": {
                try {
                    return this.parse(a);
                }
                catch (err) {
                    this.throwError(err);
                    return nullResult;
                }
            }
            case "boolOrString": {
                if (a === "" || a === "true") {
                    return true;
                }
                if (a === "false") {
                    return false;
                }
                return a;
            }
            default:
                return a; // string
        }
    }
    /** Remove attr if value falseOrEmpty; set '' or 'true' if true for HTMLELement
     * @param isSetEmpty set if need '' instead of 'value' */
    setAttr(attr, v, isSetEmpty) {
        v ? this.setAttribute(attr, isSetEmpty ? "" : v) : this.removeAttribute(attr);
    }
    /** Remove all children in fastest way */
    removeChildren() {
        // benchmark: https://measurethat.net/Benchmarks/Show/23474/2/remove-all-children-from-dom-element-2
        while (this.firstChild) {
            this.removeChild(this.firstChild);
        }
    }
    /** Throws unhanled error via empty setTimeout */
    throwError(err) {
        const e = new Error(`${this.tagName}. ${err}`, { cause: err });
        setTimeout(() => {
            throw e;
        });
    }
}