Sort shorthand vs. longhand declarations — breaking change behind config (#1700)

* Sort shorthand vs. longhand declarations

* Update sorting logic for a lot more shorthands and attempt runtime sorting as well.

Concerns:
 - Runtime sorting does not work properly as we'd also need per-bucket nested sorting where `@media, :focus, border` needs to be sorted.
 - `shorthandFor` needs 40 more shorthand properties defined…

* Add all known shorthand properties, constituents, and sibling constituents.

This no longer sorts `border-top` vs. `border-block-start` as they are siblings, not a sibling of a constituent…

* Remove unused buildSourceMap function as it was breaking builds

* Minimise ./packages/react/dist/browser/runtime/style.js size increase by moving shorthandFor to @compiled/react/runtime

* Make shorthand 'sorting' more rigorous, ensuring that border-related properties are sorted deterministically

* Fix outdated bucket number

* Add tests, reduce bucket numbers

* Add docs

* Strengthen typing (thanks Kylor)

* Add changeset

* Enable in Webpack example project, and fix docs

* Address PR feedback

* Reset ordering of longhand properties because it no longer matters

---------

Co-authored-by: Grant Wong <gwong2@atlassian.com>

Author: kylorhall-atlassian

.changeset/chatty-geese-invite.md

@@ -0,0 +1,22 @@
+---
+'@compiled/babel-plugin-strip-runtime': minor
+'@compiled/parcel-optimizer': minor
+'@compiled/webpack-loader': minor
+'@compiled/react': minor
+'@compiled/utils': minor
+'@compiled/ssr-app': minor
+'@compiled/css': minor
+---
+
+Sort shorthand properties so that they come before longhand properties.
+
+When using Compiled, one of the following will happen:
+
+Option 1. If stylesheet extraction is turned off ("runtime mode"): shorthand properties will be sorted before longhand properties, as long as they are not in a pseudo-selector like `:hover` or `:active`. This is enabled by default and cannot be turned off.
+
+Option 2. If stylesheet extraction is turned on and one of the below is true:
+
+- You are using Webpack
+- You are using Parcel AND you are running in production mode
+
+... shorthand properties will only be sorted if `sortShorthand: true` is passed to `CompiledExtractPlugin` (Webpack), or `sortShorthand: true` is passed to your Compiled config file like `.compiledcssrc` (Parcel). When sorting shorthand properties using this method (option 2), shorthand properties will always be sorted before longhand properties, taking precedence over pseudo-selectors like `:hover` or `:active`.

.changeset/curvy-scissors-double.md

@@ -0,0 +1,5 @@
+---
+'@compiled/webpack-app': patch
+---
+
+Enable sortShorthand

.changeset/lucky-gorillas-wash.md

@@ -0,0 +1,5 @@
+---
+'@compiled/utils': minor
+---
+
+Remove unused buildSourceMap function

examples/webpack/webpack.config.js

@@ -11,6 +11,8 @@ const classNameCompressionMap = require('./class-name-compression-map.json');
 
 const extractCSS = process.env.EXTRACT_TO_CSS === 'true';
 
+console.log('Stylesheet extraction enabled?', extractCSS);
+
 module.exports = {
   entry: './src/index.jsx',
   mode: 'development',
@@ -62,7 +64,10 @@ module.exports = {
   },
   plugins: [
     ...(extractCSS
-      ? [new MiniCssExtractPlugin({ filename: '[name].css' }), new CompiledExtractPlugin()]
+      ? [
+          new MiniCssExtractPlugin({ filename: '[name].css' }),
+          new CompiledExtractPlugin({ sortShorthand: true }),
+        ]
       : []),
     new HtmlWebpackPlugin(),
     new webpack.HotModuleReplacementPlugin(),

package.json

@@ -144,7 +144,7 @@
     },
     {
       "path": "./packages/react/dist/browser/runtime/style.js",
-      "limit": "482B",
+      "limit": "1000B",
       "import": "CS",
       "ignore": [
         "react"

packages/babel-plugin-strip-runtime/src/index.ts

@@ -86,10 +86,13 @@ export default declare<PluginPass>((api) => {
               cssFilename
             );
             mkdirSync(dirname(cssFilePath), { recursive: true });
-            writeFileSync(
-              cssFilePath,
-              sort(this.styleRules.sort().join('\n'), this.opts.sortAtRules)
-            );
+
+            const sortConfig = {
+              sortAtRulesEnabled: this.opts.sortAtRules,
+              sortShorthandEnabled: this.opts.sortShorthand,
+            };
+
+            writeFileSync(cssFilePath, sort(this.styleRules.sort().join('\n'), sortConfig));
 
             // Add css import to file
             path.unshiftContainer(

packages/babel-plugin-strip-runtime/src/types.ts

@@ -31,6 +31,13 @@ export interface PluginOptions {
    * Defaults to `true`.
    */
   sortAtRules?: boolean;
+
+  /**
+   * Whether to sort shorthand and longhand properties,
+   * eg. `margin` before `margin-top` for enforced determinism.
+   * Defaults to `false`.
+   */
+  sortShorthand?: boolean;
 }
 
 export interface PluginPass extends OriginalPluginPass {

packages/css/package.json

@@ -35,6 +35,7 @@
   },
   "devDependencies": {
     "@types/autoprefixer": "^10.2.0",
-    "@types/cssnano": "^5.0.0"
+    "@types/cssnano": "^5.0.0",
+    "outdent": "^0.8.0"
   }
 }

packages/css/src/plugins/__tests__/sort-at-rules.test.ts

@@ -3,7 +3,9 @@ import postcss from 'postcss';
 import { sortAtomicStyleSheet } from '../sort-atomic-style-sheet';
 
 const transform = (css: string) => {
-  const result = postcss([sortAtomicStyleSheet(true)]).process(css, {
+  const result = postcss([
+    sortAtomicStyleSheet({ sortAtRulesEnabled: undefined, sortShorthandEnabled: undefined }),
+  ]).process(css, {
     from: undefined,
   });
 

packages/css/src/plugins/__tests__/sort-pseudo-selectors.test.ts

@@ -5,20 +5,23 @@ import { atomicifyRules } from '../atomicify-rules';
 import { sortAtomicStyleSheet } from '../sort-atomic-style-sheet';
 
 const transform = (css: TemplateStringsArray) => {
-  const result = postcss([sortAtomicStyleSheet(true)]).process(css[0], {
+  const result = postcss([
+    sortAtomicStyleSheet({ sortAtRulesEnabled: undefined, sortShorthandEnabled: undefined }),
+  ]).process(css[0], {
     from: undefined,
   });
 
   return result.css;
 };
 
 const transformWithAtomicClasses = (css: TemplateStringsArray) => {
-  const result = postcss([atomicifyRules(), sortAtomicStyleSheet(true), whitespace()]).process(
-    css[0],
-    {
-      from: undefined,
-    }
-  );
+  const result = postcss([
+    atomicifyRules(),
+    sortAtomicStyleSheet({ sortAtRulesEnabled: undefined, sortShorthandEnabled: undefined }),
+    whitespace(),
+  ]).process(css[0], {
+    from: undefined,
+  });
 
   return result.css;
 };