Style merge issues

[NicholasBoll]

tl;dr;
There have been reports that styles are not merging correctly in all cases. We'll enable compatibility mode for all style merging until we can figure out why.

Long Story

Canvas Kit Styling utilities like createStyles and createStencils work a bit differently than Emotion's styled from @emotion/styled and the css prop from @emotion/react. Both work by creating a wrapper component that handles the className prop specially. If a className prop is provided, those wrapper components will look at each class name and see if it is in the Emotion cache. If there is a class name found in the emotion cache, styles will be collected into an object containing all styles associated with the cache. When everything is done, this new style object will be hashed an a new CSS class name is generated.

For example, imaging some components are created using @emotion/styled via styled:

const ComponentA = styled('div')({
  padding: 10
});

<ComponentA />

The HTML generated will look something like this:

<style>
.css-12345 {
  padding: 10px;
}
</style>

<div class="css-12345"></div>

What does Emotion do if we call styled on another component already styled?:
const ComponentB = styled(ComponentA)({
padding: 20
});

```

The HTML generated will look something like this:

<style>
// ComponentA
.css-12345 {
  padding: 10px;
}
// ComponentB
.css-abcde {
  padding: 20px;
}
// merged styles
.css-123de {
  padding: 10px;
  padding: 20px;
}
</style>

<div class="css-123de"></div>

This looks interesting. There's a style for ComponentA, ComponentB, and one for merged styles. ComponentB renders and inserts styles into the StyleSheetList. ComponentB then renders ComponentA, passing down a className="css-abcde". ComponentA handles it's own styles and injects them into the StyleSheetList and adds to the className prop: className="css-12345 css-abcde". After this, the wrapper component processes the resulting className prop, splitting on all spaces. It will check each CSS class name against the Emotion cache, collecting all styles found in the cache, in order. In this case, it finds padding: 10 from css-12345 and padding: 20 from css-abcde and creates a new style object:

{
  padding: 10,
  padding: 20
}

It creates a new CSS class name and injects it into the StyleSheetList. It removes all CSS class names on the className prop that were found in the cache and adds the new CSS class name to it instead. The className prop now looks like className="css-123de".

New Styling

The createStyles and createStencil work differently by using the browser's built in style merging using CSS specificity. In the previous example using createStyles instead:

const componentCStyles = createStyles({
  padding: 10
});

const ComponentDStyles = createStyles({
  padding: 20
})

// combining manually:
<div className={`${componentCStyles} ${componentDStyles}`} />

// using `handleCsProp`
const ComponentC = ({as: Element, ...elemProps}) => <Element {...handleCsProp(elemProps, componentCStyles)} />
const ComponentD = elemProps => <ComponentC as="div" {...elemProps} cs={componentDStyles} />

The HTML looks like:

<style>
// ComponentC
.css-12345 {
  padding: 10px;
}
// ComponentD
.css-abcde {
  padding: 20px;
}
</style>

<div class="css-12345 css-abcde"></div>

Notice handleCsProp adds class names together without merging them together. If componentCStyles are inserted before componentDStyles, the latter has a higher specificity because it is defined last.

Compatibility Mode

createStyles and createStencil rely on styles being defined in the right order because the solution depends on CSS specificity. Emotion cannot predict style insertion order, so new CSS classes are always created when merging styles together. So, what happens when you combine a component using createStyles and one using styled?

// styled component wrapper around createStyles
const ComponentF = styled(ComponentC)({
  padding: 20
})

// createStyles wrapper around a `styled` component

const componentGStyles = createStyles({
  padding: 20
})
const ComponentG = (elemProps) => {
  return <ComponentA {...handleCsProp(elemProps, componentGStyles} />
}

The styled wrapper is controlled by the styled component wrapper. Since createStyles uses the same Emotion cache, the style wrapper will merge styles the way Emotion always does.

In the ComponentG, handleCsProp is doing a bit of magic. It tracks styles added by all createStyles calls in a cache. It will also check the Emotion cache against every CSS class name found against Emotion's cache negating any CSS class names found in the createStyles cache. If there's a hit, it will call the same style merging Emotion does.

The Problem

createStyles and createStencil rely on the browser's CSS specificity for style merging and by extension, rely on styles being inserted in the correct order. Styles are inserted as soon as createStyles or createStencil are called, making them execution-order dependent. If you declare styles in the same file, it means you MUST define them in the order you expect styles to merge, top to bottom where bottom-most styles will override previous styles. If you use createStencil, the function makes sure base styles are executed before modifiers and, lastly, compoundModifiers. modifiers and compoundModifiers will be executed in order as defined in your source file.

But, sometimes modules can be out-of-order. A simple example is when using async imports:

import {createStyles} from '@workday/canvas-kit-styling';

// styles are inserted before `PrimaryButton` is even imported and evaluated by the browser
const myStyles = createStyles({
  padding: 10,
});

import('@workday/canvas-kit-react/button').then(({PrimaryButton}) => {
  const MyComponent = () => {
    <PrimaryButton cs={myStyles} />
  }
})

In this example, we declare myStyles at the top level, but import the PrimaryButton inside the then callback. This is an asynchronous import and will execute styles out of order. First myStyles, then PrimaryButton styles. This can result in incorrect style merging. In this example, you should define your styles at the same level as your component:

import {createStyles} from '@workday/canvas-kit-styling';

import('@workday/canvas-kit-react/button').then(({PrimaryButton}) => {
  // defined at the same level as the component
  const myStyles = createStyles({
    padding: 10,
  });

  const MyComponent = () => {
    <PrimaryButton cs={myStyles} />
  }
})

This is a known limitation of our styling solution.

There have also been reports that styles are merging incorrectly even outside this known use-case. Technically, inserting styles into the StyleSheetList as part of the JavaScript evaluation phase is a side effect. There are examples of JS modules being evaluated out-of-order that we don't fully understand. Until we can understand all cases of out-of-order evaluation and find a work-around, the safest and easiest option is to enable the combability mode at all times.

The upside is styles will merge the same way as expected using the same merging technique Emotion uses. The downside is Emotion's solution for style merging has a runtime cost. Static style merging has the benefit of a near zero runtime cost. Compatibility mode has the same performance profile as Emotion. But we'd rather be accurate than fast and broken. We'll enable static styling again in the future once we can guarantee styles always merge correctly in static styling mode.

[NicholasBoll]

I think I might have thought of a reason why Canvas Kit styles may be merging out of order in non-compat mode...
Imagine Card and MenuCard both have their own styles:

const cardStyles = createStyles({
  padding: 10
})

const menuCardStyles = createStyles({
  padding: 20
})

<div className={[cardStyles, menuCardStyles].join(' ')} />

The result will be 20px padding because menuCardStyles is declared after cardStyles. At runtime, each createStyles call creates a brand new cache key to prevent incorrect style merging. We ran into that with Buttons where BaseButton had a style block that was the same as TertiaryButton. Using the hash meant TertiaryButton's modifier didn't insert into the StyleSheetList and styles merged incorrectly.

But there's an optimization that happens to make sure we don't inject endless amounts of styles into the browser's StyleSheetList with all the versions of Canvas Kit that get bundled. We use Emotion's cache key based on the style's hash when we build.
What does this mean? If CK 10.3.4 and 10.3.5 are both loaded in the page, Emotion's cache insert function will not load the second one because the hashes are the same.
BUT, what happens if we change cardStyles and not menuCardStyles in a release? A new hash will be created. This could mean 10.3.4 inserts cardStyles and menuCardStyles. 10.3.5 inserts cardStyles, but not menuCardStyles because the cache key is the same as before. This now means that 10.3.5 will show padding: 10px instead of padding: 20px because cardStyles is now inserted out-of-order.

Here's a link to a reproduction where I simulate the build object the style transformer does in our build step (this isn't a dev issue, just a production build issue): https://stackblitz.com/edit/style-merge-failure-clufwt?file=src%2FApp.tsx

To fix this, we have a few options:

1. Leave compat mode on
   This is the easiest option, but not great as it doesn’t have all the benefits of switching to a static styling solution in the first place. It should still get an advantage of pre-compiling non-merged styles and reducing chances of styles changing between renders due to the use of CSS variables, but changing modifiers would still cause new styles
2. Force the styling transpiler to create unique cache keys for every single build
   This option trades the runtime cost of serializing, hashing, and injecting styles during the render cycle of React for the runtime cost of the browser having more style rules. If one version of Canvas Kit has 100 selectors and there are 10 versions of Canvas Kit on the page, there will be 1,000 selectors from CK alone. Compat mode will make sure there’s only one selector per hash (per cache. I can see the same hash in a page more than once now, so this might be moot)
3. Write our own style injection library based on Emotion’s cache with a custom StyleSheet library that can handle insertion reordering. We’d use Emotion’s cache system so that compat mode still works (always important), but Emotion doesn’t handle custom insertion order. We’d need to create insertion keys to help track insertion order for edge cases where the same insertion key is encountered. Insertion order is important. My code sandbox reproduction proves it.