@semantic-ui/query - npm Package Compare versions

Comparing version 0.0.25 to 0.0.26

package.json

 {
   "name": "@semantic-ui/query",
   "type": "module",
-  "main": "src/index.js",
+  "main": "src/index.cjs",
   "module": "src/index.js",
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./src/node-wrapper.js",
+        "default": "./src/index.cjs"
+      },
+      "module": {
+        "import": "./src/index.js",
+        "default": "./src/bundler-require-wrapper.js"
+      },
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
   "author": "Jack Lukic",
@@ -12,5 +26,5 @@ "license": "ISC",
   "dependencies": {
-    "@semantic-ui/utils": "^0.0.25"
+    "@semantic-ui/utils": "^0.0.26"
   },
-  "version": "0.0.25"
+  "version": "0.0.26"
 }

README.md

 # @semantic-ui/query
 
-Query is a **tiny (3kb!) library** for chaining interactions with DOM elements similar to jQuery.
+Query is a tiny (3kb!) library for chaining interactions with DOM elements, similar to jQuery. It is designed to work with the Shadow DOM tree, correctly matching on nested shadow DOMs in pages that use web components.
 
-It is designed to work with the Shadow DOM tree, correctly matching on nested shadow DOMs in pages that use web components.
+## Features
 
-It's designed to be fast, using only modern DOM APIs and built to work with the shadow DOM and help simplify imperative DOM mutations.
+- Fast and lightweight, using only modern DOM APIs
+- Built to work with the Shadow DOM
+- Simplifies imperative DOM mutations
+- Provides a familiar API for developers experienced with jQuery
 
-There's many reasons why you might use this over vanilla just DOM APIs, consider removing event handlers which requires you to track a reference to the original event handler to unbind, or setting up basic interaction patterns like [event delegation](https://learn.jquery.com/events/event-delegation/).
+## Installation
 
-Query supports the following methods:
+You can install Query using npm:
 
+```bash
+npm install @semantic-ui/query
+```
+
+## Usage
+
+### Standard
+
+```javascript
+import { $ } from '@semantic-ui/query';
+```
+
+### CommonJS
+
+```javascript
+const { $ } = require('@semantic-ui/query');
+```
+
+### Browser
+
+In a browser environment you may want to use `exportGlobals` to export $ and $$ for use
+
+```javascript
+  import { exportGlobals } from '@semantic-ui/query';
+
+  exportGlobals();
+
+
+#### Restoring Globals
+If you need to restore the previous values before calling export globals.
+```javascript
+  import { restoreGlobals } from '@semantic-ui/query';
+  restoreGlobals();
+```
+
+#### Custom Alias
+If you prefer to use a custom alias
+```javascript
+  import { useAlias } from '@semantic-ui/query';
+
+  const myQuery = useAlias();
+
+  // myQuery('div')
+```
+
+
+## API
+
 ### Querying DOM
-* `filter(selector)` - Filter current node list to match selector.
-* `children(selector)` - Return only child nodes matching a selector.
-* `parent(selector)` - Find the parent elements matching a selector.
-* `find(selector)` - Find child elements matching a selector.
-* `not(selector)` - Return only elements not matching a selector.
-* `closest(selector)` - Find the closest parent element matching a selector.
-* `is(selector)` - returns true if the current elements all match a selector.
-- `not(seletor)` - returns true if the current elements all do not match a selector.
 
+- `filter(selector)` - Filter current node list to match selector.
+- `children(selector)` - Return only child nodes matching a selector.
+- `parent(selector)` - Find the parent elements matching a selector.
+- `find(selector)` - Find child elements matching a selector.
+- `not(selector)` - Return only elements not matching a selector.
+- `closest(selector)` - Find the closest parent element matching a selector.
+- `is(selector)` - Returns true if the current elements all match a selector.
+- `siblings(selector)` - Return sibling elements matching a selector.
+- `index(indexFilter)` - Return the index of the element among its siblings or within the collection.
+
 ### Attributes
-` `hasClass(className)` - Returns true if class name is present on some elements
-* `addClass(classNames)` - Add class names to elements.
-* `removeClass(classNames)` - Remove class names from elements.
-# `toggleClass(classNames)` - Toggles class names on elements.
-* `css(property, value)` - Gets or sets CSS properties on an element. Accepts either two parameters or an object of properties to change. Will not return computed styles by default.
-* `cssVar(varName, newValue)` - Get/set a css var
-# `computedStyle(property)` - Gets the computed CSS for an element
-* `attr(attribute, value)` - Get/Set an attribute to a value. Accepts either two parameters or an object of attributes to change.
-* `removeAttr(attributeName)` - Remove a specified attribute from each element in the set of matched elements.
 
