@api-client/ui 0.6.5 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.6.5",
+  "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'
@@ -301,17 +301,19 @@ export class Activity extends EventTarget {
 
   /**
    * Starts a new activity for a 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.
+   * @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({ action: 'pickFile' });
+   * const resultIntent = await this.startActivityForResult<{ userId: string }>({ action: 'pickUser' });
    * if (resultIntent.resultCode === IntentResult.RESULT_OK) {
-   *   // handle result
+   *   console.log(resultIntent.data?.userId);
    * }
    * ```
    */
-  async startActivityForResult(intent: Intent): Promise<Intent> {
+  async startActivityForResult<T>(intent: Intent): Promise<ResolvedIntent<T | undefined>> {
     const { manager } = this.getApplication()
     return manager.startActivityForResult(intent)
   }
@@ -355,7 +357,7 @@ export class Activity extends EventTarget {
     if (event.type === EventTypes.Intent.startActivityForResult) {
       const info = event.detail as ActivityWithResultDetail
       const result = await this.startActivityForResult(info.intent)
-      info.onResult(IntentResult.RESULT_OK, result)
+      info.onResult(result.result, result)
     } else if (event.type === EventTypes.Intent.startActivity) {
       await this.startActivity(event.detail.intent)
     } else {

package/src/core/ActivityManager.ts

@@ -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,
@@ -137,7 +161,7 @@ export class ActivityManager {
   /**
    * Stores the resolvers for activities started for result.
    */
-  private resultResolvers = new Map<Intent, (intent: Intent) => void>()
+  private resultResolvers = new Map<Intent, (intent: ResolvedIntent) => void>()
 
   /**
    * Represents the activity stack. It is used to manage
@@ -291,9 +315,19 @@ export class ActivityManager {
   /**
    * Starts an activity that should return a result to the calling activity.
    *
+   * @template T The type of the result data expected.
    * @param intent The intent to start the activity.
-   */
-  async startActivityForResult(intent: Intent): Promise<Intent> {
+   * @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
@@ -310,8 +344,8 @@ export class ActivityManager {
       deepCopy.flags = IntentFlags.ForResult
     }
 
-    return new Promise<Intent>((resolve, reject) => {
-      this.resultResolvers.set(deepCopy, resolve)
+    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)
@@ -374,9 +408,10 @@ export class ActivityManager {
       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: Intent = {
+      const resultIntent: ResolvedIntent = {
         ...originalIntent,
         data: activity.getResult(),
+        result: activity.resultCode,
       }
       resolver(resultIntent)
     }

package/src/core/Fragment.ts

@@ -3,7 +3,7 @@ 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'
@@ -250,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<Intent> {
+  async startActivityForResult<T>(intent: Intent): Promise<ResolvedIntent<T | undefined>> {
     const activity = this.getActivity()
     if (!activity) {
       throw new Error('Fragment is not attached to an activity')
     }
-    return activity.startActivityForResult(intent)
+    return activity.startActivityForResult<T>(intent)
   }
 
   /**
@@ -296,7 +306,7 @@ export class Fragment extends EventTarget {
     if (event.type === EventTypes.Intent.startActivityForResult) {
       const info = event.detail as ActivityWithResultDetail
       const result = await this.startActivityForResult(info.intent)
-      info.onResult(IntentResult.RESULT_OK, result)
+      info.onResult(result.result, result)
     } else if (event.type === EventTypes.Intent.startActivity) {
       await activity.startActivity(event.detail.intent)
     } else {