dphelper 3.5.5 → 3.7.2

package/docs/markdown/element.md

@@ -0,0 +1,53 @@
+# element
+
+Element manipulation utilities for scaling and responsive design.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `fitScale` | Scale element based on window size | `dphelper.element.fitScale('#container', 1, true)` |
+| `scaleBasedOnWindow` | Scale element to fit window | `dphelper.element.scaleBasedOnWindow('#chart', 1, false)` |
+
+## Description
+
+Element scaling and responsive utilities:
+- **Auto Scaling** - Scale elements with window resize
+- **Fit to Window** - Scale to fit or fill viewport
+- **Responsive** - Maintain aspect ratio
+
+## Usage Examples
+
+### Scale Element
+
+```javascript
+// Basic scaling
+dphelper.element.fitScale('#myElement', 1);
+
+// Scale to fit window
+dphelper.element.fitScale('#chart', 1, true);
+
+// Custom scale
+dphelper.element.fitScale('#preview', 0.5);
+```
+
+### Responsive Charts
+
+```javascript
+// Make chart responsive
+dphelper.element.fitScale('#chart-container', 1, true);
+
+// Element scales automatically on window resize
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20230527
+- **Last Modified:** 20230527
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/event.md

@@ -0,0 +1,85 @@
+# event
+
+Event handling utilities for DOM events, drag, and keyboard.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `list` | Show attached event listeners | `dphelper.event.list(element)` |
+| `multi` | Attach multiple events | `dphelper.event.multi(element, 'click hover', handler)` |
+| `copy` | Click copy element text | to `dphelper.event.copy('#element')` |
+| `onDrag` | Handle element dragging | `dphelper.event.onDrag('.popup')` |
+| `keys` | Get keyboard event properties | `dphelper.event.keys(e)` |
+
+## Description
+
+Complete event utilities:
+- **Multi Events** - Attach multiple events at once
+- **Drag** - Drag and drop handling
+- **Copy** - Click to copy to clipboard
+- **Keyboard** - Key event properties
+
+## Usage Examples
+
+### Multiple Event Listeners
+
+```javascript
+// Attach multiple events
+dphelper.event.multi(
+  document.querySelector('#button'),
+  'click hover focus',
+  (e) => console.log(e.type)
+);
+```
+
+### Copy to Clipboard
+
+```javascript
+// Click element to copy its text
+dphelper.event.copy('#text-to-copy');
+
+// User clicks, text is copied to clipboard
+```
+
+### Keyboard Events
+
+```javascript
+// Get keyboard event properties
+document.addEventListener('keydown', (e) => {
+  const keys = dphelper.event.keys(e);
+
+  console.log(keys.key);    // 'a', 'Enter', 'Escape'
+  console.log(keys.ctrl);  // true/false
+  console.log(keys.alt);   // true/false
+  console.log(keys.shift); // true/false
+
+  // Check for shortcuts
+  if (keys.ctrl && keys.key === 's') {
+    e.preventDefault();
+    save();
+  }
+});
+```
+
+### Drag and Drop
+
+```javascript
+// Enable dragging
+dphelper.event.onDrag('.draggable-popup');
+
+// Element can now be dragged
+// Position saved to localStorage
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/fetch.md

