docs: fix Blazor, webpack, and cdn links (microsoft#5348)

* docs(webpack): fix breaking changes in webpack * docs: fix blazor docs and update cdn throughout * docs(blazor): add product color config info * Change files Co-authored-by: Aaron Wentzel <16669785+awentzel@users.noreply.github.com> Co-authored-by: EisenbergEffect <roeisenb@microsoft.com>
alphashr · alphashr · Dec 2, 2021 · Nov 29, 2021 · Nov 30, 2021 · Dec 1, 2021
commit 2ec536794820959f771ebbfe25efd5a4489e7a76
diff --git a/change/@microsoft-fast-components-54d045b3-dee7-4936-b3a3-c4fabc77ca1f.json b/change/@microsoft-fast-components-54d045b3-dee7-4936-b3a3-c4fabc77ca1f.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: corrections to Blazor, webpack, and cdn links",
+  "packageName": "@microsoft/fast-components",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/change/@microsoft-fast-element-1ba44c5d-e30e-4561-8139-9558372ffc54.json b/change/@microsoft-fast-element-1ba44c5d-e30e-4561-8139-9558372ffc54.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: corrections to cdn links",
+  "packageName": "@microsoft/fast-element",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/change/@microsoft-fast-foundation-6d7b2b4a-663d-4429-b850-8a9bcbc91924.json b/change/@microsoft-fast-foundation-6d7b2b4a-663d-4429-b850-8a9bcbc91924.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "corrections to Blazor, webpack, and cdn links",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/change/@microsoft-fast-router-0c1ea2f5-d693-4ddb-9a48-21b495de1286.json b/change/@microsoft-fast-router-0c1ea2f5-d693-4ddb-9a48-21b495de1286.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: corrections to cdn links",
+  "packageName": "@microsoft/fast-router",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/packages/web-components/fast-components/README.md b/packages/web-components/fast-components/README.md
@@ -51,15 +51,21 @@ A pre-bundled script that contains all APIs needed to use FAST Foundation is ava
 <!DOCTYPE html>
 <html lang="en">
     <head>
-        <script type="module" src="https://unpkg.com/@microsoft/fast-components"></script>
+        <script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components/dist/fast-components.min.js"></script>
     </head>
     <!-- ... -->
 </html>
 ```
 
-The above CDN location points to the latest release of `fast-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
+The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
 
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components@2.16.0/dist/fast-components.min.js"></script>
+```
+
+:::note
 For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
+:::
 
 ## Development
 

diff --git a/packages/web-components/fast-element/README.md b/packages/web-components/fast-element/README.md
@@ -38,7 +38,7 @@ A pre-bundled script that contains all APIs needed to build web components with
 <html lang="en">
     <head>
         <script type="module">
-          import { FASTElement } from "https://unpkg.com/@microsoft/fast-element";
+          import { FASTElement } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-element/dist/fast-element.min.js";
 
           // your code here
         </script>
@@ -47,9 +47,11 @@ A pre-bundled script that contains all APIs needed to build web components with
 </html>
 ```
 
-:::important
-The above CDN location points to the latest release of `fast-element`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
-:::
+The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-element@1.6.2/dist/fast-element.min.js"></script>
+```
 
 :::note
 For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.

diff --git a/packages/web-components/fast-foundation/README.md b/packages/web-components/fast-foundation/README.md
@@ -38,7 +38,7 @@ A pre-bundled script that contains all APIs needed to use FAST Foundation is ava
 <html lang="en">
     <head>
         <script type="module">
-          import { Anchor } from "https://unpkg.com/@microsoft/fast-foundation";
+          import { Anchor } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-foundation/dist/fast-foundation.min.js";
 
           // your code here
         </script>
@@ -47,6 +47,12 @@ A pre-bundled script that contains all APIs needed to use FAST Foundation is ava
 </html>
 ```
 
-The above CDN location points to the latest release of `fast-foundation`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
+The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
 
-For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-foundation@2.26.2/dist/fast-foundation.min.js"></script>
+```
+
+:::note
+For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
+:::
diff --git a/packages/web-components/fast-foundation/docs/integrations/aspnet.md b/packages/web-components/fast-foundation/docs/integrations/aspnet.md
@@ -26,7 +26,13 @@ Now that we've got our basic project setup, we need to add our web components sc
 To add a CDN script for `fast-components` use the following markup:
 
 ```html
-<script type="module" src="https://unpkg.com/@@microsoft/fast-components"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components/dist/fast-components.min.js"></script>
+```
+
+The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components@2.16.0/dist/fast-components.min.js"></script>
 ```
 
 The best place to put this is typically in your `_Layout.cshtml` file in the script section at the bottom of the `<body>`.

diff --git a/packages/web-components/fast-foundation/docs/integrations/blazor.md b/packages/web-components/fast-foundation/docs/integrations/blazor.md
@@ -19,22 +19,130 @@ dotnet new blazorwasm -o fast-blazor
 
 Create a project using the command above if you don't already have one. When the CLI completes, you should have a basic runnable Blazor application. For more information on setting up and using Blazor, [see the official Blazor Getting Started guide](https://docs.microsoft.com/en-us/aspnet/core/blazor/get-started).
 
-## Configuring scripts
+## Getting Started with the FluentUI Web Components
 
-Now that we've got our basic project setup, we need to add our web components script and update Blazor accordingly. You can either add the script from our CDN directly, or you can install it with NPM and then add that.
+FAST has special Blazor support for Microsoft's FluentUI Web Components. To get started using the Fluent UI Web Components for Blazor, you will first need to install [the official Nuget package for Fluent UI](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI/). You can use the following command:
 
-To add a CDN script for `fast-components` use the following markup:
+```shell
+dotnet add package Microsoft.Fast.Components.FluentUI
+```
+
+Next, you need to add the web components script. You can either add the script from CDN directly, or you can install it with NPM, whichever you prefer.
+
+To add the script from CDN use the following markup:
 
 ```html
-<script type="module" src="https://unpkg.com/@microsoft/fast-components"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@fluentui/web-components/dist/web-components.min.js"></script>
 ```
 
-The best place to put this is typically in your `index.html` file in the script section at the bottom of the `<body>`.
+The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@fluentui/web-components@2.0.2/dist/web-components.min.js"></script>
+```
+
+The best place to put the script tag is typically in your index.html file in the script section at the bottom of the `<body>`.
+
+If you wish to leverage NPM instead, run the following command:
+
+```html
+npm install --save @fluentui/web-components
+```
+
+You can locate the single file script build in the following location:
+
+```html
+node_modules/@fluentui/web-components/dist/web-components.min.js
+```
+
+Copy this to your `wwwroot/script` folder and reference it with a script tag as described above.
 
 :::note
-If you are setting up FAST on a Blazor Server project, you will need to escape the `@` character by repeating it in the source link. For more information check out the [Razor Pages syntax documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/razor#razor-syntax).
+If you are setting up Fluent UI Web Components on a Blazor Server project, you will need to escape the `@` character by repeating it in the source link. For more information check out the [Razor Pages syntax documentation](/aspnet/core/mvc/views/razor).
 :::
 
+### Using the FluentUI Web Components
+
+With the package installed and the script configured, you can begin using the Fluent UI Web Components in the same way as any other Blazor component. Just be sure to add the following using statement to your views:
+
+```html
+@using Microsoft.Fast.Components.FluentUI
+```
+
+Here's a small example of a `FluentCard` with a `FluentButton` that uses the Fluent "Accent" appearance:
+
+```html
+@using Microsoft.Fast.Components.FluentUI
+
+<FluentCard>
+    <h2>Hello World!</h2>
+    <FluentButton Appearance="@Appearance.Accent">Click Me</FluentButton>
+</FluentCard>
+```
+
+If you are using the .NET CLI, you can run your project with the following command from the project folder:
+
+```shell
+dotnet watch run
+```
+
+Congratulations! You're now set up to use the Fluent UI Web Components with Blazor!
+
+### Configuring the Design System
+
+The Fluent UI Web Components are built on FAST's Adaptive UI technology, which enables design customization and personalization, while automatically maintaining accessibility. This is accomplished through setting various "design tokens". The easiest way to accomplish this in Blazor is to wrap the entire UI in a `FluentDesignSystemProvider`. This special element has a number of properties you can set to configure the tokens to your desired settings. Here's an example of changing the "accent base color" and switching the system into dark mode:
+
+```html
+<FluentDesignSystemProvider AccentBaseColor="#6264A7" BaseLayerLuminance="0">
+    <Router AppAssembly="@typeof(App).Assembly">
+        <Found Context="routeData">
+            <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
+        </Found>
+        <NotFound>
+            <PageTitle>Not found</PageTitle>
+            <LayoutView Layout="@typeof(MainLayout)">
+                <p role="alert">Sorry, there's nothing at this address.</p>
+            </LayoutView>
+        </NotFound>
+    </Router>
+</FluentDesignSystemProvider>
+```
+
+:::note
+Provider token attributes can be changed on-th-fly like any other Blazor component attribute.
+:::
+
+If you are attempting to configure the components for integration into a specific Microsoft product, the following table provides `AccentBaseColor` values you can use:
+
+Product | AccentBaseColor
+------- | ---------------
+| Office | #D83B01 |
+| Word | #185ABD |
+| Excel | #107C41 |
+| PowerPoint | #C43E1C |
+| Teams | #6264A7 |
+| OneNote | #7719AA |
+| SharePoint | #03787C |
+| Stream | #BC1948 |
+
+For a list of all available token attributes, [see here](https://github.com/microsoft/fast-blazor/blob/main/src/Microsoft.Fast.Components.FluentUI/Components/FluentDesignSystemProvider.razor#L69). More examples for other components can be found in the `examples` folder [of this repository](https://github.com/microsoft/fast-blazor).
+
+## Getting Started with the FAST Components
+
+The FAST team also produces a second set of components with a more configurable design system, called FAST Frame. At this time, there isn't special Blazor support for these components, but they can still be used as normal HTML. To get started using the FAST Frame, you will first need to add a CDN script for `fast-components` use the following markup:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components@2.16.0/dist/fast-components.min.js"></script>
+```
+
+The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components/dist/fast-components.min.js"></script>
+```
+
+The best place to put this is typically in your `index.html` file in the script section at the bottom of the `<body>`.
+
 If you wish to leverage NPM instead, run the following command:
 
 ```shell
@@ -49,7 +157,11 @@ node_modules/@microsoft/fast-components/dist/fast-components.min.js
 
 Copy this to your `wwwroot/script` folder and reference it with a script tag as described above.
 
-## Using the components
+:::note
+If you are setting up Fluent UI Web Components on a Blazor Server project, you will need to escape the `@` character by repeating it in the source link. For more information check out the [Razor Pages syntax documentation](/aspnet/core/mvc/views/razor).
+:::
+
+### Using the FAST Web Components
 
 With your script tag added, you can use any component in any of your views. For example, you could put something like this in your `Index.razor` file:
 
@@ -87,38 +199,4 @@ If you are using the .NET CLI, you can run your project with the following comma
 dotnet watch run
 ```
 
-Congratulations! You're now set up to use FAST with Blazor!
-
-## Using the FluentUI Web Components
-
-FAST has special Blazor support for Microsoft's FluentUI Web Components. To leverage the FluentUI Design System, you'll need to make a few modifications to your project.
-
-First, update the script tag to point to the FluentUI Web Components.
-
-```html
-<script type="module" src="https://unpkg.com/@fluentui/web-components"></script>
-```
-
-Second, change the `fast-` prefix to `fluent-` in any CSS selectors.
-
-Third, you will want to install [the official Nuget package for FluentUI](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI/). You can use the following command:
-
-```shell
-dotnet add package Microsoft.Fast.Components.FluentUI
-```
-
-With this package installed, you can switch the HTML over to Blazor components. Here's an example:
-
-```html
-@page "/"
-@using Microsoft.Fast.Components.FluentUI
-
-<FluentCard>
-  <h2>Hello World!</h2>
-  <FluentButton Appearance="@Appearance.Accent">
-    Click Me
-  </FluentButton>
-</FluentCard>
-```
-
-To report issues or provide feedback on `Microsoft.Fast.Components.FluentUI`, please visit [the microsoft/fast-blazor repository](https://github.com/microsoft/fast-blazor).
+Congratulations! You're now set up to use FAST Components with Blazor!
diff --git a/packages/web-components/fast-foundation/docs/integrations/webpack.md b/packages/web-components/fast-foundation/docs/integrations/webpack.md
@@ -80,10 +80,15 @@ Next, in the root of your project folder, add a `tsconfig.json` file to configur
 
 You can learn more about `tsconfig.json` options in [the official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
+:::note
+Do not set `useDefineForClassFields` to `true` in your `tsconfig.json` if you are using decorators. These two features conflict at present. This will be resolved in future versions of TypeScript and FAST.
+:::
+
 Next, create a `webpack.config.js` file in the root of your project folder with the following source:
 
 ```js
 const { CleanWebpackPlugin } = require("clean-webpack-plugin");
+const path = require('path');
 
 module.exports = function(env, { mode }) {
   const production = mode === 'production';
@@ -94,7 +99,8 @@ module.exports = function(env, { mode }) {
       app: ['./src/main.ts']
     },
     output: {
-      filename: 'bundle.js'
+      filename: 'bundle.js',
+      publicPath:'/'
     },
     resolve: {
       extensions: ['.ts', '.js'],
@@ -107,6 +113,9 @@ module.exports = function(env, { mode }) {
       devMiddleware: {
         writeToDisk: true,
       },
+      static: {
+        directory: path.join(__dirname, './')
+      }
     },
     plugins: [
       new CleanWebpackPlugin()

diff --git a/packages/web-components/fast-router/README.md b/packages/web-components/fast-router/README.md
@@ -36,7 +36,7 @@ A pre-bundled script that contains all APIs needed to use FAST Router and FAST E
 <html lang="en">
     <head>
         <script type="module">
-          import { FASTRouter } from "https://unpkg.com/@microsoft/fast-router";
+          import { FASTRouter } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-router/dist/fast-router.min.js";
 
           // your code here
         </script>
@@ -45,9 +45,11 @@ A pre-bundled script that contains all APIs needed to use FAST Router and FAST E
 </html>
 ```
 
-:::important
-The above CDN location points to the latest release of `fast-router`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
-:::
+The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-router@0.2.11/dist/fast-router.min.js"></script>
+```
 
 :::note
 For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
@@ -134,25 +136,21 @@ export class AppRouterConfiguration extends RouterConfiguration<RouteSettings> {
 
 ```ts
 import { FASTElement, customElement, html, css } from '@microsoft/fast-element';
-import { FASTDesignSystemProvider } from '@microsoft/fast-components';
 import { FASTRouter } from '@microsoft/fast-router';
 import { AppRouterConfiguration } from './routes';
 
-FASTDesignSystemProvider;
 FASTRouter;
 
 const template = html<MainApplication>`
-  <fast-design-system-provider>
     <fast-router :config=${x => x.routerConfiguration}></fast-router>
-  </fast-design-system-provider>
 `;
 
 const styles = css`
   :host {
     contain: content;
   }
 
-  :host, fast-design-system-provider, fast-router {  
+  :host, fast-router {  
     display: block;
     width: 100%;
     height: 100%;