@api-client/ui 0.6.4 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",

package/src/core/Activity.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { nothing, TemplateResult } from 'lit'
-import { ActivityLifecycle, IntentResult, type Intent } from './ActivityManager.js'
+import { ActivityLifecycle, IntentResult, type Intent, type ResolvedIntent } from './ActivityManager.js'
 import { FragmentManager } from './FragmentManager.js'
 import type { Fragment } from './Fragment.js'
 import type { Application, UpdateRequest } from './Application.js'
@@ -8,6 +8,13 @@ import { bound } from '../decorators/bound.js'
 import type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js'
 import { EventTypes } from '../events/EventTypes.js'
 
+export interface ActivityResult {
+  requestCode: number
+  resultCode: IntentResult
+  data?: unknown
+  intent: Intent
+}
+
 /**
  * ## Activity
  *
@@ -84,9 +91,6 @@ export class Activity extends EventTarget {
     return this.exitCode
   }
 
-  /** Tracks pending request codes for activities started for result. */
-  protected pendingRequestCodes: number[] = []
-
   /**
    * Constructs a new Activity.
    * @param parent The parent application instance.
@@ -97,6 +101,14 @@ export class Activity extends EventTarget {
     this.manager = new FragmentManager(this)
   }
 
+  /**
+   * Returns the current activity instance.
+   * @returns This activity.
+   */
+  getActivity(): Activity {
+    return this
+  }
+
   /**
    * Checks if the activity is in the `Destroyed` state.
    * @returns `true` if destroyed, `false` otherwise.
@@ -282,25 +294,28 @@ export class Activity extends EventTarget {
    * await this.startActivity({ action: 'login' });
    * ```
    */
