@t007/utils 0.0.5 → 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OLUWATOBILOBA OKETADE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @t007/utils
+
+> The foundational utility belt and central nervous system for the `@t007` UI ecosystem. A collection of highly optimized, zero-dependency vanilla JavaScript helpers for DOM manipulation, async resource loading, and math operations.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Tobi007-del/t007-tools/blob/main/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@t007/utils.svg)](https://www.npmjs.com/package/@t007/utils)
+
+[Report Bug](https://github.com/Tobi007-del/t007-tools/issues)
+
+---
+
+## Table of contents
+
+- [@t007/utils](#t007utils)
+  - [Table of contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Features](#features)
+  - [Tech Stack](#tech-stack)
+  - [Getting Started](#getting-started)
+  - [Usage](#usage)
+  - [Author](#author)
+  - [Acknowledgments](#acknowledgments)
+
+---
+
+## Overview
+
+**@t007/utils** is the core engine that powers the rest of the `@t007` UI packages (`@t007/toast`, `@t007/dialog`, `@t007/input`). It abstracts away the heavy lifting of dynamic DOM creation, cross-browser event handling, and asynchronous resource injection.
+
+### Why @t007/utils?
+
+- ✅ **Tree-Shakeable:** Every utility is exported individually. Modern bundlers will only compile the exact code you import, resulting in zero bloat.
+- ✅ **Shared Memory:** By acting as a peer dependency for the other `@t007` packages, it ensures that your application doesn't download duplicate helper functions.
+- ✅ **Zero Frameworks:** 100% pure vanilla JavaScript. 
+
+---
+
+## Features
+
+- **DOM Engineering**: High-performance element creation and attribute binding.
+- **Resource Management**: Asynchronous script and stylesheet injection with duplicate-load prevention.
+- **Class Management**: Automatic method binding for class-based UI components.
+- **Math & Physics**: Clamping and coordinate tracking used by gesture-driven UI components.
+- **Global Injection**: Safely initializes the global `t007` object across environments.
+
+---
+
+## Tech Stack
+
+### Built with
+
+- Vanilla JavaScript (ES6+)
+- Bundled via `tsup` (ESM, CJS, IIFE outputs)
+- Built for extreme execution speed and minimal byte size.
+
+---
+
+## Getting Started
+
+### Installation
+
+Install via your preferred package manager:
+
+```bash
+npm install @t007/utils
+# or
+yarn add @t007/utils
+# or
+pnpm add @t007/utils
+````
+
+-----
+
+## Usage
+
+### Modern Bundlers (ESM)
+
+Because the library uses modern ECMAScript Modules, you can destruct exactly what you need.
+
+```javascript
+// Vite / Webpack / Next.js
+import { createEl, loadResource, uid } from '@t007/utils';
+
+// Generate a complex DOM element in one line
+const myBtn = createEl('button', { className: 'my-custom-btn', textContent: 'Click Me' });
+
+// Inject a stylesheet dynamically
+await loadResource('https://cdn.example.com/styles.css, 'link');
+```
+
+-----
+
+## Author
+
+  - Developer - [Oketade Oluwatobiloba (Tobi007-del)](https://github.com/Tobi007-del)
+  - Project - [t007-tools](https://github.com/Tobi007-del/t007-tools)
+
+## Acknowledgments
+
+The invisible backbone of the `@t007` ecosystem. Engineered to make complex DOM operations feel effortless.

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  VIRTUAL_RESOURCE: () => VIRTUAL_RESOURCE,
   assignEl: () => assignEl,
   bindAllMethods: () => bindAllMethods,
   clamp: () => clamp,
@@ -36,11 +37,6 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/core/num.ts
-function clamp(min = 0, val, max = Infinity) {
-  return Math.min(Math.max(val, min), max);
-}
-
 // src/core/str.ts
 function uid(prefix = "") {
   return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
@@ -71,8 +67,11 @@ function assignEl(el, props, dataset, styles) {
     for (const k of Object.keys(styles)) if (styles[k] !== void 0) el.style[k] = styles[k];
   }
 }
-function loadResource(src, type = "style", { module: module2, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts = 3, retryKey = false } = {}, w = window) {
-  w.t007._resourceCache ??= {};
+var VIRTUAL_RESOURCE = /* @__PURE__ */ Symbol.for("T007_VIRTUAL_RESOURCE");
+function loadResource(req, type = "style", { module: module2, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts = 3, retryKey = false } = {}, w = window) {
+  w.t007 ??= {}, w.t007._resourceCache ??= {};
+  if (req === VIRTUAL_RESOURCE || "symbol" === typeof req) return Promise.resolve();
+  const src = req;
   if (w.t007._resourceCache[src]) return w.t007._resourceCache[src];
   const existing = type === "script" ? Array.prototype.find.call(w.document.scripts, (s) => isSameURL(s.src, src)) : type === "style" ? Array.prototype.find.call(w.document.styleSheets, (s) => isSameURL(s.href, src)) : null;
   if (existing) return w.t007._resourceCache[src] = Promise.resolve(existing);
@@ -97,6 +96,11 @@ function loadResource(src, type = "style", { module: module2, media, crossOrigin
   return w.t007._resourceCache[src];
 }
 
+// src/core/num.ts
+function clamp(min = 0, val, max = Infinity) {
+  return Math.min(Math.max(val, min), max);
+}
+
 // src/mixins/methodist.ts
 function onAllMethods(owner, callback) {
   let proto = owner;
@@ -221,15 +225,17 @@ var removeScrollAssist = (el) => t007._scrollers.get(el)?.destroy();
 // src/index.ts
 if (typeof window !== "undefined") {
   window.t007 ??= {};
+  t007.VIRTUAL_RESOURCE = VIRTUAL_RESOURCE;
   window.T007_TOAST_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest`;
   window.T007_INPUT_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest`;
   window.T007_DIALOG_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest`;
-  window.T007_TOAST_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest/dist/index.css`;
-  window.T007_INPUT_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest/dist/index.css`;
-  window.T007_DIALOG_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest/dist/index.css`;
+  window.T007_TOAST_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest/dist/index.min.css`;
+  window.T007_INPUT_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest/dist/index.min.css`;
+  window.T007_DIALOG_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest/dist/index.min.css`;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
   clamp,

package/dist/index.d.cts

@@ -27,6 +27,8 @@ declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
 
 declare global {
   interface T007Namespace {
+    VIRTUAL_RESOURCE: unique symbol;
+
     _resourceCache: Partial<Record<string, Promise<HTMLElement | void>>>;
     _scrollers?: WeakMap<HTMLElement, ScrollAssistControl>;
     _scroller_r_observer?: ResizeObserver;
@@ -71,11 +73,12 @@ declare function createEl<K extends keyof HTMLElementTagNameMap>(tag: K, props?:
 declare function createEl(tag: string, props?: Partial<HTMLElement>, dataset?: Dataset, styles?: Style): HTMLElement | null;
 declare function assignEl<K extends keyof HTMLElementTagNameMap>(el?: HTMLElementTagNameMap[K], props?: Partial<HTMLElementTagNameMap[K]>, dataset?: Dataset, styles?: Style): void;
 declare function assignEl(el?: HTMLElement | null, props?: Partial<HTMLElement>, dataset?: Dataset, styles?: Style): void;
-declare function loadResource(src: string, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
+declare const VIRTUAL_RESOURCE: unique symbol;
+declare function loadResource(req: string | symbol, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
 
 declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void): void;
 declare function bindAllMethods(owner: any): void;
 declare function guardAllMethods(owner: any, guardFn?: (fn: Function) => Function, bound?: boolean): void;
 declare function guardMethod<T extends Function>(fn: T, onError?: (e: any) => void): T;
 
-export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, initScrollAssist, initVScrollerator, isSameURL, loadResource, onAllMethods, removeScrollAssist, uid };
+export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, initScrollAssist, initVScrollerator, isSameURL, loadResource, onAllMethods, removeScrollAssist, uid };

package/dist/index.d.ts

@@ -27,6 +27,8 @@ declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
 
 declare global {
   interface T007Namespace {
+    VIRTUAL_RESOURCE: unique symbol;
+
     _resourceCache: Partial<Record<string, Promise<HTMLElement | void>>>;
     _scrollers?: WeakMap<HTMLElement, ScrollAssistControl>;
     _scroller_r_observer?: ResizeObserver;
@@ -71,11 +73,12 @@ declare function createEl<K extends keyof HTMLElementTagNameMap>(tag: K, props?:
 declare function createEl(tag: string, props?: Partial<HTMLElement>, dataset?: Dataset, styles?: Style): HTMLElement | null;
 declare function assignEl<K extends keyof HTMLElementTagNameMap>(el?: HTMLElementTagNameMap[K], props?: Partial<HTMLElementTagNameMap[K]>, dataset?: Dataset, styles?: Style): void;
 declare function assignEl(el?: HTMLElement | null, props?: Partial<HTMLElement>, dataset?: Dataset, styles?: Style): void;
-declare function loadResource(src: string, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
+declare const VIRTUAL_RESOURCE: unique symbol;
+declare function loadResource(req: string | symbol, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
 
 declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void): void;
 declare function bindAllMethods(owner: any): void;
 declare function guardAllMethods(owner: any, guardFn?: (fn: Function) => Function, bound?: boolean): void;
 declare function guardMethod<T extends Function>(fn: T, onError?: (e: any) => void): T;
 
-export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, initScrollAssist, initVScrollerator, isSameURL, loadResource, onAllMethods, removeScrollAssist, uid };
+export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, initScrollAssist, initVScrollerator, isSameURL, loadResource, onAllMethods, removeScrollAssist, uid };

package/dist/index.js

@@ -1,8 +1,3 @@
-// src/core/num.ts
-function clamp(min = 0, val, max = Infinity) {
-  return Math.min(Math.max(val, min), max);
-}
-
 // src/core/str.ts
 function uid(prefix = "") {
   return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
@@ -33,8 +28,11 @@ function assignEl(el, props, dataset, styles) {
     for (const k of Object.keys(styles)) if (styles[k] !== void 0) el.style[k] = styles[k];
   }
 }
-function loadResource(src, type = "style", { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts = 3, retryKey = false } = {}, w = window) {
-  w.t007._resourceCache ??= {};
+var VIRTUAL_RESOURCE = /* @__PURE__ */ Symbol.for("T007_VIRTUAL_RESOURCE");
+function loadResource(req, type = "style", { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts = 3, retryKey = false } = {}, w = window) {
+  w.t007 ??= {}, w.t007._resourceCache ??= {};
+  if (req === VIRTUAL_RESOURCE || "symbol" === typeof req) return Promise.resolve();
+  const src = req;
   if (w.t007._resourceCache[src]) return w.t007._resourceCache[src];
   const existing = type === "script" ? Array.prototype.find.call(w.document.scripts, (s) => isSameURL(s.src, src)) : type === "style" ? Array.prototype.find.call(w.document.styleSheets, (s) => isSameURL(s.href, src)) : null;
   if (existing) return w.t007._resourceCache[src] = Promise.resolve(existing);
@@ -59,6 +57,11 @@ function loadResource(src, type = "style", { module, media, crossOrigin, integri
   return w.t007._resourceCache[src];
 }
 
+// src/core/num.ts
+function clamp(min = 0, val, max = Infinity) {
+  return Math.min(Math.max(val, min), max);
+}
+
 // src/mixins/methodist.ts
 function onAllMethods(owner, callback) {
   let proto = owner;
@@ -183,14 +186,16 @@ var removeScrollAssist = (el) => t007._scrollers.get(el)?.destroy();
 // src/index.ts
 if (typeof window !== "undefined") {
   window.t007 ??= {};
+  t007.VIRTUAL_RESOURCE = VIRTUAL_RESOURCE;
   window.T007_TOAST_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest`;
   window.T007_INPUT_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest`;
   window.T007_DIALOG_JS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest`;
-  window.T007_TOAST_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest/dist/index.css`;
-  window.T007_INPUT_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest/dist/index.css`;
-  window.T007_DIALOG_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest/dist/index.css`;
+  window.T007_TOAST_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/toast@latest/dist/index.min.css`;
+  window.T007_INPUT_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/input@latest/dist/index.min.css`;
+  window.T007_DIALOG_CSS_SRC ??= `https://cdn.jsdelivr.net/npm/@t007/dialog@latest/dist/index.min.css`;
 }
 export {
+  VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
   clamp,

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@t007/utils",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "High-performance, zero-dependency utility functions for the t007 ecosystem.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tobi007-del/t007-tools.git",
+    "url": "git+https://github.com/Tobi007-del/t007-tools.git",
     "directory": "packages/utils"
   },
-  "homepage": "https://github.com/tobi007-del/t007-tools/tree/main/packages/utils#readme",
+  "homepage": "https://github.com/Tobi007-del/t007-tools/blob/main/packages/utils#readme",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -24,20 +24,24 @@
       "default": "./dist/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "shx cp ../../LICENSE ."
   },
   "files": [
     "dist"
   ],
   "keywords": [
     "t007",
+    "ecosystem",
+    "vanilla-js",
     "utils",
     "helpers",
     "dom-manipulation",
-    "ecosystem",
-    "zero-dependency",
-    "performance",
-    "shared-logic"
+    "shared-logic",
+    "performance"
   ]
 }