@api-client/ui 0.5.29 → 0.5.31

package/build/src/core/ActivityManager.d.ts

@@ -54,9 +54,9 @@ export declare enum IntentFlags {
      */
     ByReference = 4
 }
-export interface Intent {
+export interface Intent<T = unknown> {
     action: string;
-    data?: unknown;
+    data?: T;
     category?: string[];
     flags?: number;
     /**
@@ -68,6 +68,22 @@ export declare enum IntentResult {
     RESULT_CANCELED = 0,
     RESULT_OK = 1
 }
+/**
+ * Type for activity constructor with static action property.
+ */
+export interface ActivityConstructor {
+    new (parent: Application): Activity;
+    action?: string;
+}
+/**
+ * Enhanced activity registration options.
+ */
+export interface ActivityRegistrationOptions {
+    /** Whether to override existing registrations */
+    override?: boolean;
+    /** Optional validation function for intents */
+    validateIntent?: (intent: Intent) => boolean;
+}
 /**
  * Manages application activities.
  *
@@ -97,7 +113,13 @@ export declare class ActivityManager {
     private modalActivityStack;
     private generateActivityId;
     constructor(parent: Application);
-    registerActivity(action: string, activityClass: typeof Activity): void;
+    /**
+     * Registers an activity class with enhanced options.
+     * @param action The action name to register the activity for.
+     * @param activityClass The activity class constructor.
+     * @param options Optional registration configuration.
+     */
+    registerActivity(action: string, activityClass: ActivityConstructor, options?: ActivityRegistrationOptions): void;
     /**
      * Creates an activity and pushes it into the stack, but it does not initialize any of the lifecycle methods.
      * It is a way to put an activity at some place of the stack,
@@ -150,13 +172,99 @@ export declare class ActivityManager {
      * @param activity The activity to bring to the foreground.
      */
     private updateCurrentActivity;
+    /**
+     * Safely executes an async lifecycle method with error handling.
+     * @param lifecycleMethod The lifecycle method to execute.
+     * @param activity The activity instance.
+     * @param methodName The name of the method for error reporting.
+     * @returns Promise that resolves when the method completes or rejects with wrapped error.
+     */
+    private safeExecuteLifecycleMethod;
     /**
      * Allows navigating back through the activity stack.
      * Call `ActivityManager.navigateBack()` when the user performs a back action
      * (e.g., clicks a back button).
+     * @returns Promise that resolves to true if navigation was successful, false if at root.
+     */
+    navigateBack(): Promise<boolean>;
+    /**
+     * Navigates to a specific activity in the stack, clearing activities above it.
+     * @param action The action of the activity to navigate to.
+     * @returns Promise that resolves to true if navigation was successful.
+     */
+    navigateToActivity(action: string): Promise<boolean>;
+    /**
+     * Clears the entire activity stack and starts a new root activity.
+     * @param intent The intent for the new root activity.
+     */
+    clearStackAndStart(intent: Intent): Promise<void>;
+    /**
+     * Creates an intent with better type safety and validation.
+     * @param action The action name.
+     * @param data Optional intent data.
+     * @param options Optional intent configuration.
+     * @returns A properly formed intent.
      */
-    navigateBack(): Promise<void>;
+    createIntent<T = unknown>(action: string, data?: T, options?: {
+        category?: string[];
+        flags?: number;
+        requestCode?: number;
+    }): Intent<T>;
     createRequestCode(): number;
     findActiveActivity(action: string): Activity | undefined;
+    /**
+     * Transitions an activity from Created to Resumed state.
+     * @param activity The activity to transition.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    private transitionCreatedToResumed;
+    /**
+     * Transitions an activity from Started to Resumed state.
+     * @param activity The activity to transition.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    private transitionStartedToResumed;
+    /**
+     * Transitions an activity from Initialized to Resumed state.
+     * @param activity The activity to transition.
+     * @param intent The intent used to create the activity.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    private transitionInitializedToResumed;
+    /**
+     * Cleans up resources for destroyed activities to prevent memory leaks.
+     * @param activity The activity to clean up.
+     */
+    private cleanupActivity;
+    /**
+     * Validates that an activity stack is in a consistent state.
+     * @param stack The activity stack to validate.
+     * @returns Array of validation errors, empty if valid.
+     */
+    private validateStackConsistency;
+    /**
+     * Gets diagnostic information about the current state of the activity manager.
+     * Useful for debugging and monitoring.
+     * @returns Object containing current state information.
+     */
+    getDiagnostics(): {
+        totalActivities: number;
+        modalActivities: number;
+        currentActivity?: string;
+        topActivity?: string;
+        stackValidation: string[];
+        modalStackValidation: string[];
+    };
+    /**
+     * Gets all registered activity actions.
+     * @returns Array of registered action names.
+     */
+    getRegisteredActions(): string[];
+    /**
+     * Checks if an action is registered.
+     * @param action The action to check.
+     * @returns true if the action is registered, false otherwise.
+     */
+    isActionRegistered(action: string): boolean;
 }
 //# sourceMappingURL=ActivityManager.d.ts.map

package/build/src/core/ActivityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActivityManager.d.ts","sourceRoot":"","sources":["../../../src/core/ActivityManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,oBAAY,iBAAiB;IAC3B;;;OAGG;IACH,WAAW,IAAA;IACX;;;OAGG;IACH,OAAO,IAAA;IACP;;;OAGG;IACH,OAAO,IAAA;IACP;;;OAGG;IACH,OAAO,IAAA;IACP;;;OAGG;IACH,MAAM,IAAA;IACN;;;OAGG;IACH,OAAO,IAAA;IACP;;;OAGG;IACH,SAAS,IAAA;CACV;AAED,oBAAY,WAAW;IACrB;;OAEG;IACH,KAAK,IAAS;IACd;;OAEG;IACH,SAAS,IAAS;IAClB;;;;;OAKG;IACH,WAAW,IAAS;CACrB;AAED,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,oBAAY,YAAY;IACtB,eAAe,IAAA;IACf,SAAS,IAAA;CACV;AA0BD;;;;;;;;;GASG;AACH,qBAAa,eAAe;;IAC1B,OAAO,CAAC,eAAe,CAAC,CAAU;IAElC;;OAEG;IACH,OAAO,CAAC,eAAe,CAAqC;IAE5D;;;OAGG;IACH,OAAO,CAAC,aAAa,CAA2B;IAEhD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA2B;IAErD,OAAO,CAAC,kBAAkB;gBAMd,MAAM,EAAE,WAAW;IAK/B,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,QAAQ,GAAG,IAAI;IAiBtE;;;;;;;;;OASG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAShC;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmDlD,OAAO,CAAC,aAAa;IAgBrB;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhF,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAIxC;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;YAiCzC,oBAAoB;YAoBpB,wBAAwB;IAYtC,cAAc,IAAI,QAAQ,GAAG,SAAS;IAStC,kBAAkB,IAAI,QAAQ,GAAG,SAAS;IAI1C;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,QAAQ,GAAG,IAAI;IAwB9D;;;;;;OAMG;YACW,qBAAqB;IAsEnC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnC,iBAAiB,IAAI,MAAM;IAM3B,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;CAGzD"}
+{"version":3,"file":"ActivityManager.d.ts","sourceRoot":"","sources":["../../../src/core/ActivityManager.ts"],"names":[],"mappings":"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"}

package/build/src/core/ActivityManager.js

@@ -94,10 +94,22 @@ export class ActivityManager {
         this.#parent = parent;
         // this.reflectEvent = this.reflectEvent.bind(this)
     }
-    registerActivity(action, activityClass) {
-        if (this.activityClasses.has(action)) {
+    /**
+     * Registers an activity class with enhanced options.
+     * @param action The action name to register the activity for.
+     * @param activityClass The activity class constructor.
+     * @param options Optional registration configuration.
+     */
+    registerActivity(action, activityClass, options = {}) {
+        const { override = false } = options;
+        if (this.activityClasses.has(action) && !override) {
             // eslint-disable-next-line no-console
             console.warn(`Activity with action "${action}" already registered.`, new Error().stack);
+            return;
+        }
+        // Validate that the class extends Activity
+        if (typeof activityClass !== 'function') {
+            throw new Error(`Invalid activity class for action "${action}": must be a constructor function`);
         }
         this.activityClasses.set(action, activityClass);
     }
@@ -245,6 +257,8 @@ export class ActivityManager {
             stackEntry.activity.lifecycle = ActivityLifecycle.Stopped;
             await stackEntry.activity.onDestroy();
             stackEntry.activity.lifecycle = ActivityLifecycle.Destroyed;
+            // Clean up resources to prevent memory leaks
+            this.cleanupActivity(stackEntry.activity);
             await this.manageActivityResult(stackEntry.activity, stackEntry.intent);
             // Resume the previous activity
             await this.bringLastActivityToFront();
@@ -284,11 +298,11 @@ export class ActivityManager {
     async bringLastActivityToFront() {
         if (this.modalActivityStack.length > 0) {
             const previousEntry = this.modalActivityStack[this.activityStack.length - 1];
-            await this.updateCurrentActivity(previousEntry.activity, false);
+            await this.updateCurrentActivity(previousEntry.activity, false, previousEntry.intent);
         }
         else if (this.activityStack.length > 0) {
             const previousEntry = this.activityStack[this.activityStack.length - 1];
-            await this.updateCurrentActivity(previousEntry.activity, false);
+            await this.updateCurrentActivity(previousEntry.activity, false, previousEntry.intent);
         }
         else {
             this.currentActivity = undefined; // No more activities
@@ -343,7 +357,7 @@ export class ActivityManager {
      *
      * @param activity The activity to bring to the foreground.
      */
-    async updateCurrentActivity(activity, isModal) {
+    async updateCurrentActivity(activity, isModal, intent) {
         this.setupStyles(activity, this.currentActivity);
         if (this.currentActivity &&
             this.currentActivity !== activity &&
@@ -353,61 +367,33 @@ export class ActivityManager {
             await this.currentActivity.onPause();
             this.currentActivity.lifecycle = ActivityLifecycle.Paused;
         }
-        if (activity.lifecycle === ActivityLifecycle.Paused) {
-            await activity.onResume();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Resumed;
-            activity.requestUpdate();
-        }
-        else if (activity.lifecycle === ActivityLifecycle.Stopped) {
-            await activity.onRestart();
-            activity.lifecycle = ActivityLifecycle.Resumed;
-        }
-        else if (activity.lifecycle === ActivityLifecycle.Destroyed) {
-            throw new Error(`Invalid state. The activity is already destroyed.`);
-        }
-        else if (activity.lifecycle === ActivityLifecycle.Created) {
-            await activity.onStart();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Started;
-            await activity.onResume();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Resumed;
-            activity.requestUpdate();
-        }
-        else if (activity.lifecycle === ActivityLifecycle.Started) {
-            await activity.onResume();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Resumed;
-            activity.requestUpdate();
-        }
-        else if (activity.lifecycle === ActivityLifecycle.Initialized) {
-            // TODO: Figure out intent passing here.
-            await activity.onCreate();
-            activity.lifecycle = ActivityLifecycle.Created;
-            if (this.isDestroyed(activity)) {
-                // the activity finished and the manager already took care of this situation.
-                return;
-            }
-            await activity.onStart();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Started;
-            await activity.onResume();
-            if (this.isDestroyed(activity)) {
-                return;
-            }
-            activity.lifecycle = ActivityLifecycle.Resumed;
-            activity.requestUpdate();
+        switch (activity.lifecycle) {
+            case ActivityLifecycle.Paused:
+                if (!(await this.transitionStartedToResumed(activity))) {
+                    return;
+                }
+                break;
+            case ActivityLifecycle.Stopped:
+                await this.safeExecuteLifecycleMethod(() => activity.onRestart(), activity, 'onRestart');
+                activity.lifecycle = ActivityLifecycle.Resumed;
+                break;
+            case ActivityLifecycle.Destroyed:
+                throw new Error(`Invalid state. The activity is already destroyed.`);
+            case ActivityLifecycle.Created:
+                if (!(await this.transitionCreatedToResumed(activity))) {
+                    return;
+                }
+                break;
+            case ActivityLifecycle.Started:
+                if (!(await this.transitionStartedToResumed(activity))) {
+                    return;
+                }
+                break;
+            case ActivityLifecycle.Initialized:
+                if (!(await this.transitionInitializedToResumed(activity, intent))) {
+                    return;
+                }
+                break;
         }
         if (!isModal) {
             // With a modal activity, it renders directly to the `<body>` and renders outside
@@ -415,17 +401,104 @@ export class ActivityManager {
             this.currentActivity = activity;
         }
     }
+    /**
+     * Safely executes an async lifecycle method with error handling.
+     * @param lifecycleMethod The lifecycle method to execute.
+     * @param activity The activity instance.
+     * @param methodName The name of the method for error reporting.
+     * @returns Promise that resolves when the method completes or rejects with wrapped error.
+     */
+    async safeExecuteLifecycleMethod(lifecycleMethod, activity, methodName) {
+        try {
+            await lifecycleMethod();
+        }
+        catch (error) {
+            const activityName = activity.constructor.name;
+            const wrappedError = new Error(`Error in ${activityName}.${methodName}(): ${error instanceof Error ? error.message : String(error)}`);
+            wrappedError.cause = error;
+            // Allow the activity to handle its own errors, but still propagate
+            this.#parent.dispatchEvent(new CustomEvent('activity-lifecycle-error', {
+                detail: { activity, methodName, error: wrappedError },
+            }));
+            throw wrappedError;
+        }
+    }
     /**
      * Allows navigating back through the activity stack.
      * Call `ActivityManager.navigateBack()` when the user performs a back action
      * (e.g., clicks a back button).
+     * @returns Promise that resolves to true if navigation was successful, false if at root.
      */
     async navigateBack() {
+        // Handle modal activities first
+        if (this.modalActivityStack.length > 0) {
+            const topModal = this.modalActivityStack[this.modalActivityStack.length - 1];
+            await this.finishActivity(topModal.activity);
+            return true;
+        }
+        // Handle regular activities
         if (this.activityStack.length > 1 && this.currentActivity) {
-            // Finish current, which will resume previous
             await this.finishActivity(this.currentActivity);
+            return true;
         }
-        // Else do nothing (or display a message, or exit the app)
+        // At root, cannot navigate back
+        return false;
+    }
+    /**
+     * Navigates to a specific activity in the stack, clearing activities above it.
+     * @param action The action of the activity to navigate to.
+     * @returns Promise that resolves to true if navigation was successful.
+     */
+    async navigateToActivity(action) {
+        const index = this.activityStack.findIndex((entry) => entry.action === action);
+        if (index === -1) {
+            return false;
+        }
+        // Finish all activities above the target
+        const activitiesToFinish = this.activityStack.slice(index + 1);
+        for (const entry of activitiesToFinish) {
+            await this.finishActivity(entry.activity);
+        }
+        // Bring the target activity to the front
+        const targetEntry = this.activityStack[index];
+        await this.updateCurrentActivity(targetEntry.activity, false, targetEntry.intent);
+        return true;
+    }
+    /**
+     * Clears the entire activity stack and starts a new root activity.
+     * @param intent The intent for the new root activity.
+     */
+    async clearStackAndStart(intent) {
+        // Finish all activities
+        const allActivities = [...this.activityStack, ...this.modalActivityStack];
+        for (const entry of allActivities) {
+            if (entry.activity.lifecycle !== ActivityLifecycle.Destroyed) {
+                await this.finishActivity(entry.activity);
+            }
+        }
+        // Clear stacks
+        this.activityStack.length = 0;
+        this.modalActivityStack.length = 0;
+        this.currentActivity = undefined;
+        // Start new root activity
+        await this.startActivity(intent);
+    }
+    /**
+     * Creates an intent with better type safety and validation.
+     * @param action The action name.
+     * @param data Optional intent data.
+     * @param options Optional intent configuration.
+     * @returns A properly formed intent.
+     */
+    createIntent(action, data, options = {}) {
+        if (!this.isActionRegistered(action)) {
+            throw new Error(`Cannot create intent for unregistered action: ${action}`);
+        }
+        return {
+            action,
+            data,
+            ...options,
+        };
     }
     createRequestCode() {
         const min = 1000;
@@ -435,5 +508,121 @@ export class ActivityManager {
     findActiveActivity(action) {
         return this.activityStack.find((entry) => entry.action === action)?.activity;
     }
+    /**
+     * Transitions an activity from Created to Resumed state.
+     * @param activity The activity to transition.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    async transitionCreatedToResumed(activity) {
+        await this.safeExecuteLifecycleMethod(() => activity.onStart(), activity, 'onStart');
+        if (this.isDestroyed(activity)) {
+            return false;
+        }
+        activity.lifecycle = ActivityLifecycle.Started;
+        await this.safeExecuteLifecycleMethod(() => activity.onResume(), activity, 'onResume');
+        if (this.isDestroyed(activity)) {
+            return false;
+        }
+        activity.lifecycle = ActivityLifecycle.Resumed;
+        activity.requestUpdate();
+        return true;
+    }
+    /**
+     * Transitions an activity from Started to Resumed state.
+     * @param activity The activity to transition.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    async transitionStartedToResumed(activity) {
+        await this.safeExecuteLifecycleMethod(() => activity.onResume(), activity, 'onResume');
+        if (this.isDestroyed(activity)) {
+            return false;
+        }
+        activity.lifecycle = ActivityLifecycle.Resumed;
+        activity.requestUpdate();
+        return true;
+    }
+    /**
+     * Transitions an activity from Initialized to Resumed state.
+     * @param activity The activity to transition.
+     * @param intent The intent used to create the activity.
+     * @returns true if successful, false if activity was destroyed during transition.
+     */
+    async transitionInitializedToResumed(activity, intent) {
+        await this.safeExecuteLifecycleMethod(() => activity.onCreate(intent), activity, 'onCreate');
+        activity.lifecycle = ActivityLifecycle.Created;
+        if (this.isDestroyed(activity)) {
+            return false;
+        }
+        return await this.transitionCreatedToResumed(activity);
+    }
+    /**
+     * Cleans up resources for destroyed activities to prevent memory leaks.
+     * @param activity The activity to clean up.
+     */
+    cleanupActivity(activity) {
+        // Remove any event listeners that might create memory leaks
+        // This changes the entire prototype chain of the activity,
+        // effectively making it a new object. We can't do that as the activity will loose some
+        // of its properties, so we don't do it for now.
+        // if (activity instanceof EventTarget) {
+        //   // Clear all event listeners by replacing the activity with a new EventTarget
+        //   // This is a defensive approach since we can't enumerate listeners
+        //   Object.setPrototypeOf(activity, EventTarget.prototype)
+        // }
+        // Clear any references that might prevent garbage collection
+        activity.renderRoot = undefined;
+    }
+    /**
+     * Validates that an activity stack is in a consistent state.
+     * @param stack The activity stack to validate.
+     * @returns Array of validation errors, empty if valid.
+     */
+    validateStackConsistency(stack) {
+        const errors = [];
+        const seenIds = new Set();
+        for (const entry of stack) {
+            if (seenIds.has(entry.id)) {
+                errors.push(`Duplicate activity ID found: ${entry.id}`);
+            }
+            seenIds.add(entry.id);
+            if (!entry.activity || !entry.id || !entry.action) {
+                errors.push(`Invalid stack entry: missing required properties`);
+            }
+            if (entry.activity.lifecycle === ActivityLifecycle.Destroyed) {
+                errors.push(`Destroyed activity found in stack: ${entry.id}`);
+            }
+        }
+        return errors;
+    }
+    /**
+     * Gets diagnostic information about the current state of the activity manager.
+     * Useful for debugging and monitoring.
+     * @returns Object containing current state information.
+     */
+    getDiagnostics() {
+        return {
+            totalActivities: this.activityStack.length,
+            modalActivities: this.modalActivityStack.length,
+            currentActivity: this.currentActivity?.constructor.name,
+            topActivity: this.getTopActivity()?.constructor.name,
+            stackValidation: this.validateStackConsistency(this.activityStack),
+            modalStackValidation: this.validateStackConsistency(this.modalActivityStack),
+        };
+    }
+    /**
+     * Gets all registered activity actions.
+     * @returns Array of registered action names.
+     */
+    getRegisteredActions() {
+        return Array.from(this.activityClasses.keys());
+    }
+    /**
+     * Checks if an action is registered.
+     * @param action The action to check.
+     * @returns true if the action is registered, false otherwise.
+     */
+    isActionRegistered(action) {
+        return this.activityClasses.has(action);
+    }
 }
 //# sourceMappingURL=ActivityManager.js.map