@brandup/ui-app 1.0.43 → 2.0.1

package/dist/mjs/index.js

@@ -1,23 +1,44 @@
 import { UIElement } from '@brandup/ui';
 import { Guid } from '@brandup/ui-helpers';
 
+/** Runs a chain of middlewares, invoking the named method on each in registration order. */
 class MiddlewareInvoker {
+    /** Middleware handled by this invoker node. */
     middleware;
     __next;
+    __tail = this;
+    /**
+     * @param middleware Middleware handled by this invoker node.
+     */
     constructor(middleware) {
         this.middleware = middleware;
     }
+    /**
+     * Append a middleware to the end of the chain.
+     * @param middleware Middleware to add.
+     */
     next(middleware) {
-        if (this.__next)
-            this.__next.next(middleware);
-        else
-            this.__next = new MiddlewareInvoker(middleware);
+        const invoker = new MiddlewareInvoker(middleware);
+        this.__tail.__next = invoker;
+        this.__tail = invoker;
     }
+    /**
+     * Invoke the given method across the whole middleware chain.
+     * @param method Name of the middleware method to call (e.g. "start", "navigate").
+     * @param context Invocation context.
+     * @returns Promise resolved when the chain has completed.
+     */
     invoke(method, context) {
         return this.__exec(method, context);
     }
     async __exec(method, context) {
-        const nextFunc = () => this.__next ? this.__next.__exec(method, context) : Promise.resolve();
+        let nextCalled = false;
+        const nextFunc = () => {
+            if (nextCalled)
+                throw new Error(`Middleware "${this.middleware.name}" called next() more than once for method "${method}".`);
+            nextCalled = true;
+            return this.__next ? this.__next.__exec(method, context) : Promise.resolve();
+        };
         context.abort.throwIfAborted();
         const methodFunc = this.middleware[method];
         if (typeof methodFunc === "function") {
@@ -51,14 +72,18 @@ var constants = /*#__PURE__*/Object.freeze({
     default: result
 });
 
+/** Unique name of the built-in state middleware. */
 const STATE_MIDDLEWARE_NAME = "app-state";
+/**
+ * Create the built-in state middleware that toggles loading/loaded/ready CSS state
+ * classes on the application element during start, load, navigation and submit.
+ * @returns The state middleware instance.
+ */
 const StateMiddlewareFactory = () => {
     let counter = 0;
-    //let beginTime: number;
     const begin = (context) => {
         const prev = counter++;
         if (prev === 0) {
-            //beginTime = Date.now();
             context.app.element?.classList.remove(result.STATE_CLASS.LOADED);
             context.app.element?.classList.add(result.STATE_CLASS.LOADING);
         }
@@ -77,6 +102,9 @@ const StateMiddlewareFactory = () => {
             begin(context);
             try {
                 await next();
+                // on success the begin() is left open on purpose: the loading state
+                // must persist through "loaded" and the first navigation, which closes
+                // it (see the "first" branch in navigate). On error we close it here.
             }
             catch (reason) {
                 end(context);
@@ -99,12 +127,15 @@ const StateMiddlewareFactory = () => {
                 await next();
             }
             finally {
+                end(context); // close the begin() of this navigation
+                // the first navigation also closes the loading opened by start(),
+                // which intentionally leaves its begin() open until the page is rendered
                 if (context.source == "first")
                     end(context);
-                end(context);
             }
         },
         submit: async (context, next) => {
+            begin(context);
             try {
                 await next();
             }
@@ -118,10 +149,15 @@ const StateMiddlewareFactory = () => {
     };
 };
 
+/** Unique name of the built-in hyperlink middleware. */
 const HYPERLINK_MIDDLEWARE_NAME = "app-hyperlink";
+/**
+ * Create the built-in hyperlink middleware that intercepts clicks on application links
+ * (anchors with the `applink` class or elements with `data-nav-url`) and routes them through
+ * application navigation. Honors meta/ctrl-click and `target="_blank"` to open in a new tab.
+ * @returns The hyperlink middleware instance.
+ */
 const HyperLinkMiddlewareFactory = () => {
-    let __ctrlPressed = false;
-    const onKeyDownUp = (e) => __ctrlPressed = e.ctrlKey;
     let onClick;
     return {
         name: HYPERLINK_MIDDLEWARE_NAME,
@@ -139,11 +175,9 @@ const HyperLinkMiddlewareFactory = () => {
                         if (elem.classList.contains(result.NavUrlClassName) || elem.hasAttribute(result.NavUrlAttributeName))
                             break;
                     }
-                    if (elem === e.currentTarget)
-                        return;
                     elem = elem.parentElement;
                 }
-                if (!elem || __ctrlPressed || elem.getAttribute("target") === "_blank")
+                if (!elem || e.ctrlKey || e.metaKey || elem.getAttribute("target") === "_blank")
                     return;
                 e.preventDefault();
                 e.stopPropagation();
@@ -154,8 +188,12 @@ const HyperLinkMiddlewareFactory = () => {
                     url = elem.getAttribute("href");
                 else if (elem.hasAttribute(result.NavUrlAttributeName))
                     url = elem.getAttribute(result.NavUrlAttributeName);
-                else
-                    throw "Not found url for navigation.";
+                else {
+                    // matched an applink element with no resolvable url (malformed markup);
+                    // swallow the click rather than throwing inside a global event listener
+                    console.warn("Application hyperlink: clicked element has no navigation url.");
+                    return;
+                }
                 if (elem.classList.contains(result.LoadingElementClass))
                     return;
                 elem.classList.add(result.LoadingElementClass);
@@ -169,18 +207,20 @@ const HyperLinkMiddlewareFactory = () => {
                     .catch(() => { })
                     .finally(() => elem.classList.remove(result.LoadingElementClass));
             }, false);
-            window.addEventListener("keydown", onKeyDownUp, false);
-            window.addEventListener("keyup", onKeyDownUp, false);
         },
         stop: (_context, next) => {
             window.removeEventListener("click", onClick, false);
-            window.removeEventListener("keydown", onKeyDownUp, false);
-            window.removeEventListener("keyup", onKeyDownUp, false);
             return next();
         }
     };
 };
 
+/**
+ * Parse a url into its components relative to the application base path.
+ * @param basePath Application base path.
+ * @param url Url to parse. If null, the current `window.location` is used.
+ * @returns Parsed url parts.
+ */
 const parseUrl = (basePath, url) => {
     const loc = window.location;
     let origin = loc.origin;
@@ -212,7 +252,7 @@ const parseUrl = (basePath, url) => {
             path = loc.pathname;
             query = new URLSearchParams(url);
         }
-        else if (url.startsWith("http")) {
+        else if (/^https?:\/\//i.test(url)) {
             const u = new URL(url);
             if (u.origin != origin) {
                 origin = u.origin;
@@ -248,7 +288,7 @@ const parseUrl = (basePath, url) => {
         path = path.substring(0, path.length - 1);
     path = path.toLowerCase();
     if (basePath) {
-        if (path.toLowerCase().startsWith(basePath.toLowerCase())) {
+        if (path.startsWith(basePath.toLowerCase())) {
             path = path.substring(basePath.length);
             if (!path)
                 path = '/';
@@ -291,8 +331,10 @@ const extendQuery = (url, query) => {
         query.forEach((v, k) => url.query.append(k, v.toString()));
     }
     else {
-        for (let key in query) {
+        for (const key in query) {
             const value = query[key];
+            if (value === null || typeof value === "undefined")
+                continue;
             if (!Array.isArray(value)) {
                 url.query.set(key, value);
             }
@@ -314,6 +356,14 @@ const rebuildUrl = (parsedUrl) => {
     parsedUrl.relative = relativeUrl;
     parsedUrl.full = parsedUrl.hash ? `${parsedUrl.url}#${parsedUrl.hash}` : parsedUrl.url;
 };
+/**
+ * Build a relative url from a base path with optional path, query and hash.
+ * @param basePath Application base path.
+ * @param path Optional path appended to the base path.
+ * @param query Optional query parameters.
+ * @param hash Optional hash.
+ * @returns Relative url with base path.
+ */
 const buildUrl = (basePath, path, query, hash) => {
     let url = basePath;
     if (url == '/')
@@ -358,6 +408,7 @@ const buildUrl = (basePath, path, query, hash) => {
     }
     return url;
 };
+/** Url helper functions. */
 var urlHelper = {
     parseUrl,
     extendQuery,
@@ -369,7 +420,9 @@ var url = /*#__PURE__*/Object.freeze({
     default: urlHelper
 });
 
+/** Type name of the base {@link Application} class. */
 const APP_TYPENAME = "brandup-ui-app";
+/** Reason value thrown when a navigation is overridden (e.g. by a redirect). */
 const NAV_OVERIDE_ERROR = "NavigationOveride";
 /**
  * Base application class.
@@ -386,8 +439,13 @@ class Application extends UIElement {
     __isRuned;
     __middlewares = {};
     __globalSubmit;
+    __onPopStateHandler;
     __execNav; // current navigation invoking
     __lastNav; // last success navigation
+    /**
+     * @param env Application environment.
+     * @param model Application model.
+     */
     constructor(env, model, ..._args) {
         super();
         this.env = env;
@@ -396,6 +454,7 @@ class Application extends UIElement {
         this.invoker = new MiddlewareInvoker(core);
         this.__abort = new AbortController();
     }
+    /** Type name of the application. */
     get typeName() { return APP_TYPENAME; }
     /** Current navigation context. */
     get current() { return this.__lastNav?.context; }
@@ -408,25 +467,36 @@ class Application extends UIElement {
         this.__isInited = true;
         this.onInitialize();
         middlewares.forEach(middleware => {
-            var name = middleware.name;
+            const name = middleware.name;
             if (this.__middlewares.hasOwnProperty(name))
                 throw new Error(`Middleware "${name}" already registered.`);
             this.__middlewares[name] = middleware;
             this.invoker.next(middleware);
         });
     }
-    /** Initialize application instance. */
+    /**
+     * Initialize application instance. Override to register additional middlewares.
+     * Registers the built-in state and hyperlink middlewares by default.
+     */
     onInitialize() {
         this.invoker.next(StateMiddlewareFactory());
         this.invoker.next(HyperLinkMiddlewareFactory());
     }
-    /** Begin run application. */
+    /**
+     * Called at the beginning of application run, before middlewares start.
+     * Override to perform async setup work.
+     * @returns Promise resolved when starting work is complete.
+     */
     onStarting() { return Promise.resolve(); }
-    /** Complate run application. */
+    /**
+     * Called after the application has fully started.
+     * Override to perform async work after start.
+     * @returns Promise resolved when post-start work is complete.
+     */
     onStared() { return Promise.resolve(); }
     /**
-     * Get middleware by type.
-     * @param type Type of middleware.
+     * Get registered middleware by its unique name.
+     * @param name Unique name of middleware.
      * @returns Middleware instance.
      */
     middleware(name) {
@@ -465,7 +535,7 @@ class Application extends UIElement {
             await this.invoker.invoke("loaded", context);
             console.info("app load success");
             this.__abort.signal.throwIfAborted();
-            window.addEventListener("popstate", (e) => this.__onPopState(context, e));
+            window.addEventListener("popstate", this.__onPopStateHandler = (e) => this.__onPopState(context, e));
             element.addEventListener("submit", this.__globalSubmit = (e) => {
                 const form = e.target;
                 if (!form.classList.contains(result.FormClassName))
@@ -474,23 +544,24 @@ class Application extends UIElement {
                 this.__onSubmit({ form, button: e.submitter instanceof HTMLButtonElement ? e.submitter : null })
                     .catch(() => { });
             }, false);
-            await this.onStared();
-            console.info("app runned");
         }
         catch (reason) {
             console.error(`app run error: ${reason}`);
             throw reason;
         }
+        // Run the first navigation before onStared(): its navigate middleware always
+        // closes the startup loading state (in a finally, even on error), so the app
+        // can never get stuck "loading" if onStared throws.
         try {
             await this.nav({ data: context.data, abort: this.__abort.signal });
         }
         catch (reason) {
-            if (reason === NAV_OVERIDE_ERROR) {
-                console.info(`app run nav overided`);
-                return context;
-            }
-            throw reason;
+            if (reason !== NAV_OVERIDE_ERROR)
+                throw reason;
+            console.info(`app run nav overided`);
         }
+        await this.onStared();
+        console.info("app runned");
         return context;
     }
     /**
@@ -510,54 +581,19 @@ class Application extends UIElement {
             action = "first";
         else {
             const isChangedUrl = this.__lastNav?.context.url.toLowerCase() !== navUrl.url.toLowerCase();
-            const hasHash = !!this.__lastNav?.context.hash || !!navUrl.hash;
+            const hasHash = !!navUrl.hash;
             if (isChangedUrl)
-                action = "url-change"; // если изменился url
+                action = "url-change"; // url changed
             else
                 action = hasHash ? "hash" : "url-no-change";
         }
-        let parentNav;
-        if (this.__execNav && this.__execNav.status === "work") {
-            parentNav = this.__execNav;
-            parentNav.abort.abort(NAV_OVERIDE_ERROR);
-            parentNav.context.overided = true;
-        }
-        const navIndex = parentNav ? parentNav.context.index + 1 : 1;
-        const navAbort = new AbortController();
-        const aborts = [this.__abort.signal, navAbort.signal];
-        if (abort)
-            aborts.push(abort);
-        const complextAbort = AbortSignal.any(aborts);
+        const base = this.__beginNav(abort);
         const context = {
-            index: navIndex,
-            id: Guid.createGuid(),
-            source: isFirst ? "first" : "nav",
-            app: this,
-            abort: complextAbort,
-            current: this.__lastNav?.context,
-            parent: parentNav?.context,
-            overided: false,
-            action: action,
-            data,
-            url: navUrl.url,
-            origin: navUrl.origin,
-            pathAndQuery: navUrl.relative,
-            basePath: navUrl.basePath,
-            path: navUrl.path,
-            query: navUrl.query,
-            hash: navUrl.hash,
-            external: navUrl.external,
-            replace,
-            scope,
-            redirect: async (options) => {
-                complextAbort.throwIfAborted();
-                const result = await this.nav(options);
-                complextAbort.throwIfAborted();
-                return result;
-            }
+            ...this.__createContext(base, navUrl, isFirst ? "first" : "nav", action, data, replace),
+            scope
         };
-        const currentNav = { method: "navigate", context, abort: navAbort, status: "work" };
-        return await this.__execNavigate(currentNav, parentNav);
+        const currentNav = { method: "navigate", context, abort: base.navAbort, status: "work" };
+        return await this.__execNavigate(currentNav, base.parentNav);
     }
     /**
      * Reload page with nav.
@@ -573,9 +609,14 @@ class Application extends UIElement {
         this.__abort.signal.throwIfAborted();
         window.location.reload();
     }
+    /**
+     * Destroy application: abort pending navigations, run the middleware "stop" chain and release listeners.
+     * @param contextData Stop context data.
+     * @returns Promise of the stop context.
+     */
     async destroy(contextData) {
         if (this.__abort.signal.aborted)
-            return Promise.reject('Application already destroyed.');
+            return Promise.reject(new Error('Application already destroyed.'));
         this.__abort.abort();
         console.info("app destroy begin");
         if (this.__execNav)
@@ -584,6 +625,8 @@ class Application extends UIElement {
             this.__lastNav.abort.abort();
         if (this.__globalSubmit)
             this.element?.removeEventListener("submit", this.__globalSubmit);
+        if (this.__onPopStateHandler)
+            window.removeEventListener("popstate", this.__onPopStateHandler);
         const destroyAbort = new AbortController();
         const context = {
             abort: destroyAbort.signal,
@@ -619,6 +662,10 @@ class Application extends UIElement {
         const { form, button = null, query, data = {} } = opt;
         if ((!button || !button.formNoValidate) && !form.checkValidity())
             throw new Error('Form is invalid.');
+        // guard before applying any loading class, otherwise a rejected re-entrant
+        // submit would leave the button stuck in the loading state
+        if (form.classList.contains(result.LoadingElementClass))
+            throw new Error('Form already submitting.');
         let replace = form.hasAttribute(result.NavUrlReplaceAttributeName);
         let method = form.method;
         let enctype = form.enctype;
@@ -634,62 +681,30 @@ class Application extends UIElement {
             if (button.hasAttribute(result.NavUrlReplaceAttributeName))
                 replace = true;
         }
-        if (form.classList.contains(result.LoadingElementClass))
-            throw new Error('Form already submitting.');
         form.classList.add(result.LoadingElementClass);
         method = method.toUpperCase();
         try {
-            if (method === "GET")
-                await this.nav({ url, query: new FormData(form), data: data, replace, abort: opt.abort });
+            if (method === "GET") {
+                const getUrl = urlHelper.parseUrl(this.env.basePath, url);
+                urlHelper.extendQuery(getUrl, new FormData(form));
+                if (query)
+                    urlHelper.extendQuery(getUrl, query);
+                await this.nav({ url: getUrl.url, data: data, replace, abort: opt.abort });
+            }
             else {
                 const navUrl = urlHelper.parseUrl(this.env.basePath, url);
                 if (query)
                     urlHelper.extendQuery(navUrl, query);
-                let parentNav;
-                if (this.__execNav && this.__execNav.status === "work") {
-                    parentNav = this.__execNav;
-                    parentNav.abort.abort(NAV_OVERIDE_ERROR);
-                    parentNav.context.overided = true;
-                }
-                const navIndex = parentNav ? parentNav.context.index + 1 : 1;
-                const submitAbort = new AbortController();
-                const aborts = [this.__abort.signal, submitAbort.signal];
-                if (opt.abort)
-                    aborts.push(opt.abort);
-                const complextAbort = AbortSignal.any(aborts);
-                let context = {
-                    index: navIndex,
-                    id: Guid.createGuid(),
-                    source: "submit",
-                    app: this,
-                    abort: complextAbort,
-                    current: this.__lastNav?.context,
-                    parent: parentNav?.context,
-                    overided: false,
-                    action: "submit",
-                    data,
+                const base = this.__beginNav(opt.abort);
+                const context = {
+                    ...this.__createContext(base, navUrl, "submit", "submit", data, replace),
                     form,
                     button,
                     method,
-                    enctype,
-                    url: navUrl.url,
-                    origin: navUrl.origin,
-                    pathAndQuery: navUrl.relative,
-                    basePath: navUrl.basePath,
-                    path: navUrl.path,
-                    query: navUrl.query,
-                    hash: navUrl.hash,
-                    external: navUrl.external,
-                    replace,
-                    redirect: async (options) => {
-                        complextAbort.throwIfAborted();
-                        const result = await this.nav(options);
-                        complextAbort.throwIfAborted();
-                        return result;
-                    }
+                    enctype
                 };
-                const currentNav = { method: "submit", context, abort: submitAbort, status: "work" };
-                await this.__execNavigate(currentNav);
+                const currentNav = { method: "submit", context, abort: base.navAbort, status: "work" };
+                await this.__execNavigate(currentNav, base.parentNav);
             }
         }
         finally {
@@ -701,7 +716,53 @@ class Application extends UIElement {
     __onPopState(_context, event) {
         const popUrl = location.href;
         console.log(`popstate: ${popUrl}`, event.state);
-        this.nav({ url: popUrl, data: { popstate: event.state } });
+        this.nav({ url: popUrl, data: { popstate: event.state } })
+            .catch(() => { });
+    }
+    /** Detect parent (overriding) navigation and compose the abort signal shared by a new navigation. */
+    __beginNav(abort) {
+        let parentNav;
+        if (this.__execNav && this.__execNav.status === "work") {
+            parentNav = this.__execNav;
+            parentNav.abort.abort(NAV_OVERIDE_ERROR);
+            parentNav.context.overided = true;
+        }
+        const navAbort = new AbortController();
+        const aborts = [this.__abort.signal, navAbort.signal];
+        if (abort)
+            aborts.push(abort);
+        return { parentNav, navAbort, abort: AbortSignal.any(aborts) };
+    }
+    /** Build the navigation context fields shared by nav and submit. */
+    __createContext(base, navUrl, source, action, data, replace) {
+        const { parentNav, abort } = base;
+        return {
+            index: parentNav ? parentNav.context.index + 1 : 1,
+            id: Guid.createGuid(),
+            source,
+            app: this,
+            abort,
+            current: this.__lastNav?.context,
+            parent: parentNav?.context,
+            overided: false,
+            action,
+            data,
+            url: navUrl.url,
+            origin: navUrl.origin,
+            pathAndQuery: navUrl.relative,
+            basePath: navUrl.basePath,
+            path: navUrl.path,
+            query: navUrl.query,
+            hash: navUrl.hash,
+            external: navUrl.external,
+            replace,
+            redirect: async (options) => {
+                abort.throwIfAborted();
+                const result = await this.nav(options);
+                abort.throwIfAborted();
+                return result;
+            }
+        };
     }
     async __execNavigate(nav, parent) {
         if (parent)
@@ -737,51 +798,76 @@ class Application extends UIElement {
     }
 }
 
+/** Fluent builder that configures the application type, middlewares and model, then constructs an {@link Application}. */
 class ApplicationBuilder {
     __model;
     __appType = (Application);
     __middlewares = [];
+    /**
+     * @param model Application model used when building the application.
+     */
     constructor(model) {
         this.__model = model;
     }
+    /**
+     * Set a custom application type to instantiate instead of the base {@link Application}.
+     * @param appType Application class constructor.
+     * @returns The builder, for chaining.
+     */
     useApp(appType) {
         this.__appType = appType;
         return this;
     }
+    /**
+     * Register a middleware via its factory function. Middlewares run in registration order.
+     * @param createFunc Factory that creates the middleware instance.
+     * @param params Optional arguments passed to the factory.
+     * @returns The builder, for chaining.
+     */
     useMiddleware(createFunc, ...params) {
         let midl = createFunc(...params);
         this.__middlewares.push(midl);
         return this;
     }
+    /**
+     * Build and initialize the application instance.
+     * @param env Application environment (a base path of `/` is normalized to empty).
+     * @param args Extra arguments forwarded to the application constructor.
+     * @returns The initialized application instance.
+     */
     build(env, ...args) {
-        if (!env.basePath || env.basePath == '/')
-            env.basePath = '';
-        const app = new this.__appType(env, this.__model, ...args);
+        const appEnv = { ...env };
+        if (!appEnv.basePath || appEnv.basePath == '/')
+            appEnv.basePath = '';
+        const app = new this.__appType(appEnv, this.__model, ...args);
         app.initialize(this.__middlewares);
         return app;
     }
 }
 
-HTMLElement.prototype.navUrl = function (url) {
-    if (this instanceof HTMLAnchorElement)
-        this.href = url;
-    else
-        this.dataset.navUrl = url;
-    this.classList.add(result.NavUrlClassName);
-    return this;
-};
-HTMLElement.prototype.nav = function (app, path, query, hash) {
-    const url = app.buildUrl(path, query, hash);
-    return this.navUrl(url);
-};
-HTMLElement.prototype.navReplace = function () {
-    this.setAttribute(result.NavUrlReplaceAttributeName, "");
-    return this;
-};
-HTMLElement.prototype.navScope = function (scope) {
-    this.setAttribute(result.NavUrlScopeAttributeName, scope);
-    return this;
-};
+// Guarded so importing the module does not throw in a non-DOM environment (SSR/Node).
+if (typeof HTMLElement !== "undefined") {
+    HTMLElement.prototype.navUrl = function (url) {
+        if (this instanceof HTMLAnchorElement)
+            this.href = url;
+        else
+            this.dataset.navUrl = url;
+        this.classList.add(result.NavUrlClassName);
+        return this;
+    };
+    HTMLElement.prototype.nav = function (app, path, query, hash) {
+        const url = app.buildUrl(path, query, hash);
+        return this.navUrl(url);
+    };
+    HTMLElement.prototype.navReplace = function () {
+        this.setAttribute(result.NavUrlReplaceAttributeName, "");
+        return this;
+    };
+    HTMLElement.prototype.navScope = function (scope) {
+        this.setAttribute(result.NavUrlScopeAttributeName, scope);
+        return this;
+    };
+}
 
 export { APP_TYPENAME, Application, ApplicationBuilder, constants as CONSTANTS, NAV_OVERIDE_ERROR, url as UrlHelper };
 //# sourceMappingURL=index.js.map