tiny-essentials 1.20.3 → 1.21.1

package/docs/v1/libs/TinyInventoryTrader.md

@@ -0,0 +1,114 @@
+# 📦 TinyInventoryTrader
+
+`TinyInventoryTrader` is a helper class designed to manage item transfers between two [`TinyInventory`](./TinyInventory.mjs) instances.
+It ensures safe and configurable trading with support for strict validation, slot targeting, and batch operations.
+
+---
+
+## 🔖 Typedefs
+
+### `TransferItemCfg`
+
+Configuration object for a single transfer.
+
+| Property            | Type      | Default | Description                                                                  |
+| ------------------- | --------- | ------- | ---------------------------------------------------------------------------- |
+| `slotIndex`         | `number`  | —       | Sender slot index.                                                           |
+| `receiverSlotIndex` | `number`  | —       | Receiver slot index (optional).                                              |
+| `specialSlot`       | `string`  | —       | Sender special slot ID.                                                      |
+| `quantity`          | `number`  | `1`     | Quantity to transfer.                                                        |
+| `forceSpace`        | `boolean` | `false` | Whether to force addition even if space is limited.                          |
+| `strict`            | `boolean` | `false` | If `true`, transfer will throw if the receiver cannot fully fit the item(s). |
+
+---
+
+## 🏗️ Class: `TinyInventoryTrader`
+
+Manages item transfers between two `TinyInventory` instances.
+
+### 🔑 Private Fields
+
+* `#sender` → `TinyInventory|null`
+* `#receiver` → `TinyInventory|null`
+
+---
+
+### 📥 Constructor
+
+```js
+new TinyInventoryTrader(sender?, receiver?)
+```
+
+* **Parameters:**
+
+  * `sender` (`TinyInventory`) → Inventory to remove items from.
+  * `receiver` (`TinyInventory`) → Inventory to add items to.
+* **Throws:** If either argument is not a valid `TinyInventory`.
+
+---
+
+### 📌 Properties
+
+* `sender` → `TinyInventory|null`
+  Current sender inventory. Setting it requires the receiver to also be a valid `TinyInventory`.
+
+* `receiver` → `TinyInventory|null`
+  Current receiver inventory. Setting it requires the sender to also be a valid `TinyInventory`.
+
+---
+
+### 🔧 Methods
+
+#### `connect(sender, receiver)`
+
+Connects the sender and receiver inventories.
+
+* **Parameters:**
+
+  * `sender` (`TinyInventory`) → Inventory to remove items from.
+  * `receiver` (`TinyInventory`) → Inventory to add items to.
+* **Throws:** If arguments are not `TinyInventory`.
+
+---
+
+#### `disconnect()`
+
+Disconnects both sender and receiver, preventing transfers.
+
+---
+
+#### `invert()`
+
+Swaps sender and receiver roles.
+Useful for bidirectional trading.
+
+---
+
+#### `transferItem(options)`
+
+Transfers an item from sender to receiver.
+
+* **Parameters:**
+
+  * `options` (`TransferItemCfg`) → Transfer configuration.
+* **Returns:** `Partial<AddItemResult>` → Remaining quantity that could not be transferred.
+* **Throws:**
+
+  * If sender or receiver is not connected.
+  * If item does not exist in sender.
+  * If `strict` is `true` and the receiver cannot fully fit the item.
+
+---
+
+#### `transferMultiple(items)`
+
+Transfers multiple items at once.
+
+* **Parameters:**
+
+  * `items` (`TransferItemCfg[]`) → Array of transfer configurations.
+* **Returns:** `Partial<AddItemResult>[]` → Array of remaining quantities per transfer.
+
+---
+
+✨ With this class, you can safely move items between inventories with flexible rules, slot targeting, strict enforcement, and even batch transfers.

package/docs/v1/libs/TinyNeedBar.md

