feat(colors): don't strip colors of alpha channels

resolves #95 fixes #74 fixes #77 BREAKING CHANGE: Alpha channels in colors are no longer stripped. If you want the alpha channels stripped still, either do so manually or change the classes you are using to use the [opacity modifier syntax](https://tailwindcss.com/docs/upgrade-guide#new-opacity-modifier-syntax) with the opacity set to `100` e.g. from `bg-primary` to `bg-primary/100`.
RyanClementsHax · Nov 19, 2023 · 3cca493 · 3cca493
1 parent bcbc950
commit 3cca493
Show file tree

Hide file tree

Showing 65 changed files with 297 additions and 176 deletions.
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ An unopinionated, scalable, [tailwindcss](https://tailwindcss.com/) theming solu
 
 **🌑 Trivial dark theme**: Because dark theme is _just another theme_ implementing dark theme is as easy, no special config
 
-**🤖 Automatically handles colors and opacity**: Using [tailwind with css variables](https://tailwindcss.com/docs/customizing-colors#using-css-variables) can get [tricky with colors](https://www.youtube.com/watch?v=MAtaT8BZEAo), but this plugin handles all of that for you!
+**🤖 Automatically handles colors and opacity**: Using [tailwind with css variables](https://tailwindcss.com/docs/customizing-colors#using-css-variables) can get tricky with colors, but this plugin handles all of that for you!
 
 **😅 Easy theme management**: A simple, declarative api that lets you easily create and modify themes
 
@@ -38,8 +38,8 @@ An unopinionated, scalable, [tailwindcss](https://tailwindcss.com/) theming solu
   - [Use the classes like normal](#use-the-classes-like-normal)
   - [Enable your other theme](#enable-your-other-theme)
   - [Apply variants if you want](#apply-variants-if-you-want)
-- [Contributing](#contributing)
-- [Documentation](#documentation)
+- [Config documentation](#config-documentation)
+- [Migration documentation](#migration-documentation)
 - [Enabling your theme](#enabling-your-theme)
   - [Selectors](#selectors)
   - [Media query](#media-query)
@@ -190,15 +190,15 @@ If for some reason you need to apply classes only when certain themes are active
 
 See [Variants](#variants) for more details.
 
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidance on contributing.
-
-## Documentation
+## Config documentation
 
 - [Config](docs/config.md#config)
 - [Theming Colors](docs/themingColors.md#theming-colors)
 
+## Migration documentation
+
+See [migrating.md](./docs/migrating.md) for instructions on how to migrate between major versions.
+
 ## Enabling your theme
 
 By default, the config in the `defaultTheme` section of the config will apply (i.e. if no class is applied).
@@ -485,15 +485,7 @@ module.exports = {
   theme: {
     extend: {
       colors: {
-        primary: ({ opacityVariable, opacityValue }) => {
-          if (opacityValue !== undefined) {
-            return `rgba(var(--colors-primary), ${opacityValue})`
-          }
-          if (opacityVariable !== undefined) {
-            return `rgba(var(--colors-primary), var(${opacityVariable}, 1))`
-          }
-          return `rgb(var(--colors-primary))`
-        }
+        primary: 'rgb(255 0 0 / <alpha-value>)'
       },
       fontFamily: {
         title: 'var(--font-family-title)'
@@ -503,20 +495,18 @@ module.exports = {
 }
 ```
 
-> Notice how we needed to set `color.primary` to a callback function. This is to properly handle opacity. See [Opacity](docs/themingColors.md#opacity) for more details.
-
 It also injects css variables with proper scoping into tailwind's [base layer](https://tailwindcss.com/docs/adding-custom-styles#using-css-and-layer).
 
 ```css
 /* this is configured by "defaultTheme" */
 :root {
-  --colors-primary: 255, 0, 0;
+  --colors-primary: 255 0 0;
   --font-family-title: Helvetica;
 }
 
 /* this is configured by the "my-theme" configuration */
 .my-theme {
-  --colors-primary: 0, 0, 255;
+  --colors-primary: 0 0 255;
   --font-family-title: ui-monospace;
 }
 ```
@@ -545,7 +535,7 @@ For comparison, this is what those classes looked like before without theming:
 
 .text-primary {
   --tw-text-opacity: 1;
-  color: rgb(255 0 0 1 / var(--tw-text-opacity));
+  color: rgb(255 0 0 / var(--tw-text-opacity));
 }
 ```
 
@@ -589,7 +579,7 @@ For example the above `defaultTheme` config generates the following css variable
 ```css
 /* this is configured by "defaultTheme" */
 :root {
-  --colors-primary: 255, 0, 0;
+  --colors-primary: 255 0 0;
   --font-family-title: Helvetica;
 }
 ```
@@ -632,12 +622,12 @@ For example, the above config in the `themes` section of the config generates th
 
 ```css
 .my-theme-1 {
-  --colors-primary: 255, 0, 0;
+  --colors-primary: 255 0 0;
   --font-family-title: Helvetica;
 }
 
 .my-theme-2 {
-  --colors-primary: 0, 0, 255;
+  --colors-primary: 0 0 255;
   --font-family-title: ui-monospace;
 }
 ```

diff --git a/docs/migrating.md b/docs/migrating.md
@@ -0,0 +1,17 @@
+# Migrating <!-- omit in toc -->
+
+- [From v3 to v4](#from-v3-to-v4)
+- [From v2 to V3](#from-v2-to-v3)
+- [From v1 to V2](#from-v1-to-v2)
+
+## From v3 to v4
+
+Alpha channels in colors are no longer stripped. If you want the alpha channels stripped still, either do so manually or change the classes you are using to use the [opacity modifier syntax](https://tailwindcss.com/docs/upgrade-guide#new-opacity-modifier-syntax) with the opacity set to `100` e.g. from `bg-primary` to `bg-primary/100`.
+
+## From v2 to V3
+
+The types this plugin used for tailwind's config are no longer exported. Use [tailwind's types](https://tailwindcss.com/docs/configuration#type-script-types) instead.
+
+## From v1 to V2
+
+The plugin will no longer add the [prefix](https://tailwindcss.com/docs/plugins#prefix-and-important-1) to any theme or default classes because they are base styles (more details [here](https://tailwindcss.com/docs/plugins#adding-base-styles)).
diff --git a/docs/themingColors.md b/docs/themingColors.md
@@ -3,7 +3,7 @@
 - [Opacity](#opacity)
 - [Supported color representations](#supported-color-representations)
 
-The way color values are handled is particular since colors need to work with opacity modifiers like `bg-primary/75`. They are parsed into individual rgb channels with their alpha value dropped. See [Opacity](#opacity) for details.
+The way color values are handled is particular since colors need to work with opacity modifiers like `bg-primary/75`. They are parsed into individual rgb channels.
 
 Any value that can be parsed as a color will be treated as a color. This holds for any value found anywhere on the theme object.
 
@@ -29,16 +29,16 @@ The above generates the following css variables:
 
 ```css
 :root {
-  --colors-primary: 255, 255, 255;
-  --foo-bar-bazz: 35, 0, 75;
+  --colors-primary: 255 255 255;
+  --foo-bar-bazz: 35 0 75;
 }
 ```
 
 > As you can see, the way we need to parse colors into individual channels like this makes it hard to tell what color is being represented. It doesn't work well with tooling like the vscode [Color Highlight](https://marketplace.visualstudio.com/items?itemName=naumovs.color-highlight) extension. This was a motivating factor in creating this plugin. `primary: '#fff' is easier to read and works better with tooling.
 
 ## Opacity
 
-When [theming color values in tailwindcss](https://tailwindcss.com/docs/customizing-colors#using-css-variables), you cannot naively theme them because they depend on opacity custom properties. [This video](https://www.youtube.com/watch?v=MAtaT8BZEAo) goes further into why.
+When [theming color values in tailwindcss](https://tailwindcss.com/docs/customizing-colors#using-css-variables), you cannot naively theme them because they depend on opacity custom properties.
 
 This plugin takes care of all of that complexity for you under the hood! All you have to do is specify the colors themselves.
 
@@ -62,12 +62,12 @@ The above config generates the following css variables:
 
 ```css
 :root {
-  --colors-primary: 34, 51, 255;
-  --colors-secondary: 153, 153, 153;
+  --colors-primary: 34 51 255;
+  --colors-secondary: 153 153 153;
 }
 ```
 
-Now classes like `text-primary` can work with opacity modifiers like `text-primary/75` and classes like `text-opacity-50`
+Now classes like `text-primary` can work with opacity modifiers like `text-primary/75` and classes like `text-opacity-50`.
 
 ```css
 .text-primary {
@@ -89,9 +89,11 @@ Now classes like `text-primary` can work with opacity modifiers like `text-prima
 }
 ```
 
+Colors with alpha channels are also supported as of `tailwindcss-themer@4.0.0`, but don't support opacity classes like `text-opacity-50`. That being said, those are [deprecated anyway](https://tailwindcss.com/docs/upgrade-guide#new-opacity-modifier-syntax). Only the [opacity modifer syntax](https://tailwindcss.com/docs/upgrade-guide#new-opacity-modifier-syntax) is supported for changing the opacity of these colors e.g. `text-primary/75`.
+
 ## Supported color representations
 
-You can use any color representation that can be parsed by [color](https://www.npmjs.com/package/color). Alpha channels are stripped though to support opacity. See [Opacity](#opacity) for details.
+You can use any color representation that can be parsed by [color](https://www.npmjs.com/package/color). As of `tailwindcss-themer@4.0.0` alpha channels are preserved.
 
 ```js
 require('tailwindcss-themer')({
@@ -101,7 +103,7 @@ require('tailwindcss-themer')({
         primary: '#f3f', // fine
         secondary: 'rgb(0, 21, 742)', // also fine
         tertiary: 'hsl(250, 23%, 79%)', // yup
-        quarternary: 'hsla(132, 67%, 39%, 0.66)', // also ok, but the alpha value will be stripped (thus the value will functionally be hsl(132, 67%, 39%))
+        quarternary: 'hsla(132, 67%, 39%, 0.66)', // all good as of tailwindcss-themer@4.0.0
         quinary: 'blue' // also ok
         // etc...
       }
@@ -115,12 +117,10 @@ All of the colors get parsed down to rgb channels.
 
 ```css
 :root {
-  --colors-primary: 255, 51, 255;
-  --colors-secondary: 0, 21, 255;
-  --colors-tertiary: 193.239, 189.1335, 213.7665;
-  --colors-quarternary: 32.81850000000001, 166.0815, 59.4711; /* notice how the alpha value is dropped */
-  --colors-quinary: 0, 0, 255;
+  --colors-primary: 255 51 255;
+  --colors-secondary: 0 21 255;
+  --colors-tertiary: 193.239 189.1335 213.7665;
+  --colors-quarternary: 32.81850000000001 166.0815 59.4711;
+  --colors-quinary: 0 0 255;
 }
 ```
-
-> If you want to see colors with alpha channels supported, hop on [this discussion](https://github.com/RyanClementsHax/tailwindcss-themer/discussions/95)!
diff --git a/e2e/test_repos/drivers/index.ts b/e2e/test_repos/drivers/index.ts
@@ -250,4 +250,11 @@ export function parseClasses(config: MultiThemePluginOptions): string[] {
 // Preventing purging of these styles makes writing tests with arbitrary classes
 // easier since otherwise they'd have to define the styles they use when opening
 // the repo instance
-const stylesToKeep = ['bg-primary', 'bg-primary-DEFAULT-500', 'font-title']
+const stylesToKeep = [
+  'bg-primary',
+  'bg-primary/75',
+  'bg-primary-DEFAULT-500',
+  'font-title',
+  'text-textColor',
+  'text-textColor/50'
+]