feat: upgrade API in order to reflect upcoming complexity in CSS selectors

[mdevils]

BREAKING CHANGE: API is backwards incompatible

Change: Instead of separate fields for tag, ids, classNames, attributes, pseudoClasses and pseudoElement there is a single field items which contains list of those entities. For ids there is a new Id entity type, for class names there is a new ClassName entity type, for pseudo elements there is new PseudoElement entity name.

Why: In the new CSS standard (selectors-4) and some CSS drafts the order of items in a CSS rule became important. Also pseudo element got arguments.

Example 1

Before:

import {ast, render} from 'css-selector-parser';

const selector = ast.selector({
    rules: [
        ast.rule({
            tag: ast.tagName({name: 'a'}),
            attributes: [
                ast.attribute({name: 'href', operator: '^=', value: ast.string({value: '/'})})
            ]
        }),
        ast.rule({
            classNames: ['container'],
            pseudoClasses: [
                ast.pseudoClass({
                    name: 'has',
                    argument: ast.selector({
                        rules: [
                            ast.rule({tag: ast.tagName({name: 'nav'})})
                        ]
                    })
                })
            ],
            nestedRule: ast.rule({
                combinator: '>',
                tag: ast.tagName({name: 'a'}),
                attributes: [ast.attribute({name: 'href'})],
                pseudoClasses: [
                    ast.pseudoClass({
                        name: 'nth-child',
                        argument: ast.formula({a: 0, b: 2})
                    })
                ],
                pseudoElement: 'before'
            })
        })
    ]
});

console.log(render(selector)); // a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before

After:

import {ast, render} from 'css-selector-parser';

const selector = ast.selector({
    rules: [
        ast.rule({
            items: [
                ast.tagName({name: 'a'}),
                ast.attribute({name: 'href', operator: '^=', value: ast.string({value: '/'})})
            ]
        }),
        ast.rule({
            items: [
                ast.className({name: 'container'}),
                ast.pseudoClass({
                    name: 'has',
                    argument: ast.selector({
                        rules: [ast.rule({items: [ast.tagName({name: 'nav'})]})]
                    })
                })
            ],
            nestedRule: ast.rule({
                combinator: '>',
                items: [
                    ast.tagName({name: 'a'}),
                    ast.attribute({name: 'href'}),
                    ast.pseudoClass({
                        name: 'nth-child',
                        argument: ast.formula({a: 0, b: 2})
                    }),
                    ast.pseudoElement({name: 'before'})
                ]
            })
        })
    ]
});

console.log(render(selector)); // a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before

Example 2

Code:

const parse = createParser();
const selector = parse('a[href^="/"], .container:has(nav) > a[href]:nth-child(2)');

console.log(selector);

Before:

({
  type: 'Selector',
  rules: [
    {
      type: 'Rule',
      tag: { type: 'TagName', name: 'a' },
      attributes: [
        {
          type: 'Attribute',
          name: 'href',
          operator: '^=',
          value: { type: 'String', value: '/' }
        }
      ]
    },
    {
      type: 'Rule',
      classNames: [ 'container' ],
      pseudoClasses: [
        {
          type: 'PseudoClass',
          name: 'has',
          argument: {
            type: 'Selector',
            rules: [ { type: 'Rule', tag: { type: 'TagName', name: 'nav' } } ]
          }
        }
      ],
      nestedRule: {
        type: 'Rule',
        combinator: '>',
        tag: { type: 'TagName', name: 'a' },
        attributes: [ { type: 'Attribute', name: 'href' } ],
        pseudoClasses: [
          {
            type: 'PseudoClass',
            name: 'nth-child',
            argument: { type: 'Formula', a: 0, b: 2 }
          }
        ]
      }
    }
  ]
})

After:

({
    type: 'Selector',
    rules: [
        {
            type: 'Rule',
            items: [
                { type: 'TagName', name: 'a' },
                {
                    type: 'Attribute',
                    name: 'href',
                    operator: '^=',
                    value: { type: 'String', value: '/' }
                }
            ]
        },
        {
            type: 'Rule',
            items: [
                { type: 'ClassName', name: 'container' },
                {
                    type: 'PseudoClass',
                    name: 'has',
                    argument: {
                        type: 'Selector',
                        rules: [
                            {
                                type: 'Rule',
                                items: [ { type: 'TagName', name: 'nav' } ]
                            }
                        ]
                    }
                }
            ],
            nestedRule: {
                type: 'Rule',
                items: [
                    { type: 'TagName', name: 'a' },
                    { type: 'Attribute', name: 'href' },
                    {
                        type: 'PseudoClass',
                        name: 'nth-child',
                        argument: { type: 'Formula', a: 0, b: 2 }
                    }
                ],
                combinator: '>'
            }
        }
    ]
})