tiny-essentials 1.25.0 → 1.25.1

package/docs/v1/libs/TinyAnalogClock.md

@@ -0,0 +1,295 @@
+# 🕰️ TinyAnalogClock
+
+**TinyAnalogClock** is a dependency-free JavaScript class for rendering fully customizable analog clocks. It supports dynamic resizing, custom skins (background images), flexible coloring, advanced geometry tuning, and rigorous input validation.
+
+## ✨ Features
+
+* **Zero Dependencies:** Pure JavaScript (ESM).
+* **Fully Customizable:** Control colors, sizes, layout, and internal geometry.
+* **Scalable:** All internal elements (hands, numbers, ticks) scale mathematically based on the `size`.
+* **Dynamic API:** Update **any** property (colors, padding, tick thickness, etc.) in real-time using setters.
+* **Type Safe:** Built-in validation throws errors if invalid data types are passed.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Import the Class
+
+Import the class into your JavaScript module.
+
+```javascript
+import TinyAnalogClock from './TinyAnalogClock.js';
+```
+
+### 2. Basic Usage
+
+Create an instance and append its element to your DOM.
+
+```javascript
+// 1. Create the clock instance
+const myClock = new TinyAnalogClock({
+    size: 400,
+    showSeconds: true
+});
+
+// 2. Append the generated HTML to your page
+document.body.appendChild(myClock.element);
+
+```
+
+---
+
+## ⚙️ Configuration
+
+You can pass an options object to the **constructor**. All properties are optional; defaults will be used if omitted.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `number` | `800` | Total width/height of the clock in pixels. |
+| `bgColor` | `string` | `'#f0f0f0'` | Background color of the clock face. |
+| `borderColor` | `string` | `'#333'` | Color of the outer border. |
+| `borderWidth` | `number` | `8` | Thickness of the outer border in pixels. |
+| `markColor` | `string` | `'#333'` | Color of the minute/hour tick marks. |
+| `textColor` | `string` | `'#000'` | Color of the numbers (1-12). |
+| `hourHandColor` | `string` | `'#000'` | Color of the hour hand. |
+| `minuteHandColor` | `string` | `'#444'` | Color of the minute hand. |
+| `secondHandColor` | `string` | `'#d81c1c'` | Color of the second hand. |
+| `skinUrl` | `string|null` | `null` | URL of an image to use as background. |
+| `showNumbers` | `boolean` | `true` | Show/Hide numbers on the face. |
+| `showSeconds` | `boolean` | `true` | Show/Hide the second hand. |
+| `padding` | `number` | `45` | Padding in pixels between the clock edge and the tick marks. |
+| `sizeAdjust` | `number` | `0.04` | Scale factor for the numbers font size relative to clock size. |
+| `angleDistance` | `number` | `0.95` | Distance multiplier (0-1) for placing numbers relative to the radius. |
+| `pwH` | `number` | `0.008` | Hour tick **width** as a percentage of clock size (0.0 - 1.0). |
+| `phH` | `number` | `0.08` | Hour tick **height** as a percentage of clock size (0.0 - 1.0). |
+| `pwM` | `number` | `0.005` | Minute tick **width** as a percentage of clock size (0.0 - 1.0). |
+| `phM` | `number` | `0.03` | Minute tick **height** as a percentage of clock size (0.0 - 1.0). |
+
+---
+
+## 🛠️ API Reference
+
+### Properties & Setters
+
+The class provides strict setters to update **every aspect** of the clock dynamically.
+**Note:** Invalid inputs (wrong types or negative numbers where forbidden) will throw an `Error`.
+
+#### Core Properties
+
+##### `element`
+
+* **Returns:** `HTMLElement`
+* **Description:** The main container of the clock. Use this to append the clock to your DOM.
+
+##### `size`
+
+* **Type:** `number` (positive)
+* **Description:** Updates the dimensions of the clock. Triggers a full re-render.
+
+```javascript
+clock.size = 500;
+```
+
+##### `skinUrl`
+
+* **Type:** `string | null`
+* **Description:** Sets a background image. Set to `null` to use `bgColor`.
+
+```javascript
+clock.skinUrl = './assets/wood-texture.jpg';
+```
+
+##### `bgColor`
+
+* **Type:** `string`
+* **Description:** Updates the background color (visible if no skin is set).
+
+```javascript
+clock.bgColor = '#fafafa';
+```
+
+#### Border & Colors
+
+##### `borderColor` / `borderWidth`
+
+* **Description:** Control the outer border style.
+
+```javascript
+clock.borderColor = '#ff0055';
+clock.borderWidth = 12;
+```
+
+##### `markColor` / `textColor`
+
+* **Description:** Colors for the tick marks and the numbers.
+
+```javascript
+clock.markColor = '#444';
+clock.textColor = '#222';
+```
+
+##### `hourHandColor` / `minuteHandColor` / `secondHandColor`
+
+* **Description:** Individual colors for each hand.
+
+```javascript
+clock.secondHandColor = 'red';
+```
+
+#### Visibility & Layout
+
+##### `showNumbers`
+
+* **Type:** `boolean`
+* **Description:** Toggles the numbers 1-12.
+
+```javascript
+clock.showNumbers = false;
+```
+
+##### `showSeconds`
+
+* **Type:** `boolean`
+* **Description:** Toggles the second hand visibility.
+
+```javascript
+clock.showSeconds = false;
+```
+
+##### `padding`
+
+* **Type:** `number` (non-negative)
+* **Description:** Adjusts space between the outer edge and the ticks.
+
+```javascript
+clock.padding = 20; // Move ticks closer to edge
+```
+
+#### Advanced Geometry (Fine Tuning)
+
+##### `sizeAdjust`
+
+* **Type:** `number` (positive)
+* **Description:** Scales the font size of the numbers.
+
+```javascript
+clock.sizeAdjust = 0.15; // Make numbers huge
+```
+
+##### `angleDistance`
+
+* **Type:** `number` (positive)
+* **Description:** Controls how far from the center the numbers are placed (percentage of radius).
+
+```javascript
+clock.angleDistance = 0.80; // Move numbers closer to center
+```
+
+##### `pwH`, `phH` (Hour Ticks)
+
+* **Type:** `number` (positive)
+* **Description:** Width and Height of **Hour** ticks (percentage of clock size).
+
+```javascript
+clock.pwH = 0.02; // Thicker hour lines
+clock.phH = 0.15; // Longer hour lines
+```
+
+##### `pwM`, `phM` (Minute Ticks)
+
+* **Type:** `number` (positive)
+* **Description:** Width and Height of **Minute** ticks (percentage of clock size).
+
+```javascript
+clock.pwM = 0.01; // Thicker minute lines
+```
+
+### Methods
+
+#### `destroy()`
+
+Stops the internal animation loop (`requestAnimationFrame`) and removes the element from the DOM. **Always call this when removing the clock to prevent memory leaks.**
+
+```javascript
+// When you are done with the clock
+myClock.destroy();
+```
+
+---
+
+## 🎨 Advanced Examples
+
+### Example 1: Dark Mode Clock
+
+```javascript
+const darkClock = new TinyAnalogClock({
+    size: 300,
+    bgColor: '#222',
+    borderColor: '#444',
+    markColor: '#888',
+    textColor: '#fff',
+    hourHandColor: '#fff',
+    minuteHandColor: '#ccc',
+    secondHandColor: '#ffcc00'
+});
+
+document.getElementById('app').appendChild(darkClock.element);
+```
+
+### Example 2: Minimalist Modern
+
+A clock with no numbers, thin lines, and a sleek look.
+
+```javascript
+const modernClock = new TinyAnalogClock({
+    size: 400,
+    showNumbers: false,
+    borderWidth: 2,
+    borderColor: '#000',
+    markColor: '#999',
+    hourHandColor: '#000',
+    minuteHandColor: '#555',
+    secondHandColor: '#d81c1c',
+    padding: 10,
+    pwH: 0.005, // Very thin hour ticks
+    pwM: 0.002  // Ultra thin minute ticks
+});
+
+document.body.appendChild(modernClock.element);
+```
+
+### Example 3: Chunky & Colorful
+
+A clock with thick borders, large numbers, and custom colors.
+
+```javascript
+const chunkyClock = new TinyAnalogClock({
+    size: 500,
+    bgColor: '#2a2a2a',
+    borderColor: '#ffeb3b', // Yellow border
+    borderWidth: 20,
+    textColor: '#ffeb3b',
+    sizeAdjust: 0.12, // Large numbers
+    padding: 60,
+    hourHandColor: '#fff',
+    minuteHandColor: '#ccc',
+    secondHandColor: '#ffeb3b'
+});
+
+document.body.appendChild(chunkyClock.element);
+```
+
+---
+
+### ⚠️ Error Handling
+
+The class ensures data integrity. If you try to set an invalid value, it will fail loudly to help you debug:
+
+```javascript
+try {
+    clock.size = -100; // ❌ Throws Error: 'size' must be a positive number.
+} catch (e) {
+    console.error(e.message);
+}
+```

