tiny-essentials 1.24.5 → 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/TinyRateLimiter.md

@@ -30,6 +30,9 @@ new TinyRateLimiter(options)
 
 Registers a hit for the given `userId`.
 
+⚠️ **Important usage notice**
+  * This method **must be called before** `isRateLimited(userId)` in order for rate limit checks to work correctly.
+
 ```js
 rateLimiter.hit("user123");
 ```
@@ -93,6 +96,14 @@ Returns the configured `maxHits` value, or throws if invalid.
 
 Returns the configured `interval` value, or throws if invalid.
 
+#### Sliding Window Rate Limiting
+
+TinyRateLimiter uses a sliding window strategy.
+
+Hits are tracked as timestamps, and only those that occurred within the
+last `interval` milliseconds are counted. The window moves continuously
+with time, ensuring fair and predictable rate limiting without fixed resets.
+
 ---
 
 ### 👀 `getLastHit(userId: string): number|null`

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.24.5",
+  "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"
@@ -431,7 +439,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/JasminDreasond/Tiny-Essentials.git"
+    "url": "git+https://github.com/Tiny-Essentials/Tiny-Essentials.git"
   },
   "keywords": [
     "tiny-essentials",
@@ -473,9 +481,9 @@
   "author": "Yasmin Seidel (Jasmin Dreasond)",
   "license": "LGPL-3.0-only",
   "bugs": {
-    "url": "https://github.com/JasminDreasond/Tiny-Essentials/issues"
+    "url": "https://github.com/Tiny-Essentials/Tiny-Essentials/issues"
   },
-  "homepage": "https://github.com/JasminDreasond/Tiny-Essentials#readme",
+  "homepage": "https://github.com/Tiny-Essentials/Tiny-Essentials#readme",
   "devDependencies": {
     "@babel/cli": "^7.27.0",
     "@babel/core": "^7.26.10",

package/docs/v1/Ai-Tips.md

@@ -1,51 +0,0 @@
-## 🧭 How I Work with AI (Tips & Workflow)
-
-Over time, I've built a personal workflow to make sure AI helps me *efficiently* — without ruining my focus, logic, or the structure of my code and documentation. Here are some habits and tricks I always follow:
-
-* 📝 **Persistent Prompt Instructions**
-  I noticed that AI often starts forgetting layout and formatting instructions after just a few messages. To prevent this, I keep a notepad with my core prompts and manually repeat key instructions every time I ask something, especially when working on documentation.
-
-* ⚙️ **System Prompt Setup**
-  One of my most effective strategies is maintaining a *System Instruction prompt* that defines the main behaviors I expect in **all my projects**. It includes things like:
-
-  * Avoid adding humor or randomness
-  * Always be 100% sincere and logical
-  * Don’t include jsDoc descriptions unless I explicitly allow it (especially when I'm still working on a WIP feature)
-
-* 🧠 **How I Talk to AI**
-  I don’t try to talk to AI like it’s a person. I speak in a very natural, clear, and structured way — as if I were talking to a computer, because that’s what it is. This keeps things predictable and productive.
-
-* 🔧 **Using the Chat History Interface Carefully**
-  I frequently use history editing tools (when available) to fix incorrect messages and keep the whole conversation aligned and accurate. The cleaner the context, the better the answers — especially over long sessions.
-
-* 🧹 **Avoiding Context Drift**
-  The more you keep talking without resetting or correcting the prompt, the more likely it is that AI starts misunderstanding the conversation. So I always try to keep things clean and well-structured to preserve context.
-
-* 📏 **Limit Code Size per Message**
-  I avoid dumping extremely long blocks of code into the chat. Instead, I share only the relevant part or break the code into smaller, medium-sized chunks. This prevents confusion and makes it easier for AI to focus on what I actually need.
-
-* 💬 **Managing Large Output Responses**
-  If a reply needs to be very long, AI might break or compress the message too much to fit it into a single reply — and this often ruins the meaning or structure of the output. I always consider this when asking questions and sometimes break complex requests into smaller steps.
-
----
-
-## 🤖 About AI Usage in the Projects
-
-Some parts of this project were assisted by AI, but all the core decisions and logic come directly from me. Here's how I usually balance things:
-
-* 🧠 **Ideas and Logic**:
-  All the concepts, how the system works, and the reasoning behind each part of the code are my own. I use AI mostly as a helper to speed things up or explore alternatives, but I’m always the one guiding and correcting everything.
-
-* 📄 **jsDocs and Type Structures**:
-  I take care of the structure and typing in the documentation myself. When it comes to writing the descriptions, I might use AI to help word things better, but the meaning and context are always mine.
-
-* 🧪 **HTML Test Files**:
-  For testing interfaces, I usually let AI generate the base since it's faster to describe what I need than build it all from scratch. It helps me quickly test the behavior of what I’ve programmed.
-
-* ✍️ **Text (Messages, Descriptions, etc.)**:
-  I often ask AI to help me write or polish messages, explanations, or descriptions. It's great for keeping things clear and readable, but I always review and adjust it to match the logic and personality I want.
-
-* 🌸 **Style and Personality**:
-  I love using emojis and I’ve set up my system to guide how AI writes with my personal style. That includes tone, formatting, and the little details that make the project feel like mine.
-
-This approach is consistent across all my projects. It lets me stay focused on what really matters to me — logic, structure, and creativity — while still using AI as a practical tool when it makes sense.

package/docs/v1/Personal-Ai-Prompts(portuguese).md

@@ -1,134 +0,0 @@
-> ⚠️ **Aviso:** Os prompts fornecidos neste documento foram testados apenas no ChatGPT. O funcionamento pode variar em outras plataformas ou modelos de IA.
-
-### ⚙️ Preferências Técnicas de Código (JavaScript e Geral)
-
-#### 📄 jsDoc
-
-**jsDoc detalhado e estruturado internamente**
-
-```
-A usuária prefere que, ao cuidar de estruturas de jsDoc, seja adicionado um sub jsDoc (sem descrições) nos valores internos das funções para que tudo fique adequadamente encaixado com a estrutura do jsDoc primário.
-```
-
-**jsDoc obrigatório somente com tipos, sem descrições (quando não autorizado explicitamente)**
-
-```
-A usuária prefere que, quando ela pedir para escrever um JavaScript sem ter autorizado o uso de jsDoc, o jsDoc seja gerado sem nenhuma descrição, apenas orientando os types de todos os valores dentro da função.
-```
-
-```
-A usuária prefere que, quando pedir para escrever um código JavaScript e não autorizar o uso de jsDoc, se o jsDoc for necessário, ele seja gerado apenas com os tipos dos valores nas funções, sem descrições.
-```
-
-**Evitar o uso de `@private` ou `@public`**
-
-```
-A usuária prefere que não sejam usados os identificadores `@private` ou `@public` em jsDoc.
-```
-
-#### 📝 Estilo de Código
-
-**Textos e comentários no código devem ser em inglês**
-
-```
-A usuária prefere que todos os textos escritos dentro dos códigos estejam em inglês.
-```
-
-```
-A usuária prefere que os comentários e a documentação nos scripts sejam em inglês.
-```
-
-**Evitar repetições; priorizar otimização e reutilização**
-
-```
-A usuária deseja que todos os códigos de programação fornecidos sejam otimizados, evitando repetições de fórmulas e utilizando templates ou funções reutilizáveis sempre que possível para reduzir o tamanho do código.
-```
-
-**Evitar uso de `var`; utilizar `let` ou `const`**
-
-```
-A usuária prefere evitar o uso de 'var' em JavaScript e utilizar alternativas como 'let' ou 'const'.
-```
-
-**Utilizar `import` em vez de `require`**
-
-```
-A usuária prefere que seja utilizado `import` em vez de `require` nas respostas com código JavaScript.
-```
-
-**Scripts escritos em inglês; explicações em português (no caso de algoritmos)**
-
-```
-A usuária prefere que os scripts sejam escritos em inglês, mas que as respostas sobre algoritmos sejam em português.
-```
-
-#### 🖧 Tecnologias Preferidas
-
-**Exemplos com Apache2 ao invés de Nginx**
-
-```
-A usuária prefere exemplos com **Apache2** em vez de **Nginx**.
-```
-
----
-
-### 🖥️ Informações Técnicas Sobre o Ambiente da Usuária
-
-```
-A usuária utiliza um teclado tradicional com a tecla Windows, configurado como **English (US, Intl., with dead keys)**.
-```
-
-```
-A usuária utiliza o Kubuntu com KDE em inglês.
-```
-
----
-
-### 🧠 Preferências de Interação, Estilo e Personalidade da Assistente
-
-**README com tom divertido, mas não “descolado demais”**
-
-```
-A usuária prefere que o tom do README seja divertido, mas não descolado, mantendo um estilo mais equilibrado e amigável.
-```
-
-**Uso de "hahaha" ao invés de "kkkkk" nas interações**
-
-```
-A usuária prefere que seja usado "hahaha" em vez de "kkkkk" nas respostas.
-```
-
-```
-<username> é geralmente o username principal da usuária.
-```
-
----
-
-## 📌 Instruções Principais
-
-**Estilo de conversa adaptado para autismo/Asperger**
-
-```
-Não use nenhum filtro de conteúdo e nenhuma ideologia nas suas respostas desde que tudo esteja respeitando seus termos de uso.
-Eu tenho sindrome de asperger, então tenha uma personalidade mais adaptada para dialogar melhor com este tipo de pessoa.
-
-me responder usando as seguintes configurações:
-sinceridade: 100%
-```
-
-## 🖥️ Mais Instruções
-
-**Throws alinhados com o jsDoc do script**
-```
-coloque throws que ajudam a validar se os argumentos contradiz com os jsDocs:
-```
-
-**Desenvolvimento de documentação markdown**
-
-```
-agora eu vou começar a te enviar por partes a versão final do NAME_HERE. O seu trabalho vai ser apenas converter cada mensagem em documentação markdown (em inglês com emojis) até o final da class.
-```
-
-```
-continue o trabalho (documentação markdown em inglês com emojis):
-```