@appius-fr/apx 2.2.2

package/APX.mjs

@@ -0,0 +1,117 @@
+import augmentWithListen from './modules/listen/listen.mjs';
+import augmentWithTristate from './modules/tristate/tristate.mjs';
+import dialog from './modules/dialog/dialog.mjs';
+import { loadCss } from './modules/common.mjs';
+
+/**
+ * Creates an APX object that wraps one or more HTML elements.
+ * @param {string|HTMLElement|NodeList|HTMLCollection|Array<HTMLElement>|jQuery|Function} input - The input to create the APX object from.
+ * @returns {Object} The APX object.
+ * @throws {Error} If the input type is invalid.
+ * @example
+ * // XPath
+ * const apx1 = APX('//div[@class="example"]');
+ *
+ * // CSS selector
+ * const apx2 = APX('.example');
+ *
+ * // Single element
+ * const element = document.querySelector('.example');
+ * const apx3 = APX(element);
+ *
+ * // NodeList or HTMLCollection
+ * const nodeList = document.querySelectorAll('.example');
+ * const apx4 = APX(nodeList);
+ *
+ * // Array of elements
+ * const elements = [document.querySelector('.example1'), document.querySelector('.example2')];
+ * const apx5 = APX(elements);
+ *
+ * // jQuery object
+ * const $example = $('.example');
+ * const apx6 = APX($example);
+ *
+ * // Function returning an APX object
+ * const apx7 = APX(() => APX('.example'));
+ */
+const APX = function (input, context = document) {
+    let elements;
+
+    // Validate context
+    if (typeof context === 'string') {
+        context = document.querySelector(context);
+    }
+    else if (APX.isAPXObject(context)) {
+        context = context.first();
+    } else if (!(context instanceof HTMLElement || context instanceof Document)) {
+        throw new Error('Invalid context for APX');
+    }
+
+    if (typeof input === 'string' && input.startsWith('//')) {
+        // XPath with context
+        elements = document.evaluate(input, context, null, XPathResult.ANY_TYPE, null);
+        let nodes = [];
+        let node = elements.iterateNext();
+        while (node) {
+            nodes.push(node);
+            node = elements.iterateNext();
+        }
+        elements = nodes;
+    } else if (typeof input === 'string') {
+        // CSS selector with context
+        elements = context.querySelectorAll(input);
+    } else if (input instanceof HTMLElement) {
+        // Single element within context
+        elements = context.contains(input) ? [input] : [];
+    } else if (input instanceof NodeList || input instanceof HTMLCollection) {
+        // NodeList or HTMLCollection within context
+        elements = Array.from(input).filter(el => context.contains(el));
+    } else if (Array.isArray(input) && input.every(el => el instanceof HTMLElement)) {
+        // Array of elements within context
+        elements = input.filter(el => context.contains(el));
+    } else if (typeof jQuery != 'undefined' && input instanceof jQuery) {
+        // jQuery object within context
+        elements = Array.from(input.get()).filter(el => context.contains(el));
+    } else if (typeof input === 'function') {
+        // Function returning an APX object with context
+        elements = APX(input(), context);
+    } else {
+        throw new Error('Invalid input type for APX');
+    }
+
+    var apx = {
+        elements: elements,
+        _isAPXObject: true
+    };
+    apx.length = elements.length;
+    apx.each = function (callback) {
+        if (this.elements instanceof Array) this.elements.forEach(callback);
+        if (this.elements instanceof NodeList) Array.from(this.elements).forEach(callback);
+        return this;
+    };
+    apx.get = function (index) {
+        return this.elements[index];
+    };
+    apx.all = function () {
+        if (this.elements instanceof Array) return this.elements;
+        if (this.elements instanceof NodeList) return Array.from(this.elements);
+        return this;
+    };
+    apx.first = function () {
+        return this.get(0);
+    };
+    augmentWithListen(apx);
+    augmentWithTristate(apx);
+    return apx;
+};
+
+APX.loadCss = loadCss;
+APX.dialog = dialog;
+APX.isAPXObject = function (obj) {
+    return obj && obj._isAPXObject === true;
+}
+APX.is_numeric = (n) => {
+    return !isNaN(n - parseFloat(n));
+}
+
+export default APX;

