New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

postcss-nested-ancestors

Package Overview
Dependencies
Maintainers
1
Versions
6
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

postcss-nested-ancestors

PostCSS plugin to reference any ancestor selector in nested CSS

  • 3.0.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
5.6K
decreased by-29.93%
Maintainers
1
Weekly downloads
 
Created
Source

PostCSS Nested ancestors

Build status Npm version Test coverage report

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

Keywords

FAQs

Package last updated on 07 May 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc