[Feature] Sort variants by variantOrder when unstable_stack is true

[anuraghazra]

The Problem

While building our component library we faced this issue #1951 but after trying out every solution with tailwind-override and tailwind-cascade they did not fit our needs.

Then we found this solution which worked like a charm #1446 (comment) which basically suggests to create a custom base: variant to handle the specificity issue.

See `base:` plugin code

plugin(function ({ addVariant, e }) {
  addVariant(
    "base",
    ({ container, separator, modifySelectors }) => {
      modifySelectors(({ selector }) => {
        return buildSelectorVariant(
          selector,
          "base",
          separator,
          (message) => {
            throw container.error(message);
          }
        );
      });
    },
    { unstable_stack: false } // hi
  );
}),

Now we want our variants to stack on top of other variants so we added the unstable_stack option in addVariant
Normally when unstable_stack is false
variantOrder: ['base', 'DEFAULT'] will generate the following CSS

/* base first */
.base\:bg-blue-100 {
  --tw-bg-opacity: 1;
  background-color: rgba(219, 234, 254, var(--tw-bg-opacity))
}
/* then default :) yey! */
.bg-yellow-100 {
  --tw-bg-opacity: 1;
  background-color: rgba(254, 243, 199, var(--tw-bg-opacity))
}

Which is what we want because we want the .bg-yellow-100 to override the .base:bg-blue-100.

but if we set unstable_stack=true tailwind does not follows the variantOrder and generates the following CSS which breaks the specificity.

/* default first */
.bg-yellow-100 {
  --tw-bg-opacity: 1;
  background-color: rgba(254, 243, 199, var(--tw-bg-opacity))
}
/* base at end :( */
.base\:bg-blue-100 {
  --tw-bg-opacity: 1;
  background-color: rgba(219, 234, 254, var(--tw-bg-opacity))
}

Solution

Make unstable_stack=true follow the variantOrder properly.

I've did some experiments and this code does work :-
It sorts the remainingVariants by variantOrder.
file: https://github.com/tailwindlabs/tailwindcss/blob/master/src/lib/substituteVariantsAtRules.js#L184

// substituteVariantsAtRules.js
let remainingVariants = prependStackableVariants(atRule, variants, stackableVariants)

// NEW CODE! Sorting the `remainingVariants` by `variantOrder`
remainingVariants = ensureIncludesDefault(remainingVariants).sort((a, z) =>{ 
  return config.variantOrder.indexOf(a) - config.variantOrder.indexOf(z)
})

_.forEach(_.without(remainingVariants,'responsive'), (variant) => {
  if (!variantGenerators[variant]) {
    throw new Error(
      `Your config mentions the "${variant}" variant, but "${variant}" doesn't appear to be a variant. Did you forget or misconfigure a plugin that supplies that variant?`
    )
  }
  variantGenerators[variant].handler(atRule, config)
})

Related PRs, Issues & Links:
https://tailwindcss.com/docs/configuration#variant-order
#1446
#1951
#657
#496