Add documentation for quick pick wizards (#1408)

utils/README.md

@@ -48,6 +48,72 @@ registerEvent(
 );
 ```
 
+## Pick tree items (Azure Resources API V2)
+
+The Azure Resources API exposes a `TreeDataProvider` for both the Azure resources view and the Workspace resources view. `azureResourceTreeDataProvider` and `workspaceResourceTreeDataProvider` are exposed by the Azure Resources API.
+
+We've created a set of utilities to provide a tree node picking experience that uses quick pick steps in a wizards.
+
+#### Pick an Azure subscription
+
+```ts
+const subscription = await subscriptionExperience(context, api.resources.azureResourceTreeDataProvider);
+```
+
+#### Pick an Azure resource
+
+```ts
+// pick an Azure Resource, in this case a Function App
+const functionApp = await azureResourceExperience(context, api.resources.azureResourceTreeDataProvider, AzExtResourceType.FunctionApp);
+```
+
+#### Pick a descendent of an Azure resource
+
+```ts
+// pick an Azure Resource, in this case a Function App, and then select a descendant of the Function App, in this case an App Setting item
+const functionAppAppSetting = await azureResourceExperience(context, api.resources.azureResourceTreeDataProvider, AzExtResourceType.FunctionApp, {
+    include: ['appSettingContextValue']
+});
+```
+
+#### Pick a workspace item
+
+```ts
+// pick an item based on context value
+const item = await contextValueExperience(context, api.resources.workspaceResourceTreeDataProvider, {
+    include: ['itemContextValue']
+});
+```
+
+### Run a wizard with custom pick steps
+
+If you more granular control over the quick pick steps in the wizard, you can use `runQuickPickWizard` to run a fully customizable quick pick wizard. Here's an example of picking a Function App using `runQuickPickWizard`.
+
+```ts
+
+import { runQuickPickWizard, QuickPickAzureSubscriptionStep, QuickPickGroupStep, QuickPickAzureResourceStep } from '@microsoft/vscode-azext-utils';
+
+const tdp = ext.rgApiV2.resources.azureResourceTreeDataProvider;
+
+const functionApp = await runQuickPickWizard(context, {
+    promptSteps: [
+        // first step: pick a subscription
+        new QuickPickAzureSubscriptionStep(tdp),
+        // second step: pick a group, if we are grouped by resource type, pick function apps automatically
+        new QuickPickGroupStep(tdp, {
+            groupType: [AzExtResourceType.FunctionApp],
+        }),
+        // third step: pick a resource, in this case a function app
+        new QuickPickAzureResourceStep(tdp, {
+            resourceTypes: [AzExtResourceType.FunctionApp],
+            skipIfOne: false,
+        }, {
+            placeHolder: 'Select a Function App',
+        }),
+    ]
+});
+```
+
 ## Azure Extension Tree Data Provider
 
 ![ExampleTree](resources/ExampleTree.png)

utils/index.d.ts

@@ -1685,9 +1685,32 @@ export interface PickExperienceContext extends IActionContext {
     dontUnwrap?: boolean;
 }
 
+/**
+ * Prompts the user to pick a subscription using a quick pick. If there is only one subscription, it will be returned without prompting the user.
+ *
+ * @param context The action context
+ * @param tdp Azure resource tree data provider to perform the pick experience on
+ */
+export declare function subscriptionExperience(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>): Promise<AzureSubscription>;
+
+/**
+ * Prompts the user to pick an Azure resource using a wizard comprised of quick pick steps.
+ *
+ * @param context The action context
+ * @param tdp Azure resource tree data provider to perform the pick experience on
+ * @param resourceTypes the resource types to allow the user to pick from
+ * @param childItemFilter prompt the user to pick children of the Azure resource until an item matching the filter is selected
+ */
 export declare function azureResourceExperience<TPick extends unknown>(context: PickExperienceContext, tdp: TreeDataProvider<ResourceGroupsItem>, resourceTypes?: AzExtResourceType | AzExtResourceType[], childItemFilter?: ContextValueFilter): Promise<TPick>;
+
+/**
+ * Recursively prompts the user to pick a node until a node is packed matching the context value filter.
+ *
+ * @param context The action context
+ * @param tdp tree data provider to pick a node from
+ * @param contextValueFilter the context value filter used to match the deesired node(s)
+ */
 export declare function contextValueExperience<TPick extends unknown>(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>, contextValueFilter: ContextValueFilter): Promise<TPick>;
-export declare function subscriptionExperience(context: IActionContext, tdp: TreeDataProvider<ResourceGroupsItem>): Promise<AzureSubscription>;
 
 interface CompatibilityPickResourceExperienceOptions {
     resourceTypes?: AzExtResourceType | AzExtResourceType[];
@@ -1846,12 +1869,21 @@ export declare interface ContextValueFilterQuickPickOptions extends GenericQuick
     contextValueFilter: ContextValueFilter;
 }
 
+/**
+ * Quick pick step that selects a tree node matching a context value filter.
+ */
 export declare class ContextValueQuickPickStep<TContext extends QuickPickWizardContext, TOptions extends ContextValueFilterQuickPickOptions> extends GenericQuickPickStep<TContext, TOptions> {
     protected readonly pickFilter: PickFilter;
 }
 
+/**
+ * Recursively select tree nodes until a final node is selected that matches the context value filter.
+ */
 export declare class RecursiveQuickPickStep<TContext extends QuickPickWizardContext> extends ContextValueQuickPickStep<TContext, ContextValueFilterQuickPickOptions> { }
 
+/**
+ * Quick pick step to pick an Azure subscription.
+ */
 export declare class QuickPickAzureSubscriptionStep extends GenericQuickPickStepWithCommands<AzureResourceQuickPickWizardContext, SkipIfOneQuickPickOptions> {
     public constructor(tdp: TreeDataProvider<ResourceGroupsItem>, options?: GenericQuickPickOptions);
 }
@@ -1861,6 +1893,11 @@ export declare interface GroupQuickPickOptions extends SkipIfOneQuickPickOptions
     skipIfOne?: true;
 }
 
+/**
+ * Quick pick step that selects a group.
+ *
+ * If view is grouped by Resource Type, and a group matching `options.groupType` is found, it will be auto selected.
+ */
 export declare class QuickPickGroupStep extends GenericQuickPickStep<AzureResourceQuickPickWizardContext, GroupQuickPickOptions> {
     public constructor(tdp: TreeDataProvider<unknown>, options: GroupQuickPickOptions);
 }
@@ -1870,9 +1907,18 @@ export declare interface AzureResourceQuickPickOptions extends GenericQuickPickO
     childItemFilter?: ContextValueFilter;
 }
 
+/**
+ * Quick pick step that selects an Azure resource.
+ */
 export declare class QuickPickAzureResourceStep extends GenericQuickPickStep<AzureResourceQuickPickWizardContext, AzureResourceQuickPickOptions> {
     public constructor(tdp: TreeDataProvider<ResourceGroupsItem>, options?: AzureResourceQuickPickOptions, promptOptions?: IAzureQuickPickOptions);
 }
 
+/**
+ * Creates and runs a quick pick wizard with the given wizard options.
+ *
+ * @param context The action context
+ * @param wizardOptions The options used to construct the wizard
+ */
 export declare function runQuickPickWizard<TPick>(context: PickExperienceContext, wizardOptions?: IWizardOptions<AzureResourceQuickPickWizardContext>): Promise<TPick>;
 //#endregion