dphelper 3.7.1 → 3.7.2

package/docs/markdown/triggers.md

@@ -0,0 +1,133 @@
+# triggers
+
+Custom event trigger system for application-wide event handling.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `add` | Add event listener | `dphelper.triggers.add(event, callback)` |
+| `on` | Listen for event (alias for add) | `dphelper.triggers.on(event, callback)` |
+| `emit` | Trigger an event with data | `dphelper.triggers.emit(event, data)` |
+| `remove` | Remove all listeners for event | `dphelper.triggers.remove(event)` |
+| `off` | Remove specific callback | `dphelper.triggers.off(event, callback)` |
+| `clear` | Clear all triggers | `dphelper.triggers.clear()` |
+| `list` | List all registered events | `dphelper.triggers.list()` |
+
+## Description
+
+Custom event system:
+- **Event Listeners** - Add/remove custom event listeners
+- **Event Emission** - Emit events with data payloads
+- **Namespacing** - Organize events by name
+- **Error Handling** - Safe callback execution
+
+## Usage Examples
+
+### Add Event Listeners
+
+```javascript
+// Listen for custom events
+dphelper.triggers.add('user:login', (user) => {
+  console.log('User logged in:', user);
+});
+
+dphelper.triggers.on('data:loaded', (data) => {
+  console.log('Data received:', data);
+});
+```
+
+### Emit Events
+
+```javascript
+// Emit events with data
+dphelper.triggers.emit('user:login', { id: 1, name: 'John' });
+
+dphelper.triggers.emit('notification', {
+  type: 'success',
+  message: 'Operation complete!'
+});
+```
+
+### Remove Listeners
+
+```javascript
+// Remove all listeners for an event
+dphelper.triggers.remove('user:login');
+
+// Remove specific callback
+const handler = (data) => console.log(data);
+dphelper.triggers.on('event', handler);
+// ... later
+dphelper.triggers.off('event', handler);
+```
+
+### List Registered Events
+
+```javascript
+// See all registered events
+const events = dphelper.triggers.list();
+console.log(events); // ['user:login', 'data:loaded', ...]
+
+// Clear all triggers
+dphelper.triggers.clear();
+```
+
+### Event-Driven Architecture
+
+```javascript
+// Pub/Sub event system
+class EventBus {
+  constructor() {
+    this.triggers = dphelper.triggers;
+  }
+
+  subscribe(event, callback) {
+    this.triggers.on(event, callback);
+    return () => this.triggers.off(event, callback);
+  }
+
+  publish(event, data) {
+    this.triggers.emit(event, data);
+  }
+}
+
+const bus = new EventBus();
+
+// Subscribe
+const unsubscribe = bus.subscribe('order:created', (order) => {
+  console.log('Order created:', order.id);
+});
+
+// Publish
+bus.publish('order:created', { id: 123, total: 99.99 });
+
+// Unsubscribe
+unsubscribe();
+```
+
+### Component Communication
+
+```javascript
+// Component A - Sender
+function notifyUser(userId, message) {
+  dphelper.triggers.emit('notification', { userId, message });
+}
+
+// Component B - Receiver
+dphelper.triggers.on('notification', ({ userId, message }) => {
+  showToast(`User ${userId}: ${message}`);
+});
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20250220
+- **Last Modified:** 20250220
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/type.md

@@ -0,0 +1,109 @@
+# type
+
+Utilities for type checking.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `of` | Get the type of a value | `dphelper.type.of(value)` |
+| `instOfObj` | Check if value is Object instance | `dphelper.type.instOfObj(value)` |
+| `isNaN` | Check if value is NaN | `dphelper.type.isNaN(value)` |
+| `isBool` | Check if value is boolean | `dphelper.type.isBool(value)` |
+
+## Description
+
+Type checking utilities:
+- **Type Detection** - Get precise type of any value
+- **Boolean Check** - Detect boolean values
+- **NaN Detection** - Identify NaN values
+- **Object Check** - Verify object instances
+
+## Usage Examples
+
+### Get Type
+
+```javascript
+// Get type of value
+console.log(dphelper.type.of('hello'));     // "string"
+console.log(dphelper.type.of(123));          // "number"
+console.log(dphelper.type.of(true));         // "boolean"
+console.log(dphelper.type.of({}));           // "object"
+console.log(dphelper.type.of([]));           // "object"
+console.log(dphelper.type.of(null));        // "null"
+console.log(dphelper.type.of(undefined));    // "undefined"
+```
+
+### Check Object Instance
+
+```javascript
+// Check if value is Object
+console.log(dphelper.type.instOfObj({}));           // true
+console.log(dphelper.type.instOfObj([]));           // true
+console.log(dphelper.type.instOfObj(new Date()));  // true
+console.log(dphelper.type.instOfObj('string'));    // false
+console.log(dphelper.type.instOfObj(123));         // false
+console.log(dphelper.type.instOfObj(null));         // false
+```
+
+### Check NaN
+
+```javascript
+// Check for NaN
+console.log(dphelper.type.isNaN(NaN));              // true
+console.log(dphelper.type.isNaN(0/0));              // true
+console.log(dphelper.type.isNaN('hello'));          // false
+console.log(dphelper.type.isNaN(123));              // false
+
+// Safe number validation
+function isValidNumber(value) {
+  return !dphelper.type.isNaN(value) && dphelper.type.of(value) === 'number';
+}
+```
+
+### Check Boolean
+
+```javascript
+// Check if boolean
+console.log(dphelper.type.isBool(true));    // true
+console.log(dphelper.type.isBool(false));  // true
+console.log(dphelper.type.isBool(1));      // false
+console.log(dphelper.type.isBool('true')); // false
+
+// Boolean coercion check
+function isExplicitBoolean(value) {
+  return dphelper.type.isBool(value);
+}
+```
+
+### Type Guard Functions
+
+```javascript
+// Comprehensive type checking
+function getTypeInfo(value) {
+  return {
+    type: dphelper.type.of(value),
+    isObject: dphelper.type.instOfObj(value),
+    isNaN: dphelper.type.isNaN(value),
+    isBoolean: dphelper.type.isBool(value)
+  };
+}
+
+console.log(getTypeInfo(42));
+// { type: 'number', isObject: false, isNaN: false, isBoolean: false }
+
+console.log(getTypeInfo({a: 1}));
+// { type: 'object', isObject: true, isNaN: false, isBoolean: false }
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/types.md

