@appius-fr/apx 2.5.0 → 2.6.0

package/APX.mjs

@@ -1,119 +1,122 @@
-import augmentWithListen from './modules/listen/listen.mjs';
-import augmentWithTristate from './modules/tristate/tristate.mjs';
-import dialog from './modules/dialog/dialog.mjs';
-import toast from './modules/toast/toast.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.toast = toast;
-APX.isAPXObject = function (obj) {
-    return obj && obj._isAPXObject === true;
-}
-APX.is_numeric = (n) => {
-    return !isNaN(n - parseFloat(n));
-}
-
+import augmentWithListen from './modules/listen/listen.mjs';
+import augmentWithTristate from './modules/tristate/tristate.mjs';
+import dialog from './modules/dialog/dialog.mjs';
+import toast from './modules/toast/toast.mjs';
+import { loadCss } from './modules/common.mjs';
+import { augmentWithPack, tools } from './modules/tools/exports.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);
+    augmentWithPack(apx);
+    return apx;
+};
+
+APX.loadCss = loadCss;
+APX.dialog = dialog;
+APX.toast = toast;
+APX.tools = tools;
+APX.isAPXObject = function (obj) {
+    return obj && obj._isAPXObject === true;
+}
+APX.is_numeric = (n) => {
+    return !isNaN(n - parseFloat(n));
+}
+
 export default APX;

package/README.md

@@ -2,36 +2,55 @@
 
 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.
 
+## Core Library
+
+The main APX library is defined in [`APX.mjs`](./APX.mjs), which provides the core DOM wrapping functionality and integrates all modules.
+
+**Quick Start:**
+```javascript
+import APX from './APX.mjs';
+
+// Use APX to select and manipulate elements
+APX('.my-class').each((el) => console.log(el));
+```
+
 ## 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.
+- **Utility Functions**: Includes tools like `loadCss`, `dialog`, and `toast` 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:
+APX is enhanced with several modules, each adding specialized functionality. Each module has its own detailed documentation:
 
 ### `listen`
 
-The `listen` module simplifies event handling for wrapped elements. It provides an intuitive way to attach and manage event listeners.
+The `listen` module simplifies event handling for wrapped elements. It provides an intuitive way to attach and manage event listeners with support for event delegation, multiple callbacks, debouncing, and manual event triggering.
+
+**Documentation:** [`modules/listen/README.md`](./modules/listen/README.md)
 
-Documentation: [`/modules/listen`](./modules/listen/listen.mjs)
+**Quick Example:**
+```javascript
+APX('.button').listen('click').do((event) => {
+    console.log('Button clicked!');
+});
+```
 
 ### `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)
+**Documentation:** [`modules/tristate/tristate.mjs`](./modules/tristate/tristate.mjs)
 
 ### `dialog`
 
-The `dialog` module provides utilities to create and manage modal dialogs.
+The `dialog` module provides utilities to create and manage modal dialogs with lifecycle management, button interactions, and flexible content loading.
 
-Documentation: [`/modules/dialog`](./modules/dialog/dialog.mjs)
+**Documentation:** [`modules/dialog/README.md`](./modules/dialog/README.md)
 
 Since 2.4.0, dialog content can be fetched via GET (default) or POST with optional payload and headers.
 
@@ -55,10 +74,11 @@ myDialog.open();
 
 ### `toast` (since 2.5.0)
 
-Minimal, framework‑agnostic toast notifications with auto‑loaded CSS and a small API. Exposed as `APX.toast`.
+Minimal, framework‑agnostic toast notifications with auto‑loaded CSS and a small API. Exposed as `APX.toast`. Supports advanced positioning (sticky, relative, anchored), flow control, and container management.
 
-Quick start:
+**Documentation:** [`modules/toast/README.md`](./modules/toast/README.md)
 
+**Quick Start:**
 ```javascript
 // One‑liners on the default manager
 APX.toast.success('Saved!');
@@ -70,29 +90,41 @@ APX.toast({ message: 'Processing…', type: 'info', durationMs: 0 });
 // Configure defaults
 APX.toast.configure({ position: 'top-right', maxToasts: 4, dedupe: true });
 
-// Dedupe requires a stable id
-APX.toast.show({ id: 'status', message: 'Working…', type: 'info', durationMs: 0 });
-APX.toast.show({ id: 'status', message: 'Done', type: 'success', durationMs: 1500 });
-
 // Named managers (profiles)
 APX.toast.create('admin', { position: 'bottom-left' });
 APX.toast.use('admin').info('Admin ready');
 ```
 
-Notes:
-- CSS is auto‑imported by the toast module; no `<link>` needed.
-- Overflow policy enforces a strict cap: if `maxToasts` is exceeded, the oldest is removed immediately.
-- Named managers are accessible via `APX.toast.use('<name>')`.
-
-Demo pages (work from file:// via standalone build):
+**Demo pages** (work from file:// via standalone build):
 - `demo/index.html` (landing)
 - `demo/modules/toast/index.html` (basic and advanced examples with code viewer)
 
+### `tools` (since 2.6.0)
+
+The `tools` module provides utility functions for common web development tasks. Currently includes form handling utilities with more tools planned for future releases.
+
+**Documentation:** [`modules/tools/README.md`](./modules/tools/README.md)
+
+**Quick Start:**
+```javascript
+// Convert form to JSON
+const data = APX('form#myForm').pack();
+// or
+const data = APX.tools.packFormToJSON(document.querySelector('#myForm'));
+```
+
+**Sub-modules:**
+- **`form-packer`**: Convert HTML forms to JSON with support for nested objects, arrays, and complex structures.
+  - Documentation: [`modules/tools/form-packer/README.md`](./modules/tools/form-packer/README.md)
+
+**Demo page:**
+- `demo/modules/tools/index.html` (interactive form examples and validation)
+
 ### Utilities
 
 - **`loadCss`**: Dynamically load CSS files into your document.
 
-Documentation: [`/modules/common.mjs`](./modules/common.mjs)
+Documentation: [`modules/common.mjs`](./modules/common.mjs)
 
 ## Usage
 
@@ -144,9 +176,10 @@ const apx7 = APX(() => APX('.example'));
 
 ### Utilities
 
-- **`APX.getApxPathURI()`**: Retrieve the URI path for a given element.
 - **`APX.loadCss()`**: Dynamically load CSS files.
-- **`APX.dialog()`**: Manage and display dialogs.
+- **`APX.dialog()`**: Manage and display dialogs. See [`modules/dialog/README.md`](./modules/dialog/README.md)
+- **`APX.toast`**: Toast notification system. See [`modules/toast/README.md`](./modules/toast/README.md)
+- **`APX.tools`**: Utility functions. See [`modules/tools/README.md`](./modules/tools/README.md)
 - **`APX.isAPXObject(obj)`**: Check if an object is an APX object.
 - **`APX.is_numeric(n)`**: Check if a value is numeric.