web-ui-pack/formElement.js

import WUPBaseElement from "./baseElement";
import { nestedProperty, promiseWait, scrollIntoView } from "./indexHelpers";
import WUPSpinElement from "./spinElement";
import { WUPcssButton } from "./styles";
export var SubmitActions;
(function (SubmitActions) {
    /** Disable any action */
    SubmitActions[SubmitActions["none"] = 0] = "none";
    /** Scroll to first error (if exists) and focus control */
    SubmitActions[SubmitActions["goToError"] = 1] = "goToError";
    /** Validate until first error is found (otherwise validate all) */
    SubmitActions[SubmitActions["validateUntilFirst"] = 2] = "validateUntilFirst";
    /** Collect to model only changed values */
    SubmitActions[SubmitActions["collectChanged"] = 4] = "collectChanged";
    /** Reset isDirty and assign $value to $initValue for controls (on success only) */
    SubmitActions[SubmitActions["reset"] = 8] = "reset";
    /** Lock the whole form during the pending state (set $isPending = true or provide `promise` to submitEvent.waitFor);
     * Otherwise user can submit several times in a short time;
     * If promise resolves during the short-time pending state won't be set, otherwise it takes at least 300ms via helper {@link promiseWait} */
    SubmitActions[SubmitActions["lockOnPending"] = 16] = "lockOnPending";
})(SubmitActions || (SubmitActions = {}));
const tagName = "wup-form";
const formStore = [];
/** Wrapper of FormHTMLElement that collect values from controls
 * @example
 *  // init form
 *  const form = document.createElement("wup-form");
 *  form.$options.autoComplete = false;
 *  form.$initModel = { email: "test-me@google.com" };
 *  form.addEventListener("$submit", (e) => console.warn(e.detail.model) );
 *  form.$onSubmit = async (e)=>{ await postHere(e.detail.model); } // equal to form.addEventListener
 *  // init control
 *  const el = document.createElement("wup-text");
 *  el.$options.name = "email";
 *  el.$options.validations = { required: true, email: true };
 *  form.appendChild(el);
 *  const btn = form.appendChild(document.createElement("button"));
 *  btn.textContent = "Submit";
 *  btn.type = "submit";
 *  document.body.appendChild(form);
 *  // or HTML
 *  <wup-form w-autocomplete w-autofocus>
 *    <wup-text w-name="email" />
 *    <button type="submit">Submit</submit>
 *  </wup-form>;
 * @tutorial Troubleshooting/rules:
 * * options like $initModel, $model overrides control.$initValue, control.$value (every control that matches by $options.name)
 * * In React ref-parent called after ref-children. So if you want to set control.$initValue over form.$initModel use empty setTimeout on ref-control
 * @example
 * <wup-form
      ref={(el) => {
        if (el) {
          el.$initModel = { email: "test-me@google.com" };
          el.$onSubmit = async (ev)=>{
             await postHere();
          }
        }
      }}
    >
      <wup-text
        ref={(el) => {
          if (el) {
            setTimeout(() => {
              el.$options.name = "email";
              el.$initValue = "";
            });
          }
        }}
        <button type="submit">Submit</button>
      />
  </wup-form>
 */
