tiny-essentials 1.20.2 → 1.21.0

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/TinySmartScroller.md

@@ -442,19 +442,19 @@ Scrolls the target all the way to the top immediately.
 
 ## 🧭 Scroll Position Status
 
-### 🔚 `isUserAtCustomBottom()`
+### 🔚 `isAtCustomBottom()`
 
 Returns `true` if the user is within the custom boundary of the bottom.
 
-### 🔝 `isUserAtCustomTop()`
+### 🔝 `isAtCustomTop()`
 
 Returns `true` if the user is within the custom boundary of the top.
 
-### 🧨 `isUserAtBottom()`
+### 🧨 `isAtBottom()`
 
 Returns `true` if user is currently scrolled to the actual bottom.
 
-### 🧷 `isUserAtTop()`
+### 🧷 `isAtTop()`
 
 Returns `true` if user is currently scrolled to the actual top.
 

package/docs/v1/libs/TinyTextarea.md

@@ -0,0 +1,156 @@
+# ✨ `TinyTextarea`
+
+A lightweight JavaScript utility for automatically resizing `<textarea>` elements as users type — without ugly scrollbars!
+
+---
+
+## 📦 Features
+
+* 🔁 **Auto-resizing**: Grows or shrinks with the content
+* 🚫 **No scrollbars** (until limit): Prevents `overflow-y` unless needed
+* 🔧 **Configurable**: Set `maxRows`, `extraHeight`, and hooks
+* 📡 **Live events**: Hooks for `onInput` and `onResize`
+* 🧼 **Clean lifecycle**: Includes `.refresh()` and `.destroy()`
+
+---
+
+## 🚀 Usage
+
+```js
+import TinyTextarea from './TinyTextarea.js';
+
+const textarea = document.querySelector('textarea');
+
+const autoResize = new TinyTextarea(textarea, {
+  maxRows: 8,
+  extraHeight: 0,
+  onResize: (info) => console.log('Resized:', info),
+  onInput: (info) => console.log('Input event:', info),
+});
+```
+
+To stop behavior and clean up:
+
+```js
+autoResize.destroy();
+```
+
+---
+
+## 🔧 Constructor
+
+```js
+new TinyTextarea(textarea, options?);
+```
+
+### Parameters
+
+| Name                  | Type                          | Description                                           |
+| --------------------- | ----------------------------- | ----------------------------------------------------- |
+| `textarea`            | `HTMLTextAreaElement`         | The `<textarea>` element to be managed.               |
+| `options`             | `Object` *(optional)*         | Configuration options.                                |
+| `options.maxRows`     | `number`                      | Max number of visible rows before scrollbars appear.  |
+| `options.extraHeight` | `number`                      | Extra height (in px) to add on top of computed value. |
+| `options.onResize`    | `(info: OnInputInfo) => void` | Called when number of visible rows changes.           |
+| `options.onInput`     | `(info: OnInputInfo) => void` | Called on every `input` event.                        |
+
+---
+
+## 📚 API
+
+### `.getData() → { height, rows }`
+
+Returns the last known height and number of visible rows.
+
+```js
+const { height, rows } = autoResize.getData();
+```
+
+---
+
+### `.refresh()`
+
+Forces a manual recalculation and resize of the `<textarea>`.
+
+```js
+autoResize.refresh();
+```
+
+---
+
+### `.destroy()`
+
+Cleans up listeners and disables resizing behavior. Use this if you remove the element or want to stop automatic behavior.
+
+```js
+autoResize.destroy();
+```
+
+---
+
+### 🔍 Getters
+
+TinyTextarea exposes several readonly properties to let you inspect the current configuration and state of the managed `<textarea>`.
+
+#### 📏 `lineHeight: number`
+
+Returns the height in pixels of a single line of text in the textarea, computed from its current CSS styles.
+Useful for calculating exact space usage or aligning UI elements.
+
+---
+
+#### 📐 `maxRows: number`
+
+Returns the maximum number of visible text rows allowed before the textarea begins to scroll.
+This value reflects the limit set via `options.maxRows`.
+
+---
+
+#### ➕ `extraHeight: number`
+
+Returns the number of extra pixels added to the calculated height of the textarea.
+This is useful for custom padding or visual adjustments.
+
+---
+
+#### 📏 `currentHeight: number`
+
+Returns the most recently applied height (in pixels) that was set on the `<textarea>` after resizing.
+
+---
+
+#### 📊 `currentRows: number`
+
+Returns the most recent number of visible text rows that the textarea is currently using.
+This value is calculated dynamically and may change as the user types.
+
+---
+
+#### 🧩 `textarea: HTMLTextAreaElement`
+
+Returns the original `<textarea>` DOM element that was enhanced by this instance.
+You can use this for direct styling, value changes, or other DOM-level operations.
+
+---
+
+## 📤 Event Payload: `OnInputInfo`
+
+Whenever `onResize` or `onInput` is triggered, the following object is passed:
+
+```ts
+{
+  breakLines: number;    // Total number of '\n' in the textarea
+  height: number;        // Final computed height (px)
+  scrollHeight: number;  // Natural scrollHeight of textarea
+  maxHeight: number;     // Max height before scrollbars show
+  lineHeight: number;    // Height of one line of text
+  maxRows: number;       // Maximum number of visible rows allowed
+  rows: number;          // Final calculated number of rows used
+}
+```
+
+---
+
+## 🧪 Beta Notice
+
+> 🧪 This library is currently marked as `@beta`. The API is stable but may be adjusted slightly during updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "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;
-}