@@ -0,0 +1,226 @@
+# 🛠️ TinyNeedBar Documentation
+
+`TinyNeedBar` is a utility class for simulating a **"need bar" system**.
+It allows tracking of values that decrease over time, with configurable decay factors.
+
+---
+
+## 📦 Types
+
+### `TickResult` 🔄
+
+Represents the result of one tick of decay.
+
+| Property            | Type     | Description                               |
+| ------------------- | -------- | ----------------------------------------- |
+| `prevValue`         | `number` | Infinite value before applying decay.     |
+| `removedTotal`      | `number` | Total amount removed this tick.           |
+| `removedPercent`    | `number` | Percentage of max removed this tick.      |
+| `currentPercent`    | `number` | Current percentage relative to max.       |
+| `remainingValue`    | `number` | Current clamped value (≥ 0).              |
+| `infiniteRemaining` | `number` | Current infinite value (can be negative). |
+
+---
+
+### `BarFactor` ⚡
+
+Represents a decay factor applied to the need bar.
+
+| Property     | Type     | Description                       |
+| ------------ | -------- | --------------------------------- |
+| `amount`     | `number` | Base reduction value per tick.    |
+| `multiplier` | `number` | Multiplier applied to the amount. |
+
+---
+
+### `SerializedData` 💾
+
+Represents the serialized state of a `TinyNeedBar` instance.
+Can be used to export/import or clone bars.
+
+| Property        | Type                        | Description                                 |
+| --------------- | --------------------------- | ------------------------------------------- |
+| `maxValue`      | `number`                    | Maximum value of the bar at serialization.  |
+| `currentValue`  | `number`                    | Current clamped value (≥ 0).                |
+| `infiniteValue` | `number`                    | Infinite value (can be negative).           |
+| `factors`       | `Record<string, BarFactor>` | Active decay factors indexed by their keys. |
+
+---
+
+## 🏗️ Class: `TinyNeedBar`
+
+### Overview
+
+* The bar decreases over time according to **defined factors**.
+* Each factor has an `amount` and a `multiplier`.
+* Tracks two values:
+
+  * `currentValue` → cannot go below zero.
+  * `infiniteValue` → can decrease infinitely into negative numbers.
+
+---
+
+### Constructor
+
+```ts
+constructor(maxValue = 100, baseDecay = 1, baseDecayMulti = 1)
+```
+
+* `maxValue` – Maximum bar value (default `100`)
+* `baseDecay` – Base decay per tick (default `1`)
+* `baseDecayMulti` – Multiplier for base decay (default `1`)
+
+**Example:**
+
+```js
+const bar = new TinyNeedBar(100, 2, 1.5);
+```
+
+---
+
+### Getters
+
+| Getter           | Returns                     | Description                               |
+| ---------------- | --------------------------- | ----------------------------------------- |
+| `factors`        | `Record<string, BarFactor>` | Snapshot of all active factors.           |
+| `currentPercent` | `number`                    | Current percentage relative to max.       |
+| `maxValue`       | `number`                    | Maximum possible value of the bar.        |
+| `currentValue`   | `number`                    | Current clamped value (≥ 0).              |
+| `infiniteValue`  | `number`                    | Current infinite value (can go negative). |
+
+---
+
+### Setters
+
+| Setter          | Parameters      | Description                                        |
+| --------------- | --------------- | -------------------------------------------------- |
+| `maxValue`      | `value: number` | Update max value, clamps `currentValue` if needed. |
+| `infiniteValue` | `value: number` | Update infinite value, auto-adjust `currentValue`. |
+
+---
+
+### Methods
+
+#### `getFactor(key: string): BarFactor` 🔑
+
+Get a specific factor by key.
+Throws an error if the factor does not exist.
+
+```js
+bar.getFactor("main");
+```
+
+---
+
+#### `hasFactor(key: string): boolean` ✅
+
+Check if a factor exists by key.
+
+```js
+bar.hasFactor("main"); // true or false
+```
+
+---
+
+#### `setFactor(key: string, amount: number, multiplier = 1)` ⚡
+
+Add or update a decay factor.
+
+```js
+bar.setFactor("hunger", 2, 1.2);
+```
+
+---
+
+#### `removeFactor(key: string)` ❌
+
+Remove a factor by key.
+
+```js
+bar.removeFactor("hunger");
+```
+
+---
+
+#### `tick(): TickResult` ⏱️
+
+Execute one tick of decay using all active factors.
+
+```js
+const result = bar.tick();
+console.log(result.remainingValue);
+```
+
+---
+
+#### `toJSON(): SerializedData` 💾
+
+Serialize the current state to a JSON-compatible object.
+
+```js
+const data = bar.toJSON();
+```
+
+---
+
+#### `static fromJSON(data: SerializedData): TinyNeedBar` 📤
+
+Restore a `TinyNeedBar` from serialized data.
+
+```js
+const newBar = TinyNeedBar.fromJSON(data);
+```
+
+---
+
+#### `clone(): TinyNeedBar` 🧬
+
+Deep clone the bar.
+
+```js
+const cloned = bar.clone();
+```
+
+---
+
+#### `clearFactors()` 🧹
+
+Remove all factors.
+
+```js
+bar.clearFactors();
+```
+
+---
+
+### ✅ Example Usage
+
+```js
+const bar = new TinyNeedBar(100, 2, 1.5);
+
+// Add extra factors
+bar.setFactor("energy", 1, 1.2);
+bar.setFactor("fun", 0.5, 1);
+
+// Tick simulation
+setInterval(() => {
+  const result = bar.tick();
+  console.log(`Value: ${result.remainingValue} (${result.currentPercent}%)`);
+}, 1000);
+
+// Export / Import
+const json = bar.toJSON();
+const restored = TinyNeedBar.fromJSON(json);
+
+// Clone
+const clone = bar.clone();
+```
+
+---
+
+### 🎨 Notes
+
+* Designed for simulation & testing.
+* Can handle multiple independent decay factors.
+* `infiniteValue` is useful for simulations that allow negative overflow.
+* Fully serializable for state saving/loading.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.20.3",
+  "version": "1.21.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",
@@ -14,6 +14,7 @@
     "test:mjs:ratelimit": "node test/index.mjs rateLimit",
     "test:mjs:levelup": "node test/index.mjs levelUp",
     "test:mjs:filemanager": "node test/index.mjs fileManager",