+- `hasClass(className)` - Returns true if class name is present on some elements.
+- `addClass(classNames)` - Add class names to elements.
+- `removeClass(classNames)` - Remove class names from elements.
+- `toggleClass(classNames)` - Toggles class names on elements.
+- `css(property, value, settings)` - Gets or sets CSS properties on an element. Accepts either two parameters or an object of properties to change. Will not return computed styles by default.
+- `cssVar(variable, value)` - Get/set a CSS variable.
+- `computedStyle(property)` - Gets the computed CSS for an element.
+- `attr(attribute, value)` - Get/Set an attribute to a value. Accepts either two parameters or an object of attributes to change.
+- `removeAttr(attributeName)` - Remove a specified attribute from each element in the set of matched elements.
+- `prop(name, value)` - Get/Set a property on an element.
+
 ### Content
-* `html(newHTML)` - Get or set HTML for the current node list.
-* `outerHTML(newHTML)` - Get or set outer HTML for the current node list. Outer HTML includes the current tag contents in the returned HTML.
-* `text(newText)` - Get or set text for the current node list. This is recursive, getting all child text nodes and works with slotted content.
-* `textNode()` - Gets the current text node of the matched elements. This is not recursive.
 
-## Sizing
-- `width()` - get the width of an element
-- `height()` get the height of an element
-- `scrollHeight()` - get the scroll height of an element
-- `scrollWidth()`- get the scroll width of an element
-- `offsetParent()` - get the offset parent of an element for positioning.
+- `html(newHTML)` - Get or set HTML for the current node list.
+- `outerHTML(newHTML)` - Get or set outer HTML for the current node list. Outer HTML includes the current tag contents in the returned HTML.
+- `text(newText)` - Get or set text for the current node list. This is recursive, getting all child text nodes and works with slotted content.
+- `textNode()` - Gets the current text node of the matched elements. This is not recursive.
 
+### Sizing
+
+- `width(value)` - Get or set the width of an element.
+- `height(value)` - Get or set the height of an element.
+- `scrollHeight(value)` - Get or set the scroll height of an element.
+- `scrollWidth(value)` - Get or set the scroll width of an element.
+- `scrollLeft(value)` - Get or set the scrollLeft position of an element.
+- `scrollTop(value)` - Get or set the scrollTop position of an element.
+- `offsetParent(options)` - Get the offset parent of an element for positioning.
+- `naturalWidth()` - Get the natural width of an element.
+- `naturalHeight()` - Get the natural height of an element.
+
 ### Events
-* `on(event, targetSelectorOrHandler, handler)` - Attach an event using either event delegation (i.e., `.on('childNode', 'click', func)`) or regular event binding (i.e., `.on('click', func)`).
-* `one(event, targetSelectorOrHandler, handler, options)` - Attach an event handler that fires only once
-* `off(event, handler)` - Removes an event either by event type or handler.
-* `dispatchEvent(eventName, data, eventSettings)` - Dispatch an event from an element with data
 