package/docs/v1/libs/TinyTextDiffer.md

@@ -0,0 +1,114 @@
+# 📝 TinyTextDiffer — Text Comparison Tool
+
+Welcome to **TinyTextDiffer**! This is a lightweight, history-based utility designed to compute granular differences between text versions, mimicking the logic used by modern version control systems like GitHub.
+
+It uses the **Longest Common Subsequence (LCS)** algorithm to ensure that changes are detected accurately at the character level, providing a clean "Added/Deleted/Normal" parse for your UI.
+
+---
+
+## ✨ Features
+
+* 📜 **Version History**: Store and manage multiple versions of a string.
+* 🔍 **Granular Diff**: Detects specific changes (additions, removals, or unchanged text).
+* 🛡️ **Type Safety**: Robust internal validations for indices and data types.
+* 🧹 **Memory Management**: Includes `clear()` and `destroy()` methods to prevent memory leaks.
+* 📦 **ESM Ready**: Built with modern JavaScript using `import/export`.
+
+---
+
+## 🚀 Installation & Setup
+
+Since this is an ES Module, you can simply import it into your project:
+
+```javascript
+import TinyTextDiffer from './TinyTextDiffer.js';
+
+const differ = new TinyTextDiffer(["Initial text", "Updated text!"]);
+
+```
+
+---
+
+## 📚 API Reference
+
+### 🏗️ Constructor
+
+`new TinyTextDiffer(history)`
+
+* **history** (`string[]`): Optional. Initial array of text versions.
+
+---
+
+### 🛠️ Methods
+
+| Method | Parameters | Returns | Description |
+| --- | --- | --- | --- |
+| `add` | `text: string` | `void` | Appends a new version to the end of the history. |
+| `addAt` | `index: number, text: string` | `void` | Inserts a version at a specific position. |
+| `compare` | `...indexes: number` | `DiffResult[][]` | Compares pairs of indices and returns the differences. |
+| `get` | `index: number` | `string` | Retrieves the text at the specified index. |
+| `has` | `index: number` | `boolean` | Checks if a version exists at the specified index. |
+| `remove` | `none` | `string` | Removes and returns the last version in history. |
+| `removeAt` | `index: number` | `boolean` | Removes a specific version and returns `true` if successful. |
+| `clear` | `none` | `void` | Wipes the entire history. |
+| `destroy` | `none` | `void` | Marks the instance as destroyed and frees memory. |
+
+---
+
+### 📊 Data Types
+
+#### `DiffResult`
+
+The `compare` method returns an array of these objects:
+
+```javascript
+/**
+ * @typedef {Object} DiffResult
+ * @property {string} value - The actual string content.
+ * @property {"normal"|"added"|"deleted"} type - The status of the segment.
+ */
+```
+
+---
+
+## 💡 Usage Example
+
+Comparing two versions to see what changed:
+
+```javascript
+const differ = new TinyTextDiffer(["Hello World", "Hello World!"]);
+
+// Comparing index 0 with index 1
+const [result] = differ.compare(0, 1);
+
+console.log(result);
+/*
+Output:
+[
+  { value: "Hello World", type: "normal" },
+  { value: "!", type: "added" }
+]
+*/
+```
+
+---
+
+## ⚙️ Technical Details
+
+### The Algorithm
+
+The core of this tool is the `_computeDiff` private method. It implements a dynamic programming approach to find the **Longest Common Subsequence**.
+
+1. It builds a comparison matrix between two strings.
+2. It traces back the path to identify where characters were added or removed.
+3. It optimizes the output by grouping consecutive characters of the same type (e.g., merging "H", "e", "l", "l", "o" into "Hello").
+
+---
+
+## 🛡️ Error Handling
+
+This class is designed to be "loud" about misuse to help you debug faster:
+
+* Throws `TypeError` if you try to add non-string values.
+* Throws `Error` if you try to access indices out of bounds.
+* Throws `Error` if you attempt to use the instance after calling `destroy()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
@@ -216,6 +216,10 @@
       "require": "./dist/v1/libs/TinyDragger.cjs",
       "import": "./dist/v1/libs/TinyDragger.mjs"
     },
+    "./libs/TinyTextDiffer": {
+      "require": "./dist/v1/libs/TinyTextDiffer.cjs",
+      "import": "./dist/v1/libs/TinyTextDiffer.mjs"
+    },
     "./libs/TinyDragDropDetector": {
       "require": "./dist/v1/libs/TinyDragDropDetector.cjs",
       "import": "./dist/v1/libs/TinyDragDropDetector.mjs"
@@ -248,6 +252,10 @@
       "require": "./dist/v1/libs/TinyAfterScrollWatcher.cjs",
       "import": "./dist/v1/libs/TinyAfterScrollWatcher.mjs"
     },
+    "./libs/TinyAnalogClock": {
+      "require": "./dist/v1/libs/TinyAnalogClock.cjs",
+      "import": "./dist/v1/libs/TinyAnalogClock.mjs"
+    },
     "./libs/TinyAdvancedRaffle": {
       "require": "./dist/v1/libs/TinyAdvancedRaffle.cjs",
       "import": "./dist/v1/libs/TinyAdvancedRaffle.mjs"