Docs for partial references and some other new stuff, #2009

docs/selectors.md

@@ -110,9 +110,110 @@ If you'd need to use the ampersand symbol in a selector without it behaving like
     .foo[title*='\&']
     // => .foo[title*='&']
 
+## Partial Reference
+
+`^[N]` anywhere in a selector, where `N` can be a number, represents a partial reference.
+
+Partial reference works similar to the parent reference, but while parent reference contains the whole selector, partial selectors contain only the first merged `N` levels of the nested selectors, so you could access those nesting levels individually.
+
+The `^[0]` would give you the selector from the first level, the `^[1]` would give you the rendered selector from the second level and so on:
+
+    .foo
+      &__bar
+        width: 10px
+
+        ^[0]:hover &
+          width: 20px
+
+would be rendered as
+
+    .foo__bar {
+      width: 10px;
+    }
+    .foo:hover .foo__bar {
+      width: 20px;
+    }
+
+Negative values are counting from the end, so ^[-1] would give you the last selector from the chain before `&`:
+
+    .foo
+      &__bar
+        &_baz
+          width: 10px
+
+          ^[-1]:hover &
+            width: 20px
+
+would be rendered as
+
+    .foo__bar_baz {
+      width: 10px;
+    }
+    .foo__bar:hover .foo__bar_baz {
+      width: 20px;
+    }
+
+Negative values are especially helpful for usage inside mixins when you don't know at what nesting level you're calling it.
+
+* * *
+
+Note that partial reference contain the whole rendered chain of selectors until the given nesting level, not the “part” of the selector.
+
+### Ranges in partial references
+
+`^[N..M]` anywhere in a selector, where both `N` and `M` can be numbers, represents a partial reference.
+
+If you'd have a case when you'd need to get the raw part of the selector, or to get the range of parts programmatically, you could use ranges inside partial reference.
+
+If the range would start from the positive value, the result won't contain the selectors of the previous levels and you'd get the result as if the selectors of those levels were inserted at the root of the stylesheet:
+
+    .foo
+      & .bar
+        width: 10px
+
+        ^[0]:hover ^[1..-1]
+          width: 20px
+
+would be rendered as
+
+    .foo .bar {
+      width: 10px;
+    }
+    .foo:hover .bar {
+      width: 20px;
+    }
+
+One number in the range would be the start index, the second — the end index. Note that the order of those numbers won't matter as the selectors would always render from the first levels to the last, so `^[1..-1]` would be equal to the `^[-1..1]`.
+
+When both numbers are equal, the result would be just one raw level of a selector, so you could replace `^[1..-1]` in a previous example to `^[-1..-1]`, and it would be equal to the same last one raw selector, but would be more reliable if used inside mixins.
+
+## Relative Reference
+
+The `../` characters at the start of a selector mark a relative reference, which points to the previous to the `&` compiled selector. You can nest relative reference: `../../` to get deeper levels, but note that it can be used only at the start of the selector.
+
+    .foo
+      .bar
+        width: 10px
+
+        &,
+        ../ .baz
+          height: 10px
+
+would be rendered as
+
+    .foo .bar {
+      width: 10px;
+    }
+    .foo .bar,
+    .foo .baz {
+      height: 10px;
+    }
+
+Relative references can be considered as shortcuts to the partial references with ranges like `^[0..-(N + 1)]` where the `N` is the number of relative references used.
+
 ## Root Reference
 
-The `/` character at the start of the selector is a root reference. It references the root context and this means the selector won't prepend the parent's selector to it (unless you would use it with `&`). It is helpful when you need to write some styles both to some nested selector and to another one, not in the current scope.
+The `/` character at the start of a selector is a root reference. It references the root context and this means the selector won't prepend the parent's selector to it (unless you would use it with `&`). It is helpful when you need to write some styles both to some nested selector and to another one, not in the current scope.
 
     textarea
     input
@@ -156,6 +257,44 @@ This bif could also accept an optional string argument, in this case it would re
       selector('&:hover')
     // '.foo:hover'
 
+### Multiple values for `selector()` bif
+
+`selector()` bif can accept multiple values or a comma-separated list in order to create a nested selector structure easier.
+
+    {selector('.a', '.b', '.c, .d')}
+      color: red
+
+would be equal to the
+
+    .a
+      .b
+        .c,
+        .d
+          color: red
+
+and would be rendered as
+
+    .a .b .c,
+    .a .b .d {
+      color: #f00;
+    }
+
+## selectors() bif
+
+This bif returns a comma-separated list of nested selectors for the current level:
+
+    .a
+      .b
+        &__c
+          content: selectors()
+
+would be rendered as
+
+    .a .b__c {
+      content: '.a', '& .b', '&__c';
+    }
+
+
 ## Disambiguation
 
 Expressions such as `margin - n` could be interpreted both as a subtraction operation, as well as a property with an unary minus. To disambiguate, wrap the expression with parens: