Merge pull request #49 from bschlenk/master

feat: Add support for parsing & nesting selector

Author: mdevils

README.md

@@ -179,6 +179,7 @@ const parse = createParser({
 | `css-scoping-1` | Shadow DOM selectors (`:host`, `:host-context()`, `::slotted()`) |
 | `css-pseudo-4` | Modern pseudo-elements (`::selection`, `::backdrop`, etc.) |
 | `css-shadow-parts-1` | `::part()` for styling shadow DOM components |
+| `css-nesting-1` | CSS Nesting selector (`&`) |
 
 The `latest` syntax automatically includes all modules marked as current specifications.
 

docs/interfaces/AstFactory.md

@@ -52,6 +52,7 @@ console.log(ast.isRule(selector)); // prints false
 - [isFormulaOfSelector](AstFactory.md#isformulaofselector)
 - [isId](AstFactory.md#isid)
 - [isNamespaceName](AstFactory.md#isnamespacename)
+- [isNestingSelector](AstFactory.md#isnestingselector)
 - [isNoNamespace](AstFactory.md#isnonamespace)
 - [isPseudoClass](AstFactory.md#ispseudoclass)
 - [isPseudoElement](AstFactory.md#ispseudoelement)
@@ -63,6 +64,7 @@ console.log(ast.isRule(selector)); // prints false
 - [isWildcardNamespace](AstFactory.md#iswildcardnamespace)
 - [isWildcardTag](AstFactory.md#iswildcardtag)
 - [namespaceName](AstFactory.md#namespacename)
+- [nestingSelector](AstFactory.md#nestingselector)
 - [noNamespace](AstFactory.md#nonamespace)
 - [pseudoClass](AstFactory.md#pseudoclass)
 - [pseudoElement](AstFactory.md#pseudoelement)
@@ -317,6 +319,27 @@ ___
 entity is AstNamespaceName
 
 
+___
+
+### isNestingSelector
+
+• **isNestingSelector**: (`entity`: `unknown`) => entity is AstNestingSelector
+
+#### Type declaration
+
+▸ (`entity`): entity is AstNestingSelector
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `entity` | `unknown` |
+
+##### Returns
+
+entity is AstNestingSelector
+
+
 ___
 
 ### isNoNamespace
@@ -549,6 +572,27 @@ ___
 [`AstNamespaceName`](AstNamespaceName.md)
 
 
+___
+
+### nestingSelector
+
+• **nestingSelector**: (`props?`: {}) => [`AstNestingSelector`](AstNestingSelector.md)
+
+#### Type declaration
+
+▸ (`props?`): [`AstNestingSelector`](AstNestingSelector.md)
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `props?` | `Object` |
+
+##### Returns
+
+[`AstNestingSelector`](AstNestingSelector.md)
+
+
 ___
 
 ### noNamespace
@@ -620,7 +664,7 @@ ___
 
 ### rule
 
-• **rule**: (`props`: { `combinator?`: `string` ; `items`: ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[] ; `nestedRule?`: [`AstRule`](AstRule.md)  }) => [`AstRule`](AstRule.md)
+• **rule**: (`props`: { `combinator?`: `string` ; `items`: ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstNestingSelector`](AstNestingSelector.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[] ; `nestedRule?`: [`AstRule`](AstRule.md)  }) => [`AstRule`](AstRule.md)
 
 #### Type declaration
 
@@ -632,7 +676,7 @@ ___
 | :------ | :------ | :------ |
 | `props` | `Object` | - |
 | `props.combinator?` | `string` | Rule combinator which was used to nest this rule (i.e. `">"` in case of `"div > span"` if the current rule is `"span"`). |
-| `props.items` | ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[] | Items of a CSS rule. Can be tag, ids, class names, pseudo-classes and pseudo-elements. |
+| `props.items` | ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstNestingSelector`](AstNestingSelector.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[] | Items of a CSS rule. Can be tag, ids, class names, pseudo-classes and pseudo-elements. |
 | `props.nestedRule?` | [`AstRule`](AstRule.md) | Nested rule if specified (i.e. `"div > span"`). |
 
 ##### Returns

docs/interfaces/AstNestingSelector.md

@@ -0,0 +1,29 @@
+[css-selector-parser](../../README.md) / [Exports](../modules.md) / AstNestingSelector
+
+# Interface: AstNestingSelector
+
+CSS Nesting Selector: `&`.
+Represents the parent selector in nested CSS.
+Generated by [ast.nestingSelector](AstFactory.md#nestingselector).
+
+**`See`**
+
+https://www.w3.org/TR/css-nesting-1/#nest-selector
+
+**`Example`**
+
+```ts
+"&:hover"
+```
+
+## Table of contents
+
+### Properties
+
+- [type](AstNestingSelector.md#type)
+
+## Properties
+
+### type
+
+• **type**: ``"NestingSelector"``

docs/interfaces/AstRule.md

@@ -27,7 +27,7 @@ ___
 
 ### items
 
-• **items**: ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[]
+• **items**: ([`AstTagName`](AstTagName.md) \| [`AstWildcardTag`](AstWildcardTag.md) \| [`AstId`](AstId.md) \| [`AstClassName`](AstClassName.md) \| [`AstNestingSelector`](AstNestingSelector.md) \| [`AstPseudoClass`](AstPseudoClass.md) \| [`AstAttribute`](AstAttribute.md) \| [`AstPseudoElement`](AstPseudoElement.md))[]
 
 Items of a CSS rule. Can be tag, ids, class names, pseudo-classes and pseudo-elements.
 

docs/interfaces/SyntaxDefinition.md

@@ -13,7 +13,9 @@ CSS Selector Syntax Definition can be used to define custom CSS selector parsing
 - [classNames](SyntaxDefinition.md#classnames)
 - [combinators](SyntaxDefinition.md#combinators)
 - [ids](SyntaxDefinition.md#ids)
+- [modules](SyntaxDefinition.md#modules)
 - [namespace](SyntaxDefinition.md#namespace)
+- [nestingSelector](SyntaxDefinition.md#nestingselector)
 - [pseudoClasses](SyntaxDefinition.md#pseudoclasses)
 - [pseudoElements](SyntaxDefinition.md#pseudoelements)
 - [tag](SyntaxDefinition.md#tag)
@@ -101,6 +103,21 @@ https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Typ
 
 ___
 
+### modules
+
+• `Optional` **modules**: (``"css-position-1"`` \| ``"css-position-2"`` \| ``"css-position-3"`` \| ``"css-position-4"`` \| ``"css-scoping-1"`` \| ``"css-pseudo-4"`` \| ``"css-shadow-parts-1"`` \| ``"css-nesting-1"``)[]
+
+Additional CSS modules to include in the syntax definition.
+These are specific CSS modules that add new selectors or modify existing ones.
+
+**`Example`**
+
+```ts
+['css-position-4', 'css-scoping-1']
+```
+
+___
+
 ### namespace
 
 • `Optional` **namespace**: `boolean` \| { `wildcard?`: `boolean`  }
@@ -119,6 +136,25 @@ https://www.w3.org/TR/css3-namespace/
 
 ___
 
+### nestingSelector
+
+• `Optional` **nestingSelector**: `boolean`
+
+CSS Nesting Selector (&).
+Represents the parent selector in nested CSS.
+
+**`Example`**
+
+```ts
+&:hover
+```
+
+**`See`**
+
+https://www.w3.org/TR/css-nesting-1/#nest-selector
+
+___
+
 ### pseudoClasses
 
 • `Optional` **pseudoClasses**: ``false`` \| { `definitions?`: { `Formula`: `undefined` \| `string`[] ; `FormulaOfSelector`: `undefined` \| `string`[] ; `NoArgument`: `undefined` \| `string`[] ; `Selector`: `undefined` \| `string`[] ; `String`: `undefined` \| `string`[]  } ; `unknown?`: ``"accept"`` \| ``"reject"``  }

docs/modules.md

@@ -13,6 +13,7 @@
 - [AstFormulaOfSelector](interfaces/AstFormulaOfSelector.md)
 - [AstId](interfaces/AstId.md)
 - [AstNamespaceName](interfaces/AstNamespaceName.md)
+- [AstNestingSelector](interfaces/AstNestingSelector.md)
 - [AstNoNamespace](interfaces/AstNoNamespace.md)
 - [AstPseudoClass](interfaces/AstPseudoClass.md)
 - [AstPseudoElement](interfaces/AstPseudoElement.md)
@@ -30,6 +31,7 @@
 
 - [AstEntity](modules.md#astentity)
 - [CssLevel](modules.md#csslevel)
+- [CssModule](modules.md#cssmodule)
 - [Parser](modules.md#parser)
 
 ### Variables
@@ -45,7 +47,7 @@
 
 ### AstEntity
 
-Ƭ **AstEntity**: [`AstSelector`](interfaces/AstSelector.md) \| [`AstRule`](interfaces/AstRule.md) \| [`AstTagName`](interfaces/AstTagName.md) \| [`AstWildcardTag`](interfaces/AstWildcardTag.md) \| [`AstId`](interfaces/AstId.md) \| [`AstClassName`](interfaces/AstClassName.md) \| [`AstNamespaceName`](interfaces/AstNamespaceName.md) \| [`AstWildcardNamespace`](interfaces/AstWildcardNamespace.md) \| [`AstNoNamespace`](interfaces/AstNoNamespace.md) \| [`AstSubstitution`](interfaces/AstSubstitution.md) \| [`AstString`](interfaces/AstString.md) \| [`AstFormula`](interfaces/AstFormula.md) \| [`AstFormulaOfSelector`](interfaces/AstFormulaOfSelector.md) \| [`AstPseudoClass`](interfaces/AstPseudoClass.md) \| [`AstAttribute`](interfaces/AstAttribute.md) \| [`AstPseudoElement`](interfaces/AstPseudoElement.md)
+Ƭ **AstEntity**: [`AstSelector`](interfaces/AstSelector.md) \| [`AstRule`](interfaces/AstRule.md) \| [`AstTagName`](interfaces/AstTagName.md) \| [`AstWildcardTag`](interfaces/AstWildcardTag.md) \| [`AstId`](interfaces/AstId.md) \| [`AstClassName`](interfaces/AstClassName.md) \| [`AstNamespaceName`](interfaces/AstNamespaceName.md) \| [`AstWildcardNamespace`](interfaces/AstWildcardNamespace.md) \| [`AstNoNamespace`](interfaces/AstNoNamespace.md) \| [`AstNestingSelector`](interfaces/AstNestingSelector.md) \| [`AstSubstitution`](interfaces/AstSubstitution.md) \| [`AstString`](interfaces/AstString.md) \| [`AstFormula`](interfaces/AstFormula.md) \| [`AstFormulaOfSelector`](interfaces/AstFormulaOfSelector.md) \| [`AstPseudoClass`](interfaces/AstPseudoClass.md) \| [`AstAttribute`](interfaces/AstAttribute.md) \| [`AstPseudoElement`](interfaces/AstPseudoElement.md)
 
 One of CSS AST entity types.
 
@@ -57,6 +59,26 @@ ___
 
 ___
 
+### CssModule
+
+Ƭ **CssModule**: keyof typeof `cssModules`
+
+CSS Module name.
+
+**`Example`**
+
+```ts
+'css-position-3'
+```
+
+**`Example`**
+
+```ts
+'css-scoping-1'
+```
+
+___
+
 ### Parser
 
 Ƭ **Parser**: (`input`: `string`) => [`AstSelector`](interfaces/AstSelector.md)
@@ -133,6 +155,7 @@ Creates a parse function to be used later to parse CSS selectors.
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `options` | `Object` | - |
+| `options.modules?` | (``"css-position-1"`` \| ``"css-position-2"`` \| ``"css-position-3"`` \| ``"css-position-4"`` \| ``"css-scoping-1"`` \| ``"css-pseudo-4"`` \| ``"css-shadow-parts-1"`` \| ``"css-nesting-1"``)[] | Additional CSS modules to include in the syntax definition. These are specific CSS modules that add new selectors or modify existing ones. **`Example`** ```ts ['css-position-3', 'css-scoping-1'] ``` |
 | `options.strict?` | `boolean` | CSS selector parser in modern browsers is very forgiving. For instance, it works fine with unclosed attribute selectors: `"[attr=value"`. Set to `false` in order to mimic browser behaviour. Default: `true` |
 | `options.substitutes?` | `boolean` | Flag to enable substitutes. This is not part of CSS syntax, but rather a useful feature to pass variables into CSS selectors. Default: `false` **`Example`** ```ts "[attr=$variable]" ``` |
 | `options.syntax?` | [`CssLevel`](modules.md#csslevel) \| [`SyntaxDefinition`](interfaces/SyntaxDefinition.md) | CSS Syntax options to be used for parsing. Can either be one of the predefined CSS levels ([CssLevel](modules.md#csslevel)) or a more detailed syntax definition ([SyntaxDefinition](interfaces/SyntaxDefinition.md)). Default: `"latest"` |

src/ast.ts

@@ -20,7 +20,16 @@ export interface AstSelector {
 export interface AstRule {
     type: 'Rule';
     /** Items of a CSS rule. Can be tag, ids, class names, pseudo-classes and pseudo-elements. */
-    items: (AstTagName | AstWildcardTag | AstId | AstClassName | AstAttribute | AstPseudoClass | AstPseudoElement)[];
+    items: (
+        | AstTagName
+        | AstWildcardTag
+        | AstId
+        | AstClassName
+        | AstAttribute
+        | AstPseudoClass
+        | AstPseudoElement
+        | AstNestingSelector
+    )[];
     /** Rule combinator which was used to nest this rule (i.e. `">"` in case of `"div > span"` if the current rule is `"span"`). */
     combinator?: string;
     /** Nested rule if specified (i.e. `"div > span"`). */
@@ -194,6 +203,17 @@ export interface AstFormulaOfSelector {
     /** Selector that goes after formula (i.e. `"div -> span"` in case of `":nth-child(2n + 1 of div > span)"` */
     selector: AstRule;
 }
+/**
+ * CSS Nesting Selector: `&`.
+ * Represents the parent selector in nested CSS.
+ * Generated by {@link AstFactory.nestingSelector ast.nestingSelector}.
+ * @see https://www.w3.org/TR/css-nesting-1/#nest-selector
+ * @example "&:hover"
+ */
+export interface AstNestingSelector {
+    type: 'NestingSelector';
+}
+
 /**
  * Substitution is not part of CSS spec, but rather a useful extension on top of CSS if you need to pass variables.
  * Generated by {@link AstFactory.substitution ast.substitution}.
@@ -221,6 +241,7 @@ export type AstEntity =
     | AstNamespaceName
     | AstWildcardNamespace
     | AstNoNamespace
+    | AstNestingSelector
     | AstSubstitution
     | AstString
     | AstFormula
@@ -343,6 +364,7 @@ export const ast: AstFactory = {
     ...astMethods<AstNamespaceName>('NamespaceName')('namespaceName', 'isNamespaceName'),
     ...astMethods<AstWildcardNamespace>('WildcardNamespace')('wildcardNamespace', 'isWildcardNamespace'),
     ...astMethods<AstNoNamespace>('NoNamespace')('noNamespace', 'isNoNamespace'),
+    ...astMethods<AstNestingSelector>('NestingSelector')('nestingSelector', 'isNestingSelector'),
     ...astMethods<AstAttribute>('Attribute')('attribute', 'isAttribute'),
     ...astMethods<AstPseudoClass>('PseudoClass')('pseudoClass', 'isPseudoClass'),
     ...astMethods<AstPseudoElement>('PseudoElement')('pseudoElement', 'isPseudoElement'),

src/index.ts

@@ -10,6 +10,7 @@ export {
     AstFormulaOfSelector,
     AstId,
     AstNamespaceName,
+    AstNestingSelector,
     AstNoNamespace,
     AstPseudoClass,
     AstPseudoElement,

src/parser.ts

@@ -117,6 +117,7 @@ export function createParser(
         : [false, false];
     const idEnabled = Boolean(syntaxDefinition.ids);
     const classNamesEnabled = Boolean(syntaxDefinition.classNames);
+    const nestingSelectorEnabled = Boolean(syntaxDefinition.nestingSelector);
     const namespaceEnabled = Boolean(syntaxDefinition.namespace);
     const namespaceWildcardEnabled =
         syntaxDefinition.namespace &&
@@ -743,6 +744,10 @@ export function createParser(
                 const idName = parseIdentifier();
                 assert(idName, 'Expected ID name.');
                 rule.items.push({type: 'Id', name: idName});
+            } else if (is('&')) {
+                assert(nestingSelectorEnabled, 'Nesting selector is not enabled.');
+                next();
+                rule.items.push({type: 'NestingSelector'});
             } else if (is('[')) {
                 assert(attributesEnabled, 'Attributes are not enabled.');
                 rule.items.push(parseAttribute());

src/render.ts

@@ -86,6 +86,8 @@ export function render(entity: AstEntity): string {
         return `#${escapeIdentifier(entity.name)}`;
     } else if (entity.type === 'ClassName') {
         return `.${escapeIdentifier(entity.name)}`;
+    } else if (entity.type === 'NestingSelector') {
+        return '&';
     } else if (entity.type === 'Attribute') {
         const {name, namespace, operator, value, caseSensitivityModifier} = entity;
         let result = '[';