dphelper 3.7.1 → 3.7.2

package/docs/markdown/coords.md

@@ -0,0 +1,127 @@
+# coords
+
+Coordinate and geometry utilities for GPS, mapping, and calculations.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `degreesToRadians` | Convert degrees to radians | `dphelper.coords.degreesToRadians(45)` |
+| `latToMeters` | Convert latitude to meters | `dphelper.coords.latToMeters([40.68, -74.04])` |
+| `toVector` | Convert coordinates to 3D vector | `dphelper.coords.toVector([lat, lon, alt])` |
+| `convertToDecDegrees` | Convert DMS to decimal degrees | `dphelper.coords.convertToDecDegrees(39, 5, 59, 'N')` |
+| `distance` | Calculate distance between two points (Haversine) | `dphelper.coords.distance([lat1, lon1], [lat2, lon2])` |
+| `polarToCartesian` | Convert polar to Cartesian coordinates | `dphelper.coords.polarToCartesian(x, y, radius, angle)` |
+| `mapDegreesToPixels` | Map degrees to pixel values | `dphelper.coords.mapDegreesToPixels(deg, min, max, minPx, maxPx, pad)` |
+
+## Description
+
+Coordinate manipulation toolkit:
+- **Unit Conversion** - Degrees, radians, meters
+- **Distance Calculation** - Haversine formula for GPS
+- **Coordinate Systems** - Polar, Cartesian, 3D vectors
+- **Mapping** - Degrees to pixels for maps
+
+## Usage Examples
+
+### Degree/Radian Conversion
+
+```javascript
+// Degrees to radians
+console.log(dphelper.coords.degreesToRadians(0));    // 0
+console.log(dphelper.coords.degreesToRadians(90));   // 1.57...
+console.log(dphelper.coords.degreesToRadians(180));  // 3.14...
+console.log(dphelper.coords.degreesToRadians(360));  // 6.28...
+```
+
+### Distance Calculation (GPS)
+
+```javascript
+// Distance between New York and Washington DC
+const nyc = [40.7128, -74.0060];
+const dc = [38.9072, -77.0369];
+
+const dist = dphelper.coords.distance(nyc, dc);
+console.log(dist);
+// { km: 328.54, mi: 204.18, nMi: 177.4 }
+
+// Calculate travel distance for logistics
+const locations = [
+  [40.7128, -74.0060],  // NYC
+  [39.9526, -75.1652],  // Philadelphia
+  [39.2894, -76.6152],  // Baltimore
+  [38.9072, -77.0369]   // Washington DC
+];
+
+function calculateTotalDistance(points) {
+  let total = 0;
+  for (let i = 0; i < points.length - 1; i++) {
+    const dist = dphelper.coords.distance(points[i], points[i + 1]);
+    total += dist.km;
+  }
+  return total;
+}
+```
+
+### Coordinate Conversion
+
+```javascript
+// Convert DMS to decimal degrees
+// 39° 5' 59" N -> decimal
+const dec = dphelper.coords.convertToDecDegrees(39, 5, 59, 'N');
+console.log(dec); // 39.0997...
+
+// With South/West (negative)
+const south = dphelper.coords.convertToDecDegrees(33, 51, 30, 'S');
+console.log(south); // -33.8583...
+```
+
+### 3D Vector from GPS
+
+```javascript
+// Convert GPS coordinates to 3D Earth-centered vector
+const vector = dphelper.coords.toVector([40.7128, -74.0060, 0]);
+console.log(vector);
+// [x, y, z] in meters from Earth center
+```
+
+### Polar to Cartesian
+
+```javascript
+// Convert polar to Cartesian for graphics
+const cart = dphelper.coords.polarToCartesian(100, 100, 50, 90);
+console.log(cart);
+// { x: 100, y: 150 }
+
+// Create circular motion
+for (let angle = 0; angle < 360; angle += 30) {
+  const pos = dphelper.coords.polarToCartesian(200, 200, 80, angle);
+  console.log(`Angle ${angle}:`, pos);
+}
+```
+
+### Map Pixel Mapping
+
+```javascript
+// Map latitude to pixel for interactive maps
+const pixel = dphelper.coords.mapDegreesToPixels(
+  45,     // Current degree
+  30,     // Min latitude
+  60,      // Max latitude
+  0,       // Min pixel
+  500,     // Max pixel
+  10       // Padding
+);
+```
+
+## 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/credits.md

