tiny-essentials 1.16.0 → 1.16.2

package/docs/v1/libs/TinyAfterScrollWatcher.md

@@ -0,0 +1,231 @@
+# 📜 TinyAfterScrollWatcher
+
+A minimalistic scroll watcher that queues and executes functions **after scrolling has stopped** on a given element or the window.
+Perfect for optimizing logic that should only run **after** the user has finished scrolling.
+
+---
+
+## 🚀 Features
+
+* ✅ Works on any scrollable element or the window
+* ⏱️ Customizable "inactivity timeout" (default: `100ms`)
+* 🧠 Executes queued callbacks after scroll ends
+* 🧷 Add/remove scroll listeners easily (`onScroll` / `offScroll`)
+* 🛑 Execute logic right before after-scroll queue (`onStop`)
+* 🧹 Cleanly destroy the instance when no longer needed
+
+---
+
+## 📦 Import
+
+```js
+import TinyAfterScrollWatcher from './TinyAfterScrollWatcher.mjs';
+```
+
+---
+
+## 🧪 Example
+
+```js
+const watcher = new TinyAfterScrollWatcher(window);
+
+// Optional: set a custom delay (in ms)
+watcher.inactivityTime = 300;
+
+// Add a function to run after scroll has stopped
+watcher.doAfterScroll(() => {
+  console.log('Scroll has stopped for 300ms!');
+});
+
+// Add a function to run immediately when scroll stops
+watcher.onStop(() => {
+  console.log('User just stopped scrolling!');
+});
+
+// Add a custom scroll listener
+const myScrollHandler = () => console.log('Scrolling...');
+watcher.onScroll(myScrollHandler);
+
+// Remove it later
+watcher.offScroll(myScrollHandler);
+
+// Also remove onStop listener
+watcher.offStop(myStopFunction);
+
+// Fully destroy the watcher
+watcher.destroy();
+```
+
+---
+
+## 🧠 Class: `TinyAfterScrollWatcher`
+
+### 🔧 Constructor
+
+```ts
+new TinyAfterScrollWatcher(scrollTarget?: Element | Window, inactivityTime?: number)
+```
+
+#### Parameters:
+
+| Name             | Type                | Default  | Description                                                            |
+| ---------------- | ------------------- | -------- | ---------------------------------------------------------------------- |
+| `scrollTarget`   | `Element \| Window` | `window` | The scrollable element to watch. Can also be the global `window`.      |
+| `inactivityTime` | `number`            | `100`    | Milliseconds to wait after the last scroll before executing the queue. |
+
+---
+
+### ⏲️ Property: `inactivityTime`
+
+* **Type:** `number`
+* **Getter/Setter**
+
+Defines how many milliseconds to wait after scroll stops before executing the queue.
+
+#### Example:
+
+```js
+watcher.inactivityTime = 500;
+console.log(watcher.inactivityTime); // 500
+```
+
+#### Throws:
+
+* `TypeError` if the value is not a finite positive number.
+
+---
+
+### 🧩 Method: `doAfterScroll(fn)`
+
+Adds a function to the queue that runs once scroll has stopped for the configured delay.
+
+```ts
+doAfterScroll(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                          |
+| ---- | -------- | ------------------------------------ |
+| `fn` | `FnData` | Function to run after scrolling ends |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🛑 Method: `onStop(fn)`
+
+Registers a function to be called **immediately after scrolling stops**, but **before** the `doAfterScroll` queue is executed.
+
+```ts
+onStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                                     |
+| ---- | -------- | ----------------------------------------------- |
+| `fn` | `FnData` | Function to call as soon as scroll has stopped. |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🔁 Method: `offStop(fn)`
+
+Removes a function previously registered with `onStop`.
+
+```ts
+offStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                        |
+| ---- | -------- | ---------------------------------- |
+| `fn` | `FnData` | Function to remove from onStop set |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🧷 Method: `onScroll(fn)`
+
+Registers a custom scroll listener on the tracked element.
+
+```ts
+onScroll(fn: OnScrollFunc): void
+```
+
+#### Parameters:
+
+| Name | Type           | Description                             |
+| ---- | -------------- | --------------------------------------- |
+| `fn` | `OnScrollFunc` | The listener function for scroll events |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🗑️ Method: `offScroll(fn)`
+
+Removes a previously registered scroll listener.
+
+```ts
+offScroll(fn: OnScrollFunc): void
+```
+
+#### Parameters:
+
+| Name | Type           | Description                   |
+| ---- | -------------- | ----------------------------- |
+| `fn` | `OnScrollFunc` | The scroll listener to remove |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 💣 Method: `destroy()`
+
+Cleans up all internal and external listeners.
+Once destroyed, the instance stops functioning and cannot be reused.
+
+```ts
+destroy(): void
+```
+
+---
+
+## 🧾 Typedefs
+
+```ts
+/**
+ * A function with no parameters and no return value.
+ */
+type FnData = () => void;
+
+/**
+ * A function that handles a scroll event.
+ * It receives a standard `Event` object when a scroll occurs.
+ */
+type OnScrollFunc = (ev: Event) => void;
+```
+
+---
+
+## 📝 Notes
+
+* `onStop` functions are called **before** the `doAfterScroll` queue.
+* The `doAfterScroll` queue runs in **LIFO** order (last-in, first-out).
+* `requestAnimationFrame` is used for efficient polling.
+* Lower `inactivityTime` makes scroll-stop detection more responsive.

package/docs/v1/libs/TinyHtml.md

@@ -1331,3 +1331,328 @@ Checks if the element is **fully inside** the viewport — meaning:
 ```js
 TinyHtml.isScrolledIntoView(element);
 ```
+
+---
+
+## 🎨 CSS Property Aliases (`cssPropAliases`)
+
+TinyHtml provides automatic conversion between `camelCase` and `kebab-case` style properties to simplify working with inline styles in HTML elements.
+
+This is useful for working with both JavaScript style names and the raw `style=""` attribute.
+
+### 🔁 Alias Mapping
+
+The object `cssPropAliases` maps JavaScript-style property names (`camelCase`) to their CSS equivalents (`kebab-case`), for example:
+
+```js
+TinyHtml.cssPropAliases.backgroundColor; // "background-color"
+```
+
+⚠️ Do not modify the internal `#cssPropAliases` object directly. Instead, use the `TinyHtml.cssPropAliases` proxy.
+
+### ✍️ Adding a New Alias
+
+To add a new alias and automatically generate the reverse mapping:
+
+```js
+TinyHtml.cssPropAliases.tinyPudding = 'tiny-pudding';
+```
+
+This will automatically make this available:
+
+```js
+TinyHtml.cssPropRevAliases['tiny-pudding']; // "tinyPudding"
+```
+
+---
+
+## ✂️ Utility Functions
+
+### 🔡 `TinyHtml.toStyleKc(str)`
+
+Converts a camelCase property to kebab-case if it exists in the alias list.
+
+```js
+TinyHtml.toStyleKc('marginLeft'); // "margin-left"
+```
+
+### 🔡 `TinyHtml.toStyleCc(str)`
+
+Converts a kebab-case property to camelCase if it exists in the reverse alias list.
+
+```js
+TinyHtml.toStyleCc('font-weight'); // "fontWeight"
+```
+
+---
+
+## 🧩 Style Methods
+
+### 🎯 `TinyHtml.setStyle(el, prop, value)`
+
+Sets one or more inline CSS properties on an element or a list of elements.
+
+```js
+TinyHtml.setStyle(element, 'backgroundColor', 'blue');
+
+TinyHtml.setStyle(element, {
+  fontSize: '14px',
+  color: 'white',
+});
+```
+
+---
+
+### 🔍 `TinyHtml.getStyle(el, prop)`
+
+Returns the value of an inline style property (not computed).
+
+```js
+TinyHtml.getStyle(element, 'backgroundColor'); // "blue"
+```
+
+---
+
+### 🧾 `TinyHtml.style(el, settings = {})`
+
+Returns all inline styles defined directly on the element (`style` attribute), as an object.
+
+You can customize the output by passing an optional settings object:
+
+* `camelCase` (`boolean`, default `false`) – If `true`, property names will be returned in camelCase format.
+* `rawAttr` (`boolean`, default `false`) – If `true`, the raw `style` attribute string will be parsed manually instead of using the element's `style` object.
+
+#### ✅ Examples
+
+```js
+TinyHtml.style(element, { rawAttr: true, camelCase: false });
+// {
+//   "background-color": "tomato",
+//   "border-radius": "10px"
+// }
+
+TinyHtml.style(element, { rawAttr: true, camelCase: true });
+// {
+//   backgroundColor: "tomato",
+//   borderRadius: "10px"
+// }
+
+TinyHtml.style(element, { rawAttr: false, camelCase: true });
+// {
+//   "backgroundColor":"tomato",
+//   "borderTopLeftRadius":"10px",
+//   "borderTopRightRadius":"10px",
+//   "borderBottomRightRadius":"10px",
+//   "borderBottomLeftRadius":"10px",
+//   "borderTopStyle":"dashed",
+//   "borderRightStyle":"dashed",
+//   "borderBottomStyle":"dashed",
+//   "borderLeftStyle":"dashed"
+// }
+```
+
+---
+
+### ❌ `TinyHtml.removeStyle(el, prop)`
+
+Removes one or more properties from an element’s inline styles.
+
+```js
+TinyHtml.removeStyle(element, 'color');
+
+TinyHtml.removeStyle(element, ['fontSize', 'padding']);
+```
+
+---
+
+### 🔁 `TinyHtml.toggleStyle(el, prop, val1, val2)`
+
+Toggles a CSS inline property between two values.
+
+```js
+TinyHtml.toggleStyle(element, 'backgroundColor', 'blue', 'red');
+```
+
+---
+
+### 🧼 `TinyHtml.clearStyle(el)`
+
+Removes all inline styles (`style=""`) from the element(s).
+
+```js
+TinyHtml.clearStyle(element);
+```
+
+---
+
+## 🧪 Reading Computed Styles
+
+TinyHtml provides multiple utilities for reading CSS styles from elements, both individually and in groups, using computed values (via `window.getComputedStyle`).
+
+---
+
+### 🧬 `TinyHtml.css(el)` / `el.css()`
+
+Returns the full computed style object for a given element.
+
+```js
+const style = TinyHtml.css(element);
+
+// or using instance:
+const style = myTinyElem.css();
+```
+
+**Returns:**
+`CSSStyleDeclaration` – all computed styles from the browser.
+
+---
+
+### 🔍 `TinyHtml.cssString(el, prop)` / `el.cssString(prop)`
+
+Returns a specific **computed CSS value as a string**.
+
+```js
+myTinyElem.cssString('marginTop');        // "10px"
+```
+
+**Returns:**
+`string | null` – The computed value of the property, or `null` if invalid.
+
+---
+
+### 📑 `TinyHtml.cssList(el, props[])` / `el.cssList(props[])`
+
+Returns a **subset of computed styles** based on a list of property names.
+
+```js
+TinyHtml.cssList(element, ['width', 'height']);
+// { width: "120px", height: "40px" }
+```
+
+**Returns:**
+`Partial<CSSStyleDeclaration>` – only the requested properties.
+
+---
+
+### 🔢 `TinyHtml.cssFloat(el, prop)` / `el.cssFloat(prop)`
+
+Returns the **computed value parsed as a float number**.
+
+```js
+myTinyElem.cssFloat('width');  // 120
+```
+
+This is useful when working with dimensions or numeric spacing.
+
+**Returns:**
+`number` – A parsed float, or `0` if invalid.
+
+---
+
+### 🔢🔢 `TinyHtml.cssFloats(el, props[])` / `el.cssFloats(props[])`
+
+Gets multiple computed CSS float values at once.
+
+```js
+myTinyElem.cssFloats(['paddingTop', 'paddingBottom']);
+// { paddingTop: 10, paddingBottom: 5 }
+```
+
+**Returns:**
+`Record<string, number>` – A mapping of property names to their float values.
+
+---
+
+## 🖱️ Focus & Blur
+
+TinyHtml provides utility methods to programmatically focus or blur HTML elements.
+
+### ✨ `TinyHtml.focus(el)` / `el.focus()`
+
+Focuses the specified element.
+
+```js
+TinyHtml.focus(element);
+// or
+tinyElem.focus();
+```
+
+---
+
+### 🌫️ `TinyHtml.blur(el)` / `el.blur()`
+
+Removes focus from the specified element.
+
+```js
+TinyHtml.blur(element);
+// or
+tinyElem.blur();
+```
+
+---
+
+## 🌐 Window Scroll & Viewport Helpers
+
+These methods let you control and query scroll positions and viewport size with simple, readable functions.
+
+---
+
+### 🔽 `TinyHtml.setWinScrollTop(value)`
+
+Scrolls the window vertically to the given pixel value.
+
+```js
+TinyHtml.setWinScrollTop(500);
+```
+
+---
+
+### ⬅️ `TinyHtml.setWinScrollLeft(value)`
+
+Scrolls the window horizontally to the given pixel value.
+
+```js
+TinyHtml.setWinScrollLeft(200);
+```
+
+---
+
+### 📏 `TinyHtml.winScrollTop()`
+
+Returns the current vertical scroll position.
+
+```js
+const y = TinyHtml.winScrollTop(); // e.g., 512
+```
+
+---
+
+### 📐 `TinyHtml.winScrollLeft()`
+
+Returns the current horizontal scroll position.
+
+```js
+const x = TinyHtml.winScrollLeft(); // e.g., 100
+```
+
+---
+
+### 🪟 `TinyHtml.winInnerHeight()`
+
+Returns the height of the visible viewport in pixels.
+
+```js
+const height = TinyHtml.winInnerHeight(); // e.g., 1080
+```
+
+---
+
+### 🪟 `TinyHtml.winInnerWidth()`
+
+Returns the width of the visible viewport in pixels.
+
+```js
+const width = TinyHtml.winInnerWidth(); // e.g., 2560
+```
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "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",