@@ -0,0 +1,122 @@
+# fetch
+
+HTTP fetch utilities with automatic retry and exponential backoff.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `get` | Perform GET request with retry | `dphelper.fetch.get(url, options)` |
+| `post` | Perform POST request with JSON | `dphelper.fetch.post(url, body, options)` |
+
+## Description
+
+HTTP request utilities:
+- **GET** - Fetch data with automatic retries
+- **POST** - Send JSON data with automatic JSON headers
+- **Retry** - Exponential backoff on failure
+- **Error Handling** - Automatic retry on network errors
+
+## Usage Examples
+
+### GET Request
+
+```javascript
+// Simple GET request
+const response = await dphelper.fetch.get('https://api.example.com/data');
+const data = await response.json();
+
+// GET with options
+const users = await dphelper.fetch.get('/api/users', {
+  headers: { 'Authorization': 'Bearer token' }
+});
+```
+
+### POST Request
+
+```javascript
+// POST JSON data
+const response = await dphelper.fetch.post('/api/users', {
+  name: 'John',
+  email: 'john@example.com'
+});
+
+// POST with custom headers
+const response = await dphelper.fetch.post('/api/upload', formData, {
+  headers: { 'X-Custom-Header': 'value' }
+});
+```
+
+### Error Handling with Retry
+
+```javascript
+// Automatic retry on failure
+async function fetchWithRetry(url, options = {}) {
+  try {
+    const response = await dphelper.fetch.get(url, options);
+    return await response.json();
+  } catch (error) {
+    console.error('Fetch failed:', error);
+    return null;
+  }
+}
+```
+
+### API Integration
+
+```javascript
+class ApiClient {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+
+  async get(endpoint) {
+    const response = await dphelper.fetch.get(`${this.baseUrl}${endpoint}`);
+    return response.json();
+  }
+
+  async post(endpoint, data) {
+    const response = await dphelper.fetch.post(`${this.baseUrl}${endpoint}`, data);
+    return response.json();
+  }
+}
+
+const api = new ApiClient('https://api.example.com');
+const data = await api.get('/items');
+```
+
+## Security Notes
+
+> [!IMPORTANT]
+> Network functions (`fetch`, `SSE`, `socket`) require **input validation** by the caller.
+
+This library provides networking primitives **by design**:
+- HTTP/HTTPS requests
+- Server-Sent Events
+- WebSocket connections
+
+As a devtools library, these features are essential for modern web development. **Callers are responsible for validating URLs and data** before passing them to these functions.
+
+### Best Practices
+
+```javascript
+// ALWAYS validate and sanitize user input
+const sanitizedUrl = dphelper.sanitize.url(userInput);
+const validatedData = dphelper.sanitize.html(userData);
+
+await dphelper.fetch.get(sanitizedUrl);
+```
+
+---
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20260221
+- **Last Modified:** 20260329
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/form.md

