@appius-fr/apx 2.5.0 → 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.
+