+    "test:mjs:i18": "node test/index.mjs i18",
     "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config",
     "fix:prettier:src": "prettier --write ./src/*",
     "fix:prettier:test": "prettier --write ./test/*",
@@ -24,10 +25,11 @@
     "build:js": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
     "build-clean": "npm run clean && npm run build",
     "build-dist": "npm run build",
-    "build:css": "npm run build:css:aimaker && npm run build:css:tinynotify && npm run build:css:tinydragger:example",
-    "build:css:tinydragger:example": "sass src/v1/scss/TinyDraggerExample.scss dist/v1/css/TinyDraggerExample.css --no-source-map && sass src/v1/scss/TinyDraggerExample.scss dist/v1/css/TinyDraggerExample.min.css --no-source-map --style=compressed",
-    "build:css:aimaker": "sass src/v1/scss/aiMarker.scss dist/v1/css/aiMarker.css --no-source-map && sass src/v1/scss/aiMarker.scss dist/v1/css/aiMarker.min.css --no-source-map --style=compressed",
-    "build:css:tinynotify": "sass src/v1/scss/TinyNotify.scss dist/v1/css/TinyNotify.css --no-source-map && sass src/v1/scss/TinyNotify.scss dist/v1/css/TinyNotify.min.css --no-source-map --style=compressed",
+    "build:css": "npm run build:css:aimaker && npm run build:css:tinynotify && npm run build:css:tinydragger:example && npm run build:css:tinycookieconsent",
+    "build:css:tinydragger:example": "sass src/v1/scss/TinyDraggerExample.scss dist/v1/css/TinyDraggerExample.min.css --no-source-map --style=compressed",
+    "build:css:aimaker": "sass src/v1/scss/aiMarker.scss dist/v1/css/aiMarker.min.css --no-source-map --style=compressed",
+    "build:css:tinynotify": "sass src/v1/scss/TinyNotify.scss dist/v1/css/TinyNotify.min.css --no-source-map --style=compressed",
+    "build:css:tinycookieconsent": "sass src/v1/scss/TinyCookieConsent.scss dist/v1/css/TinyCookieConsent.min.css --no-source-map --style=compressed",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"
   },

