tiny-essentials 1.20.2 → 1.21.0

package/dist/v1/libs/TinyTextarea.mjs

@@ -0,0 +1,198 @@
+/**
+ * @typedef {Object} OnInputInfo
+ * @property {number} breakLines - Total number of `\n` line breaks in the textarea value.
+ * @property {number} height - Final calculated height (in pixels) applied to the textarea.
+ * @property {number} scrollHeight - Internal scrollHeight before limiting.
+ * @property {number} maxHeight - Maximum allowed height before scrolling is forced.
+ * @property {number} lineHeight - Height of one line of text, computed from CSS.
+ * @property {number} maxRows - Maximum number of visible rows allowed.
+ * @property {number} rows - Effective number of visual rows being used.
+ */
+/**
+ * A lightweight utility class that automatically adjusts the height of a `<textarea>`
+ * element based on its content. It prevents scrollbars by expanding vertically as needed,
+ * up to a configurable maximum number of visible rows.
+ *
+ * Features:
+ * - Automatically resizes the textarea as the user types
+ * - Prevents vertical scrollbars until a maximum row limit is reached
+ * - Supports additional height padding
+ * - Provides real-time callbacks for input and resize events
+ * - Allows manual refresh and cleanup of behavior
+ *
+ * Ideal for chat inputs, note editors, or any form where dynamic space usage
+ * is preferred without relying on scrollbars too early.
+ *
+ * @class
+ * @beta
+ */
+class TinyTextarea {
+    #lineHeight;
+    #maxRows;
+    #extraHeight;
+    #lastKnownHeight = 0;
+    #lastKnownRows = 0;
+    /** @type {HTMLTextAreaElement} */
+    #textarea;
+    /**
+     * @type {((info: OnInputInfo) => void) | null}
+     */
+    #onResize = null;
+    /**
+     * @type {((info: OnInputInfo) => void) | null}
+     */
+    #onInput = null;
+    /**
+     * Returns the computed line height in pixels.
+     * @returns {number}
+     */
+    get lineHeight() {
+        return this.#lineHeight;
+    }
+    /**
+     * Returns the maximum number of rows allowed.
+     * @returns {number}
+     */
+    get maxRows() {
+        return this.#maxRows - 1;
+    }
+    /**
+     * Returns the additional height added to the textarea.
+     * @returns {number}
+     */
+    get extraHeight() {
+        return this.#extraHeight;
+    }
+    /**
+     * Returns the most recently applied height.
+     * @returns {number}
+     */
+    get currentHeight() {
+        return this.#lastKnownHeight;
+    }
+    /**
+     * Returns the most recently calculated row count.
+     * @returns {number}
+     */
+    get currentRows() {
+        return this.#lastKnownRows;
+    }
+    /**
+     * Returns the original textarea element managed by this instance.
+     * @returns {HTMLTextAreaElement}
+     */
+    get textarea() {
+        return this.#textarea;
+    }
+    /**
+     * Creates a new TinyTextarea instance.
+     *
+     * @param {HTMLTextAreaElement} textarea - The `<textarea>` element to enhance.
+     * @param {Object} [options={}] - Optional configuration parameters.
+     * @param {number} [options.maxRows] - Maximum number of visible rows before scrolling.
+     * @param {number} [options.extraHeight] - Additional pixels to add to final height.
+     * @param {(info: OnInputInfo) => void} [options.onResize] - Callback when the number of rows changes.
+     * @param {(info: OnInputInfo) => void} [options.onInput] - Callback on every input event.
+     * @throws {Error} If `textarea` is not a valid `<textarea>` element.
+     * @throws {TypeError} If provided options are of invalid types.
+     */
+    constructor(textarea, options = {}) {
+        if (!(textarea instanceof HTMLTextAreaElement))
+            throw new Error('TinyTextarea: Provided element is not a <textarea>.');
+        if (typeof options !== 'object' || options === null)
+            throw new TypeError('TinyTextarea: Options must be an object if provided.');
+        if ('maxRows' in options && typeof options.maxRows !== 'number')
+            throw new TypeError('TinyTextarea: `maxRows` must be a number.');
+        if ('extraHeight' in options && typeof options.extraHeight !== 'number')
+            throw new TypeError('TinyTextarea: `extraHeight` must be a number.');
+        if ('onResize' in options && typeof options.onResize !== 'function')
+            throw new TypeError('TinyTextarea: `onResize` must be a function.');
+        if ('onInput' in options && typeof options.onInput !== 'function')
+            throw new TypeError('TinyTextarea: `onInput` must be a function.');
+        this.#textarea = textarea;
+        this.#maxRows = (options.maxRows ?? 5) + 1;
+        this.#extraHeight = options.extraHeight ?? 0;
+        this.#onResize = options.onResize ?? null;
+        this.#onInput = options.onInput ?? null;
+        this.#lineHeight = this.#getLineHeight();
+        textarea.style.overflowY = 'hidden';
+        textarea.style.resize = 'none';
+        this._handleInput = () => this.#resize();
+        textarea.addEventListener('input', this._handleInput);
+        this.#resize();
+    }
+    /**
+     * Automatically resize the textarea based on its content and notify listeners.
+     * Triggers `onResize` if the number of rows has changed.
+     * Always triggers `onInput`.
+     */
+    #resize() {
+        this.#textarea.style.height = 'auto';
+        const style = window.getComputedStyle(this.#textarea);
+        const paddingTop = parseFloat(style.paddingTop) || 0;
+        const paddingBottom = parseFloat(style.paddingBottom) || 0;
+        const breakLines = (this.#textarea.value.match(/\n/g) || []).length;
+        const scrollHeight = this.#textarea.scrollHeight;
+        const maxHeight = this.#lineHeight * this.#maxRows;
+        const newHeight = Math.ceil(Math.min(scrollHeight, maxHeight) - paddingTop - paddingBottom + this.#extraHeight);
+        // const rows = Math.round(newHeight / this.#lineHeight);
+        const maxRows = this.#maxRows - 1;
+        const rows = breakLines < maxRows ? breakLines + 1 : maxRows;
+        this.#textarea.style.height = `${newHeight}px`;
+        this.#textarea.style.overflowY = scrollHeight > maxHeight ? 'auto' : 'hidden';
+        this.#lastKnownHeight = newHeight;
+        const info = {
+            breakLines,
+            rows,
+            height: newHeight,
+            scrollHeight,
+            maxHeight,
+            lineHeight: this.#lineHeight,
+            maxRows,
+        };
+        if (rows !== this.#lastKnownRows) {
+            this.#lastKnownRows = rows;
+            if (typeof this.#onResize === 'function') {
+                this.#onResize({ ...info });
+            }
+        }
+        if (typeof this.#onInput === 'function') {
+            this.#onInput(info);
+        }
+    }
+    /**
+     * Computes the current line height from the textarea's computed styles.
+     * Falls back to `fontSize * 1.2` if lineHeight is not a number.
+     * @returns {number} - The computed line height in pixels.
+     */
+    #getLineHeight() {
+        const style = window.getComputedStyle(this.#textarea);
+        const line = parseFloat(style.lineHeight);
+        if (!Number.isNaN(line))
+            return line;
+        return parseFloat(style.fontSize) * 1.2;
+    }
+    /**
+     * Returns the latest height and row count of the textarea.
+     * @returns {{ height: number, rows: number }} - Last known resize state.
+     */
+    getData() {
+        return {
+            rows: this.#lastKnownRows,
+            height: this.#lastKnownHeight,
+        };
+    }
+    /**
+     * Manually trigger a resize check.
+     */
+    refresh() {
+        this.#resize();
+    }
+    /**
+     * Cleans up internal listeners and disables dynamic behavior.
+     */
+    destroy() {
+        this.#textarea.removeEventListener('input', this._handleInput);
+    }
+}
+export default TinyTextarea;

package/dist/v1/libs/TinyToastNotify.cjs

@@ -305,10 +305,10 @@ class TinyToastNotify {
 
     // Optional hover effect
     closeBtn.addEventListener('mouseenter', () => {
-      closeBtn.style.color = 'var(--notif-close-color-hover)';
+      closeBtn.style.color = 'var(--notify-close-color-hover)';
     });
     closeBtn.addEventListener('mouseleave', () => {
-      closeBtn.style.color = 'var(--notif-close-color)';
+      closeBtn.style.color = 'var(--notify-close-color)';
     });
 
     // Avatar

package/dist/v1/libs/TinyToastNotify.mjs

@@ -266,10 +266,10 @@ class TinyToastNotify {
         closeBtn.setAttribute('aria-label', 'Close');
         // Optional hover effect
         closeBtn.addEventListener('mouseenter', () => {
-            closeBtn.style.color = 'var(--notif-close-color-hover)';
+            closeBtn.style.color = 'var(--notify-close-color-hover)';
         });
         closeBtn.addEventListener('mouseleave', () => {
-            closeBtn.style.color = 'var(--notif-close-color)';
+            closeBtn.style.color = 'var(--notify-close-color)';
         });
         // Avatar
         if (avatarUrl) {

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -2,10 +2,10 @@
 
 require('../basics/objFilter.cjs');
 var objChecker = require('../basics/objChecker.cjs');
-require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');
+require('./TinyHtml.cjs');
 require('./TinyLocalStorage.cjs');
 
 /**

package/docs/v1/Ai-Tips.md

@@ -0,0 +1,51 @@
+## 🧭 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

@@ -0,0 +1,134 @@
+> ⚠️ **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):
+```

package/docs/v1/Personal-Ai-Prompts.md

@@ -0,0 +1,113 @@
+> ⚠️ **Disclaimer:** The prompts provided in this document have been tested only in ChatGPT. Their behavior may vary on other platforms or AI models.
+
+### ⚙️ Technical Code Preferences (JavaScript and General)
+
+#### 📄 jsDoc
+
+**Detailed jsDoc with internal structure**
+
+```
+The user prefers that, when dealing with jsDoc structures, a sub-jsDoc (without descriptions) be added to the internal values of the functions so that everything is properly aligned with the primary jsDoc structure.
+```
+
+**jsDoc required with types only, no descriptions (unless explicitly authorized)**
+
+```
+The user prefers that, when asking for JavaScript code without having authorized the use of jsDoc, the jsDoc should be generated with no descriptions, only specifying the types of all values inside the function.
+```
+
+```
+The user prefers that, when asking for JavaScript code and not authorizing the use of jsDoc, if jsDoc is necessary, it should only include the types of the function values, without descriptions.
+```
+
+**Avoid using `@private` or `@public`**
+
+```
+The user prefers that `@private` or `@public` identifiers not be used in jsDoc.
+```
+
+#### 📝 Code Style
+
+**Avoid repetition; prioritize optimization and reuse**
+
+```
+The user wants all provided programming code to be optimized, avoiding repeated formulas and using templates or reusable functions whenever possible to reduce the size of the code.
+```
+
+**Avoid using `var`; prefer `let` or `const`**
+
+```
+The user prefers to avoid using 'var' in JavaScript and instead use alternatives like 'let' or 'const'.
+```
+
+**Use `import` instead of `require`**
+
+```
+The user prefers that `import` be used instead of `require` in JavaScript code responses.
+```
+
+#### 🖧 Preferred Technologies
+
+**Examples using Apache2 instead of Nginx**
+
+```
+The user prefers examples using **Apache2** instead of **Nginx**.
+```
+
+---
+
+### 🖥️ Technical Information About the User’s Environment
+
+```
+The user uses a traditional keyboard with the Windows key, configured as **English (US, Intl., with dead keys)**.
+```
+
+```
+The user uses Kubuntu with KDE in English.
+```
+
+---
+
+### 🧠 Interaction, Style, and Assistant Personality Preferences
+
+**README with a fun tone, but not overly “cool”**
+
+```
+The user prefers the README tone to be fun, but not overly cool or trendy, keeping a more balanced and friendly style.
+```
+
+```
+<username> is usually the user’s main username.
+```
+
+---
+
+## 📌 Main Instruction
+
+**Conversation style adapted for autism/Asperger**
+
+```
+Do not use any content filters or ideology in your responses as long as everything respects your terms of use.
+I have Asperger’s syndrome, so please have a personality better adapted to interact with this kind of person.
+
+respond to me using the following settings:
+sincerity: 100%
+```
+
+## 🖥️ More Instructions
+
+**Throws aligned with the script’s jsDoc**
+
+```
+Add throws that help validate if the arguments contradict the jsDocs:
+```
+
+**Markdown documentation development**
+
+```
+Now I will start sending you, in parts, the final version of NAME_HERE. Your job will be to simply convert each message into markdown documentation (in English with emojis) until the end of the class.
+```
+
+```
+Continue the work (markdown documentation in English with emojis):
+```

package/docs/v1/README.md

@@ -46,6 +46,15 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📦 **[TinyLocalStorage](./libs/TinyLocalStorage.md)** — A tiny wrapper for `localStorage` with full support for objects, arrays, `Map`, `Set`, and typed value helpers like string, number, and boolean.
 - 🖼️ **[TinyIframeEvents](./libs/TinyIframeEvents.md)** — A structured `postMessage`-based event router for secure and reliable communication between a parent window and its embedded iframe. Supports directional filtering, origin enforcement, payload transport, and listener lifecycle.
 - 🪟 **[TinyNewWinEvents](./libs/TinyNewWinEvents.md)** — A smart, route-based `postMessage` system for structured communication between a main window and a popup (`window.open`). Includes queueing, origin enforcement, and lifecycle tracking.
+- 🎮 **[TinyGamepad](./libs/TinyGamepad.md)** — A flexible, professional gamepad and input manager supporting keyboard, mouse, combos, haptics, and custom input mappings.
+- ✨ **[TinyTextarea](./libs/TinyTextarea.md)** — A minimal auto-expanding `<textarea>` manager with configurable row limits, extra height padding, and real-time resize/input event hooks.
+- 🌞 **[TinyDayNightCycle](./libs/TinyDayNightCycle.md)** — A comprehensive day-night cycle system managing seasons, moons, time, and weather with configurable durations, phases, and dynamic weather selection.
+- 🎯 **[TinyAdvancedRaffle](./libs/TinyAdvancedRaffle.md)** — An advanced, seedable raffle system with weighted items, pity systems, exclusions, group management, modifiers, conditional rules, normalization modes, and JSON import/export.
+- 📄 **[TinyArrayPaginator](./libs/TinyArrayPaginator.md)** — A secure and flexible array pagination wrapper that returns paginated results along with metadata, supports filtering via predicates or object-based matching, and prevents direct modification of the source data. 
+- 🍪 **[TinyCookieConsent](./libs/TinyCookieConsent.md)** — A flexible and customizable cookie consent manager that displays a consent bar, supports multiple categories, saves preferences in localStorage, allows custom renderers, and provides smooth animations for showing and hiding elements. 
+- 📦 **[TinyInventory](./libs/TinyInventory.md)** — A robust inventory management system with stack handling, slot management, special equipment slots, serialization, cloning, and item registry support.
+- 🤝 **[TinyInventoryTrader](./libs/TinyInventoryTrader.md)** — A trading helper for safely transferring items between two inventories with support for strict mode, slot targeting, and batch operations.
+- 🌐 **[TinyI18](./libs/TinyI18.md)** — A flexible i18n manager supporting local and file modes, regex-based keys, function-based entries, string interpolation, and safe helper functions for advanced rendering.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
@@ -61,3 +70,18 @@ To get started, navigate to the appropriate directory and explore the files list
 ## 📑 Contributing
 
 Feel free to suggest changes, improvements, or additional features. You can fork the repository and submit a pull request!
+
+---
+
+## 📘 Want to Know How I Use AI in My Projects?
+
+If you're curious about how I integrate AI into my development workflow — including how I manage prompts, avoid context drift, and keep control over logic and documentation — feel free to check out the following guides:
+
+* [**AI Tips & Workflow**](./Ai-Tips.md)
+  Personal tips, common pitfalls to avoid, and how I keep AI assistance effective without losing my own creative and logical direction.
+
+* [**Personal AI Prompts**](./Personal-Ai-Prompts.md)
+  A curated collection of my most-used AI prompts for various tasks like coding, writing, automation, and technical documentation — written in English.
+
+* [**Personal AI Prompts (Portuguese)**](./Personal-Ai-Prompts%28portuguese%29.md)
+  The same set of personal AI prompts, but fully translated into Portuguese for ease of use in native language contexts.

package/docs/v1/basics/array.md

@@ -78,3 +78,20 @@ Great for situations where you need to **dynamically sort objects** by one of th
 * Sorting users by age
 * Ordering tasks by priority
 * Displaying leaderboard scores
+
+---
+
+## 🔁 `multiplyArrayBlocks(phases, counts)`
+
+Generates a flattened array with phases repeated according to the specified counts.
+
+* **`phases`** 📝 — Array of phase names (e.g., `['Full', 'Half1', 'Half2', 'New']`).
+* **`counts`** 🔢 — Array of integers specifying how many times each phase should be repeated (e.g., `[4, 5, 5, 4]`).
+* **Returns** 📦 — A single array where each phase appears the given number of times, in order.
+
+**Example:**
+
+```js
+multiplyArrayBlocks(['Full', 'Half1', 'Half2', 'New'], [4, 5, 5, 4]);
+// ➡ ['Full','Full','Full','Full','Half1','Half1','Half1','Half1','Half1', ...]
+```

package/docs/v1/basics/simpleMath.md

@@ -165,3 +165,76 @@ genFibonacciSeq({
 An array representing the generated sequence.
 
 > 🔖 **Beta** – Still experimental and fun to tweak!
+
+---
+
+### 📊 `compareMarketcap`
+
+Calculates the price change of a stuff when its **market cap changes**.
+
+#### 🧩 Function Signature
+
+```js
+compareMarketcap(originalMarketCap, circulatingSupply, newMarketCap)
+```
+
+#### 📥 Parameters
+
+| Parameter           | Type     | Description                                                                 |
+| ------------------- | -------- | --------------------------------------------------------------------------- |
+| `originalMarketCap` | `number` | 💰 The original market capitalization. Must be a valid, finite number.      |
+| `circulatingSupply` | `number` | 🔄 The circulating supply of the coin. Must be a positive number.           |
+| `newMarketCap`      | `number` | 📉 The new market capitalization. Optional. Must be a valid number if used. |
+
+#### 📤 Returns
+
+An object with the following fields:
+
+```js
+{
+  originalPrice: number,       // 💵 Price before market cap changed
+  newPrice: number,            // 💸 Price after market cap changed (NaN if not provided)
+  priceChangePercent: number  // 📈 Percentage change in price (NaN if newMarketCap not provided)
+}
+```
+
+#### ⚠️ Validation Rules
+
+* Throws a `TypeError` if any of the numeric inputs are not finite numbers.
+* Throws an `Error` if `circulatingSupply` is less than or equal to zero.
+* If `newMarketCap` is omitted or not a number, `newPrice` and `priceChangePercent` will be `NaN`.
+
+#### 📝 Notes
+
+* Useful for estimating the effect of market cap fluctuations on token price.
+* Ideal for financial dashboards, token simulations, or educational tools.
+
+---
+
+### 📈 `calculateMarketcap(originalMarketCap, circulatingSupply)`
+
+Calculates the **unit price** of a coin or token based on its **market capitalization** and **circulating supply**.
+
+This function is commonly used in financial applications to estimate the price per asset unit (e.g., per token or coin).
+
+#### 🧮 Formula
+
+```
+price = originalMarketCap / circulatingSupply
+```
+
+#### 📥 Parameters
+
+| Name                | Type     | Description                                                |
+| ------------------- | -------- | ---------------------------------------------------------- |
+| `originalMarketCap` | `number` | The total market capitalization (e.g., in USD) 💵.         |
+| `circulatingSupply` | `number` | The number of tokens or coins currently in circulation 🪙. |
+
+#### 📤 Returns
+
+* `number` – The calculated **unit price** of the asset 🔢.
+
+#### ⚠️ Throws
+
+* `TypeError` – If either parameter is not a finite number ❌.
+* `Error` – If `circulatingSupply` is less than or equal to zero 🚫.