Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #877 from OfficeDev/jahnp/scoped-versioning
Add support for scoped versioning
- Loading branch information
Showing
17 changed files
with
385 additions
and
168 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,6 +11,7 @@ npm-debug.log | |
| *.sublime-workspace | ||
| docs.css | ||
| dist | ||
| temp | ||
|
|
||
| # Docs files | ||
| docs/app | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Version scoping | ||
| "Version-scoping" is a variation of Fabric Core which provides a wrapped or "scoped" version of every Fabric class under a modifier of the `.ms-Fabric` base class, which is tied to the current version. If the version is `5.1.0`, this "scope class" would take the form `.ms-Fabric--v5-1-0`. | ||
|
|
||
| ## Why is this useful? | ||
| Version scoping is targeted at the scenario where multiple versions of Fabric Core may live on a single web page, whose differences between major versions could potentially introduce regressions or conflicts. | ||
|
|
||
| A practical example of this is the SharePoint Web Parts used for publishing articles. Web Parts are effectively miniature applications, each of which can depend on their own version of Fabric. To ensure that they can continue to exist on the same publishing page without: | ||
| 1. Risking regressions from other web parts that might be using an older version of Fabric, and | ||
| 2. Forcing them to consume the latest (which would likely require work to update), | ||
|
|
||
| the Web Part developer can scope the Fabric styles for their entire Web Part to the particular version that was used during development. | ||
|
|
||
| ## Usage | ||
| Usage of version scoping is straightforward. Simply append the "versioned class" to the container element you wish to scope, then use Fabric Core classes as you normally would. | ||
|
|
||
| Here's a minimal HTML page demonstrating this: | ||
|
|
||
| ```html | ||
| <html> | ||
| <head> | ||
| <!-- Link to the scoped styles for the current version of Fabric Core --> | ||
| <link rel="stylesheet" href="/fabric-5.1.0.scoped.css"> | ||
| </head> | ||
| <body> | ||
| <!-- Add the scoping class --> | ||
| <div class="ms-Fabric--v5-1-0"> | ||
| <!-- | ||
| Use Fabric as usual. These styles will be unaffected | ||
| by other versions of Fabric. They also cannot be used | ||
| outside of a scoped class. | ||
| --> | ||
| <h1 class="ms-font-su">Some scoped title <i class="ms-Icon ms-Icon--Info"></i></h1> | ||
| </div> | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| ## Notes on fonts | ||
| Icon `@font-face` definitions (including the `font-family` name) and their font files are only scoped to **major versions** of Fabric. What this means is that all of the normal, additive changes to icon font files that occur within a major version's lifetime will be applied to a single font file, rather than maintaining separate font files for each minor or patch release. What this means is that there will not be `fabricmdl2icons-5.1.0.ttf`, `fabricmdl2icons-5.2.0.ttf`, etc. There will simply be `fabricmdl2icons-5.ttf`. | ||
|
|
||
| This is because generally icon font changes are purely additive, and rarely change significantly even between minor versions. However, the CSS classes for those icons (e.g. `ms-Icon--X`) *are* version scoped like normal classes. Also, note that the "unscoped" version of the icon font file as used today will still be available. | ||
|
|
||
| Finally, the standard, "unscoped" `@font-face` definitions to the Segoe UI webfonts are included in scoped Fabric unchanged. These fonts almost never change appreciably and are not considered risky to depend on between major releases. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| @@include('../../templates/modules/components/DocumentationPageHeader.html') | ||
| <style> | ||
| .ms-Fabric--v5-1-0 .ms-fontColor-themePrimary { | ||
| color: #ff0000; | ||
| } | ||
| </style> | ||
|
|
||
| <div class="docs-Styles-section" id="scoping"> | ||
| <h2>Version Scoping Sample</h2> | ||
| <p>For scenarios where multiple major versions may live in the same DOM, Fabric provides a "scoped" version of all Core styles that will only apply those styles when used under a versioned wrapper class.</p> | ||
|
|
||
| <p> | ||
| To use scoped Fabric styles, simply add the versioned wrapper class to the parent DOM element you wish to scope, then use Fabric as usual. | ||
| </p> | ||
|
|
||
| <p>For example, take this following title, which uses unscoped Fabric:</p> | ||
|
|
||
| <pre><code> | ||
| <div class="ms-font-xxl ms-fontColor-themePrimary">This title uses ms-fontColor-themePrimary from unscoped Fabric.</div> | ||
| </code></pre> | ||
|
|
||
| <div class="ms-font-xxl ms-fontColor-themePrimary">This title uses ms-fontColor-themePrimary from unscoped Fabric.</div> | ||
|
|
||
| <p>To scope this title to v5.1.0, add an extra wrapper <code>div</code> around it and add both the <code>ms-Fabric</code> wrapper class and the scoping class for the current version of Fabric. Note that to illustrate this behavior for this demonstration, <code>.ms-fontColor-themePrimary</code> has been overridden with a different color when used under the <code>ms-Fabric--v5-1-0</code> version-scoping class.</p> | ||
|
|
||
| <pre><code> | ||
| <div class="ms-Fabric ms-Fabric--v5-1-0"> | ||
| <div class="ms-font-xxl ms-fontColor-themePrimary">This title uses ms-fontColor-themePrimary from Fabric 5.1.0.</div> | ||
| </div> | ||
| </code></pre> | ||
|
|
||
| <div class="ms-Fabric ms-Fabric--v5-1-0"> | ||
| <div class="ms-font-xxl ms-fontColor-themePrimary">This title uses ms-fontColor-themePrimary from Fabric 5.1.0.</div> | ||
| </div> | ||
| </div> | ||
| @@include('../../templates/modules/components/DocumentationPageFooter.html') |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| // Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE in the project root for license information. | ||
|
|
||
| // | ||
| // Office UI Fabric | ||
| // Core styles scoped to the current major version of Fabric | ||
|
|
||
| // Variable is set during gulp task as comma seperated list. i.e. 5,1,0 | ||
| $ms-fabric-version: <%= fabricVersion %>; | ||
|
|
||
| @import './References'; | ||
| @import './mixins/ScopedStyles.Mixins'; | ||
|
|
||
| // Sets a global flag to enable scoped styles within certain files | ||
| $do-scope-styles: true; | ||
|
|
||
| // Scope all core styles under a helper class for the current major version. | ||
| // This produces styles of the form .ms-Fabric-{version #} .ms-font-m. | ||
|
|
||
| @include scope-fabric { | ||
| @import './Animation'; | ||
| @import './BrandIcon'; | ||
| @import './Color'; | ||
| @import './Font'; | ||
| @import './Grid'; | ||
| @import './Icon'; | ||
| @import './Responsive'; | ||
| @import './Utility'; | ||
| @import './Wrapper'; | ||
| } | ||
|
|
||
| // @font-face definitions do not need to be scoped | ||
| @import './Font.Definitions'; | ||
| @import './Icon.Definitions'; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| // Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE in the project root for license information. | ||
|
|
||
| // | ||
| // Office UI Fabric | ||
| // -------------------------------------------------- | ||
| // @font-face rules for Segoe UI | ||
|
|
||
| // Additional @font-face rules for the Leelawadee font. | ||
| @font-face { | ||
| font-family: 'Leelawadee UI'; | ||
| src: local('Leelawadee UI Bold'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-bold.woff2') format('woff2'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-bold.woff') format('woff'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-bold.ttf') format('truetype'); | ||
| font-weight: 600; | ||
| font-style: normal; | ||
| } | ||
|
|
||
| @font-face { | ||
| font-family: 'Leelawadee UI'; | ||
| src: local('Leelawadee UI Regular'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-regular.woff2') format('woff2'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-regular.woff') format('woff'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-regular.ttf') format('truetype'); | ||
| font-weight: 400; | ||
| font-style: normal; | ||
| } | ||
|
|
||
| @font-face { | ||
| font-family: 'Leelawadee UI'; | ||
| src: local('Leelawadee UI Semilight'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-semilight.woff2') format('woff2'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-semilight.woff') format('woff'), | ||
| url('#{$ms-font-directory}/leelawadeeui-thai/leelawadeeui-semilight.ttf') format('truetype'); | ||
| font-weight: 300; | ||
| font-style: normal; | ||
| } | ||
|
|
||
| // Output the standard fonts | ||
| @include SegoeUIWestEuropeanLight; | ||
| @include SegoeUIWestEuropeanRegular; | ||
| @include SegoeUIWestEuropeanSemibold; | ||
| @include SegoeUIWestEuropeanSemilight; | ||
|
|
||
| // Mixins to generate language-specific font faces. | ||
| @include SegoeUIArabicLight; | ||
| @include SegoeUIArabicRegular; | ||
| @include SegoeUIArabicSemibold; | ||
| @include SegoeUIArabicSemilight; | ||
|
|
||
| @include SegoeUICyrillicLight; | ||
| @include SegoeUICyrillicRegular; | ||
| @include SegoeUICyrillicSemibold; | ||
| @include SegoeUICyrillicSemilight; | ||
|
|
||
| @include SegoeUIEastEuropeanLight; | ||
| @include SegoeUIEastEuropeanRegular; | ||
| @include SegoeUIEastEuropeanSemibold; | ||
| @include SegoeUIEastEuropeanSemilight; | ||
|
|
||
| @include SegoeUIGreekLight; | ||
| @include SegoeUIGreekRegular; | ||
| @include SegoeUIGreekSemibold; | ||
| @include SegoeUIGreekSemilight; | ||
|
|
||
| @include SegoeUIHebrewLight; | ||
| @include SegoeUIHebrewRegular; | ||
| @include SegoeUIHebrewSemibold; | ||
| @include SegoeUIHebrewSemilight; | ||
|
|
||
| @include SegoeUIVietnameseLight; | ||
| @include SegoeUIVietnameseRegular; | ||
| @include SegoeUIVietnameseSemibold; | ||
| @include SegoeUIVietnameseSemilight; | ||
|
|
||
| // Generate the override classes for non-distributed fonts. | ||
| @include language-override-system-fonts(jpn, $ms-font-stack-japanese); | ||
| @include language-override-system-fonts(kor, $ms-font-stack-korean); | ||
| @include language-override-system-fonts(cmn, $ms-font-stack-chinese-simplified); | ||
| @include language-override-system-fonts(yue, $ms-font-stack-chinese-traditional); | ||
| @include language-override-system-fonts(hin, $ms-font-stack-hindi); | ||
|
|
||
| // Generate the override classes for web fonts. | ||
| // Thai (Leelawadee) | ||
| // tha | ||
| @include language-override-system-fonts(tha, $ms-font-stack-leelawadee); | ||
|
|
||
| // Arabic | ||
| // ara | ||
| @include language-override-system-fonts(ara, $ms-font-stack-arabic); | ||
|
|
||
| // East European | ||
| // ces, et, hrv, hun, lit, pl, lat, tur, slk, kaz | ||
| @include language-override-system-fonts(ces, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(est, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(hrv, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(hun, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(kaz, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(lav, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(lit, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(pol, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(slk, $ms-font-stack-eastEuropean); | ||
| @include language-override-system-fonts(tur, $ms-font-stack-eastEuropean); | ||
|
|
||
| // Cyrillic | ||
| // rus | ||
| @include language-override-system-fonts(rus, $ms-font-stack-cyrillic); | ||
|
|
||
| // Greek | ||
| // ell | ||
| @include language-override-system-fonts(ell, $ms-font-stack-greek); | ||
|
|
||
| // Hebrew | ||
| // heb | ||
| @include language-override-system-fonts(heb, $ms-font-stack-hebrew); | ||
|
|
||
| // Vietnamese | ||
| // vie | ||
| @include language-override-system-fonts(vie, $ms-font-stack-vietnamese); |
Oops, something went wrong.