Implement the ultimate quick pick experience

utils/hostapi.d.ts

@@ -18,7 +18,7 @@ export interface AzureHostExtensionApi {
     /**
      * The VSCode TreeView for the shared app resource view
      */
-    readonly appResourceTreeView: vscode.TreeView<AzExtTreeItem>;
+    readonly appResourceTreeView: vscode.TreeView<unknown>;
 
     /**
      * The `AzExtTreeDataProvider` for the shared workspace resource view
@@ -28,12 +28,12 @@ export interface AzureHostExtensionApi {
     /**
      * The VSCode TreeView for the shared workspace resource view
      */
-    readonly workspaceResourceTreeView: vscode.TreeView<AzExtTreeItem>;
+    readonly workspaceResourceTreeView: vscode.TreeView<unknown>;
 
     /**
      * Version of the API
      */
-    readonly apiVersion: string;
+    readonly apiVersion: '0.0.1';
 
     /**
      * Reveals an item in the shared app resource tree
@@ -76,7 +76,7 @@ export interface AzureHostExtensionApi {
     /**
      * @deprecated Use `appResourceTreeView` instead
      */
-    readonly treeView: vscode.TreeView<AzExtTreeItem>;
+    readonly treeView: vscode.TreeView<unknown>;
 
     /**
      * @deprecated Use `registerWorkspaceResourceProvider` instead

utils/hostapi.v2.d.ts

@@ -6,7 +6,7 @@
 import * as vscode from 'vscode';
 import type { Environment } from '@azure/ms-rest-azure-env';
 import type { Activity } from './hostapi';
-import type { AzExtResourceType } from './index';
+import type { AzExtResourceType, QuickPickWizardContext } from './index';
 import type { AzureExtensionApi } from './api';
 
 /**
@@ -325,3 +325,12 @@ export interface v2AzureResourcesApi extends AzureExtensionApi {
     */
     registerWorkspaceResourceBranchDataProvider<TModel extends WorkspaceResourceModel>(type: WorkspaceResourceType, provider: WorkspaceResourceBranchDataProvider<TModel>): vscode.Disposable;
 }
+
+export declare interface PickSubscriptionWizardContext extends QuickPickWizardContext {
+    subscription?: AzureSubscription;
+}
+
+export declare interface AzureResourceQuickPickWizardContext extends QuickPickWizardContext, PickSubscriptionWizardContext {
+    resource?: AzureResource;
+    resourceGroup?: string;
+}

utils/index.d.ts

@@ -6,10 +6,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import type { Environment } from '@azure/ms-rest-azure-env';
-import { CancellationToken, CancellationTokenSource, Disposable, Event, ExtensionContext, FileChangeEvent, FileChangeType, FileStat, FileSystemProvider, FileType, InputBoxOptions, MarkdownString, MessageItem, MessageOptions, OpenDialogOptions, OutputChannel, Progress, QuickPickItem, QuickPickOptions, TextDocumentShowOptions, ThemeIcon, TreeDataProvider, TreeItem, TreeItemCollapsibleState, TreeView, Uri } from 'vscode';
+import { CancellationToken, CancellationTokenSource, Disposable, Event, ExtensionContext, FileChangeEvent, FileChangeType, FileStat, FileSystemProvider, FileType, InputBoxOptions, MarkdownString, MessageItem, MessageOptions, OpenDialogOptions, OutputChannel, Progress, QuickPickItem, QuickPickOptions as VSCodeQuickPickOptions, TextDocumentShowOptions, ThemeIcon, TreeDataProvider, TreeItem, TreeItemCollapsibleState, TreeView, Uri } from 'vscode';
 import { TargetPopulation } from 'vscode-tas-client';
 import { AzureExtensionApi, AzureExtensionApiProvider } from './api';
