dphelper 3.5.5 → 3.7.2

package/docs/markdown/terminal.md

@@ -0,0 +1,73 @@
+# terminal
+
+Creates a terminal-like interface in the browser console or a DOM element.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `terminal` | Create terminal in DOM element | `dphelper.terminal(parentDom)` |
+
+## Description
+
+In-browser terminal:
+- **Console Redirect** - Redirect console methods to DOM
+- **Visual Output** - See logs in a visual terminal
+- **Debugging** - Great for debugging web apps
+- **Interactive** - Create terminal-like interface
+
+## Usage Examples
+
+### Create Terminal
+
+```javascript
+// Create terminal in a div
+const terminalDiv = document.getElementById('terminal');
+dphelper.terminal(terminalDiv);
+
+// Now console.log, console.error etc. appear in the div
+console.log("Hello Terminal!");
+console.error("Error message");
+console.warn("Warning");
+```
+
+### Debug Panel
+
+```javascript
+// Add debug terminal to page
+<div id="debug-terminal" style="background: #000; color: #0f0; padding: 10px;"></div>
+
+dphelper.terminal('#debug-terminal');
+
+// All console output now goes to the terminal
+console.log('App started');
+console.debug('Debug info');
+console.error('Something went wrong');
+```
+
+### Application Logging
+
+```javascript
+// Use as application log viewer
+function initDebugTerminal() {
+  const terminal = document.getElementById('terminal');
+  dphelper.terminal(terminal);
+
+  // Your app logs now appear visually
+  console.log('[APP] Initializing...');
+  console.log('[APP] Loading data...');
+  console.error('[APP] Failed to load');
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20240525
+- **Last Modified:** 20240525
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/text.md

@@ -0,0 +1,245 @@
+# text
+
+Utilities for text and string manipulation.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `trim` | Trim specific characters from string | `dphelper.text.trim(s, c, b, e)` |
+| `capitalize` | Capitalize first letter of each word | `dphelper.text.capitalize(txt)` |
+| `lower` | Convert string to lowercase | `dphelper.text.lower(txt)` |
+| `upper` | Convert string to uppercase | `dphelper.text.upper(txt)` |
+| `nl2br` | Convert newlines to `<br>` tags | `dphelper.text.nl2br(str)` |
+| `sanitize` | Remove HTML tags from string | `dphelper.text.sanitize(str)` |
+| `camelCase.toSpace` | Convert camelCase to space-separated | `dphelper.text.camelCase.toSpace(str)` |
+| `camelCase.toUnderscore` | Convert camelCase to underscore | `dphelper.text.camelCase.toUnderscore(str)` |
+| `fitContainer` | Auto-adjust font size to fit container | `dphelper.text.fitContainer(selector)` |
+| `keywords` | Extract keywords from sentence | `dphelper.text.keywords(sentence)` |
+| `replaceText` | Replace multiple patterns in text | `dphelper.text.replaceText(text, replacements)` |
+
+## Description
+
+Comprehensive text manipulation utilities:
+- **Case Conversion** - lower, upper, capitalize
+- **HTML Conversion** - nl2br, sanitize HTML tags
+- **camelCase** - Convert to/from space or underscore
+- **Text Extraction** - Extract keywords from text
+- **Pattern Replacement** - Multi-replacement operations
+
+## Usage Examples
+
+### Capitalize
+
+```javascript
+// Capitalize each word
+const text = 'hello world from dpHelper';
+const capitalized = dphelper.text.capitalize(text);
+// Output: "Hello World From DpHelper"
+
+// Use for titles
+const title = 'the quick brown fox';
+console.log(dphelper.text.capitalize(title));
+// "The Quick Brown Fox"
+```
+
+### Lower/Upper Case
+
+```javascript
+// Convert to lowercase
+const upper = 'HELLO WORLD';
+console.log(dphelper.text.lower(upper));
+// "hello world"
+
+// Convert to uppercase
+const lower = 'hello world';
+console.log(dphelper.text.upper(lower));
+// "HELLO WORLD"
+
+// Normalize user input
+const username = '  JohnDoe  ';
+console.log(dphelper.text.lower(username.trim()));
+// "johndoe"
+```
+
+### Newlines to BR Tags
+
+```javascript
+// Convert newlines to HTML <br>
+const text = 'Line 1\nLine 2\nLine 3';
+const html = dphelper.text.nl2br(text);
+// Output: "Line 1<br>Line 2<br>Line 3"
+
+// Display user textarea content
+function displayTextareaContent(textareaValue) {
+  return dphelper.text.nl2br(textareaValue);
+}
+
+// Preserve whitespace
+const poem = 'Roses are red\nViolets are blue\nSugar is sweet\nAnd so are you';
+document.getElementById('poem').innerHTML = dphelper.text.nl2br(poem);
+```
+
+### Remove HTML Tags
+
+```javascript
+// Strip HTML tags
+const html = '<p>Hello <b>World</b></p>';
+const plain = dphelper.text.sanitize(html);
+// Output: "Hello World"
+
+// Get plain text from rich editor
+function getPlainText(htmlContent) {
+  return dphelper.text.sanitize(htmlContent);
+}
+
+// Extract text from HTML
+const article = '<article><h1>Title</h1><p>Content here</p></article>';
+console.log(dphelper.text.sanitize(article));
+// "TitleContent here"
+```
+
+### camelCase Conversions
+
+```javascript
+// camelCase to space-separated
+const camel = 'userNameFirst';
+const spaced = dphelper.text.camelCase.toSpace(camel);
+// Output: "User Name First"
+
+// camelCase to underscore
+const underscored = dphelper.text.camelCase.toUnderscore(camel);
+// Output: "user_name_first"
+
+// Use for readable labels
+function createLabel(key) {
+  return dphelper.text.camelCase.toSpace(key);
+}
+
+console.log(createLabel('firstName'));  // "First Name"
+console.log(createLabel('lastName'));   // "Last Name"
+console.log(createLabel('emailAddress')); // "Email Address"
+
+// Database to UI
+const dbColumn = 'createdAtDate';
+console.log(dphelper.text.camelCase.toSpace(dbColumn));
+// "Created At Date"
+```
+
+### Extract Keywords
+
+```javascript
+// Extract keywords from text (words > 3 chars, title case)
+const sentence = 'The JavaScript Programming Language is Amazing';
+const keywords = dphelper.text.keywords(sentence);
+// Output: ["javascript", "programming", "language", "amazing"]
+
+// Analyze text content
+function analyzeContent(text) {
+  return {
+    keywords: dphelper.text.keywords(text),
+    wordCount: text.split(/\s+/).length
+  };
+}
+
+// Tag generation
+const article = 'React is a JavaScript library for building user interfaces';
+const tags = dphelper.text.keywords(article);
+// ["react", "javascript", "library", "building", "user", "interfaces"]
+```
+
+### Replace Multiple Patterns
+
+```javascript
+// Replace multiple patterns at once
+const text = 'Copyright (c) 2024 by Company (r)';
+const result = dphelper.text.replaceText(text, {
+  '(c)': '&copy;',
+  '(r)': '&reg;',
+  '(tm)': '&trade;'
+});
+// Output: "Copyright © 2024 by Company ®"
+
+// Symbol replacement
+const legal = 'Copyright (c) 2024 (r) All Rights Reserved (tm)';
+console.log(dphelper.text.replaceText(legal, {
+  '(c)': '©',
+  '(r)': '®',
+  '(tm)': '™'
+}));
+// "Copyright © 2024 ® All Rights Reserved ™"
+
+// Emoticon replacement
+const message = 'Hello :) Have a great day !';
+const emoticons = dphelper.text.replaceText(message, {
+  ':)': '😊',
+  '(:': '😊',
+  ':(': '😢',
+  '):': '😢',
+  '!': '❗'
+});
+// "Hello 😊 Have a great day ❗"
+```
+
+### Auto-fit Text to Container
+
+```javascript
+// Automatically adjust font size to fit container width
+// HTML: <div id="title">Long Title Text Here</div>
+
+dphelper.text.fitContainer('#title');
+
+// The font-size will auto-adjust based on container width
+// Responds to window resize events
+```
+
+### Complete Form Processor
+
+```javascript
+class TextProcessor {
+  static formatTitle(text) {
+    return dphelper.text.capitalize(dphelper.text.lower(text.trim()));
+  }
+
+  static toSlug(text) {
+    const spaced = dphelper.text.camelCase.toUnderscore(text);
+    return dphelper.text.lower(spaced).replace(/\s+/g, '-');
+  }
+
+  static extractSearchTerms(text) {
+    return dphelper.text.keywords(text);
+  }
+
+  static prepareForDisplay(text) {
+    return dphelper.text.nl2br(
+      dphelper.text.sanitize(text)
+    );
+  }
+
+  static replaceSymbols(text, symbols) {
+    return dphelper.text.replaceText(text, symbols);
+  }
+}
+
+// Usage
+console.log(TextProcessor.formatTitle('HELLO WORLD'));
+// "Hello world"
+
+console.log(TextProcessor.toSlug('User Name First'));
+// "user_name_first"
+
+console.log(TextProcessor.extractSearchTerms('React and Vue are Frameworks'));
+// ["react", "vue", "frameworks"]
+```
+
+## 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/timer.md

@@ -0,0 +1,98 @@
+# timer
+
+Management of timers, delays, and intervals.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `sleep` | Pause execution for milliseconds | `dphelper.timer.sleep(ms)` |
+| `percentage` | Calculate time percentage between dates | `dphelper.timer.percentage(start, end)` |
+
+## Description
+
+Timer utilities:
+- **Sleep** - Async pause/delay
+- **Percentage** - Calculate elapsed time percentage
+
+## Usage Examples
+
+### Sleep/Delay
+
+```javascript
+// Async delay
+await dphelper.timer.sleep(1000);
+// Pauses for 1 second
+
+// In async functions
+async function delayedAction() {
+  console.log('Start');
+  await dphelper.timer.sleep(2000);
+  console.log('After 2 seconds');
+}
+
+// Retry with delay
+async function retryWithBackoff(fn, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (i < maxRetries - 1) {
+        await dphelper.timer.sleep(1000 * Math.pow(2, i));
+      }
+    }
+  }
+}
+```
+
+### Time Percentage
+
+```javascript
+// Calculate progress percentage
+const start = new Date('2024-01-01');
+const end = new Date('2024-12-31');
+const now = new Date('2024-06-15');
+
+const progress = dphelper.timer.percentage(start, end);
+// Returns percentage of year complete (approximately 50%)
+
+// Countdown timer
+const eventStart = new Date('2024-12-25');
+const today = new Date();
+
+const percentComplete = dphelper.timer.percentage(today, eventStart);
+console.log(`${percentComplete}% until event`);
+```
+
+### Progress Tracking
+
+```javascript
+// Track operation progress
+function trackProgress(startTime, duration) {
+  const now = Date.now();
+  const elapsed = now - startTime;
+  return dphelper.timer.percentage(startTime, startTime + duration);
+}
+
+const operationDuration = 10000; // 10 seconds
+const start = Date.now();
+
+// In a loop
+setInterval(() => {
+  const progress = trackProgress(start, operationDuration);
+  console.log(`${progress}% complete`);
+  if (progress >= 100) clearInterval(this);
+}, 500);
+```
+
+## 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/tools.md

@@ -0,0 +1,111 @@
+# tools
+
+Miscellaneous developer utilities for common programming tasks.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `byteSize` | Converts bytes to human-readable format (KB, MB, GB, etc.) | `dphelper.tools.byteSize(1024)` |
+| `zIndex` | Finds the highest z-index value in the DOM | `dphelper.tools.zIndex()` |
+| `zeroToFalse` | Converts zero to false, otherwise returns the value | `dphelper.tools.zeroToFalse(0)` |
+
+## Description
+
+This module provides various utility functions that are commonly needed in web development projects. It includes byte size conversion, DOM z-index detection, and value transformation utilities.
+
+## Usage Examples
+
+### Byte Size Conversion
+
+Convert file sizes from bytes to human-readable format:
+
+```javascript
+// Convert bytes to KB, MB, GB, etc.
+console.log(dphelper.tools.byteSize(500));      // "500b"
+console.log(dphelper.tools.byteSize(1024));     // "1.0Kb"
+console.log(dphelper.tools.byteSize(1048576));  // "1.0Mb"
+console.log(dphelper.tools.byteSize(1073741824)); // "1.0Gb"
+
+// Useful for displaying file sizes
+const fileSize = 15728640; // 15 MB in bytes
+console.log(dphelper.tools.byteSize(fileSize)); // "15.0Mb"
+```
+
+### Z-Index Detection
+
+Find the highest z-index in the document to ensure new elements appear on top:
+
+```javascript
+// Get the highest z-index in the DOM
+const highestZ = dphelper.tools.zIndex();
+console.log(highestZ); // e.g., 100
+
+// Create a new modal on top of all other elements
+const modal = document.createElement('div');
+modal.style.zIndex = highestZ + 1;
+modal.style.position = 'absolute';
+document.body.appendChild(modal);
+```
+
+### Zero to False Conversion
+
+Convert numeric zero to boolean false for conditional logic:
+
+```javascript
+// Returns false when value is 0
+console.log(dphelper.tools.zeroToFalse(0));    // false
+console.log(dphelper.tools.zeroToFalse(1));    // 1
+console.log(dphelper.tools.zeroToFalse(42));   // 42
+console.log(dphelper.tools.zeroToFalse(-5));   // -5
+
+// Useful in form validation
+const count = 0;
+if (dphelper.tools.zeroToFalse(count)) {
+  console.log('Count is valid');
+} else {
+  console.log('Count is zero or invalid');
+}
+```
+
+## Advanced Usage
+
+### Creating a File Size Display Component
+
+```javascript
+function formatFileSize(bytes) {
+  return dphelper.tools.byteSize(bytes);
+}
+
+// Display various file sizes
+const files = [256, 1024, 1024 * 50, 1024 * 1024, 1024 * 1024 * 2];
+files.forEach(size => {
+  console.log(`${size} bytes = ${formatFileSize(size)}`);
+});
+```
+
+### Modal Management
+
+```javascript
+function openModal(content) {
+  const highestZ = dphelper.tools.zIndex();
+  const modal = document.createElement('div');
+  modal.className = 'modal-overlay';
+  modal.style.zIndex = highestZ + 1;
+  modal.innerHTML = content;
+  document.body.appendChild(modal);
+  return modal;
+}
+```
+
+## 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/translators.md

@@ -0,0 +1,65 @@
+# translators
+
+Utilities for transformation conversions.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `convertMatrixToScale` | Convert CSS matrix to scale values | `dphelper.translators.convertMatrixToScale(matrix)` |
+
+## Description
+
+CSS transformation utilities:
+- **Matrix to Scale** - Parse CSS transform matrix
+- **Extract Values** - Get scaleX, scaleY from matrix
+
+## Usage Examples
+
+### Convert Matrix to Scale
+
+```javascript
+// Get element's transform matrix
+const element = document.getElementById('myElement');
+const style = window.getComputedStyle(element);
+const matrix = style.transform;
+
+// Convert matrix to scale values
+const scale = dphelper.translators.convertMatrixToScale({ value: matrix });
+// Returns { scaleX, scaleY }
+
+// Example with known matrix
+const result = dphelper.translators.convertMatrixToScale({
+  value: 'matrix(2, 0, 0, 2, 0, 0)'
+});
+// { scaleX: 2, scaleY: 2 }
+```
+
+### Animation Scaling
+
+```javascript
+// Track element scale during animation
+function getScale(element) {
+  const style = window.getComputedStyle(element);
+  return dphelper.translators.convertMatrixToScale({ value: style.transform });
+}
+
+// Monitor scale changes
+const element = document.querySelector('.scaling-element');
+setInterval(() => {
+  const scale = getScale(element);
+  console.log(`Current scale: ${scale.scaleX}x${scale.scaleY}`);
+}, 100);
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/trigger.md

