BREAKING: changed the definition of shortcuts within config.rules

.changeset/metal-meals-sniff.md

@@ -0,0 +1,43 @@
+---
+'twind': patch
+---
+
+BREAKING: changed the definition of shortcuts within config.rules
+
+The new format should be more readable and clear about what is happening.
+
+```js
+// defineConfig is optional but helps with type inference
+defineConfig({
+  rules: [
+    /* Some aliases */
+    // shortcut: styles are generated as defined by twind — same as if they where used alone
+    // shortcut to multiple utilities
+    ['card', 'py-2 px-4 font-semibold rounded-lg shadow-md'],
+
+    // dynamic shortcut — `$$` is everything after the match eg `btn-red` -> `red`
+    ['card-', ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`],
+
+    // single utility alias — need to use `~(...)` as it would be otherwise recognized as a CSS property
+    ['red', '~(text-red-100)'],
+
+    // apply: styles are generated in order they are declared
+    // apply to multiple utilities
+    ['btn-green', '@(bg-green-500 hover:bg-green-700 text-white)'],
+
+    // dynamic apply
+    ['btn-', ({ $$ }) => `@(bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg)`],
+
+    /* Some rules */
+    ['hidden', { display: 'none' }],
+
+    // Table Layout
+    // .table-auto { table-layout: auto }
+    // .table-fixed { table-layout: fixed }
+    ['table-(auto|fixed)', 'tableLayout'],
+
+    // dynamic
+    ['table-', (match, context) => /* ... */],
+],
+})
+```

README.md

@@ -109,7 +109,7 @@ We have created a few [examples](https://github.com/tw-in-js/twind/tree/next/exa
     - allows to reset twind (start clean): `tw.clear()`
     - allows to remove twind (remove the associated style element): `tw.destroy()`
   - `shortcut` (previously known as `apply`) and `css` as known from twind v0.16.
-    - with support for creating named shortcuts: `shortcut.PrimaryButton\`bg-red-500 text-white\``->`PrimaryButton#<hash>`
+    - with support for creating named shortcuts: `` shortcut.PrimaryButton`bg-red-500 text-white`​ `` -> `PrimaryButton#<hash>`
   - new `cx` function to create class names
     - grouped rules are ungrouped
   - `style` — stitches like component definitions
@@ -123,9 +123,9 @@ We have created a few [examples](https://github.com/tw-in-js/twind/tree/next/exa
     - anonymous shortcuts: `~(!text-(3xl center) !underline italic focus:not-italic)`
       - support comma-separated shortcuts — this prevents different classNames errors during hydration:
         - `hover:~(!text-(3xl,center),!underline,italic,focus:not-italic)`
-        - `cx()` converts these to comma-separated group
+        - `cx()` converts space-separated to comma-separated
     - named shortcuts: `PrimaryButton~(bg-red-500 text-white)` -> `PrimaryButton#<hash>`
-      - `shortcut()` is a helper to simplify creation of shortcuts (works like `apply()` in twind v0.16); it supports creating named shortcuts: ``shortcut.PrimaryButton`bg-red-500 text-white`​`` -> `PrimaryButton#<hash>`
+      - `shortcut()` is a helper to simplify creation of shortcuts (works like `apply()` in twind v0.16); it supports creating named shortcuts: `` shortcut.PrimaryButton`bg-red-500 text-white`​ `` -> `PrimaryButton#<hash>`
 - config
 
   - presets are executed in order they are defined
@@ -147,7 +147,7 @@ We have created a few [examples](https://github.com/tw-in-js/twind/tree/next/exa
 
   - darkMode can be selector string `{ darkMode: '.dark-mode &' }` or `{ darkMode: 'html[data-theme="dark"] &` }`
 
-  - rules and shortcuts based on ideas from [UnoCSS](https://github.com/antfu/unocss)
+  - rules based on ideas from [UnoCSS](https://github.com/antfu/unocss)
 
     ```js
     // defineConfig is optional but helps with type inference
@@ -161,18 +161,21 @@ We have created a few [examples](https://github.com/tw-in-js/twind/tree/next/exa
         // .table-fixed { table-layout: fixed }
         ['table-(auto|fixed)', 'tableLayout'],
 
-        // Some shortcuts
-        {
-          // single utility alias
-          red: 'text-red-100',
+        // Some aliases
+        // shortcut to multiple utilities
+        ['card', 'py-2 px-4 font-semibold rounded-lg shadow-md'],
 
-          // shortcuts to multiple utilities
-          btn: 'py-2 px-4 font-semibold rounded-lg shadow-md',
-          'btn-green': 'text-white bg-green-500 hover:bg-green-700',
+        // dynamic shortcut
+        ['card-', ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`],
 
-          // dynamic shortcut
-          'btn-': ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`,
-        },
+        // single utility alias — need to use `~(...)` as it would be otherwise recognized as a CSS property
+        ['red', '~(text-red-100)'],
+
+        // apply to multiple utilities
+        ['btn-green', '@(bg-green-500 hover:bg-green-700 text-white)'],
+
+        // dynamic apply
+        ['btn-', ({ $$ }) => `@(bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg)`],
       ],
     })
     ```

documentation/40-reference/README.md

@@ -11,7 +11,7 @@
 - inline apply: styles are generated in order they are declared
   - `@(underline font-bold)` -> `@(underline,font-bold)`
   - `Link@(underline font-bold)` -> `Link#12345`
