feat: override variant

docs/setup.md

@@ -37,6 +37,8 @@ The setup functions is a named export of the main module and accepts an config o
   - [DOM Sheet](#dom-sheet)
   - [Virtual Sheet](#virtual-sheet)
   - [Custom Sheet Implementation](#custom-sheet-implementation)
+- [Plugins](#plugins)
+- [Variants](#variants)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 </details>
@@ -293,6 +295,22 @@ sheet.target
 
 In case the builtin sheet implementations do not solve your use case, you can [create your own](./sheets.md#custom-sheet-implementation).
 
+## Plugins
+
+The `plugins` property allows to define new plugins or override core plugins. See [Plugins](./plugins.md) for details.
+
+## Variants
+
+The `variants` property allows to define new variants or override [core variants](./tailwind-extensions.md#variants).
+
+```js
+setup({
+  variants: {
+    'not-checked': '&:not(:checked)',
+  },
+})
+```
+
 <hr/>
 
 Continue to [Examples](./examples.md)

docs/tailwind-extensions.md

@@ -77,7 +77,7 @@ _Advanced_ pseudo classes (those that take parameters like `:is(header)`) are no
 ```js
 setup({
   variants: {
-    ':is-header': '&:is(header)',
+    'is-header': '&:is(header)',
   },
 })
 
@@ -150,6 +150,31 @@ Please note that [some CSS properties are inherited](https://developer.mozilla.o
 
 </details>
 
+<details><summary><code>override:*</code> - Increase the specificity of rules</summary>
+
+When using components that have some default styles (like [twin/styled](./styled.md)) it happens that one wants to override a rule. Consider the following example:
+
+```js
+const shared = tw`text(xl center blue-600) underline`
+const special = tw`${shared} text-purple-600 no-underline`
+// => text-xl text-center text-blue-600 underline text-purple-600 no-underline
+```
+
+One can not be sure that the `text-purple-600` would be correctly applied as the order of classes does not matter. Only the [specificity](https://specificity.keegan.st/).
+
+To support these cases twind includes the `override` variant which uses a little trick to increase the specificity: `.class-name.class-name` is more specific than just `.class-name`
+
+The above example should be re-written to:
+
+```js
+const shared = tw`text(xl center blue-600) underline`
+const special = tw`${shared} override:(text-purple-600 no-underline)`
+```
+
+> [live and interactive demo](https://esm.codes/#aW1wb3J0IHsgdHcgfSBmcm9tICdodHRwczovL2Nkbi5za3lwYWNrLmRldi90d2luZCcKCmNvbnN0IHNoYXJlZCA9IHR3YHRleHQoeGwgY2VudGVyIGJsdWUtNjAwKSB1bmRlcmxpbmVgCmNvbnN0IHNwZWNpYWwgPSB0d2Ake3NoYXJlZH0gb3ZlcnJpZGU6KHRleHQtcHVycGxlLTYwMCBuby11bmRlcmxpbmUpYAoKZG9jdW1lbnQuYm9keS5pbm5lckhUTUwgPSBgCiAgPHAgY2xhc3M9IiR7c2hhcmVkfSI+Q29tbW9uIFN0eWxlczwvcD4KICA8cCBjbGFzcz0iJHtzcGVjaWFsfSI+U3BlY2lhbCBTdHlsZXM8L3A+CmAK)
+
+</details>
+
 ## Directives
 
 <details><summary>Some directives support all CSS values</summary>

src/__tests__/api.json

@@ -721,5 +721,6 @@
   "children:underline": ".children\\:underline>*{text-decoration:underline}",
   "siblings:underline": ".siblings\\:underline~*{text-decoration:underline}",
   "sibling:underline": ".sibling\\:underline+*{text-decoration:underline}",
-  "text-center!": ".text-center\\!{text-align:center !important}"
+  "text-center!": ".text-center\\!{text-align:center !important}",
+  "override:text-center": ".override\\:text-center.override\\:text-center{text-align:center}"
 }

src/twind/decorate.ts

@@ -34,7 +34,7 @@ export const decorate = (
 
     // Check other well known variants
     // and fallback to pseudo class
-    return { [variants[variant] || '&' + variant]: translation }
+    return { [variants[tail(variant)] || '&' + variant]: translation }
   }
 
   // Apply variants depth-first

src/twind/variants.ts

@@ -1,13 +1,14 @@
 export const coreVariants: Record<string, string> = {
-  ':dark': '@media (prefers-color-scheme:dark)',
-  ':sticky': '@supports ((position: -webkit-sticky) or (position:sticky))',
-  ':motion-reduce': '@media (prefers-reduced-motion:reduce)',
-  ':motion-safe': '@media (prefers-reduced-motion:no-preference)',
-  ':first': '&:first-child',
-  ':last': '&:last-child',
-  ':even': '&:nth-child(2n)',
-  ':odd': '&:nth-child(odd)',
-  ':children': '&>*',
-  ':siblings': '&~*',
-  ':sibling': '&+*',
+  dark: '@media (prefers-color-scheme:dark)',
+  sticky: '@supports ((position: -webkit-sticky) or (position:sticky))',
+  'motion-reduce': '@media (prefers-reduced-motion:reduce)',
+  'motion-safe': '@media (prefers-reduced-motion:no-preference)',
+  first: '&:first-child',
+  last: '&:last-child',
+  even: '&:nth-child(2n)',
+  odd: '&:nth-child(odd)',
+  children: '&>*',
+  siblings: '&~*',
+  sibling: '&+*',
+  override: '&&',
 }