-import type { Activity, ActivityTreeItemOptions, AppResource, OnErrorActivityData, OnProgressActivityData, OnStartActivityData, OnSuccessActivityData } from './hostapi'; // This must remain `import type` or else a circular reference will result
+import type { Activity, ActivityTreeItemOptions, AppResource, AzureHostExtensionApi, OnErrorActivityData, OnProgressActivityData, OnStartActivityData, OnSuccessActivityData } from './hostapi'; // This must remain `import type` or else a circular reference will result
 
 export declare interface RunWithTemporaryDescriptionOptions {
     description: string;
@@ -640,7 +640,9 @@ export declare class UserCancelledError extends Error {
     constructor(stepName?: string);
 }
 
-export declare class NoResourceFoundError extends Error { }
+export declare class NoResourceFoundError extends Error {
+    constructor(context?: ITreeItemPickerContext);
+}
 
 export type CommandCallback = (context: IActionContext, ...args: any[]) => any;
 
@@ -995,7 +997,7 @@ export interface IAzureQuickPickItem<T = undefined> extends QuickPickItem {
 /**
  * Provides additional options for QuickPicks used in Azure Extensions
  */
-export interface IAzureQuickPickOptions extends QuickPickOptions, AzExtUserInputOptions {
+export interface IAzureQuickPickOptions extends VSCodeQuickPickOptions, AzExtUserInputOptions {
     /**
      * An optional id to identify this QuickPick across sessions, used in persisting previous selections
      * If not specified, a hash of the placeHolder will be used
@@ -1714,6 +1716,9 @@ export declare interface Wrapper {
     unwrap<T>(): T;
 }
 
+// temporary
+type ResourceGroupsItem = unknown;
+
 /**
  * Tests to see if something is a wrapper, by ensuring it is an object
  * and has an "unwrap" function
@@ -1722,6 +1727,47 @@ export declare interface Wrapper {
  */
 export declare function isWrapper(maybeWrapper: unknown): maybeWrapper is Wrapper;
 
+export declare function appResourceExperience<TPick extends unknown>(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>, resourceTypes?: AzExtResourceType | AzExtResourceType[], childItemFilter?: ContextValueFilter): Promise<TPick>;
+export declare function contextValueExperience<TPick extends unknown>(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>, contextValueFilter: ContextValueFilter): Promise<TPick>;
+
+interface CompatibilityPickResourceExperienceOptions {
+    resourceTypes?: AzExtResourceType | AzExtResourceType[];
+    childItemFilter?: ContextValueFilter
+}
+
+export declare namespace PickTreeItemWithCompatibility {
+    /**
+     * Provides compatibility for the legacy `pickAppResource` Resource Groups API
+     */
+    export function resource<TPick extends AzExtTreeItem>(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>, options: CompatibilityPickResourceExperienceOptions): Promise<TPick>;
+    /**
+     * Returns `ISubscriptionContext` instead of `ApplicationSubscription` for compatibility.
+     */
+    export function subscription(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>): Promise<ISubscriptionContext>;
+}
+
+export declare interface QuickPickWizardContext extends IActionContext {
+    pickedNodes: unknown[];
+}
+
+/**
+ * Describes filtering based on context value. Items that pass the filter will
+ * match at least one of the `include` filters, but none of the `exclude` filters.
+ */
+export declare interface ContextValueFilter {
+    /**
+     * This filter will include items that match *any* of the values in the array.
+     * When a string is used, exact value comparison is done.
+     */
+    include: string | RegExp | (string | RegExp)[];
+
+    /**
+     * This filter will exclude items that match *any* of the values in the array.
+     * When a string is used, exact value comparison is done.
+     */
+    exclude?: string | RegExp | (string | RegExp)[];
+}
+
 /**
  * Get extension exports for the extension with the given id. Activates extension first if needed.
  *

utils/package.json

@@ -47,7 +47,7 @@
         "@microsoft/vscode-azext-dev": "^0.1.4",
         "@types/html-to-text": "^8.1.0",
         "@types/mocha": "^7.0.2",
-        "@types/node": "^14.0.0",
+        "@types/node": "^16.0.0",
         "@types/semver": "^7.3.9",
         "@types/vscode": "1.64.0",
         "@typescript-eslint/eslint-plugin": "^4.28.3",

utils/src/index.ts

@@ -37,6 +37,9 @@ export * from './utils/contextUtils';
 export * from './activityLog/activities/ExecuteActivity';
 export * from './getAzExtResourceType';
 export * from './AzExtResourceType';
+export * from './treev2/quickPickWizard/experiences/appResourceExperience';
+export * from './treev2/quickPickWizard/experiences/compatibility/PickTreeItemWithCompatibility';
+export * from './treev2/quickPickWizard/experiences/contextValueExperience';
 export * from './utils/apiUtils';
 export * from './tree/isAzExtTreeItem';
 // NOTE: The auto-fix action "source.organizeImports" does weird things with this file, but there doesn't seem to be a way to disable it on a per-file basis so we'll just let it happen

utils/src/treev2/quickPickWizard/ContextValueQuickPickStep.ts

@@ -0,0 +1,53 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { TreeItem } from 'vscode';
+import * as types from '../../../index';
+import { parseContextValue } from '../../utils/contextUtils';
+import { PickFilter } from './common/PickFilter';
+import { GenericQuickPickOptions, GenericQuickPickStep } from './GenericQuickPickStep';
+
+export interface ContextValueFilterQuickPickOptions extends GenericQuickPickOptions {
+    contextValueFilter: types.ContextValueFilter;
+}
+
+export class ContextValueQuickPickStep<TContext extends types.QuickPickWizardContext, TOptions extends ContextValueFilterQuickPickOptions> extends GenericQuickPickStep<TContext, TOptions> {
+    protected readonly pickFilter: PickFilter = new ContextValuePickFilter(this.pickOptions);
+}
+
+class ContextValuePickFilter implements PickFilter {
+    constructor(private readonly pickOptions: ContextValueFilterQuickPickOptions) { }
+
+    isFinalPick(node: TreeItem): boolean {
+        const includeOption = this.pickOptions.contextValueFilter.include;
+        const excludeOption = this.pickOptions.contextValueFilter.exclude;
+
+        const includeArray: (string | RegExp)[] = Array.isArray(includeOption) ? includeOption : [includeOption];
+        const excludeArray: (string | RegExp)[] = excludeOption ?
+            (Array.isArray(excludeOption) ? excludeOption : [excludeOption]) :
+            [];
+
+        const nodeContextValues: string[] = parseContextValue(node.contextValue);
+
+        return includeArray.some(i => this.matchesSingleFilter(i, nodeContextValues)) &&
+            !excludeArray.some(e => this.matchesSingleFilter(e, nodeContextValues));
+    }
+
+    isAncestorPick(node: TreeItem): boolean {
+        // `TreeItemCollapsibleState.None` and `undefined` are both falsy, and indicate that a `TreeItem` cannot have children--and therefore, cannot be an indirect pick
+        return !node.collapsibleState;
+    }
+
+    private matchesSingleFilter(matcher: string | RegExp, nodeContextValues: string[]): boolean {
+        return nodeContextValues.some(c => {
+            if (matcher instanceof RegExp) {
+                return matcher.test(c);
+            }
+
+            // Context value matcher is a string, do full equality (same as old behavior)
+            return c === matcher;
+        })
+    }
+}

utils/src/treev2/quickPickWizard/GenericQuickPickStep.ts

@@ -0,0 +1,99 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as types from '../../../index';
+import * as vscode from 'vscode';
+import { getLastNode } from './common/getLastNode';
+import { AzureWizardPromptStep } from '../../wizard/AzureWizardPromptStep';
+import { PickFilter } from './common/PickFilter';
+import { localize } from '../../localize';
+
+export interface GenericQuickPickOptions {
+    skipIfOne?: boolean;
+}
+
+export interface SkipIfOneQuickPickOptions extends GenericQuickPickOptions {
+    skipIfOne?: true;
+}
+
+export abstract class GenericQuickPickStep<TContext extends types.QuickPickWizardContext, TOptions extends GenericQuickPickOptions> extends AzureWizardPromptStep<TContext> {
+    public readonly supportsDuplicateSteps = true;
+
+    protected readonly abstract pickFilter: PickFilter<vscode.TreeItem>;
+
+    public constructor(
+        protected readonly treeDataProvider: vscode.TreeDataProvider<unknown>,
+        protected readonly pickOptions: TOptions
+    ) {
+        super();
+    }
+
+    public async prompt(wizardContext: TContext): Promise<void> {
+        const pick = await this.promptInternal(wizardContext);
+        wizardContext.pickedNodes.push(pick);
+    }
+
+    public undo(wizardContext: TContext): void {
+        wizardContext.pickedNodes.pop();
+    }
+
+    public shouldPrompt(_wizardContext: TContext): boolean {
+        return true;
+    }
+
+    protected async promptInternal(wizardContext: TContext): Promise<unknown> {
+        const picks = await this.getPicks(wizardContext);
+
+        if (picks.length === 1 && this.pickOptions.skipIfOne) {
+            return picks[0].data;
+        } else {
+            const selected = await wizardContext.ui.showQuickPick(picks, {
+                noPicksMessage: localize('noMatchingResources', 'No matching resources found.'),
+                /* TODO: options */
+                /* TODO: set id here so recently picked items appear at the top */
+            });
+
+            return selected.data;
+        }
+    }
+
+    protected async getPicks(wizardContext: TContext): Promise<types.IAzureQuickPickItem<unknown>[]> {
+        const lastPickedItem: unknown | undefined = getLastNode(wizardContext);
+
+        // TODO: if `lastPickedItem` is an `AzExtParentTreeItem`, should we clear its cache?
+        const childElements = (await this.treeDataProvider.getChildren(lastPickedItem)) || [];
+        const childItems = await Promise.all(childElements.map(async (childElement: unknown) => await this.treeDataProvider.getTreeItem(childElement)));
+        const childPairs: [unknown, vscode.TreeItem][] = childElements.map((childElement: unknown, i: number) => [childElement, childItems[i]]);
+
+        const finalChoices = childPairs.filter(([, ti]) => this.pickFilter.isFinalPick(ti));
+        const ancestorChoices = childPairs.filter(([, ti]) => this.pickFilter.isAncestorPick(ti));
+
+        let promptChoices: [unknown, vscode.TreeItem][] = [];
+        if (finalChoices.length === 0) {
+            if (ancestorChoices.length === 0) {
+                // Don't throw and end the wizard, let user use back button instead
+            } else {
+                promptChoices = ancestorChoices;
+            }
+        } else {
+            promptChoices = finalChoices;
+        }
+
+        const picks: types.IAzureQuickPickItem<unknown>[] = [];
+        for (const choice of promptChoices) {
+            picks.push(await this.getQuickPickItem(...choice));
+        }
+
+        return picks;
+    }
+
+    private async getQuickPickItem(element: unknown, item: vscode.TreeItem): Promise<types.IAzureQuickPickItem<unknown>> {
+        return {
+            label: ((item.label as vscode.TreeItemLabel)?.label || item.label) as string,
+            description: item.description as string,
+            data: element,
+        };
+    }
+}

