Support plugin options in CSS

[thecrypticace]

Builds on #14239 — that PR needs to be merged first.

This PR allows plugins defined with plugin.withOptions to receive options in CSS when using @plugin as long as the options are simple key/value pairs.

For example, the following is now valid and will include the forms plugin with only the base styles enabled:

@plugin "@tailwindcss/forms" {
  strategy: base;
}

We handle null, true, false, and numeric values as expected and will convert them to their JavaScript equivalents. Comma separated values are turned into arrays. All other values are converted to strings.

For example, in the following plugin definition, the options that are passed to the plugin will be the correct types:

• debug will be the boolean value true
• threshold will be the number 0.5
• message will be the string "Hello world"
• features will be the array ["base", "responsive"]

@plugin "my-plugin" {
  debug: false;
  threshold: 0.5;
  message: Hello world;
  features: base, responsive;
}

If you need to pass a number or boolean value as a string, you can do so by wrapping the value in quotes:

@plugin "my-plugin" {
  debug: "false";
  threshold: "0.5";
  message: "Hello world";
}

When duplicate options are encountered the last value wins:

@plugin "my-plugin" {
  message: Hello world;
  message: Hello plugin; /* this will be the value of `message` */
}

It's important to note that this feature is only available for plugins defined with plugin.withOptions. If you try to pass options to a plugin that doesn't support them, you'll get an error message when building:

@plugin "my-plugin" {
  debug: false;
  threshold: 0.5;
}

/* Error: The plugin "my-plugin" does not accept options */

Additionally, if you try to pass in more complex values like objects or selectors you'll get an error message:

@plugin "my-plugin" {
  color: { red: 100; green: 200; blue: 300 };
}

/* Error: Objects are not supported in `@plugin` options. */

@plugin "my-plugin" {
  .some-selector > * {
    primary: "blue";
    secondary: "green";
  }
}

/* Error: `@plugin` can only contain declarations. */

[rnevius]

Is this documented anywhere?

[chasegiunta]

@thecrypticace did this make it to 4.0 release? https://play.tailwindcss.com/zyTwDJniph?file=css

[saadeghi]

@chasegiunta remove the ; at the end.

[thecrypticace]

Yep, it did. ☝️ What @saadeghi said, the ; is causing an error. Though the error is kinda non-sensical. I've made a note to look into that.

[chasegiunta]

@thecrypticace @saadeghi I'm an idiot. Thanks fellas! Semi-related, I was looking at this due to a breaking behavior on which layer the tailwindcss-forms resets are placed (v3 was components layer, v4 is utilities, making overrides nearly impossible) tailwindlabs/tailwindcss-forms#162 (comment). Anyways, thank you