postcss-custom-properties - npm Package Compare versions

Comparing version 6.2.0 to 6.3.0

CHANGELOG.md

@@ -0,1 +1,10 @@
+# 6.3.0 - 2018-02-15
+
+- Fixed: `var()` captures strictly `var()` functions and not `xvar()`, etc
+- Fixed: `var()` better captures whitespace within the function
+- Fixed: comments within declarations using `var()` are now preserved
+- Changed: `preserve` option defaults as `true` to reflect the browser climate
+- Changed: `warnings` option defaults to `false` to reflect the browser climate
+- Updated documentation
+
 # 6.2.0 - 2017-10-06
@@ -2,0 +11,0 @@

dist/index.js

@@ -19,4 +19,5 @@ "use strict";
 var VAR_FUNC_IDENTIFIER = "var";
+var VAR_FUNC_REGEX = /(^|[^\w-])var\(/;
 // matches `name[, fallback]`, captures "name" and "fallback"
-var RE_VAR = /([\w-]+)(?:\s*,\s*)?\s*(.*)?/;
+var RE_VAR = /[\f\n\r\t ]*([\w-]+)(?:[\f\n\r\t ]*,[\f\n\r\t ]*([\W\w]+))?/;
 
@@ -44,7 +45,11 @@ /**
 
-  var start = value.indexOf(VAR_FUNC_IDENTIFIER + "(");
-  if (start === -1) {
+  var hasVarFunction = VAR_FUNC_REGEX.test(value);
+
+  if (!hasVarFunction) {
     return [value];
   }
 
+  var match = value.match(VAR_FUNC_REGEX);
+  var start = match.index + match[1].length;
+
   var matches = (0, _balancedMatch2.default)("(", ")", value.substring(start));
@@ -165,5 +170,5 @@
     var variables = prefixVariables(options.variables);
-    var strict = options.strict === undefined ? true : options.strict;
-    var appendVariables = options.appendVariables;
-    var preserve = options.preserve;
+    var strict = "strict" in options ? Boolean(options.strict) : true;
+    var appendVariables = "appendVariables" in options ? Boolean(options.appendVariables) : false;
+    var preserve = "preserve" in options ? options.preserve : true;
     var map = {};
@@ -173,4 +178,4 @@ var importantMap = {};
     globalOpts = {
-      warnings: options.warnings === undefined ? true : options.warnings,
-      noValueNotifications: options.noValueNotifications || "warning"
+      warnings: "warnings" in options ? Boolean(options.warnings) : false,
+      noValueNotifications: "noValueNotifications" in options ? String(options.noValueNotifications) : "warning"
 
@@ -243,3 +248,3 @@ // define variables
     style.walkDecls(function (decl) {
-      var value = decl.value;
+      var value = decl.raws.value ? decl.raws.value.raw : decl.value;
 
@@ -246,0 +251,0 @@ // skip values that don’t contain variable functions

package.json

 {
   "name": "postcss-custom-properties",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "PostCSS plugin to polyfill W3C CSS Custom Properties for cascading variables",
@@ -22,3 +22,3 @@ "keywords": [
     "balanced-match": "^1.0.0",
-    "postcss": "^6.0.13"
+    "postcss": "^6.0.18"
   },
@@ -28,5 +28,5 @@ "devDependencies": {
     "babel-plugin-add-module-exports": "^0.2.1",
-    "babel-preset-env": "^1.6.0",
+    "babel-preset-env": "^1.6.1",
     "babel-register": "^6.26.0",
-    "eslint": "^4.8.0",
+    "eslint": "^4.17.0",
     "npmpub": "^3.1.0",
@@ -33,0 +33,0 @@ "tape": "^4.8.0"

README.md

@@ -1,22 +0,30 @@
-# postcss-custom-properties [![CSS Standard Status](https://jonathantneal.github.io/css-db/badge/css-variables.svg)](https://jonathantneal.github.io/css-db/#css-variables) [![Build Status](https://travis-ci.org/postcss/postcss-custom-properties.svg)](https://travis-ci.org/postcss/postcss-custom-properties)
+# PostCSS Custom Properties [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]
 
-> [PostCSS](https://github.com/postcss/postcss) plugin to transform [W3C CSS Custom Properties for ~~cascading~~ variables](http://www.w3.org/TR/css-variables/) syntax to more compatible CSS.
+[![NPM Version][npm-img]][npm-url]
+[![CSS Standard Status][css-img]][css-url]
+[![Build Status][cli-img]][cli-url]
+[![Gitter Chat][git-img]][git-url]
 
-_Per w3c specifications, the usage of `var()` is limited to property values. Do not expect the plugin to transform `var()` in media queries or in selectors._
+[PostCSS Custom Properties] lets you use CSS Custom Properties in CSS, following
+the [CSS Custom Properties for Cascading Variables] specification.
 
-**N.B.** The transformation _is not complete_ and **cannot be** (dynamic *cascading* variables based on custom properties relies on the DOM tree).
-It currently just aims to provide a future-proof way of using a **limited subset (to `:root` selector)** of the features provided by native CSS custom properties.
-_Since we do not know the DOM in the context of this plugin, we cannot produce safe output_.
-Read [#1](https://github.com/postcss/postcss-custom-properties/issues/1) & [#9](https://github.com/postcss/postcss-custom-properties/issues/9) to know why this limitation exists.
+```css
+:root {
+  --color: red;
+}
 
-_If you are looking for a full support of CSS custom properties, please follow [the opened issue for runtime support](https://github.com/postcss/postcss-custom-properties/issues/32)._
+h1 {
+  color: var(--color);
+}
 
-**N.B.²** If you are wondering why there is a different plugin ([`postcss-css-variables`](https://github.com/MadLittleMods/postcss-css-variables)) that claims to do more than this plugin, be sure to understand the explanation above about limitation. This plugins have a behavior that is not [reflecting the specifications](https://github.com/MadLittleMods/postcss-css-variables/issues/4).
+/* becomes */
 
-_This plugin works great with [postcss-calc](https://github.com/postcss/postcss-calc)._
+:root {
+  --color: red;
+}
 
-## Installation
-
-```console
-$ npm install postcss-custom-properties
+div {
+  color: red;
+  color: var(--color);
+}
 ```
@@ -26,20 +34,97 @@
 
+Add [PostCSS Custom Properties] to your build tool:
+
+```bash
+npm install postcss-custom-properties --save-dev
+```
+
+#### Node
+
+Use [PostCSS Custom Properties] to process your CSS:
+
 ```js
-// dependencies
-var fs = require("fs")
-var postcss = require("postcss")
-var customProperties = require("postcss-custom-properties")
+import postCSSCustomProperties from 'postcss-custom-properties';
 
-// css to be processed
-var css = fs.readFileSync("input.css", "utf8")
+postCSSCustomProperties.process(YOUR_CSS);
+```
 
-// process css using postcss-custom-properties
-var output = postcss()
-  .use(customProperties())
-  .process(css)
-  .css
+#### PostCSS
+
+Add [PostCSS] to your build tool:
+
+```bash
+npm install postcss --save-dev
 ```
 
-Using this `input.css`:
+Use [PostCSS Custom Properties] as a plugin:
 
+```js
+import postcss from 'gulp-postcss';
+import postCSSCustomProperties from 'postcss-custom-properties';
+
+postcss([
+  postCSSCustomProperties()
+]).process(YOUR_CSS);
+```
+
+#### Gulp
+
+Add [Gulp PostCSS] to your build tool:
+
+```bash
+npm install gulp-postcss --save-dev
+```
+
+Use [PostCSS Custom Properties] in your Gulpfile:
+
+```js
+import postcss from 'gulp-postcss';
+import postCSSCustomProperties from 'postcss-custom-properties';
+
+gulp.task('css', () => gulp.src('./src/*.css').pipe(
+  postcss([
+    postCSSCustomProperties()
+  ])
+).pipe(
+  gulp.dest('.')
+));
+```
+
+#### Grunt
+
+Add [Grunt PostCSS] to your build tool:
+
+```bash
+npm install grunt-postcss --save-dev
+```
+
+Use [PostCSS Custom Properties] in your Gruntfile:
+
+```js
+import postCSSCustomProperties from 'postcss-custom-properties';
+
+grunt.loadNpmTasks('grunt-postcss');
+
+grunt.initConfig({
+  postcss: {
+    options: {
+      use: [
+       postCSSCustomProperties()
+      ]
+    },
+    dist: {
+      src: '*.css'
+    }
+  }
+});
+```
+
+## Options
+
+### strict
+
+The `strict` option determines whether a `var()` function should transform into
+its specified fallback value. By default, the option is `true` because this
+plugin can not verify if the computed `:root` value is valid or not.
+
 ```css
@@ -51,113 +136,214 @@ :root {
 div {
-  color: var(--color);
+  color: var(--color, blue);
 }
-```
 
-you will get:
+/* becomes */
 
-```css
+:root {
+  --color: red;
+}
+
 div {
-  color: red;
+  color: blue;
+  color: var(--color, blue);
 }
 ```
 
-You can also compile CSS custom properties with their fallback value.
+### preserve
 
-Using this `input.css`:
+The `preserve` option determines how Custom Properties should be preserved. By
+default, this option is truthy and preserves declarations containing `var()`.
 
 ```css
-div {
-  color: var(--color, #f00);
+:root {
+  --color: red;
 }
-```
 
-you will get:
+h1 {
+  color: var(--color);
+}
 
-```css
-div {
-  color: #f00;
+/* becomes */
+
+:root {
+  --color: red;
 }
+
+h1 {
+  color: red;
+  color: var(--color);
+}
 ```
 
-Note that plugin returns itself in order to expose a `setVariables` function
-that allow you to programmatically change the variables.
+The option may also be set to `false`, where Custom Properties and declarations
+containing `var()` will be removed:
 
 ```js
-var variables = {
-  "--a": "b",
+postCSSCustomProperties({
+  variables: {
+    preserve: false
+  }
+})
+```
+
+```css
+:root {
+  --color: red;
 }
-var plugin = customProperties()
-plugin.setVariables(variables)
-var result = postcss()
-  .use(plugin)
-  .process(input)
+
+h1 {
+  color: var(--color);
+}
+
+/* becomes */
+
+h1 {
+  color: red;
+}
 ```
 
-This might help for dynamic live/hot reloading.
+The option may also be set to `"preserve-computed"`, where Custom Properties
+will remain, but declarations containing `var()` will be removed:
 
-Checkout [tests](test) for more.
+```js
+postCSSCustomProperties({
+  variables: {
+    preserve: 'preserve-computed'
+  }
+})
+```
 
-### Options
+```css
+:root {
+  --color: red;
+}
 
-#### `strict`
+h1 {
+  color: var(--color);
+}
 
-Default: `true`
+/* becomes */
 
-Per specifications, all fallbacks should be added since we can't verify if a
-computed value is valid or not.
-This option allows you to avoid adding too many fallback values in your CSS.
+:root {
+  --color: red;
+}
 
-#### `preserve`
+h1 {
+  color: red;
+}
+```
 
-Default: `false`
+### variables
 
-Allows you to preserve custom properties & var() usage in output.
+The `variables` option allows you to pass an object of variables into CSS, as if
+they had been specified on `:root`.
 
 ```js
-var out = postcss()
-  .use(customProperties({preserve: true}))
-  .process(css)
-  .css
+postCSSCustomProperties({
+  variables: {
+    color: 'red'
+  }
+})
 ```
 
-You can also set `preserve: "computed"` to get computed resolved custom
-properties in the final output.
-Handy to make them available to your JavaScript.
+```css
+h1 {
+  color: var(--color);
+}
 
-#### `variables`
+/* becomes */
 
-Default: `{}`
+h1 {
+  color: red;
+  color: var(--color);
+}
+```
 
-Allows you to pass an object of variables for `:root`. These definitions will
-override any that exist in the CSS.
-The keys are automatically prefixed with the CSS `--` to make it easier to share
+Note that these definitions will override any that exist in the CSS, and that
+the keys will be automatically prefixed (`--`) to make it easier to share
 variables in your codebase.
 
-#### `appendVariables`
+### appendVariables
 
-Default: `false`
+The `appendVariables` option determines whether Custom Properties will be
+appended to your CSS file. By default, this option is `false`.
 
-If `preserve` is set to `true` (or `"computed"`), allows you to append your
-variables at the end of your CSS.
+If enabled when `preserve` is set to `true` or `"computed"`, this option allows
+you to append your variables at the end of your CSS:
 
-#### `warnings`
+```js
+postCSSCustomProperties({
+  appendVariables: true,
+  variables: {
+    color: 'red'
+  }
+})
+```
 
-Default: `true`
-Type: `Boolean|Object`
+```css
+h1 {
+  color: var(--color);
+}
 
-Allows you to enable/disable warnings. If true, will enable all warnings.
-For now, it only allow to disable messages about custom properties definition
-not scoped in a `:root` selector.
+/* becomes */
 
+h1 {
+  color: red;
+  color: var(--color);
+}
 
-### `noValueNotifications`
+:root {
+  --color: red;
+}
+```
 
-Default: `'warning'`
-Values: `'warning'|'error'`
+### warnings
 
-If it is set to `'error'`, using of undefined variable will throw an error.
+The `warnings` option determines whether Custom Property related warnings should
+be logged by the plugin or not. By default, warnings are set to `false` and are
+not logged.
 
+If enabled, the plugin will enable all warnings:
 
+```js
+postCSSCustomProperties({
+  warnings: true
+})
+```
+
+```css
+h1 {
+  color: var(--color);
+}
+```
+
+```
+variable '--color' is undefined and used without a fallback
+```
+
+### noValueNotifications
+
+When warnings are enabled, the `noValueNotifications` option determines whether
+undefined variables will throw a warning or an error. By default, it is set to
+`warning`.
+
 ---
 
+## Notes
+
+As written in the specification, usage of `var()` is limited to property values.
+Do not expect the plugin to transform `var()` in media queries or in selectors.
+
+The transformation of Custom Properties done by this plugin _is not complete_
+and **cannot be** because dynamic *cascading* variables based on custom
+properties relies on the DOM tree. Since we do not know the DOM in the context
+of this plugin, we cannot produce safe output. This plugin currently aims to
+provide a future-proof way of using a **limited subset** of the features
+provided by native CSS custom properties.
+
+There is a separate plugin, [PostCSS CSS Variables], that attempts to guess the
+context of Custom Properties without access to the DOM tree. This does not
+[reflecting the specifications](https://github.com/MadLittleMods/postcss-css-variables/issues/4),
+so be sure you understand the risks before you decide to use it.
+
 ## Contributing
@@ -167,3 +353,3 @@
 
-```console
+```bash
 $ git clone https://github.com/YOU/postcss-custom-properties.git
@@ -175,4 +361,22 @@ $ git checkout -b patch-1
 
+---
+
 ## [Changelog](CHANGELOG.md)
 
 ## [License](LICENSE)
+
+[npm-url]: https://www.npmjs.com/package/postcss-custom-properties
+[npm-img]: https://img.shields.io/npm/v/postcss-custom-properties.svg
+[css-url]: https://jonathantneal.github.io/css-db/#css-variables
+[css-img]: https://jonathantneal.github.io/css-db/badge/css-variables.svg
+[cli-url]: https://travis-ci.org/postcss/postcss-custom-properties
+[cli-img]: https://img.shields.io/travis/postcss/postcss-custom-properties.svg
+[git-url]: https://gitter.im/postcss/postcss
+[git-img]: https://img.shields.io/badge/chat-gitter-blue.svg
+
+[CSS Custom Properties for Cascading Variables]: https://www.w3.org/TR/css-variables-1/
+[PostCSS CSS Variables]: https://github.com/MadLittleMods/postcss-css-variables
+[PostCSS Custom Properties]: https://github.com/postcss/postcss-custom-properties
+[PostCSS]: https://github.com/postcss/postcss
+[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
+[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss

No alert changes

Improved metrics

Total package byte prevSize

22330

increased by16.93%

Lines of code

247

increased by1.23%

Number of lines in readme file

379

increased by116.57%

Dependency changes

• Updatedpostcss@^6.0.18