2.0.0 Add support for multiple levels of unimportance

Author: mwnciau

.gitignore

@@ -1 +1,8 @@
-node_modules
+*
+!src
+!.gitignore
+!CHANGELOG.md
+!LICENSE
+!package.json
+!package-lock.json
+!README.md

CHANGELOG.md

@@ -1,3 +1,7 @@
+### 2.0.0 [2023-09-29]
+- (BC BREAK) Variant changed from `~:` to `-:`
+- Added support for additional levels of unimportance
+
 ### 1.0.1 [2023-09-29]
 - Create project readme
 

README.md

@@ -2,7 +2,6 @@
 A [Tailwind CSS] plugin that creates lower-specificity utility classes that can
 be used to create components with overridable defaults.
 
-
 ## Installation
 
 ```sh
@@ -20,21 +19,21 @@ module.exports = {
 
 ## Getting started
 
-To make a class unimportant, use the `~:` prefix.
+To make a class unimportant, use the `-:` variant.
 
 ```html
-<p class="~:font-bold">Hello world</p>
+<p class="-:font-bold">Hello world</p>
 ```
 
-These classes will always have lower precedence than classes without the prefix.
+These classes will always have lower precedence than classes without the variant.
 
 ```php
 // The text will have normal or bold weight depending on the order of the
 // `font-bold` and `font-normal` classes in the compiled CSS.
 <p class="font-bold font-normal">Hello world</p>
 
 // The text will always have normal weight
-<p class="~:font-bold font-normal">Hello world</p>
+<p class="-:font-bold font-normal">Hello world</p>
 ```
 
 This is useful when making components where you want to be able to override the
@@ -43,7 +42,7 @@ default classes.
 ```php
 /// paragraph.blade.php
 <p {{ 
-    $attributes->merge(['class' => '~:text-base ~:font-normal ~:text-grey-800'])
+    $attributes->merge(['class' => '-:text-base -:font-normal'])
 }}>
     {{ $slot }}
 </p>
@@ -54,18 +53,64 @@ default classes.
 <x-paragraph class="text-lg font-bold">Hello world!</x-paragraph>
 ```
 
+### Making classes even more unimportant
+
+Sometimes it's useful to extend components within other components, and you can
+run into the same problem of clashing Tailwind classes.
+
+This plugin provides additional class variants for up to 10 levels of
+unimportance: `--:`, `---:`, `----:`, etc. 
+
+```php
+// -:text-blue takes precedence over --:text-green, which takes precedence over
+// ---:text-red
+<a class="---:text-red --:text-green -:text-blue">
+    The link is blue
+</a>
+```
+
+As the variants become larger, you may prefer to use the number variants, where
+the lowest number takes precedence: `--1:`, `--2:`, `--3:`, etc. The number and
+symbol variants can be used interchangeably.
+
+```php
+// This example is identical to the previous example
+<a class="--5:text-red --:text-green --1:text-blue">
+    The link is blue
+</a>
+```
+
+Arbitrary values are also supported. For example, `--[5]:` is equivalent to
+`-----:`. Zero and negative values can be used to make classes of higher
+precedence.
+
+| Unimportance | Symbolic variant | Numberic variant |
+|--------------|------------------|------------------|
+| 1            | `-:`             | `--1:`           |
+| 2            | `--:`            | `--2:`           |
+| 3            | `---:`           | `--3:`           |
+| 4            | `----:`          | `--4:`           |
+| 5            | `-----:`         | `--5:`           |
+| 6            | `------:`        | `--6:`           |
+| 7            | `-------:`       | `--7:`           |
+| 8            | `--------:`      | `--8:`           |
+| 9            | `---------:`     | `--9:`           |
+| 10           | `----------:`    | `--10:`          |
+| `n`          | _n/a_            | `--[n]:`         |
+
+
 ## How it works
 
-The `~:` prefix wraps the selector for a given class in the css `:where()`
+The `-:` variant wraps the selector for a given class in the css `:where()`
 function, reducing its [specificity] to `0-0-0`. This means classes you use
-without the unimportant prefix will be applied preferentially.
+without the unimportant variant will be applied preferentially.
 
 ```css
 /* Specificity of 0-1-0 */
 .bg-white
 
 /* Specificity of 0-0-0 */
-:where(.\~\:bg-white)
+:where(.-\:bg-white)
 ```
 
 However, having a specificity of `0-0-0` means that the default tailwind base
@@ -80,12 +125,12 @@ a {
 }
 
 /* Specificity of 0-0-0 */
-:where(.\~\:text-red) {
+:where(.-\:text-red) {
     color: red;
 } 
 </style>
 
-<a class="~:text-red">The link is blue</a>
+<a class="-:text-red">The link is blue</a>
 ```
 
 To fix this problem, the plugin sets the `important` Tailwind configuration
@@ -106,13 +151,26 @@ a {
 }
 
 /* Specificity of 0-1-0 */
-:root :where(.\~\:text-red) {
+:root :where(.-\:text-red) {
     color: red;
 }
 </style>
 
-<a class="~:text-red">The link is red</a>
-<a class="~:text-red text-green">The link is green</a>
+<a class="-:text-red">The link is red</a>
+<a class="-:text-red text-green">The link is green</a>
+```
+
+### Levels of unimportance
+
+Classes with greater levels of unimportance are output first in the generated
+CSS file so that the less unimportant classes take precedence.
+
+```css
+/* The more unimportant class is output first */
+.--\:bg-white {...}
+
+/* The later CSS rule takes precedence */
+.-\:bg-black {...}
 ```
 
 [Tailwind CSS]: https://github.com/tailwindlabs/tailwindcss

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwindcss-unimportant",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Adds lower specificity tailwindcss utility classes to be used in components",
   "main": "src/index.js",
   "peerDependencies": {

src/index.js

@@ -1,8 +1,43 @@
 const plugin = require("tailwindcss/plugin");
 
 const unimportant = plugin(
-    ({ addVariant }) => {
-        addVariant("~", ":where(&)");
+    ({ matchVariant }) => {
+        matchVariant(
+            '-',
+            (unimportance) => {
+                return ':where(&)'
+            },
+            {
+                values: {
+                    DEFAULT: 1,
+                    '': 2,
+                    '-': 3,
+                    '--': 4,
+                    '---': 5,
+                    '----': 6,
+                    '-----': 7,
+                    '------': 8,
+                    '-------': 9,
+                    '--------': 10,
+                    1: 1,
+                    2: 2,
+                    3: 3,
+                    4: 4,
+                    5: 5,
+                    6: 6,
+                    7: 7,
+                    8: 8,
+                    9: 9,
+                    10: 10,
+                },
+                sort(a, z) {
+                    const aValue = parseInt(typeof a.value === 'symbol' ? 0 : a.value);
+                    const zValue = parseInt(typeof z.value === 'symbol' ? 0 : z.value);
+
+                    return zValue - aValue;
+                }
+            },
+        );
     },
     {important: ':root'}
 );