@@ -0,0 +1,56 @@
+# credits
+
+Application startup credits and initialization logger.
+
+## Functions
+
+| Function | Description |
+|----------|-------------|
+| `credits` | Logs application startup information to console |
+
+## Description
+
+Displays application information on startup:
+- **Version** - Current application version
+- **Author** - Developer credits
+- **Console Logging** - Grouped, styled output
+
+## Usage Examples
+
+### Automatic Startup
+
+```javascript
+// Automatically called on dphelper initialization
+// Shows in console:
+//
+// ┌─────────────────────────────────────┐
+// │  dphelper v1.0.0                    │
+// │  by Dario Passariello started       │
+// │  name: dphelper                     │
+// │  version: 1.0.0                     │
+// └─────────────────────────────────────┘
+
+// Output is styled with orange color for visibility
+```
+
+### Console Output
+
+```javascript
+// When called, displays:
+// dphelper v1.0.0
+// by Dario Passariello started
+// name: dphelper
+// version: 1.0.0
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/date.md

@@ -0,0 +1,260 @@
+# date
+
+Comprehensive date and time manipulation utilities with support for multiple formats, locales, and timezone handling.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `days` | Returns array of day names in specified language | `dphelper.date.days('en')` |
+| `months` | Returns array of month names in specified language | `dphelper.date.months('en')` |
+| `year` | Returns current year | `dphelper.date.year()` |
+| `toIso` | Converts date to ISO format (localized) | `dphelper.date.toIso(value, 'en')` |
+| `toMMDDYYYY` | Converts to MMDDYYYY format | `dphelper.date.toMMDDYYYY(value)` |
+| `toYYYYMMDD` | Converts to YYYYMMDD format (database-friendly) | `dphelper.date.toYYYYMMDD(value)` |
+| `toHuman` | Converts to human-readable format | `dphelper.date.toHuman(value)` |
+| `convert` | Converts date between formats using month array | `dphelper.date.convert(value, format)` |
+| `iso2Epoch` | Converts ISO date to epoch milliseconds | `dphelper.date.iso2Epoch(value)` |
+| `localIsoTime` | Gets local ISO time for a date | `dphelper.date.localIsoTime(value)` |
+| `utc` | Gets current UTC time string | `dphelper.date.utc()` |
+| `parse` | Parses date with custom separator | `dphelper.date.parse(value, '/')` |
+| `addDays` | Adds days to a date | `dphelper.date.addDays(date, 5)` |
+| `dateTimeToString` | Converts date to formatted string | `dphelper.date.dateTimeToString(date)` |
+| `isoToHuman` | Converts ISO to human format with time | `dphelper.date.isoToHuman(value, '@')` |
+| `fullDate` | Returns DD-MM-YYYY HH:MM:SS format | `dphelper.date.fullDate()` |
+| `epoch` | Returns current epoch time in milliseconds | `dphelper.date.epoch()` |
+| `diffInDays` | Calculates difference between two dates in days | `dphelper.date.diffInDays(d1, d2)` |
+| `diffInWeeks` | Calculates difference between two dates in weeks | `dphelper.date.diffInWeeks(d1, d2)` |
+| `diffInMonths` | Calculates difference between two dates in months | `dphelper.date.diffInMonths(d1, d2)` |
+| `diffInYears` | Calculates difference between two dates in years | `dphelper.date.diffInYears(d1, d2)` |
+| `dateToYMD` | Converts date to YYYY-MM-DD format | `dphelper.date.dateToYMD(date)` |
+| `collection` | Returns various date format representations | `dphelper.date.collection({ type: 'toISOString' })` |
+| `timeZones` | Returns array of all supported timezones | `dphelper.date.timeZones()` |
+
+## Description
+
+Complete date manipulation library providing:
+- **Format Conversion** - ISO, MMDDYYYY, YYYYMMDD, human-readable
+- **Localization** - Multi-language day/month names
+- **Timezone Support** - UTC, local time, timezone list
+- **Date Arithmetic** - Add days, calculate differences
+- **Epoch/Unix Time** - Convert to/from milliseconds
+- **Date Collections** - Multiple format representations
+
+## Usage Examples
+
+### Getting Current Date Information
+
+```javascript
+// Get current year
+console.log(dphelper.date.year()); // 2026
+
+// Get current UTC time
+console.log(dphelper.date.utc()); // "Mon, 02 Mar 2026 09:44:55 GMT"
+
+// Get full date and time
+console.log(dphelper.date.fullDate()); // "02-03-2026 09:44:55"
+
+// Get current epoch time
+console.log(dphelper.date.epoch()); // 1709375095000
+
+// Get supported timezones
+console.log(dphelper.date.timeZones()); // ["Africa/Abidjan", "America/Adak", ...]
+```
+
+### Format Conversions
+
+```javascript
+const date = new Date('2026-03-15T10:30:00Z');
+
+// To ISO format (localized)
+console.log(dphelper.date.toIso(date, 'en'));  // "March 15, 2026"
+console.log(dphelper.date.toIso(date, 'it'));  // "15 marzo 2026"
+
+// To MMDDYYYY
+console.log(dphelper.date.toMMDDYYYY(date)); // "03152026"
+
+// To YYYYMMDD (database format)
+console.log(dphelper.date.toYYYYMMDD(date)); // "20260315"
+
+// To human readable
+console.log(dphelper.date.toHuman(date)); // "Sunday, March 15, 2026"
+
+// To YYYY-MM-DD
+console.log(dphelper.date.dateToYMD(date)); // "2026-03-15"
+
+// ISO to human with custom separator
+console.log(dphelper.date.isoToHuman('2026-03-15T14:30:00', '@'));
+// "15 March 2026 @ 14:30"
+```
+
+### Date Parsing
+
+```javascript
+// Parse date with custom separator
+console.log(dphelper.date.parse('03152026', '/')); // "03/15/2026"
+console.log(dphelper.date.parse('15.03.2026', '.')); // "15.03.2026"
+
+// Convert between formats using month array
+const months = dphelper.date.months('en');
+console.log(dphelper.date.convert('03152026', months)); // "15 March 2026"
+```
+
+### Date Arithmetic
+
+```javascript
+const today = new Date('2026-03-15');
+
+// Add days to a date
+const nextWeek = dphelper.date.addDays(today, 7);
+console.log(nextWeek); // Date object for 2026-03-22
+
+const lastMonth = dphelper.date.addDays(today, -30);
+console.log(lastMonth); // Date object for 2026-02-13
+```
+
+### Date Differences
+
+```javascript
+const date1 = new Date('2026-01-01');
+const date2 = new Date('2026-03-15');
+
+// Calculate differences
+console.log(dphelper.date.diffInDays(date1, date2));   // 73 days
+console.log(dphelper.date.diffInWeeks(date1, date2)); // 10 weeks
+console.log(dphelper.date.diffInMonths(date1, date2)); // 2 months
+console.log(dphelper.date.diffInYears(date1, date2));  // 0 years
+
+// Calculate age
+const birthDate = new Date('1990-05-20');
+const now = new Date();
+const age = dphelper.date.diffInYears(birthDate, now);
+console.log(age); // 35 (approximately)
+```
+
+### Epoch/Unix Time Conversion
+
+```javascript
+const isoDate = '2026-03-15T10:30:00Z';
+
+// ISO to epoch (milliseconds)
+console.log(dphelper.date.iso2Epoch(isoDate)); // 1778979000000
+
+// Current epoch
+console.log(dphelper.date.epoch()); // 1709375095000
+
+// Epoch back to date
+const epoch = 1709375095000;
+const date = new Date(epoch);
+console.log(date.toISOString()); // "2026-03-02T09:44:55.000Z"
+```
+
+### Local vs UTC Time
+
+```javascript
+const date = new Date();
+
+// Get local ISO time
+console.log(dphelper.date.localIsoTime(date));
+// "2026-03-02T02:44:55.123"
+
+// Get UTC time
+console.log(dphelper.date.utc());
+// "Mon, 02 Mar 2026 09:44:55 GMT"
+```
+
+### Date Collection (Multiple Formats)
+
+```javascript
+const date = new Date('2026-03-15T14:30:00');
+
+// Get various representations
+console.log(dphelper.date.collection({ date, type: 'toDateString' }));
+// "Sun Mar 15 2026"
+
+console.log(dphelper.date.collection({ date, type: 'toISOString' }));
+// "2026-03-15T14:30:00.000Z"
+
+console.log(dphelper.date.collection({ date, type: 'toLocaleDateString' }));
+// "3/15/2026"
+
+console.log(dphelper.date.collection({ date, type: 'toLocaleString' }));
+// "3/15/2026, 7:30:00 AM"
+
+console.log(dphelper.date.collection({ date, type: 'toISOStringShort' }));
+// "2026-03-15"
+```
+
+### Localization
+
+```javascript
+// Get day names in different languages
+console.log(dphelper.date.days('en'));
+// ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
+
+console.log(dphelper.date.days('it'));
+// ["lunedì", "martedì", "mercoledì", "giovedì", "venerdì", "sabato", "domenica"]
+
+// Get month names in different languages
+console.log(dphelper.date.months('en'));
+// ["January", "February", "March", ...]
+
+console.log(dphelper.date.months('it'));
+// ["gennaio", "febbraio", "marzo", ...]
+```
+
+## Advanced Usage
+
+### Date Range Calculator
+
+```javascript
+function getDateRange(startDate, endDate) {
+  const days = dphelper.date.diffInDays(startDate, endDate);
+  const weeks = dphelper.date.diffInWeeks(startDate, endDate);
+  const months = dphelper.date.diffInMonths(startDate, endDate);
+
+  return { days, weeks, months };
+}
+
+const start = new Date('2026-01-01');
+const end = new Date('2026-12-31');
+console.log(getDateRange(start, end));
+// { days: 364, weeks: 52, months: 11 }
+```
+
+### Timestamp Logger
+
+```javascript
+function logWithTimestamp(message) {
+  const timestamp = dphelper.date.fullDate();
+  console.log(`[${timestamp}] ${message}`);
+}
+
+logWithTimestamp('Application started');
+// [02-03-2026 09:44:55] Application started
+```
+
+### Database Date Handler
+
+```javascript
+// Save to database
+const dbDate = dphelper.date.toYYYYMMDD(new Date());
+console.log(dbDate); // "20260302"
+
+// Read from database
+const dbValue = "20260315";
+const displayDate = dphelper.date.toHuman(new Date(dbValue));
+console.log(displayDate); // "Sunday, March 15, 2026"
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/disable.md

