@api-client/ui 0.5.30 → 0.5.32

package/src/core/ActivityManager.ts

@@ -58,9 +58,9 @@ export enum IntentFlags {
   ByReference = 1 << 2,
 }
 
-export interface Intent {
+export interface Intent<T = unknown> {
   action: string
-  data?: unknown
+  data?: T
   category?: string[]
   flags?: number
   /**
@@ -98,6 +98,24 @@ interface ActivityStackEntry {
   action: string
 }
 
+/**
+ * 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.
  *
@@ -139,12 +157,31 @@ export class ActivityManager {
     // this.reflectEvent = this.reflectEvent.bind(this)
   }
 
-  registerActivity(action: string, activityClass: typeof Activity): void {
-    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: string,
+    activityClass: ActivityConstructor,
+    options: ActivityRegistrationOptions = {}
+  ): void {
+    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
     }
-    this.activityClasses.set(action, activityClass)
+
+    // 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 as typeof Activity)
   }
 
   // protected reflectEvent<T extends Event>(event: T): T {
@@ -302,6 +339,9 @@ export class ActivityManager {
       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
@@ -343,10 +383,10 @@ export class ActivityManager {
   private async bringLastActivityToFront(): Promise<void> {
     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
     }
@@ -404,7 +444,7 @@ export class ActivityManager {
    *
    * @param activity The activity to bring to the foreground.
    */
-  private async updateCurrentActivity(activity: Activity, isModal: boolean): Promise<void> {
+  private async updateCurrentActivity(activity: Activity, isModal: boolean, intent?: Intent): Promise<void> {
     this.setupStyles(activity, this.currentActivity)
     if (
       this.currentActivity &&
@@ -416,56 +456,38 @@ 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
@@ -474,17 +496,130 @@ export class ActivityManager {
     }
   }
 
+  /**
+   * 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 async safeExecuteLifecycleMethod(
+    lifecycleMethod: () => void | Promise<void>,
+    activity: Activity,
+    methodName: string
+  ): Promise<void> {
+    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(): Promise<void> {
+  async navigateBack(): Promise<boolean> {
+    // 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
+    }
+
+    // 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: string): Promise<boolean> {
+    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: Intent): Promise<void> {
+    // 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<T = unknown>(
+    action: string,
+    data?: T,
+    options: {
+      category?: string[]
+      flags?: number
+      requestCode?: number
+    } = {}
+  ): Intent<T> {
+    if (!this.isActionRegistered(action)) {
+      throw new Error(`Cannot create intent for unregistered action: ${action}`)
+    }
+
+    return {
+      action,
+      data,
+      ...options,
     }
-    // Else do nothing (or display a message, or exit the app)
   }
 
   createRequestCode(): number {
@@ -496,4 +631,142 @@ export class ActivityManager {
   findActiveActivity(action: string): Activity | undefined {
     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.
+   */
+  private async transitionCreatedToResumed(activity: Activity): Promise<boolean> {
+    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.
+   */
+  private async transitionStartedToResumed(activity: Activity): Promise<boolean> {
+    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.
+   */
+  private async transitionInitializedToResumed(activity: Activity, intent?: Intent): Promise<boolean> {
+    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.
+   */
+  private cleanupActivity(activity: Activity): void {
+    // 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.
+   */
+  private validateStackConsistency(stack: ActivityStackEntry[]): string[] {
+    const errors: string[] = []
+    const seenIds = new Set<string>()
+
+    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(): {
+    totalActivities: number
+    modalActivities: number
+    currentActivity?: string
+    topActivity?: string
+    stackValidation: string[]
+    modalStackValidation: string[]
+  } {
+    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(): string[] {
+    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: string): boolean {
+    return this.activityClasses.has(action)
+  }
 }

package/src/core/renderer/ApplicationRenderer.ts

@@ -1,7 +1,7 @@
-import { nothing, render, type RootPart, type TemplateResult } from 'lit'
+import { nothing, type TemplateResult } from 'lit'
 import type { Application } from '../Application.js'
 import type { Activity } from '../Activity.js'
-import { Renderer, renderFn } from './Renderer.js'
+import { Renderer } from './Renderer.js'
 import { ModalActivity } from '../ModalActivity.js'
 
 export class ApplicationRenderer extends Renderer {
@@ -12,46 +12,42 @@ export class ApplicationRenderer extends Renderer {
     this.renderedFirst = new WeakMap()
   }
 
-  [renderFn](): void {
-    const { app, renderRoot } = this
-    let host: Application | Activity
-    let root: HTMLElement | null = renderRoot
-    let content: TemplateResult | typeof nothing
-    const activity = app.manager.getTopActivity()
-    if (activity) {
-      host = activity
-      if (activity.renderRoot) {
-        root = activity.renderRoot
-      }
-      if (activity instanceof ModalActivity) {
-        content = activity.renderDialog()
-      } else {
-        content = activity.render()
+  private _handleFirstRender(target: Application | Activity, clearRoot: boolean, root: HTMLElement): void {
+    if (!this.renderedFirst.has(target)) {
+      this.renderedFirst.set(target, true)
+      if (clearRoot) {
+        this._clearRoot(root)
       }
+      queueMicrotask(() => target.onFirstRender())
+    }
+  }
+
+  protected renderer(): void {
+    const { app, renderRoot: defaultRenderRoot } = this
+    const activity = app.manager.getTopActivity()
+
+    const host: Application | Activity = activity || app
+    const root: HTMLElement | null = activity?.renderRoot || defaultRenderRoot
+
+    let content: TemplateResult | typeof nothing
+    if (activity instanceof ModalActivity) {
+      content = activity.renderDialog()
     } else {
-      host = app
-      content = app.render()
+      content = host.render()
     }
     if (!root) {
       // eslint-disable-next-line no-console
       console.warn(`The "renderRoot" is not set up.`)
       return
     }
-    if (!this.renderedFirst.has(app)) {
-      this.renderedFirst.set(app, true)
-      Array.from(root.childNodes).forEach((node) => root.parentNode?.removeChild(node))
-      setTimeout(() => app.onFirstRender())
-    }
-    // host might !== app
-    if (!this.renderedFirst.has(host)) {
-      setTimeout(() => host.onFirstRender())
+    this._handleFirstRender(app, true, root)
+    if (!this.firstRendered) {
+      this.firstRenderedFlag = true
     }
-    const litPart = root as HTMLElement & { _$litPart$?: RootPart }
-    if (litPart._$litPart$ && litPart._$litPart$.options) {
-      litPart._$litPart$.options.host = host
+    if (host !== app) {
+      this._handleFirstRender(host, false, root)
     }
-    render(content, root, { host })
-    this.resolveUpdatePromise()
+    this._render(content, root, host)
     this.app.onRendered()
   }
 }

package/src/core/renderer/FragmentRenderer.ts

@@ -1,33 +1,24 @@
-import { render, RenderOptions, RootPart } from 'lit'
 import type { Fragment } from '../Fragment.js'
-import { Renderer, renderFn } from './Renderer.js'
+import { Renderer } from './Renderer.js'
 
 export class FragmentRenderer extends Renderer {
   constructor(protected fragment: Fragment) {
     super()
   }
 
-  [renderFn](): void {
+  protected renderer(): void {
     const root = this.renderRoot
     if (!root) {
       // return quietly. Fragments can be rendered directly.
       return
     }
-    const fragment = this.fragment
-    const host = fragment.getSingleVisibleFragment() || fragment
+    const host = this.fragment.getSingleVisibleFragment() ?? this.fragment
     if (!this.firstRendered) {
       this.firstRenderedFlag = true
       // cleanup any pre-existing content.
-      Array.from(root.childNodes).forEach((node) => root.parentNode?.removeChild(node))
-      setTimeout(() => host.onFirstRender())
+      this._clearRoot(root)
+      queueMicrotask(() => host.onFirstRender())
     }
-    const litPart = root as unknown as HTMLElement & { _$litPart$?: RootPart }
-    if (litPart._$litPart$) {
-      ;(litPart._$litPart$.options as RenderOptions).host = host
-    }
-    // console.log(host, root)
-    render(host.render(), root, { host })
-    this.resolveUpdatePromise()
-    // this.app.onRendered()
+    this._render(host.render(), root, host)
   }
 }