@appius-fr/apx 2.5.2 → 2.6.0

package/modules/listen/README.md

@@ -0,0 +1,235 @@
+# APX Listen Module
+
+The `listen` module provides a powerful event handling system for APX objects. It enables event delegation, multiple callback chaining, debouncing via timeouts, and manual event triggering.
+
+---
+
+## Installation
+
+The `listen` module is automatically included when you import APX. It augments all APX objects with the `.listen()` and `.trigger()` methods.
+
+```javascript
+import APX from './APX.mjs';
+// .listen() and .trigger() are now available on all APX objects
+```
+
+---
+
+## Usage
+
+### Basic Event Listening
+
+```javascript
+// Listen to a single event type
+APX('.my-button').listen('click').do((event) => {
+    console.log('Button clicked!', event.target);
+});
+
+// Listen to multiple event types
+APX('.my-input').listen(['input', 'change']).do((event) => {
+    console.log('Input changed:', event.target.value);
+});
+```
+
+### Event Delegation
+
+Use event delegation to handle events on dynamically added elements:
+
+```javascript
+// Listen for clicks on any button inside the container (even if added later)
+APX('#container').listen('click', '.button').do((event) => {
+    console.log('Button clicked:', event.target);
+});
+```
+
+### Multiple Callbacks (Chaining)
+
+Chain multiple callbacks that execute sequentially:
+
+```javascript
+APX('.my-button').listen('click').do((event) => {
+    console.log('First callback');
+    return fetch('/api/data'); // Can return promises
+}).do((event) => {
+    console.log('Second callback (runs after first completes)');
+}).do((event) => {
+    console.log('Third callback');
+});
+```
+
+### Debouncing with Timeout
+
+Add a delay before executing callbacks:
+
+```javascript
+// Wait 300ms after the last event before executing callbacks
+APX('.search-input').listen('input', { timeout: 300 }).do((event) => {
+    console.log('Searching for:', event.target.value);
+    // This will only fire 300ms after the user stops typing
+});
+```
+
+### Manual Event Triggering
+
+Manually trigger events and their registered callbacks:
+
+```javascript
+// Trigger a click event
+APX('.my-button').trigger('click');
+
+// Or trigger with an actual Event object
+const customEvent = new CustomEvent('myevent', { detail: { data: 'value' } });
+APX('.my-element').trigger(customEvent);
+```
+
+---
+
+## API
+
+### `.listen(eventTypes, selector?, options?)`
+
+Adds event listeners to the APX-wrapped elements.
+
+**Parameters:**
+- `eventTypes` (string | string[]): The event type(s) to listen for (e.g., `'click'`, `['input', 'change']`)
+- `selector` (string, optional): CSS selector for event delegation
+- `options` (object, optional): Configuration options
+  - `timeout` (number): Delay in milliseconds before executing callbacks (default: `0`)
+
+**Returns:** An object with a `.do()` method for chaining callbacks.
+
+**Example:**
+```javascript
+APX('.element')
+    .listen('click', '.button', { timeout: 100 })
+    .do((event) => { /* callback 1 */ })
+    .do((event) => { /* callback 2 */ });
+```
+
+### `.do(callback)`
+
+Adds a callback function to the event listener chain. Callbacks execute sequentially, and each callback can return a Promise to delay the next callback.
+
+**Parameters:**
+- `callback` (Function): The callback function that receives the event object
+
+**Returns:** The same object (for chaining)
+
+**Example:**
+```javascript
+APX('.button').listen('click').do((event) => {
+    // Callback is bound to the matched element
+    console.log(this); // The matched element
+    return fetch('/api').then(res => res.json());
+}).do((event) => {
+    // This runs after the fetch completes
+    console.log('Fetch completed');
+});
+```
+
+### `.trigger(event)`
+
+Manually triggers an event on all wrapped elements and executes registered callbacks.
+
+**Parameters:**
+- `event` (string | Event): Event type string or an Event object
+
+**Example:**
+```javascript
+// Trigger with string
+APX('.button').trigger('click');
+
+// Trigger with Event object
+const event = new CustomEvent('custom', { detail: { foo: 'bar' } });
+APX('.element').trigger(event);
+```
+
+---
+
+## Examples
+
+### Form Validation with Debouncing
+
+```javascript
+APX('#email-input').listen('input', { timeout: 500 }).do((event) => {
+    const email = event.target.value;
+    if (email.includes('@')) {
+        validateEmail(email);
+    }
+});
+```
+
+### Dynamic Content with Event Delegation
+
+```javascript
+// Handle clicks on buttons added dynamically
+APX('#dynamic-container').listen('click', '.action-button').do((event) => {
+    const button = event.target;
+    const action = button.dataset.action;
+    handleAction(action);
+});
+```
+
+### Sequential Async Operations
+
+```javascript
+APX('#submit-button').listen('click').do(async (event) => {
+    // First: Validate form
+    const isValid = await validateForm();
+    if (!isValid) throw new Error('Validation failed');
+}).do(async (event) => {
+    // Second: Submit form (only if validation passed)
+    const result = await submitForm();
+    return result;
+}).do((event) => {
+    // Third: Show success message
+    showSuccessMessage();
+});
+```
+
+### Multiple Event Types
+
+```javascript
+APX('.input-field').listen(['focus', 'blur', 'input']).do((event) => {
+    switch (event.type) {
+        case 'focus':
+            highlightField(event.target);
+            break;
+        case 'blur':
+            validateField(event.target);
+            break;
+        case 'input':
+            updatePreview(event.target.value);
+            break;
+    }
+});
+```
+
+---
+
+## Features
+
+- ✅ **Event Delegation**: Handle events on dynamically added elements
+- ✅ **Multiple Callbacks**: Chain multiple callbacks that execute sequentially
+- ✅ **Promise Support**: Callbacks can return Promises for async operations
+- ✅ **Debouncing**: Add timeouts to delay callback execution
+- ✅ **Multiple Event Types**: Listen to multiple event types at once
+- ✅ **Manual Triggering**: Programmatically trigger events and callbacks
+- ✅ **Context Binding**: Callbacks are bound to the matched element (`this`)
+
+---
+
+## Notes
+
+- Callbacks execute sequentially; if a callback returns a Promise, the next callback waits for it to resolve
+- Event delegation uses `closest()` to find the matching element, so it works with nested elements
+- Timeouts are cleared and reset on each event, making it perfect for debouncing
+- The `trigger()` method respects event delegation selectors when executing callbacks
+
+---
+
+## License
+
+Author : Thibault SAELEN  
+Copyright Appius SARL.
+