@@ -0,0 +1,302 @@
+# form
+
+Comprehensive form utilities for validation, serialization, and input management.
+
+## Functions
+
+### Serialization
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `serialize` | Converts form data to JavaScript object | `dphelper.form.serialize('#myForm')` |
+
+### Validation
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `confirmType` | Validates value against a specific type | `dphelper.form.confirmType('email', 'test@example.com')` |
+| `required` | Checks if a value is present | `dphelper.form.required(value)` |
+| `minLength` | Validates minimum string length | `dphelper.form.minLength('hello', 3)` |
+| `maxLength` | Validates maximum string length | `dphelper.form.maxLength('hello', 10)` |
+| `maxPhoneNumber` | Validates phone number length | `dphelper.form.maxPhoneNumber('1234567890', 10)` |
+| `isNumeric` | Checks if value is numeric | `dphelper.form.isNumeric(42)` |
+| `isEmail` | Validates email format | `dphelper.form.isEmail('test@example.com')` |
+
+### Input Control
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `pattern` | Validates input against type-specific pattern | `dphelper.form.pattern(event)` |
+| `noSpecialChars` | Blocks special characters in input | `dphelper.form.noSpecialChars(event)` |
+
+### Utilities
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `table` | Generates an editable data table | `dphelper.form.table([7, 24], 'tableId', element)` |
+| `sanitize` | Removes dangerous characters from input | `dphelper.form.sanitize(userInput)` |
+
+## Description
+
+Complete form management solution:
+- **Data Serialization** - Form to object conversion with type handling
+- **Validation** - Required fields, length, email, numeric, patterns
+- **Input Filtering** - Block special characters, pattern enforcement
+- **Table Generation** - Create editable data grids
+- **Security** - Input sanitization for XSS prevention
+
+## Usage Examples
+
+### Form Serialization
+
+```javascript
+// HTML form
+// <form id="myForm">
+//   <input name="username" value="john">
+//   <input name="age" value="30">
+//   <input name="active" value="true">
+// </form>
+
+const data = dphelper.form.serialize('#myForm');
+console.log(data);
+// { username: "john", age: 30, active: true }
+
+// Handles nested names
+// <input name="user[name]" value="John">
+// <input name="user[email]" value="john@example.com">
+
+const userData = dphelper.form.serialize('#myForm');
+console.log(userData);
+// { user: { name: "John", email: "john@example.com" } }
+
+// Array handling
+// <input name="tags[]" value="javascript">
+// <input name="tags[]" value="typescript">
+
+const tagsData = dphelper.form.serialize('#myForm');
+// { tags: ["javascript", "typescript"] }
+```
+
+### Form Validation
+
+```javascript
+// Required field
+console.log(dphelper.form.required("hello"));      // undefined (valid)
+console.log(dphelper.form.required(""));            // "Required"
+console.log(dphelper.form.required(null));          // "Required"
+console.log(dphelper.form.required(undefined));     // "Required"
+
+// Minimum length
+console.log(dphelper.form.minLength("hello", 3));   // undefined (valid)
+console.log(dphelper.form.minLength("hi", 3));     // "Must Enter a Value"
+
+// Maximum length
+console.log(dphelper.form.maxLength("hello", 10)); // undefined (valid)
+console.log(dphelper.form.maxLength("hello world", 5)); // "Exceeds Max Length"
+
+// Phone number validation
+console.log(dphelper.form.maxPhoneNumber("1234567890", 10)); // undefined
+console.log(dphelper.form.maxPhoneNumber("12345678901", 10)); // "Exceeds Max Length"
+
+// Type confirmation
+console.log(dphelper.form.confirmType("number", "123"));  // true
+console.log(dphelper.form.confirmType("number", "abc"));  // false
+console.log(dphelper.form.confirmType("email", "test@example.com")); // true
+```
+
+### Email Validation
+
+```javascript
+// Basic email validation
+console.log(dphelper.form.isEmail("test@example.com"));      // true
+console.log(dphelper.form.isEmail("john.doe@company.co.uk")); // true
+console.log(dphelper.form.isEmail("invalid"));                // false
+console.log(dphelper.form.isEmail("@example.com"));          // false
+console.log(dphelper.form.isEmail("test@"));                // false
+
+// Use in form validation
+function validateForm(formData) {
+  const errors = {};
+
+  if (dphelper.form.required(formData.email)) {
+    errors.email = "Email is required";
+  } else if (!dphelper.form.isEmail(formData.email)) {
+    errors.email = "Invalid email format";
+  }
+
+  if (dphelper.form.minLength(formData.password, 8)) {
+    errors.password = "Password must be at least 8 characters";
+  }
+
+  return errors;
+}
+```
+
+### Numeric Validation
+
+```javascript
+// Check if value is numeric
+console.log(dphelper.form.isNumeric(123));       // true
+console.log(dphelper.form.isNumeric("123"));     // true
+console.log(dphelper.form.isNumeric("12.34"));    // true
+console.log(dphelper.form.isNumeric("abc"));     // false
+console.log(dphelper.form.isNumeric(NaN));       // false
+```
+
+### Input Event Handlers
+
+```javascript
+// Pattern validation on input change
+// <input type="text" onchange="dphelper.form.pattern(event)">
+document.querySelector('input[type="text"]').addEventListener('change', dphelper.form.pattern);
+
+// Block special characters
+// <input onkeyup="dphelper.form.noSpecialChars(event)">
+document.querySelector('input').addEventListener('keyup', dphelper.form.noSpecialChars);
+
+// Example: Username input
+const usernameInput = document.getElementById('username');
+usernameInput.addEventListener('input', (e) => {
+  // Only allow letters, numbers, and underscores
+  const original = e.target.value;
+  const cleaned = original.replace(/[^a-zA-Z0-9_]/g, '');
+  if (cleaned !== original) {
+    e.target.value = cleaned;
+  }
+});
+```
+
+### Table Generation
+
+```javascript
+// Generate a data entry table
+const container = document.getElementById('tableContainer');
+
+// Default 7 columns x 24 rows
+dphelper.form.table([7, 24], 'dataTable', container);
+
+// Custom size: 5 columns x 10 rows
+dphelper.form.table([5, 10], 'myTable', container);
+
+// Creates an editable table with:
+// - Column headers (1-5)
+// - Row numbers (1-10)
+// - Number inputs in each cell
+// - Random values (0-99)
+// - Tab navigation (column + row based)
+```
+
+### Input Sanitization
+
+```javascript
+// Remove dangerous characters
+console.log(dphelper.form.sanitize("<script>alert('xss')</script>"));
+// "scriptalertxssscript"
+
+// Remove special characters but keep spaces
+console.log(dphelper.form.sanitize("Hello World! @#$%"));
+// "Hello World "
+
+// Use for form input
+function handleFormSubmit(e) {
+  e.preventDefault();
+
+  const formData = {};
+  const inputs = e.target.querySelectorAll('input');
+
+  inputs.forEach(input => {
+    formData[input.name] = dphelper.form.sanitize(input.value);
+  });
+
+  // Now safe to process
+  console.log(formData);
+}
+```
+
+## Advanced Usage
+
+### Complete Form Validation
+
+```javascript
+class FormValidator {
+  constructor() {
+    this.errors = {};
+  }
+
+  validate(field, value, rules) {
+    this.errors[field] = undefined;
+
+    if (rules.required) {
+      const error = dphelper.form.required(value);
+      if (error) {
+        this.errors[field] = error;
+        return false;
+      }
+    }
+
+    if (rules.minLength) {
+      const error = dphelper.form.minLength(value, rules.minLength);
+      if (error) {
+        this.errors[field] = error;
+        return false;
+      }
+    }
+
+    if (rules.maxLength) {
+      const error = dphelper.form.maxLength(value, rules.maxLength);
+      if (error) {
+        this.errors[field] = error;
+        return false;
+      }
+    }
+
+    if (rules.email && !dphelper.form.isEmail(value)) {
+      this.errors[field] = "Invalid email address";
+      return false;
+    }
+
+    if (rules.numeric && !dphelper.form.isNumeric(value)) {
+      this.errors[field] = "Must be a number";
+      return false;
+    }
+
+    return true;
+  }
+
+  getErrors() {
+    return this.errors;
+  }
+
+  hasErrors() {
+    return Object.values(this.errors).some(e => e !== undefined);
+  }
+}
+
+// Usage
+const validator = new FormValidator();
+
+validator.validate('username', 'john', {
+  required: true,
+  minLength: 3,
+  maxLength: 20
+});
+
+validator.validate('email', 'john@example.com', {
+  required: true,
+  email: true
+});
+
+console.log(validator.getErrors());
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/format.md

@@ -0,0 +1,122 @@
+# format
+
+Utilities for data formatting like currency and phone numbers.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `currency` | Format a number as currency | `dphelper.format.currency(value, locale, currency)` |
+| `phoneNumber` | Format a string as a phone number | `dphelper.format.phoneNumber(value, countryCode)` |
+
+## Description
+
+Data formatting utilities:
+- **Currency** - Format numbers with locale-specific currency symbols using Intl API
+- **Phone Numbers** - Format phone numbers by country code
+- **Localization** - Supports multiple locales (en-US, de-DE, ja-JPY, etc.)
+
+## Usage Examples
+
+### Currency Formatting
+
+```javascript
+// Basic USD currency (default)
+const price = dphelper.format.currency(1234.56);
+// Output: "$1,234.56"
+
+// Euro currency with German locale
+const euro = dphelper.format.currency(1234.56, 'de-DE', 'EUR');
+// Output: "1.234,56 €"
+
+// Japanese Yen
+const yen = dphelper.format.currency(5000, 'ja-JPY', 'JPY');
+// Output: "¥5,000"
+
+// British Pound
+const pound = dphelper.format.currency(99.99, 'en-GB', 'GBP');
+// Output: "£99.99"
+
+// Swiss Franc
+const franc = dphelper.format.currency(1500, 'de-CH', 'CHF');
+// Output: "CHF 1'500.00"
+```
+
+### Phone Number Formatting
+
+```javascript
+// US phone number
+const usPhone = dphelper.format.phoneNumber('5551234567', 'US');
+// Output: "(555) 123-4567"
+
+// Invalid format returns original
+const invalid = dphelper.format.phoneNumber('123', 'US');
+// Output: "123"
+```
+
+### E-commerce Price Display
+
+```javascript
+function formatProductPrice(product, locale = 'en-US', currency = 'USD') {
+  return dphelper.format.currency(product.price, locale, currency);
+}
+
+const products = [
+  { name: 'Laptop', price: 1299.99 },
+  { name: 'Phone', price: 899.00 },
+  { name: 'Tablet', price: 549.50 },
+  { name: 'Headphones', price: 199.99 }
+];
+
+products.forEach(p => {
+  console.log(`${p.name}: ${formatProductPrice(p)}`);
+});
+// Laptop: $1,299.99
+// Phone: $899.00
+// Tablet: $549.50
+// Headphones: $199.99
+```
+
+### International Checkout
+
+```javascript
+const locales = {
+  US: { locale: 'en-US', currency: 'USD', symbol: '$' },
+  DE: { locale: 'de-DE', currency: 'EUR', symbol: '€' },
+  JP: { locale: 'ja-JPY', currency: 'JPY', symbol: '¥' },
+  GB: { locale: 'en-GB', currency: 'GBP', symbol: '£' },
+  IT: { locale: 'it-IT', currency: 'EUR', symbol: '€' }
+};
+
+function formatByRegion(region, amount) {
+  const config = locales[region];
+  if (!config) return amount;
+  return dphelper.format.currency(amount, config.locale, config.currency);
+}
+
+// Format total cart for different regions
+const cart = [
+  { item: 'Product A', price: 100 },
+  { item: 'Product B', price: 50 },
+  { item: 'Shipping', price: 10 }
+];
+
+const total = cart.reduce((sum, item) => sum + item.price, 0);
+
+console.log('US Total:', formatByRegion('US', total));   // $160.00
+console.log('DE Total:', formatByRegion('DE', total));   // 160,00 €
+console.log('JP Total:', formatByRegion('JP', total));   // ¥160
+console.log('GB Total:', formatByRegion('GB', total));   // £160.00
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*