make specificity calculation customizable (#1392)

packages/selector-specificity/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changes to Selector Specificity
 
+### Unreleased (minor)
+
+- Add an option to `selectorSpecificity` and `specificityOfMostSpecificListItem` to customize the calculation
+- Add `specificityOfMostSpecificListItem` as an exported function
+
 ### 3.0.3
 
 _March 31, 2024_

packages/selector-specificity/dist/index.cjs

@@ -1 +1 @@
-"use strict";var e=require("postcss-selector-parser");function selectorSpecificity(s){if(!s)return{a:0,b:0,c:0};let t=0,i=0,c=0;if("universal"==s.type)return{a:0,b:0,c:0};if("id"===s.type)t+=1;else if("tag"===s.type)c+=1;else if("class"===s.type)i+=1;else if("attribute"===s.type)i+=1;else if(isPseudoElement(s))switch(s.value.toLowerCase()){case"::slotted":if(c+=1,s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case"::view-transition-group":case"::view-transition-image-pair":case"::view-transition-old":case"::view-transition-new":return s.nodes&&1===s.nodes.length&&"selector"===s.nodes[0].type&&selectorNodeContainsNothingOrOnlyUniversal(s.nodes[0])?{a:0,b:0,c:0}:{a:0,b:0,c:1};default:c+=1}else if(e.isPseudoClass(s))switch(s.value.toLowerCase()){case":-webkit-any":case":any":default:i+=1;break;case":-moz-any":case":has":case":is":case":matches":case":not":if(s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case":where":break;case":nth-child":case":nth-last-child":if(i+=1,s.nodes&&s.nodes.length>0){const n=s.nodes[0].nodes.findIndex((e=>"tag"===e.type&&"of"===e.value.toLowerCase()));if(n>-1){const o=[e.selector({nodes:s.nodes[0].nodes.slice(n+1),value:""})];s.nodes.length>1&&o.push(...s.nodes.slice(1));const a=specificityOfMostSpecificListItem(o);t+=a.a,i+=a.b,c+=a.c}}break;case":local":case":global":s.nodes&&s.nodes.length>0&&s.nodes.forEach((e=>{const s=selectorSpecificity(e);t+=s.a,i+=s.b,c+=s.c}));break;case":host":case":host-context":if(i+=1,s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case":active-view-transition":case":active-view-transition-type":return{a:0,b:1,c:0}}else e.isContainer(s)&&s.nodes.length>0&&s.nodes.forEach((e=>{const s=selectorSpecificity(e);t+=s.a,i+=s.b,c+=s.c}));return{a:t,b:i,c:c}}function specificityOfMostSpecificListItem(e){let s={a:0,b:0,c:0};return e.forEach((e=>{const t=selectorSpecificity(e);t.a>s.a?s=t:t.a<s.a||(t.b>s.b?s=t:t.b<s.b||t.c>s.c&&(s=t))})),s}function isPseudoElement(s){return e.isPseudoElement(s)}function selectorNodeContainsNothingOrOnlyUniversal(e){if(!e)return!1;if(!e.nodes)return!1;const s=e.nodes.filter((e=>"comment"!==e.type));return 0===s.length||1===s.length&&"universal"===s[0].type}exports.compare=function compare(e,s){return e.a===s.a?e.b===s.b?e.c-s.c:e.b-s.b:e.a-s.a},exports.selectorSpecificity=selectorSpecificity;
+"use strict";var e=require("postcss-selector-parser");function selectorSpecificity(t,s){const i=s?.customSpecificity?.(t);if(i)return i;if(!t)return{a:0,b:0,c:0};let c=0,n=0,o=0;if("universal"==t.type)return{a:0,b:0,c:0};if("id"===t.type)c+=1;else if("tag"===t.type)o+=1;else if("class"===t.type)n+=1;else if("attribute"===t.type)n+=1;else if(isPseudoElement(t))switch(t.value.toLowerCase()){case"::slotted":if(o+=1,t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case"::view-transition-group":case"::view-transition-image-pair":case"::view-transition-old":case"::view-transition-new":return t.nodes&&1===t.nodes.length&&"selector"===t.nodes[0].type&&selectorNodeContainsNothingOrOnlyUniversal(t.nodes[0])?{a:0,b:0,c:0}:{a:0,b:0,c:1};default:o+=1}else if(e.isPseudoClass(t))switch(t.value.toLowerCase()){case":-webkit-any":case":any":default:n+=1;break;case":-moz-any":case":has":case":is":case":matches":case":not":if(t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case":where":break;case":nth-child":case":nth-last-child":if(n+=1,t.nodes&&t.nodes.length>0){const i=t.nodes[0].nodes.findIndex((e=>"tag"===e.type&&"of"===e.value.toLowerCase()));if(i>-1){const a=e.selector({nodes:[],value:""});a.parent=t;t.nodes[0].nodes.slice(i+1).forEach((e=>{e.remove(),a.append(e)}));const r=[a];t.nodes.length>1&&r.push(...t.nodes.slice(1));const f=specificityOfMostSpecificListItem(r,s);c+=f.a,n+=f.b,o+=f.c}}break;case":local":case":global":t.nodes&&t.nodes.length>0&&t.nodes.forEach((e=>{const t=selectorSpecificity(e,s);c+=t.a,n+=t.b,o+=t.c}));break;case":host":case":host-context":if(n+=1,t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case":active-view-transition":case":active-view-transition-type":return{a:0,b:1,c:0}}else e.isContainer(t)&&t.nodes.length>0&&t.nodes.forEach((e=>{const t=selectorSpecificity(e,s);c+=t.a,n+=t.b,o+=t.c}));return{a:c,b:n,c:o}}function specificityOfMostSpecificListItem(e,t){let s={a:0,b:0,c:0};return e.forEach((e=>{const i=selectorSpecificity(e,t);i.a>s.a?s=i:i.a<s.a||(i.b>s.b?s=i:i.b<s.b||i.c>s.c&&(s=i))})),s}function isPseudoElement(t){return e.isPseudoElement(t)}function selectorNodeContainsNothingOrOnlyUniversal(e){if(!e)return!1;if(!e.nodes)return!1;const t=e.nodes.filter((e=>"comment"!==e.type));return 0===t.length||1===t.length&&"universal"===t[0].type}exports.compare=function compare(e,t){return e.a===t.a?e.b===t.b?e.c-t.c:e.b-t.b:e.a-t.a},exports.selectorSpecificity=selectorSpecificity,exports.specificityOfMostSpecificListItem=specificityOfMostSpecificListItem;

packages/selector-specificity/dist/index.d.ts

@@ -1,10 +1,55 @@
 import type { Node } from 'postcss-selector-parser';
 
+/**
+ * Options for the calculation of the specificity of a selector
+ */
+export declare type CalculationOptions = {
+    /**
+     * The callback to calculate a custom specificity for a node
+     */
+    customSpecificity?: CustomSpecificityCallback;
+};
+
+/**
+ * Compare two specificities
+ * @param s1 The first specificity
+ * @param s2 The second specificity
+ * @returns A value smaller than `0` if `s1` is less specific than `s2`, `0` if `s1` is equally specific as `s2`, a value larger than `0` if `s1` is more specific than `s2`
+ */
 export declare function compare(s1: Specificity, s2: Specificity): number;
 
-export declare function selectorSpecificity(node: Node): Specificity;
+/**
+ * Calculate a custom specificity for a node
+ */
+export declare type CustomSpecificityCallback = (node: Node) => Specificity | void | false | null | undefined;
 
+/**
+ * Calculate the specificity for a selector
+ */
+export declare function selectorSpecificity(node: Node, options?: CalculationOptions): Specificity;
+
+/**
+ * The specificity of a selector
+ */
 export declare type Specificity = {
+    /**
+     * The number of ID selectors in the selector
+     */
+    a: number;
+    /**
+     * The number of class selectors, attribute selectors, and pseudo-classes in the selector
+     */
+    b: number;
+    /**
+     * The number of type selectors and pseudo-elements in the selector
+     */
+    c: number;
+};
+
+/**
+ * Calculate the most specific selector in a list
+ */
+export declare function specificityOfMostSpecificListItem(nodes: Array<Node>, options?: CalculationOptions): {
     a: number;
     b: number;
     c: number;

packages/selector-specificity/dist/index.mjs

@@ -1 +1 @@
-import e from"postcss-selector-parser";function compare(e,s){return e.a===s.a?e.b===s.b?e.c-s.c:e.b-s.b:e.a-s.a}function selectorSpecificity(s){if(!s)return{a:0,b:0,c:0};let t=0,i=0,c=0;if("universal"==s.type)return{a:0,b:0,c:0};if("id"===s.type)t+=1;else if("tag"===s.type)c+=1;else if("class"===s.type)i+=1;else if("attribute"===s.type)i+=1;else if(isPseudoElement(s))switch(s.value.toLowerCase()){case"::slotted":if(c+=1,s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case"::view-transition-group":case"::view-transition-image-pair":case"::view-transition-old":case"::view-transition-new":return s.nodes&&1===s.nodes.length&&"selector"===s.nodes[0].type&&selectorNodeContainsNothingOrOnlyUniversal(s.nodes[0])?{a:0,b:0,c:0}:{a:0,b:0,c:1};default:c+=1}else if(e.isPseudoClass(s))switch(s.value.toLowerCase()){case":-webkit-any":case":any":default:i+=1;break;case":-moz-any":case":has":case":is":case":matches":case":not":if(s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case":where":break;case":nth-child":case":nth-last-child":if(i+=1,s.nodes&&s.nodes.length>0){const n=s.nodes[0].nodes.findIndex((e=>"tag"===e.type&&"of"===e.value.toLowerCase()));if(n>-1){const o=[e.selector({nodes:s.nodes[0].nodes.slice(n+1),value:""})];s.nodes.length>1&&o.push(...s.nodes.slice(1));const a=specificityOfMostSpecificListItem(o);t+=a.a,i+=a.b,c+=a.c}}break;case":local":case":global":s.nodes&&s.nodes.length>0&&s.nodes.forEach((e=>{const s=selectorSpecificity(e);t+=s.a,i+=s.b,c+=s.c}));break;case":host":case":host-context":if(i+=1,s.nodes&&s.nodes.length>0){const e=specificityOfMostSpecificListItem(s.nodes);t+=e.a,i+=e.b,c+=e.c}break;case":active-view-transition":case":active-view-transition-type":return{a:0,b:1,c:0}}else e.isContainer(s)&&s.nodes.length>0&&s.nodes.forEach((e=>{const s=selectorSpecificity(e);t+=s.a,i+=s.b,c+=s.c}));return{a:t,b:i,c:c}}function specificityOfMostSpecificListItem(e){let s={a:0,b:0,c:0};return e.forEach((e=>{const t=selectorSpecificity(e);t.a>s.a?s=t:t.a<s.a||(t.b>s.b?s=t:t.b<s.b||t.c>s.c&&(s=t))})),s}function isPseudoElement(s){return e.isPseudoElement(s)}function selectorNodeContainsNothingOrOnlyUniversal(e){if(!e)return!1;if(!e.nodes)return!1;const s=e.nodes.filter((e=>"comment"!==e.type));return 0===s.length||1===s.length&&"universal"===s[0].type}export{compare,selectorSpecificity};
+import e from"postcss-selector-parser";function compare(e,t){return e.a===t.a?e.b===t.b?e.c-t.c:e.b-t.b:e.a-t.a}function selectorSpecificity(t,s){const i=s?.customSpecificity?.(t);if(i)return i;if(!t)return{a:0,b:0,c:0};let c=0,n=0,o=0;if("universal"==t.type)return{a:0,b:0,c:0};if("id"===t.type)c+=1;else if("tag"===t.type)o+=1;else if("class"===t.type)n+=1;else if("attribute"===t.type)n+=1;else if(isPseudoElement(t))switch(t.value.toLowerCase()){case"::slotted":if(o+=1,t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case"::view-transition-group":case"::view-transition-image-pair":case"::view-transition-old":case"::view-transition-new":return t.nodes&&1===t.nodes.length&&"selector"===t.nodes[0].type&&selectorNodeContainsNothingOrOnlyUniversal(t.nodes[0])?{a:0,b:0,c:0}:{a:0,b:0,c:1};default:o+=1}else if(e.isPseudoClass(t))switch(t.value.toLowerCase()){case":-webkit-any":case":any":default:n+=1;break;case":-moz-any":case":has":case":is":case":matches":case":not":if(t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case":where":break;case":nth-child":case":nth-last-child":if(n+=1,t.nodes&&t.nodes.length>0){const i=t.nodes[0].nodes.findIndex((e=>"tag"===e.type&&"of"===e.value.toLowerCase()));if(i>-1){const a=e.selector({nodes:[],value:""});a.parent=t;t.nodes[0].nodes.slice(i+1).forEach((e=>{e.remove(),a.append(e)}));const r=[a];t.nodes.length>1&&r.push(...t.nodes.slice(1));const l=specificityOfMostSpecificListItem(r,s);c+=l.a,n+=l.b,o+=l.c}}break;case":local":case":global":t.nodes&&t.nodes.length>0&&t.nodes.forEach((e=>{const t=selectorSpecificity(e,s);c+=t.a,n+=t.b,o+=t.c}));break;case":host":case":host-context":if(n+=1,t.nodes&&t.nodes.length>0){const e=specificityOfMostSpecificListItem(t.nodes,s);c+=e.a,n+=e.b,o+=e.c}break;case":active-view-transition":case":active-view-transition-type":return{a:0,b:1,c:0}}else e.isContainer(t)&&t.nodes.length>0&&t.nodes.forEach((e=>{const t=selectorSpecificity(e,s);c+=t.a,n+=t.b,o+=t.c}));return{a:c,b:n,c:o}}function specificityOfMostSpecificListItem(e,t){let s={a:0,b:0,c:0};return e.forEach((e=>{const i=selectorSpecificity(e,t);i.a>s.a?s=i:i.a<s.a||(i.b>s.b?s=i:i.b<s.b||i.c>s.c&&(s=i))})),s}function isPseudoElement(t){return e.isPseudoElement(t)}function selectorNodeContainsNothingOrOnlyUniversal(e){if(!e)return!1;if(!e.nodes)return!1;const t=e.nodes.filter((e=>"comment"!==e.type));return 0===t.length||1===t.length&&"universal"===t[0].type}export{compare,selectorSpecificity,specificityOfMostSpecificListItem};

packages/selector-specificity/docs/selector-specificity.api.json

@@ -171,10 +171,45 @@
       "name": "",
       "preserveMemberOrder": false,
       "members": [
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@csstools/selector-specificity!CalculationOptions:type",
+          "docComment": "/**\n * Options for the calculation of the specificity of a selector\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type CalculationOptions = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    customSpecificity?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "CustomSpecificityCallback",
+              "canonicalReference": "@csstools/selector-specificity!CustomSpecificityCallback:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/_types/index.d.ts",
+          "releaseTag": "Public",
+          "name": "CalculationOptions",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@csstools/selector-specificity!compare:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Compare two specificities\n *\n * @param s1 - The first specificity\n *\n * @param s2 - The second specificity\n *\n * @returns A value smaller than `0` if `s1` is less specific than `s2`, `0` if `s1` is equally specific as `s2`, a value larger than `0` if `s1` is more specific than `s2`\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -234,10 +269,54 @@
           ],
           "name": "compare"
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@csstools/selector-specificity!CustomSpecificityCallback:type",
+          "docComment": "/**\n * Calculate a custom specificity for a node\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type CustomSpecificityCallback = "
+            },
+            {
+              "kind": "Content",
+              "text": "(node: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Node",
+              "canonicalReference": "postcss-selector-parser!parser.Node:type"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Reference",
+              "text": "Specificity",
+              "canonicalReference": "@csstools/selector-specificity!Specificity:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | void | false | null | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/_types/index.d.ts",
+          "releaseTag": "Public",
+          "name": "CustomSpecificityCallback",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@csstools/selector-specificity!selectorSpecificity:function(1)",
-          "docComment": "",
+          "docComment": "/**\n * Calculate the specificity for a selector\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -248,6 +327,15 @@
               "text": "Node",
               "canonicalReference": "postcss-selector-parser!parser.Node:type"
             },
+            {
+              "kind": "Content",
+              "text": ", options?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "CalculationOptions",
+              "canonicalReference": "@csstools/selector-specificity!CalculationOptions:type"
+            },
             {
               "kind": "Content",
               "text": "): "
@@ -264,8 +352,8 @@
           ],
           "fileUrlPath": "dist/_types/index.d.ts",
           "returnTypeTokenRange": {
-            "startIndex": 3,
-            "endIndex": 4
+            "startIndex": 5,
+            "endIndex": 6
           },
           "releaseTag": "Public",
           "overloadIndex": 1,
@@ -277,14 +365,22 @@
                 "endIndex": 2
               },
               "isOptional": false
+            },
+            {
+              "parameterName": "options",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": true
             }
           ],
           "name": "selectorSpecificity"
         },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@csstools/selector-specificity!Specificity:type",
-          "docComment": "",
+          "docComment": "/**\n * The specificity of a selector\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -306,6 +402,82 @@
             "startIndex": 1,
             "endIndex": 2
           }
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@csstools/selector-specificity!specificityOfMostSpecificListItem:function(1)",
+          "docComment": "/**\n * Calculate the most specific selector in a list\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function specificityOfMostSpecificListItem(nodes: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Array",
+              "canonicalReference": "!Array:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "Node",
+              "canonicalReference": "postcss-selector-parser!parser.Node:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ", options?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "CalculationOptions",
+              "canonicalReference": "@csstools/selector-specificity!CalculationOptions:type"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    a: number;\n    b: number;\n    c: number;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/_types/index.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 8,
+            "endIndex": 9
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "nodes",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "options",
+              "parameterTypeTokenRange": {
+                "startIndex": 6,
+                "endIndex": 7
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "specificityOfMostSpecificListItem"
         }
       ]
     }