Adding a dedicated merge-styles package which will replace the glamor usage.

[dzearing]

This PR adds the merge-styles package, which will, in a future PR, allow us to remove the glamor reference. Please see the README included. Also see the tests to understand usage.

I have isolated the changes so that this PR only adds a new package. It is not used in any production code yet. This will come in other PRs, but I wanted to break out smaller reviews to ensure we focus on getting the main code completed and functional.

Office UI Fabric - merge-styles

The merge-styles library provides a number of utilities for loading styles through javascript. It is designed to make it simple to style components through javascript. It generates css rules, rather than using inline styling, to ensure we can use css features like pseudo selectors (:hover) and parent/child selectors (media queries).

The library was built for speed and size; the entire package is 2.7k gzipped.

The basic idea is to provide a method which can take in one or more style objects css styling javascript objects representing the styles for a given element, and return a single class name. If the same set of styling is passed in, the same name returns and nothing is re-registered.

This has a number of benefits over traditional build time staticly produced css:

• Only register classes that are needed, when they're needed, reducing the overall selector count.

• Dynamically create new class permutations based on contextual theming requirements. (Use a different theme inside of a DIV without downloading multiple copies of the css rule definitions.)

• Use JavaScript to define the class content (using utilities like color converters, or reusing constant numbers becomes possible.)

• Allow control libraries to merge customized styling in with their rules, avoiding complexities like css selector specificity.

• Simplify RTL processing; lefts become rights in RTL, in the actual rules. No complexity like html[dir=rtl] prefixes necessary, which alleviates unexpected specificity bugs.

• Reduce bundle size. Automatically handles vendor prefixing, unit providing, RTL flipping, and margin/padding expansion (e.g. margin will automatically expand out to margin TRBL, so that we avoid specificity problems when merging things together.)

• Reduce the build time overhead of running through CSS preprocessors.

• TypeScript type safety; spell "background" wrong and get build breaks.

The api surfaces consists of TypeScript interfaces and a few important methods:

mergeStyles(..args[] - Takes in one or more style objects, merges them in the right order, and produces a single css class name which can be injected into any component.

mergeStyleSet - Takes in one or more style set objects, each consisting of a set of areas, each which will produce a class name. Using this is analogous to calling mergeStyles for each property in the object, but ensures we maintain the set ordering when multiple style sets are merged.

concatStyleSet - In some cases you simply need to combine style sets, without actually generating class names (it is costs in performance to generate class names.) This tool returns a single set merging many together.

Vocabulary

Let's clear up a few definitions before we start;

A style object represents the collection of css rules, except that the names are camelCased rather than kebab-cased. Example:

let style = {
  backgroundColor: 'red',
  left: 42
};

Additionally, style objects can contain selectors under the selectors property:

let style = {
  backgroundColor: 'red',
  selectors: {
    ':hover': {
      backgroundColor: 'blue';
    },
    '.parent &': { /* parent selector */ },
    '& .child': { /* child selector */ }
  }
};

A style set represents a map of area to style object. When building a component, you need to generate a class name for each element that requires styling. You would defint this in a style set.

let styleSet = {
  root: { background: 'red' },
  button: { margin: 42 }
}

Basic usage

When building a component, you will need a style set map of class names to inject into your elements' class attributes.

The recommended pattern is to provide the classnames in a separate function, typically in a separate file ComponentName.classNames.ts.

import { IStyle, mergeStyleSets, memoize } from '@uifabric/merge-styles';

export interface IComponentClassNames {
  root: string;
  button: string;
  buttonIcon: string;
}

export const getClassNames = () => {
  return mergeStyleSets({
    root: {
        background: 'red'
      }
    ),

    button: {
      backgroundColor: 'green',
      selectors: {
        ':hover': {
          backgroundColor: 'blue'
        }
      }
    },

    buttonIcon: {
      margin: 10
    }
  });
};

The class map can then be used in a component:

import { getClassNames } from './MyComponent.classNames';

export const MyComponent = () => {
  let { root, button, buttonIcon } = getClassNames();

  return (
    <div className={ root }>
      <button className={ button }>
        <i className={ buttonIcon } />
      </button>
    </div>
  );
};

Managing conditionals and states

Style objects can be represented by a simple object, but also can be an array of the objects. The merge functions will handle arrays and merge things together in the given order. They will also ignore falsey values, allowing you to conditionalize the results.

In the following example, the root class generated will be different depending on the isToggled state:

export const getClassNames = (
  isToggled: boolean
): IComponentClassNames => {

  return mergeStyleSet({
    root: [
      {
        background: 'red'
      },
      isToggled && {
        background: 'green'
      }
    ]
  })
};

