@csstools/postcss-image-function 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changes to PostCSS Image Function
+
+### 1.0.0
+
+_May 13, 2026_
+
+- Initial version
+- Updated [`@csstools/postcss-progressive-custom-properties`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties) to [`5.1.0`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties/CHANGELOG.md#510) (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,93 @@
+# PostCSS Image Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]
+
+`npm install @csstools/postcss-image-function --save-dev`
+
+[PostCSS Image Function] lets you easily generate a solid-color image from any color following the [CSS Images 4 Specification].
+
+```css
+.foo {
+	background-image: image(transparent);
+}
+
+.foo {
+	--bg-image: image(transparent);
+}
+
+/* becomes */
+
+.foo {
+	background-image: linear-gradient(transparent,transparent);
+}
+
+.foo {
+	--bg-image: linear-gradient(transparent,transparent);
+}
+```
+
+## Usage
+
+Add [PostCSS Image Function] to your project:
+
+```bash
+npm install postcss @csstools/postcss-image-function --save-dev
+```
+
+Use it as a [PostCSS] plugin:
+
+```js
+const postcss = require('postcss');
+const postcssImageFunction = require('@csstools/postcss-image-function');
+
+postcss([
+	postcssImageFunction(/* pluginOptions */)
+]).process(YOUR_CSS /*, processOptions */);
+```
+
+
+
+## Options
+
+### preserve
+
+The `preserve` option determines whether the original notation
+is preserved. By default, it is not preserved.
+
+```js
+postcssImageFunction({ preserve: true })
+```
+
+```css
+.foo {
+	background-image: image(transparent);
+}
+
+.foo {
+	--bg-image: image(transparent);
+}
+
+/* becomes */
+
+.foo {
+	background-image: linear-gradient(transparent,transparent);
+	background-image: image(transparent);
+}
+
+.foo {
+	--bg-image: linear-gradient(transparent,transparent);
+}
+
+@supports (background-image: image(red)) {
+.foo {
+	--bg-image: image(transparent);
+}
+}
+```
+
+[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
+[css-url]: https://cssdb.org/#image-function
+[discord]: https://discord.gg/bUadyRwkJS
+[npm-url]: https://www.npmjs.com/package/@csstools/postcss-image-function
+
+[PostCSS]: https://github.com/postcss/postcss
+[PostCSS Image Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-image-function
+[CSS Images 4 Specification]: https://drafts.csswg.org/css-images-4/#funcdef-image

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { PluginCreator } from 'postcss';
+
+/** postcss-image-function plugin options */
+export declare type basePluginOptions = {
+    /** Preserve the original notation. default: false */
+    preserve?: boolean;
+};
+
+/** postcss-image-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 image() functions in CSS. */
+declare const postcssPlugin: PluginCreator<pluginOptions>;
+export default postcssPlugin;
+export { postcssPlugin as 'module.exports' }
+
+export { }

package/dist/index.mjs

@@ -0,0 +1 @@
+import e from"@csstools/postcss-progressive-custom-properties";import{hasFallback as s,hasSupportsAtRuleAncestor as o}from"@csstools/utilities";import{replaceComponentValues as t,parseCommaSeparatedListOfComponentValues as r,isFunctionNode as i,isWhiteSpaceOrCommentNode as n,FunctionNode as a,TokenNode as c,stringify as l}from"@csstools/css-parser-algorithms";import{tokenize as m,TokenType as p}from"@csstools/css-tokenizer";const u=/\bimage\(/i,g=/^image$/i,basePlugin=e=>({postcssPlugin:"postcss-image-function",Declaration(v){const f=v.value;if(!u.test(f))return;if(s(v))return;if(o(v,u))return;const d=t(r(m({css:f})),e=>{if(i(e)&&g.test(e.getName())&&1===e.value.filter(e=>!n(e)).length)return new a([p.Function,"linear-gradient(",e.name[2],e.name[3],{value:"linear-gradient"}],e.endToken,[...e.value,new c([p.Comma,",",e.name[2],e.name[3],void 0]),...e.value])}),P=l(d);P!==f&&(v.cloneBefore({value:P}),e?.preserve||v.remove())}});basePlugin.postcss=!0;const postcssPlugin=s=>{const o=Object.assign({preserve:!1,enableProgressiveCustomProperties:!0},s);return o.enableProgressiveCustomProperties&&o.preserve?{postcssPlugin:"postcss-image-function",plugins:[e(),basePlugin(o)]}:basePlugin(o)};postcssPlugin.postcss=!0;export{postcssPlugin as default,postcssPlugin as"module.exports"};

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@csstools/postcss-image-function",
+	"description": "Generate a solid-color image from any color",
+	"version": "1.0.0",
+	"contributors": [
+		{
+			"name": "Antonio Laguna",
+			"email": "antonio@laguna.es",
+			"url": "https://antonio.laguna.es"
+		},
+		{
+			"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": ">=20.19.0"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.mjs"
+		}
+	},
+	"files": [
+		"CHANGELOG.md",
+		"LICENSE.md",
+		"README.md",
+		"dist"
+	],
+	"dependencies": {
+		"@csstools/css-parser-algorithms": "^4.0.0",
+		"@csstools/css-tokenizer": "^4.0.0",
+		"@csstools/postcss-progressive-custom-properties": "^5.1.0",
+		"@csstools/utilities": "^3.0.0"
+	},
+	"peerDependencies": {
+		"postcss": "^8.4"
+	},
+	"scripts": {},
+	"homepage": "https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-image-function#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/csstools/postcss-plugins.git",
+		"directory": "plugins/postcss-image-function"
+	},
+	"bugs": "https://github.com/csstools/postcss-plugins/issues",
+	"keywords": [
+		"csswg",
+		"fallback",
+		"image function",
+		"postcss-plugin"
+	]
+}