Updates to web parts guidance (SharePoint#828)

* Updated guidance on using JSOM to the latest version of SPFx

* Updated code sample in the guidance on validating web part property values

* Updated code samples in the guidance on using cascading dropdowns to the latest version of SPFx

* Updated guidance on building custom web part properties

Author: waldekmastykarz

docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md

@@ -1,7 +1,5 @@
 # Build custom controls for the property pane
 
-> Note. This article has not yet been verified with SPFx GA version, so you might have challenges on making this work as such with the latest release.
-
 The SharePoint Framework contains a set of standard controls for the property pane. But sometimes you need additional functionality beyond the basic controls. You might need asynchronous updates to the data on a control, or a specific user interface. Build a custom control for the property pane to get the functionality you need.
 
 In this article you will learn how to build a custom control for the property pane. You will build a custom dropdown control that loads its data asynchronously from an external service without blocking the user interface of the web part.
@@ -78,12 +76,12 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
 }
 ```
 
-Update the **propertyPaneSettings** getter to:
+Update the **getPropertyPaneConfiguration** method to:
 
 ```ts
 export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWebPartProps> {
   // ...
-  protected get propertyPaneSettings(): IPropertyPaneSettings {
+  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
     return {
       pages: [
         {
@@ -108,10 +106,10 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
 }
 ```
 
-In the **src/webparts/listItems/loc/mystrings.d.ts** file change the **IListItemsStrings** interface to:
+In the **src/webparts/listItems/loc/mystrings.d.ts** file change the **IListItemsWebPartStrings** interface to:
 
 ```ts
-declare interface IListItemsStrings {
+declare interface IListItemsWebPartStrings {
   PropertyPaneDescription: string;
   BasicGroupName: string;
   ListFieldLabel: string;
@@ -134,26 +132,17 @@ In the **src/webparts/listItems/components/ListItems.tsx** file change the conte
 
 ```tsx
 export default class ListItems extends React.Component<IListItemsProps, {}> {
-  public render(): JSX.Element {
+  public render(): React.ReactElement<IListItemsProps> {
     return (
       <div className={styles.listItems}>
         <div className={styles.container}>
-          <div className={css('ms-Grid-row ms-bgColor-themeDark ms-fontColor-white', styles.row)}>
-            <div className='ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1'>
-              <span className='ms-font-xl ms-fontColor-white'>
-                Welcome to SharePoint!
-              </span>
-              <p className='ms-font-l ms-fontColor-white'>
-                Customize SharePoint experiences using web parts.
-              </p>
-              <p className='ms-font-l ms-fontColor-white'>
-                {this.props.listName}
-              </p>
-              <a
-                className={css('ms-Button', styles.button)}
-                href='https://github.com/SharePoint/sp-dev-docs/wiki'
-              >
-                <span className='ms-Button-label'>Learn more</span>
+          <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
+            <div className="ms-Grid-col ms-lg10 ms-xl8 ms-xlPush2 ms-lgPush1">
+              <span className="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>
+              <p className="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>
+              <p className="ms-font-l ms-fontColor-white">{escape(this.props.listName)}</p>
+              <a href="https://aka.ms/spfx" className={styles.button}>
+                <span className={styles.label}>Learn more</span>
               </a>
             </div>
           </div>
@@ -164,6 +153,14 @@ export default class ListItems extends React.Component<IListItemsProps, {}> {
 }
 ```
 
+Next, open the **src/webparts/listItems/components/IListItemsProps.ts** file and replace its contents with:
+
+```ts
+export interface IListItemsProps {
+  listName: string;
+}
+```
+
 Run the following command to verify that the project is running:
 
 ```sh
@@ -205,7 +202,7 @@ In the project **src** folder, create a hierarchy of three new folders so that y
 In the **src/controls/PropertyPaneAsyncDropdown/components** folder create a new file named **IAsyncDropdownProps.ts** and enter the following code:
 
 ```ts
-import { IDropdownOption } from 'office-ui-fabric-react';
+import { IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
 
 export interface IAsyncDropdownProps {
   label: string;
@@ -219,12 +216,12 @@ export interface IAsyncDropdownProps {
 
 The **IAsyncDropdownProps** class defines properties that can be set on the React component used by the custom property pane control. The **label** property specifies the label for the dropdown control. The function associated with the **loadOptions** delegate is called by the control to load the available options. The function associated with the **onChanged** delegate is called after the user selected an option in the dropdown. The **selectedKey** property specifies the selected value which can be a string or a number. The **disabled** property specifies if the dropdown control is disabled or not. The **stateKey** property is used to force the React component to re-render.
 
-#### Define asynchronous dropdown React component stateKey
+#### Define asynchronous dropdown React component interface
 
 In the **src/controls/PropertyPaneAsyncDropdown/components** folder create new file named **IAsyncDropdownState.ts** and enter the following code:
 
 ```ts
-import { IDropdownOption } from 'office-ui-fabric-react';
+import { IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
 
 export interface IAsyncDropdownState {
   loading: boolean;
@@ -241,14 +238,17 @@ In the **src/controls/PropertyPaneAsyncDropdown/components** folder create a new
 
 ```tsx
 import * as React from 'react';
-import { Dropdown, Spinner } from 'office-ui-fabric-react';
+import { Dropdown, IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
+import { Spinner } from 'office-ui-fabric-react/lib/components/Spinner';
 import { IAsyncDropdownProps } from './IAsyncDropdownProps';
 import { IAsyncDropdownState } from './IAsyncDropdownState';
-import { IDropdownOption } from 'office-ui-fabric-react';
 
 export default class AsyncDropdown extends React.Component<IAsyncDropdownProps, IAsyncDropdownState> {
+  private selectedKey: React.ReactText;
+
   constructor(props: IAsyncDropdownProps, state: IAsyncDropdownState) {
     super(props);
+    this.selectedKey = props.selectedKey;
 
     this.state = {
       loading: false,
@@ -298,15 +298,33 @@ export default class AsyncDropdown extends React.Component<IAsyncDropdownProps,
     return (
       <div>
         <Dropdown label={this.props.label}
-          isDisabled={this.props.disabled || this.state.loading || this.state.error !== undefined}
-          onChanged={this.props.onChanged}
-          selectedKey={this.props.selectedKey}
+          disabled={this.props.disabled || this.state.loading || this.state.error !== undefined}
+          onChanged={this.onChanged.bind(this)}
+          selectedKey={this.selectedKey}
           options={this.state.options} />
         {loading}
         {error}
       </div>
     );
   }
+
+  private onChanged(option: IDropdownOption, index?: number): void {
+    this.selectedKey = option.key;
+    // reset previously selected options
+    const options: IDropdownOption[] = this.state.options;
+    options.forEach((o: IDropdownOption): void => {
+      if (o.key !== option.key) {
+        o.selected = false;
+      }
+    });
+    this.setState((prevState: IAsyncDropdownState, props: IAsyncDropdownProps): IAsyncDropdownState => {
+      prevState.options = options;
+      return prevState;
+    });
+    if (this.props.onChanged) {
+      this.props.onChanged(option, index);
+    }
+  }
 }
 ```
 
@@ -327,7 +345,7 @@ The second set of properties are private properties used internally inside the c
 In the **src/controls/PropertyPaneAsyncDropdown** folder create a new file named **IPropertyPaneAsyncDropdownProps.ts** and enter the following code:
 
 ```ts
-import { IDropdownOption } from 'office-ui-fabric-react';
+import { IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
 
 export interface IPropertyPaneAsyncDropdownProps {
   label: string;
@@ -365,7 +383,7 @@ import {
   IPropertyPaneField,
   PropertyPaneFieldType
 } from '@microsoft/sp-webpart-base';
-import { IDropdownOption } from 'office-ui-fabric-react';
+import { IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
 import { IPropertyPaneAsyncDropdownProps } from './IPropertyPaneAsyncDropdownProps';
 import { IPropertyPaneAsyncDropdownInternalProps } from './IPropertyPaneAsyncDropdownInternalProps';
 import AsyncDropdown from './components/AsyncDropdown';
@@ -380,6 +398,7 @@ export class PropertyPaneAsyncDropdown implements IPropertyPaneField<IPropertyPa
   constructor(targetProperty: string, properties: IPropertyPaneAsyncDropdownProps) {
     this.targetProperty = targetProperty;
     this.properties = {
+      key: properties.label,
       label: properties.label,
       loadOptions: properties.loadOptions,
       onPropertyChange: properties.onPropertyChange,
@@ -422,9 +441,9 @@ export class PropertyPaneAsyncDropdown implements IPropertyPaneField<IPropertyPa
 
 The **PropertyPaneAsyncDropdown** class implements the standard SharePoint Framework **IPropertyPaneField** interface using the **IPropertyPaneAsyncDropdownProps** interface as a contract for its public properties that can be set from inside the web part. The class contains the following three public properties defined by the **IPropertyPaneField** interface:
 
- * **type**: Must be set to **PropertyPaneFieldType.Custom** for a custom property pane control.
- * **targetProperty**: Used to specify the name of the web part property to be used with the control.
- * **properties**: Used to define control-specific properties.
+- **type**: Must be set to **PropertyPaneFieldType.Custom** for a custom property pane control.
+- **targetProperty**: Used to specify the name of the web part property to be used with the control.
+- **properties**: Used to define control-specific properties.
 
 Notice how the **properties** property is of the internal **IPropertyPaneAsyncDropdownInternalProps** type rather than the public **IPropertyPaneAsyncDropdownProps** interface implemented by the class. This is on purpose so that the **properties** property can define the **onRender** method required by the SharePoint Framework. If the **onRender** method was a part of the public **IPropertyPaneAsyncDropdownProps** interface then, when using the asynchronous dropdown control in the web part, you would be required to assign a value to it inside the web part, which isn't desirable.
 
@@ -458,7 +477,7 @@ import { PropertyPaneAsyncDropdown } from '../../controls/PropertyPaneAsyncDropd
 Then after that code, add a reference to the **IDropdownOption** interface and two helpers functions required to work with web part properties.
 
 ```ts
-import { IDropdownOption } from 'office-ui-fabric-react';
+import { IDropdownOption } from 'office-ui-fabric-react/lib/components/Dropdown';
 import { update, get } from '@microsoft/sp-lodash-subset';
 ```
 
@@ -500,21 +519,21 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
     // store new value in web part properties
     update(this.properties, propertyPath, (): any => { return newValue; });
     // refresh web part
-    this.onPropertyPaneFieldChanged(propertyPath, oldValue, newValue);
+    this.render();
   }
 }
 ```
 
 After selecting a list in the list dropdown, the selected value should be persisted in web part properties and the web part should be re-rendered to reflect the selected property.
 
-#### Render the list web part property using the asynchronous dropdown property pane control 
+#### Render the list web part property using the asynchronous dropdown property pane control
 
-In the **ListItemsWebPart** class change the **propertyPaneSettings** getter to use the asynchronous dropdown property pane control to render the **listName** web part property.
+In the **ListItemsWebPart** class change the **getPropertyPaneConfiguration** method to use the asynchronous dropdown property pane control to render the **listName** web part property.
 
 ```ts
 export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWebPartProps> {
   // ...
-  protected get propertyPaneSettings(): IPropertyPaneSettings {
+  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
     return {
       pages: [
         {
@@ -580,6 +599,15 @@ export interface IListItemsWebPartProps {
 }
 ```
 
+Change the contents of the **src/webparts/listItems/components/IListItemsProps.ts** file to:
+
+```ts
+export interface IListItemsProps {
+  listName: string;
+  item: string;
+}
+```
+
 In the **src/webparts/listItems/ListItemsWebPart.ts** file, change the code of the **render** method to:
 
 ```ts
@@ -597,10 +625,10 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
 }
 ```
 
-In the **src/webparts/listItems/loc/mystrings.d.ts** file change the **IListItemsStrings** interface to
+In the **src/webparts/listItems/loc/mystrings.d.ts** file change the **IListItemsWebPartStrings** interface to
 
 ```ts
-declare interface IListItemsStrings {
+declare interface IListItemsWebPartStrings {
   PropertyPaneDescription: string;
   BasicGroupName: string;
   ListFieldLabel: string;
@@ -627,29 +655,18 @@ In the **src/webparts/listItems/components/ListItems.tsx** file change the **ren
 
 ```tsx
 export default class ListItems extends React.Component<IListItemsProps, {}> {
-  public render(): JSX.Element {
+  public render(): React.ReactElement<IListItemsProps> {
     return (
       <div className={styles.listItems}>
         <div className={styles.container}>
-          <div className={css('ms-Grid-row ms-bgColor-themeDark ms-fontColor-white', styles.row)}>
-            <div className='ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1'>
-              <span className='ms-font-xl ms-fontColor-white'>
-                Welcome to SharePoint!
-              </span>
-              <p className='ms-font-l ms-fontColor-white'>
-                Customize SharePoint experiences using web parts.
-              </p>
-              <p className='ms-font-l ms-fontColor-white'>
-                {this.props.listName}
-              </p>
-              <p className='ms-font-l ms-fontColor-white'>
-                {this.props.item}
-              </p>
-              <a
-                className={css('ms-Button', styles.button)}
-                href='https://github.com/SharePoint/sp-dev-docs/wiki'
-              >
-                <span className='ms-Button-label'>Learn more</span>
+          <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
+            <div className="ms-Grid-col ms-lg10 ms-xl8 ms-xlPush2 ms-lgPush1">
+              <span className="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>
+              <p className="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>
+              <p className="ms-font-l ms-fontColor-white">{escape(this.props.listName)}</p>
+              <p className="ms-font-l ms-fontColor-white">{escape(this.props.item)}</p>
+              <a href="https://aka.ms/spfx" className={styles.button}>
+                <span className={styles.label}>Learn more</span>
               </a>
             </div>
           </div>
@@ -720,7 +737,7 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
     // store new value in web part properties
     update(this.properties, propertyPath, (): any => { return newValue; });
     // refresh web part
-    this.onPropertyPaneFieldChanged(propertyPath, oldValue, newValue);
+    this.render();
   }
 }
 ```
@@ -738,12 +755,12 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
 }
 ```
 
-Next change the code of the **propertyPaneSettings** getter to:
+Next change the code of the **getPropertyPaneConfiguration** method to:
 
 ```ts
 export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWebPartProps> {
   // ...
-  protected get propertyPaneSettings(): IPropertyPaneSettings {
+  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
     // reference to item dropdown needed later after selecting a list
     this.itemsDropDown = new PropertyPaneAsyncDropdown('item', {
       label: strings.ItemFieldLabel,
@@ -800,7 +817,7 @@ export default class ListItemsWebPart extends BaseClientSideWebPart<IListItemsWe
     // store new value in web part properties
     update(this.properties, 'item', (): any => { return this.properties.item; });
     // refresh web part
-    this.onPropertyPaneFieldChanged(propertyPath, oldValue, newValue);
+    this.render();
     // reset selected values in item dropdown
     this.itemsDropDown.properties.selectedKey = this.properties.item;
     // allow to load items