@csstools/postcss-alpha-function 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changes to PostCSS Alpha Function
+
+### 1.0.0
+
+_August 22, 2025_
+
+- Initial version
+- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.1.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#310) (minor)
+- Updated [`@csstools/postcss-progressive-custom-properties`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties) to [`4.2.0`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties/CHANGELOG.md#420) (minor)

package/LICENSE.md

@@ -0,0 +1,18 @@
+MIT No Attribution (MIT-0)
+
+Copyright © CSSTools Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# PostCSS Alpha Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]
+
+`npm install @csstools/postcss-alpha-function --save-dev`
+
+[PostCSS Alpha Function] lets you use the `alpha` function in
+CSS, following the [CSS Color] specification.
+
+```css
+.color {
+	color: alpha(from #dddd / calc(alpha / 2));
+}
+
+:root {
+	--a-color: alpha(from rgb(2 1 0 / var(--a)) / calc(alpha / 2));
+}
+
+/* becomes */
+
+.color {
+	color: rgb(from #dddd r g b / calc(alpha / 2));
+}
+
+:root {
+	--a-color: rgb(from rgb(2 1 0 / var(--a)) r g b / calc(alpha / 2));
+}
+```
+
+## Usage
+
+Add [PostCSS Alpha Function] to your project:
+
+```bash
+npm install postcss @csstools/postcss-alpha-function --save-dev
+```
+
+Use it as a [PostCSS] plugin:
+
+```js
+const postcss = require('postcss');
+const postcssAlphaFunction = require('@csstools/postcss-alpha-function');
+
+postcss([
+	postcssAlphaFunction(/* pluginOptions */)
+]).process(YOUR_CSS /*, processOptions */);
+```
+
+
+
+## Options
+
+### preserve
+
+The `preserve` option determines whether the original notation
+is preserved. By default, it is not preserved.
+
+```js
+postcssAlphaFunction({ preserve: true })
+```
+
+```css
+.color {
+	color: alpha(from #dddd / calc(alpha / 2));
+}
+
+:root {
+	--a-color: alpha(from rgb(2 1 0 / var(--a)) / calc(alpha / 2));
+}
+
+/* becomes */
+
+.color {
+	color: rgb(from #dddd r g b / calc(alpha / 2));
+	color: alpha(from #dddd / calc(alpha / 2));
+}
+
+:root {
+	--a-color: rgb(from rgb(2 1 0 / var(--a)) r g b / calc(alpha / 2));
+}
+
+@supports (color: alpha(from red / 1)) and (color: rgb(0 0 0 / 0)) {
+:root {
+	--a-color: alpha(from rgb(2 1 0 / var(--a)) / calc(alpha / 2));
+}
+}
+```
+
+### enableProgressiveCustomProperties
+
+The `enableProgressiveCustomProperties` option determines whether the original notation
+is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.
+
+> [!NOTE]
+> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
+> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).
+
+```js
+postcssAlphaFunction({ enableProgressiveCustomProperties: false })
+```
+
+```css
+.color {
+	color: alpha(from #dddd / calc(alpha / 2));
+}
+
+:root {
+	--a-color: alpha(from rgb(2 1 0 / var(--a)) / calc(alpha / 2));
+}
+
+/* becomes */
+
+.color {
+	color: rgb(from #dddd r g b / calc(alpha / 2));
+	color: alpha(from #dddd / calc(alpha / 2));
+}
+
+:root {
+	--a-color: rgb(from rgb(2 1 0 / var(--a)) r g b / calc(alpha / 2));
+	--a-color: alpha(from rgb(2 1 0 / var(--a)) / calc(alpha / 2));
+}
+```
+
+_Custom properties do not fallback to the previous declaration_
+
+## Copyright : color conversions
+
+This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).
+
+[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
+[css-url]: https://cssdb.org/#alpha-function
+[discord]: https://discord.gg/bUadyRwkJS
+[npm-url]: https://www.npmjs.com/package/@csstools/postcss-alpha-function
+
+[PostCSS]: https://github.com/postcss/postcss
+[PostCSS Alpha Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-alpha-function
+[CSS Color]: https://drafts.csswg.org/css-color-5/#relative-alpha

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var e=require("@csstools/postcss-progressive-custom-properties"),o=require("@csstools/css-tokenizer"),s=require("@csstools/css-color-parser"),t=require("@csstools/utilities"),r=require("@csstools/css-parser-algorithms");const n=/\balpha\(/i,a=/^alpha$/i,l=new Set(["srgb","srgb-linear","display-p3","display-p3-linear","a98-rgb","prophoto-rgb","rec2020","xyz","xyz-d50","xyz-d65"]),basePlugin=e=>({postcssPlugin:"postcss-color-function",Declaration(i){const c=i.value;if(!n.test(c))return;if(t.hasFallback(i))return;if(t.hasSupportsAtRuleAncestor(i,n))return;const v=o.tokenize({css:c}),u=r.replaceComponentValues(r.parseCommaSeparatedListOfComponentValues(v),e=>{if(r.isFunctionNode(e)&&a.test(e.getName()))for(let t=0;t<e.value.length;t++){let n=e.value[t];for(;r.isWhiteSpaceOrCommentNode(n);)t++,n=e.value[t];for(r.isTokenNode(n)&&o.isTokenIdent(n.value)&&"from"===n.value[4].value.toLowerCase()&&(t++,n=e.value[t]);r.isWhiteSpaceOrCommentNode(n);)t++,n=e.value[t];const a=n;if(r.isFunctionNode(a)){const s=a.getName().toLowerCase();if("var"===s)return;if("color"===s){let s="";for(let e=0;e<a.value.length;e++){const t=a.value[e];if(r.isTokenNode(t)&&o.isTokenIdent(t.value)&&l.has(t.value[4].value.toLowerCase())){if(s)return;s=t.value[4].value}}if(!s)return;e.name[1]="color(",e.name[4].value="color";let n=["r","g","b"];return"xyz"!==s&&"xyz-d50"!==s&&"xyz-d65"!==s||(n=["x","y","z"]),void e.value.splice(t+1,0,new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,s,-1,-1,{value:s}]),new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[0],-1,-1,{value:n[0]}]),new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[1],-1,-1,{value:n[1]}]),new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[2],-1,-1,{value:n[2]}]))}switch(s){case"rgb":case"rgba":return void convertToRelativeColor(e,t+1,"rgb",["r","g","b"]);case"hsl":case"hsla":return void convertToRelativeColor(e,t+1,"hsl",["h","s","l"]);case"hwb":return void convertToRelativeColor(e,t+1,"hwb",["h","w","b"]);case"lab":return void convertToRelativeColor(e,t+1,"lab",["l","a","b"]);case"lch":return void convertToRelativeColor(e,t+1,"lch",["l","c","h"]);case"oklab":return void convertToRelativeColor(e,t+1,"oklab",["l","a","b"]);case"oklch":return void convertToRelativeColor(e,t+1,"oklch",["l","c","h"])}}if(r.isTokenNode(a)&&(o.isTokenHash(a.value)||o.isTokenIdent(a.value))){const o=s.color(a);if(!o)return;if(!o.syntaxFlags.has(s.SyntaxFlag.Hex)&&!o.syntaxFlags.has(s.SyntaxFlag.ColorKeyword))return;return void convertToRelativeColor(e,t+1,"rgb",["r","g","b"])}}}),p=r.stringify(u);p!==c&&(i.cloneBefore({value:p}),e?.preserve||i.remove())}});function convertToRelativeColor(e,s,t,n){e.name[1]=t+"(",e.name[4].value=t,e.value.splice(s,0,new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[0],-1,-1,{value:n[0]}]),new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[1],-1,-1,{value:n[1]}]),new r.WhitespaceNode([[o.TokenType.Whitespace," ",-1,-1,void 0]]),new r.TokenNode([o.TokenType.Ident,n[2],-1,-1,{value:n[2]}]))}basePlugin.postcss=!0;const postcssPlugin=o=>{const s=Object.assign({preserve:!1,enableProgressiveCustomProperties:!0},o);return s.enableProgressiveCustomProperties&&s.preserve?{postcssPlugin:"postcss-color-function",plugins:[e(),basePlugin(s)]}:basePlugin(s)};postcssPlugin.postcss=!0,module.exports=postcssPlugin;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { PluginCreator } from 'postcss';
+
+/** postcss-color-function plugin options */
+export declare type pluginOptions = {
+    /** Preserve the original notation. default: false */
+    preserve?: boolean;
+    /** Enable "@csstools/postcss-progressive-custom-properties". default: true */
+    enableProgressiveCustomProperties?: boolean;
+};
+
+/** Transform the color() function in CSS. */
+declare const postcssPlugin: PluginCreator<pluginOptions>;
+export default postcssPlugin;
+
+export { }