@@ -0,0 +1,102 @@
+# types
+
+Advanced type checking and validation utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `of` | Get the type of a value | `dphelper.types.of(value)` |
+| `instOfObj` | Check if value is Object instance | `dphelper.types.instOfObj(value)` |
+| `isNaN` | Check if value is NaN | `dphelper.types.isNaN(value)` |
+| `isBool` | Check if value is boolean | `dphelper.types.isBool(value)` |
+
+## Description
+
+Advanced type utilities:
+- **Type Detection** - Get precise type of any value
+- **Boolean Check** - Detect boolean values (including string booleans)
+- **Object Check** - Verify object instances
+
+## Usage Examples
+
+### Get Type
+
+```javascript
+// Get type of value
+console.log(dphelper.types.of('hello'));     // "string"
+console.log(dphelper.types.of(123));        // "number"
+console.log(dphelper.types.of(true));       // "boolean"
+console.log(dphelper.types.of({}));         // "object"
+console.log(dphelper.types.of([]));         // "object"
+console.log(dphelper.types.of(null));       // "null"
+console.log(dphelper.types.of(undefined));  // "undefined"
+```
+
+### Check Object Instance
+
+```javascript
+// Check if value is Object instance
+console.log(dphelper.types.instOfObj({}));           // true
+console.log(dphelper.types.instOfObj([]));           // true
+console.log(dphelper.types.instOfObj(new Date()));    // true
+console.log(dphelper.types.instOfObj('string'));     // false
+console.log(dphelper.types.instOfObj(123));          // false
+```
+
+### Check NaN
+
+```javascript
+// Check for NaN
+console.log(dphelper.types.isNaN(NaN));              // true
+console.log(dphelper.types.isNaN(0/0));              // true
+console.log(dphelper.types.isNaN('hello'));          // false
+console.log(dphelper.types.isNaN(123));             // false
+```
+
+### Check Boolean
+
+```javascript
+// Check if boolean (including string representations)
+console.log(dphelper.types.isBool(true));     // true
+console.log(dphelper.types.isBool(false));    // true
+console.log(dphelper.types.isBool(1));       // false
+console.log(dphelper.types.isBool('true'));  // false
+console.log(dphelper.types.isBool(null));    // true
+console.log(dphelper.types.isBool(undefined));// true
+```
+
+### Form Validation
+
+```javascript
+// Type-safe form validation
+function validateField(value, type) {
+  const actualType = dphelper.types.of(value);
+
+  if (type === 'string' && actualType !== 'string') {
+    return { valid: false, error: 'Must be a string' };
+  }
+
+  if (type === 'number' && actualType !== 'number') {
+    return { valid: false, error: 'Must be a number' };
+  }
+
+  if (type === 'boolean' && !dphelper.types.isBool(value)) {
+    return { valid: false, error: 'Must be a boolean' };
+  }
+
+  return { valid: true };
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/ui.md

@@ -0,0 +1,45 @@
+# UI
+
+User Interface components and Debugging tools.
+
+## Debugging Tools
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `fps` | Toggles a real-time FPS and Memory monitor overlay | `dphelper.UI.fps(true)` |
+| `boxModel` | Toggles visual box-model highlighter for all elements | `dphelper.UI.boxModel(true)` |
+
+## Base Components
+
+- `input`, `button`, `textarea`, `select`, `code` (Work in progress)
+
+## Description
+
+The UI module provides both functional interface components and developer-oriented inspection tools to monitor application health and layout.
+
+## Usage Examples
+
+### Performance Monitoring
+
+```javascript
+// Shows FPS and RAM usage on screen
+dphelper.UI.fps(true);
+```
+
+### Layout Debugging
+
+```javascript
+// Highlights borders of all elements on the page
+dphelper.UI.boxModel(true);
+```
+
+## Details
+
+- **Author:** Dario Passariello & Jo
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/markdown/window.md

@@ -0,0 +1,211 @@
+# window
+
+Window management utilities for popups, zoom control, page leave handling, and memory management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `enhancement` | Enhance window with additional properties | `dphelper.window.enhancement()` |
+| `center` | Open centered popup window | `dphelper.window.center({ url, title, name, w, h })` |
+| `onBeforeUnLoad` | Prompt before leaving page | `dphelper.window.onBeforeUnLoad('#form')` |
+| `purge` | Clear elements from memory | `dphelper.window.purge()` |
+| `stopZoomWheel` | Disable Ctrl+wheel zoom | `dphelper.window.stopZoomWheel()` |
+| `setZoom` | Set element zoom level | `dphelper.window.setZoom('#container', 1.5)` |
+| `getZoom` | Get element zoom level | `dphelper.window.getZoom('#container')` |
+
+## Description
+
+Complete window management toolkit:
+- **Popup Windows** - Centered, sized windows
+- **Zoom Control** - Get/set zoom levels
+- **Page Exit** - Warn before leaving with unsaved changes
+- **Memory** - Purge unused elements
+- **Accessibility** - Disable unwanted zoom
+
+## Usage Examples
+
+### Centered Popup Window
+
+```javascript
+// Open centered popup
+dphelper.window.center({
+  url: 'https://example.com',
+  title: 'Popup Window',
+  name: 'myPopup',
+  w: 800,  // width
+  h: 600   // height
+});
+
+// Useful for:
+// - Video players
+// - Image galleries
+// - Login/signup modals
+// - External content
+```
+
+### Before Unload Warning
+
+```javascript
+// Warn user before leaving with unsaved changes
+dphelper.window.onBeforeUnLoad('#myForm');
+
+// When user tries to leave:
+// - Fills out form
+// - Clicks external link
+// - Closes tab
+// -> Shows confirmation dialog
+
+// Clean form detection
+// <input id="myForm">
+// Warning only shows if form has content
+```
+
+### Zoom Control
+
+```javascript
+// Get current zoom level
+const zoom = dphelper.window.getZoom();
+console.log(zoom); // 1 (or 1.5, 2, etc.)
+
+// Get specific element zoom
+const elZoom = dphelper.window.getZoom('#container');
+console.log(elZoom);
+
+// Set zoom level (1 = 100%)
+dphelper.window.setZoom('#container', 1.5); // 150%
+dphelper.window.setZoom('#container', 2);    // 200%
+dphelper.window.setZoom('#container', 0.5);  // 50%
+
+// Reset to default
+dphelper.window.setZoom('#container', 1);
+```
+
+### Disable Mouse Wheel Zoom
+
+```javascript
+// Prevent Ctrl+wheel zoom (accessibility feature)
+dphelper.window.stopZoomWheel();
+
+// Useful for:
+// - Interactive maps
+// - Canvas applications
+// - Games
+// - Preventing accidental zoom
+```
+
+### Memory Purge
+
+```javascript
+// Purge document from memory after delay
+dphelper.window.purge(document, 10000); // 10 seconds
+
+// Or purge specific element
+const oldContent = document.getElementById('oldContent');
+dphelper.window.purge(oldContent, 5000);
+
+// Cleans up:
+// - Event listeners
+// - References
+// - Child nodes
+```
+
+### Window Enhancement
+
+```javascript
+// Enhance window with cross-browser utilities
+dphelper.window.enhancement();
+
+// Adds:
+// - Cross-browser requestAnimationFrame
+// - Additional window properties
+```
+
+## Advanced Usage
+
+### Complete Form Protection
+
+```javascript
+class FormProtection {
+  constructor(formSelector) {
+    this.form = document.querySelector(formSelector);
+    this.init();
+  }
+
+  init() {
+    // Enable beforeunload warning
+    dphelper.window.onBeforeUnLoad(this.form);
+  }
+
+  // Clean up when form is submitted
+  onSubmit(callback) {
+    this.form.addEventListener('submit', (e) => {
+      // Remove protection after successful submit
+      this.disable();
+      callback(e);
+    });
+  }
+
+  disable() {
+    // Programmatically disable warning
+    window.onbeforeunload = null;
+  }
+}
+
+// Usage
+const protectedForm = new FormProtection('#contactForm');
+protectedForm.onSubmit(() => {
+  console.log('Form submitted!');
+});
+```
+
+### Responsive Zoom Handler
+
+```javascript
+class ZoomManager {
+  constructor(container) {
+    this.container = container;
+    this.setupHandlers();
+  }
+
+  setupHandlers() {
+    // Disable default zoom
+    dphelper.window.stopZoomWheel();
+
+    // Track zoom changes
+    window.addEventListener('resize', () => this.handleResize());
+  }
+
+  handleResize() {
+    const width = window.innerWidth;
+    let zoom = 1;
+
+    if (width < 768) {
+      zoom = 0.75;
+    } else if (width < 1024) {
+      zoom = 0.9;
+    }
+
+    dphelper.window.setZoom(this.container, zoom);
+  }
+
+  getCurrentZoom() {
+    return dphelper.window.getZoom(this.container);
+  }
+}
+
+// Usage
+const zoomManager = new ZoomManager('#app-container');
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*