-  startActivity(intent: Intent): Promise<void> {
-    return this.parent.manager.startActivity(intent)
+  async startActivity(intent: Intent): Promise<Activity> {
+    const { manager } = this.getApplication()
+    return manager.startActivity(intent)
   }
 
   /**
    * Starts a new activity for a result.
+   * @template T The type of the result data expected.
    * @param intent The intent to start.
-   * @returns The request code for the started activity.
+   * @returns A promise that resolves when the started activity finishes, returning the result Intent with
+   * data of type T.
    * @example
    * ```typescript
-   * const code = await this.startActivityForResult({ action: 'pickFile' });
+   * const resultIntent = await this.startActivityForResult<{ userId: string }>({ action: 'pickUser' });
+   * if (resultIntent.resultCode === IntentResult.RESULT_OK) {
+   *   console.log(resultIntent.data?.userId);
+   * }
    * ```
    */
-  async startActivityForResult(intent: Intent): Promise<number> {
+  async startActivityForResult<T>(intent: Intent): Promise<ResolvedIntent<T | undefined>> {
     const { manager } = this.getApplication()
-    const code = manager.createRequestCode()
-    this.pendingRequestCodes.push(code)
-    await manager.startActivityForResult(intent, code)
-    return code
+    return manager.startActivityForResult(intent)
   }
 
   /**
@@ -317,57 +332,6 @@ export class Activity extends EventTarget {
     this.resultData = data
   }
 
-  /**
-   * Called when an activity you launched exits, giving you the request code, result code, and intent.
-   * Override to handle results from started activities.
-   * @param requestCode The request code.
-   * @param resultCode The result code.
-   * @param intent The intent that was used to start the activity.
-   * @example
-   * ```typescript
-   * async onActivityResult(requestCode, resultCode, intent) {
-   *   if (resultCode === IntentResult.RESULT_OK) {
-   *     // handle result
-   *   }
-   * }
-   * ```
-   */
-  async onActivityResult(requestCode: number, resultCode: IntentResult, intent: Intent): Promise<void> {
-    const index = this.pendingRequestCodes.indexOf(requestCode)
-    if (index !== -1) {
-      this.pendingRequestCodes.splice(index, 1)
-    }
-    // First we check whether any of the fragments has the code.
-    const fragment = this.manager.findByRequestCode(requestCode)
-    if (fragment) {
-      return fragment.onActivityResult(requestCode, resultCode, intent)
-    }
-    if (this.constructor === Activity) {
-      // eslint-disable-next-line no-console
-      console.info(
-        `Activity#onActivityResult not implemented. Request code: ${requestCode}, result code: ${resultCode}`,
-        intent
-      )
-    }
-  }
-
-  /**
-   * Returns the current activity instance.
-   * @returns This activity.
-   */
-  getActivity(): Activity {
-    return this
-  }
-
-  /**
-   * Checks if this activity initiated the activity for result with the given code.
-   * @param code The request code.
-   * @returns `true` if the code is pending, `false` otherwise.
-   */
-  hasRequestCode(code: number): boolean {
-    return this.pendingRequestCodes.includes(code)
-  }
-
   /**
    * Gets the result data set by `setResult`.
    * @returns The result data or `undefined`.
@@ -392,7 +356,8 @@ export class Activity extends EventTarget {
   async handleIntentEvent(event: CustomEvent<ActivityDetail | ActivityWithResultDetail>): Promise<void> {
     if (event.type === EventTypes.Intent.startActivityForResult) {
       const info = event.detail as ActivityWithResultDetail
-      await this.startActivityForResult(info.intent)
+      const result = await this.startActivityForResult(info.intent)
+      info.onResult(result.result, result)
     } else if (event.type === EventTypes.Intent.startActivity) {
       await this.startActivity(event.detail.intent)
     } else {

package/src/core/ActivityManager.ts

@@ -1,6 +1,6 @@
 import type { Activity } from './Activity.js'
 import type { Application } from './Application.js'
-import { navigateScreen } from './ApplicationRoute.js'
+// import { navigateScreen } from './ApplicationRoute.js'
 
 export enum ActivityLifecycle {
   /**
@@ -59,9 +59,22 @@ export enum IntentFlags {
 }
 
 export interface Intent<T = unknown> {
+  /**
+   * The action name the activity is registered for.
+   */
   action: string
+  /**
+   * The data passed to the activity.
+   */
   data?: T
+  /**
+   * The category of the activity.
+   * Optional and currently not used.
+   */
   category?: string[]
+  /**
+   * The flags that control the behavior of the activity.
+   */
   flags?: number
   /**
    * The request code used to distinguish between different activities.
@@ -69,6 +82,17 @@ export interface Intent<T = unknown> {
   requestCode?: number
 }
 
+/**
+ * An intent returned by an activity after the activity result is ready.
+ * This object is only created when the activity is started with the `ForResult` flag.
+ */
+export interface ResolvedIntent<T = unknown> extends Intent<T> {
+  /**
+   * The result code returned by the activity.
+   */
+  result: IntentResult
+}
+
 export enum IntentResult {
   RESULT_CANCELED,
   RESULT_OK,
@@ -134,6 +158,11 @@ export class ActivityManager {
    */
   private activityClasses = new Map<string, typeof Activity>()
 
+  /**
+   * Stores the resolvers for activities started for result.
+   */
+  private resultResolvers = new Map<Intent, (intent: ResolvedIntent) => void>()
+
   /**
    * Represents the activity stack. It is used to manage
    * the UI state after calling the back action.
@@ -184,15 +213,6 @@ export class ActivityManager {
     this.activityClasses.set(action, activityClass as typeof Activity)
   }
 
-  // protected reflectEvent<T extends Event>(event: T): T {
-  //   const copy = Reflect.construct(event.constructor, [event.type, event])
-  //   const dispatched = this.#parent.events.dispatchEvent(copy)
-  //   if (!dispatched) {
-  //     event.preventDefault()
-  //   }
-  //   return copy
-  // }
-
   /**
    * 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,
@@ -210,21 +230,21 @@ export class ActivityManager {
     this.activityStack.push(stackEntry)
   }
 
-  setupRoute(intent: Intent): void {
-    if (intent.data) {
-      const typed = intent.data as { uri?: string }
-      if (typed.uri) {
-        navigateScreen(typed.uri)
-      }
-    }
-  }
+  // setupRoute(intent: Intent): void {
+  //   if (intent.data) {
+  //     const typed = intent.data as { uri?: string }
+  //     if (typed.uri) {
+  //       navigateScreen(typed.uri)
+  //     }
+  //   }
+  // }
 
   /**
    * Starts a new activity and brings it to the foreground.
    *
    * @param intent The intent that created this activity.
    */
-  async startActivity(intent: Intent): Promise<void> {
+  async startActivity(intent: Intent): Promise<Activity> {
     const { currentActivity, activityStack } = this
     const lastIndex = activityStack.findLastIndex((entry) => entry.action === intent.action)
     // if the activity is in the history list, we bring it up and update intent.
@@ -239,9 +259,9 @@ export class ActivityManager {
       })
       await info.activity.onNewIntent(intent)
       // TODO: Check if the activity is destroyed.
-      this.setupRoute(intent)
+      // this.setupRoute(intent)
       await this.updateCurrentActivity(info.activity, false)
-      return
+      return info.activity
     }
     const activity = this.buildActivity(intent)
     if (currentActivity) {
@@ -263,16 +283,17 @@ export class ActivityManager {
     await activity.onCreate(intent)
     if (this.isDestroyed(activity)) {
       // the activity finished and the manager already took care of this situation.
-      return
+      return activity
     }
     activity.lifecycle = ActivityLifecycle.Created
 
     await this.updateCurrentActivity(activity, !!isModal)
     if (this.isDestroyed(activity)) {
       // the activity finished and the manager already took care of this situation.
-      return
+      return activity
     }
-    this.setupRoute(intent)
+    // this.setupRoute(intent)
+    return activity
   }
 
   private buildActivity(intent: Intent): Activity {
@@ -293,12 +314,20 @@ export class ActivityManager {
 
   /**
    * Starts an activity that should return a result to the calling activity.
-   * The result should be a unique number across the application.
+   *
+   * @template T The type of the result data expected.
    * @param intent The intent to start the activity.
-   * @param requestCode The request code used to match the activity result.
-   */
-  async startActivityForResult(intent: Intent, requestCode: number): Promise<void> {
-    intent.requestCode = requestCode
+   * @returns A promise that resolves when the started activity finishes, returning the result Intent with
+   * data of type T.
+   * @example
+   * ```typescript
+   * const resultIntent = await mgr.startActivityForResult<{ userId: string }>({ action: 'pickUser' });
+   * if (resultIntent.resultCode === IntentResult.RESULT_OK) {
+   *   console.log(resultIntent.data?.userId);
+   * }
+   * ```
+   */
+  async startActivityForResult<T>(intent: Intent): Promise<ResolvedIntent<T | undefined>> {
     const byReference = (intent.flags ?? 0) & IntentFlags.ByReference
     const shallowCopy = { ...intent }
     const data = shallowCopy.data
@@ -314,7 +343,14 @@ export class ActivityManager {
     } else {
       deepCopy.flags = IntentFlags.ForResult
     }
-    await this.startActivity(deepCopy)
+
+    return new Promise<ResolvedIntent<T>>((resolve, reject) => {
+      this.resultResolvers.set(deepCopy, resolve as (intent: ResolvedIntent<unknown>) => void)
+      this.startActivity(deepCopy).catch((e) => {
+        this.resultResolvers.delete(deepCopy)
+        reject(e)
+      })
+    })
   }
 
   isDestroyed(activity: Activity): boolean {
@@ -342,7 +378,7 @@ export class ActivityManager {
       // Clean up resources to prevent memory leaks
       this.cleanupActivity(stackEntry.activity)
 
-      await this.manageActivityResult(stackEntry.activity, stackEntry.intent)
+      this.resolveActivityResult(stackEntry.activity, stackEntry.intent)
 
       // Resume the previous activity
       await this.bringLastActivityToFront()
@@ -353,6 +389,9 @@ export class ActivityManager {
       }
       await activity.onDestroy()
       activity.lifecycle = ActivityLifecycle.Destroyed
+
+      this.resolveActivityResult(activity, { action: '' })
+
       // This can happen when an activity finishes in one of the callback methods,
       // before it is added to the stack. In that case, we bring the last activity back to the front.
       await this.bringLastActivityToFront()
@@ -360,25 +399,21 @@ export class ActivityManager {
     this.#parent.requestUpdate()
   }
 
-  private async manageActivityResult(activity: Activity, intent: Intent): Promise<void> {
-    const { flags = 0, requestCode = -1 } = intent
-    if (flags & IntentFlags.ForResult) {
-      const all = [...this.activityStack, ...this.modalActivityStack]
-      const target = all.find((entry) => entry.activity.hasRequestCode(requestCode))
-      if (target) {
-        if (target.activity.lifecycle === ActivityLifecycle.Destroyed) {
-          return
-        }
-        if (target.activity.lifecycle === ActivityLifecycle.Resumed) {
-          await target.activity.onPause()
-          target.activity.lifecycle = ActivityLifecycle.Paused
-        }
-        // Let's create a shallow copy of the intent. We can disregard the ByReference flag here,
-        // as we override the data with the result data.
-        const intentCopy = { ...intent }
-        intentCopy.data = activity.getResult()
-        await target.activity.onActivityResult(requestCode, activity.resultCode, intentCopy)
+  private resolveActivityResult(activity: Activity, originalIntent: Intent): void {
+    const resolver = this.resultResolvers.get(originalIntent)
+    // The activity might have not been started with startActivityForResult.
+    // A thing to consider for the future is whether we should throw an error in a case where
+    // the activity was started for result but the resolver was not found.
+    if (resolver) {
+      this.resultResolvers.delete(originalIntent)
+      // We construct the result intent.
+      // Ideally we would like to preserve the original intent structure but with new data.
+      const resultIntent: ResolvedIntent = {
+        ...originalIntent,
+        data: activity.getResult(),
+        result: activity.resultCode,
       }
+      resolver(resultIntent)
     }
   }
 

package/src/core/Fragment.ts

@@ -3,16 +3,12 @@ import { Activity } from './Activity.js'
 import { FragmentState, type FragmentOptions, FragmentManager } from './FragmentManager.js'
 import type { Application, UpdateRequest } from './Application.js'
 import { FragmentRenderer } from './renderer/FragmentRenderer.js'
-import { Intent, IntentResult } from './ActivityManager.js'
+import { Intent, ResolvedIntent } from './ActivityManager.js'
 import { bound } from '../decorators/bound.js'
 import type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentEvents.js'
 import { EventTypes } from '../events/EventTypes.js'
 import { type RefOrCallback } from 'lit/directives/ref.js'
 
-export interface PendingActivityResult {
-  onResult(result: IntentResult, intent: Intent): void
-}
-
 /**
  * Similar to Activity, with lifecycle methods (onCreate, onAttach, onDetach, etc.).
  * The crucial difference is that a Fragment is always hosted by an `Activity` or
@@ -31,20 +27,6 @@ export class Fragment extends EventTarget {
   protected children = new Map<string, Fragment>()
   protected fragmentManager: FragmentManager
 
-  /**
-   * The request code used to start an activity for a result.
-   */
-  requestCode = -1
-
-  /**
-   * A list of pending activity results that were requested by the components
-   * hosted in this fragment.
-   * The key is the request code and the value contains the callback
-   * that will be called when the activity result is received.
-   * The callback is called with the result code and the resulting intent.
-   */
-  pendingActivityResult: Map<number, PendingActivityResult> = new Map<number, PendingActivityResult>()
-
   #renderer: FragmentRenderer
 
   get renderer(): FragmentRenderer {
@@ -230,7 +212,7 @@ export class Fragment extends EventTarget {
    *
    * @example
    * // In your parent fragment's render method:
-   * html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`
+   * // html`<div ${ref(this.createFragmentRef('my-child-fragment'))}></div>`
    */
   createFragmentRef(key: string): RefOrCallback<Element> {
     return (element?: Element) => {
@@ -268,14 +250,24 @@ export class Fragment extends EventTarget {
 
   /**
    * Starts an activity for result.
+   * @template T The type of the result data expected.
    * @param intent The intent to start.
+   * @returns A promise that resolves when the started activity finishes, returning the result Intent with
+   * data of type T.
+   * @example
+   * ```typescript
+   * const resultIntent = await this.startActivityForResult<{ userId: string }>({ action: 'pickUser' });
+   * if (resultIntent.resultCode === IntentResult.RESULT_OK) {
+   *   console.log(resultIntent.data?.userId);
+   * }
+   * ```
    */
-  async startActivityForResult(intent: Intent): Promise<void> {
+  async startActivityForResult<T>(intent: Intent): Promise<ResolvedIntent<T | undefined>> {
     const activity = this.getActivity()
     if (!activity) {
-      throw new Error(`The fragment has no activity. Unable to start an intent.`)
+      throw new Error('Fragment is not attached to an activity')
     }
-    this.requestCode = await activity.startActivityForResult(intent)
+    return activity.startActivityForResult<T>(intent)
   }
 
   /**
@@ -290,44 +282,6 @@ export class Fragment extends EventTarget {
     await activity.startActivity(intent)
   }
 
-  /**
-   * The callback method that is triggered when another activity that was
-   * started for result finishes.
-   *
-   * @param requestCode The request code that was used to start the activity.
-   * @param data The data that was passed back.
-   * @param intent The intent that was used to start the activity.
-   */
-  async onActivityResult(requestCode: number, resultCode: IntentResult, intent: Intent): Promise<void> {
-    const { pendingActivityResult, children } = this
-    if (pendingActivityResult.has(requestCode)) {
-      const { onResult } = pendingActivityResult.get(requestCode) as PendingActivityResult
-      pendingActivityResult.delete(requestCode)
-      onResult(resultCode, intent)
-      return
-    }
-    for (const fragment of children.values()) {
-      if (fragment.hasRequestCode(requestCode)) {
-        fragment.onActivityResult(requestCode, resultCode, intent)
-        return
-      }
-    }
-    this.requestCode = -1
-    if (this.constructor === Fragment) {
-      // eslint-disable-next-line no-console
-      console.info('Fragment#onActivityResult() not implemented', requestCode, resultCode, intent)
-    }
-  }
-
-  hasRequestCode(requestCode: number): boolean {
-    for (const fragment of this.children.values()) {
-      if (fragment.hasRequestCode(requestCode)) {
-        return true
-      }
-    }
-    return this.requestCode === requestCode
-  }
-
   /**
    * A handler for the intent event dispatched by web components hosted by this fragment.
    *
@@ -351,11 +305,8 @@ export class Fragment extends EventTarget {
     }
     if (event.type === EventTypes.Intent.startActivityForResult) {
       const info = event.detail as ActivityWithResultDetail
-      const code = await activity.startActivityForResult(info.intent)
-      this.requestCode = code
-      this.pendingActivityResult.set(code, {
-        onResult: info.onResult,
-      })
+      const result = await this.startActivityForResult(info.intent)
+      info.onResult(result.result, result)
     } else if (event.type === EventTypes.Intent.startActivity) {
       await activity.startActivity(event.detail.intent)
     } else {

package/src/core/FragmentManager.ts

@@ -210,18 +210,4 @@ export class FragmentManager {
       }
     }
   }
-
-  /**
-   * Finds a fragment by activity request code.
-   * @param requestCode The request code to find the fragment by.
-   * @returns The corresponding fragment or `null`.
-   */
-  findByRequestCode(requestCode: number): Fragment | null {
-    for (const [, fragment] of this.fragments) {
-      if (fragment.hasRequestCode(requestCode)) {
-        return fragment
-      }
-    }
-    return null
-  }
 }