@@ -0,0 +1,99 @@
+# trigger
+
+Programmatic DOM event triggers.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `click` | Trigger click event | `dphelper.trigger.click(element)` |
+| `change` | Trigger change event | `dphelper.trigger.change(element)` |
+| `input` | Trigger input event | `dphelper.trigger.input(element)` |
+
+## Description
+
+Programmatic event triggering:
+- **Click** - Simulate user clicks
+- **Change** - Trigger value change events
+- **Input** - Trigger input events
+- **Testing** - Useful for automated testing
+
+## Usage Examples
+
+### Trigger Click
+
+```javascript
+// Click an element
+const button = document.getElementById('submit');
+dphelper.trigger.click(button);
+
+// Click first element in collection
+const links = document.querySelectorAll('.nav-link');
+if (links.length > 0) {
+  dphelper.trigger.click(links[0]);
+}
+```
+
+### Trigger Change
+
+```javascript
+// Trigger change on input
+const input = document.getElementById('username');
+input.value = 'newvalue';
+dphelper.trigger.change(input);
+
+// Trigger change on select
+const select = document.getElementById('country');
+select.value = 'US';
+dphelper.trigger.change(select);
+```
+
+### Trigger Input
+
+```javascript
+// Trigger input event
+const input = document.getElementById('search');
+input.value = 'search term';
+dphelper.trigger.input(input);
+
+// For autocomplete/typeahead
+function simulateTyping(element, text) {
+  element.value = '';
+  text.split('').forEach((char, i) => {
+    element.value += char;
+    dphelper.trigger.input(element);
+  });
+}
+```
+
+### Form Automation
+
+```javascript
+// Fill and submit form programmatically
+function fillForm(data) {
+  Object.entries(data).forEach(([field, value]) => {
+    const input = document.querySelector(`[name="${field}"]`);
+    if (input) {
+      input.value = value;
+      dphelper.trigger.input(input);
+      dphelper.trigger.change(input);
+    }
+  });
+
+  // Submit
+  const submitBtn = document.querySelector('button[type="submit"]');
+  dphelper.trigger.click(submitBtn);
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20241001
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*