+- `on(event, targetSelectorOrHandler, handlerOrOptions, options)` - Attach an event using either event delegation or regular event binding.
+- `one(event, targetSelectorOrHandler, handlerOrOptions, options)` - Attach an event handler that fires only once.
+- `off(event, handler)` - Removes an event either by event type or handler.
+- `dispatchEvent(eventName, eventData, eventSettings)` - Dispatch an event from an element with data.
+
 ### DOM Manipulation
-* `remove()` - Remove current elements from the DOM.
 
+- `remove()` - Remove current elements from the DOM.
+- `clone()` - Create a deep clone of the elements in the Query instance.
+- `insertAfter(selector)` - Insert elements after each target element.
+
 ### Utilities
-* `each(function(el, index) => {})` - Run a function across a series of DOM nodes.
-* `get(index)` - Returns the real DOM element from the node list at the matching index (no longer chainable).
-* `eq(index)` - Filters node list to only include the element at the index (still chainable).
-* `initialize(settings)` - Adds the settings to given element after DOM content has loaded.
 
+- `each(callback)` - Run a function across a series of DOM nodes.
+- `get(index)` - Returns the real DOM element from the node list at the matching index (no longer chainable).
+- `eq(index)` - Filters node list to only include the element at the index (still chainable).
+- `initialize(settings)` - Adds the settings to given element after DOM content has loaded.
+- `map(callback)` - Apply a function to every element and return the results as an array.
+- `count()` - Get the number of elements in the Query instance.
+- `exists()` - Check if the Query instance contains any elements.
+
 ### Form
-* `value(newValue)` - Get the current value of the first element in the set of matched elements or set the value of every matched element. This method is an alias for `value(newValue)`.
 
+- `value(newValue)` - Get the current value of the first element in the set of matched elements or set the value of every matched element. This method is an alias for `val()`.
+
 ### Event Handling
-* `focus()` - Sets focus on the first element in the set of matched elements.
-* `blur()` - Removes focus from the first element in the set of matched elements.
+
+- `focus()` - Sets focus on the first element in the set of matched elements.
+- `blur()` - Removes focus from the first element in the set of matched elements.
+
+### Internal
+- `chain(elements)` - Create a new Query instance with the provided elements.
+
+
+### Global Export
+
+Query allows you to opt-in to exporting globals in a browser environment. You can use the `exportGlobals` function to attach `$`, `$$`, and `Query` to the global scope.
+
+```html
+
+  import { exportGlobals } from 'https://unpkg.com/@semantic-ui/query';
+
+  exportGlobals({
+    $: true,
+    $$: true,
+    Query: false
+  });
+
+  // Use $ and $$ globally
+  $('selector');
+  $$('selector');
+
+```
+
+You can also use `$.noConflict()` to restore the original values of `$` and `$$` and assign Query to a different variable:
+
+```html
+
+  import { exportGlobals } from 'https://unpkg.com/@semantic-ui/query';
+
+  exportGlobals();
+
+  const myQuery = $.noConflict();
+
+  // Use myQuery instead of $
+  myQuery('div').addClass('active');
+
+```
+
+## License
+
+Query is licensed under the MIT License. See [LICENSE](LICENSE) for more information.

src/index.js

@@ -0,1 +1,2 @@
+import { isClient } from '@semantic-ui/utils';
 import { Query } from './query.js';
@@ -5,3 +6,3 @@
   const isClient = typeof window !== 'undefined';