-- inline shortcut: style are generated as defined by twind — same as if they where used alone
+- inline shortcut: styles are generated as defined by twind — same as if they where used alone
   - `~(underline font-bold)` -> `~(underline,font-bold)`
   - `Link~(underline font-bold)` -> `Link#abcdef`
 - comments
@@ -187,21 +187,63 @@ Used to update an html string with styles.
 
 ## Config
 
-- hash all shortcuts and apply
+### Rules
 
-  ```js
-  setup({
-    hash(className, defaultHash) {
-      if (/^[~@]\(/.test(className)) {
-        // a shortcut like `~(...)`
-        // an apply like `@(...)`
-        return defaultHash(className)
-      }
-
-      return className
-    },
-  })
-  ```
+> based on ideas from [UnoCSS](https://github.com/antfu/unocss)
+
+```js
+// defineConfig is optional but helps with type inference
+defineConfig({
+  rules: [
+    // Some rules
+    ['hidden', { display: 'none' }],
+
+    // Table Layout
+    // .table-auto { table-layout: auto }
+    // .table-fixed { table-layout: fixed }
+    ['table-(auto|fixed)', 'tableLayout'],
+
+    // dynamic
+    ['table-', (match, context) => /* ... */],
+
+    // Some aliases
+    // shortcut: styles are generated as defined by twind — same as if they where used alone
+    // shortcut to multiple utilities
+    ['card', 'py-2 px-4 font-semibold rounded-lg shadow-md'],
+
+    // dynamic shortcut — `$$` is everything after the match eg `btn-red` -> `red`
+    ['card-', ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`],
+
+    // single utility alias — need to use `~(...)` as it would be otherwise recognized as a CSS property
+    ['red', '~(text-red-100)'],
+
+    // apply: styles are generated in order they are declared
+    // apply to multiple utilities
+    ['btn-green', '@(bg-green-500 hover:bg-green-700 text-white)'],
+
+    // dynamic apply
+    ['btn-', ({ $$ }) => `@(bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg)`],
+  ],
+})
+```
+
+### Hash
+
+**hash all shortcuts and apply**
+
+```js
+setup({
+  hash(className, defaultHash) {
+    if (/^[~@]\(/.test(className)) {
+      // a shortcut like `~(...)`
+      // an apply like `@(...)`
+      return defaultHash(className)
+    }
+
+    return className
+  },
+})
+```
 
 ## Browser Support
 

package.json

@@ -37,26 +37,26 @@
       "name": "twind",
       "path": "packages/twind/dist/twind.esnext.js",
       "brotli": true,
-      "limit": "6.6kb"
+      "limit": "6.5kb"
     },
     {
       "name": "twind (setup)",
       "path": "packages/twind/dist/twind.esnext.js",
       "import": "{ setup }",
       "brotli": true,
-      "limit": "4.4kb"
+      "limit": "4.35kb"
     },
     {
       "name": "@twind/cdn",
       "path": "packages/cdn/dist/cdn.esnext.js",
       "brotli": true,
-      "limit": "14.65kb"
+      "limit": "14.55kb"
     },
     {
       "name": "@twind/tailwind",
       "path": "packages/tailwind/dist/tailwind.esnext.js",
       "brotli": true,
-      "limit": "14.55kb"
+      "limit": "14.5kb"
     }
   ],
   "// start — use 'BROWSER=none' to prevent vite to open a browser if within codesandbox or stackblitz": "",

packages/cdn/package.json

@@ -29,7 +29,7 @@
       "name": "@twind/cdn",
       "path": "dist/cdn.esnext.js",
       "brotli": true,
-      "limit": "14.65kb"
+      "limit": "14.55kb"
     }
   ],
   "dependencies": {

packages/preset-tailwind/src/rules.test.json

@@ -1881,13 +1881,13 @@
       ".text-red-100{--tw-text-opacity:1;color:rgba(254,226,226,var(--tw-text-opacity))}"
     ]
   ],
-  "btn": [
+  "card": [
     "*,::before,::after{--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000}",
-    ".btn{padding-top:0.5rem;padding-bottom:0.5rem;padding-left:1rem;padding-right:1rem;font-weight:600;border-radius:0.5rem}",
-    ".btn{--tw-shadow:0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1);--tw-shadow-colored:0 4px 6px -1px var(--tw-shadow-color), 0 2px 4px -2px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow)}"
+    ".card{--tw-shadow:0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1);--tw-shadow-colored:0 4px 6px -1px var(--tw-shadow-color), 0 2px 4px -2px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow);padding-left:1rem;padding-right:1rem;padding-top:0.5rem;padding-bottom:0.5rem;font-weight:600;border-radius:0.5rem}"
   ],
+  "card-red": ".card-red{--tw-text-opacity:1;color:rgba(254,226,226,var(--tw-text-opacity));--tw-bg-opacity:1;background-color:rgba(248,113,113,var(--tw-bg-opacity));padding-left:1rem;padding-right:1rem;padding-top:0.5rem;padding-bottom:0.5rem;border-radius:0.5rem}",
   "btn-green": [
-    ".btn-green{--tw-text-opacity:1;color:rgba(255,255,255,var(--tw-text-opacity));--tw-bg-opacity:1;background-color:rgba(34,197,94,var(--tw-bg-opacity))}",
+    ".btn-green{--tw-bg-opacity:1;background-color:rgba(34,197,94,var(--tw-bg-opacity));--tw-text-opacity:1;color:rgba(255,255,255,var(--tw-text-opacity))}",
     ".btn-green:hover{--tw-bg-opacity:1;background-color:rgba(21,128,61,var(--tw-bg-opacity))}"
   ],
   "btn-red": ".btn-red{--tw-bg-opacity:1;background-color:rgba(248,113,113,var(--tw-bg-opacity));--tw-text-opacity:1;color:rgba(254,226,226,var(--tw-text-opacity));padding-top:0.5rem;padding-bottom:0.5rem;padding-left:1rem;padding-right:1rem;border-radius:0.5rem}",

packages/preset-tailwind/src/rules.test.ts

@@ -48,18 +48,21 @@ const tw = twind(
       },
     },
     rules: [
-      // Some shortcuts
-      {
-        // single utility alias
-        red: 'text-red-100',
+      // Some aliases
+      // shortcut to multiple utilities
+      ['card', 'py-2 px-4 font-semibold rounded-lg shadow-md'],
 
-        // shortcuts to multiple utilities
-        btn: 'py-2 px-4 font-semibold rounded-lg shadow-md',
-        'btn-green': 'text-white bg-green-500 hover:bg-green-700',
+      // dynamic shortcut
+      ['card-', ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`],
 