export default class WUPFormElement extends WUPBaseElement {
    /** Returns this.constructor // watch-fix: https://github.com/Microsoft/TypeScript/issues/3841#issuecomment-337560146 */
    #ctr = this.constructor;
    static get $styleRoot() {
        return `:root {
      --btn-submit-text: var(--base-btn-text);
      --btn-submit-bg: var(--base-btn-bg);
      --btn-submit-focus: var(--base-btn-focus);
    }
    [wupdark] {
      --btn-submit-text: var(--base-btn-text);
      --btn-submit-bg: var(--base-btn-bg);
      --btn-submit-focus: var(--base-btn-focus);
    }`;
    }
    static get $style() {
        return `${super.$style}
        :host {
          position: relative;
          display: block;
          max-width: 500px;
          margin: auto;
        }
        ${WUPcssButton(":host button[type=submit]")}
        :host button[type=submit] {
          --base-btn-text: var(--btn-submit-text);
          --base-btn-bg: var(--btn-submit-bg);
          --base-btn-focus: var(--btn-submit-focus);
          display: block;
        }`;
    }
    static get mappedAttributes() {
        const m = super.mappedAttributes;
        m.autostore.type = 2 /* AttributeTypes.string */;
        return m;
    }
    /** Find form related to control,register and apply initModel if initValue undefined */
    static $tryConnect(control) {
        const form = formStore.find((f) => f.contains(control));
        form?.$controls.push(control);
        return form;
    }
    /** Map model to control-values */
    static $modelToControls(m, controls, prop) {
        const out = { hasProp: undefined };
        controls.forEach((c) => {
            const key = c.$options.name;
            if (key) {
                const v = m && nestedProperty.get(m, key, out);
                if (out.hasProp) {
                    c[prop] = v;
                }
            }
        });
    }
    /** Collect model from control-values */
    static $modelFromControls(prevModel, controls, prop, isOnlyChanged) {
        if (isOnlyChanged) {
            controls.forEach((c) => c.$options.name && c.$isChanged && nestedProperty.set(prevModel, c.$options.name, c[prop]));
        }
        else {
            controls.forEach((c) => c.$options.name && nestedProperty.set(prevModel, c.$options.name, c[prop]));
        }
        return prevModel;
    }
    static get observedAttributes() {
        const a = super.observedAttributes;
        a.push("disabled", "readonly"); // support for `readonly` & `w-readonly`
        return a;
    }
    /** Default options - applied to every element. Change it to configure default behavior */
    static $defaults = {
        submitActions: 1 /* SubmitActions.goToError */ | 2 /* SubmitActions.validateUntilFirst */ | 8 /* SubmitActions.reset */ | 16 /* SubmitActions.lockOnPending */,
        autoComplete: false,
        autoFocus: false,
        autoStore: false,
        disabled: false,
        readOnly: false,
    };
    /** Fires before $submit is happened; can be prevented via `e.preventDefault()` */
    $onWillSubmit;
    /** Dispatched on submit. Return promise to lock form and show spinner on http-request */
    $onSubmit;
    /** Fires when submit is end (after http-response) */
    $onSubmitEnd;
    /** Dispatched on submit */
    // It's not required but called: $onsubmit?: (ev: WUP.Form.SubmitEvent<Model>) => void;
    /** All controls related to form */
    $controls = [];
    /** Returns related to form controls with $options.name != null */
    get $controlsAttached() {
        return this.$controls.filter((c) => c.$options.name != null);
    }
    _model;
    /** Model related to every control inside (with $options.name);
     *  @see {@link BaseControl.prototype.$value} */
    get $model() {
        return Object.assign(this._model || {}, this.#ctr.$modelFromControls({}, this.$controls, "$value"));
    }
    set $model(m) {
        if (m !== this._model) {
            this._model = m;
            this.#ctr.$modelToControls(m, this.$controls, "$value");
        }
    }
    _initModel;
    /** Default/init model related to every control inside;
     *  @see {@link BaseControl.prototype.$initValue} */
    get $initModel() {
        // it's required to avoid case when model has more props than controls
        return this.#ctr.$modelFromControls(this._initModel || {}, this.$controls, "$initValue");
    }
    set $initModel(m) {
        if (m !== this._initModel) {
            this._initModel = m;
            this.#ctr.$modelToControls(m, this.$controls, "$initValue");
        }
    }
    /** Pending state (spinner + lock form if SubmitActions.lockOnPending enabled) */
    get $isPending() {
        return this.#stopPending !== undefined;
    }
    set $isPending(v) {
        if (v !== this.$isPending) {
            this.changePending(v);
        }
    }
    /** Returns true if all nested controls (with name) are valid */
    get $isValid() {
        return this.$controlsAttached.every((c) => c.$isValid);
    }
    /** Returns true if some of controls value is changed by user */
    get $isChanged() {
        return this.$controls.some((c) => c.$options.name && c.$isChanged);
    }
    /** Call it to manually trigger submit or better to use `gotSubmit` for handling events properly */
    $submit() {
        this.gotSubmit(null, this);
    }
    /** Called on every spin-render */
    renderSpin(target) {
        WUPSpinElement.$use();
        const spin = document.createElement("wup-spin");
        spin.$options.fit = true;
        spin.$options.overflowFade = false;
        spin.$options.overflowTarget = target;
        return spin;
    }
    #stopPending;
    /** Change pending state */
    changePending(v) {
        if (v === !!this.#stopPending) {
            return;
        }
        if (v) {
            const wasDisabled = this._opts.disabled;
            if (this._opts.submitActions & 16 /* SubmitActions.lockOnPending */) {
                this.$options.disabled = true;
            }
            const btns = [];
            const spins = [];
            this.querySelectorAll("[type='submit']").forEach((b) => {
                spins.push(this.appendChild(this.renderSpin(b)));
                b._wupDisabled = b.disabled;
                b.disabled = true;
                btns.push(b);
            });
            this.#stopPending = () => {
                this.#stopPending = undefined;
                this.$options.disabled = wasDisabled;
                btns.forEach((b) => (b.disabled = b._wupDisabled));
                spins.forEach((s) => s.remove());
            };
        }
        else {
            this.#stopPending();
        }
    }
    /** Called on submit before validation (to fire validation & $onSubmit if successful) */
    gotSubmit(e, submitter) {
        e?.preventDefault(); // prevent default keyboard or mouse event because it's handled in custom event
        const willEv = this.fireEvent("$willSubmit", {
            bubbles: true,
            cancelable: true,
            detail: {
                relatedEvent: e,
                relatedForm: this,
                submitter,
            },
        });
        if (willEv.defaultPrevented) {
            return;
        }
        // validate
        let errCtrl;
        let arrCtrl = this.$controlsAttached;
        if (this._opts.submitActions & 2 /* SubmitActions.validateUntilFirst */) {
            errCtrl = arrCtrl.find((c) => c.validateBySubmit() && c.canShowError);
        }
        else {
            arrCtrl.forEach((c) => {
                const err = c.validateBySubmit();
                if (err && !errCtrl && c.canShowError) {
                    errCtrl = c;
                }
            });
        }
        // analyze - go to error
        if (errCtrl) {
            if (this._opts.submitActions & 1 /* SubmitActions.goToError */) {
                const el = errCtrl;
                scrollIntoView(el, { offsetTop: -30, onlyIfNeeded: true }).then(() => el.focus());
            }
            return;
        }
        // collect changes only from valid controls: because some controls has canShowError: false
        arrCtrl = arrCtrl.filter((c) => c.canShowError);
        // collect values to model
        const onlyChanged = this._opts.submitActions & 4 /* SubmitActions.collectChanged */;
        const m = this.#ctr.$modelFromControls({}, arrCtrl, "$value", !!onlyChanged);
        // fire events
        const ev = new CustomEvent("$submit", {
            cancelable: false,
            bubbles: true,
            detail: {
                model: m,
                relatedEvent: e,
                relatedForm: this,
                submitter,
            },
        });
        const needReset = this._opts.submitActions & 8 /* SubmitActions.reset */;
        setTimeout(() => {
            const p1 = this.$onSubmit?.call(this, ev);
            this.dispatchEvent(ev);
            // SubmitEvent constructor doesn't exist on some browsers: https://developer.mozilla.org/en-US/docs/Web/API/SubmitEvent/SubmitEvent
            const ev2 = new (window.SubmitEvent || Event)("submit", { submitter, cancelable: false, bubbles: true });
            /* istanbul ignore else */
            if (!window.SubmitEvent) {
                ev2.submitter = submitter;
            }
            this.dispatchEvent(ev2);
            let success = false;
            promiseWait(Promise.all([p1, ev.detail.waitFor]), 300, (v) => this.changePending(v))
                .then(() => {
                this._opts.autoStore && this.storageSave(null); // clear storage after submit
                if (needReset) {
                    arrCtrl.forEach((v) => (v.$isDirty = false));
                    this.$initModel = this.$model;
                }
                success = true;
            })
                .finally(() => {
                this.fireEvent("$submitEnd", { detail: { success }, cancelable: false, bubbles: true });
            });
        });
    }
    /** Auto-safe debounce timeout */
    #autoStoreT;
    #autoStoreRemEv;
    gotChanges(propsChanged) {
        super.gotChanges(propsChanged);
        this.setAttr("readonly", this._opts.readOnly, true);
        this.setAttr("disabled", this._opts.disabled, true);
        if (this._opts.autoStore) {
            this.#autoStoreRemEv = this.appendEvent(this, "$change", () => {
                if (this._preventStorageSave) {
                    return;
                }
                this.#autoStoreT && clearTimeout(this.#autoStoreT);
                this.#autoStoreT = setTimeout(() => this._opts.autoStore && this.storageSave(), 700);
            });
            // works only on init
            !propsChanged &&
                setTimeout(() => {
                    const m = this.storageGet();
                    if (m) {
                        this._preventStorageSave = true;
                        this.$model = { ...this._initModel, ...m, ...this._model };
                        setTimeout(() => delete this._preventStorageSave);
                    }
                }, 2); // timeout required to wait for init controls
        }
        else if (this.#autoStoreRemEv) {
            this.#autoStoreRemEv.call(this);
            this.#autoStoreRemEv = undefined;
        }
        const p = propsChanged;
        if (p && (p.includes("disabled") || p.includes("autoComplete") || p.includes("readOnly"))) {
            this.$controls.forEach((c) => c.gotFormChanges(propsChanged));
        }
    }
    gotReady() {
        super.gotReady();
        // tie with heading if possible
        if (["title", "aria-label", "aria-labelledby"].every((a) => !this.hasAttribute(a))) {
            const meHeading = (el) => el && (/H[\d]/.test(el.tagName) || el.getAttribute("role") === "heading") ? el : null;
            const h = meHeading(this.firstElementChild) ?? meHeading(this.previousElementSibling);
            if (h) {
                h.id ||= this.#ctr.$uniqueId;
                this.setAttribute("aria-labelledby", h.id);
            }
        }
        this.appendEvent(this, "keydown", (e) => e.key === "Enter" &&
            !e.defaultPrevented &&
            !e.submitPrevented && // textarea related
            !e.shiftKey &&
            !e.ctrlKey &&
            this.gotSubmit(e, e.target instanceof HTMLElement ? e.target : this), { passive: false });
        this.appendEvent(this, "click", (e) => {
            if (!e.defaultPrevented) {
                let t = e.target;
                while (t instanceof HTMLElement && t !== this) {
                    if (t.type === "submit") {
                        this.gotSubmit(e, t);
                        return;
                    }
                    t = t.parentElement;
                }
            }
        }, { passive: false });
    }
    connectedCallback() {
        super.connectedCallback();
        this.setAttribute("role", "form");
        formStore.push(this);
    }
    /** Returns storage key based on url+control-names or `$options.autoStore` if `string` */
    get storageKey() {
        const sn = this._opts.autoStore;
        return typeof sn === "string"
            ? sn
            : `${window.location.pathname}?${this.$controls
                .map((c) => c.$options.name)
                .filter((v) => v)
                .sort()
                .join(",")}`;
    }
    /** Get & parse value from storage according to option `autoStore`, $model */
    storageGet() {
        try {
            const key = this.storageKey;
            const sv = window.localStorage.getItem(key);
            if (sv) {
                const m = JSON.parse(sv);
                let hasVals = false;
                this.$controls.forEach((c) => {
                    const n = c.$options.name;
                    if (!n) {
                        return;
                    }
                    const v = m[n];
                    if (v === undefined) {
                        return;
                    }
                    const parsed = typeof v === "string" ? c.parse(v) : v;
                    nestedProperty.set(m, n, parsed);
                    if (n.includes(".")) {
                        delete m[n];
                    }
                    hasVals = true;
                });
                if (!hasVals) {
                    return null;
                }
                return m;
            }
        }
        catch (err) {
            this.throwError(err); // re-throw error when storage is full
        }
        return null;
    }
    _preventStorageSave;
    /** Save/remove model (only changes) to storage according to option `autoStore`, $model
     * @returns model saved to localStorage or Null if removed */
    storageSave(model = {}) {
        try {
            const storage = window.localStorage;
            if (model == null) {
                storage.removeItem(this.storageKey);
                return null;
            }
            const m = {}; // plain model without nested objects
            let hasChanges = false;
            this.$controls.forEach((c) => {
                // ignore password controls and controls without names
                if (c.$options.name && c.tagName !== "WUP-PWD") {
                    const v = c.$value;
                    if (c.$isChanged && v !== undefined) {
                        if (typeof v === "object" && !v.toJSON && !Array.isArray(v)) {
                            return; // skip complex objects that not serializable: otherwise it can throw err on parse
                        }
                        m[c.$options.name] = v; // get only changed values
                        hasChanges = true;
                    }
                }
            });
            if (hasChanges) {
                storage.setItem(this.storageKey, JSON.stringify(m));
                return m;
            }
            storage.removeItem(this.storageKey);
        }
        catch (err) {
            this.throwError(err); // re-throw error when storage is full
        }
        return null;
    }
    disconnectedCallback() {
        super.disconnectedCallback();
        formStore.splice(formStore.indexOf(this), 1);
    }
}
customElements.define(tagName, WUPFormElement);
// todo show success/error result in <wup-alert> at the left/right angle + add autoSubmit option