@cypress/unique-selector 2.1.1 → 2.1.3

package/README.md

@@ -1,115 +1,196 @@
-unique-selector
-===============
-
-[![Build Status](https://travis-ci.org/ericclemmons/unique-selector.png)](https://travis-ci.org/ericclemmons/unique-selector)
-[![CocoaPods](https://img.shields.io/cocoapods/l/AFNetworking.svg)]()
-[![semantic-versioning](https://img.shields.io/badge/semantic%20-versioning-green.svg)]()
+# unique-selector
 
 Given a DOM node, return a unique CSS selector matching only that element.
-This is particularly useful when tracking in custom variables in analytics:
 
+Selector uniqueness is determined based on the given element's root node. Elements rendered within Shadow DOM will derive a selector unique within the associated ShadowRoot context. Otherwise, a selector unique within an element's owning document will be derived.
 
-    document.addEventListener('click', function(event) {
-        var selector = unique(event.target);
+## Installation
 
-        _gaq.push(['_trackEvent', 'Engagement', 'Click', selector]);
-    }, false);
+![NPM Version](https://img.shields.io/npm/v/%40cypress%2Funique-selector)
 
-Selector uniqueness is determined based on the given element's root node. Elements rendered within Shadow DOM will derive a selector unique within the associated ShadowRoot context. Otherwise, a selector unique within an element's owning document will be derived.
+```bash
+npm install @cypress/unique-selector
+```
 
-Installation
-------------
+## API
 
-[![NPM](https://nodei.co/npm/unique-selector.png?mini=true)](https://nodei.co/npm/unique-selector/)
+### `unique(element, options)`
 
-Options
-------------
-e.g.1 DomElement = `<span id="test"></span>`
+Generates a unique CSS selector for the given DOM element.
 
-``` 
-import unique from 'unique-selector';
+#### Parameters
 
-// Optional Options
-options = {
-    // Array of selector types based on which the unique selector will generate
-    selectorTypes : [ 'ID', 'Class', 'Tag', 'NthChild' ]
-}
+- **`element`** (Element) - The DOM element for which to generate a unique selector
+- **`options`** (Object, optional) - Configuration options for selector generation
 
-unique( DomElement, options ); // #test
-```
+#### Options
 
-e.g.2 DomElement = `<span test="2"></span>`
+- **`selectorTypes`** (String[], optional) - Array of selector types to use in order of preference. Default: `['id', 'name', 'class', 'tag', 'nth-child']`
+  
+  Available selector types:
+  - `'id'` - Uses element's ID attribute (e.g., `#myId`)
+  - `'name'` - Uses element's name attribute (e.g., `[name="myName"]`)
+  - `'class'` - Uses element's class attributes (e.g., `.myClass`)
+  - `'tag'` - Uses element's tag name (e.g., `div`, `span`)
+  - `'nth-child'` - Uses nth-child position (e.g., `:nth-child(1)`)
+  - `'attributes'` - Uses all attributes except those in `attributesToIgnore`
+  - `'data-*'` - Uses specific data attributes (e.g., `data-foo`, `data-test-id`)
+  - `'attribute:*'` - Uses specific attributes (e.g., `attribute:role`, `attribute:aria-label`)
+
+- **`attributesToIgnore`** (String[], optional) - Array of attribute names to ignore when generating selectors. Default: `['id', 'class', 'length']`
+
+- **`filter`** (Function, optional) - A filter function to conditionally reject various traits when building selectors.
+  
+  ```javascript
+  function filter(type, key, value) {
+    // type: 'attribute', 'class', 'tag', 'nth-child'
+    // key: attribute name (for attributes), class name (for classes), etc.
+    // value: attribute value, class name, tag name, nth-child position
+    
+    // Return true to allow this trait, false to reject it
+    return true;
+  }
+  ```
 
-```
-import unique from 'unique-selector';
+- **`selectorCache`** (Map<Element, String>, optional) - Cache to improve performance of repeated selector generation. The caller is responsible for cache invalidation.
 
-// Optional Options
-options = {
-    // Array of selector types based on which the unique selector will be generate
-    selectorTypes : [ 'Attributes' ]
-}
+- **`isUniqueCache`** (Map<String, Boolean>, optional) - Cache to improve performance of repeated uniqueness checks. The caller is responsible for cache invalidation.
 
-unique( DomElement, options ); // [test="2"]
-```
+#### Returns
 
+- **String** - A unique CSS selector for the element, or `null` if no unique selector can be generated
 
-Tests
------
+## Usage Examples
 
-    $ npm run test
+### Basic Usage
 
-    
-Contributing
------
-Feel free to open issues, make suggestions or send PRs.
-This project adheres to the Contributor Covenant [code of conduct](http://contributor-covenant.org/). By participating, you are expected to uphold this code.
+```javascript
+import unique from '@cypress/unique-selector';
 
+// Get a unique selector for an element
+const element = document.querySelector('.my-button');
+const selector = unique(element);
+// Returns: '#my-button' or '.my-button' or 'button' etc.
+```
 
-Contact
------
+### Custom Selector Types
 
-Avraam Mavridis : [@avraamakis](https://twitter.com/avraamakis)
+```javascript
+// Use only ID and class selectors
+const selector = unique(element, {
+    selectorTypes: ['id', 'class']
+});
 
-Eric Clemmons : [@ericclemmons](https://twitter.com/ericclemmons)
+// Use only data attributes
+const selector = unique(element, {
+    selectorTypes: ['data-test-id', 'data-cy']
+});
 
+// Use specific attributes
+const selector = unique(element, {
+    selectorTypes: ['attribute:role', 'attribute:aria-label']
+});
+```
 
-Releases
---------
+### Filtering Selectors
+
+```javascript
+// Filter out certain IDs
+const selector = unique(element, {
+    filter: (type, key, value) => {
+        if (type === 'attribute' && key === 'id') {
+            // Only allow IDs that contain 'test'
+            return value.includes('test');
+        }
+        return true;
+    }
+});
+
+// Filter out certain classes
+const selector = unique(element, {
+    filter: (type, key, value) => {
+        if (type === 'class') {
+            // Only allow classes that start with 'btn-'
+            return value.startsWith('btn-');
+        }
+        return true;
+    }
+});
+```
 
-- v2.1.0
-  
-    - 
+### Performance Optimization with Caching
 
-- v0.1.0
+```javascript
+const selectorCache = new Map();
+const isUniqueCache = new Map();
 
-    - Big refactor/rewrite using es6
-    - More test + Change the test script
-    - Script to compile es6 to es5 using babel
-    - Ability to pass options for the **selectorTypes** based on which the unique selector will be generated, see the options
+const selector = unique(element, {
+    selectorCache,
+    isUniqueCache
+});
 
+// Reuse the same caches for multiple calls
+const selector2 = unique(anotherElement, {
+    selectorCache,
+    isUniqueCache
+});
+```
 
-- v0.0.4
+### Shadow DOM Support
 
-    - Handle extra whitespace in `className` ([#9](https://github.com/ericclemmons/unique-selector/pull/9))
+```javascript
+// Works with Shadow DOM elements
+const shadowHost = document.querySelector('#shadow-host');
+const shadowRoot = shadowHost.attachShadow({ mode: 'open' });
+const shadowElement = shadowRoot.querySelector('.shadow-button');
 
-- v0.0.3
+const selector = unique(shadowElement);
+// Returns a selector unique within the shadow root context
+```
 
-    - Add support for various `<form>` elements ([#2](https://github.com/ericclemmons/unique-selector/issues/2))
+## Selector Generation Strategy
 
-- v0.0.2
+The library follows this strategy to generate unique selectors:
 
-    - Fix bug with `nth-child` calculation
+1. **Element-level uniqueness**: First tries to find a selector that uniquely identifies the element within its parent
+2. **Parent traversal**: If element-level uniqueness fails, traverses up the DOM tree, building a path of selectors
+3. **Selector type precedence**: Uses the `selectorTypes` array to determine which selector types to try first
+4. **Combination fallback**: For classes and attributes, tries combinations of multiple selectors if single selectors aren't unique
+5. **Nth-child fallback**: Uses nth-child positioning as a last resort
 
-- v0.0.1
+## Examples of Generated Selectors
 
-    - Initial release
+```html
+<!-- Element with ID -->
+<div id="header">Header</div>
+<!-- Selector: #header -->
 
+<!-- Element with unique class -->
+<button class="submit-btn">Submit</button>
+<!-- Selector: .submit-btn -->
 
+<!-- Element with multiple classes -->
+<div class="card primary large">Card</div>
+<!-- Selector: .card.primary.large -->
 
-License
--------
+<!-- Element with data attributes -->
+<div data-test-id="user-profile">Profile</div>
+<!-- Selector: [data-test-id="user-profile"] -->
 
-MIT
+<!-- Element with custom attributes -->
+<button role="button" aria-label="Close">×</button>
+<!-- Selector: [role="button"] or [aria-label="Close"] -->
 
+<!-- Element requiring nth-child -->
+<div class="item">Item 1</div>
+<div class="item">Item 2</div>
+<!-- Selector: :nth-child(1) or :nth-child(2) -->
 
-[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/AvraamMavridis/unique-selector/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
+<!-- Complex nested element -->
+<div class="container">
+  <div class="wrapper">
+    <span class="text">Hello</span>
+  </div>
+</div>
+<!-- Selector: .container > .wrapper > .text -->
+```

package/lib/index.js

@@ -25,6 +25,8 @@ var _getParents = require('./getParents');
 
 var _getAttribute = require('./getAttribute');
 
+var _isShadowRoot = require('./isShadowRoot');
+
 function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } else { return Array.from(arr); } } /**
                                                                                                                                                                                                      * Expose `unique`
                                                                                                                                                                                                      */
@@ -297,6 +299,19 @@ function unique(el) {
       if (isUniqueCache) {
         isUniqueCache.set(maybeUniqueSelector, isUniqueSelector);
       }
+
+      // If the selector is not unique but we detect we've reached a ShadowRoot attempt
+      // to prefix the selector with `:host >` to anchor against the root. This helps
+      // address the possibility of a unique path segment not existing before reaching
+      // the root.
+      if (!isUniqueSelector && el.parentNode && (0, _isShadowRoot.isShadowRoot)(el.parentNode)) {
+        maybeUniqueSelector = ':host > ' + maybeUniqueSelector;
+        isUniqueSelector = (0, _isUnique.isUnique)(el, maybeUniqueSelector);
+
+        if (isUniqueCache) {
+          isUniqueCache.set(maybeUniqueSelector, isUniqueSelector);
+        }
+      }
     }
 
     if (isUniqueSelector) {

package/lib/isShadowRoot.js

@@ -0,0 +1,15 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isShadowRoot = isShadowRoot;
+/**
+ * Checks if the supplied node is a ShadowRoot
+ * 
+ * @param  { Object } element
+ * @return { Boolean }
+ */
+function isShadowRoot(node) {
+  return Object.getPrototypeOf(node).constructor.name === 'ShadowRoot';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cypress/unique-selector",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Given a DOM node, return a unique CSS selector matching only that element",
   "main": "./lib/index.js",
   "jsnext:main": "./src/index.js",
@@ -39,12 +39,11 @@
     "babel-register": "^6.26.0",
     "chai": "^4.3.4",
     "component": "~1.1.0",
-    "eslint": "^8.0.1",
-    "eslint-config-airbnb": "^18.2.1",
-    "eslint-config-airbnb-lite": "^1.0.4",
-    "eslint-plugin-react": "^7.26.1",
+    "eslint": "^8.57.1",
+    "eslint-config-airbnb": "^19.0.0",
+    "eslint-plugin-react": "^7.37.5",
     "jquery": "^3.6.0",
-    "jsdom": "^18.0.0",
+    "jsdom": "^27.4.0",
     "mocha": "~9.1.3",
     "mocha-jsdom": "^2.0.0",
     "mocha-phantomjs": "~4.1.0",