utils/src/treev2/quickPickWizard/RecursiveQuickPickStep.ts

@@ -0,0 +1,34 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as types from '../../../index';
+import { ContextValueFilterQuickPickOptions, ContextValueQuickPickStep } from './ContextValueQuickPickStep';
+import { getLastNode } from './common/getLastNode';
+
+export class RecursiveQuickPickStep<TContext extends types.QuickPickWizardContext> extends ContextValueQuickPickStep<TContext, ContextValueFilterQuickPickOptions> {
+    hideStepCount: boolean = true;
+
+    public async getSubWizard(wizardContext: TContext): Promise<types.IWizardOptions<TContext> | undefined> {
+        const lastPickedItem = getLastNode(wizardContext);
+
+        if (!lastPickedItem) {
+            // Something went wrong, no node was chosen
+            throw new Error('No node was set after prompt step.');
+        }
+
+        if (this.pickFilter.isFinalPick(await this.treeDataProvider.getTreeItem(lastPickedItem))) {
+            // The last picked node matches the expected filter
+            // No need to continue prompting
+            return undefined;
+        } else {
+            // Need to keep going because the last picked node is not a match
+            return {
+                promptSteps: [
+                    new RecursiveQuickPickStep(this.treeDataProvider, this.pickOptions)
+                ],
+            };
+        }
+    }
+}