@@ -0,0 +1,109 @@
+# disable
+
+Disabling browser functionalities on DOM elements.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `select` | Disable text selection | `dphelper.disable.select(el)` |
+| `spellCheck` | Disable spell checking | `dphelper.disable.spellCheck(tmr)` |
+| `rightClick` | Disable context menu | `dphelper.disable.rightClick(el)` |
+| `copy` | Disable copy functionality | `dphelper.disable.copy(el)` |
+| `paste` | Disable paste functionality | `dphelper.disable.paste(el)` |
+
+## Description
+
+Browser functionality control:
+- **Text Selection** - Prevent user from selecting text
+- **Context Menu** - Disable right-click menu
+- **Clipboard** - Disable copy/paste operations
+- **Spell Check** - Turn off browser spell checking
+- **Element Targeting** - Apply to specific elements or entire page
+
+## Usage Examples
+
+### Disable Text Selection
+
+```javascript
+// Disable selection on entire page
+dphelper.disable.select();
+
+// Disable on specific element
+dphelper.disable.select('#protected-content');
+
+// Re-enable selection (manual CSS)
+document.body.style.userSelect = 'text';
+```
+
+### Disable Right-Click Context Menu
+
+```javascript
+// Disable right-click on entire page
+dphelper.disable.rightClick();
+
+// Disable on specific container
+dphelper.disable.rightClick('#game-area');
+
+// Useful for games or protected content
+const protectedArea = document.getElementById('protected');
+dphelper.disable.rightClick('#protected');
+```
+
+### Disable Copy/Paste
+
+```javascript
+// Disable copy on specific element
+dphelper.disable.copy('#secure-input');
+
+// Disable paste
+dphelper.disable.paste('#no-paste-input');
+
+// Combined for form security
+dphelper.disable.copy('. confidential-data');
+dphelper.disable.paste('.confidential-data');
+```
+
+### Disable Spell Check
+
+```javascript
+// Disable spell check (default 5000ms delay)
+dphelper.disable.spellCheck();
+
+// Custom timing
+dphelper.disable.spellCheck(3000);
+
+// Apply to text inputs
+document.querySelectorAll('input[type="text"], textarea').forEach(el => {
+  el.spellcheck = false;
+});
+```
+
+### Complete Protection Setup
+
+```javascript
+// Full content protection
+function protectContent(selector) {
+  dphelper.disable.select(selector);
+  dphelper.disable.rightClick(selector);
+  dphelper.disable.copy(selector);
+}
+
+// Protect premium article
+protectContent('.premium-content');
+
+// Protect user profile
+protectContent('#user-profile');
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/dispatch.md

@@ -0,0 +1,108 @@
+# dispatch
+
+Custom event dispatch and listener management utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `set` | Dispatch a custom event | `dphelper.dispatch.set('myEvent', { detail: data })` |
+| `listen` | Listen for custom events | `dphelper.dispatch.listen('myEvent', callback)` |
+| `remove` | Remove event listener | `dphelper.dispatch.remove('myEvent')` |
+
+## Description
+
+Custom event management:
+- **Dispatch** - Fire custom events with data
+- **Listen** - Register event handlers
+- **Manage** - Remove listeners
+
+## Usage Examples
+
+### Dispatching Events
+
+```javascript
+// Simple event
+dphelper.dispatch.set('user:login');
+
+// With data
+dphelper.dispatch.set('user:login', {
+  detail: { userId: 123, timestamp: Date.now() }
+});
+
+// Application events
+dphelper.dispatch.set('app:loaded');
+dphelper.dispatch.set('data:updated', { detail: { source: 'api' } });
+```
+
+### Listening for Events
+
+```javascript
+// Listen for event
+dphelper.dispatch.listen('user:login', (e) => {
+  console.log('User logged in:', e.detail);
+});
+
+// Multiple handlers
+dphelper.dispatch.listen('data:updated', (e) => {
+  console.log('Data updated:', e.detail);
+});
+
+// App lifecycle
+dphelper.dispatch.listen('app:loaded', () => {
+  console.log('App ready!');
+  initializeApp();
+});
+```
+
+### Removing Listeners
+
+```javascript
+// Remove specific listener
+dphelper.dispatch.remove('user:login');
+
+// Clean up on component unmount
+function cleanup() {
+  dphelper.dispatch.remove('myEvent');
+}
+```
+
+### Complete Event System
+
+```javascript
+class EventBus {
+  constructor() {
+    this.listeners = {};
+  }
+
+  on(event, callback) {
+    dphelper.dispatch.listen(event, callback);
+  }
+
+  emit(event, data) {
+    dphelper.dispatch.set(event, { detail: data });
+  }
+
+  off(event) {
+    dphelper.dispatch.remove(event);
+  }
+}
+
+// Usage
+const events = new EventBus();
+
+events.on('user:action', (e) => console.log('Action:', e.detail));
+events.emit('user:action', { type: 'click', target: 'button' });
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20231231
+- **Last Modified:** 20240612
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*