package/modules/tools/README.md

@@ -0,0 +1,165 @@
+# APX Tools Module
+
+The `tools` module provides utility functions for common web development tasks. Currently, it includes form handling utilities, with more tools planned for future releases.
+
+---
+
+## Installation
+
+The `tools` module is automatically included when you import APX. All tools are accessible via `APX.tools`.
+
+```javascript
+import APX from './APX.mjs';
+// APX.tools is now available
+```
+
+---
+
+## Available Tools
+
+### Form Packer
+
+The `form-packer` sub-module provides utilities for converting HTML forms to JSON objects.
+
+**Quick Start:**
+```javascript
+// Direct API
+const form = document.querySelector('#myForm');
+const data = APX.tools.packFormToJSON(form);
+
+// APX method (recommended)
+const data = APX('form#myForm').pack();
+```
+
+**Features:**
+- Nested objects via bracket notation (`user[name]`)
+- Arrays via `[]` notation (`tags[]`)
+- Numeric indices (`items[0][name]`)
+- Mixed structures (objects with both numeric and string keys)
+- Automatic conflict detection
+
+**Documentation:** See [`form-packer/README.md`](./form-packer/README.md) for complete documentation.
+
+---
+
+## API Reference
+
+### `APX.tools.packFormToJSON(form)`
+
+Converts an HTML form element into a JSON object.
+
+**Parameters:**
+- `form` (HTMLFormElement): The form element to convert
+
+**Returns:** (Object) The JSON object representation of the form data
+
+**Throws:** (TypeError) If `form` is not an `HTMLFormElement`
+
+**Example:**
+```javascript
+const form = document.querySelector('#myForm');
+const data = APX.tools.packFormToJSON(form);
+console.log(data);
+```
+
+### `APX('form').pack()`
+
+Converts the first selected form element into a JSON object. This is a chainable method on APX objects.
+
+**Returns:** (Object) The JSON object representation of the form data
+
+**Throws:** (Error) If no element is found or the first element is not a form
+
+**Example:**
+```javascript
+const data = APX('form#myForm').pack();
+console.log(data);
+```
+
+---
+
+## Examples
+
+### Basic Form Conversion
+
+```html
+<form id="contactForm">
+    <input name="name" value="John Doe">
+    <input name="email" value="john@example.com">
+    <input name="message" value="Hello!">
+</form>
+```
+
+```javascript
+const data = APX('form#contactForm').pack();
+// Result: { name: "John Doe", email: "john@example.com", message: "Hello!" }
+```
+
+### Complex Form with Nested Structures
+
+```html
+<form id="orderForm">
+    <input name="customer[name]" value="John">
+    <input name="customer[email]" value="john@example.com">
+    <input name="items[0][name]" value="Product 1">
+    <input name="items[0][quantity]" value="2">
+    <input name="items[1][name]" value="Product 2">
+    <input name="items[1][quantity]" value="1">
+    <input name="tags[]" value="urgent">
+    <input name="tags[]" value="express">
+</form>
+```
+
+```javascript
+const data = APX('form#orderForm').pack();
+// Result: {
+//   customer: { name: "John", email: "john@example.com" },
+//   items: [
+//     { name: "Product 1", quantity: "2" },
+//     { name: "Product 2", quantity: "1" }
+//   ],
+//   tags: ["urgent", "express"]
+// }
+```
+
+---
+
+## Module Structure
+
+```
+modules/tools/
+├── form-packer/
+│   ├── packToJson.mjs      # Core conversion function
+│   ├── augment-apx.mjs    # APX object augmentation (.pack() method)
+│   └── README.md           # Detailed documentation
+├── exports.mjs             # Centralized exports
+└── README.md               # This file
+```
+
+---
+
+## Future Tools
+
+More utility functions are planned for future releases:
+- Form validation utilities
+- Data transformation helpers
+- DOM manipulation utilities
+- And more...
+
+---
+
+## Demo
+
+See the interactive demo at `demo/modules/tools/index.html` for:
+- Live form examples with various structures
+- Dynamic form generation
+- JSON output visualization
+- Form-to-JSON validation tool
+
+---
+
+## License
+
+Author : Thibault SAELEN  
+Copyright Appius SARL.
+

package/modules/tools/exports.mjs

@@ -0,0 +1,16 @@
+// Import des fonctions et modules des sous-modules
+import augmentWithPack from './form-packer/augment-apx.mjs';
+import { packFormToJSON } from './form-packer/packToJson.mjs';
+
+// Export de la fonction d'augmentation
+export { augmentWithPack };
+
+// Export des fonctions utilitaires
+export { packFormToJSON };
+
+// Export d'un objet tools pour faciliter l'utilisation
+export const tools = {
+    packFormToJSON: packFormToJSON
+};
+
+