@appius-fr/apx 2.5.2 → 2.6.0

package/modules/tools/form-packer/README.md

@@ -0,0 +1,315 @@
+# APX Tools: Form Packer
+
+The `form-packer` module provides utilities for converting HTML forms into structured JSON objects. It handles complex form structures including nested objects, arrays, numeric indices, and mixed structures.
+
+---
+
+## Installation
+
+The `form-packer` module is automatically included when you import APX. It provides both a direct API and an APX object method.
+
+```javascript
+import APX from './APX.mjs';
+// APX.tools.packFormToJSON() and APX('form').pack() are now available
+```
+
+---
+
+## Usage
+
+### Method 1: Direct API
+
+```javascript
+const form = document.querySelector('#myForm');
+const data = APX.tools.packFormToJSON(form);
+console.log(data);
+```
+
+### Method 2: APX Object Method (Recommended)
+
+```javascript
+// Using APX selector
+const data = APX('form#myForm').pack();
+const data2 = APX('form.myformclass').pack();
+```
+
+---
+
+## Features
+
+### Nested Objects
+
+Use bracket notation to create nested objects:
+
+```html
+<input name="user[name]" value="John">
+<input name="user[email]" value="john@example.com">
+<input name="user[profile][age]" value="30">
+```
+
+**Result:**
+```json
+{
+  "user": {
+    "name": "John",
+    "email": "john@example.com",
+    "profile": {
+      "age": "30"
+    }
+  }
+}
+```
+
+### Arrays
+
+Use `[]` notation to create arrays:
+
+```html
+<input name="tags[]" value="javascript">
+<input name="tags[]" value="html">
+<input name="tags[]" value="css">
+```
+
+**Result:**
+```json
+{
+  "tags": ["javascript", "html", "css"]
+}
+```
+
+### Numeric Indices
+
+Use numeric indices to create arrays with specific positions:
+
+```html
+<input name="items[0][name]" value="Item 1">
+<input name="items[0][price]" value="10">
+<input name="items[1][name]" value="Item 2">
+<input name="items[1][price]" value="20">
+```
+
+**Result:**
+```json
+{
+  "items": [
+    { "name": "Item 1", "price": "10" },
+    { "name": "Item 2", "price": "20" }
+  ]
+}
+```
+
+### Mixed Structures
+
+The module intelligently handles mixed structures (objects with both numeric and string keys):
+
+```html
+<input name="data[type]" value="product">
+<input name="data[0][name]" value="Item 1">
+<input name="data[1][name]" value="Item 2">
+```
+
+**Result:**
+```json
+{
+  "data": {
+    "type": "product",
+    "0": { "name": "Item 1" },
+    "1": { "name": "Item 2" }
+  }
+}
+```
+
+---
+
+## API
+
+### `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');
+try {
+    const data = APX.tools.packFormToJSON(form);
+    console.log(data);
+} catch (error) {
+    console.error('Error:', error.message);
+}
+```
+
+### `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
+try {
+    const data = APX('form#myForm').pack();
+    console.log(data);
+} catch (error) {
+    console.error('Error:', error.message);
+}
+```
+
+---
+
+## Advanced Features
+
+### Conflict Detection
+
+The module automatically detects incompatible form structures and throws descriptive errors:
+
+```html
+<!-- This will throw an error -->
+<input name="items[0]" value="primitive value">
+<input name="items[0][nested][value]" value="nested value">
+```
+
+**Error:** `Path conflict: "items[0]" is used as a final value, but "items[0][nested][value]" tries to use it as an intermediate path.`
+
+### Two-Phase Processing
+
+The module uses a two-phase processing architecture:
+
+1. **Analysis Phase**: Analyzes all form fields to detect conflicts and structure requirements
+2. **Processing Phase**: Builds the JSON object with intelligent type conversion
+
+This ensures correct handling of complex structures and prevents data loss.
+
+### ES6+ Best Practices
+
+The module is built with modern JavaScript:
+- Arrow functions
+- Destructuring
+- Optional chaining (`?.`)
+- Nullish coalescing (`??`)
+- `for...of` loops
+- `Number.parseInt` / `Number.isNaN`
+- `reduce()` for transformations
+
+---
+
+## Examples
+
+### Complex Form Example
+
+```html
+<form id="userForm">
+    <input name="name" value="John Doe">
+    <input name="email" value="john@example.com">
+    
+    <input name="address[street]" value="123 Main St">
+    <input name="address[city]" value="New York">
+    <input name="address[zip]" value="10001">
+    
+    <input name="tags[]" value="developer">
+    <input name="tags[]" value="designer">
+    
+    <input name="items[0][name]" value="Laptop">
+    <input name="items[0][price]" value="999">
+    <input name="items[1][name]" value="Mouse">
+    <input name="items[1][price]" value="29">
+</form>
+```
+
+```javascript
+const data = APX('form#userForm').pack();
+```
+
+**Result:**
+```json
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "address": {
+    "street": "123 Main St",
+    "city": "New York",
+    "zip": "10001"
+  },
+  "tags": ["developer", "designer"],
+  "items": [
+    { "name": "Laptop", "price": "999" },
+    { "name": "Mouse", "price": "29" }
+  ]
+}
+```
+
+### Multiple Values
+
+If multiple inputs share the same name (without brackets), they are automatically converted to an array:
+
+```html
+<input name="color" value="red">
+<input name="color" value="blue">
+<input name="color" value="green">
+```
+
+**Result:**
+```json
+{
+  "color": ["red", "blue", "green"]
+}
+```
+
+---
+
+## Supported Input Types
+
+The module supports all standard HTML form input types:
+- `text`, `email`, `password`, `number`, `tel`, `url`, `search`
+- `checkbox`, `radio`
+- `select` (single and multiple)
+- `textarea`
+- `hidden`
+- Custom input types
+
+---
+
+## Error Handling
+
+The module provides clear error messages for common issues:
+
+- **Invalid input**: `TypeError: packFormToJSON expects an HTMLFormElement`
+- **No element found**: `Error: No element found` (when using `.pack()`)
+- **Not a form**: `Error: Element is not a form` (when using `.pack()`)
+- **Path conflicts**: Descriptive error messages indicating the conflicting paths
+
+---
+
+## Demo
+
+See the interactive demo at `demo/modules/tools/index.html` for:
+- Live form examples
+- Dynamic form generation
+- JSON output visualization
+- Form-to-JSON validation tool
+
+---
+
+## Notes
+
+- Empty form fields are included in the result (with empty string values)
+- Checkboxes and radio buttons use their `value` attribute (or `"on"` if no value)
+- Multiple select elements create arrays automatically
+- The module handles edge cases like empty keys, mixed structures, and numeric indices
+- All conversions preserve the original form structure as much as possible
+
+---
+
+## License
+
+Author : Thibault SAELEN  
+Copyright Appius SARL.
+

package/modules/tools/form-packer/augment-apx.mjs

@@ -0,0 +1,30 @@
+import { packFormToJSON } from './packToJson.mjs';
+
+/**
+ * Ajoute la méthode pack() aux objets APX pour convertir les formulaires en JSON
+ * @param {Object} apx - L'objet APX à augmenter
+ * @returns {Object} L'objet APX augmenté
+ */
+export default function (apx) {
+    /**
+     * Convertit le premier formulaire sélectionné en objet JSON
+     * @returns {Object} L'objet JSON résultant
+     * @throws {Error} Si aucun formulaire n'est trouvé ou si le premier élément n'est pas un formulaire
+     * @example
+     * const data = APX('form.myformclass').pack();
+     */
+    apx.pack = function () {
+        const firstElement = this.first();
+        if (!firstElement) {
+            throw new Error('No element found');
+        }
+        if (firstElement.tagName !== 'FORM') {
+            throw new Error('Element is not a form');
+        }
+        return packFormToJSON(firstElement);
+    };
+    
+    return apx;
+}
+
+