Add support for scoped versioning #877

Jahnp · 2016-12-17T20:55:25Z

Version scoping

This pull request adds support for "version-scoping" Fabric Core, which effectively wraps or "scopes" every Fabric class under a modifier of the .ms-Fabric base class, which is tied to the current version. If the version is 5.0.1, this "scope class" would take the form .ms-Fabric--v5-0-1.

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:

Risking regressions from other web parts that might be using an older version of Fabric, and
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>
    <head>
        <!-- Link to the scoped styles for the current version of Fabric Core -->
        <link rel="stylesheet" href="/fabric-5.0.1.scoped.css">
    </head>
    <body>
        <!-- Add the scoping class -->
        <div class="ms-Fabric--v5-0-1">
            <!-- 
                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.

…version info at build time. Modify core Fabric build to accommodate scoped Fabric

… gulp-changed from task since it was causing changes to not be reflected

…files. Include in scoped output

… the form ms-Fabric--v4-1-0

…c-core into jahnp/scoped-versioning # Conflicts: # src/sass/Fabric.Icons.Font.Output.scss

@font-face

- Add scoping rules back to _Icon.Mixins.scss - Split out @font-face definiton from _Icon.scss into _IconFont.scss and import where necessary.

…phy.scss and _Font.scss, respectively

… of Fabric

… typography classes into _Font.scss

mikewheaton · 2016-12-17T21:08:26Z

src/sass/Fabric.scss

 @import './Font';
 @import './Grid';
+@import './IconFont';


Maybe Icon.Definition to match the font definitions file? The word 'definition' is already bothering me but Font.Font would be far worse.

Ah yes, good catch--I'll change this. And I agree, I'd really love to stick with single-word filenames as much as possible, but not sure how else to split this out.

@mikewheaton super pedantic preference: would you prefer Definition or Definitions for the Icon file? There's technically only one definition :/ I'm inclined to use the latter for pure consistency and flexibility but don't feel strongly about it.

…face

…face definition filenames

mikewheaton · 2016-12-19T18:33:28Z

Looks really good! A couple small to-dos:

Animations (the @keyframes, not the classes) are not scoped. Do we want to scope them by appending the version number (e.g. @keyframes slideRightIn10--v5-1-0)?
We need to get the scoped icon fonts (e.g. fabricmdl2icons-5.woff2) on the CDN before this is released. I've added the waiting-to-merge label. Want me to get those onto the CDN and update our icons release process?

Jahnp · 2016-12-19T18:52:51Z

@mikewheaton Thanks for the feedback! Great points.

RE: Scoping keyframs: That's a really good point, I hadn't considered that. Since they wouldn't affect classes, the "interface" for developers wouldn't be affected either. I'll go ahead and make this change.
RE: Scoped icons on the CDN--definitely. I'll try to get to this today. I'd generally prefer waiting on CDN inclusion before merging, but since this is a new/currently-unused feature, I'm a little less concerned about that.

…eparate var.

Jahnp · 2016-12-20T22:56:20Z

@mikewheaton @micahgodbolt: Alright, I've added version scoping to @keyframes definitions and their uses within the mixins. However, I didn't change the mixin names--that seems unnecessary at this stage (and is actually impossible as of right now without re-defining versions).

My solution generates output like this:

// @keyframes definitions
@keyframes fadeIn--v5-1-0 {
  from {
    opacity: 0;
    animation-timing-function: cubic-bezier(0.1, 0.25, 0.75, 0.9);
  }

  to {
    opacity: 1;
  }
}

@keyframes slideRightIn10--v5-1-0 {
  from {
    transform: translate3d(-10px, 0px, 0px);
  }

  to {
    transform: translate3d(0px, 0px, 0px);
  }
}

// Scoped animation classes
.ms-Fabric--v5-1-0 .ms-u-slideRightIn10 {
  animation-name: fadeIn--v5-1-0, slideRightIn10--v5-1-0;
  animation-duration: 0.367s;
  animation-timing-function: cubic-bezier(0.1, 0.9, 0.2, 1);
  animation-fill-mode: both;
}

Let me know what you think of the approach. I'll get started on getting the versioned icons on the CDN next.

Also--huge thanks to @micahgodbolt for the suggestions on how to resolve, well, my variable resolution issues!

mikewheaton · 2016-12-21T01:09:02Z

Approved! 🎉 🎉 🎉

mikewheaton · 2016-12-31T20:46:07Z

Removed the 'waiting-to-merge' label, as the scoped icons for v5 are now available on the CDN.

…mment

Inline version number instead of file based

Jahnp added 18 commits October 4, 2016 22:16

