@api-client/ui 0.5.29 → 0.5.31

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/elements/currency/internals/Picker.ts

@@ -764,7 +764,6 @@ export default class CurrencyPicker extends LitElement {
         <ui-select
           label="${this.label}"
           @change="${this.handleCurrencySelect}"
-          menuPositioning="popover"
           ?disabled="${this.disabled}"
           ?required="${this.required}"
           .supportingText="${this.supportingText || ''}"

package/src/md/menu/internal/Menu.ts

@@ -118,12 +118,19 @@ export default class Menu extends UiList {
     // Let CSS anchor positioning handle the positioning automatically
     // Only intervene if we need to set max-height for overflow cases
     const box = this.getBoundingClientRect()
-    const menuBottom = box.top + box.height
-    const menuRight = box.left + box.width
 
     // Reset any previous manual positioning to let CSS anchor positioning work
     this.style.removeProperty('position-area')
     this.style.removeProperty('max-height')
+    this.style.removeProperty('max-width')
+
+    // Check if the menu content is being clipped
+    const isVerticallyClipped = this.scrollHeight > this.clientHeight
+    const isHorizontallyClipped = this.scrollWidth > this.clientWidth
+
+    // Get the actual bottom and right edges of the menu
+    const menuBottom = box.top + box.height
+    const menuRight = box.left + box.width
 
     // Detect if menu is positioned above or below the anchor
     // by checking if the menu is in the upper or lower half of the viewport
@@ -139,16 +146,24 @@ export default class Menu extends UiList {
       this.classList.remove('menu-positioned-above')
     }
 
-    // Only set max-height if the menu would overflow
-    if (menuBottom > innerHeight) {
-      const availableHeight = innerHeight - box.top
+    // Only set max-height if the menu would overflow the viewport OR is already clipped
+    if (menuBottom > innerHeight || isVerticallyClipped) {
+      let availableHeight: number
+
+      if (isMenuInUpperHalf) {
+        // Menu is positioned below the anchor - available space is from top to bottom of viewport
+        availableHeight = innerHeight - box.top
+      } else {
+        // Menu is positioned above the anchor - available space is from top of viewport to bottom of menu
+        availableHeight = box.top + box.height
+      }
+
       this.style.maxHeight = `${Math.max(200, availableHeight - 20)}px`
     }
 
-    if (menuRight > innerWidth) {
+    // Only set max-width if the menu would overflow the viewport OR is already clipped
+    if (menuRight > innerWidth || isHorizontallyClipped) {
       const availableWidth = innerWidth - box.left
-      // Let CSS anchor positioning handle horizontal flipping
-      // We could set max-width if needed
       if (availableWidth < 200) {
         this.style.maxWidth = `${Math.max(180, availableWidth - 20)}px`
       }

package/src/md/select/internals/Select.styles.ts

@@ -12,11 +12,6 @@ export default css`
   }
 
   .input {
-    anchor-name: --input;
     cursor: default;
   }
-
-  .menu {
-    position-anchor: --input;
-  }
 `

package/src/md/select/internals/Select.ts

@@ -1,9 +1,11 @@
 import { html, LitElement, PropertyValues, TemplateResult } from 'lit'
 import { property, query, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
+import { styleMap } from 'lit/directives/style-map.js'
 import { setDisabled } from '../../../lib/disabled.js'
 import type UiOption from './Option.js'
 import type { UiMenuElement } from '../../menu/ui-menu.js'
+import { nanoid } from 'nanoid'
 
 import '../../text-field/ui-outlined-text-field.js'
 import '../../menu/ui-menu.js'
@@ -274,6 +276,9 @@ export default class UiSelect extends LitElement {
     if (!this.disabled) {
       this.setAttribute('tabindex', '0')
     }
+    if (!this.id) {
+      this.id = `select-${nanoid(6)}`
+    }
   }
 
   /**
@@ -355,11 +360,17 @@ export default class UiSelect extends LitElement {
 
   protected async setCurrentOption(): Promise<void> {
     await this.updateComplete
+    const options = this.querySelectorAll<UiOption>('ui-option')
     if (this.value) {
-      const options = this.querySelectorAll<UiOption>('ui-option')
       this.selectedOption = Array.from(options).find((option) => option.value === this.value) || null
     } else {
-      this.selectedOption = null
+      const selected = Array.from(options).find((option) => option.selected)
+      if (selected) {
+        this.selectedOption = selected
+        this.#value = selected.value
+      } else {
+        this.selectedOption = null
+      }
     }
   }
 
@@ -500,19 +511,10 @@ export default class UiSelect extends LitElement {
     this.focus()
   }
 
-  override render(): TemplateResult {
-    const classes = classMap({
-      'ui-select': true,
-      'open': this.open,
-      'disabled': this.disabled,
-    })
-    return html`${this.renderFocusRing()}
-      <div class="${classes}" aria-activedescendant=${this.ariaActiveDescendant || ''}>
-        ${this.renderInput()} ${this.renderMenu()}
-      </div> `
-  }
-
   protected renderInput(): TemplateResult {
+    const styles = {
+      'anchor-name': `--${this.id}`,
+    }
     return html`<ui-outlined-text-field
       .name=${this.name}
       .label=${this.label}
@@ -521,32 +523,60 @@ export default class UiSelect extends LitElement {
       .required=${this.required}
       readonly
       tabindex="-1"
-      inert
+      .inert=${true}
       aria-hidden="true"
       .invalid=${this.invalid}
       .invalidText=${this.invalidText || ''}
       .supportingText=${this.supportingText || ''}
       class="input"
+      style=${styleMap(styles)}
+      part="input"
     >
-      <ui-icon slot="suffix">arrow_drop_down</ui-icon>
+      <ui-icon part="icon" slot="suffix">arrow_drop_down</ui-icon>
     </ui-outlined-text-field>`
   }
 
   protected renderMenu(): TemplateResult {
+    const styles = {
+      'position-anchor': `--${this.id}`,
+    }
     return html`<ui-menu
       id="menu"
       class="menu"
+      part="menu"
+      style=${styleMap(styles)}
       popover="auto"
       selector="ui-option"
       @select="${this.handleSelect}"
       @close="${this.handleMenuClose}"
       @highlightchange="${this.handleHighlightChange}"
     >
-      <slot></slot>
+      <slot @slotchange="${this.handleSlotChange}"></slot>
     </ui-menu>`
   }
 
+  protected async handleSlotChange(): Promise<void> {
+    // When options change, re-evaluate the current selection
+    // only if we don't have an explicit value set
+    if (!this.value) {
+      await this.setCurrentOption()
+      this.requestUpdate()
+    }
+  }
+
   protected renderFocusRing(): TemplateResult {
     return html`<md-focus-ring part="focus-ring" class="focus-ring" .control="${this as HTMLElement}"></md-focus-ring>`
   }
+
+  override render(): TemplateResult {
+    const classes = classMap({
+      'ui-select': true,
+      'open': this.open,
+      'disabled': this.disabled,
+    })
+    return html`${this.renderFocusRing()}
+      <div class="${classes}" aria-activedescendant=${this.ariaActiveDescendant || ''}>
+        ${this.renderInput()} ${this.renderMenu()}
+      </div> `
+  }
 }

package/test/core/activity_manager.spec.ts

@@ -354,10 +354,10 @@ describe('ActivityManager', () => {
 
       assert.isTrue(activity1.onActivityResult.calledOnce)
       const [calledRequestCode, calledResultCode, calledIntent] = activity1.onActivityResult.firstCall.args
-      assert.equal(calledRequestCode, requestCode)
-      assert.equal(calledResultCode, IntentResult.RESULT_OK)
-      assert.deepEqual(calledIntent.data, resultData)
-      assert.equal(calledIntent.action, TestActivity2.action)
+      assert.equal(calledRequestCode, requestCode, 'has the request code from activity1')
+      assert.equal(calledResultCode, IntentResult.RESULT_OK, 'has the OK result code')
+      assert.deepEqual(calledIntent.data, resultData, 'has the result data from activity2')
+      assert.equal(calledIntent.action, TestActivity2.action, 'has the action of activity2')
     })
 
     it('handles finishing an activity that was only created (not fully started)', async () => {