docs: disambiguation simplification for non-react solutions (#2054)

* docs: disambiguation simplification for non-react solutions

remove importMgtComponentLibrary references
removed spfx-utils from sp-mgt package.json
reworded custom element load behavior

Author: gavinbarron

packages/mgt-components/README.md

@@ -89,71 +89,42 @@ The earlier example can be updated to use the disambiguation feature as follows:
 
 > Note: the `import` of `mgt-components` must use a dynamic import to ensure that the disambiguation is applied before the components are imported.
 
-To simplify this pattern when developing SharePoint Framework web parts we have provided helper utilities in the [`mgt-spfx-utils`](https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-spfx-utils) package. Example usages are provided below.
+When developing SharePoint Framework web parts the pattern for using disambiguation is based on whether or not the MGT React wrapper library is being used. If you are using React then the helper utility in the [`mgt-spfx-utils`](https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-spfx-utils) package should be used. SharePoint Framework web part example usages are provided below.
 
 ### Usage in a SharePoint web part with no framework
 
-The `importMgtComponentsLibrary` helper function wraps a dynamic import of the `@microsoft/mgt-components` library.
+A dynamic import of the `@microsoft/mgt-components` library is used after configuring the disambiguation.
 
-A more complete example is available in the [No Framework Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-mgt/src/webparts/helloWorld/HelloWorldWebPart.ts).
+This example is sourced from the [No Framework Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-mgt/src/webparts/helloWorld/HelloWorldWebPart.ts).
 
 ```ts
 import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
 import { Providers } from '@microsoft/mgt-element';
 import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider';
 import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
-import { importMgtComponentsLibrary } from '@microsoft/mgt-spfx-utils';
 
 export default class MgtWebPart extends BaseClientSideWebPart<Record<string, unknown>> {
-  private _hasImportedMgtScripts = false;
-  private _errorMessage = '';
 
   protected onInit(): Promise<void> {
+    customElementHelper.withDisambiguation('foo');
     if (!Providers.globalProvider) {
       Providers.globalProvider = new SharePointProvider(this.context);
     }
-    customElementHelper.withDisambiguation('foo');
-    return super.onInit();
-  }
-
-  private onScriptsLoadedSuccessfully() {
-    this.render();
+    return import('@microsoft/mgt-components').then(() => super.onInit());
   }
 
   public render(): void {
-    importMgtComponentsLibrary(this._hasImportedMgtScripts, this.onScriptsLoadedSuccessfully, this.setErrorMessage);
-
     this.domElement.innerHTML = `
     <section class="${styles.helloWorld} ${this.context.sdks.microsoftTeams ? styles.teams : ''}">
-      ${this._renderMgtComponents()}
-      ${this._renderErrorMessage()}
+      <mgt-foo-login></mgt-foo-login>
     </section>`;
   }
-
-  private _renderMgtComponents(): string {
-    return this._hasImportedMgtScripts
-      ? '<mgt-foo-login></mgt-foo-login>'
-      : '';
-  }
-
-  private setErrorMessage(e?: Error): void {
-    if (e) this.renderError(e);
-
-    this._errorMessage = 'An error ocurred loading MGT scripts';
-    this.render();
-  }
-
-  private _renderErrorMessage(): string {
-    return this._errorMessage
-      ? `<span>${this._errorMessage}</span>`
-      : '';
-  }
 }
 ```
 
 ### Usage in a SharePoint web part using React
 
-The `lazyLoadComponent` helper function leverages `React.lazy` and `React.Suspense` to asynchronously load the components which have a direct dependency on `@microsoft/mgt-react` from the top level web part component.
+The `lazyLoadComponent` helper function from [`mgt-spfx-utils`](https://github.com/microsoftgraph/microsoft-graph-toolkit/tree/main/packages/mgt-spfx-utils) leverages `React.lazy` and `React.Suspense` to asynchronously load the components which have a direct dependency on `@microsoft/mgt-react` from the top level web part component.
 
 A complete example is available in the [React SharePoint Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-webpart/src/webparts/mgtDemo/MgtDemoWebPart.ts).
 

packages/mgt-spfx-utils/README.md

@@ -8,19 +8,7 @@ Helper functions to simplify lazy loading of Microsoft Graph Toolkit components
 
 ## Installation
 
-To lazy load Microsoft Graph Toolkit components from the library, add the `@microsoft/mgt-spfx-utils` package as a dependency to your SharePoint Framework project. If you use React, also add the `@microsoft/mgt-react` package:
-
-```bash
-npm install @microsoft/mgt-spfx-utils
-```
-
-or
-
-```bash
-yarn add @microsoft/mgt-spfx-utils
-```
-
-or when using React:
+To lazy load Microsoft Graph Toolkit components in a React web part add both the `@microsoft/mgt-spfx-utils` and `@microsoft/mgt-react` packages as dependencies to your SharePoint Framework project:
 
 ```bash
 npm install @microsoft/mgt-spfx-utils @microsoft/mgt-react
@@ -38,11 +26,11 @@ Disambiguation is intended to provide developers with a mechanism to use a speci
 
 By disambiguating tag names of Microsoft Graph Toolkit components, you can use your own version of MGT rather than using the centrally deployed `@microsoft/mgt-spfx` package. This allows you to avoid colliding with SharePoint Framework components built by other developers. When disambiguating tag names, MGT is included in the generated SPFx bundle, increasing its size. It is strongly recommended that you use a disambiguation value unique to your organization and solution to avoid collisions with other solutions, e.g. `contoso-hr-extensions`.
 
-> **Important:** Since a given web component tag can only be registered once these approaches **must** be used along with the `customElementHelper.withDisambiguation('foo')` approach as this allows developers to create disambiguated tag names.
+> **Important:** Since a given web component tag can only be registered once this approach **must** be used along with the `customElementHelper.withDisambiguation('foo')` as this allows developers to create disambiguated tag names.
 
 ### When using no framework web parts
 
-When building SharePoint Framework web parts without a JavaScript framework the `@microsoft/mgt-components` library must be asynchronously loaded after configuring the disambiguation setting. The `importMgtComponentsLibrary` helper function wraps this functionality. Once the `@microsoft/mgt-components` library is loaded you can load components directly in your web part.
+When building SharePoint Framework web parts without a JavaScript framework the `@microsoft/mgt-components` library must be asynchronously loaded after configuring the disambiguation setting. No helper library is necessary as dynamic imports are sufficient. After the browser has loaded the `@microsoft/mgt-components` library any tags which had already been rendered to the DOM without an existing custom element registration will automatically have the loaded custom behavior attached to them.
 
 Below is a minimal example web part that demonstrates how to use MGT with disambiguation in SharePoint Framework Web parts. A more complete example is available in the [No Framework Web Part Sample](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/samples/sp-mgt/src/webparts/helloWorld/HelloWorldWebPart.ts).
 
@@ -51,53 +39,24 @@ import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
 import { Providers } from '@microsoft/mgt-element';
 import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider';
 import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
-import { importMgtComponentsLibrary } from '@microsoft/mgt-spfx-utils';
 
 export default class MgtWebPart extends BaseClientSideWebPart<Record<string, unknown>> {
-  private _hasImportedMgtScripts = false;
-  private _errorMessage = '';
-
   protected onInit(): Promise<void> {
     if (!Providers.globalProvider) {
       Providers.globalProvider = new SharePointProvider(this.context);
     }
     // Use the solution name to ensure unique tag names
     customElementHelper.withDisambiguation('spfx-solution-name');
-    return super.onInit();
-  }
-
-  private onScriptsLoadedSuccessfully() {
-    this.render();
+    return import('@microsoft/mgt-components').then(() => super.onInit());
   }
 
   public render(): void {
-    importMgtComponentsLibrary(this._hasImportedMgtScripts, this.onScriptsLoadedSuccessfully, this.setErrorMessage);
 
     this.domElement.innerHTML = `
     <section class="${styles.helloWorld} ${this.context.sdks.microsoftTeams ? styles.teams : ''}">
-      ${this._renderMgtComponents()}
-      ${this._renderErrorMessage()}
+      <mgt-spfx-solution-name-login></mgt-spfx-solution-name-login>
     </section>`;
   }
-
-  private _renderMgtComponents(): string {
-    return this._hasImportedMgtScripts
-      ? '<mgt-foo-login></mgt-foo-login>'
-      : '';
-  }
-
-  private setErrorMessage(e?: Error): void {
-    if (e) this.renderError(e);
-
-    this._errorMessage = 'An error ocurred loading MGT scripts';
-    this.render();
-  }
-
-  private _renderErrorMessage(): string {
-    return this._errorMessage
-      ? `<span>${this._errorMessage}</span>`
-      : '';
-  }
 }
 ```
 

packages/mgt-spfx-utils/src/importMgtComponentsLibrary.ts

@@ -5,8 +5,6 @@
  * -------------------------------------------------------------------------------------------
  */
 
-import './importMgtComponentsLibrary';
 import './lazyLoadMgtReactComponent';
 
-export * from './importMgtComponentsLibrary';
 export * from './lazyLoadMgtReactComponent';

packages/mgt-spfx-utils/src/index.ts

@@ -3,7 +3,7 @@
   "solution": {
     "name": "sp-mgt-no-framework-client-side-solution",
     "id": "8606d7ab-8b1e-461f-b611-416054c65000",
-    "version": "1.0.0.1",
+    "version": "1.0.0.2",
     "includeClientSideAssets": true,
     "skipFeatureDeployment": true,
     "isDomainIsolated": false,

samples/sp-mgt/config/package-solution.json

@@ -1,6 +1,6 @@
 {
   "name": "sp-mgt-no-framework",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": true,
   "main": "lib/index.js",
   "scripts": {
@@ -15,7 +15,6 @@
     "@microsoft/mgt-element": "*",
     "@microsoft/mgt-components": "*",
     "@microsoft/mgt-sharepoint-provider": "*",
-    "@microsoft/mgt-spfx-utils": "*",
     "@microsoft/sp-core-library": "1.16.1",
     "@microsoft/sp-property-pane": "1.16.1",
     "@microsoft/sp-webpart-base": "1.16.1",

samples/sp-mgt/package.json

@@ -5,68 +5,38 @@ import styles from './HelloWorldWebPart.module.scss';
 import { Providers } from '@microsoft/mgt-element';
 import { SharePointProvider } from '@microsoft/mgt-sharepoint-provider';
 import { customElementHelper } from '@microsoft/mgt-element/dist/es6/components/customElementHelper';
-import { importMgtComponentsLibrary } from '@microsoft/mgt-spfx-utils';
 
 export default class HelloWorldWebPart extends BaseClientSideWebPart<Record<string, unknown>> {
-  private _hasImportedMgtScripts = false;
-  private _errorMessage = '';
-
   protected onInit(): Promise<void> {
+    customElementHelper.withDisambiguation('sp-mgt-no-framework-client-side-solution');
     if (!Providers.globalProvider) {
       Providers.globalProvider = new SharePointProvider(this.context);
     }
-    customElementHelper.withDisambiguation('sp-mgt-no-framework-client-side-solution');
-    return super.onInit();
-  }
-
-  private onScriptsLoadedSuccessfully() {
-    this.render();
+    return import('@microsoft/mgt-components').then(() => super.onInit());
   }
 
   public render(): void {
-    importMgtComponentsLibrary(this._hasImportedMgtScripts, this.onScriptsLoadedSuccessfully, this.setErrorMessage);
-
     this.domElement.innerHTML = `
     <section class="${styles.helloWorld} ${this.context.sdks.microsoftTeams ? styles.teams : ''}">
       ${this._renderMgtComponents()}
-      ${this._renderErrorMessage()}
     </section>`;
   }
 
   private _renderMgtComponents(): string {
-    return this._hasImportedMgtScripts
-      ? `
+    return `
       <div class="${styles.container}">
-        <mgt-contoso-person
+        <mgt-sp-mgt-no-framework-client-side-solution-person
           show-presence
           person-query="me"
           view="twoLines"
           person-card="hover"
-        ></mgt-contoso-person>
-        <mgt-contoso-people></mgt-contoso-people>
-        <mgt-contoso-agenda></mgt-contoso-agenda>
-        <mgt-contoso-people-picker></mgt-contoso-people-picker>
-        <mgt-contoso-teams-channel-picker></mgt-contoso-teams-channel-picker>
-        <mgt-contoso-tasks></mgt-contoso-tasks>
+        ></mgt-sp-mgt-no-framework-client-side-solution-person>
+        <mgt-sp-mgt-no-framework-client-side-solution-people></mgt-sp-mgt-no-framework-client-side-solution-people>
+        <mgt-sp-mgt-no-framework-client-side-solution-agenda></mgt-sp-mgt-no-framework-client-side-solution-agenda>
+        <mgt-sp-mgt-no-framework-client-side-solution-people-picker></mgt-sp-mgt-no-framework-client-side-solution-people-picker>
+        <mgt-sp-mgt-no-framework-client-side-solution-teams-channel-picker></mgt-sp-mgt-no-framework-client-side-solution-teams-channel-picker>
+        <mgt-sp-mgt-no-framework-client-side-solution-tasks></mgt-sp-mgt-no-framework-client-side-solution-tasks>
       </div>
-`
-      : '';
-  }
-
-  private setErrorMessage(e?: Error): void {
-    if (e) this.renderError(e);
-
-    this._errorMessage = 'An error ocurred loading MGT scripts';
-    this.render();
-  }
-
-  private _renderErrorMessage(): string {
-    return this._errorMessage
-      ? `
-      <span class="${styles.error}>
-        ${this._errorMessage}
-      </span>
-`
-      : '';
+`;
   }
 }