csstree

• Added support for the @container at-rule
• Added support for the @starting-style at-rule
• Added support for the @scope at-rule
• Added support for the @position-try at-rule
• Added support for the @layer at-rule
• Added support for layer, layer() and supports() in the @media at-rule (according to the @import rule in Cascading and Inheritance 5)
• Added Layer and LayerList node types
• Added TokenStream#lookupTypeNonSC() method
• Added <dashed-ident> to generic types
• Bumped mdn/data to 2.10.0
• Aligned <'font'> to CSS Fonts 4
• Aligned <color> to CSS Color 5
• Fixed initialization when Object.prototype is extended or polluted (#262)
• Fixed fork() method to consider the generic option when creating a Lexer instance (#266)
• Fixed crash on parse error when custom line or offset is specified via options (#251)
• Fixed speak syntax patch (#241)
• Fixed :lang() to accept a list of <ident> or <string> per spec (#265)
• Fixed lexer matching for syntaxes referred to as <'property'>, when the syntax has a top-level #-multiplier (#102)
• Relaxed parsing of syntax definition to allow whitespaces in range multiplier (#270)
• Changed parseWithFallback() to rollback tokenIndex before calling a fallback
• Changed Block to not include { and }
• Changed Atrule and Rule to include { and } for a block
• Changed Ratio parsing:
  • Left and right parts contain nodes instead of strings
  • Both left and right parts of a ratio can now be any number; validation of number range is no longer within the parser's scope.
  • Both parts can now be functions. Although not explicitly mentioned in the specification, mathematical functions can replace numbers, addressing potential use cases (#162).
  • As per the CSS Values and Units Level 4 specification, the right part of Ratio can be omitted. While this can't be a parser output (which would produce a Number node), it's feasible during Ratio node construction or transformation.
• Changes to query-related at-rules:
  • Added new node types:
    • Feature: represents features like (feature) and (feature: value), fundamental for both @media and @container at-rules
    • FeatureRange: represents features in a range context
    • FeatureFunction: represents functional features such as @supports's selector() or @container's style()
    • Condition: used across all query-like at-rules, encapsulating queries with features and the not, and, and or operators
    • GeneralEnclosure: represents the <general-enclosed> production, which caters to unparsed parentheses or functional expressions

    Note: All new nodes include a kind property to define the at-rule type. Supported kinds are media, supports, and container

  • Added support for functions for features and features in a range context, e.g. (width: calc(100cm / 6))
  • Added a condition value for the parser's context option to parse queries. Use the kind option to specify the condition type, e.g., parse('...', { context: 'condition', kind: 'media' })
  • Introduced a features section in the syntax configuration for defining functional features of at-rules. Expand definitions using the fork() method. The current definition is as follows:

    features: {
        supports: { selector() { /* ... */ } },
        container: { style() { /* ... */ } }
    }
    

  • Changes for @media at-rule:
    • Enhanced prelude parsing for complex queries. Parentheses with errors will be parsed as GeneralEnclosed
    • Added support for features in a range context, e.g. (width > 100px) or (100px < height < 400px)
    • Transitioned from MediaFeature node type to the Feature node type with kind: "media"
    • Changed MediaQuery node structure into the following form:

      type MediaQuery = {
          type: "MediaQuery";
          modifier: string | null; // e.g. "not", "only", etc.
          mediaType: string | null; // e.g. "all", "screen", etc.
          condition: Condition | null;
      }
      

  • Changes for @supports at-rule:
    • Enhanced prelude parsing for complex queries. Parentheses with errors will be parsed as GeneralEnclosed
    • Added support for features in a range context, e.g. (width > 100px) or (100px < height < 400px)
    • Added SupportsDeclaration node type to encapsulate a declaration in a query, replacing Parentheses
    • Parsing now employs Condition or SupportsDeclaration nodes of kind supports instead of Parentheses
    • Added support for the selector() feature via the FeatureFunction node (configured in features.supports.selector)

• Added :host, :host() and :host-context() pseudo class support (#216)
• Fixed generator, parse and parse-selector entry points by adding missed NestedSelector node type
• Removed npm > 7 version requirement (#218)

• Added CSS Nesting support:
  • Added NestingSelector node type for & (a nesting selector) in selectors
  • Added @nest at-rule
  • Changed behaviour for @media inside a Rule to parse its block content as a Declaration first
  • Changed DeclarationList behaviour to follow the rules for Rule's block
• Added the dimension units introspection & customisation:
  • Added Lexer#units dictionary to provide unit groups (length, angle, etc.) used for matching
  • Changed Lexer's constructor to take into consideration config.units to override default units
  • Extended lexer's dump to contain a units dictionary
• Bumped mdn-data to 2.0.30

• Fixed a regression added in 2.2.0 for at-rule syntax matching when at-rule has no prelude (#203)

• Bumped mdn-data to 2.0.28
• Added support for CSS wide keywords revert and revert-layer
• Dropped support for expression() the same way as CSS wide keywords
• Patched background-clip property definition to match Backgrounds and Borders 4 (#190)
• Patched content property definition to allow attr() (#201)
• Fixed definition syntax matching when a comma is expected before a <delim-token>
• Fixed at-rule validation fail when no prelude is specified and its syntax allows an empty prelude, that's the case for @page at-rule (#191)
• Added new units according to current state of CSS Values and Units 4: rex, cap, rcap, rch, ic, ric, lh, rlh, vi, vb, sv*, lv*, dv*
• Added container relative length units from CSS Containment 3: cqw, cqh, cqi, cqb, cqmin, cqmax
• Removed vm unit (supposed to be an old IE versions supported this unit instead of vmax)
• Value definition syntax:
  • Added support for stacked multipliers +# and #? according to spec (#199)
  • Added parsing of a dimension in range definition notations, however, a validation for such ranges is not supported yet (#192)
  • Changed parsing of range definition notation to not omitting [-∞,∞] ranges

• Bumped mdn-data to 2.0.27
• Added module field to package.json
• Fixed minor issues in CommonJS version
• Fixed css-tree/utils export (#181)
• Added css-tree/convertor export
• Added css-tree/selector-parser export (~27kb when bundled, #183)
• Reduced bundle size:
  • css-tree/parser 50kb -> 41kb
  • css-tree/generator 46kb -> 23kb
• Renamed syntaxes into types in css-tree/definition-syntax-data-patch
• Added parsing support for :is(), :-moz-any(), :-webkit-any() and :where() (#182, #184)

• Extended Node.js support to include ^10
• Fixed generate() in safe mode to add a whitespace between <dimension-token> and <hash-token>, otherwise some values are broken in IE11, e.g. border properties (#173)
• Removed allowance for : for an attribute name on AttributeSelector parsing as it does not meet the CSS specs (details)

• Fixed unintended whitespace on generate() in safe mode between type-selector and id-selector (e.g. a#id). A regression was introduces in 2.0.2 since IE11 fails on values when <hash-token> goes after <ident-token> without a whitespace in the middle, e.g. 1px solid#000. Thus, in one case, a space between the <ident-token> and the <hash-token> is required, and in the other, vice versa. Until a better solution found, a workaround is used on id-selector generation by producing a <delim-token> instead of <hash-token>.

• Updated width, min-width and max-width syntax definitions
• Patched counter related syntaxes to match specs until updated in mdn-data
• Replaced source-map with source-map-js which reduce install size by ~700KB
• Fixed calc() function consumption on definition syntax matching
• Fixed generate() auto emitting a whitespace edge cases when next token starts with a dash (minus)
• Fixed generate() safe mode to cover more cases for IE11
• Fixed CommonJS bundling by adding browser files dist/data.cjs and dist/version.cjs
• Added exports:
  • css-tree/definition-syntax-data
  • css-tree/definition-syntax-data-patch

• Extended Node.js support to include ^12.20.0 and ^14.13.0 versions

ES2020 syntax and support for ESM

The source code was refactored to use ES2020 syntax and ES modules by default. However, Commonjs version of library is still supported, so the package became a dual module. Using ESM allowed to reduce bundle size from 167Kb down to 164Kb despite that mdn-data grew up in size by 11Kb.

In case only a part of CSSTree functionality is used (for instance only for a parsing), it's possible now to use specific exports like css-tree/parser (see the full list of exports) to reduce a bundle size. As new package mechanics are used, the minimal version for Node.js was changed to 14.16+.

No white space nodes on AST anymore

Previously white spaces was preserved on CSS parsing as a WhiteSpace node with a single space. This was mostly needed to avoid combining the CSS tokens into one when generating back into a CSS string. This is no longer necessary, as the generator has been reworked to independently determine when to use spaces in output. This simplify analysis and construction of the AST, and also improves the performance and memory consumption a bit.

Some changes have been made to the AST construction during parsing. First of all, white spaces in selectors are now producing { type: 'Combinator', name: ' ' } nodes when appropriate. Second, white spaces surrounding operators - and + are now replacing with a single space and appending to operators to preserve a behaviour of expressions in calc() functions. Finally, the only case a WhiteSpace node is now created is a custom property declaration with a single whitespace token as the value, since --var: ; and --var:; have different behaviour in terms of CSS.

Improved generator

CSS Syntax Module defines rules for CSS serialization that it must "round-trip" with parsing. Starting with this release the CSSTree's generator follows these rules and determines itself when to output the space to avoid unintended CSS tokens combining.

The spec rules allow to omit whitespaces in most cases. However, some older browsers fail to parse the resulting CSS because they didn't follow the spec. For this reason, the generator supports two modes:

• safe (by default) which adds an extra space in some edge cases;
• spec which completely follows the spec.

import { parse, generate } from 'css-tree';

const ast = parse('a { border: calc(1px) solid #ff0000 }');

// safe mode is by default
// the same as console.log(generate(ast, { mode: 'safe' }));
console.log(generate(ast));
// a{border:calc(1px) solid#ff0000}

// spec mode
console.log(generate(ast, { mode: 'spec' }));
// a{border:calc(1px)solid#ff0000}

These changes to the generator bring it closer to the pretty print output that will be implemented in future releases.

Auto encoding and decoding of values

For string and url values an auto encoding and decoding was implemented. This means you no longer need to do any preprocessing on string or url values before analyzing or transforming of it. Most noticeable simplification with Url nodes:

// CSSTree 1.x
csstree.walk(ast, function(node) {
    if (node.type === 'Url') {
        if (node.value.type === 'String') {
            urls.push(node.value.value.substring(1, node.value.value.length - 1));
        } else {
            urls.push(node.value.value);
        }
    }
});

// CSSTree 2.0
csstree.walk(ast, function(node) {
    if (node.type === 'Url') {
        urls.push(node.value);
    }
});

It is worth noting that despite the fact that in many cases the example above will give the same results for both versions, a solution with CSSTree 1.x still lacks decoding of escaped sequences, that is, additional processing of values is needed.

Additionaly, encode and decode functions for string, url and ident values are available as utils:

import { string, url, ident } from 'css-tree';

string.decode('"hello\\9  \\"world\\""') // hello\t "world"
string.decode('\'hello\\9  "world"\'')   // hello\t "world"
string.encode('hello\t "world"')         // "hello\9  \"world\""
string.encode('hello\t "world"', true)   // 'hello\9  "world"'

url.decode('url(file\ \(1\).ext)')  // file (1).ext
url.encode('file (1).ext')          // url(file\ \(1\).ext)

ident.decode('hello\\9 \\ world')   // hello\t world
ident.encode('hello\t world')       // hello\9 \ world

Changes

• Package
  • Dropped support for Node.js prior 14.16 (following patch versions changed it to ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0)
  • Converted to ES modules. However, CommonJS is supported as well (dual module)
  • Added exports for standalone parts instead of internal paths usage (use as import * as parser from "css-tree/parser" or require("css-tree/parser")):
    • css-tree/tokenizer
    • css-tree/parser
    • css-tree/walker
    • css-tree/generator
    • css-tree/lexer
    • css-tree/definition-syntax
    • css-tree/utils
  • Changed bundle set to provide dist/csstree.js (an IIFE version with csstree as a global name) and dist/csstree.esm.js (as ES module). Both are minified
  • Bumped mdn-data to 2.0.23
• Tokenizer
  • Changed tokenize() to take a function as second argument, which will be called for every token. No stream instance is creating when second argument is ommited.
  • Changed TokenStream#getRawLength() to take second parameter as a function (rule) that check a char code to stop a scanning
  • Added TokenStream#forEachToken(fn) method
  • Removed TokenStream#skipWS() method
  • Removed TokenStream#getTokenLength() method
• Parser
  • Moved SyntaxError (custom parser's error class) from root of public API to parser via parse.SyntaxError
  • Removed parseError field in parser's SyntaxError
  • Changed selector parsing to produce { type: 'Combinator', name: ' ' } node instead of WhiteSpace node
  • Removed producing of WhiteSpace nodes with the single exception for a custom property declaration with a single white space token as a value
  • Parser adds a whitespace to + and - operators, when a whitespace is before and/or after an operator
  • Exposed parser's inner configuration as parse.config
  • Added consumeUntilBalanceEnd(), consumeUntilLeftCurlyBracket(), consumeUntilLeftCurlyBracketOrSemicolon(), consumeUntilExclamationMarkOrSemicolon() and consumeUntilSemicolonIncluded() methods to parser's inner API to use with Raw instead of Raw.mode
  • Changed Nth to always consume of clause when presented, so it became more general and moves validation to lexer
  • Changed String node type to store decoded string value, i.e. with no quotes and escape sequences
  • Changed Url node type to store decoded url value as a string instead of String or Raw node, i.e. with no quotes, escape sequences and url() wrapper
• Generator
  • Generator is now determines itself when a white space required between emitting tokens
  • Changed chunk() handler to token() (output a single token) and tokenize() (split a string into tokens and output each of them)
  • Added mode option for generate() to specify a mode of token separation: spec or safe (by default)
  • Added emit(token, type, auto) handler as implementation specific token processor
  • Changed Nth to serialize +n as n
  • Added auto-encoding for a string and url tokens on serialization
• Lexer
  • Removed Lexer#matchDeclaration() method
• Utils
  • Added ident, string and url helpers to decode/encode corresponding values, e.g. url.decode('url("image.jpg")') === 'image.jpg'
  • List
    • Changed List to be iterable (iterates data)
    • Changed List#first, List#last and List#isEmpty to getters
    • Changed List#getSize() method to List#size getter
    • Removed List#each() and List#eachRight() methods, List#forEach() and List#forEachRight() should be used instead

• Fixed matching on CSS wide keywords for at-rule's prelude and descriptors
• Added fit-content to width property patch as browsers are supported it as a keyword (nonstandard), but spec defines it as a function
• Fixed parsing a value contains parentheses or brackets and parseValue option is set to false, in that case !important was included into a value but must not (#155)

• Rolled back to use spread syntax in object literals since it not supported by nodejs < 8.3 (#145)

• Fixed edge cases in mismatch location computation for SyntaxMatchError

• Fixed edge cases for parsing of custom property value with a single whitespace when parseCustomProperty:true

• Bumped mdn-data to 2.0.14
• Extended fork() method to allow append syntax instead of overriding for types, properties and atrules, e.g. csstree.fork({ types: { color: '| foo | bar' } })
• Extended lexer API for validation
  • Added Lexer#checkAtruleName(atruleName), Lexer#checkAtrulePrelude(atruleName, prelude), Lexer#checkAtruleDescriptorName(atruleName, descriptorName) and Lexer#checkPropertyName(propertyName)
  • Added Lexer#getAtrule(atruleName, fallbackBasename) method
  • Extended Lexer#getAtrulePrelude() and Lexer#getProperty() methods to take fallbackBasename parameter
  • Improved SyntaxMatchError location details
  • Changed error messages

• Added onComment option to parser config
• Added support for break and skip values in walk() to control traversal
• Added List#reduce() and List#reduceRight() methods
• Bumped mdn-data to 2.0.12
• Exposed version of the lib (i.e. import { version } from 'css-tree')
• Renamed HexColor node type into Hash
• Removed element() specific parsing rules
• Removed dist/default-syntax.json from package
• Fixed Lexer#dump() to dump atrules syntaxes as well
• Fixed matching comma separated <urange> list (#135)

• Fixed walker with visit: "Declaration" to iterate DeclarationList (#114)

• Bumped mdn-data to 2.0.6
• Added initial implementation for at-rule matching via Lexer#matchAtrulePrelude() and Lexer#matchAtruleDescriptor() methods
• Added -moz-control-character-visibility, -ms-grid-columns, -ms-grid-rows and -ms-hyphenate-limit-last properties to patch (#111, thanks to @life777)
• Added flow, flow-root and table-caption values to patched display (#112, thanks to @silverwind)

• Bumped source-map version to ^0.6.1 to fix source map generation inconsistency across node.js versions due to mappings sorting bug and v8 moving to a stable Array#sort (fix commit in source-map)