Merge pull request SharePoint#6692 from andrewconnell/updateFabricStylesDocs

Migrate CSS change from wiki to docs

Author: andrewconnell

docs/spfx/office-ui-fabric-integration.md

@@ -1,7 +1,7 @@
 ---
 title: Using Office UI Fabric Core and Fabric React in SharePoint Framework
 description: Information about the Fabric Core and Fabric React packages, and challenges with using CSS.
-ms.date: 05/13/2019
+ms.date: 02/09/2021
 ms.prod: sharepoint
 localization_priority: Priority
 ---
@@ -14,36 +14,38 @@ Microsoft uses Fabric Core and Fabric React in SharePoint. Microsoft regularly p
 
 The challenge with Global CSS styles is explained in the following presentation within the context of React and JavaScript: [React CSS in JS](https://speakerdeck.com/vjeux/react-css-in-js).
 
-To achieve reliability, one of the main problems we need to solve is that of **Global CSS styles**. This accounts to not using global class names in the HTML markup and instead using Fabric Core mixins and variables in the Sass declaration file. This involves importing the Fabric Core's Sass declarations in your Sass file and then consuming the variables and mixins appropriately. 
+To achieve reliability, one of the main problems we need to solve is that of **Global CSS styles**. This accounts to not using global class names in the HTML markup and instead using Fabric Core mixins and variables in the Sass declaration file. This involves importing the Fabric Core's Sass declarations in your Sass file and then consuming the variables and mixins appropriately.
 
 ## Goals
 
-The goal of the SharePoint Framework is to allow both Microsoft and customers to build rich, beautiful, and consistent user experiences on top of SharePoint. 
+The goal of the SharePoint Framework is to allow both Microsoft and customers to build rich, beautiful, and consistent user experiences on top of SharePoint.
 
 In accordance with these goals, following are the key design principles:
 
-* Customers should be able to smoothly and reliably consume Fabric Core and Fabric React in their solutions.
-* Microsoft will roll out updated experiences that consume updated versions of Fabric Core and Fabric React in SharePoint without conflicting with customer's solutions.
-* Customers can customize and override the default styles, designs, and components to tailor the solution's needs.
+- Customers should be able to smoothly and reliably consume Fabric Core and Fabric React in their solutions.
+- Microsoft will roll out updated experiences that consume updated versions of Fabric Core and Fabric React in SharePoint without conflicting with customer's solutions.
+- Customers can customize and override the default styles, designs, and components to tailor the solution's needs.
 
 There are two parts of the Office UI Fabric that are available for use by developers:
 
-* [Office UI Fabric Core](https://developer.microsoft.com/fabric). A set of core styles, typography, a responsive grid, animations, icons, and other fundamental building blocks of the overall design language.
+- [Office UI Fabric Core](https://developer.microsoft.com/fabric). A set of core styles, typography, a responsive grid, animations, icons, and other fundamental building blocks of the overall design language.
 
-* [Office UI Fabric React](https://developer.microsoft.com/fabric#/components). A set of React components built on top of the Fabric design language for use in React-based projects.
+- [Office UI Fabric React](https://developer.microsoft.com/fabric#/components). A set of React components built on top of the Fabric design language for use in React-based projects.
 
 ## Office UI Fabric Core package
 
-The SharePoint Framework Fabric Core npm package **([@microsoft/sp-office-ui-fabric-core](https://www.npmjs.com/package/@microsoft/sp-office-ui-fabric-core))** contains a subset of supported Fabric Core styles that can be safely consumed within a SharePoint Framework component. 
+The SharePoint Framework Fabric Core npm package **([@microsoft/sp-office-ui-fabric-core](https://www.npmjs.com/package/@microsoft/sp-office-ui-fabric-core))** contains a subset of supported Fabric Core styles that can be safely consumed within a SharePoint Framework component.
 
 The following core styles are supported in the package:
+
 - Typography
 - Layouts
 - Colors
 - Themes
 - Localization
 
 The following are not yet supported in the package:
+
 - Animations
 - Icons
 
@@ -53,41 +55,39 @@ Starting with the SharePoint Framework Yeoman generator version 1.3.4, the defau
 
 To use the Fabric Core package in your existing project, install the package as a dependency:
 
-```
+```console
 npm install @microsoft/sp-office-ui-fabric-core --save
 ```
 
-After it's installed, you can then import the Fabric Core Sass declarations in your Sass definition file and use the mixins and variables as described in the following section. 
+After it's installed, you can then import the Fabric Core Sass declarations in your Sass definition file and use the mixins and variables as described in the following section.
 
 ### Use Fabric Core styles
 
 To use the Fabric Core styles, you need to import the `SPFabricCore` declarations into your Sass file.
 
-> [!NOTE] 
+> [!NOTE]
 > Make sure you have the **\@microsoft/sp-office-ui-fabric-core** npm package installed.
 
 ```css
 @import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';
 ```
 
-<br/>
-
 Now you can use the core styles as mixins and variables.
 
 ```css
 .row {
-    @include ms-Grid-row;
-    @include ms-fontColor-white;
-    background-color: $ms-color-themeDark;
-    padding: 20px;
-  }
- ``` 
+  @include ms-Grid-row;
+  @include ms-fontColor-white;
+  background-color: $ms-color-themeDark;
+  padding: 20px;
+}
+ ```
 
 ## Office UI Fabric React
 
 We recommend that you use the versions of the Office UI Fabric React package included in the project in the SharePoint Framework's Yeoman generator. For instance, the SharePoint Framework v1.7.0 release uses Fabric React v5.131.0
 
-> [!NOTE] 
+> [!NOTE]
 > Fabric React versions 2.x or older are not supported in SharePoint Framework.
 
 After the Fabric React package is installed, you can import the required components from the Fabric React bundle.
@@ -110,7 +110,7 @@ The Fabric React package includes the supported Fabric Core styles used in the F
 
 Because the **\@microsoft/sp-office-ui-fabric-core** package is already installed in your solution by the Yeoman generator, we recommend that you uninstall that package if you decide to use Fabric components and reduce your component bundle size.
 
-```
+```console
 npm uninstall @microsoft/sp-office-ui-fabric-core --save
 ```
 
@@ -124,29 +124,29 @@ You can then import the core styles from the Sass declarations available in the
 
 Fabric components in your solution are locked to the specific version of Fabric React that you installed. You need to update the Fabric React package to get any new components if they are available in a newer package version. Because the Fabric components are included in the component bundle, it may increase the size of your component bundle. However, this approach is the only approach that is officially supported when Office UI Fabric React is being used in SharePoint Framework solutions.
 
-
 ## The CSS challenge with Office UI Fabric
 
-The following concepts and references provide insights on the challenge with using Office UI Fabric in the context of client-side web parts. 
+The following concepts and references provide insights on the challenge with using Office UI Fabric in the context of client-side web parts.
 
 ### Global CSS styles
 
 How to avoid Global CSS styles at all costs is a big problem. Today, both Fabric Core and Fabric React have global styles. A lack of any native solutions from the browser to manage the style scoping makes this a very difficult problem.
-  
-  - [Scope CSS](https://developer.mozilla.org/docs/Web/CSS/:scope) is in early stages of discussion.
-  - iframes are not a good option to isolate styles.
-  - [Web Components](https://developer.mozilla.org/docs/Web/Web_Components) is another standard that talks about scoped styles but is still in the discussion stage.
-  - [The React: CSS in JS](https://speakerdeck.com/vjeux/react-css-in-js) discussion explains the problem well. 
-  
+
+- [Scope CSS](https://developer.mozilla.org/docs/Web/CSS/:scope) is in early stages of discussion.
+- iframes are not a good option to isolate styles.
+- [Web Components](https://developer.mozilla.org/docs/Web/Web_Components) is another standard that talks about scoped styles but is still in the discussion stage.
+- [The React: CSS in JS](https://speakerdeck.com/vjeux/react-css-in-js) discussion explains the problem well.
+
 There is plenty of other documentation on the web about the solutions to the global namespace menace.
 
 ### CSS specificity
 
 How [CSS specificity](https://developer.mozilla.org/docs/Web/CSS/Specificity) applies to web UI. Higher specificity styles override lower specificity styles, but the key thing to understand is how the specificity rules apply. In general, the precedence order from highest to lowest is as follows:
-  - The style attribute (for example, `style="background:red;"`)
-  - ID selectors (`#myDiv { }`)
-  - Class selectors (`.myCssClass{}`), attribute selectors (`[type="radio"]`), and pseudo-classes (`:hover`)
-  - Type selectors (`h1`)
+
+- The style attribute (for example, `style="background:red;"`)
+- ID selectors (`#myDiv { }`)
+- Class selectors (`.myCssClass{}`), attribute selectors (`[type="radio"]`), and pseudo-classes (`:hover`)
+- Type selectors (`h1`)
 
 **Loading order**. If two classes are applied on an element and have the same specificity, the class that is loaded later takes precedence. As shown in the following code, the button appears red. If the order of the style tags is changed, the button appears green. This is an important concept, and if not used correctly, the user experience can become load order-dependent (that is, inconsistent).
 
@@ -176,7 +176,7 @@ The web part div would be assigned this scope, that is `<div data-sp-webpart cla
 
 The rest of the page would contain unscoped Office UI Fabric Core styles. This way, as per CSS specificity rules, the scoped CSS would take precedence within the web part div. The web part and its contents would align to the specific version of the Office UI Fabric Core that the developer had chosen.
 
-*Overriding* Fabric Core styles would not be supported.  
+*Overriding* Fabric Core styles would not be supported.
 
 ```javascript
 // Sample of how the scoping would work.
@@ -203,7 +203,7 @@ After analyzing this strategy for a while, it was decided that the descendant se
 
 #### Lack of reliable nesting support
 
-This approach only works if the Microsoft user experience (that is, page and first-party web parts) use an unscoped version of the Office UI Fabric Core such as `ms-Icon--List`, while the third-party web parts only use scoped Office UI Fabric Core CSS as explained earlier. 
+This approach only works if the Microsoft user experience (that is, page and first-party web parts) use an unscoped version of the Office UI Fabric Core such as `ms-Icon--List`, while the third-party web parts only use scoped Office UI Fabric Core CSS as explained earlier.
 
 The reason being that the specificity of the scoped CSS applied on the web part overrides the unscoped CSS on the page. Keep in mind, as explained earlier, that if CSS specificity of the two classes is the same, their loading order plays a role in how the CSS classes are applied. The class that loads later takes precedence. Hence, the higher specificity of the scoped CSS is important in getting a consistent experience.
 
@@ -218,8 +218,6 @@ Furthermore, multiple extensions, one contained in the other, cannot use differe
 </div>
 ```
 
-<br/>
-
 Here's a more simplistic sample demonstrating the challenge:
 
 ```HTML
@@ -261,7 +259,7 @@ Here's a more simplistic sample demonstrating the challenge:
       <br/>
       <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
       All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
-      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span> 
+      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
       <div class='scope1'>
         <button class='myButton'</button>
         <div class='scope2'>
@@ -279,17 +277,33 @@ Here's a more simplistic sample demonstrating the challenge:
 
 #### Leakage from unscoped classes
 
-There is another problem with descendant selectors. Note in the previous example that the height and the width styles from the unscoped myButton class are applied to all the buttons. This implies that a change in that style could inadvertently break HTML by using scoped markup. 
+There is another problem with descendant selectors. Note in the previous example that the height and the width styles from the unscoped myButton class are applied to all the buttons. This implies that a change in that style could inadvertently break HTML by using scoped markup.
 
 Say for example, for some reason at the app level we decide to make height 0 px on the myButton class. That results in all third-party web parts that use the myButton class to have a height of 0 px (that is, a serious regression in the user experience).
 
+## Safely use legacy Office UI Fabric Styles (after SPFx v1.8.2)
+
+> [!IMPORTANT]
+> The following guidance applies to SharePoint Framework >= 1.8.2
+
+Ensure that the webpart manifest demands legacy Fabric core styles be loaded onto the page. This is done by specifying `loadLegacyFabricCss: true` in the solution manifest.
+
+Prior to the release of SPFx v1.8.2, a host page bug was present where legacy Fabric core styles were loaded unscoped. Therefore, if another solution demanded the styles, then all other solutions on the page were able to use them. This led to solutions working "by chance" when not rendered in isolation.
+
+To address this bug, the styles were scoped to `.ms-SPLegacyFabricBlock` class and applied to SPFx solutions that demand the Fabric core stylesheet be loaded. To provide a migration path for solutions reliant on the side-effect above, the `.ms-SPLegacyFabricBlock` class is applied to all `<div>`'s exposed to third-party solutions. During that time, modify the solution(s) impacted to declare the dependency on legacy Fabric core styles.
+
+> [!IMPORTANT]
+> Eventually the explicit reference to `.ms-SPLegacyFabricBlock` **will be removed** from the DOM for solutions that don't declare their dependency. This change will be broadly communicated via existing channels prior to removing this class.
+
+In the event of a solution that is running in DOM elements that are not provided by the SPFx (*which is generally unsupported*), you'll need to apply the `.ms-SPLegacyFabricBlock` class yourself.
+
 ## Usage of the Office UI Fabric icons in SPFx components
 
-There are changes on how to use Office UI Fabric icons in the rendering of the SharePoint Framework solutions starting from the SharePoint Framework version 1.8.2.
+There are changes on how to use Office UI Fabric icons in the rendering of the SharePoint Framework solutions starting from the SharePoint Framework v1.8.2.
 
 ### Legacy way of using icons (before SPFx 1.8.2)
 
-```HTML
+```html
 <i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>
 ```
 
@@ -301,9 +315,9 @@ Solutions build with *no JavaScript framework* option.
 1. Make code changes similar to below code, to get the required icon into your code:
 
 ```typescript
-  import { getIconClassName } from '@uifabric/styling';
+import { getIconClassName } from '@uifabric/styling';
 
-  return `<i class="${getIconClassName('Mail')}" />`;
+return `<i class="${getIconClassName('Mail')}" />`;
 ```
 
 Solutions build with *React* option or by using *React* in general.
@@ -312,9 +326,9 @@ Solutions build with *React* option or by using *React* in general.
 2. Make code changes similar to below code, to get the required icon into your code:
 
 ```typescript
-  import { Icon } from 'office-ui-fabric-react/lib/Icon';
+import { Icon } from 'office-ui-fabric-react/lib/Icon';
 
-  <Icon iconName='Mail' />
+<Icon iconName='Mail' />
 ```
 
 ## See also

docs/spfx/release-1.8.2.md

@@ -1,7 +1,7 @@
 ---
 title: SharePoint Framework v1.8.2 release notes
 description: Release notes for the SharePoint Framework v1.8.2 release
-ms.date: 07/03/2020
+ms.date: 02/09/2021
 ms.prod: sharepoint
 localization_priority: Priority
 ---
@@ -42,7 +42,8 @@ This is a minor patch release that mostly focuses on build and tooling issues, w
 - For the React-scaffolded projects, we now explicitly add **office-ui-fabric-react** (OUIFR) v6 to **package.json**.  We were finding a common pattern where people weren't adding OUIFR to **package.json**, but were using it.
   - OUIFR would end up in the **node_modules** folder because of downstream dependencies. While the solution would compile, it could cause issues in the future such as when the solution was upgraded to use a different version of the framework. In this case, a different version of OUIFR would get used.
   - In general, using packages in this pattern (*via shadow dependencies*) is a bad thing.  You're more than welcome to remove the reference in **package.json** if you aren't using OUIFR in your solution, or change the version if needed.  We also updated the type declarations for the React packages to match the versions of React / React DOM referenced in the release.
-- Support for [Node.js 10](https://nodejs.org/).  Node.js v8 is still supported, but will be removed in a future release.
+- Added `.ms-SPLegacyFabricBlock` CSS class to SPFx solutions that load the Office UI Fabric core stylesheets on demand (*see [Safely use legacy Office UI Fabric Styles (after SPFx v1.8.2)](office-ui-fabric-integration.md#safely-use-legacy-office-ui-fabric-styles-after-spfx-v182) for more detail*)
+- Support for [Node.js 10](https://nodejs.org/). Node.js v8 is still supported, but will be removed in a future release.
 
 ### Updates added to SharePoint Online