uicore-ts 1.1.362 → 1.1.363

package/compiledScripts/UIRoute.d.ts

@@ -8,7 +8,15 @@ export interface UIRouteComponent<T = any> {
     name: string;
     parameters: UIRouteParameters<T>;
 }
+export interface UIRouteChangeDescriptor {
+    currentRoute: UIRoute;
+    targetRoute: UIRoute;
+    forcefully: boolean;
+    replacesCurrentRouteInHistory: boolean;
+}
+export type UIRouteShouldApplyRouteChangeCallbackFunction = (routeChangeDescriptor: UIRouteChangeDescriptor) => boolean | Promise<boolean>;
 export declare class UIRoute extends Array<UIRouteComponent> {
+    static ShouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction;
     constructor(hash?: string);
     static get currentRoute(): UIRoute;
     /**
@@ -19,13 +27,29 @@ export declare class UIRoute extends Array<UIRouteComponent> {
      * "tap the already-active tab to reset to root" feature in TopBarView).
      * Defaults to `false`.
      */
-    apply(forcefully?: boolean): void;
+    apply(forcefully?: boolean): boolean | Promise<boolean>;
+    /**
+     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.
+     * Use this only for route changes that are internal bookkeeping or that already
+     * passed a higher-level confirmation flow.
+     */
+    applyWithoutRouteApplicationCheck(forcefully?: boolean): boolean;
     /**
      * @param forcefully When `true`, replaces the current history entry with
      * this route even when the route is identical to the current URL hash.
      * Defaults to `false`.
      */
-    applyByReplacingCurrentRouteInHistory(forcefully?: boolean): void;
+    applyByReplacingCurrentRouteInHistory(forcefully?: boolean): boolean | Promise<boolean>;
+    /**
+     * Replaces the current history entry without consulting
+     * `UIRoute.routeApplicationShouldProceed`.
+     */
+    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully?: boolean): boolean;
+    _applyRouteAfterRouteApplicationCheck(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean | Promise<boolean>;
+    _applyRouteIfAllowed(routeApplicationShouldProceed: boolean, forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
+    _applyRouteWithoutRouteApplicationCheck(forcefully: boolean, replacesCurrentRouteInHistory: boolean): boolean;
+    _needsRouteApplication(forcefully: boolean): boolean;
+    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor;
     copy(): UIRoute;
     routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]): UIRoute;
     routeByRemovingComponentNamed(componentName: string): UIRoute;
@@ -35,7 +59,7 @@ export declare class UIRoute extends Array<UIRouteComponent> {
         [P in keyof T["ParameterIdentifierName"]]: string;
     }>, extendParameters?: boolean): UIRoute;
     routeWithComponent(name: string, parameters: UIRouteParameters, extendParameters?: boolean): UIRoute;
-    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters?: boolean): void;
+    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters?: boolean): boolean | Promise<boolean>;
     componentWithViewController<T extends typeof UIViewController>(viewController: T): UIRouteComponent<{
         [P in ValueOf<T["ParameterIdentifierName"]>]: string;
     }> | undefined;

package/compiledScripts/UIRoute.js

@@ -59,18 +59,69 @@ class UIRoute extends Array {
     return new UIRoute(window.location.hash);
   }
   apply(forcefully = import_UIObject.NO) {
-    const stringRepresentation = this.stringRepresentation;
-    if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {
-      return;
-    }
-    window.location.hash = stringRepresentation;
+    return this._applyRouteAfterRouteApplicationCheck(forcefully, import_UIObject.NO);
+  }
+  applyWithoutRouteApplicationCheck(forcefully = import_UIObject.NO) {
+    return this._applyRouteWithoutRouteApplicationCheck(forcefully, import_UIObject.NO);
   }
   applyByReplacingCurrentRouteInHistory(forcefully = import_UIObject.NO) {
-    const stringRepresentation = this.stringRepresentation;
-    if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {
-      return;
+    return this._applyRouteAfterRouteApplicationCheck(forcefully, import_UIObject.YES);
+  }
+  applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = import_UIObject.NO) {
+    return this._applyRouteWithoutRouteApplicationCheck(forcefully, import_UIObject.YES);
+  }
+  _applyRouteAfterRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory) {
+    if (!this._needsRouteApplication(forcefully)) {
+      return import_UIObject.NO;
+    }
+    const routeApplicationShouldProceed = UIRoute.ShouldApplyRouteChange;
+    if (!routeApplicationShouldProceed) {
+      return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory);
+    }
+    const shouldProceed = routeApplicationShouldProceed(
+      this._routeApplication(forcefully, replacesCurrentRouteInHistory)
+    );
+    if (shouldProceed instanceof Promise) {
+      return shouldProceed.then((routeApplicationShouldProceed2) => {
+        return this._applyRouteIfAllowed(
+          routeApplicationShouldProceed2,
+          forcefully,
+          replacesCurrentRouteInHistory
+        );
+      });
     }