-  if(!args?.root && isClient) {
+  if (!args?.root && isClient) {
     args.root = document;
@@ -12,2 +13,49 @@ }
 
-export { Query, $ };
+const $$ = function (selector, args = {}) {
+  args.pierceShadow = true;
+  return $(selector, args);
+};
+
+let originalDollar;
+let originalDoubleDollar;
+
+const exportGlobals = function({ dollar = true, doubleDollar = true, query = true} = {}) {
+  if (isClient) {
+
+
+    if(dollar) {
+      originalDollar = window.$;
+      window.$ = $;
+    }
+
+    if (doubleDollar) {
+      originalDoubleDollar = window.$$;
+      window.$$ = $$;
+    }
+
+    if (query) {
+      window.Query = Query;
+    }
+  }
+}
+
+// Add a restoreGlobals method to restore the original values of $ and $$
+const restoreGlobals = function(settings) {
+  if (window.$ === $) {
+    window.$ = originalDollar;
+  }
+  if (window.$$ === $$) {
+    window.$$ = originalDoubleDollar;
+  }
+  if (typeof settings == 'object' && settings.removeQuery && window.Query === Query) {
+    window.Query = undefined;
+  }
+  return $;
+};
+
+// Bind Query to a different alias than $
+const useAlias = function() {
+  return new Query(...arguments);
+};
+
+export { Query, $, $$, exportGlobals, restoreGlobals, useAlias };

src/query.js

@@ -535,6 +535,6 @@ import { isPlainObject, isString, isArray, isDOM, isFunction, findIndex, inArray, isObject, each } from '@semantic-ui/utils';
   focus() {
-    return this[0].focus();
+    return this.length ? this[0].focus() : this;
   }
   blur() {
-    return this[0].blur();
+    return this.length ? this[0].blur() : this;
   }
@@ -541,0 +541,0 @@

test/dom/query.test.js

@@ -1,3 +0,3 @@
-import { describe, beforeEach, expect, it, vi } from 'vitest';
-import { $ } from '@semantic-ui/query';
+import { describe, beforeEach, afterEach, expect, it, vi } from 'vitest';
+import { $, $$, Query, exportGlobals, restoreGlobals, useAlias } from '@semantic-ui/query';
 
@@ -11,3 +11,56 @@ describe('query', () => {
 
+  describe('Global helpers', () => {
+    beforeEach(() => {
+      // Clear any existing global variables before each test
+      delete window.$;
+      delete window.$$;    delete window.Query;
+    });
 
+    describe('exportGlobals', () => {
+      it('should attach $, $$, and Query to the global scope', () => {
+        exportGlobals();
+        expect(window.$).toBe($);
+        expect(window.$$).toBe($$);
+        expect(window.Query).toBe(Query);
+      });
+
+      it('should allow selective global exports', () => {
+        exportGlobals({ dollar: true, doubleDollar: false, query: false });
+        expect(window.$).toBe($);
+        expect(window.$$).toBeUndefined();
+        expect(window.Query).toBeUndefined();
+      });
+    });
+
+    describe('restoreGlobals', () => {
+      it('should restore the original values of $ and $$', () => {
+        const originalDollar = window.$ = () => {};
+        const originalDoubleDollar = window.$$ = () => {};
+
+        exportGlobals();
+        restoreGlobals();
+
+        expect(window.$).toBe(originalDollar);
+        expect(window.$$).toBe(originalDoubleDollar);
+      });
+
+      it('should remove Query from the global scope when specified', () => {
+        exportGlobals();
+        restoreGlobals({ removeQuery: true });
+        expect(window.Query).toBeUndefined();
+      });
+    });
+
+    describe('useAlias', () => {
+      it('should create a new Query instance with the provided arguments', () => {
+        const div = document.createElement('div');
+        document.body.appendChild(div);
+
+        const $alias = useAlias('div');
+        expect($alias).toBeInstanceOf(Query);
+        expect($alias[0]).toBe(div);
+      });
+    });
+  });
+
   describe('selectors', () => {
@@ -14,0 +67,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

77267

increased by8.43%

Number of package files

11

increased by37.5%

Lines of code

1915

increased by5.86%

Number of lines in readme file

182

increased by167.65%

Dependency changes

• + Added@semantic-ui/utils@0.0.26(transitive)

• - Removed@semantic-ui/utils@0.0.25(transitive)

• Updated@semantic-ui/utils@^0.0.26