@unsass/selector 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -2,28 +2,28 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## 1.4.0 (2026-01-03)
+## [1.6.0](https://github.com/unsass/selector/compare/v1.5.0...v1.6.0) (2026-09-19)
+
+### Dependencies
+
+* **deps:** require node >=22 ([fc20214](https://github.com/unsass/selector/commit/fc20214fb8a6187cadadbf51c6d082aa9da25e0d))
+
+## [1.5.0](https://github.com/unsass/selector/compare/v1.4.0...v1.5.0) (2026-06-13)
+
+### Features
+
+* add functional pseudo-class helpers ([09ee327](https://github.com/unsass/selector/commit/09ee32775dca2092b984ffacd0df7939d0eb4318))
+
+## [1.4.0](https://github.com/unsass/selector/compare/v1.3.0...v1.4.0) (2026-01-03)
+
+### Features
 
-* ci: add `release.config.js` ([6fb94ff](https://github.com/unsass/selector/commit/6fb94ff))
-* ci: lint code ([e7c5ae5](https://github.com/unsass/selector/commit/e7c5ae5))
-* ci: rename `node.js.yml` to `publish.yml` ([bdfb2a2](https://github.com/unsass/selector/commit/bdfb2a2))
-* ci: update `commit-msg` ([7f78c1c](https://github.com/unsass/selector/commit/7f78c1c))
 * feat: use the plain-CSS if() syntax ([bfda10e](https://github.com/unsass/selector/commit/bfda10e))
-* chore: switch to ESM ([faee4d8](https://github.com/unsass/selector/commit/faee4d8))
-* chore(deps-dev): bump to `@commitlint/cli` 20.3.0 ([581c39e](https://github.com/unsass/selector/commit/581c39e))
-* chore(deps-dev): bump to `sass-true` 10.1.0 ([125f7b4](https://github.com/unsass/selector/commit/125f7b4))
-* chore(deps-dev): bump to `stylelint` 16.26.1 ([9249a20](https://github.com/unsass/selector/commit/9249a20))
-* chore(deps-dev): prevent dependencies vulnerabilities ([311b5f1](https://github.com/unsass/selector/commit/311b5f1))
-* chore(deps): bump to `@commitlint/cli` 20.1.0 ([7873ab3](https://github.com/unsass/selector/commit/7873ab3))
-* chore(deps): bump to `sass-true` 8.1.0 ([796746d](https://github.com/unsass/selector/commit/796746d))
-* chore(deps): bump to `sass-true` 9.0.0 ([c6f302c](https://github.com/unsass/selector/commit/c6f302c))
+
+### Dependencies
+
 * chore(deps): bump to `sass` 1.97.1 ([3dfbf70](https://github.com/unsass/selector/commit/3dfbf70))
-* chore(deps): bump to `semantic-release` 25.0.1 ([93db310](https://github.com/unsass/selector/commit/93db310))
-* chore(deps): bump to `stylelint-config-unsass` 2.0.0 ([ccb922e](https://github.com/unsass/selector/commit/ccb922e))
-* chore(deps): bump to `stylelint-config-unsass` 2.2.0 ([04e20fa](https://github.com/unsass/selector/commit/04e20fa))
-* chore(deps): clean `package-lock.json` ([65d4a3d](https://github.com/unsass/selector/commit/65d4a3d))
-* chore(deps): prevent dependencies vulnerabilities ([b3fbab9](https://github.com/unsass/selector/commit/b3fbab9))
-* test(deps): switch from jest to vitest ([8c3ed03](https://github.com/unsass/selector/commit/8c3ed03))
+
 
 ## [1.3.0](https://github.com/unsass/selector/compare/v1.2.0...v1.3.0) (2023-09-11)
 

package/README.md

@@ -6,7 +6,15 @@
 
 ## Introduction
 
-Sass functions and mixins to manage CSS selectors.
+A small Sass toolkit for building CSS selectors programmatically. Compose scoped, prefixed or suffixed class names with
+pseudo-classes, pseudo-elements and `@at-root` support through concise, composable mixins and helpers, so selector logic
+stays readable and consistent.
+
+<div align="center">
+
+![Selector](.github/banner.svg)
+
+</div>
 
 ## Installing
 
@@ -24,7 +32,35 @@ npm install @unsass/selector
 }
 ```
 
-### Result
+```css
+.md\:foo {
+    color: darkcyan;
+}
+```
+
+## Mixins
+
+### `create($selector, $scope, $separator, $suffix, $pseudo-class, $pseudo-element, $root)`
+
+Builds a class selector from a name, with optional scope, separator, pseudo and `@at-root` options.
+
+| Parameter         | Description                                                | Default |
+|-------------------|------------------------------------------------------------|---------|
+| `$selector`       | Selector name (a leading `.` is stripped).                 | —       |
+| `$scope`          | Scope affix value, as a single token or a list of tokens.  | `null`  |
+| `$separator`      | Scope affix separator.                                     | `":"`   |
+| `$suffix`         | Append the scope as a suffix instead of a prefix.          | `false` |
+| `$pseudo-class`   | Pseudo-class appended to the selector.                     | `null`  |
+| `$pseudo-element` | Pseudo-element appended to the selector.                   | `null`  |
+| `$root`           | Wrap the output in an `@at-root` rule.                     | `false` |
+
+```scss
+@use "@unsass/selector";
+
+@include selector.create("foo", "md") {
+    color: darkcyan;
+}
+```
 
 ```css
 .md\:foo {
@@ -32,13 +68,25 @@ npm install @unsass/selector
 }
 ```
 
-## API
+#### `$scope`
 
-| Mixin                                                                                   | Description                                                |
-|-----------------------------------------------------------------------------------------|------------------------------------------------------------|
-| `create($selector, $scope, $separator, $suffix, $pseudo-class, $pseudo-element, $root)` | Sets new CSS selector with class scope and pseudo options. |
+Pass a list to chain several scope tokens.
 
-### `$separator`
+```scss
+@use "@unsass/selector";
+
+@include selector.create("foo", ("md", "lg")) {
+    color: darkcyan;
+}
+```
+
+```css
+.md\:lg\:foo {
+    color: darkcyan;
+}
+```
+
+#### `$separator`
 
 Define your own scope separator character.
 
@@ -50,17 +98,15 @@ Define your own scope separator character.
 }
 ```
 
-### Result
-
 ```css
 .md\@foo {
     color: darkcyan;
 }
 ```
 
-### `$suffix`
+#### `$suffix`
 
-Define the scope value has a prefix on selector.
+Append the scope value as a suffix on the selector.
 
 ```scss
 @use "@unsass/selector";
@@ -70,17 +116,15 @@ Define the scope value has a prefix on selector.
 }
 ```
 
-### Result
-
 ```css
 .foo\:md {
     color: darkcyan;
 }
 ```
 
-### `$pseudo-class`
+#### `$pseudo-class`
 
-Define the pseudo class suffix.
+Define the pseudo-class suffix.
 
 ```scss
 @use "@unsass/selector";
@@ -90,17 +134,15 @@ Define the pseudo class suffix.
 }
 ```
 
-### Result
-
 ```css
 .hover\:foo:hover {
     color: darkcyan;
 }
 ```
 
-### `$pseudo-element`
+#### `$pseudo-element`
 
-Define the pseudo element suffix.
+Define the pseudo-element suffix.
 
 ```scss
 @use "@unsass/selector";
@@ -110,17 +152,15 @@ Define the pseudo element suffix.
 }
 ```
 
-### Result
-
 ```css
 .before\:foo::before {
     color: darkcyan;
 }
 ```
 
-### `$root`
+#### `$root`
 
-Wrap the selector with `@at-root` rule before code output.
+Wrap the selector with an `@at-root` rule before code output.
 
 ```scss
 @use "@unsass/selector";
@@ -134,10 +174,129 @@ Wrap the selector with `@at-root` rule before code output.
 }
 ```
 
-### Result
-
 ```css
 .md\:foo .bar {
     color: darkcyan;
 }
 ```
+
+### `media($query)`
+
+Wraps the content in a `@media` rule.
+
+```scss
+@use "@unsass/selector";
+
+.foo {
+    @include selector.media("screen") {
+        color: darkcyan;
+    }
+}
+```
+
+```css
+@media screen {
+    .foo {
+        color: darkcyan;
+    }
+}
+```
+
+## Functions
+
+### `to-class($name)`
+
+Returns a class selector from a name.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.to-class("foo"); // ".foo"
+```
+
+### `to-id($name)`
+
+Returns an id selector from a name.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.to-id("foo"); // "#foo"
+```
+
+### `pseudo-class($selector, $pseudo-class)`
+
+Appends a pseudo-class to a selector.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.pseudo-class(".foo", "hover"); // ".foo:hover"
+```
+
+### `pseudo-element($selector, $pseudo-element)`
+
+Appends a pseudo-element to a selector.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.pseudo-element(".foo", "before"); // ".foo::before"
+```
+
+### `is($selector, $args…)`
+
+Restricts the selector with an `:is()` pseudo-class matching any of the given selectors.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.is("article", "h1", "h2"); // "article:is(h1, h2)"
+```
+
+### `where($selector, $args…)`
+
+Like `is()`, but with zero specificity through the `:where()` pseudo-class.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.where(".prose", "a", "button"); // ".prose:where(a, button)"
+```
+
+### `has($selector, $args…)`
+
+Restricts the selector to elements matching the relational `:has()` condition.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.has(".card", "> img"); // ".card:has(> img)"
+```
+
+### `exclude($selector, $args…)`
+
+Excludes the given selectors through a `:not()` pseudo-class. Named `exclude` because `not` is a reserved Sass keyword.
+
+```scss
+@use "@unsass/selector";
+
+$selector: selector.exclude(".btn", ".btn--disabled"); // ".btn:not(.btn--disabled)"
+$selector: selector.exclude(".item", ".a", ".b"); // ".item:not(.a, .b)"
+```
+
+These helpers return selectors, so they compose:
+
+```scss
+@use "@unsass/selector";
+
+#{selector.exclude(selector.is(".x", "a", "b"), ".y")} {
+    color: darkcyan;
+}
+```
+
+```css
+.x:is(a, b):not(.y) {
+    color: darkcyan;
+}
+```

package/package.json

@@ -1,44 +1,54 @@
 {
     "name": "@unsass/selector",
-    "version": "1.4.0",
+    "version": "1.6.0",
     "description": "Sass functions and mixins to manage CSS selectors.",
     "type": "module",
     "scripts": {
         "lint:css": "stylelint --fix \"**/*.scss\"",
         "lint": "npm-run-all --parallel lint:*",
         "test": "vitest",
-        "prepare": "husky install",
+        "prepare": "husky",
         "release": "semantic-release"
     },
     "engines": {
-        "node": ">=18"
+        "node": ">=22"
     },
     "sass": "index.scss",
     "devDependencies": {
-        "@commitlint/cli": "^20.3.0",
-        "@commitlint/config-conventional": "^20.3.0",
-        "@semantic-release/changelog": "^6.0.3",
-        "@semantic-release/git": "^10.0.1",
+        "@commitlint/cli": "^21.2.2",
+        "@commitlint/config-conventional": "^21.2.2",
+        "@semantic-release/changelog": "^7.0.0",
+        "@semantic-release/git": "^11.0.1",
+        "@semantic-release/github": "^12.0.9",
+        "conventional-changelog-conventionalcommits": "^9.3.1",
         "husky": "^9.1.7",
         "npm-run-all": "^4.1.5",
+        "sass": "^1.104.1",
         "sass-true": "^10.1.0",
-        "semantic-release": "^25.0.2",
+        "semantic-release": "^25.0.9",
         "stylelint": "^16.26.1",
-        "stylelint-config-unsass": "^2.2.0",
-        "vitest": "^4.0.16"
+        "stylelint-config-unsass": "^2.3.0",
+        "vitest": "^5.0.1"
     },
     "dependencies": {
         "@unsass/string": "^1.4.2",
-        "@unsass/types": "^1.0.2",
-        "sass": "^1.97.1"
+        "@unsass/types": "^1.0.2"
+    },
+    "peerDependencies": {
+        "sass": ">=1.95.0"
     },
     "keywords": [
         "sass",
+        "scss",
         "selector",
         "class",
+        "pseudo",
+        "mixins",
+        "functions",
         "unsass",
         "front-end"
     ],
+    "author": "Front Factory",
     "license": "MIT",
     "homepage": "https://github.com/unsass/selector#readme",
     "bugs": {
@@ -54,6 +64,7 @@
         "CHANGELOG.md"
     ],
     "publishConfig": {
-        "access": "public"
+        "access": "public",
+        "provenance": true
     }
 }

package/src/_functions.scss

@@ -1,5 +1,5 @@
 // ============================================================================================= //
-//                                            MIXINS                                             //
+//                                           FUNCTIONS                                           //
 // ============================================================================================= //
 
 @use "sass:map";
@@ -21,6 +21,11 @@
 ///   $selector: pseudo-class(".foo", "hover");
 ///   // ".foo:hover"
 ///
+/// @param {string} $selector - Base selector.
+/// @param {string} $pseudo-class - Pseudo-class name (without the leading colon).
+///
+/// @return {string} The selector suffixed with the pseudo-class.
+///
 /// @access public
 ///
 @function pseudo-class($selector, $pseudo-class) {
@@ -29,24 +34,99 @@
 
 ///
 /// @example - scss
-///   $selector: pseudo-class(".foo", "before");
+///   $selector: pseudo-element(".foo", "before");
 ///   // ".foo::before"
 ///
+/// @param {string} $selector - Base selector.
+/// @param {string} $pseudo-element - Pseudo-element name (without the leading colons).
+///
+/// @return {string} The selector suffixed with the pseudo-element.
+///
 /// @access public
 ///
 @function pseudo-element($selector, $pseudo-element) {
     @return selector.append($selector, "::#{$pseudo-element}");
 }
 
+///
+/// @example - scss
+///   $selector: is("article", "h1", "h2");
+///   // "article:is(h1, h2)"
+///
+/// @param {string} $selector - Base selector.
+/// @param {arglist} $args - One or more selectors to match.
+///
+/// @return {selector} The selector restricted to the `:is()` matches.
+///
+/// @access public
+///
+@function is($selector, $args...) {
+    @return selector.append($selector, ":is(#{$args})");
+}
+
+///
+/// @example - scss
+///   $selector: where(".prose", "a", "button");
+///   // ".prose:where(a, button)"
+///
+/// @param {string} $selector - Base selector.
+/// @param {arglist} $args - One or more selectors to match (with zero specificity).
+///
+/// @return {selector} The selector restricted to the `:where()` matches.
+///
+/// @access public
+///
+@function where($selector, $args...) {
+    @return selector.append($selector, ":where(#{$args})");
+}
+
+///
+/// @example - scss
+///   $selector: has(".card", "> img");
+///   // ".card:has(> img)"
+///
+/// @param {string} $selector - Base selector.
+/// @param {arglist} $args - One or more relative selectors the element must contain.
+///
+/// @return {selector} The selector restricted to elements matching the `:has()` condition.
+///
+/// @access public
+///
+@function has($selector, $args...) {
+    @return selector.append($selector, ":has(#{$args})");
+}
+
+///
+/// Negation pseudo-class. Outputs the CSS `:not()` (renamed because `not` is a reserved Sass keyword).
+///
+/// @example - scss
+///   $selector: exclude(".btn", ".btn--disabled");
+///   // ".btn:not(.btn--disabled)"
+///
+/// @param {string} $selector - Base selector.
+/// @param {arglist} $args - One or more selectors to exclude.
+///
+/// @return {selector} The selector excluding the `:not()` matches.
+///
+/// @access public
+///
+@function exclude($selector, $args...) {
+    @return selector.append($selector, ":not(#{$args})");
+}
+
 ///
 /// @example - scss
 ///   $selector: to-id("foo");
 ///   // "#foo"
 ///
+/// @param {string} $name - Selector name (without the leading `#`).
+///
+/// @return {string} The id selector.
+///
 /// @access public
 ///
-@function to-id($selector) {
-    @return "##{$selector}";
+@function to-id($name) {
+    @return "##{$name}";
 }
 
 ///
@@ -54,8 +134,12 @@
 ///   $selector: to-class("foo");
 ///   // ".foo"
 ///
+/// @param {string} $name - Selector name (without the leading `.`).
+///
+/// @return {string} The class selector.
+///
 /// @access public
 ///
-@function to-class($selector) {
-    @return ".#{$selector}";
+@function to-class($name) {
+    @return ".#{$name}";
 }

package/src/_mixins.scss

@@ -25,7 +25,7 @@
 ///   }
 ///
 /// @example - css
-///   .md:foo {
+///   .md\:foo {
 ///     color: darkcyan;
 ///   }
 ///
@@ -50,11 +50,12 @@
 ///   }
 ///
 /// @param {string} $selector - Selector name.
-/// @param {string, list} $scope - Selector affix value.
-/// @param {string} $separator - Selector affix separator.
-/// @param {string} $pseudo-class - Selector pseudo-class.
-/// @param {string} $pseudo-element - Selector pseudo-element.
-/// @param {boolean} $suffix - Use suffix instead of prefix.
+/// @param {string | list} $scope [null] - Selector affix value.
+/// @param {string} $separator [":"] - Selector affix separator.
+/// @param {boolean} $suffix [false] - Use suffix instead of prefix.
+/// @param {string} $pseudo-class [null] - Selector pseudo-class.
+/// @param {string} $pseudo-element [null] - Selector pseudo-element.
+/// @param {boolean} $root [false] - Wrap the output in an `@at-root` rule.
 ///
 /// @see {function} functions.pseudo-class
 /// @see {function} functions.pseudo-element
@@ -157,10 +158,12 @@
 ///     }
 ///   }
 ///
+/// @param {string} $query - The media query condition.
+///
 /// @access public
 ///
-@mixin media($args) {
-    @media #{$args} {
+@mixin media($query) {
+    @media #{$query} {
         @content;
     }
 }