Optimizing for performance

Resolving the class names on every render can be an unwanted expense especially in hot spots where things are rendered frequently. To optimize, we recommend 2 guidelines:

1. For your getClassNames function, flatten all input parameters into simple immutable values. This helps the memoize utility to cache the results based on the input.

2. Use the memoize function from the @uifabric/utilities package to cache the results, given a unique combination of inputs. Example:

import { memoize } from '@uifabric/utilities';

export const getClassNames = memoize((
  isToggled: boolean
) => {
  return mergeStyleSet({
    // ...
  });
});

Registering fonts

Registering font faces example:

import { fontFace } from '@uifabric/merge-styles';

fontFace({
  fontFamily: `"Segoe UI"`,
  src: `url("//cdn.com/fontface.woff2) format(woff2)`,
  fontWeight: "normal"
});

Note that in cases like fontFamily you may need to embed quotes in the string as shown above.

Registering keyframes

Registering animation keyframes example:

import { keyframes, mergeStyleSets } from '@uifabric/merge-styles';

let fadeIn = keyframes({
  "from": {
    opacity: 0
  },
  "to": {
    opacity: 1
  }
});

export const getClassNames = () => {
  return mergeStyleSets({
    root: {
      animationName: fadeIn
    }
  });
};

Server-side rendering

Example:

import { renderStatic } from '@uifabric/merge-styles/lib/server';

let { html, css } = renderStatic(() => {
  return ReactDOM.renderToString(...);
});

Caveats:

• Currently font face definitions and keyframes won't be included in the result.

[christiango]

probably worth just setting strict: true since it is a new project

[ThomasMichon]

+1

[christiango]

args.foreach()?

[cschleiden]

for (const currentSet of args) {?

[ThomasMichon]

+1 for for (const ___ of ___)

[cschleiden]

why any? can't we add displayName to the type?

[cschleiden]

nit, move this down to where it's used?

[cschleiden]

Shouldn't we use an actual type instead of the += 2 logic everywhere we touch rulePairs?
(if not, rename rules to rulePairs here?)

[cschleiden]

const

[cschleiden]

const? (Maybe enable theconst tslint rule?)

[dzearing]

I don't really agree with it. Here's why.

const is very useful for communicating and enforcing that something should not change. There are times where you do this to avoid mistakes. I look at it as a readonly property. Good usage examples are things such as constant strings at the top of a file, which are reused in a variety of places. It communicates and enforces that these aren't going to change values ever.

But most of the time, you don't care to communicate this. And it doesn't prevent bugs when enforced. It just creates noise. I don't think I've ever hit a scenario where I accidentally assigned a value to something where it wasn't anticipated.

If you have a scenario where there is a legitimate bug caught by overusing const, I'd love to hear it.

[cschleiden]

Maybe it's only because using C++ for years (const refs!), but for me it's valuable additional information, I don't actually have to read the rest of the code when I see const, I know that variable is not being reassigned. Granted, if it's a reference to an object it's less useful since the object itself might change, but for "value types" it's valuable.

Don't remember any complicated bug being caught by it, it's more like surfacing issues in badly written code, inline anonymous functions that modify variables in the closure by accident and things like that.

[ThomasMichon]

serialized.push(propName, ruleEntries[propName]);

[ThomasMichon]

I think you can use object instead of {} where you expect actual objects now.

[ThomasMichon]

Are we going to want a way to point this at a different document instance, such as an iframe.contentWindow.document?

[ThomasMichon]

Does GlobalSettings support targeting a different window or document instance?

[dzearing]

removed GlobalSettings usage. If window is unavailable i cache it in the local module.

[dzearing]

by simplifying some of the logic i'm able to bring the total size down from 3.4k to 2.7k (gzipped) so that's good.

[ThomasMichon]

object

[ThomasMichon]

const rootStyle: IStyle & {
    displayName?: string;
} = ...;

[ThomasMichon]

I would prefer it if most of these functions took a Stylesheet as a parameter rather than referring back to Stylesheet.getInstance(). It would produce a more decoupled architecture that would be easier to extend.

[dzearing]

I'm not sure on that one. Stylesheet tracks state over time, so by default it should be a singleton, but is there a use case where it would be better to pass around?

[ThomasMichon]

for (const arg of args) {
    ...

[ThomasMichon]

Would use for (const __ of ___) construct instead.

[dzearing]

[ts] Type 'Map<string, IStyle>' is not an array type or a string type.

[ThomasMichon]

+1