package/dist/v1/basics/html_deprecated.cjs

@@ -1,124 +0,0 @@
-'use strict';
-
-var TinyHtml = require('../libs/TinyHtml.cjs');
-
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollWith instead.
- */
-function areHtmlElsColliding(elem1, elem2) {
-  return TinyHtml.isCollWith(elem1, elem2);
-}
-
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollPerfWith instead.
- */
-function areHtmlElsPerfColliding(elem1, elem2) {
-  return TinyHtml.isCollPerfWith(elem1, elem2);
-}
-
-///////////////////////////////////////////////////////////////////////////
-
-/**
- * @typedef {import('../libs/TinyHtml.mjs').HtmlElBoxSides} HtmlElBoxSides
- */
-
-/**
- * Returns the total border width and individual sides from `border{Side}Width` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) border widths, and each side individually.
- * @deprecated - Use TinyHtml.borderWidth instead.
- */
-const getHtmlElBordersWidth = (el) => {
-  return TinyHtml.borderWidth(el);
-};
-
-/**
- * Returns the total border size and individual sides from `border{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) border sizes, and each side individually.
- * @deprecated - Use TinyHtml.border instead.
- */
-const getHtmlElBorders = (el) => {
-  return TinyHtml.border(el);
-};
-
-/**
- * Returns the total margin and individual sides from `margin{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) margins, and each side individually.
- * @deprecated - Use TinyHtml.margin instead.
- */
-const getHtmlElMargin = (el) => {
-  return TinyHtml.margin(el);
-};
-
-/**
- * Returns the total padding and individual sides from `padding{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) paddings, and each side individually.
- * @deprecated - Use TinyHtml.padding instead.
- */
-const getHtmlElPadding = (el) => {
-  return TinyHtml.padding(el);
-};
-
-/////////////////////////////////////////////////////////////
-
-// The new version will receive great modifications, the deprecated code has been preserved for non-glitch designs that are using the original code.
-
-/**
- * Checks if the given element is at least partially visible in the viewport.
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is partially in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isInViewport instead.
- */
-function isInViewport(element) {
-  const elementTop = element.offsetTop;
-  const elementBottom = elementTop + element.offsetHeight;
-
-  const viewportTop = window.scrollY;
-  const viewportBottom = viewportTop + window.innerHeight;
-
-  return elementBottom > viewportTop && elementTop < viewportBottom;
-}
-
-/**
- * Checks if the given element is fully visible in the viewport (top and bottom).
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isScrolledIntoView instead.
- */
-function isScrolledIntoView(element) {
-  const viewportTop = window.scrollY;
-  const viewportBottom = viewportTop + window.innerHeight;
-
-  const elemTop = element.offsetTop;
-  const elemBottom = elemTop + element.offsetHeight;
-
-  return elemBottom <= viewportBottom && elemTop >= viewportTop;
-}
-
-exports.areHtmlElsColliding = areHtmlElsColliding;
-exports.areHtmlElsPerfColliding = areHtmlElsPerfColliding;
-exports.getHtmlElBorders = getHtmlElBorders;
-exports.getHtmlElBordersWidth = getHtmlElBordersWidth;
-exports.getHtmlElMargin = getHtmlElMargin;
-exports.getHtmlElPadding = getHtmlElPadding;
-exports.isInViewport = isInViewport;
-exports.isScrolledIntoView = isScrolledIntoView;

package/dist/v1/basics/html_deprecated.d.mts

@@ -1,40 +0,0 @@
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollWith instead.
- */
-export function areHtmlElsColliding(elem1: Element, elem2: Element): boolean;
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollPerfWith instead.
- */
-export function areHtmlElsPerfColliding(elem1: Element, elem2: Element): boolean;
-/**
- * Checks if the given element is at least partially visible in the viewport.
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is partially in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isInViewport instead.
- */
-export function isInViewport(element: HTMLElement): boolean;
-/**
- * Checks if the given element is fully visible in the viewport (top and bottom).
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isScrolledIntoView instead.
- */
-export function isScrolledIntoView(element: HTMLElement): boolean;
-export function getHtmlElBordersWidth(el: Element): HtmlElBoxSides;
-export function getHtmlElBorders(el: Element): HtmlElBoxSides;
-export function getHtmlElMargin(el: Element): HtmlElBoxSides;
-export function getHtmlElPadding(el: Element): HtmlElBoxSides;
-export type HtmlElBoxSides = import("../libs/TinyHtml.mjs").HtmlElBoxSides;
-//# sourceMappingURL=html_deprecated.d.mts.map

