postcss 8.3.8 → 8.4.0

package/README.md

@@ -40,493 +40,5 @@ at <postcss@evilmartians.com>.
 </a>
 
 
-## Sponsorship
-
-PostCSS needs your support. We are accepting donations
-[at Open Collective](https://opencollective.com/postcss/).
-
-<a href="https://tailwindcss.com/">
-  <img src="https://refactoringui.nyc3.cdn.digitaloceanspaces.com/tailwind-logo.svg"
-       alt="Sponsored by Tailwind CSS" width="213" height="50">
-</a>      <a href="https://themeisle.com/">
-  <img src="https://mllj2j8xvfl0.i.optimole.com/d0cOXWA.3970~373ad/w:auto/h:auto/q:90/https://s30246.pcdn.co/wp-content/uploads/2019/03/logo.png"
-       alt="Sponsored by ThemeIsle" width="171" height="56">
-</a>
-
-
-## Plugins
-
-Currently, PostCSS has more than 200 plugins. You can find all of the plugins
-in the [plugins list] or in the [searchable catalog]. Below is a list
-of our favorite plugins — the best demonstrations of what can be built
-on top of PostCSS.
-
-If you have any new ideas, [PostCSS plugin development] is really easy.
-
-[searchable catalog]: https://www.postcss.parts/
-[plugins list]:       https://github.com/postcss/postcss/blob/main/docs/plugins.md
-
-
-### Solve Global CSS Problem
-
-* [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
-  and execute them only for the current file.
-* [`postcss-modules`] and [`react-css-modules`] automatically isolate
-  selectors within components.
-* [`postcss-autoreset`] is an alternative to using a global reset
-  that is better for isolatable components.
-* [`postcss-initial`] adds `all: initial` support, which resets
-  all inherited styles.
-* [`cq-prolyfill`] adds container query support, allowing styles that respond
-  to the width of the parent.
-
-
-### Use Future CSS, Today
-
-* [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
-* [`postcss-preset-env`] allows you to use future CSS features today.
-
-
-### Better CSS Readability
-
-* [`postcss-nested`] unwraps nested rules the way Sass does.
-* [`postcss-sorting`] sorts the content of rules and at-rules.
-* [`postcss-utilities`] includes the most commonly used shortcuts and helpers.
-* [`short`] adds and extends numerous shorthand properties.
-
-
-### Images and Fonts
-
-* [`postcss-assets`] inserts image dimensions and inlines files.
-* [`postcss-sprites`] generates image sprites.
-* [`font-magician`] generates all the `@font-face` rules needed in CSS.
-* [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
-* [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
-* [`webp-in-css`] to use WebP image format in CSS background.
-* [`avif-in-css`] to use AVIF image format in CSS background.
-
-### Linters
-
-* [`stylelint`] is a modular stylesheet linter.
-* [`stylefmt`] is a tool that automatically formats CSS
-  according `stylelint` rules.
-* [`doiuse`] lints CSS for browser support, using data from Can I Use.
-* [`colorguard`] helps you maintain a consistent color palette.
-
-
-### Other
-
-* [`postcss-rtl`] combines both-directional (left-to-right and right-to-left) styles in one CSS file.
-* [`cssnano`] is a modular CSS minifier.
-* [`lost`] is a feature-rich `calc()` grid system.
-* [`rtlcss`] mirrors styles for right-to-left locales.
-
-[PostCSS plugin development]:   https://github.com/postcss/postcss/blob/main/docs/writing-a-plugin.md
-[`postcss-inline-svg`]:         https://github.com/TrySound/postcss-inline-svg
-[`postcss-preset-env`]:         https://github.com/jonathantneal/postcss-preset-env
-[`react-css-modules`]:          https://github.com/gajus/react-css-modules
-[`postcss-autoreset`]:          https://github.com/maximkoretskiy/postcss-autoreset
-[`postcss-write-svg`]:          https://github.com/jonathantneal/postcss-write-svg
-[`postcss-utilities`]:          https://github.com/ismamz/postcss-utilities
-[`postcss-initial`]:            https://github.com/maximkoretskiy/postcss-initial
-[`postcss-sprites`]:            https://github.com/2createStudio/postcss-sprites
-[`postcss-modules`]:            https://github.com/outpunk/postcss-modules
-[`postcss-sorting`]:            https://github.com/hudochenkov/postcss-sorting
-[`postcss-assets`]:             https://github.com/assetsjs/postcss-assets
-[`font-magician`]:              https://github.com/jonathantneal/postcss-font-magician
-[`autoprefixer`]:               https://github.com/postcss/autoprefixer
-[`cq-prolyfill`]:               https://github.com/ausi/cq-prolyfill
-[`postcss-rtl`]:                https://github.com/vkalinichev/postcss-rtl
-[`postcss-use`]:                https://github.com/postcss/postcss-use
-[`css-modules`]:                https://github.com/css-modules/css-modules
-[`webp-in-css`]:                https://github.com/ai/webp-in-css
-[`avif-in-css`]:                https://github.com/nucliweb/avif-in-css
-[`colorguard`]:                 https://github.com/SlexAxton/css-colorguard
-[`stylelint`]:                  https://github.com/stylelint/stylelint
-[`stylefmt`]:                   https://github.com/morishitter/stylefmt
-[`cssnano`]:                    https://cssnano.co/
-[`postcss-nested`]:             https://github.com/postcss/postcss-nested
-[`doiuse`]:                     https://github.com/anandthakker/doiuse
-[`rtlcss`]:                     https://github.com/MohammadYounes/rtlcss
-[`short`]:                      https://github.com/jonathantneal/postcss-short
-[`lost`]:                       https://github.com/peterramsing/lost
-
-## Syntaxes
-
-PostCSS can transform styles in any syntax, not just CSS.
-If there is not yet support for your favorite syntax,
-you can write a parser and/or stringifier to extend PostCSS.
-
-* [`sugarss`] is a indent-based syntax like Sass or Stylus.
-* [`postcss-syntax`] switch syntax automatically by file extensions.
-* [`postcss-html`] parsing styles in `<style>` tags of HTML-like files.
-* [`postcss-markdown`] parsing styles in code blocks of Markdown files.
-* [`postcss-jsx`] parsing CSS in template / object literals of source files.
-* [`postcss-styled`] parsing CSS in template literals of source files.
-* [`postcss-scss`] allows you to work with SCSS
-  *(but does not compile SCSS to CSS)*.
-* [`postcss-sass`] allows you to work with Sass
-    *(but does not compile Sass to CSS)*.
-* [`postcss-less`] allows you to work with Less
-  *(but does not compile LESS to CSS)*.
-* [`postcss-less-engine`] allows you to work with Less
-  *(and DOES compile LESS to CSS using true Less.js evaluation)*.
-* [`postcss-js`] allows you to write styles in JS or transform
-  React Inline Styles, Radium or JSS.
-* [`postcss-safe-parser`] finds and fixes CSS syntax errors.
-* [`midas`] converts a CSS string to highlighted HTML.
-
-[`postcss-less-engine`]: https://github.com/Crunch/postcss-less
-[`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
-[`postcss-syntax`]:      https://github.com/gucong3000/postcss-syntax
-[`postcss-html`]:        https://github.com/gucong3000/postcss-html
-[`postcss-markdown`]:    https://github.com/gucong3000/postcss-markdown
-[`postcss-jsx`]:         https://github.com/gucong3000/postcss-jsx
-[`postcss-styled`]:      https://github.com/gucong3000/postcss-styled
-[`postcss-scss`]:        https://github.com/postcss/postcss-scss
-[`postcss-sass`]:        https://github.com/AleshaOleg/postcss-sass
-[`postcss-less`]:        https://github.com/webschik/postcss-less
-[`postcss-js`]:          https://github.com/postcss/postcss-js
-[`sugarss`]:             https://github.com/postcss/sugarss
-[`midas`]:               https://github.com/ben-eb/midas
-
-
-## Articles
-
-* [Some things you may think about PostCSS… and you might be wrong](http://julian.io/some-things-you-may-think-about-postcss-and-you-might-be-wrong)
-* [What PostCSS Really Is; What It Really Does](https://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss/)
-* [PostCSS Guides](https://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
-
-More articles and videos you can find on [awesome-postcss](https://github.com/jjaderg/awesome-postcss) list.
-
-
-## Books
-
-* [Mastering PostCSS for Web Design](https://www.packtpub.com/web-development/mastering-postcss-web-design) by Alex Libby, Packt. (June 2016)
-
-
-## Usage
-
-You can start using PostCSS in just two steps:
-
-1. Find and add PostCSS extensions for your build tool.
-2. [Select plugins] and add them to your PostCSS process.
-
-[Select plugins]: https://www.postcss.parts/
-
-
-### CSS-in-JS
-
-The best way to use PostCSS with CSS-in-JS is [`astroturf`].
-Add its loader to your `webpack.config.js`:
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/,
-        use: ['style-loader', 'postcss-loader'],
-      },
-      {
-        test: /\.jsx?$/,
-        use: ['babel-loader', 'astroturf/loader'],
-      }
-    ]
-  }
-}
-```
-
-Then create `postcss.config.js`:
-
-```js
-module.exports = {
-  plugins: [
-    require('autoprefixer'),
-    require('postcss-nested')
-  ]
-}
-```
-
-[`astroturf`]: https://github.com/4Catalyzer/astroturf
-
-
-### Parcel
-
-[Parcel] has built-in PostCSS support. It already uses Autoprefixer
-and cssnano. If you want to change plugins, create `postcss.config.js`
-in project’s root:
-
-```js
-module.exports = {
-  plugins: [
-    require('autoprefixer'),
-    require('postcss-nested')
-  ]
-}
-```
-
-Parcel will even automatically install these plugins for you.
-
-> Please, be aware of [the several issues in Version 1](https://github.com/parcel-bundler/parcel/labels/CSS%20Preprocessing). Notice, [Version 2](https://github.com/parcel-bundler/parcel/projects/5) may resolve the issues via [issue #2157](https://github.com/parcel-bundler/parcel/issues/2157).
-
-[Parcel]: https://parceljs.org
-
-
-### Webpack
-
-Use [`postcss-loader`] in `webpack.config.js`:
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/,
-        exclude: /node_modules/,
-        use: [
-          {
-            loader: 'style-loader',
-          },
-          {
-            loader: 'css-loader',
-            options: {
-              importLoaders: 1,
-            }
-          },
-          {
-            loader: 'postcss-loader'
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Then create `postcss.config.js`:
-
-```js
-module.exports = {
-  plugins: [
-    require('autoprefixer'),
-    require('postcss-nested')
-  ]
-}
-```
-
-[`postcss-loader`]: https://github.com/postcss/postcss-loader
-
-
-### Gulp
-
-Use [`gulp-postcss`] and [`gulp-sourcemaps`].
-
-```js
-gulp.task('css', () => {
-  const postcss    = require('gulp-postcss')
-  const sourcemaps = require('gulp-sourcemaps')
-
-  return gulp.src('src/**/*.css')
-    .pipe( sourcemaps.init() )
-    .pipe( postcss([ require('autoprefixer'), require('postcss-nested') ]) )
-    .pipe( sourcemaps.write('.') )
-    .pipe( gulp.dest('build/') )
-})
-```
-
-[`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
-[`gulp-postcss`]:    https://github.com/postcss/gulp-postcss
-
-
-### npm Scripts
-
-To use PostCSS from your command-line interface or with npm scripts
-there is [`postcss-cli`].
-
-```sh
-postcss --use autoprefixer -o main.css css/*.css
-```
-
-[`postcss-cli`]: https://github.com/postcss/postcss-cli
-
-
-### Browser
-
-If you want to compile CSS string in browser (for instance, in live edit
-tools like CodePen), just use [Browserify] or [webpack]. They will pack
-PostCSS and plugins files into a single file.
-
-To apply PostCSS plugins to React Inline Styles, JSS, Radium
-and other [CSS-in-JS], you can use [`postcss-js`] and transforms style objects.
-
-```js
-const postcss  = require('postcss-js')
-const prefixer = postcss.sync([ require('autoprefixer') ])
-
-prefixer({ display: 'flex' }) //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
-```
-
-[`postcss-js`]: https://github.com/postcss/postcss-js
-[Browserify]:   http://browserify.org/
-[CSS-in-JS]:    https://github.com/MicheleBertoli/css-in-js
-[webpack]:      https://webpack.github.io/
-
-
-### Deno
-
-PostCSS also supports [Deno]:
-
-```js
-import postcss from 'https://deno.land/x/postcss/mod.js'
-import autoprefixer from 'https://jspm.dev/autoprefixer'
-
-const result = await postcss([autoprefixer]).process(css)
-```
-
-[Deno]: https://deno.land/
-
-
-### Runners
-
-* **Grunt**: [`@lodder/grunt-postcss`](https://github.com/C-Lodder/grunt-postcss)
-* **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
-* **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
-* **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
-* **Brunch**: [`postcss-brunch`](https://github.com/brunch/postcss-brunch)
-* **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
-* **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
-* **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
-* **Taskr**: [`taskr-postcss`](https://github.com/lukeed/taskr/tree/master/packages/postcss)
-* **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
-* **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
-
-
-### JS API
-
-For other environments, you can use the JS API:
-
-```js
-const autoprefixer = require('autoprefixer')
-const postcss = require('postcss')
-const postcssNested = require('postcss-nested')
-const fs = require('fs')
-
-fs.readFile('src/app.css', (err, css) => {
-  postcss([autoprefixer, postcssNested])
-    .process(css, { from: 'src/app.css', to: 'dest/app.css' })
-    .then(result => {
-      fs.writeFile('dest/app.css', result.css, () => true)
-      if ( result.map ) {
-        fs.writeFile('dest/app.css.map', result.map.toString(), () => true)
-      }
-    })
-})
-```
-
-Read the [PostCSS API documentation] for more details about the JS API.
-
-All PostCSS runners should pass [PostCSS Runner Guidelines].
-
-[PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/main/docs/guidelines/runner.md
-[PostCSS API documentation]: https://postcss.org/api/
-
-
-### Options
-
-Most PostCSS runners accept two parameters:
-
-* An array of plugins.
-* An object of options.
-
-Common options:
-
-* `syntax`: an object providing a syntax parser and a stringifier.
-* `parser`: a special syntax parser (for example, [SCSS]).
-* `stringifier`: a special syntax output generator (for example, [Midas]).
-* `map`: [source map options].
-* `from`: the input file name (most runners set it automatically).
-* `to`: the output file name (most runners set it automatically).
-
-[source map options]: https://postcss.org/api/#sourcemapoptions
-[Midas]:              https://github.com/ben-eb/midas
-[SCSS]:               https://github.com/postcss/postcss-scss
-
-
-### Treat Warnings as Errors
-
-In some situations it might be helpful to fail the build on any warning
-from PostCSS or one of its plugins. This guarantees that no warnings
-go unnoticed, and helps to avoid bugs. While there is no option to enable
-treating warnings as errors, it can easily be done
-by adding `postcss-fail-on-warn` plugin in the end of PostCSS plugins:
-
-```js
-module.exports = {
-  plugins: [
-    require('autoprefixer'),
-    require('postcss-fail-on-warn')
-  ]
-}
-```
-
-
-## Editors & IDE Integration
-
-
-### VS Code
-
-* [`csstools.postcss`] adds support for PostCSS, `postcss-preset-env`
-  and CSS Modules.
-
-[`csstools.postcss`]: https://marketplace.visualstudio.com/items?itemName=csstools.postcss
-
-
-### Atom
-
-* [`language-postcss`] adds PostCSS and [SugarSS] highlight.
-* [`source-preview-postcss`] previews your output CSS in a separate, live pane.
-
-[SugarSS]: https://github.com/postcss/sugarss
-
-
-### Sublime Text
-
-* [`Syntax-highlighting-for-PostCSS`] adds PostCSS highlight.
-
-[`Syntax-highlighting-for-PostCSS`]: https://github.com/hudochenkov/Syntax-highlighting-for-PostCSS
-[`source-preview-postcss`]:          https://atom.io/packages/source-preview-postcss
-[`language-postcss`]:                https://atom.io/packages/language-postcss
-
-
-### Vim
-
-* [`postcss.vim`] adds PostCSS highlight.
-
-[`postcss.vim`]: https://github.com/stephenway/postcss.vim
-
-
-### WebStorm
-
-WebStorm 2016.3 [has] built-in PostCSS support.
-
-[has]: https://blog.jetbrains.com/webstorm/2016/08/webstorm-2016-3-early-access-preview/
-
-
-## Security Contact
-
-To report a security vulnerability, please use the [Tidelift security contact].
-Tidelift will coordinate the fix and disclosure.
-
-[Tidelift security contact]: https://tidelift.com/security
-
-
-## For Enterprise
-
-Available as part of the Tidelift Subscription.
-
-The maintainers of `postcss` and thousands of other packages are working
-with Tidelift to deliver commercial support and maintenance for the open source
-dependencies you use to build your applications. Save time, reduce risk,
-and improve code health, while paying the maintainers of the exact dependencies
-you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-postcss?utm_source=npm-postcss&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
+## Docs
+Read **[full docs](https://github.com/postcss/postcss#readme)** on GitHub.

package/lib/container.d.ts

@@ -181,10 +181,10 @@ export default abstract class Container<
    */
   walkRules(
     selectorFilter: string | RegExp,
-    callback: (atRule: Rule, index: number) => false | void
+    callback: (rule: Rule, index: number) => false | void
   ): false | undefined
   walkRules(
-    callback: (atRule: Rule, index: number) => false | void
+    callback: (rule: Rule, index: number) => false | void
   ): false | undefined
 
   /**

package/lib/container.js

@@ -316,7 +316,7 @@ class Container extends Node {
     }
 
     let processed = nodes.map(i => {
-      // istanbul ignore next
+      /* c8 ignore next */
       if (!i[my]) Container.rebuild(i)
       i = i.proxyOf
       if (i.parent) i.parent.removeChild(i)
@@ -410,7 +410,7 @@ Container.registerAtRule = dependant => {
 module.exports = Container
 Container.default = Container
 
-// istanbul ignore next
+/* c8 ignore start */
 Container.rebuild = node => {
   if (node.type === 'atrule') {
     Object.setPrototypeOf(node, AtRule.prototype)
@@ -430,3 +430,4 @@ Container.rebuild = node => {
     })
   }
 }
+/* c8 ignore stop */

package/lib/css-syntax-error.d.ts

@@ -1,5 +1,20 @@
 import { FilePosition } from './input.js'
 
+/**
+ * A position that is part of a range.
+ */
+export interface RangePosition {
+  /**
+   * The line number in the input.
+   */
+  line: number
+
+  /**
+   * The column number in the input.
+   */
+  column: number
+}
+
 /**
  * The CSS parser throws this error for broken CSS.
  *
@@ -31,17 +46,21 @@ import { FilePosition } from './input.js'
  */
 export default class CssSyntaxError {
   /**
-   * @param message Error message.
-   * @param line    Source line of the error.
-   * @param column  Source column of the error.
-   * @param source  Source code of the broken file.
-   * @param file    Absolute path to the broken file.
-   * @param plugin  PostCSS plugin name, if error came from plugin.
+   * Instantiates a CSS syntax error. Can be instantiated for a single position
+   * or for a range.
+   * @param message        Error message.
+   * @param lineOrStartPos If for a single position, the line number, or if for
+   *                       a range, the inclusive start position of the error.
+   * @param columnOrEndPos If for a single position, the column number, or if for
+   *                       a range, the exclusive end position of the error.
+   * @param source         Source code of the broken file.
+   * @param file           Absolute path to the broken file.
+   * @param plugin         PostCSS plugin name, if error came from plugin.
    */
   constructor(
     message: string,
-    line?: number,
-    column?: number,
+    lineOrStartPos?: number | RangePosition,
+    columnOrEndPos?: number | RangePosition,
     source?: string,
     file?: string,
     plugin?: string
@@ -121,6 +140,34 @@ export default class CssSyntaxError {
    */
   column?: number
 
+  /**
+   * Source line of the error's end, exclusive. Provided if the error pertains
+   * to a range.
+   *
+   * ```js
+   * error.endLine       //=> 3
+   * error.input.endLine //=> 4
+   * ```
+   *
+   * PostCSS will use the input source map to detect the original location.
+   * If you need the position in the PostCSS input, use `error.input.endLine`.
+   */
+  endLine?: number
+
+  /**
+   * Source column of the error's end, exclusive. Provided if the error pertains
+   * to a range.
+   *
+   * ```js
+   * error.endColumn       //=> 1
+   * error.input.endColumn //=> 4
+   * ```
+   *
+   * PostCSS will use the input source map to detect the original location.
+   * If you need the position in the PostCSS input, use `error.input.endColumn`.
+   */
+  endColumn?: number
+
   /**
    * Source code of the broken file.
    *

package/lib/css-syntax-error.js

@@ -1,6 +1,6 @@
 'use strict'
 
-let { red, bold, gray, isColorSupported } = require('nanocolors')
+let pico = require('picocolors')
 
 let terminalHighlight = require('./terminal-highlight')
 
@@ -20,8 +20,15 @@ class CssSyntaxError extends Error {
       this.plugin = plugin
     }
     if (typeof line !== 'undefined' && typeof column !== 'undefined') {
-      this.line = line
-      this.column = column
+      if (typeof line === 'number') {
+        this.line = line
+        this.column = column
+      } else {
+        this.line = line.line
+        this.column = line.column
+        this.endLine = column.line
+        this.endColumn = column.column
+      }
     }
 
     this.setMessage()
@@ -44,7 +51,7 @@ class CssSyntaxError extends Error {
     if (!this.source) return ''
 
     let css = this.source
-    if (color == null) color = isColorSupported
+    if (color == null) color = pico.isColorSupported
     if (terminalHighlight) {
       if (color) css = terminalHighlight(css)
     }
@@ -57,6 +64,7 @@ class CssSyntaxError extends Error {
 
     let mark, aside
     if (color) {
+      let { bold, red, gray } = pico.createColors(true)
       mark = text => bold(red(text))
       aside = text => gray(text)
     } else {