Add utilities to scope core Fabric styles to the current major version

43566da

Add template for Fabric.Scoped.scss, which will consume package.json …

fbabf38

…version info at build time. Modify core Fabric build to accommodate scoped Fabric

Add temp folder to config and update .gitignore to exclude it

0bb585e

Add scoped pre-build task as dependency of Fabric-buildStyles. Remove…

052562d

… gulp-changed from task since it was causing changes to not be reflected

Scope specific Fabric Core imports

511e31b

Add scoping documentation page

898b1d7

Remove static scoped styles

650459e

Scope icon font definitions and CDN references to point to versioned …

b0d33aa

…files. Include in scoped output

Include patch version in scope class, so full scope class would be of…

66a44ed

… the form ms-Fabric--v4-1-0

Add fonts to scoped output

d227daf

Merge branch 'master' of https://github.com/OfficeDev/office-ui-fabri…

127fce3

…c-core into jahnp/scoped-versioning # Conflicts: # src/sass/Fabric.Icons.Font.Output.scss

Add ghdocs documentation for scoping

d0fa7d3

- Merge master and cleanup conflicts.

770bc52

- Add scoping rules back to _Icon.Mixins.scss - Split out @font-face definiton from _Icon.scss into _IconFont.scss and import where necessary.

Split out typography classes and Segoe @font-face rules into _Typogra…

fd1061c

…phy.scss and _Font.scss, respectively

Remove unnecessary comments

b4ae9cc

Rewrite scoping example documentation

4d34b4f

Remove unnecessary ScopingPage styles

ba136da

Remove scoping sample, since this has been documented elsewhere

51f8223

msftclas added the cla-not-required label Dec 17, 2016

Jahnp added 2 commits December 17, 2016 12:58

Update scoping sample & documentation to reflect the currrent version…

8b96464

… of Fabric

Move Segoe @font-face definitions into _Font.Definitions and move the…

9483e8e

… typography classes into _Font.scss

mikewheaton reviewed Dec 17, 2016

View reviewed changes

Jahnp added 2 commits December 17, 2016 13:15

Change _IconFont.scss to _Icon.Definitions.scss to match other @font-…

250ae72

…face definition filenames

Add _Icon.Definitions.scss

9816592

mikewheaton added the waiting-to-merge label Dec 19, 2016

Jahnp added 2 commits December 20, 2016 14:50

Prefix global scoping vars with 'ms-'. Separate scoping suffix as a s…

2e186b1

…eparate var.

Version-scope @Keyframes definitions and uses

4494dcb

mikewheaton removed the waiting-to-merge label Dec 31, 2016

Jahnp and others added 4 commits January 3, 2017 09:05

Merge branch 'master' into jahnp/scoped-versioning

e554ea0

Inline version number instead of file based

b401d7a

removed old task and templates. changed variable format and upated co…

3fc8061

…mment

Merge pull request #890 from OfficeDev/mgodbolt/scoped-versioning

fc043ac

Inline version number instead of file based

mikewheaton added this to the 6.0.0 milestone Jan 4, 2017

mikewheaton merged commit f17c069 into master Jan 4, 2017

mikewheaton deleted the jahnp/scoped-versioning branch January 4, 2017 20:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for scoped versioning #877

Add support for scoped versioning #877

Jahnp commented Dec 17, 2016

mikewheaton Dec 17, 2016

Jahnp Dec 17, 2016

Jahnp Dec 17, 2016 •

edited

mikewheaton commented Dec 19, 2016 •

edited

Jahnp commented Dec 19, 2016

Jahnp commented Dec 20, 2016 •

edited

mikewheaton commented Dec 21, 2016 •

edited by dzearing

mikewheaton commented Dec 31, 2016

Add support for scoped versioning #877

Add support for scoped versioning #877

Conversation

Jahnp commented Dec 17, 2016

Version scoping

Why is this useful?

Usage

Notes on fonts

mikewheaton Dec 17, 2016

Choose a reason for hiding this comment

Jahnp Dec 17, 2016

Choose a reason for hiding this comment

Jahnp Dec 17, 2016 • edited

Choose a reason for hiding this comment

mikewheaton commented Dec 19, 2016 • edited

Jahnp commented Dec 19, 2016

Jahnp commented Dec 20, 2016 • edited

mikewheaton commented Dec 21, 2016 • edited by dzearing

mikewheaton commented Dec 31, 2016

Jahnp Dec 17, 2016 •

edited

mikewheaton commented Dec 19, 2016 •

edited

Jahnp commented Dec 20, 2016 •

edited

mikewheaton commented Dec 21, 2016 •

edited by dzearing