package/README.md

@@ -0,0 +1,115 @@
+# APX DOM Wrapper
+
+APX is a versatile DOM wrapper designed to simplify interactions with HTML elements. It provides a unified interface for working with various input types, including XPath, CSS selectors, individual HTMLElements, NodeLists, HTMLCollections, arrays of elements, jQuery objects, and even functions that return APX objects.
+
+## Features
+
+- **XPath Support**: Easily select elements using XPath queries.
+- **CSS Selector Support**: Utilize CSS selectors for element selection.
+- **Enhanced Interactions**: Augmented with modules like `listen` for event handling and `tristate` for managing tristate logic.
+- **Utility Functions**: Includes tools like `loadCss`, and `dialog` for extended functionality.
+- **jQuery Compatibility**: Seamlessly works with jQuery objects.
+- **Function Input**: Accepts functions returning an APX object as input.
+
+## Modules
+
+APX is enhanced with several modules, each adding specialized functionality:
+
+### `listen`
+
+The `listen` module simplifies event handling for wrapped elements. It provides an intuitive way to attach and manage event listeners.
+
+Documentation: [`/modules/listen`](./modules/listen/listen.mjs)
+
+### `tristate`
+
+The `tristate` module allows you to manage tristate logic (e.g., on/off/indeterminate) for HTML elements efficiently.
+
+Documentation: [`/modules/tristate`](./modules/tristate/tristate.mjs)
+
+### `dialog`
+
+The `dialog` module provides utilities to create and manage modal dialogs.
+
+Documentation: [`/modules/dialog`](./modules/dialog/dialog.mjs)
+
+### Utilities
+
+- **`loadCss`**: Dynamically load CSS files into your document.
+
+Documentation: [`/modules/common.mjs`](./modules/common.mjs)
+
+## Usage
+
+Here are some examples of how you can use APX:
+
+```javascript
+// Using XPath
+const apx1 = APX('//div[@class="example"]');
+
+// Using CSS selector
+const apx2 = APX('.example');
+
+// Using a single element
+const element = document.querySelector('.example');
+const apx3 = APX(element);
+
+// Using NodeList or HTMLCollection
+const nodeList = document.querySelectorAll('.example');
+const apx4 = APX(nodeList);
+
+// Using an array of elements
+const elements = [document.querySelector('.example1'), document.querySelector('.example2')];
+const apx5 = APX(elements);
+
+// Using a jQuery object
+const $example = $('.example');
+const apx6 = APX($example);
+
+// Using a function returning an APX object
+const apx7 = APX(() => APX('.example'));
+```
+
+## API
+
+### Core Functionality
+
+- **`APX(input, context = document)`**: The main function that creates an APX object. Accepts a wide variety of input types:
+  - `string`: XPath or CSS selectors.
+  - `HTMLElement`: Single DOM element.
+  - `NodeList`/`HTMLCollection`: A collection of DOM elements.
+  - `Array<HTMLElement>`: An array of DOM elements.
+  - `jQuery`: A jQuery object.
+  - `Function`: A function that returns an APX object.
+- **Methods on APX objects**:
+  - `.each(callback)`: Iterates over elements.
+  - `.get(index)`: Retrieves an element by index.
+  - `.all()`: Returns all wrapped elements.
+  - `.first()`: Returns the first wrapped element.
+
+### Utilities
+
+- **`APX.getApxPathURI()`**: Retrieve the URI path for a given element.
+- **`APX.loadCss()`**: Dynamically load CSS files.
+- **`APX.dialog()`**: Manage and display dialogs.
+- **`APX.isAPXObject(obj)`**: Check if an object is an APX object.
+- **`APX.is_numeric(n)`**: Check if a value is numeric.
+
+## Installation
+
+To include APX in your project:
+
+1. Clone the repository or download the package.
+2. Import APX and its modules into your project:
+   ```javascript
+   import APX from './path-to-apx/apx.mjs';
+   ```
+
+## Contributing
+
+We welcome contributions! Please refer to the contribution guidelines in the repository.
+
+## License
+
+Author : Thibault SAELEN
+Copyright Appius SARL.