-        // dynamic shortcut — could be a rule as well
-        'btn-': ({ $$ }) => `bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg`,
-      },
+      // single utility alias — need to use `~(...)` as it would be otherwise recognized as a CSS property
+      ['red', '~(text-red-100)'],
+
+      // apply to multiple utilities
+      ['btn-green', '@(bg-green-500 hover:bg-green-700 text-white)'],
+
+      // dynamic apply
+      ['btn-', ({ $$ }) => `@(bg-${$$}-400 text-${$$}-100 py-2 px-4 rounded-lg)`],
     ],
   },
   virtual(),

packages/twind/package.json

@@ -29,21 +29,21 @@
       "name": "twind",
       "path": "dist/twind.esnext.js",
       "brotli": true,
-      "limit": "6.6kb"
+      "limit": "6.5kb"
     },
     {
       "name": "twind (setup)",
       "path": "dist/twind.esnext.js",
       "import": "{ setup }",
       "brotli": true,
-      "limit": "4.4kb"
+      "limit": "4.35kb"
     },
     {
       "name": "twind (twind + cssom)",
       "path": "dist/twind.esnext.js",
       "import": "{ twind, cssom }",
       "brotli": true,
-      "limit": "4.1kb"
+      "limit": "4kb"
     }
   ],
   "dependencies": {