dphelper 3.7.1 → 3.7.2

package/docs/markdown/i18n.md

@@ -0,0 +1,292 @@
+# i18n
+
+Internationalization and localization utilities for multi-language support, including translations, pluralization, date/number formatting, and relative time.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `setLocale` | Set current locale | `dphelper.i18n.setLocale('it')` |
+| `getLocale` | Get current locale | `dphelper.i18n.getLocale()` |
+| `t` | Translate a key | `dphelper.i18n.t('hello', { name: 'World' })` |
+| `addTranslations` | Add translation strings | `dphelper.i18n.addTranslations('it', { hello: 'Ciao!' })` |
+| `pluralize` | Get pluralized string | `dphelper.i18n.pluralize(5, { one: 'item', other: 'items' })` |
+| `number` | Format number by locale | `dphelper.i18n.number(1234.56, 'de-DE', { currency: 'EUR' })` |
+| `date` | Format date by locale | `dphelper.i18n.date(new Date(), 'en-US', { dateStyle: 'long' })` |
+| `relativeTime` | Get relative time string | `dphelper.i18n.relativeTime(Date.now() - 3600000)` |
+| `list` | Format list by locale | `dphelper.i18n.list(['a', 'b', 'c'], 'en')` |
+| `getSupportedLocales` | Get list of locales | `dphelper.i18n.getSupportedLocales()` |
+
+## Description
+
+Complete internationalization module featuring:
+- **Translation System** - Key-based translations with variable interpolation
+- **Pluralization** - Support for multiple plural forms (zero, one, two, few, many, other)
+- **Locale-aware Formatting** - Numbers, dates, and lists formatted per locale
+- **Relative Time** - "2 hours ago", "in 5 minutes" style strings
+- **Auto-detection** - Automatic browser locale detection
+- **Extensible** - Add custom translations for any language
+
+## Usage Examples
+
+### Basic Translation
+
+```javascript
+// Set locale
+dphelper.i18n.setLocale('en');
+
+// Simple translation
+console.log(dphelper.i18n.t('hello')); // "Hello {name}!"
+console.log(dphelper.i18n.t('hello', { name: 'World' })); // "Hello World!"
+console.log(dphelper.i18n.t('goodbye')); // "Goodbye!"
+
+// Change locale
+dphelper.i18n.setLocale('it');
+console.log(dphelper.i18n.t('hello', { name: 'Mario' })); // "Ciao Mario!"
+```
+
+### Adding Custom Translations
+
+```javascript
+// Add Italian translations
+dphelper.i18n.addTranslations('it', {
+  'hello': 'Ciao {name}!',
+  'goodbye': 'Arrivederci!',
+  'welcome': 'Benvenuto nella nostra app!',
+  'items_count': 'Hai {count} oggetti'
+});
+
+// Add Spanish translations
+dphelper.i18n.addTranslations('es', {
+  'hello': '¡Hola {name}!',
+  'goodbye': '¡Adiós!',
+  'welcome': '¡Bienvenido a nuestra aplicación!'
+});
+
+// Use translations
+dphelper.i18n.setLocale('es');
+console.log(dphelper.i18n.t('welcome')); // "¡Bienvenido a nuestra aplicación!"
+```
+
+### Pluralization
+
+```javascript
+dphelper.i18n.setLocale('en');
+
+// Basic pluralization
+console.log(dphelper.i18n.pluralize(0, { one: 'item', other: 'items' }));
+// "items" (uses 'other' for 0 in English)
+
+console.log(dphelper.i18n.pluralize(1, { one: 'item', other: 'items' }));
+// "item"
+
+console.log(dphelper.i18n.pluralize(5, { one: 'item', other: 'items' }));
+// "items"
+
+// With translation keys
+dphelper.i18n.addTranslations('en', {
+  'items': '{count} item',
+  'items_plural': '{count} items'
+});
+
+// In a message
+const count = 10;
+const message = count === 1
+  ? dphelper.i18n.t('items', { count })
+  : dphelper.i18n.t('items_plural', { count });
+```
+
+### Number Formatting
+
+```javascript
+dphelper.i18n.setLocale('en-US');
+
+// Basic number formatting
+console.log(dphelper.i18n.number(1234.56)); // "1,234.56"
+
+// Currency
+console.log(dphelper.i18n.number(1234.56, 'en-US', {
+  style: 'currency',
+  currency: 'USD'
+})); // "$1,234.56"
+
+console.log(dphelper.i18n.number(1234.56, 'de-DE', {
+  style: 'currency',
+  currency: 'EUR'
+})); // "1.234,56 €"
+
+// Percentages
+console.log(dphelper.i18n.number(0.75, 'en-US', { style: 'percent' })); // "75%"
+
+// Different locales
+console.log(dphelper.i18n.number(1234.56, 'ja-JP')); // "1,234.56"
+console.log(dphelper.i18n.number(1234.56, 'fr-FR')); // "1 234,56"
+```
+
+### Date Formatting
+
+```javascript
+const date = new Date('2026-03-15T14:30:00Z');
+
+// Date only
+console.log(dphelper.i18n.date(date, 'en-US', { dateStyle: 'short' }));
+// "3/15/2026"
+
+console.log(dphelper.i18n.date(date, 'en-US', { dateStyle: 'long' }));
+// "March 15, 2026"
+
+// Time only
+console.log(dphelper.i18n.date(date, 'en-US', { timeStyle: 'short' }));
+// "2:30 PM"
+
+// Full date and time
+console.log(dphelper.i18n.date(date, 'it-IT', {
+  dateStyle: 'full',
+  timeStyle: 'short' }));
+// "domenica 15 marzo 2026, 14:30"
+
+// Custom format
+console.log(dphelper.i18n.date(date, 'en-GB', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric'
+})); // "15 March 2026"
+```
+
+### Relative Time
+
+```javascript
+const now = Date.now();
+
+// Past
+console.log(dphelper.i18n.relativeTime(now - 60000)); // "1 minute ago"
+console.log(dphelper.i18n.relativeTime(now - 3600000)); // "1 hour ago"
+console.log(dphelper.i18n.relativeTime(now - 86400000)); // "1 day ago"
+
+// Future
+console.log(dphelper.i18n.relativeTime(now + 60000)); // "in 1 minute"
+console.log(dphelper.i18n.relativeTime(now + 3600000)); // "in 1 hour"
+
+// With locale
+console.log(dphelper.i18n.relativeTime(now - 3600000, 'es')); // "hace 1 hora"
+console.log(dphelper.i18n.relativeTime(now + 3600000, 'es')); // "dentro de 1 hora"
+```
+
+### List Formatting
+
+```javascript
+const items = ['Apple', 'Banana', 'Orange'];
+
+// Basic list
+console.log(dphelper.i18n.list(items, 'en'));
+// "Apple, Banana, and Orange"
+
+console.log(dphelper.i18n.list(items, 'it'));
+// "Apple, Banana e Orange"
+
+// With options
+console.log(dphelper.i18n.list(items, 'en', { type: 'disjunction' }));
+// "Apple, Banana, or Orange"
+```
+
+## Advanced Usage
+
+### Complete i18n Setup
+
+```javascript
+// Initialize i18n with custom translations
+function initI18n(locale) {
+  // Set locale
+  dphelper.i18n.setLocale(locale);
+
+  // Add translations for common strings
+  dphelper.i18n.addTranslations(locale, {
+    'app.name': 'My Application',
+    'app.tagline': 'Building the future',
+    'nav.home': 'Home',
+    'nav.about': 'About',
+    'nav.contact': 'Contact',
+    'common.save': 'Save',
+    'common.cancel': 'Cancel',
+    'common.delete': 'Delete',
+    'common.loading': 'Loading...',
+    'error.generic': 'An error occurred',
+    'error.network': 'Network error. Please try again.',
+    'user.greeting': 'Welcome, {name}!',
+    'items.count': '{count, plural, =0{No items} one{# item} other{# items}}'
+  });
+}
+
+// Usage
+initI18n('en');
+console.log(dphelper.i18n.t('user.greeting', { name: 'John' }));
+```
+
+### Dynamic Locale Switching
+
+```javascript
+class I18nManager {
+  constructor() {
+    this.locale = 'en';
+  }
+
+  async setLocale(locale) {
+    // Fetch translations from server
+    const translations = await fetch(`/api/translations/${locale}`)
+      .then(r => r.json());
+
+    // Add translations
+    dphelper.i18n.addTranslations(locale, translations);
+
+    // Set locale
+    dphelper.i18n.setLocale(locale);
+    this.locale = locale;
+
+    // Dispatch event for UI update
+    window.dispatchEvent(new CustomEvent('localechange', { detail: { locale } }));
+  }
+
+  t(key, vars) {
+    return dphelper.i18n.t(key, vars);
+  }
+
+  formatNumber(value, options) {
+    return dphelper.i18n.number(value, this.locale, options);
+  }
+
+  formatDate(date, options) {
+    return dphelper.i18n.date(date, this.locale, options);
+  }
+}
+
+const i18n = new I18nManager();
+```
+
+### React-like Translation Component
+
+```javascript
+// Simple translation helper for templates
+function tr(key, vars) {
+  return dphelper.i18n.t(key, vars);
+}
+
+// Usage in templates
+const template = `
+  <h1>${tr('app.name')}</h1>
+  <p>${tr('user.greeting', { name: userName })}</p>
+  <p>${tr('items.count', { count: itemCount })}</p>
+  <p>${tr('common.lastUpdated', { date: dphelper.i18n.date(lastUpdate) })}</p>
+`;
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20260313
+- **Last Modified:** 20260313
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/image.md

@@ -0,0 +1,298 @@
+# image
+
+Comprehensive image processing utilities for client-side image manipulation, including resize, crop, rotate, flip, filters, and format conversion.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `resize` | Resize image to dimensions | `dphelper.image.resize(img, 100, 100)` |
+| `crop` | Crop image to region | `dphelper.image.crop(img, { x: 0, y: 0, width: 100, height: 100 })` |
+| `toDataURL` | Convert to data URL | `dphelper.image.toDataURL(img, 'image/webp', 0.8)` |
+| `fromDataURL` | Create image from data URL | `dphelper.image.fromDataURL(dataUrl)` |
+| `filter` | Apply CSS filters | `dphelper.image.filter(img, { brightness: 1.2, contrast: 1.1 })` |
+| `rotate` | Rotate image by degrees | `dphelper.image.rotate(img, 90)` |
+| `flip` | Flip horizontally/vertically | `dphelper.image.flip(img, 'horizontal')` |
+| `grayscale` | Convert to grayscale | `dphelper.image.grayscale(img)` |
+| `blur` | Apply blur effect | `dphelper.image.blur(img, 5)` |
+| `getDimensions` | Get image dimensions | `dphelper.image.getDimensions(img)` |
+| `load` | Load image from URL | `dphelper.image.load('image.jpg')` |
+| `composite` | Composite two images | `dphelper.image.composite(img1, img2, 'multiply')` |
+
+## Description
+
+Powerful client-side image processing module providing:
+- **Resize & Crop** - Precise dimension control with quality options
+- **Rotation & Flipping** - Rotate by degrees, flip horizontally or vertically
+- **Filters** - Brightness, contrast, saturation, hue, blur, sepia, and more
+- **Format Conversion** - Convert between PNG, JPEG, WebP with quality control
+- **Compositing** - Blend multiple images with different blend modes
+- **Canvas-based** - All operations use HTML5 Canvas for performance
+
+## Usage Examples
+
+### Loading Images
+
+```javascript
+// Load image from URL
+const img = await dphelper.image.load('photo.jpg');
+console.log(dphelper.image.getDimensions(img));
+// { width: 1920, height: 1080 }
+
+// Load from different source
+const img2 = await dphelper.image.load('https://example.com/image.png');
+```
+
+### Resize & Crop
+
+```javascript
+const img = await dphelper.image.load('photo.jpg');
+
+// Resize to specific dimensions
+const thumb = dphelper.image.resize(img, 150, 150);
+document.getElementById('thumbnail').src = thumb;
+
+// Resize with pixelated (nearest neighbor) quality
+const pixelArt = dphelper.image.resize(img, 32, 32, 'pixelated');
+document.getElementById('sprite').src = pixelArt;
+
+// Crop to region
+const cropped = dphelper.image.crop(img, {
+  x: 100,
+  y: 100,
+  width: 200,
+  height: 200
+});
+document.getElementById('cropped').src = cropped;
+```
+
+### Rotation & Flipping
+
+```javascript
+const img = await dphelper.image.load('photo.jpg');
+
+// Rotate 90 degrees clockwise
+const rotated90 = dphelper.image.rotate(img, 90);
+document.getElementById('rotated').src = rotated90;
+
+// Rotate 45 degrees
+const rotated45 = dphelper.image.rotate(img, 45);
+
+// Flip horizontally
+const flippedH = dphelper.image.flip(img, 'horizontal');
+
+// Flip vertically
+const flippedV = dphelper.image.flip(img, 'vertical');
+```
+
+### Applying Filters
+
+```javascript
+const img = await dphelper.image.load('photo.jpg');
+
+// Brightness adjustment (1 = normal, 0.5 = darker, 1.5 = brighter)
+const brightened = dphelper.image.filter(img, { brightness: 1.3 });
+
+// Contrast adjustment
+const contrasted = dphelper.image.filter(img, { contrast: 1.2 });
+
+// Saturation
+const saturated = dphelper.image.filter(img, { saturate: 1.5 });
+const desaturated = dphelper.image.filter(img, { saturate: 0.3 });
+
+// Hue rotation (degrees)
+const hueShifted = dphelper.image.filter(img, { hueRotate: 90 });
+
+// Blur (pixels)
+const blurred = dphelper.image.filter(img, { blur: 5 });
+
+// Sepia effect
+const sepia = dphelper.image.filter(img, { sepia: 1 });
+
+// Invert colors
+const inverted = dphelper.image.filter(img, { invert: 1 });
+
+// Grayscale
+const gray = dphelper.image.filter(img, { grayscale: 1 });
+
+// Combined filters
+const vintage = dphelper.image.filter(img, {
+  brightness: 1.1,
+  contrast: 1.2,
+  sepia: 0.3
+});
+```
+
+### Format Conversion
+
+```javascript
+const img = await dphelper.image.load('photo.png');
+
+// Convert to JPEG with quality
+const jpeg80 = dphelper.image.toDataURL(img, 'image/jpeg', 0.8);
+const jpeg50 = dphelper.image.toDataURL(img, 'image/jpeg', 0.5);
+
+// Convert to WebP (better compression)
+const webp = dphelper.image.toDataURL(img, 'image/webp', 0.9);
+
+// Keep as PNG (lossless)
+const png = dphelper.image.toDataURL(img, 'image/png', 1);
+```
+
+### Image Compositing
+
+```javascript
+const img1 = await dphelper.image.load('background.jpg');
+const img2 = await dphelper.image.load('overlay.png');
+
+// Overlay with normal blending
+const normal = dphelper.image.composite(img1, img2, 'source-over', 0, 0);
+
+// Multiply blend (for shadows/overlays)
+const multiplied = dphelper.image.composite(img1, img2, 'multiply', 50, 50);
+
+// Screen blend (for light effects)
+const screened = dphelper.image.composite(img1, img2, 'screen', 0, 0);
+
+// Overlay blend
+const overlaid = dphelper.image.composite(img1, img2, 'overlay', 0, 0);
+```
+
+## Advanced Usage
+
+### Thumbnail Generator
+
+```javascript
+async function generateThumbnail(file, maxSize = 150) {
+  // Load the uploaded file
+  const dataUrl = await readFileAsDataURL(file);
+  const img = await dphelper.image.fromDataURL(dataUrl);
+
+  // Get original dimensions
+  const { width, height } = dphelper.image.getDimensions(img);
+
+  // Calculate new dimensions (maintain aspect ratio)
+  let newWidth, newHeight;
+  if (width > height) {
+    newWidth = maxSize;
+    newHeight = (height / width) * maxSize;
+  } else {
+    newHeight = maxSize;
+    newWidth = (width / height) * maxSize;
+  }
+
+  // Resize and convert to JPEG
+  const thumbnail = dphelper.image.resize(img, newWidth, newHeight);
+  return dphelper.image.toDataURL(thumbnail, 'image/jpeg', 0.8);
+}
+
+// Helper to read file as data URL
+function readFileAsDataURL(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+}
+
+// Usage
+document.querySelector('input[type="file"]').addEventListener('change', async (e) => {
+  const thumbnail = await generateThumbnail(e.target.files[0]);
+  document.getElementById('preview').src = thumbnail;
+});
+```
+
+### Image Editor
+
+```javascript
+class ImageEditor {
+  constructor(imageElement) {
+    this.img = imageElement;
+    this.history = [];
+  }
+
+  async applyFilter(options) {
+    const result = dphelper.image.filter(this.img, options);
+    this.history.push(result);
+    return result;
+  }
+
+  async resize(width, height) {
+    const result = dphelper.image.resize(this.img, width, height);
+    this.history.push(result);
+    return result;
+  }
+
+  async rotate(degrees) {
+    const result = dphelper.image.rotate(this.img, degrees);
+    this.history.push(result);
+    return result;
+  }
+
+  async crop(region) {
+    const result = dphelper.image.crop(this.img, region);
+    this.history.push(result);
+    return result;
+  }
+
+  async undo() {
+    if (this.history.length > 0) {
+      const prev = this.history.pop();
+      this.img = await dphelper.image.fromDataURL(prev);
+    }
+    return this.img;
+  }
+
+  async export(format = 'image/png', quality = 0.92) {
+    return dphelper.image.toDataURL(this.img, format, quality);
+  }
+}
+
+// Usage
+const editor = new ImageEditor(document.getElementById('original'));
+const filtered = await editor.applyFilter({ brightness: 1.2, contrast: 1.1 });
+document.getElementById('result').src = filtered;
+```
+
+### Profile Picture Processor
+
+```javascript
+async function processProfilePicture(file) {
+  const dataUrl = await readFileAsDataURL(file);
+  const img = await dphelper.image.fromDataURL(dataUrl);
+
+  // Get dimensions
+  const { width, height } = dphelper.image.getDimensions(img);
+
+  // Calculate square crop (center)
+  const size = Math.min(width, height);
+  const x = (width - size) / 2;
+  const y = (height - size) / 2;
+
+  // Crop to square
+  const cropped = dphelper.image.crop(img, { x, y, width: size, height: size });
+
+  // Resize to standard profile size
+  const resized = dphelper.image.resize(
+    await dphelper.image.fromDataURL(cropped),
+    200,
+    200
+  );
+
+  // Convert to JPEG with good quality
+  return dphelper.image.toDataURL(resized, 'image/jpeg', 0.9);
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20260313
+- **Last Modified:** 20260313
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*