nav tabs on admin dashboard

node_modules/postcss-selector-parser/API.md

@@ -8,27 +8,30 @@ not documented here are subject to change at any point.*
 This is the module's main entry point.
 
 ```js
-var parser = require('postcss-selector-parser');
+const parser = require('postcss-selector-parser');
 ```
 
-### `parser([transform])`
+### `parser([transform], [options])`
 
 Creates a new `processor` instance
 
 ```js
-var processor = parser();
+const processor = parser();
+```
 
-// or, with optional transform function
-var transform = function (selectors) {
-    selectors.eachUniversal(function (selector) {
+Or, with optional transform function
+
+```js
+const transform = selectors => {
+    selectors.walkUniversals(selector => {
         selector.remove();
     });
 };
 
-var processor = parser(transform)
+const processor = parser(transform)
 
 // Example
-var result = processor.process('*.class').result;
+const result = processor.processSync('*.class');
 // => .class
 ```
 
@@ -37,6 +40,7 @@ var result = processor.process('*.class').result;
 Arguments:
 
 * `transform (function)`: Provide a function to work with the parsed AST.
+* `options (object)`: Provide default options for all calls on the returned `Processor`.
 
 ### `parser.attribute([props])`
 
@@ -77,6 +81,18 @@ Arguments:
 
 * `props (object)`: The new node's properties.
 
+Notes:
+* **Descendant Combinators** The value of descendant combinators created by the
+  parser always just a single space (`" "`). For descendant selectors with no
+  comments, additional space is now stored in `node.spaces.before`. Depending
+  on the location of comments, additional spaces may be stored in
+  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
+* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
+  named combinators like `/deep/` and `/for/` are parsed as combinators. The
+  `node.value` is name after being unescaped and normalized as lowercase. The
+  original value for the combinator name is stored in `node.raws.value`.
+
+
 ### `parser.comment([props])`
 
 Creates a new comment.
@@ -222,7 +238,7 @@ root.nodes[0].parent === root;
 Returns a string representation of the node.
 
 ```js
-var id = parser.id({value: 'search'});
+const id = parser.id({value: 'search'});
 console.log(String(id));
 // => #search
 ```
@@ -232,7 +248,7 @@ console.log(String(id));
 Returns the next/previous child of the parent node.
 
 ```js
-var next = id.next();
+const next = id.next();
 if (next && next.type !== 'combinator') {
     throw new Error('Qualified IDs are not allowed!');
 }
@@ -243,8 +259,8 @@ if (next && next.type !== 'combinator') {
 Replace a node with another.
 
 ```js
-var attr = selectors.first.first;
-var className = parser.className({value: 'test'});
+const attr = selectors.first.first;
+const className = parser.className({value: 'test'});
 attr.replaceWith(className);
 ```
 
@@ -268,12 +284,23 @@ Returns a copy of a node, detached from any parent containers that the
 original might have had.
 
 ```js
-var cloned = parser.id({value: 'search'});
+const cloned = parser.id({value: 'search'});
 String(cloned);
 
 // => #search
 ```
 
+### `node.isAtPosition(line, column)`
+
+Return a `boolean` indicating whether this node includes the character at the
+position of the given line and column. Returns `undefined` if the nodes lack
+sufficient source metadata to determine the position.
+
+Arguments:
+
+* `line`: 1-index based line number relative to the start of the selector.
+* `column`: 1-index based column number relative to the start of the selector.
+
 ### `node.spaces`
 
 Extra whitespaces around the node will be moved into `node.spaces.before` and
@@ -284,15 +311,13 @@ no semantic meaning:
       h1     ,     h2   {}
 ```
 
-However, *combinating* spaces will form a `combinator` node:
+For descendent selectors, the value is always a single space.
 
 ```css
 h1        h2 {}
 ```
 
-A `combinator` node may only have the `spaces` property set if the combinator
-value is a non-whitespace character, such as `+`, `~` or `>`. Otherwise, the
-combinator value will contain all of the spaces between selectors.
+Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.
 
 ### `node.source`
 
@@ -368,6 +393,19 @@ Arguments:
 
 * `index`: The index of the node to return.
 
+### `container.atPosition(line, column)`
+
+Returns the node at the source position `index`.
+
+```js
+selector.at(0) === selector.first;
+selector.at(0) === selector.nodes[0];
+```
+
+Arguments:
+
+* `index`: The index of the node to return.
+
 ### `container.index(node)`
 
 Return the index of the node within its container.
@@ -408,8 +446,8 @@ Iterate the container's immediate children, calling `callback` for each child.
 You may return `false` within the callback to break the iteration.
 
 ```js
-var className;
-selectors.each(function (selector, index) {
+let className;
+selectors.each((selector, index) => {
     if (selector.type === 'class') {
         className = selector.value;
         return false;
@@ -431,7 +469,7 @@ Like `container#each`, but will also iterate child nodes as long as they are
 `container` types.
 
 ```js
-selectors.walk(function (selector, index) {
+selectors.walk((selector, index) => {
     // all nodes
 });
 ```
@@ -468,7 +506,7 @@ to the groups that you created via the callback.
 
 ```js
 // (input) => h1 h2>>h3
-var list = selectors.first.split((selector) => {
+const list = selectors.first.split(selector => {
     return selector.type === 'combinator';
 });
 
@@ -486,7 +524,7 @@ Add a node to the start/end of the container. Note that doing so will set
 the parent property of the node to this container.
 
 ```js
-var id = parser.id({value: 'search'});
+const id = parser.id({value: 'search'});
 selector.append(id);
 ```
 
@@ -499,9 +537,9 @@ Arguments:
 Add a node before or after an existing node in a container:
 
 ```js
-selectors.walk(function (selector) {
+selectors.walk(selector => {
     if (selector.type !== 'class') {
-        var className = parser.className({value: 'theme-name'});
+        const className = parser.className({value: 'theme-name'});
         selector.parent.insertAfter(selector, className);
     }
 });
@@ -550,7 +588,7 @@ support parsing of legacy CSS hacks.
 
 ## Selector nodes
 
-A selector node represents a single compound selector. For example, this
+A selector node represents a single complex selector. For example, this
 selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
 It has no special functionality of its own.
 
@@ -575,6 +613,30 @@ Remains `undefined` if there is no attribute value.
 [href] /* undefined */
 ```
 
+### `attribute.qualifiedAttribute`
+
+Returns the attribute name qualified with the namespace if one is given.
+
+### `attribute.offsetOf(part)`
+
+ Returns the offset of the attribute part specified relative to the
+ start of the node of the output string. This is useful in raising
+ error messages about a specific part of the attribute, especially
+ in combination with `attribute.sourceIndex`.
+
+ Returns `-1` if the name is invalid or the value doesn't exist in this
+ attribute.
+
+ The legal values for `part` are:
+
+ * `"ns"` - alias for "namespace"
+ * `"namespace"` - the namespace if it exists.
+ * `"attribute"` - the attribute name
+ * `"attributeNS"` - the start of the attribute or its namespace
+ * `"operator"` - the match operator of the attribute
+ * `"value"` - The value (string or identifier)
+ * `"insensitive"` - the case insensitivity flag
+
 ### `attribute.raws.unquoted`
 
 Returns the unquoted content of the attribute's value.
@@ -587,38 +649,225 @@ Remains `undefined` if there is no attribute value.
 [href] /* undefined */
 ```
 
-### `attribute.raws.insensitive`
+### `attribute.spaces`
 
-If there is an `i` specifying case insensitivity, returns that `i` along with the whitespace
-around it.
+Like `node.spaces` with the `before` and `after` values containing the spaces
+around the element, the parts of the attribute can also have spaces before
+and after them. The for each of `attribute`, `operator`, `value` and
+`insensitive` there is corresponding property of the same nam in
+`node.spaces` that has an optional `before` or `after` string containing only
+whitespace.
 
-```css
-[id=Bar i ] /* " i " */
-[id=Bar   i  ] /* "   i  " */
-```
+Note that corresponding values in `attributes.raws.spaces` contain values
+including any comments. If set, these values will override the
+`attribute.spaces` value. Take care to remove them if changing
+`attribute.spaces`.
 
-## `processor`
+### `attribute.raws`
 
-### `process(cssText, [options])`
+The raws object stores comments and other information necessary to re-render
+the node exactly as it was in the source.
 
-Processes the `cssText`, returning the parsed output
+If a comment is embedded within the identifiers for the `namespace`, `attribute`
+or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.
+
+If a comment is embedded within the space between parts of the attribute
+then the raw for that space is set accordingly.
+
+Setting an attribute's property `raws` value to be deleted.
+
+For now, changing the spaces required also updating or removing any of the
+raws values that override them.
+
+Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:
 
 ```js
-var processor = parser();
+{
+  attribute: "href",
+  operatator: "=",
+  value: "test",
+  spaces: {
+    before: '',
+    after: '',
+    attribute: { before: '  ', after: '  ' },
+    operator: { after: '  ' },
+    value: { after: ' ' },
+    insensitive: { after: ' ' }
+  },
+  raws: {
+    spaces: {
+      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
+      operator: { after: ' /* after-operator */ ' },
+      value: { after: '/* wow */ /*omg*/' },
+      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
+    },
+    unquoted: 'test',
+    value: 'te/*inside-value*/st'
+  }
+}
+```
 
-var result = processor.process(' .class').result;
+## `Processor`
+
+### `ProcessorOptions`
+
+* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
+* `updateSelector` - When `true`, if any processor methods are passed a postcss
+  `Rule` node instead of a string, then that Rule's selector is updated
+  with the results of the processing. Defaults to `true`.
+
+### `process|processSync(selectors, [options])`
+
+Processes the `selectors`, returning a string from the result of processing.
+
+Note: when the `updateSelector` option is set, the rule's selector
+will be updated with the resulting string.
+
+**Example:**
+
+```js
+const parser = require("postcss-selector-parser");
+const processor = parser();
+
+let result = processor.processSync(' .class');
+console.log(result);
 // =>  .class
 
+// Asynchronous operation
+let promise = processor.process(' .class').then(result => {
+    console.log(result)
+    // => .class
+});
+
 // To have the parser normalize whitespace values, utilize the options
-var result = processor.process('  .class  ', {lossless: false}).result;
+result = processor.processSync('  .class  ', {lossless: false});
+console.log(result);
 // => .class
+
+// For better syntax errors, pass a PostCSS Rule node.
+const postcss = require('postcss');
+rule = postcss.rule({selector: ' #foo    > a,  .class  '});
+processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
+    console.log(result);
+    // => #foo>a,.class
+    console.log("rule:", rule.selector);
+    // => rule: #foo>a,.class
+})
 ```
 
 Arguments:
 
-* `cssText (string)`: The css to be parsed.
+* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
+  node.
 * `[options] (object)`: Process options
 
-Options:
 
-* `lossless (boolean)`: false to normalize the selector whitespace, defaults to true
+### `ast|astSync(selectors, [options])`
+
+Like `process()` and `processSync()` but after
+processing the `selectors` these methods return the `Root` node of the result
+instead of a string.
+
+Note: when the `updateSelector` option is set, the rule's selector
+will be updated with the resulting string.
+
+### `transform|transformSync(selectors, [options])`
+
+Like `process()` and `processSync()` but after
+processing the `selectors` these methods return the value returned by the
+processor callback.
+
+Note: when the `updateSelector` option is set, the rule's selector
+will be updated with the resulting string.
+
+### Error Handling Within Selector Processors
+
+The root node passed to the selector processor callback
+has a method `error(message, options)` that returns an
+error object. This method should always be used to raise
+errors relating to the syntax of selectors. The options
+to this method are passed to postcss's error constructor
+([documentation](http://api.postcss.org/Container.html#error)).
+
+#### Async Error Example
+
+```js
+let processor = (root) => {
+    return new Promise((resolve, reject) => {
+        root.walkClasses((classNode) => {
+            if (/^(.*)[-_]/.test(classNode.value)) {
+                let msg = "classes may not have underscores or dashes in them";
+                reject(root.error(msg, {
+                    index: classNode.sourceIndex + RegExp.$1.length + 1,
+                    word: classNode.value
+                }));
+            }
+        });
+        resolve();
+    });
+};
+
+const postcss = require("postcss");
+const parser = require("postcss-selector-parser");
+const selectorProcessor = parser(processor);
+const plugin = postcss.plugin('classValidator', (options) => {
+    return (root) => {
+        let promises = [];
+        root.walkRules(rule => {
+            promises.push(selectorProcessor.process(rule));
+        });
+        return Promise.all(promises);
+    };
+});
+postcss(plugin()).process(`
+.foo-bar {
+  color: red;
+}
+`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));
+
+// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
+//
+// > 1 | .foo-bar {
+//     |     ^
+//   2 |   color: red;
+//   3 | }
+```
+
+#### Synchronous Error Example
+
+```js
+let processor = (root) => {
+    root.walkClasses((classNode) => {
+        if (/.*[-_]/.test(classNode.value)) {
+            let msg = "classes may not have underscores or dashes in them";
+            throw root.error(msg, {
+                index: classNode.sourceIndex,
+                word: classNode.value
+            });
+        }
+    });
+};
+
+const postcss = require("postcss");
+const parser = require("postcss-selector-parser");
+const selectorProcessor = parser(processor);
+const plugin = postcss.plugin('classValidator', (options) => {
+    return (root) => {
+        root.walkRules(rule => {
+            selectorProcessor.processSync(rule);
+        });
+    };
+});
+postcss(plugin()).process(`
+.foo-bar {
+  color: red;
+}
+`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));
+
+// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
+//
+// > 1 | .foo-bar {
+//     |     ^
+//   2 |   color: red;
+//   3 | }
+```