-    window.location.replace(this.linkRepresentation);
+    return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory);
+  }
+  _applyRouteIfAllowed(routeApplicationShouldProceed, forcefully, replacesCurrentRouteInHistory) {
+    if (!routeApplicationShouldProceed) {
+      return import_UIObject.NO;
+    }
+    return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory);
+  }
+  _applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory) {
+    if (!this._needsRouteApplication(forcefully)) {
+      return import_UIObject.NO;
+    }
+    if (replacesCurrentRouteInHistory) {
+      window.location.replace(this.linkRepresentation);
+    } else {
+      window.location.hash = this.stringRepresentation;
+    }
+    return import_UIObject.YES;
+  }
+  _needsRouteApplication(forcefully) {
+    if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {
+      return import_UIObject.NO;
+    }
+    return import_UIObject.YES;
+  }
+  _routeApplication(forcefully, replacesCurrentRouteInHistory) {
+    return {
+      currentRoute: UIRoute.currentRoute,
+      targetRoute: this.copy(),
+      forcefully,
+      replacesCurrentRouteInHistory
+    };
   }
   copy() {
     const result = new UIRoute(this.stringRepresentation);
@@ -148,7 +199,7 @@ class UIRoute extends Array {
     return result;
   }
   navigateBySettingComponent(name, parameters, extendParameters = import_UIObject.NO) {
-    this.routeWithComponent(name, parameters, extendParameters).apply();
+    return this.routeWithComponent(name, parameters, extendParameters).apply();
   }
   componentWithViewController(viewController) {
     return this.componentWithName(viewController.routeComponentName);

package/compiledScripts/UIRoute.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../scripts/UIRoute.ts"],
-  "sourcesContent": ["import { IS_NIL, IS_NOT, NO, ValueOf } from \"./UIObject\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];\n\nexport type UIRouteParameters<T = any> = {\n    \n    [key: string]: string;\n    \n} | T;\n\n\nexport interface UIRouteComponent<T = any> {\n    \n    name: string;\n    parameters: UIRouteParameters<T>;\n    \n}\n\n\nexport class UIRoute extends Array<UIRouteComponent> {\n    \n    constructor(hash?: string) {\n        \n        super()\n        \n        if (!hash || !hash.startsWith) {\n            \n            return\n            \n        }\n        \n        if (hash.startsWith(\"#\")) {\n            hash = hash.slice(1)\n        }\n        \n        hash = decodeURIComponent(hash)\n        \n        const components = hash.split(\"]\")\n        components.forEach(component => {\n            \n            const componentName = component.split(\"[\")[0]\n            const parameters: Record<string, string> = {}\n            \n            if (!componentName) {\n                return\n            }\n            \n            const parametersString = component.split(\"[\")[1] || \"\"\n            const parameterPairStrings = parametersString.split(\",\") || []\n            \n            parameterPairStrings.forEach(pairString => {\n                \n                const keyAndValueArray = pairString.split(\":\")\n                const key = decodeURIComponent(keyAndValueArray[0])\n                const value = decodeURIComponent(keyAndValueArray[1])\n                \n                if (key) {\n                    parameters[key] = value\n                }\n                \n            })\n            \n            \n            this.push({\n                name: componentName,\n                parameters: parameters\n            })\n            \n        })\n        \n        \n    }\n    \n    \n    static get currentRoute() {\n        \n        return new UIRoute(window.location.hash)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, applies the route even if its string\n     * representation is identical to the current URL hash, causing the browser\n     * to fire a `hashchange` event and re-run the full `handleRoute` flow.\n     * Use this only when you explicitly need re-entrant navigation (e.g. the\n     * \"tap the already-active tab to reset to root\" feature in TopBarView).\n     * Defaults to `false`.\n     */\n    apply(forcefully = NO) {\n        \n        const stringRepresentation = this.stringRepresentation\n        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {\n            return\n        }\n        \n        window.location.hash = stringRepresentation\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, replaces the current history entry with\n     * this route even when the route is identical to the current URL hash.\n     * Defaults to `false`.\n     */\n    applyByReplacingCurrentRouteInHistory(forcefully = NO) {\n        \n        const stringRepresentation = this.stringRepresentation\n        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {\n            return\n        }\n        \n        window.location.replace(this.linkRepresentation)\n        \n    }\n    \n    \n    override copy() {\n        const result = new UIRoute(this.stringRepresentation)\n        return result\n    }\n    \n    \n    routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]) {\n        const result = this.copy()\n        const indexesToRemove: number[] = []\n        result.forEach(function (component, index, array) {\n            if (!componentNames.contains(component.name)) {\n                indexesToRemove.push(index)\n            }\n        })\n        indexesToRemove.forEach(function (indexToRemove, index, array) {\n            result.removeElementAtIndex(indexToRemove)\n        })\n        return result\n    }\n    \n    \n    routeByRemovingComponentNamed(componentName: string) {\n        const result = this.copy()\n        const componentIndex = result.findIndex(function (component, index) {\n            return (component.name == componentName)\n        })\n        if (componentIndex != -1) {\n            result.splice(componentIndex, 1)\n        }\n        return result\n    }\n    \n    \n    routeByRemovingParameterInComponent(componentName: string, parameterName: string, removeComponentIfEmpty = NO) {\n        let result = this.copy()\n        let parameters = result.componentWithName(componentName)?.parameters ?? {}\n        delete parameters[parameterName]\n        result = result.routeWithComponent(componentName, parameters)\n        if (removeComponentIfEmpty && Object.keys(parameters).length == 0) {\n            result = result.routeByRemovingComponentNamed(componentName)\n        }\n        return result\n    }\n    \n    routeBySettingParameterInComponent(componentName: string, parameterName: string, valueToSet: string) {\n        let result = this.copy()\n        if (IS_NIL(valueToSet) || IS_NIL(parameterName)) {\n            return result\n        }\n        let parameters = result.componentWithName(componentName)?.parameters\n        if (IS_NOT(parameters)) {\n            parameters = {}\n        }\n        parameters[parameterName] = valueToSet\n        result = result.routeWithComponent(componentName, parameters)\n        return result\n    }\n    \n    \n    routeWithViewControllerComponent<T extends typeof UIViewController>(\n        viewController: T,\n        parameters: UIRouteParameters<{ [P in keyof T[\"ParameterIdentifierName\"]]: string }>,\n        extendParameters: boolean = NO\n    ) {\n        \n        return this.routeWithComponent(viewController.routeComponentName, parameters, extendParameters)\n        \n    }\n    \n    routeWithComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        const result = this.copy()\n        let component = result.componentWithName(name)\n        if (IS_NOT(component)) {\n            component = {\n                name: name,\n                parameters: {}\n            }\n            result.push(component)\n        }\n        \n        if (IS_NOT(parameters)) {\n            \n            parameters = {}\n            \n        }\n        \n        if (extendParameters) {\n            component.parameters = Object.assign(component.parameters, parameters)\n        }\n        else {\n            component.parameters = parameters\n        }\n        \n        return result\n        \n    }\n    \n    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        this.routeWithComponent(name, parameters, extendParameters).apply()\n        \n    }\n    \n    \n    componentWithViewController<T extends typeof UIViewController>(viewController: T): UIRouteComponent<{ [P in ValueOf<T[\"ParameterIdentifierName\"]>]: string }> | undefined {\n        \n        return this.componentWithName(viewController.routeComponentName)\n        \n    }\n    \n    componentWithName(name: string): UIRouteComponent | undefined {\n        let result\n        this.forEach(function (component, index, self) {\n            if (component.name == name) {\n                result = component\n            }\n        })\n        return result\n    }\n    \n    \n    get linkRepresentation() {\n        return \"#\" + this.stringRepresentation\n    }\n    \n    \n    get stringRepresentation() {\n        \n        let result = \"\"\n        this.forEach(function (component, index, self) {\n            result = result + component.name\n            const parameters = component.parameters\n            result = result + \"[\"\n            Object.keys(parameters).forEach(function (key, index, keys) {\n                if (index) {\n                    result = result + \",\"\n                }\n                result = result + encodeURIComponent(key) + \":\" + encodeURIComponent(parameters[key])\n            })\n            result = result + \"]\"\n        })\n        \n        return result\n        \n    }\n    \n    \n}\n"],
-  "mappings": "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",
-  "names": ["index"]
+  "sourcesContent": ["import { IS_NIL, IS_NOT, NO, ValueOf, YES } from \"./UIObject\"\nimport { UIViewController } from \"./UIViewController\"\n\n\nexport type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];\n\nexport type UIRouteParameters<T = any> = {\n    \n    [key: string]: string;\n    \n} | T;\n\n\nexport interface UIRouteComponent<T = any> {\n    \n    name: string;\n    parameters: UIRouteParameters<T>;\n    \n}\n\n\nexport interface UIRouteChangeDescriptor {\n    \n    currentRoute: UIRoute;\n    targetRoute: UIRoute;\n    forcefully: boolean;\n    replacesCurrentRouteInHistory: boolean;\n    \n}\n\n\nexport type UIRouteShouldApplyRouteChangeCallbackFunction = (\n    routeChangeDescriptor: UIRouteChangeDescriptor\n) => boolean | Promise<boolean>;\n\n\nexport class UIRoute extends Array<UIRouteComponent> {\n    \n    static ShouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction\n    \n    constructor(hash?: string) {\n        \n        super()\n        \n        if (!hash || !hash.startsWith) {\n            \n            return\n            \n        }\n        \n        if (hash.startsWith(\"#\")) {\n            hash = hash.slice(1)\n        }\n        \n        hash = decodeURIComponent(hash)\n        \n        const components = hash.split(\"]\")\n        components.forEach(component => {\n            \n            const componentName = component.split(\"[\")[0]\n            const parameters: Record<string, string> = {}\n            \n            if (!componentName) {\n                return\n            }\n            \n            const parametersString = component.split(\"[\")[1] || \"\"\n            const parameterPairStrings = parametersString.split(\",\") || []\n            \n            parameterPairStrings.forEach(pairString => {\n                \n                const keyAndValueArray = pairString.split(\":\")\n                const key = decodeURIComponent(keyAndValueArray[0])\n                const value = decodeURIComponent(keyAndValueArray[1])\n                \n                if (key) {\n                    parameters[key] = value\n                }\n                \n            })\n            \n            \n            this.push({\n                name: componentName,\n                parameters: parameters\n            })\n            \n        })\n        \n        \n    }\n    \n    \n    static get currentRoute() {\n        \n        return new UIRoute(window.location.hash)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, applies the route even if its string\n     * representation is identical to the current URL hash, causing the browser\n     * to fire a `hashchange` event and re-run the full `handleRoute` flow.\n     * Use this only when you explicitly need re-entrant navigation (e.g. the\n     * \"tap the already-active tab to reset to root\" feature in TopBarView).\n     * Defaults to `false`.\n     */\n    apply(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteApplicationCheck(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.\n     * Use this only for route changes that are internal bookkeeping or that already\n     * passed a higher-level confirmation flow.\n     */\n    applyWithoutRouteApplicationCheck(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, NO)\n        \n    }\n    \n    \n    /**\n     * @param forcefully When `true`, replaces the current history entry with\n     * this route even when the route is identical to the current URL hash.\n     * Defaults to `false`.\n     */\n    applyByReplacingCurrentRouteInHistory(forcefully = NO): boolean | Promise<boolean> {\n        \n        return this._applyRouteAfterRouteApplicationCheck(forcefully, YES)\n        \n    }\n    \n    \n    /**\n     * Replaces the current history entry without consulting\n     * `UIRoute.routeApplicationShouldProceed`.\n     */\n    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = NO): boolean {\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, YES)\n        \n    }\n    \n    \n    _applyRouteAfterRouteApplicationCheck(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean | Promise<boolean> {\n        \n        if (!this._needsRouteApplication(forcefully)) {\n            return NO\n        }\n        \n        const routeApplicationShouldProceed = UIRoute.ShouldApplyRouteChange\n        if (!routeApplicationShouldProceed) {\n            return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)\n        }\n        \n        const shouldProceed = routeApplicationShouldProceed(\n            this._routeApplication(forcefully, replacesCurrentRouteInHistory)\n        )\n        \n        if (shouldProceed instanceof Promise) {\n            return shouldProceed.then(routeApplicationShouldProceed => {\n                return this._applyRouteIfAllowed(\n                    routeApplicationShouldProceed,\n                    forcefully,\n                    replacesCurrentRouteInHistory\n                )\n            })\n        }\n        \n        return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteIfAllowed(\n        routeApplicationShouldProceed: boolean,\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!routeApplicationShouldProceed) {\n            return NO\n        }\n        \n        return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)\n        \n    }\n    \n    \n    _applyRouteWithoutRouteApplicationCheck(\n        forcefully: boolean,\n        replacesCurrentRouteInHistory: boolean\n    ): boolean {\n        \n        if (!this._needsRouteApplication(forcefully)) {\n            return NO\n        }\n        \n        if (replacesCurrentRouteInHistory) {\n            window.location.replace(this.linkRepresentation)\n        }\n        else {\n            window.location.hash = this.stringRepresentation\n        }\n        \n        return YES\n        \n    }\n    \n    \n    _needsRouteApplication(forcefully: boolean): boolean {\n        \n        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {\n            return NO\n        }\n        \n        return YES\n        \n    }\n    \n    \n    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {\n        \n        return {\n            currentRoute: UIRoute.currentRoute,\n            targetRoute: this.copy(),\n            forcefully: forcefully,\n            replacesCurrentRouteInHistory: replacesCurrentRouteInHistory\n        }\n        \n    }\n    \n    \n    override copy() {\n        const result = new UIRoute(this.stringRepresentation)\n        return result\n    }\n    \n    \n    routeByRemovingComponentsOtherThanOnesNamed(componentNames: string[]) {\n        const result = this.copy()\n        const indexesToRemove: number[] = []\n        result.forEach(function (component, index, array) {\n            if (!componentNames.contains(component.name)) {\n                indexesToRemove.push(index)\n            }\n        })\n        indexesToRemove.forEach(function (indexToRemove, index, array) {\n            result.removeElementAtIndex(indexToRemove)\n        })\n        return result\n    }\n    \n    \n    routeByRemovingComponentNamed(componentName: string) {\n        const result = this.copy()\n        const componentIndex = result.findIndex(function (component, index) {\n            return (component.name == componentName)\n        })\n        if (componentIndex != -1) {\n            result.splice(componentIndex, 1)\n        }\n        return result\n    }\n    \n    \n    routeByRemovingParameterInComponent(componentName: string, parameterName: string, removeComponentIfEmpty = NO) {\n        let result = this.copy()\n        let parameters = result.componentWithName(componentName)?.parameters ?? {}\n        delete parameters[parameterName]\n        result = result.routeWithComponent(componentName, parameters)\n        if (removeComponentIfEmpty && Object.keys(parameters).length == 0) {\n            result = result.routeByRemovingComponentNamed(componentName)\n        }\n        return result\n    }\n    \n    routeBySettingParameterInComponent(componentName: string, parameterName: string, valueToSet: string) {\n        let result = this.copy()\n        if (IS_NIL(valueToSet) || IS_NIL(parameterName)) {\n            return result\n        }\n        let parameters = result.componentWithName(componentName)?.parameters\n        if (IS_NOT(parameters)) {\n            parameters = {}\n        }\n        parameters[parameterName] = valueToSet\n        result = result.routeWithComponent(componentName, parameters)\n        return result\n    }\n    \n    \n    routeWithViewControllerComponent<T extends typeof UIViewController>(\n        viewController: T,\n        parameters: UIRouteParameters<{ [P in keyof T[\"ParameterIdentifierName\"]]: string }>,\n        extendParameters: boolean = NO\n    ) {\n        \n        return this.routeWithComponent(viewController.routeComponentName, parameters, extendParameters)\n        \n    }\n    \n    routeWithComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        const result = this.copy()\n        let component = result.componentWithName(name)\n        if (IS_NOT(component)) {\n            component = {\n                name: name,\n                parameters: {}\n            }\n            result.push(component)\n        }\n        \n        if (IS_NOT(parameters)) {\n            \n            parameters = {}\n            \n        }\n        \n        if (extendParameters) {\n            component.parameters = Object.assign(component.parameters, parameters)\n        }\n        else {\n            component.parameters = parameters\n        }\n        \n        return result\n        \n    }\n    \n    navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {\n        \n        return this.routeWithComponent(name, parameters, extendParameters).apply()\n        \n    }\n    \n    \n    componentWithViewController<T extends typeof UIViewController>(viewController: T): UIRouteComponent<{ [P in ValueOf<T[\"ParameterIdentifierName\"]>]: string }> | undefined {\n        \n        return this.componentWithName(viewController.routeComponentName)\n        \n    }\n    \n    componentWithName(name: string): UIRouteComponent | undefined {\n        let result\n        this.forEach(function (component, index, self) {\n            if (component.name == name) {\n                result = component\n            }\n        })\n        return result\n    }\n    \n    \n    get linkRepresentation() {\n        return \"#\" + this.stringRepresentation\n    }\n    \n    \n    get stringRepresentation() {\n        \n        let result = \"\"\n        this.forEach(function (component, index, self) {\n            result = result + component.name\n            const parameters = component.parameters\n            result = result + \"[\"\n            Object.keys(parameters).forEach(function (key, index, keys) {\n                if (index) {\n                    result = result + \",\"\n                }\n                result = result + encodeURIComponent(key) + \":\" + encodeURIComponent(parameters[key])\n            })\n            result = result + \"]\"\n        })\n        \n        return result\n        \n    }\n    \n    \n}\n"],
+  "mappings": "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",
+  "names": ["routeApplicationShouldProceed", "index"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uicore-ts",
-  "version": "1.1.362",
+  "version": "1.1.363",
   "description": "UICore is a library to build native-like user interfaces using pure Typescript. No HTML is needed at all. Components are described as TS classes and all user interactions are handled explicitly. This library is strongly inspired by the UIKit framework that is used in IOS. In addition, UICore has tools to handle URL based routing, array sorting and filtering and adds a number of other utilities for convenience.",
   "main": "compiledScripts/index.js",
   "types": "compiledScripts/index.d.ts",

package/scripts/UIRoute.ts

@@ -1,4 +1,4 @@
-import { IS_NIL, IS_NOT, NO, ValueOf } from "./UIObject"
+import { IS_NIL, IS_NOT, NO, ValueOf, YES } from "./UIObject"
 import { UIViewController } from "./UIViewController"
 
 
@@ -19,8 +19,25 @@ export interface UIRouteComponent<T = any> {
 }
 
 
+export interface UIRouteChangeDescriptor {
+    
+    currentRoute: UIRoute;
+    targetRoute: UIRoute;
+    forcefully: boolean;
+    replacesCurrentRouteInHistory: boolean;
+    
+}
+
+
+export type UIRouteShouldApplyRouteChangeCallbackFunction = (
+    routeChangeDescriptor: UIRouteChangeDescriptor
+) => boolean | Promise<boolean>;
+
+
 export class UIRoute extends Array<UIRouteComponent> {
     
+    static ShouldApplyRouteChange?: UIRouteShouldApplyRouteChangeCallbackFunction
+    
     constructor(hash?: string) {
         
         super()
@@ -89,14 +106,21 @@ export class UIRoute extends Array<UIRouteComponent> {
      * "tap the already-active tab to reset to root" feature in TopBarView).
      * Defaults to `false`.
      */
-    apply(forcefully = NO) {
+    apply(forcefully = NO): boolean | Promise<boolean> {
         
-        const stringRepresentation = this.stringRepresentation
-        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {
-            return
-        }
+        return this._applyRouteAfterRouteApplicationCheck(forcefully, NO)
+        
+    }
+    
+    
+    /**
+     * Applies this route without consulting `UIRoute.routeApplicationShouldProceed`.
+     * Use this only for route changes that are internal bookkeeping or that already
+     * passed a higher-level confirmation flow.
+     */
+    applyWithoutRouteApplicationCheck(forcefully = NO): boolean {
         
-        window.location.hash = stringRepresentation
+        return this._applyRouteWithoutRouteApplicationCheck(forcefully, NO)
         
     }
     
@@ -106,14 +130,112 @@ export class UIRoute extends Array<UIRouteComponent> {
      * this route even when the route is identical to the current URL hash.
      * Defaults to `false`.
      */
-    applyByReplacingCurrentRouteInHistory(forcefully = NO) {
+    applyByReplacingCurrentRouteInHistory(forcefully = NO): boolean | Promise<boolean> {
         
-        const stringRepresentation = this.stringRepresentation
-        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == stringRepresentation) {
-            return
+        return this._applyRouteAfterRouteApplicationCheck(forcefully, YES)
+        
+    }
+    
+    
+    /**
+     * Replaces the current history entry without consulting
+     * `UIRoute.routeApplicationShouldProceed`.
+     */
+    applyByReplacingCurrentRouteInHistoryWithoutRouteApplicationCheck(forcefully = NO): boolean {
+        
+        return this._applyRouteWithoutRouteApplicationCheck(forcefully, YES)
+        
+    }
+    
+    
+    _applyRouteAfterRouteApplicationCheck(
+        forcefully: boolean,
+        replacesCurrentRouteInHistory: boolean
+    ): boolean | Promise<boolean> {
+        
+        if (!this._needsRouteApplication(forcefully)) {
+            return NO
+        }
+        
+        const routeApplicationShouldProceed = UIRoute.ShouldApplyRouteChange
+        if (!routeApplicationShouldProceed) {
+            return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)
+        }
+        
+        const shouldProceed = routeApplicationShouldProceed(
+            this._routeApplication(forcefully, replacesCurrentRouteInHistory)
+        )
+        
+        if (shouldProceed instanceof Promise) {
+            return shouldProceed.then(routeApplicationShouldProceed => {
+                return this._applyRouteIfAllowed(
+                    routeApplicationShouldProceed,
+                    forcefully,
+                    replacesCurrentRouteInHistory
+                )
+            })
+        }
+        
+        return this._applyRouteIfAllowed(shouldProceed, forcefully, replacesCurrentRouteInHistory)
+        
+    }
+    
+    
+    _applyRouteIfAllowed(
+        routeApplicationShouldProceed: boolean,
+        forcefully: boolean,
+        replacesCurrentRouteInHistory: boolean
+    ): boolean {
+        
+        if (!routeApplicationShouldProceed) {
+            return NO
         }
         
-        window.location.replace(this.linkRepresentation)
+        return this._applyRouteWithoutRouteApplicationCheck(forcefully, replacesCurrentRouteInHistory)
+        
+    }
+    
+    
+    _applyRouteWithoutRouteApplicationCheck(
+        forcefully: boolean,
+        replacesCurrentRouteInHistory: boolean
+    ): boolean {
+        
+        if (!this._needsRouteApplication(forcefully)) {
+            return NO
+        }
+        
+        if (replacesCurrentRouteInHistory) {
+            window.location.replace(this.linkRepresentation)
+        }
+        else {
+            window.location.hash = this.stringRepresentation
+        }
+        
+        return YES
+        
+    }
+    
+    
+    _needsRouteApplication(forcefully: boolean): boolean {
+        
+        if (!forcefully && new UIRoute(window.location.hash).stringRepresentation == this.stringRepresentation) {
+            return NO
+        }
+        
+        return YES
+        
+    }
+    
+    
+    _routeApplication(forcefully: boolean, replacesCurrentRouteInHistory: boolean): UIRouteChangeDescriptor {
+        
+        return {
+            currentRoute: UIRoute.currentRoute,
+            targetRoute: this.copy(),
+            forcefully: forcefully,
+            replacesCurrentRouteInHistory: replacesCurrentRouteInHistory
+        }
         
     }
     
@@ -218,7 +340,7 @@ export class UIRoute extends Array<UIRouteComponent> {
     
     navigateBySettingComponent(name: string, parameters: UIRouteParameters, extendParameters: boolean = NO) {
         
-        this.routeWithComponent(name, parameters, extendParameters).apply()
+        return this.routeWithComponent(name, parameters, extendParameters).apply()
         
     }