tiny-essentials 1.11.0 → 1.12.0

package/docs/v1/libs/TinyUploadClicker.md

@@ -0,0 +1,108 @@
+# 📦 TinyUploadClicker
+
+A tiny but good JavaScript utility that lets you bind any clickable element (buttons, icons, divs, etc.) to trigger a hidden `<input type="file">`. This allows full control over file upload behavior, visual customization, and events — without ever showing the native file input element.
+
+---
+
+## 🚀 Features
+
+* 🎯 **Use any HTML element** as a file input trigger
+* 🎨 **Custom attributes and styles** for the input element
+* 🔁 **Multiple file selection** support
+* 🧠 **Strong runtime validations** with helpful errors
+* 🪝 **Lifecycle hooks** for click and file selection
+* 🧹 **Clean `destroy()` method** to remove everything
+* 🔐 **No dependencies**, pure JS
+
+---
+
+## ✨ Example
+
+```js
+const uploader = new TinyUploadClicker({
+  triggers: '#uploadBtn',
+  accept: ['.png', '.jpg'],
+  multiple: true,
+  inputAttributes: { 'data-role': 'upload' },
+  inputStyles: { display: 'none' },
+  onClick: (el) => console.log('Trigger clicked:', el),
+  onFileLoad: (files, el) => console.log('Files selected:', files)
+});
+
+// Later, cleanup:
+uploader.destroy();
+```
+
+---
+
+## 🧱 Constructor
+
+### `new TinyUploadClicker(options)`
+
+Creates a new instance of the upload click manager.
+
+#### 🔐 Throws
+
+* `TypeError` if any part of the config is invalid
+* `Error` if a trigger selector resolves to no element
+
+#### 💡 Parameters
+
+| Name      | Type                                      | Required | Description                                 |
+| --------- | ----------------------------------------- | -------- | ------------------------------------------- |
+| `options` | [`UploaderConfig`](#-uploaderconfig-type) | ✅ Yes    | Configuration object for the upload clicker |
+
+---
+
+## 🧩 `UploaderConfig` Type
+
+```ts
+type UploaderConfig = {
+  triggers: string | HTMLElement | Array<string | HTMLElement>,
+  multiple?: boolean,
+  accept?: string | string[],
+  inputAttributes?: Record<string, string>,
+  inputStyles?: Partial<CSSStyleDeclaration>,
+  onClick?: ((triggerElement: HTMLElement) => void) | null,
+  onFileLoad?: ((files: FileList, triggerElement: HTMLElement) => void) | null
+}
+```
+
+| Property          | Type                                                    | Default               | Description                                                           |
+| ----------------- | ------------------------------------------------------- | --------------------- | --------------------------------------------------------------------- |
+| `triggers`        | `string \| HTMLElement \| Array<string \| HTMLElement>` | —                     | Elements (or selectors) that will trigger file selection when clicked |
+| `multiple`        | `boolean`                                               | `false`               | Whether multiple files can be selected                                |
+| `accept`          | `string \| string[]`                                    | `""`                  | Accepted file types (e.g., `".png"` or `"image/*"`)                   |
+| `inputAttributes` | `Record<string, string>`                                | `{}`                  | Extra attributes to apply to the `<input type="file">`                |
+| `inputStyles`     | `Partial<CSSStyleDeclaration>`                          | `{ display: 'none' }` | Custom inline styles for the hidden input                             |
+| `onClick`         | `(HTMLElement) => void \| null`                         | `null`                | Hook triggered when a trigger is clicked (before file dialog opens)   |
+| `onFileLoad`      | `(FileList, HTMLElement) => void \| null`               | `null`                | Hook triggered after files are selected                               |
+
+---
+
+## 🔧 Methods
+
+### `destroy(): void`
+
+Destroys all internal listeners and DOM elements created by the instance.
+Cleans up memory and detaches everything from the DOM.
+
+---
+
+## 🛡️ Runtime Validations
+
+The constructor performs strict type validation and helpful error reporting:
+
+* ❌ Missing or invalid `triggers` throws immediately.
+* ❌ Selectors that resolve to `null` will throw.
+* ❌ Invalid types for `accept`, `onClick`, `onFileLoad`, `inputStyles`, and `inputAttributes` are rejected.
+* ✅ Supports string or array for `accept`.
+
+---
+
+## 🛠️ Internal Design
+
+* Each trigger gets its own file input.
+* Inputs are stored in a `WeakMap<HTMLElement, HTMLInputElement>`.
+* After a file is selected, the input is reset so the same file can be selected again.
+* All inputs are appended to `document.body` and styled invisibly by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.11.0",
+  "version": "1.12.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",
@@ -12,6 +12,7 @@
     "test:mjs:jsoncolor": "node test/index.mjs colorStringify",
     "test:mjs:ratelimit": "node test/index.mjs rateLimit",
     "test:mjs:levelup": "node test/index.mjs levelUp",
+    "test:mjs:filemanager": "node test/index.mjs fileManager",
     "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/*",
@@ -22,7 +23,8 @@
     "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",
+    "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",
     "clean": "rm -rf dist",
@@ -36,6 +38,14 @@
     ".": {
       "require": "./dist/v1/index.cjs",
       "import": "./dist/v1/index.mjs"
+    },
+    "./libs": {
+      "require": "./dist/v1/libs/index.cjs",
+      "import": "./dist/v1/libs/index.mjs"
+    },
+    "./basics": {
+      "require": "./dist/v1/basics/index.cjs",
+      "import": "./dist/v1/basics/index.mjs"
     }
   },
   "repository": {