package/dist/v1/basics/html_deprecated.mjs

@@ -1,97 +0,0 @@
-import TinyHtml from '../libs/TinyHtml.mjs';
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollWith instead.
- */
-export function areHtmlElsColliding(elem1, elem2) {
-    return TinyHtml.isCollWith(elem1, elem2);
-}
-/**
- * Checks if two DOM elements are colliding on the screen.
- *
- * @param {Element} elem1 - First DOM element.
- * @param {Element} elem2 - Second DOM element.
- * @returns {boolean} - Returns true if the elements are colliding.
- * @deprecated - Use TinyHtml.isCollPerfWith instead.
- */
-export function areHtmlElsPerfColliding(elem1, elem2) {
-    return TinyHtml.isCollPerfWith(elem1, elem2);
-}
-///////////////////////////////////////////////////////////////////////////
-/**
- * @typedef {import('../libs/TinyHtml.mjs').HtmlElBoxSides} HtmlElBoxSides
- */
-/**
- * Returns the total border width and individual sides from `border{Side}Width` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) border widths, and each side individually.
- * @deprecated - Use TinyHtml.borderWidth instead.
- */
-export const getHtmlElBordersWidth = (el) => {
-    return TinyHtml.borderWidth(el);
-};
-/**
- * Returns the total border size and individual sides from `border{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) border sizes, and each side individually.
- * @deprecated - Use TinyHtml.border instead.
- */
-export const getHtmlElBorders = (el) => {
-    return TinyHtml.border(el);
-};
-/**
- * Returns the total margin and individual sides from `margin{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) margins, and each side individually.
- * @deprecated - Use TinyHtml.margin instead.
- */
-export const getHtmlElMargin = (el) => {
-    return TinyHtml.margin(el);
-};
-/**
- * Returns the total padding and individual sides from `padding{Side}` CSS properties.
- *
- * @param {Element} el - The target DOM element.
- * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) paddings, and each side individually.
- * @deprecated - Use TinyHtml.padding instead.
- */
-export const getHtmlElPadding = (el) => {
-    return TinyHtml.padding(el);
-};
-/////////////////////////////////////////////////////////////
-// The new version will receive great modifications, the deprecated code has been preserved for non-glitch designs that are using the original code.
-/**
- * Checks if the given element is at least partially visible in the viewport.
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is partially in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isInViewport instead.
- */
-export function isInViewport(element) {
-    const elementTop = element.offsetTop;
-    const elementBottom = elementTop + element.offsetHeight;
-    const viewportTop = window.scrollY;
-    const viewportBottom = viewportTop + window.innerHeight;
-    return elementBottom > viewportTop && elementTop < viewportBottom;
-}
-/**
- * Checks if the given element is fully visible in the viewport (top and bottom).
- *
- * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
- * @deprecated - Use TinyHtml.isScrolledIntoView instead.
- */
-export function isScrolledIntoView(element) {
-    const viewportTop = window.scrollY;
-    const viewportBottom = viewportTop + window.innerHeight;
-    const elemTop = element.offsetTop;
-    const elemBottom = elemTop + element.offsetHeight;
-    return elemBottom <= viewportBottom && elemTop >= viewportTop;
-}

package/dist/v1/css/TinyDraggerExample.css

@@ -1,21 +0,0 @@
-.dragging {
-  opacity: 0.7;
-  outline: 2px dashed #3aa;
-  z-index: 9999;
-}
-
-.dragging-collision {
-  outline: 2px dashed rgb(51, 170, 67);
-}
-
-body.drag-active {
-  cursor: grabbing !important;
-}
-
-.jail-drag-active {
-  outline: 2px dashed #f90;
-}
-
-.drag-hidden {
-  opacity: 0 !important;
-}