package/dist/index.mjs

@@ -0,0 +1 @@
+import e from"@csstools/postcss-progressive-custom-properties";import{tokenize as o,isTokenIdent as r,TokenType as s,isTokenHash as t}from"@csstools/css-tokenizer";import{color as l,SyntaxFlag as a}from"@csstools/css-color-parser";import{hasFallback as n,hasSupportsAtRuleAncestor as i}from"@csstools/utilities";import{replaceComponentValues as c,parseCommaSeparatedListOfComponentValues as v,isFunctionNode as u,isWhiteSpaceOrCommentNode as p,isTokenNode as d,WhitespaceNode as h,TokenNode as f,stringify as g}from"@csstools/css-parser-algorithms";const b=/\balpha\(/i,w=/^alpha$/i,m=new Set(["srgb","srgb-linear","display-p3","display-p3-linear","a98-rgb","prophoto-rgb","rec2020","xyz","xyz-d50","xyz-d65"]),basePlugin=e=>({postcssPlugin:"postcss-color-function",Declaration(C){const y=C.value;if(!b.test(y))return;if(n(C))return;if(i(C,b))return;const x=o({css:y}),R=c(v(x),e=>{if(u(e)&&w.test(e.getName()))for(let o=0;o<e.value.length;o++){let n=e.value[o];for(;p(n);)o++,n=e.value[o];for(d(n)&&r(n.value)&&"from"===n.value[4].value.toLowerCase()&&(o++,n=e.value[o]);p(n);)o++,n=e.value[o];const i=n;if(u(i)){const t=i.getName().toLowerCase();if("var"===t)return;if("color"===t){let t="";for(let e=0;e<i.value.length;e++){const o=i.value[e];if(d(o)&&r(o.value)&&m.has(o.value[4].value.toLowerCase())){if(t)return;t=o.value[4].value}}if(!t)return;e.name[1]="color(",e.name[4].value="color";let l=["r","g","b"];return"xyz"!==t&&"xyz-d50"!==t&&"xyz-d65"!==t||(l=["x","y","z"]),void e.value.splice(o+1,0,new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,t,-1,-1,{value:t}]),new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,l[0],-1,-1,{value:l[0]}]),new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,l[1],-1,-1,{value:l[1]}]),new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,l[2],-1,-1,{value:l[2]}]))}switch(t){case"rgb":case"rgba":return void convertToRelativeColor(e,o+1,"rgb",["r","g","b"]);case"hsl":case"hsla":return void convertToRelativeColor(e,o+1,"hsl",["h","s","l"]);case"hwb":return void convertToRelativeColor(e,o+1,"hwb",["h","w","b"]);case"lab":return void convertToRelativeColor(e,o+1,"lab",["l","a","b"]);case"lch":return void convertToRelativeColor(e,o+1,"lch",["l","c","h"]);case"oklab":return void convertToRelativeColor(e,o+1,"oklab",["l","a","b"]);case"oklch":return void convertToRelativeColor(e,o+1,"oklch",["l","c","h"])}}if(d(i)&&(t(i.value)||r(i.value))){const r=l(i);if(!r)return;if(!r.syntaxFlags.has(a.Hex)&&!r.syntaxFlags.has(a.ColorKeyword))return;return void convertToRelativeColor(e,o+1,"rgb",["r","g","b"])}}}),T=g(R);T!==y&&(C.cloneBefore({value:T}),e?.preserve||C.remove())}});function convertToRelativeColor(e,o,r,t){e.name[1]=r+"(",e.name[4].value=r,e.value.splice(o,0,new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,t[0],-1,-1,{value:t[0]}]),new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,t[1],-1,-1,{value:t[1]}]),new h([[s.Whitespace," ",-1,-1,void 0]]),new f([s.Ident,t[2],-1,-1,{value:t[2]}]))}basePlugin.postcss=!0;const postcssPlugin=o=>{const r=Object.assign({preserve:!1,enableProgressiveCustomProperties:!0},o);return r.enableProgressiveCustomProperties&&r.preserve?{postcssPlugin:"postcss-color-function",plugins:[e(),basePlugin(r)]}:basePlugin(r)};postcssPlugin.postcss=!0;export{postcssPlugin as default};

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@csstools/postcss-alpha-function",
+	"description": "Use the alpha() function in CSS",
+	"version": "1.0.0",
+	"contributors": [
+		{
+			"name": "Romain Menke",
+			"email": "romainmenke@gmail.com"
+		}
+	],
+	"license": "MIT-0",
+	"funding": [
+		{
+			"type": "github",
+			"url": "https://github.com/sponsors/csstools"
+		},
+		{
+			"type": "opencollective",
+			"url": "https://opencollective.com/csstools"
+		}
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"type": "module",
+	"main": "dist/index.cjs",
+	"module": "dist/index.mjs",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"CHANGELOG.md",
+		"LICENSE.md",
+		"README.md",
+		"dist"
+	],
+	"dependencies": {
+		"@csstools/css-color-parser": "^3.1.0",
+		"@csstools/css-parser-algorithms": "^3.0.5",
+		"@csstools/css-tokenizer": "^3.0.4",
+		"@csstools/postcss-progressive-custom-properties": "^4.2.0",
+		"@csstools/utilities": "^2.0.0"
+	},
+	"peerDependencies": {
+		"postcss": "^8.4"
+	},
+	"scripts": {},
+	"homepage": "https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-alpha-function#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/csstools/postcss-plugins.git",
+		"directory": "plugins/postcss-alpha-function"
+	},
+	"bugs": "https://github.com/csstools/postcss-plugins/issues",
+	"keywords": [
+		"alpha",
+		"color",
+		"css",
+		"design",
+		"postcss",
+		"postcss-plugin"
+	]
+}