tiny-essentials 1.12.2 → 1.13.1

package/docs/v1/libs/TinyDomReadyManager.md

@@ -0,0 +1,198 @@
+# 🕒 TinyDomReadyManager
+
+A flexible, customizable JavaScript class to execute code **only when the DOM is ready**, or when additional asynchronous requirements (like Promises or asset loads) are met.
+Supports **prioritized callbacks**, **filters**, and now even **DOM-only fast execution**!
+
+---
+
+## 🧠 Type Definitions
+
+### `Fn` 🛠️
+
+```ts
+type Fn = () => void;
+```
+
+A basic function to be executed once the system is ready.
+
+---
+
+### `FnFilter` 🔍
+
+```ts
+type FnFilter = () => boolean;
+```
+
+A conditional function that decides whether a handler should be executed.
+Returns `true` to allow execution, or `false` to skip.
+
+---
+
+### `Handler` 🧩
+
+```ts
+interface Handler {
+  fn: Fn;
+  once: boolean;
+  priority: number;
+  filter: FnFilter | null;
+  domOnly: boolean;
+}
+```
+
+Describes a registered handler and how it should be treated during readiness flow.
+
+---
+
+## 🚀 Class: `TinyDomReadyManager`
+
+### `init()` 🕓
+
+```ts
+init(): void
+```
+
+Initializes the manager and waits for the `DOMContentLoaded` event.
+If the DOM is already ready, it triggers immediately.
+
+* ⚠️ Throws an `Error` if called more than once.
+
+---
+
+### `addPromise(promise)` ⏳
+
+```ts
+addPromise(promise: Promise<any>): void
+```
+
+Adds a custom `Promise` that delays full readiness.
+This allows tasks like `fetch()` or image preloading to block late-stage handlers.
+
+* ⚠️ Throws a `TypeError` if `promise` is not a real `Promise`.
+
+---
+
+### `onReady(fn, options?)` ✅
+
+```ts
+onReady(fn: Fn, options?: {
+  once?: boolean;
+  priority?: number;
+  filter?: FnFilter | null;
+  domOnly?: boolean;
+}): void
+```
+
+Registers a function to run at the right moment:
+
+| Option     | Type               | Default | Description                                                              |
+| ---------- | ------------------ | ------- | ------------------------------------------------------------------------ |
+| `once`     | `boolean`          | `true`  | Whether to execute only once                                             |
+| `priority` | `number`           | `0`     | Higher values run earlier                                                |
+| `filter`   | `FnFilter \| null` | `null`  | Optional condition before executing                                      |
+| `domOnly`  | `boolean`          | `false` | 🚀 If `true`, runs immediately after **DOM is ready**, skipping promises |
+
+* ⚠️ Throws a `TypeError` if `fn` is not a function.
+
+---
+
+### `isReady()` 📡
+
+```ts
+isReady(): boolean
+```
+
+Returns `true` only after both the DOM is ready **and** all added promises have resolved.
+
+---
+
+### `isDomReady()` 🧱
+
+```ts
+isDomReady(): boolean
+```
+
+Returns `true` if the DOM is already ready (i.e., `DOMContentLoaded` has fired).
+Returns `false` if the DOM is still loading.
+
+> ✅ Useful when you want to know *just* when the document is interactive, regardless of async operations.
+
+---
+
+## 🧪 Readiness Phases
+
+| Phase           | Description                              |
+| --------------- | ---------------------------------------- |
+| **DOM Ready**   | Triggers `domOnly: true` handlers        |
+| **Fully Ready** | Triggers all normal `onReady()` handlers |
+
+---
+
+## 💡 Example Usage
+
+### Basic Usage
+
+```js
+import TinyDomReadyManager from './TinyDomReadyManager.js';
+
+const manager = new TinyDomReadyManager();
+
+manager.onReady(() => {
+  console.log('Ready after DOM + Promises!');
+});
+
+manager.addPromise(fetch('/config.json'));
+manager.init();
+```
+
+---
+
+### DOM-Only Handler (Faster)
+
+```js
+manager.onReady(() => {
+  console.log('DOM is ready, skipping Promises!');
+}, { domOnly: true, priority: 100 });
+```
+
+---
+
+### Conditional + Prioritized
+
+```js
+manager.onReady(() => {
+  console.log('Only runs if in dark mode');
+}, {
+  priority: 5,
+  filter: () => document.documentElement.classList.contains('dark')
+});
+```
+
+---
+
+### Mixing Both Types
+
+```js
+manager.onReady(() => {
+  console.log('DOM-only logic A');
+}, { domOnly: true, priority: 10 });
+
+manager.onReady(() => {
+  console.log('DOM-only logic B');
+}, { domOnly: true, priority: 5 });
+
+manager.onReady(() => {
+  console.log('Waits for API call');
+});
+
+manager.addPromise(fetch('/api/user'));
+manager.init();
+```
+
+---
+
+## 📌 Notes
+
+* `domOnly` handlers are ideal for UI setup or event binding.
+* Regular handlers are best for things that depend on data loading or external states.
+* All handlers are executed safely, and exceptions are caught with warning logs.

package/package.json

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