Support creating new variants through plugins (WIP)

[adamwathan]

Implementation for #496.

Right now this PR adds support for basic variant plugins that just alter the selector, like our bundled variants.

It lets you write a plugin like this to create a first-child variant:

{
  // ...
  plugins: [
    // ...
    function({ addVariant }) {
      addVariant('first-child', ({ className, separator }) => {
        return `.first-child${separator}${className}:first-child`
      })
    }
  ]
}

It also changes how the order variants are generated in is determined, by pushing that control to the user instead of using a hard-coded order. Now the order of your variants in your modules config is the order we use to generate the variants, so if you list ['hover, 'focus'], hover will be generated first, but if you list ['focus', 'hover'] then focus will be generated first. This puts the user in control of which rule takes precedence.

Next up:

• Support variant generators that modify properties, not just selectors
• Support variant generators that need to wrap rules in an at-rule (like a supports-grid variant)
• Allow variant generator plugin authors to control how responsive versions of their variants are generated (right now we just prefix the last class in the selector)

[adamwathan]

I've pushed some updates to this PR to support variant generators that modify properties as well as variant generators that need to wrap rules in an at-rule.

I've done this by giving variant plugins complete control to manipulate the CSS AST using the regular PostCSS API.

Note: This replaces the API the PR started with, where you only needed to return a string to change a selector name.

Now the addVariant closure receives a PostCSS Container that contains all of the rules nested inside of the @variants at-rule. You manipulate those rules using the regular PostCSS API, by walking and mutating rules, declarations, etc.

For example, here's a plugin that creates a new important variant:

function({ addVariant }) {
  addVariant('important', ({ container }) => {
    container.walkRules(rule => {
      rule.selector = `.\\!${rule.selector.slice(1)}`
      rule.walkDecls(decl => {
        decl.important = true
      })
    })
  })
}

...and here's one that adds a supports-grid variant:

function({ addVariant }) {
  addVariant('supports-grid', ({ container, separator }) => {
    const supportsRule = postcss.atRule({ name: 'supports', params: '(display: grid)' })
    supportsRule.nodes = container.nodes
    container.nodes = [supportsRule]
    supportsRule.walkRules(rule => {
      rule.selector = `.supports-grid${separator}${rule.selector.slice(1)}`
    })
  })
}

I'd like to provide some more ergonomic abstractions on top of the raw PostCSS API for common situations, but this feels like the right starting point because it gives plugin authors the most flexibility and control.

One example of an ergonomic abstraction is the modifySelectors function that now gets passed to the addVariant closure argument. It gets you pretty close to the API the PR exposed originally for simple selector modifications without introducing new complexity in how things work.

Here's a plugin that uses modifySelectors to create a simple first-child variant:

function({ addVariant }) {
  addVariant('first-child', ({ modifySelectors, separator }) => {
    modifySelectors(({ className }) => {
      return `.first-child${separator}${className}:first-child`
    })
  })
}

Under the hood, modifySelectors expands the code above to this:

function({ addVariant }) {
  addVariant('first-child', ({ container, separator }) => {
    container.walkRules(rule => {
      const className = rule.selector.slice(1)
      rule.selector = `.first-child${separator}${className}:first-child`
    })
  })
}

There might be a way to simplify this even more, for example there's no reason we couldn't allow you to do something like this:

function({ addVariant }) {
  addVariant('first-child', modifySelectors({ className, separator }) => {
      return `.first-child${separator}${className}:first-child`
  })
}

The only thing about this API is that modifySelectors has to come from somewhere, so it would need to be destructurable out of the top level plugin function (function({ addVariant, modifySelectors })) or imported from another module, like some sort of separate tailwindcss-plugin-utils package or something.

Either way, by supporting manipulationg via raw PostCSS I've knocked off most of the requirements I mentioned in the opening PR comment, with only "allow plugin authors to control how responsive variants are generated" left to tackle.

[adamwathan]

Going to merge this as-is for now and probably include in the next patch release without much ceremony, so I have the option to break it in the next minor if needed which is where I'll probably officially "announce" it and add documentation.

[adamwathan]

This feature has been moved behind a flag to make it a bit more explicit that it's subject to change.

To enable it (as of 0.6.2 which will be out today):

module.exports = {
 // ...
  experiments: {
    pluginVariants: true,
  },
}