@vived/core 2.0.1 → 2.0.2

package/src/Utilities/README.md

@@ -0,0 +1,478 @@
+# Utilities
+
+The Utilities folder provides a collection of general-purpose helper functions for common programming tasks. These utilities cover color manipulation, animations, unit conversions, file operations, and mathematical transformations.
+
+## Overview
+
+Utilities are standalone functions that:
+- **Have no dependencies** on other application features
+- **Solve specific problems** with a focused API
+- **Are highly reusable** across different contexts
+- **Include proper validation** with warnings for invalid inputs
+
+## Animation & Interpolation
+
+### LerpNumber
+
+Smooth animation class for interpolating numeric values over time using `requestAnimationFrame`.
+
+```typescript
+import { LerpNumber, quintInOut } from "@vived/core";
+
+const lerper = new LerpNumber();
+
+// Set defaults (optional)
+lerper.defaultDurationMS = 1000;
+lerper.defaultEase = quintInOut;
+
+// Animate from 0 to 100 over 2 seconds
+await lerper.lerp({
+	start: 0,
+	end: 100,
+	durationMS: 2000,
+	update: (value) => {
+		console.log(`Current value: ${value}`);
+	},
+	onComplete: () => {
+		console.log("Animation complete!");
+	}
+});
+
+// With custom easing
+await lerper.lerp({
+	start: 0,
+	end: 100,
+	ease: quadInOut,
+	update: (value) => updateUI(value)
+});
+
+// Cancel animation
+if (lerper.isLerping)
+{
+	lerper.cancel();
+}
+```
+
+**Configuration Options:**
+- `start` - Starting value
+- `end` - Target value
+- `update` - Callback receiving interpolated values
+- `durationMS` - Animation duration (default: 1000ms)
+- `ease` - Easing function (default: quintInOut)
+- `onComplete` - Called when animation completes naturally
+- `onCancel` - Called when animation is cancelled
+
+### Easing Functions
+
+Comprehensive collection of easing functions for smooth animations. All functions accept input from 0-1 and return output from 0-1, with automatic clamping.
+
+```typescript
+import {
+	easeLinear,
+	quadIn, quadOut, quadInOut,
+	cubicIn, cubicOut, cubicInOut,
+	quartIn, quartOut, quartInOut,
+	quintIn, quintOut, quintInOut,
+	sinIn, sinOut, sinInOut,
+	expoIn, expoOut, expoInOut,
+	circIn, circOut, circInOut
+} from "@vived/core";
+
+// Linear (constant speed)
+const linear = easeLinear(0.5); // 0.5
+
+// Quadratic (x²)
+const easeIn = quadIn(0.5); // 0.25
+const easeOut = quadOut(0.5); // 0.75
+const easeInOut = quadInOut(0.5); // 0.5
+
+// Cubic (x³)
+const cubic = cubicInOut(0.5);
+
+// Quartic (x⁴)
+const quart = quartInOut(0.5);
+
+// Quintic (x⁵)
+const quint = quintInOut(0.5);
+
+// Sine wave
+const sine = sinInOut(0.5);
+
+// Exponential
+const expo = expoInOut(0.5);
+
+// Circular
+const circ = circInOut(0.5);
+
+// Use with animations
+const progress = 0.5; // 50% through animation
+const easedProgress = quintInOut(progress);
+const currentValue = start + (end - start) * easedProgress;
+```
+
+**Easing Types:**
+- **In** - Slow start, accelerating
+- **Out** - Fast start, decelerating
+- **InOut** - Slow start and end, fast middle
+
+**Available Easings:**
+- `easeLinear` - No easing
+- `quad*` - Quadratic (power of 2)
+- `cubic*` - Cubic (power of 3)
+- `quart*` - Quartic (power of 4)
+- `quint*` - Quintic (power of 5)
+- `sin*` - Sine wave
+- `expo*` - Exponential
+- `circ*` - Circular
+
+### interpolateNumber
+
+Basic numeric interpolation with optional clamping.
+
+```typescript
+import { interpolateNumber } from "@vived/core";
+
+// Basic interpolation
+const value = interpolateNumber(0, 100, 0.5); // 50
+
+// Allow values outside range
+const unclamped = interpolateNumber(0, 100, 1.5); // 150
+
+// Clamp to 0-1 range
+const clamped = interpolateNumber(0, 100, 1.5, true); // 100
+
+// Negative percent
+const negative = interpolateNumber(0, 100, -0.5); // -50
+const clampedNeg = interpolateNumber(0, 100, -0.5, true); // 0
+```
+
+## Color Utilities
+
+### addAlphaToHex
+
+Add an alpha channel to a hex color code.
+
+```typescript
+import { addAlphaToHex } from "@vived/core";
+
+// Full hex with alpha
+const color1 = addAlphaToHex("#ffffff", 0.5); // "#ffffff80"
+const color2 = addAlphaToHex("#ff0000", 1); // "#ff0000ff"
+const color3 = addAlphaToHex("#000000", 0); // "#00000000"
+
+// Short hex (automatically expanded)
+const color4 = addAlphaToHex("#fff", 0.5); // "#ffffff80"
+const color5 = addAlphaToHex("#f00", 0.25); // "#ff000040"
+
+// Invalid hex returns "#000" with warning
+const invalid = addAlphaToHex("#gggggg", 0.5); // "#000"
+const invalid2 = addAlphaToHex("ffffff", 0.5); // "#000" (missing #)
+```
+
+**Alpha Values:**
+- `0` - Fully transparent
+- `0.5` - Semi-transparent
+- `1` - Fully opaque
+
+### alphaToHex
+
+Convert alpha value (0-1) to hex string.
+
+```typescript
+import { alphaToHex } from "@vived/core";
+
+const hex1 = alphaToHex(1); // "ff"
+const hex2 = alphaToHex(0.5); // "80"
+const hex3 = alphaToHex(0); // "00"
+const hex4 = alphaToHex(0.25); // "40"
+
+// Out of range returns "00" with warning
+const invalid = alphaToHex(1.5); // "00"
+const invalid2 = alphaToHex(-0.1); // "00"
+```
+
+## Mathematical Conversions
+
+### degreesToRadians
+
+Convert degrees to radians.
+
+```typescript
+import { degreesToRadians } from "@vived/core";
+
+const rad1 = degreesToRadians(180); // ~3.14159 (π)
+const rad2 = degreesToRadians(90); // ~1.5708 (π/2)
+const rad3 = degreesToRadians(45); // ~0.7854 (π/4)
+const rad4 = degreesToRadians(0); // 0
+```
+
+### Length Converters
+
+Convert between metric and imperial units.
+
+```typescript
+import {
+	inchesToMeters,
+	metersToInches,
+	feetToMeters,
+	metersToFeet
+} from "@vived/core";
+
+// Inches ↔ Meters
+const meters1 = inchesToMeters(39.37); // ~1
+const inches = metersToInches(1); // ~39.37
+
+// Feet ↔ Meters
+const meters2 = feetToMeters(3.28); // ~1
+const feet = metersToFeet(1); // ~3.28
+
+// Practical examples
+const screenWidth = 27; // inches
+const screenWidthM = inchesToMeters(screenWidth); // ~0.686 meters
+
+const roomLength = 5; // meters
+const roomLengthFt = metersToFeet(roomLength); // ~16.4 feet
+```
+
+**Conversion Factors:**
+- 1 meter = 39.3701 inches
+- 1 meter = 3.28084 feet
+
+## File Operations
+
+### downloadFile
+
+Trigger a browser download for a Blob.
+
+```typescript
+import { downloadFile } from "@vived/core";
+
+// Download text file
+const textBlob = new Blob(["Hello World"], { type: "text/plain" });
+downloadFile("hello.txt", textBlob);
+
+// Download JSON
+const data = { name: "John", age: 30 };
+const jsonBlob = new Blob([JSON.stringify(data)], { type: "application/json" });
+downloadFile("data.json", jsonBlob);
+
+// Download image
+const canvas = document.getElementById("myCanvas") as HTMLCanvasElement;
+canvas.toBlob((blob) => {
+	if (blob)
+	{
+		downloadFile("image.png", blob);
+	}
+});
+
+// Download CSV
+const csvContent = "Name,Age\nJohn,30\nJane,25";
+const csvBlob = new Blob([csvContent], { type: "text/csv" });
+downloadFile("data.csv", csvBlob);
+```
+
+**How it works:**
+1. Creates a temporary anchor element
+2. Creates an object URL from the Blob
+3. Triggers a download
+4. Cleans up the anchor and URL
+
+## ID Generation
+
+### generateUniqueID
+
+Generate a universally unique identifier (UUID v4).
+
+```typescript
+import { generateUniqueID } from "@vived/core";
+
+const id1 = generateUniqueID(); // "a3bb189e-8bf9-3888-9912-ace4e6543002"
+const id2 = generateUniqueID(); // "f8e7d5c6-9a4b-4c5d-8e6f-7a8b9c0d1e2f"
+
+// Use for entity IDs
+const userId = generateUniqueID();
+const sessionId = generateUniqueID();
+
+// Use for tracking
+const eventId = generateUniqueID();
+const transactionId = generateUniqueID();
+```
+
+**Properties:**
+- RFC 4122 compliant UUID v4
+- 122 bits of randomness
+- Extremely low collision probability
+- Safe for distributed systems
+
+## Usage Patterns
+
+### Smooth Property Animation
+
+```typescript
+import { LerpNumber, quintInOut } from "@vived/core";
+
+class AnimatedObject
+{
+	private lerper = new LerpNumber();
+	private _opacity = 1;
+
+	async fadeOut()
+	{
+		await this.lerper.lerp({
+			start: this._opacity,
+			end: 0,
+			durationMS: 500,
+			ease: quintInOut,
+			update: (value) => {
+				this._opacity = value;
+				this.render();
+			}
+		});
+	}
+
+	async fadeIn()
+	{
+		await this.lerper.lerp({
+			start: this._opacity,
+			end: 1,
+			durationMS: 500,
+			ease: quintInOut,
+			update: (value) => {
+				this._opacity = value;
+				this.render();
+			}
+		});
+	}
+
+	render()
+	{
+		// Update visual representation
+	}
+}
+```
+
+### Color with Transparency
+
+```typescript
+import { addAlphaToHex } from "@vived/core";
+
+function createOverlay(baseColor: string, opacity: number): string
+{
+	return addAlphaToHex(baseColor, opacity);
+}
+
+const overlay = createOverlay("#000000", 0.7); // Semi-transparent black
+document.body.style.backgroundColor = overlay;
+```
+
+### Unit Conversion in VR
+
+```typescript
+import { feetToMeters, metersToFeet } from "@vived/core";
+
+class VRRoom
+{
+	// User inputs in feet
+	setDimensions(widthFeet: number, heightFeet: number, depthFeet: number)
+	{
+		// Convert to meters for internal use
+		this.width = feetToMeters(widthFeet);
+		this.height = feetToMeters(heightFeet);
+		this.depth = feetToMeters(depthFeet);
+	}
+
+	// Display in feet for user
+	getDimensionsDisplay(): string
+	{
+		const w = metersToFeet(this.width).toFixed(1);
+		const h = metersToFeet(this.height).toFixed(1);
+		const d = metersToFeet(this.depth).toFixed(1);
+		return `${w}' × ${h}' × ${d}'`;
+	}
+
+	private width = 0;
+	private height = 0;
+	private depth = 0;
+}
+```
+
+### Export Application Data
+
+```typescript
+import { downloadFile, generateUniqueID } from "@vived/core";
+
+function exportUserData(userData: any)
+{
+	const exportData = {
+		id: generateUniqueID(),
+		timestamp: new Date().toISOString(),
+		data: userData
+	};
+
+	const json = JSON.stringify(exportData, null, 2);
+	const blob = new Blob([json], { type: "application/json" });
+	downloadFile(`export-${Date.now()}.json`, blob);
+}
+```
+
+### Custom Easing with Interpolation
+
+```typescript
+import { interpolateNumber, expoOut } from "@vived/core";
+
+function animateWithEasing(
+	start: number,
+	end: number,
+	progress: number
+): number
+{
+	const easedProgress = expoOut(progress);
+	return interpolateNumber(start, end, easedProgress);
+}
+
+// Use in animation loop
+let progress = 0;
+const interval = setInterval(() => {
+	progress += 0.01;
+	const value = animateWithEasing(0, 100, progress);
+	updateUI(value);
+
+	if (progress >= 1)
+	{
+		clearInterval(interval);
+	}
+}, 16); // ~60fps
+```
+
+## Validation & Error Handling
+
+Most utilities include validation with console warnings:
+
+```typescript
+// Invalid hex returns fallback with warning
+addAlphaToHex("invalid", 0.5); // "#000" + console.warn()
+
+// Out of range returns fallback with warning
+alphaToHex(1.5); // "00" + console.warn()
+
+// Interpolation with clamping prevents out-of-range
+interpolateNumber(0, 100, 1.5, true); // 100 (clamped)
+```
+
+## Performance Considerations
+
+- **LerpNumber** - Uses `requestAnimationFrame` for smooth animations aligned with browser repaints
+- **Easing functions** - Optimized mathematical operations with early returns for edge cases
+- **UUID generation** - Uses native crypto APIs for secure random numbers
+- **Interpolation** - Simple arithmetic operations with minimal overhead
+- **Color conversion** - String operations are lightweight but use sparingly in tight loops
+
+## Use Cases
+
+- **UI Animations** - Smooth transitions for opacity, position, scale
+- **Color Manipulation** - Dynamic theming with transparency
+- **Data Export** - Download user-generated content or reports
+- **Unit Conversion** - VR/AR applications with real-world measurements
+- **Game Development** - Custom easing curves for game feel
+- **Entity Management** - Unique IDs for tracking objects
+- **Chart Animations** - Smooth value changes in data visualizations