feat(wizards): support async showWhen(), SkipPrompter backward/forward aws#6166

## Problem
Wizard framework does not support:
- async `showWhen()` provider.
- restoring previous state of WizardPrompter in nested wizard when
  user clicks BACK button.
- skipping prompter in backward direction.

## Solution
- introduce `NestedWizard` class that uses child wizards as prompters with
  support for instantiating and restoring child wizards in backward direction.
- update wizard state controller to support `ControlSingal.Skip` and add concept
  of wizard direction.
- support async `showWhen()` provider.

fix aws#6094

Author: vicheey

packages/core/src/dev/activation.ts

@@ -411,7 +411,7 @@ async function openStorageFromInput() {
                         title: 'Enter a key',
                     })
                 } else if (target === 'globalsView') {
-                    return new SkipPrompter('')
+                    return new SkipPrompter()
                 } else if (target === 'globals') {
                     // List all globalState keys in the quickpick menu.
                     const items = globalState
@@ -483,7 +483,7 @@ async function resetState() {
 
             this.form.key.bindPrompter(({ target }) => {
                 if (target && resettableFeatures.some((f) => f.name === target)) {
-                    return new SkipPrompter('')
+                    return new SkipPrompter()
                 }
                 throw new Error('invalid feature target')
             })

packages/core/src/shared/ui/common/skipPrompter.ts

@@ -3,24 +3,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { StepEstimator } from '../../wizards/wizard'
+import { StepEstimator, WIZARD_SKIP } from '../../wizards/wizard'
 import { Prompter, PromptResult } from '../prompter'
 
-/** Pseudo-prompter that immediately returns a value (and thus "skips" a step). */
+/** Prompter that returns SKIP control signal to parent wizard */
 export class SkipPrompter<T> extends Prompter<T> {
-    /**
-     * @param val Value immediately returned by the prompter.
-     */
-    constructor(public readonly val: T) {
+    constructor() {
         super()
     }
 
     protected async promptUser(): Promise<PromptResult<T>> {
-        const promptPromise = new Promise<PromptResult<T>>((resolve) => {
-            resolve(this.val)
-        })
-
-        return await promptPromise
+        return WIZARD_SKIP
     }
 
     public get recentItem(): any {

packages/core/src/shared/ui/nestedWizardPrompter.ts

@@ -0,0 +1,63 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Wizard, WizardOptions } from '../wizards/wizard'
+import { Prompter } from './prompter'
+import { WizardPrompter } from './wizardPrompter'
+import { createHash } from 'crypto'
+
+/**
+ * An abstract class that extends the base Wizard class plus the ability to
+ * use other wizard classes as prompters
+ */
+export abstract class NestedWizard<T> extends Wizard<T> {
+    /**
+     * Map to store memoized wizard instances using SHA-256 hashed keys
+     */
+    private wizardInstances: Map<string, any> = new Map()
+
+    public constructor(options?: WizardOptions<T>) {
+        super(options)
+    }
+
+    /**
+     * Creates a prompter for a wizard instance with memoization.
+     *
+     * @template TWizard - The type of wizard, must extend Wizard<TState>
+     * @template TState - The type of state managed by the wizard
+     *
+     * @param wizardClass - The wizard class constructor
+     * @param args - Constructor arguments for the wizard instance
+     *
+     * @returns A wizard prompter to be used as prompter
+     *
+     * @example
+     * // Create a prompter for SyncWizard
+     * const prompter = this.createWizardPrompter<SyncWizard, SyncParams>(
+     *     SyncWizard,
+     *     template.uri,
+     *     syncUrl
+     * )
+     *
+     * @remarks
+     * - Instances are memoized using a SHA-256 hash of the wizard class name and arguments
+     * - The same wizard instance is reused for identical constructor parameters for restoring wizard prompter
+     *   states during back button click event
+     */
+    protected createWizardPrompter<TWizard extends Wizard<TState>, TState>(
+        wizardClass: new (...args: any[]) => TWizard,
+        ...args: ConstructorParameters<new (...args: any[]) => TWizard>
+    ): Prompter<TState> {
+        const memoizeKey = createHash('sha256')
+            .update(wizardClass.name + JSON.stringify(args))
+            .digest('hex')
+
+        if (!this.wizardInstances.get(memoizeKey)) {
+            this.wizardInstances.set(memoizeKey, new wizardClass(...args))
+        }
+
+        return new WizardPrompter(this.wizardInstances.get(memoizeKey)) as Prompter<TState>
+    }
+}

packages/core/src/shared/ui/wizardPrompter.ts

@@ -3,19 +3,26 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { StepEstimator, Wizard } from '../wizards/wizard'
+import _ from 'lodash'
+import { StepEstimator, Wizard, WIZARD_BACK, WIZARD_SKIP } from '../wizards/wizard'
 import { Prompter, PromptResult } from './prompter'
 
 /**
- * Wraps {@link Wizard} object into its own {@link Prompter}, allowing wizards to use other
- * wizards in their flows.
+ * Wraps {@link Wizard} object into its own {@link Prompter}, allowing wizards to use other wizards in their flows.
+ * This is meant to be used exclusively in createWizardPrompter() method of {@link NestedWizard} class.
+ *
+ * @remarks
+ *  - The WizardPrompter class should never be instantiated with directly.
+ *  - Use createWizardPrompter() method of {@link NestedWizard} when creating a nested wizard prompter for proper state management.
+ *  - See examples:
+ *     - {@link SingleNestedWizard}
+ *     - {@link DoubleNestedWizard}
  */
 export class WizardPrompter<T> extends Prompter<T> {
     public get recentItem(): any {
         return undefined
     }
     public set recentItem(response: any) {}
-
     private stepOffset: number = 0
     private response: T | undefined
 
@@ -51,6 +58,15 @@ export class WizardPrompter<T> extends Prompter<T> {
 
     protected async promptUser(): Promise<PromptResult<T>> {
         this.response = await this.wizard.run()
-        return this.response
+
+        if (this.response === undefined) {
+            return WIZARD_BACK as PromptResult<T>
+        } else if (_.isEmpty(this.response)) {
+            return WIZARD_SKIP as PromptResult<T>
+        }
+
+        return {
+            ...this.response,
+        } as PromptResult<T>
     }
 }

packages/core/src/shared/wizards/stateController.ts

@@ -9,7 +9,16 @@ export enum ControlSignal {
     Retry,
     Exit,
     Back,
-    Continue,
+    Skip,
+}
+
+/**
+ * Value for indicating current direction of the wizard
+ * Created mainly to support skipping prompters
+ */
+export enum Direction {
+    Forward,
+    Backward,
 }
 
 export interface StepResult<TState> {
@@ -39,9 +48,11 @@ export class StateMachineController<TState> {
     private extraSteps = new Map<number, Branch<TState>>()
     private steps: Branch<TState> = []
     private internalStep: number = 0
+    private direction: Direction
 
     public constructor(private state: TState = {} as TState) {
         this.previousStates = [_.cloneDeep(state)]
+        this.direction = Direction.Forward
     }
 
     public addStep(step: StepFunction<TState>): void {
@@ -71,12 +82,14 @@ export class StateMachineController<TState> {
 
         this.state = this.previousStates.pop()!
         this.internalStep -= 1
+        this.direction = Direction.Backward
     }
 
     protected advanceState(nextState: TState): void {
         this.previousStates.push(this.state)
         this.state = nextState
         this.internalStep += 1
+        this.direction = Direction.Forward
     }
 
     protected detectCycle(step: StepFunction<TState>): TState | undefined {
@@ -105,6 +118,12 @@ export class StateMachineController<TState> {
         }
 
         if (isMachineResult(result)) {
+            if (result.controlSignal === ControlSignal.Skip) {
+                /**
+                 * Depending on current wizard direction, skip signal get converted to forward or backward control signal
+                 */
+                result.controlSignal = this.direction === Direction.Forward ? undefined : ControlSignal.Back
+            }
             return result
         } else {
             return { nextState: result }

packages/core/src/shared/wizards/wizard.ts

@@ -46,10 +46,12 @@ export const WIZARD_RETRY = {
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const WIZARD_BACK = { id: WIZARD_CONTROL, type: ControlSignal.Back, toString: () => makeControlString('Back') }
 // eslint-disable-next-line @typescript-eslint/naming-convention
+export const WIZARD_SKIP = { id: WIZARD_CONTROL, type: ControlSignal.Skip, toString: () => makeControlString('Skip') }
+// eslint-disable-next-line @typescript-eslint/naming-convention
 export const WIZARD_EXIT = { id: WIZARD_CONTROL, type: ControlSignal.Exit, toString: () => makeControlString('Exit') }
 
 /** Control signals allow for alterations of the normal wizard flow */
-export type WizardControl = typeof WIZARD_RETRY | typeof WIZARD_BACK | typeof WIZARD_EXIT
+export type WizardControl = typeof WIZARD_RETRY | typeof WIZARD_BACK | typeof WIZARD_EXIT | typeof WIZARD_SKIP
 
 export function isWizardControl(obj: any): obj is WizardControl {
     return obj !== undefined && obj.id === WIZARD_CONTROL
@@ -269,9 +271,7 @@ export class Wizard<TState extends Partial<Record<keyof TState, unknown>>> {
 
         if (isValidResponse(answer)) {
             state.stepCache.picked = prompter.recentItem
-        }
-
-        if (!isValidResponse(answer)) {
+        } else {
             delete state.stepCache.stepOffset
         }
 

packages/core/src/shared/wizards/wizardForm.ts

@@ -25,7 +25,7 @@ interface ContextOptions<TState, TProp> {
      * in a single resolution step then they will be added in the order in which they were
      * bound.
      */
-    showWhen?: (state: WizardState<TState>) => boolean
+    showWhen?: (state: WizardState<TState>) => boolean | Promise<boolean>
     /**
      * Sets a default value to the target property. This default is applied to the current state
      * as long as the property has not been set.
@@ -135,16 +135,30 @@ export class WizardForm<TState extends Partial<Record<keyof TState, unknown>>> {
         this.formData.set(key, { ...this.formData.get(key), ...element })
     }
 
-    public canShowProperty(prop: string, state: TState, defaultState: TState = this.applyDefaults(state)): boolean {
+    public canShowProperty(
+        prop: string,
+        state: TState,
+        defaultState: TState = this.applyDefaults(state)
+    ): boolean | Promise<boolean> {
         const current = _.get(state, prop)
         const options = this.formData.get(prop) ?? {}
 
         if (isAssigned(current) || checkParent(prop, state, options)) {
             return false
         }
 
-        if (options.showWhen !== undefined && !options.showWhen(defaultState as WizardState<TState>)) {
-            return false
+        if (options.showWhen !== undefined) {
+            const showStatus = options.showWhen(defaultState as WizardState<TState>)
+            if (showStatus instanceof Promise) {
+                return showStatus
+                    .then((result) => {
+                        return result
+                    })
+                    .catch(() => {
+                        return false // Default to not showing if there's an error
+                    })
+            }
+            return showStatus
         }
 
         return options.provider !== undefined