@api-client/ui 0.1.8 → 0.1.9

package/src/core/Activity.ts

@@ -9,54 +9,88 @@ import type { ActivityDetail, ActivityWithResultDetail } from '../events/IntentE
 import { EventTypes } from '../events/EventTypes.js'
 
 /**
- * `Activity` is a crucial component of your app. An application sends an intent
- * to bring the activity. If it's found, the activity gets to the foreground and start its activity.
+ * ## Activity
  *
- * **Lifecycle**
+ * `Activity` is a core building block of your application, representing a single,
+ * focused operation that a user can perform.
+ * Activities manage their own lifecycle, UI, and fragments, and communicate with the application
+ * and other activities via intents.
  *
- * - `onCreated()` - fires when the system first creates the activity.
- * - `onStart()` - the activity becomes visible to the user as the app prepares for
- *  the activity to enter the foreground and become interactive.
- * - `onResume()` - the state in which the app interacts with the user.
- * - `onPause()` - the first indication that the user is leaving your activity.
- * - `onStop()` - your activity is no longer visible to the user.
- * - `onDestroy()`- is called before the activity is destroyed
+ * Activities are managed by the application and can be started, paused, resumed, stopped,
+ * and destroyed according to the app's navigation and user actions.
+ * They can also start other activities for results, manage fragments, and handle intent
+ * events dispatched by hosted web components.
+ *
+ * ### Lifecycle Methods
+ * - `onCreate(intent?)` - Called when the activity is first created.
+ * - `onStart()` - Called when the activity becomes visible to the user.
+ * - `onResume()` - Called when the activity gains focus and becomes interactive.
+ * - `onPause()` - Called when the activity loses focus but is still visible.
+ * - `onStop()` - Called when the activity is no longer visible.
+ * - `onDestroy()` - Called before the activity is destroyed.
+ * - `onRestart()` - Called after the activity has been stopped, just prior to it being started again.
+ *
+ * ### Example
+ * ```typescript
+ * class MyActivity extends Activity {
+ *   async onCreate(intent?: Intent) {
+ *     super.onCreate(intent);
+ *     // Initialization logic here
+ *   }
+ *
+ *   render() {
+ *     return html`<h1>Hello from MyActivity!</h1>`;
+ *   }
+ * }
+ * ```
  */
 export class Activity extends EventTarget {
   /**
-   * To be set by an activity to replace the default render root.
-   * This is particularly useful when the activity is a modal dialog
-   * and the content should be rendered outside the application's render root.
+   * The root element where the activity's content should be rendered.
+   * Set this if you want to render outside the application's default render root (e.g., for modals).
    */
   renderRoot?: HTMLElement
+
   /**
-   * An activity can define its action name that does not change.
-   * It then should be used as the activity registration key.
-   * This way other activities/fragments can use it to call the activity.
+   * An optional static action name for the activity.
+   * Use this as the registration key for referencing the activity in intents.
+   *
+   * @example
+   * ```typescript
+   * class LoginActivity extends Activity {
+   *   static action = 'login';
+   * }
+   * ```
    */
   static action?: string
 
+  /** The current lifecycle state of the activity. */
   public lifecycle: ActivityLifecycle = ActivityLifecycle.Initialized
+
+  /** The parent application instance. */
   protected parent: Application
-  /**
-   * The fragment manager that manages fragments in this activity.
-   */
+
+  /** The fragment manager for managing fragments within this activity. */
   protected manager: FragmentManager
+
+  /** Data to be returned as a result to the calling activity. */
   protected resultData?: unknown
 
+  /** The exit code for the activity result. */
   protected exitCode = IntentResult.RESULT_CANCELED
 
+  /** Gets the current result code for the activity. */
   get resultCode(): IntentResult {
     return this.exitCode
   }
 
-  /**
-   * When starting an new activity for result, we add the request code here
-   * so that the manager can track which activity originally called the
-   * activity for result.
-   */
+  /** Tracks pending request codes for activities started for result. */
   protected pendingRequestCodes: number[] = []
 
+  /**
+   * Constructs a new Activity.
+   * @param parent The parent application instance.
+   */
   constructor(parent: Application) {
     super()
     this.parent = parent
@@ -64,82 +98,76 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Called when the activity is starting. This is where most initialization should go.
-   * You can call `finish()` from within this function, in which case `onDestroy()` will be
-   * immediately called after `onCreate()` without any of the rest of the activity lifecycle
-   * (`onStart()`, `onResume()`, `onPause()`, etc) executing.
-   *
-   * In the `onCreate()` method, perform basic activity startup logic that happens only once
-   * for the entire life of the activity.
+   * Checks if the activity is in the `Destroyed` state.
+   * @returns `true` if destroyed, `false` otherwise.
+   */
+  isDestroyed(): boolean {
+    return this.lifecycle === ActivityLifecycle.Destroyed
+  }
+
+  /**
+   * Checks if the activity is in the `Resumed` state.
+   * @returns `true` if resumed, `false` otherwise.
+   */
+  isResumed(): boolean {
+    return this.lifecycle === ActivityLifecycle.Resumed
+  }
+
+  /**
+   * Called when the activity is starting. Override to perform initialization logic.
    * @param intent Optional intent data.
+   * @example
+   * ```typescript
+   * async onCreate(intent?: Intent) {
+   *   await fetchData();
+   * }
+   * ```
    */
   onCreate(intent?: Intent): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:create', { detail: intent }))
   }
 
   /**
-   * Called when the activity becomes visible.
-   * As `onCreate()` exits, the activity enters the `Started` state, and the activity becomes visible
-   * to the user. This callback contains what amounts to the activity’s final preparations for coming
-   * to the foreground and becoming interactive.
-   *
-   * Called after `onCreate()`.  It will usually be followed by onResume().
-   * This is a good place to begin running animations, etc.
-   * You can call `finish()` from within this function, in which case `onStop()` will be
-   * immediately called after `onStart()` without the lifecycle transitions
-   * in-between (`onResume()`, `onPause()`, etc) executing.
+   * Called when the activity becomes visible to the user.
+   * Override to start animations or prepare UI.
    */
   onStart(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:start', { detail: null }))
   }
 
   /**
-   * Called when the activity gains focus.
-   * Called after the `onPause()`. This is usually a hint for your activity to start interacting
-   * with the user, which is a good indicator that the activity became active and ready to receive input.
-   * This sometimes could also be a transit state toward another resting state.
-   * For instance, an activity may be relaunched to `onPause()` due to configuration changes and
-   * the activity was visible, but wasn't the top-most activity of an activity task.
-   * The `render()` function is always called after this callback.
+   * Called when the activity gains focus and becomes interactive.
+   * Override to start input handling or resume tasks.
    */
   onResume(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:resume', { detail: null }))
   }
 
   /**
-   * Called when the activity loses focus.
-   * Called as part of the activity lifecycle when the user no longer actively interacts with the activity,
-   * but it is still visible on screen. The counterpart to `onResume()`.
-   *
-   * When activity B is launched in front of activity A, this callback will be invoked on A.
-   * B will not be created until A's `onPause()` returns, so be sure to not do anything lengthy here.
-   *
-   * This callback is mostly used for saving any persistent state the activity is editing,
-   * to present a "edit in place" model to the user and making sure nothing is lost if there are
-   * not enough resources to start the new activity without first killing this one.
-   * This is also a good place to stop things that consume a noticeable amount of CPU in order
-   * to make the switch to the next activity as fast as possible.
+   * Called when the activity loses focus but is still visible.
+   * Override to pause ongoing tasks or save state.
    */
   onPause(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:pause', { detail: null }))
   }
 
   /**
-   * Called when you are no longer visible to the user.
-   * You will next receive either onRestart(), onDestroy(), or nothing, depending on later user activity.
-   * This is a good place to stop refreshing UI, running animations and other visual things.
+   * Called when the activity is no longer visible to the user.
+   * Override to stop UI updates or animations.
    */
   onStop(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:stop', { detail: null }))
   }
 
+  /**
+   * Called after the activity has been stopped, just prior to it being started again.
+   */
   onRestart(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:restart', { detail: null }))
   }
 
   /**
-   * Perform any final cleanup before an activity is destroyed.
-   * This can happen because the activity is finishing (someone called finish() on it).
+   * Called before the activity is destroyed. Override to clean up resources.
    */
   onDestroy(): void | Promise<void> {
     this.dispatchEvent(new CustomEvent('activity:destroy', { detail: null }))
@@ -147,45 +175,54 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Called when a new intent is delivered
+   * Called when a new intent is delivered to the activity.
+   * Override to handle new intents.
    * @param intent New intent data.
    */
   onNewIntent(intent: Intent): void | Promise<void> {
-    //
+    // Override in subclass if needed
   }
 
   /**
    * Called by the renderer when the activity is rendered for the first time.
+   * Override to perform actions after first render.
    */
   onFirstRender(): void {
-    //
+    // Override in subclass if needed
   }
 
   /**
-   * A function called when it should render the view.
+   * Renders the activity's view. Override to provide UI.
+   * @returns A Lit TemplateResult or `nothing` if nothing should be rendered.
+   * @example
+   * ```typescript
+   * render() {
+   *   return html`<div>Hello, world!</div>`;
+   * }
+   * ```
    */
   render(): TemplateResult | typeof nothing {
     return nothing
   }
 
   /**
-   * Finishes the activity.
+   * Finishes the activity and notifies the application.
+   * @example
+   * ```typescript
+   * await this.finish();
+   * ```
    */
   async finish(): Promise<void> {
     await this.getApplication().manager.finishActivity(this)
   }
 
   /**
-   * When the activity changes its state it should call the
-   * `requestUpdate()` method to inform the parent application to
-   * perform the render operation.
-   * The function dispatches the `activity:update` custom event
-   * that is handled by the parent application.
-   *
-   * Note, the application may choose to not call the render procedure
-   * (for example, when the activity is not visible). The rendering
-   * function is asynchronous. The only way to know the activity is being rendered,
-   * is when the `render()` method if called.
+   * Requests the parent application to update the UI.
+   * @param opts Update options.
+   * @example
+   * ```typescript
+   * this.requestUpdate();
+   * ```
    */
   requestUpdate(opts: UpdateRequest = {}): void {
     const { activity = true } = opts
@@ -196,18 +233,32 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Registers a new fragment.
-   * @param key The name of the fragment
-   * @param fragment The fragment to register.
+   * Registers a new fragment with this activity.
+   * @param key The fragment's key.
+   * @param fragment The fragment instance.
+   * @param data Optional data to pass to the fragment.
+   * @example
+   * ```typescript
+   * await this.addFragment('profile', new ProfileFragment());
+   * ```
    */
   async addFragment(key: string, fragment: Fragment, data?: unknown): Promise<void> {
     await this.manager.attachFragment(key, fragment, this, data)
   }
 
+  /**
+   * Shows a registered fragment.
+   * @param key The fragment's key.
+   * @param root Optional root element to render into.
+   */
   async showFragment(key: string, root?: HTMLElement): Promise<void> {
     await this.manager.showFragment(key, root)
   }
 
+  /**
+   * Hides a registered fragment.
+   * @param key The fragment's key.
+   */
   async hideFragment(key: string): Promise<void> {
     const fragment = this.manager.findFragment(key)
     if (fragment) {
@@ -216,16 +267,20 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Unifies Fragment and Activity interfaces.
-   * @returns `this`
+   * Returns the parent application instance.
+   * @returns The application.
    */
   getApplication(): Application {
     return this.parent
   }
 
   /**
-   * A shortcut to the `manager` function.
-   * @param intent The intent to start
+   * Starts a new activity.
+   * @param intent The intent to start.
+   * @example
+   * ```typescript
+   * await this.startActivity({ action: 'login' });
+   * ```
    */
   startActivity(intent: Intent): Promise<void> {
     return this.parent.manager.startActivity(intent)
@@ -233,8 +288,12 @@ export class Activity extends EventTarget {
 
   /**
    * Starts a new activity for a result.
-   * @param intent The intent that created this activity.
-   * @returns The request code created with this call.
+   * @param intent The intent to start.
+   * @returns The request code for the started activity.
+   * @example
+   * ```typescript
+   * const code = await this.startActivityForResult({ action: 'pickFile' });
+   * ```
    */
   async startActivityForResult(intent: Intent): Promise<number> {
     const { manager } = this.getApplication()
@@ -245,8 +304,13 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Call this method to return data to the activity that started this activity.
-   * @param data The data to return.
+   * Sets the result to be returned to the calling activity.
+   * @param resultCode The result code.
+   * @param data Optional result data.
+   * @example
+   * ```typescript
+   * this.setResult(IntentResult.RESULT_OK, { userId: 123 });
+   * ```
    */
   setResult(resultCode: IntentResult, data?: unknown): void {
     this.exitCode = resultCode
@@ -254,17 +318,19 @@ export class Activity extends EventTarget {
   }
 
   /**
-   * Called when an activity you launched exits, giving you the `requestCode` you started it with,
-   * the `resultCode` it returned, and any additional data from it. The `resultCode` will be `RESULT_CANCELED`
-   * if the activity explicitly returned that, didn't return any result, or crashed during its operation.
-   *
-   * An activity can never receive a result in the resumed state. You can count on `onResume()` being called
-   * after this method, though not necessarily immediately after. If the activity was resumed,
-   * it will be paused and the result will be delivered, followed by `onResume()`.
-   *
-   * @param requestCode The request code passed to startActivityForResult.
-   * @param data The result from the activity.
+   * 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)
@@ -285,37 +351,42 @@ export class Activity extends EventTarget {
     }
   }
 
+  /**
+   * Returns the current activity instance.
+   * @returns This activity.
+   */
   getActivity(): Activity {
     return this
   }
 
   /**
-   * Checks whether this activity initiated the activity for result.
-   * @param code The request code to look for.
-   * @returns `true` if the activity has the request code.
+   * 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`.
+   */
   getResult(): unknown | undefined {
     return this.resultData
   }
 
   /**
-   * A handler for the intent event dispatched by web components hosted by this activity.
-   *
-   * **Usage example:**
+   * Handles intent events dispatched by web components hosted by this activity.
    *
-   * ```ts
+   * Usage example:
+   * ```html
    * <custom-element @startactivity="${this.handleIntentEvent}"></custom-element>
    * <custom-element @startactivityforresult="${this.handleIntentEvent}"></custom-element>
    * ```
    *
-   * @param event The event that was dispatched.
-   * @returns A promise that resolves when the intent is handled.
-   * @throws An error if the activity has no activity.
-   * @throws An error if the event type is not recognized.
+   * @param event The intent event.
+   * @throws Error if the event type is not recognized.
    */
   @bound
   async handleIntentEvent(event: CustomEvent<ActivityDetail | ActivityWithResultDetail>): Promise<void> {