PostCSS Nested ancestors

PostCSS plugin to reference any parent ancestor selector in nested CSS.

Getting ancestor selectors

When writing modular nested CSS, & current parent selector is often not enough.

PostCSS Nested ancestors introduces ^& selector which let you reference any parent ancestor selector with an easy and customizable interface.

This plugin should be used before a PostCSS rules unwrapper like postcss-nested.

See PostCSS docs for examples for your environment.

Ancestor selectors schema

    .level-1 {
|   |   .level-2 {
|   |   |   .level-3 {
|   |   |   |   .level-4 {
|   |   |   |   |
|   |   |   |   --- & {}        /*      & = ".level-1 .level-2 .level-3 .level-4" */
|   |   |   ------- ^& {}       /*     ^& = ".level-1 .level-2 .level-3"          */
|   |   ----------- ^^& {}      /*    ^^& = ".level-1 .level-2"                   */
|   --------------- ^^^& {}     /*   ^^^& = ".level-1"                            */
------------------- ^^^^& {}    /*  ^^^^& = ""                                    */
                }
            }
        }
    }

A real example

/* Without postcss-nested-ancestors */
.MyComponent
    &-part{}
    &:hover {
        > .MyComponent-part {} /* Must manually repeat ".MyComponent" for each child */
    }
}

/* With postcss-nested-ancestors */
.MyComponent
    &-part{}
    &:hover {
        > ^&-part {} /* Skip ":hover" inheritance here */
    }
}

/* After postcss-nested-ancestors */
.MyComponent {
    &-part{}
    &:hover {
        > .MyComponent-part {}
}

/* After postcss-nested */
.MyComponent {}
.MyComponent-part {}
.MyComponent:hover {}
.MyComponent:hover > .MyComponent-part {} /* No ":hover" inheritance here! */

Why?

Currently another plugin - postcss-current-selector - has tried to solve the problem of referencing ancestors selector. It works great, but its approach involves assigning ancestor selectors to special variables to be later processed by a further postcss plugin postcss-simple-vars.

PostCSS Nested ancestors instead replaces special ancestor selectors, makes no use of variable assignment and produces an output ready to be unwrapped with postcss-nested.

Installation

$ npm install --save-dev postcss postcss-nested-ancestors

Usage

postcss([require('postcss-nested-ancestors')]);

Options

placeholder

Type: string Default: ^&

Ancestor selector pattern (utility option to automatically set both levelSymbol and parentSymbol)

levelSymbol

Type: string Default: ^

Define ancestor selector fragment relative to the matching nesting level

parentSymbol

Type: string Default: &

Ancestor selector base symbol

replaceDeclarations (experimental)

Type: boolean Default: false

If this is true then this plugin will look through your declaration values for the placeholder symbol and replace them with specified selector.

An use case for this if enabling postcss-ref to work with dynamic @ref selectors. Read discussion here.

/* Before */
.foo {
  &:last-child {
    border-top: ref(^&, border-bottom);
  }
}

/* After PostCSS Nested ancestors and PostCSS Nested */
.foo {
}

.foo:last-child {
  border-top: ref(.foo, border-bottom);
}

Known issues

Multiple ancestor placeholders in same selector

This plugin currently fails when trying to replace more than one different ancestor placeholder in a single rule selector. This scenario has not been considered in order to not bloat the code with a remote use case.

More precisely, all ancestor placeholders are replaced, but processed as if they where the equal to the first ancestor placeholder found in selector.

In general, do not use more than one ancestor placeholder in a single rule selector. Anyway, this use case can be rewritten by splitting the selectors in multiple nested rules (see edge case 2).

Edge case 1 (success)

/* 2 equal ancestor placeholders in single rule selector */
.a {
  &:hover {
    ^&^&-b {
    }
  }
}

/* Output: It works but casts a warning */
.a {
  &:hover {
    .a.a-b {
    }
  }
}

Edge case 2 (failing)

/* 2 different ancestor placeholders in single rule selector */
.a {
  &-b {
    &:hover {
      /* Will be processed as ^&^&-c{}, sorry! */
      ^&^^&-c {
      }
    }
  }
}

/* Wrong output: All placeholder replaced with the value of the first one */
.a {
  &-b {
    &:hover {
      /* Expected output: .a-b.a-c{}*/
      .a-b.a-b-c {
      }
    }
  }
}

/* This use case can be rewritten as: */
.a {
  &-b {
    &:hover {
      ^& {
        &^^^&-c {
        }
      }
    }
  }
}

Replace declaration values in complex nesting scenarios

replaceDeclarations options used in a complex nesting scenario might have undesired outputs because of the different nature of CSS selectors and and declaration values.

In general, avoid replacing declaration values when inside a rule with multiple selectors (but why should you?). In other words don't get yourself into trouble!

Here is an example of what you don't want to do.

/* Don't replace declaration value inside multiple selector rules */
.a1,
.a2 {
  &:hover {
    &:before {
      content: '^^&';
    }
  }
}

/* Output */
.a1,
.a2 {
  &:hover {
    &:before {
      content: '.a1,.a2';
    }
  }
}

Contributing

Contributions are super welcome, but please follow the conventions below if you want to do a pull request:

Create a new branch and make the pull request from that branch
Each pull request for a single feature or bug fix
If you are planning on doing something big, please discuss first with @toomuchdesign about it
Update tests (test.js) covering new features

Todo's

Better comment source code

toomuchdesign/postcss-nested-ancestors