@t007/utils 0.0.22 → 0.0.24

package/dist/index.d.cts

@@ -1,54 +1,93 @@
 export { KeyStruct, assignEl, bindAllMethods, clamp, cleanKeyCombo, createEl, formatKeyForDisplay, formatKeyShortcutsForDisplay, getTermsForKey, guardAllMethods, guardMethod, isObj, keyEventAllowed, keysSettings, matchKeys, onAllMethods, parseForARIAKS, parseKeyCombo, requestAnimationFrame, setInterval, setTimeout, stringifyKeyEvent } from 'sia-reactor/utils';
 
+/** Configuration for the vertical edge-scrolling helper. */
 interface ScrolleratorOptions {
+    /** Starting lines-per-second speed. */
     baseSpeed?: number;
+    /** Maximum accelerated speed. */
     maxSpeed?: number;
+    /** Delay before acceleration kicks in. */
     stepDelay?: number;
+    /** Base frame rate used to estimate movement. */
     baseRate?: number;
+    /** Approximate line height in pixels. */
     lineHeight?: number;
+    /** Edge margin that triggers scrolling. */
     margin?: number;
+    /** Scroll container or window target. */
     car?: Window | HTMLElement;
 }
+/** Scrolling controls returned by initVScrollerator. */
 interface Scrollerator {
+    /** Trigger a scroll frame and return the computed distance. */
     drive: (clientY: number, brake?: boolean, offsetY?: number) => number;
+    /** Reset speed and timers. */
     reset: () => void;
 }
+/** Create an edge-driven vertical scrolling controller.
+ * @param options Scrollerator configuration.
+ * @returns Drive and reset controls for the controller.
+ */
 declare function initVScrollerator({ baseSpeed, maxSpeed, stepDelay, baseRate, lineHeight, margin, car }?: ScrolleratorOptions): Scrollerator;
+/** Scroll assist control object returned by initScrollAssist. */
 interface ScrollAssistControl {
+    /** Recompute assist visibility. */
     update: () => void;
+    /** Tear down observers and assist elements. */
     destroy: () => void;
 }
+/** Configuration for scroll assist overlays. */
 interface ScrollAssistOptions {
+    /** Scroll speed in pixels per second. */
     pxPerSecond?: number;
+    /** Class name applied to assist overlays. */
     assistClassName?: string;
+    /** Enable vertical assist overlays. */
     vertical?: boolean;
+    /** Enable horizontal assist overlays. */
     horizontal?: boolean;
 }
+/** Attach directional scroll assist overlays to an element.
+ * @param el Scrollable element to enhance.
+ * @param options Scroll assist configuration.
+ * @returns Scroll assist controls or void when the element is already managed.
+ */
 declare function initScrollAssist(el: HTMLElement, { pxPerSecond, assistClassName, vertical, horizontal }?: ScrollAssistOptions): ScrollAssistControl | void;
+/** Remove scroll assist from an element.
+ * @param el Target element.
+ */
 declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
 
 declare global {
   interface T007Namespace {
+    /** Symbol used to mark virtual resources that should not load a real asset. */
     VIRTUAL_RESOURCE: symbol;
-
+    /** Cache used to deduplicate resource loading promises. */
     _resourceCache: Partial<Record<string, Promise<HTMLElement | void>>>;
+    /** Active scroll assist controllers keyed by element. */
     _scrollers?: WeakMap<HTMLElement, ScrollAssistControl>;
+    /** Resize observer used by scroll assist controllers. */
     _scroller_r_observer?: ResizeObserver;
+    /** Mutation observer used by scroll assist controllers. */
     _scroller_m_observer?: MutationObserver;
   }
-
   interface Window {
+    /** Shared T007 namespace. */
     t007: T007Namespace;
-
+    /** CDN entrypoint for @t007/toast. */
     T007_TOAST_JS_SRC?: string;
+    /** CDN entrypoint for @t007/input. */
     T007_INPUT_JS_SRC?: string;
+    /** CDN entrypoint for @t007/dialog. */
     T007_DIALOG_JS_SRC?: string;
-    
+    /** CDN stylesheet for @t007/toast. */
     T007_TOAST_CSS_SRC?: string;
+    /** CDN stylesheet for @t007/input. */
     T007_INPUT_CSS_SRC?: string;
+    /** CDN stylesheet for @t007/dialog. */
     T007_DIALOG_CSS_SRC?: string;
   }
-
+  /** Shared T007 namespace on the global object. */
   var t007: T007Namespace;
 }
 
@@ -64,40 +103,98 @@ declare function isIter<T = unknown>(obj: any): obj is Iterable<T>;
 declare function isFunc<T extends Function = Function>(val: any): val is T;
 declare function inBoolArrOpt(opt: any, str: string): boolean;
 
+/** Create a short unique string with an optional prefix.
+ * @param prefix Prefix added to the generated id.
+ * @returns A browser-safe unique id string.
+ */
 declare function uid(prefix?: string): string;
+/** Compare two URLs after normalizing origin, pathname, and separators.
+ * @param src1 First URL or path.
+ * @param src2 Second URL or path.
+ * @returns True when both references point to the same resource.
+ */
 declare function isSameURL(src1: unknown, src2: unknown): boolean;
 
 interface LimitedOptions {
-    key?: string /** Key for localStorage persistence (if omitted, uses session-only) */;
-    maxTimes?: number /** Max times to call (default: 1) */;
+    /** Storage key used to persist call counts. */
+    key?: string;
+    /** Maximum number of allowed calls. */
+    maxTimes?: number;
 }
 interface LimitedHandle<T extends (...args: any[]) => any> {
+    /** Call the wrapped function with the original arguments. */
     (...args: Parameters<T>): ReturnType<T> | void;
+    /** Number of calls already consumed in the current session. */
     count: number;
+    /** Number of calls left before the limit is reached. */
     left: number;
+    /** Reset the call counter. */
     reset: () => void;
+    /** Consume the full allowance and block further calls. */
     block: () => void;
 }
+/** Limit how many times a function may run.
+ * @param FN_KEY Storage namespace used to persist the counter.
+ * @param fn Function to wrap.
+ * @param opts Call limit settings or a storage key string.
+ * @returns Wrapped function with count, reset, and block helpers.
+ */
 declare function limited<T extends (...args: any[]) => any>(FN_KEY: string, fn: T, opts?: LimitedOptions | string): LimitedHandle<T>;
+/** Resolve on the next task tick.
+ * @param timeout Delay in milliseconds.
+ * @returns Promise that resolves after the timeout.
+ */
 declare const mockAsync: (timeout?: number) => Promise<void>;
+/** Resolve on the next animation frame.
+ * @param w Window-like object used for scheduling.
+ * @returns Promise that resolves on the next frame.
+ */
 declare const breath: (w?: Window & typeof globalThis) => Promise<unknown>;
+/** Resolve after two animation frames.
+ * @param w Window-like object used for scheduling.
+ * @returns Promise that resolves after layout has had two frames to settle.
+ */
 declare const deepBreath: (w?: Window & typeof globalThis) => Promise<unknown>;
+/** Run cleanup immediately or on abort, then return the callable cleanup.
+ * @param cleanup Cleanup function to protect.
+ * @param signal Optional abort signal.
+ * @returns The wrapped cleanup function.
+ */
 declare function bindCleanupToSignal<Cb extends () => any>(cleanup: Cb, signal?: AbortSignal): Cb;
 
+/** Resource type accepted by loadResource. */
 type ResourceType = "style" | "script" | string;
+/** Options used when loading a script or stylesheet resource. */
 type LoadResourceOptions = Partial<{
+    /** Load the script as a module. */
     module: boolean;
+    /** Media query applied to loaded stylesheets. */
     media: string;
+    /** crossorigin attribute for the resource element. */
     crossOrigin: "anonymous" | "use-credentials" | string | null;
+    /** Subresource integrity hash. */
     integrity: string;
+    /** Referrer policy for the resource element. */
     referrerPolicy: "no-referrer" | "origin" | "strict-origin-when-cross-origin" | string;
+    /** nonce attribute for CSP-enabled environments. */
     nonce: string;
+    /** fetchpriority hint for the browser. */
     fetchPriority: "high" | "low" | "auto";
+    /** Number of attempts before rejecting. */
     attempts: number;
+    /** Cache-busting retry token key. */
     retryKey: boolean | string;
 }>;
 
+/** Virtual resource marker used to skip real network loading. */
 declare const VIRTUAL_RESOURCE: symbol;
+/** Load a stylesheet or script into the current document with retry support.
+ * @param req Resource URL or virtual resource symbol.
+ * @param type Resource type to load.
+ * @param options Resource loading options.
+ * @param w Window-like target used for DOM insertion.
+ * @returns Promise resolving to the created element or void.
+ */
 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>;
 
 export { type LimitedHandle, type LimitedOptions, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, VIRTUAL_RESOURCE, bindCleanupToSignal, breath, deepBreath, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isPOJO, isSameURL, isStr, isSym, limited, loadResource, mockAsync, removeScrollAssist, uid };

package/dist/index.d.ts

@@ -1,54 +1,93 @@
 export { KeyStruct, assignEl, bindAllMethods, clamp, cleanKeyCombo, createEl, formatKeyForDisplay, formatKeyShortcutsForDisplay, getTermsForKey, guardAllMethods, guardMethod, isObj, keyEventAllowed, keysSettings, matchKeys, onAllMethods, parseForARIAKS, parseKeyCombo, requestAnimationFrame, setInterval, setTimeout, stringifyKeyEvent } from 'sia-reactor/utils';
 
+/** Configuration for the vertical edge-scrolling helper. */
 interface ScrolleratorOptions {
+    /** Starting lines-per-second speed. */
     baseSpeed?: number;
+    /** Maximum accelerated speed. */
     maxSpeed?: number;
+    /** Delay before acceleration kicks in. */
     stepDelay?: number;
+    /** Base frame rate used to estimate movement. */
     baseRate?: number;
+    /** Approximate line height in pixels. */
     lineHeight?: number;
+    /** Edge margin that triggers scrolling. */
     margin?: number;
+    /** Scroll container or window target. */
     car?: Window | HTMLElement;
 }
+/** Scrolling controls returned by initVScrollerator. */
 interface Scrollerator {
+    /** Trigger a scroll frame and return the computed distance. */
     drive: (clientY: number, brake?: boolean, offsetY?: number) => number;
+    /** Reset speed and timers. */
     reset: () => void;
 }
+/** Create an edge-driven vertical scrolling controller.
+ * @param options Scrollerator configuration.
+ * @returns Drive and reset controls for the controller.
+ */
 declare function initVScrollerator({ baseSpeed, maxSpeed, stepDelay, baseRate, lineHeight, margin, car }?: ScrolleratorOptions): Scrollerator;
+/** Scroll assist control object returned by initScrollAssist. */
 interface ScrollAssistControl {
+    /** Recompute assist visibility. */
     update: () => void;
+    /** Tear down observers and assist elements. */
     destroy: () => void;
 }
+/** Configuration for scroll assist overlays. */
 interface ScrollAssistOptions {
+    /** Scroll speed in pixels per second. */
     pxPerSecond?: number;
+    /** Class name applied to assist overlays. */
     assistClassName?: string;
+    /** Enable vertical assist overlays. */
     vertical?: boolean;
+    /** Enable horizontal assist overlays. */
     horizontal?: boolean;
 }
+/** Attach directional scroll assist overlays to an element.
+ * @param el Scrollable element to enhance.
+ * @param options Scroll assist configuration.
+ * @returns Scroll assist controls or void when the element is already managed.
+ */
 declare function initScrollAssist(el: HTMLElement, { pxPerSecond, assistClassName, vertical, horizontal }?: ScrollAssistOptions): ScrollAssistControl | void;
+/** Remove scroll assist from an element.
+ * @param el Target element.
+ */
 declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
 
 declare global {
   interface T007Namespace {
+    /** Symbol used to mark virtual resources that should not load a real asset. */
     VIRTUAL_RESOURCE: symbol;
-
+    /** Cache used to deduplicate resource loading promises. */
     _resourceCache: Partial<Record<string, Promise<HTMLElement | void>>>;
+    /** Active scroll assist controllers keyed by element. */
     _scrollers?: WeakMap<HTMLElement, ScrollAssistControl>;
+    /** Resize observer used by scroll assist controllers. */
     _scroller_r_observer?: ResizeObserver;
+    /** Mutation observer used by scroll assist controllers. */
     _scroller_m_observer?: MutationObserver;
   }
-
   interface Window {
+    /** Shared T007 namespace. */
     t007: T007Namespace;
-
+    /** CDN entrypoint for @t007/toast. */
     T007_TOAST_JS_SRC?: string;
+    /** CDN entrypoint for @t007/input. */
     T007_INPUT_JS_SRC?: string;
+    /** CDN entrypoint for @t007/dialog. */
     T007_DIALOG_JS_SRC?: string;
-    
+    /** CDN stylesheet for @t007/toast. */
     T007_TOAST_CSS_SRC?: string;
+    /** CDN stylesheet for @t007/input. */
     T007_INPUT_CSS_SRC?: string;
+    /** CDN stylesheet for @t007/dialog. */
     T007_DIALOG_CSS_SRC?: string;
   }
-
+  /** Shared T007 namespace on the global object. */
   var t007: T007Namespace;
 }
 
@@ -64,40 +103,98 @@ declare function isIter<T = unknown>(obj: any): obj is Iterable<T>;
 declare function isFunc<T extends Function = Function>(val: any): val is T;
 declare function inBoolArrOpt(opt: any, str: string): boolean;
 
+/** Create a short unique string with an optional prefix.
+ * @param prefix Prefix added to the generated id.
+ * @returns A browser-safe unique id string.
+ */
 declare function uid(prefix?: string): string;
+/** Compare two URLs after normalizing origin, pathname, and separators.
+ * @param src1 First URL or path.
+ * @param src2 Second URL or path.
+ * @returns True when both references point to the same resource.
+ */
 declare function isSameURL(src1: unknown, src2: unknown): boolean;
 
 interface LimitedOptions {
-    key?: string /** Key for localStorage persistence (if omitted, uses session-only) */;
-    maxTimes?: number /** Max times to call (default: 1) */;
+    /** Storage key used to persist call counts. */
+    key?: string;
+    /** Maximum number of allowed calls. */
+    maxTimes?: number;
 }
 interface LimitedHandle<T extends (...args: any[]) => any> {
+    /** Call the wrapped function with the original arguments. */
     (...args: Parameters<T>): ReturnType<T> | void;
+    /** Number of calls already consumed in the current session. */
     count: number;
+    /** Number of calls left before the limit is reached. */
     left: number;
+    /** Reset the call counter. */
     reset: () => void;
+    /** Consume the full allowance and block further calls. */
     block: () => void;
 }
+/** Limit how many times a function may run.
+ * @param FN_KEY Storage namespace used to persist the counter.
+ * @param fn Function to wrap.
+ * @param opts Call limit settings or a storage key string.
+ * @returns Wrapped function with count, reset, and block helpers.
+ */
 declare function limited<T extends (...args: any[]) => any>(FN_KEY: string, fn: T, opts?: LimitedOptions | string): LimitedHandle<T>;
+/** Resolve on the next task tick.
+ * @param timeout Delay in milliseconds.
+ * @returns Promise that resolves after the timeout.
+ */
 declare const mockAsync: (timeout?: number) => Promise<void>;
+/** Resolve on the next animation frame.
+ * @param w Window-like object used for scheduling.
+ * @returns Promise that resolves on the next frame.
+ */
 declare const breath: (w?: Window & typeof globalThis) => Promise<unknown>;
+/** Resolve after two animation frames.
+ * @param w Window-like object used for scheduling.
+ * @returns Promise that resolves after layout has had two frames to settle.
+ */
 declare const deepBreath: (w?: Window & typeof globalThis) => Promise<unknown>;
+/** Run cleanup immediately or on abort, then return the callable cleanup.
+ * @param cleanup Cleanup function to protect.
+ * @param signal Optional abort signal.
+ * @returns The wrapped cleanup function.
+ */
 declare function bindCleanupToSignal<Cb extends () => any>(cleanup: Cb, signal?: AbortSignal): Cb;
 
+/** Resource type accepted by loadResource. */
 type ResourceType = "style" | "script" | string;
+/** Options used when loading a script or stylesheet resource. */
 type LoadResourceOptions = Partial<{
+    /** Load the script as a module. */
     module: boolean;
+    /** Media query applied to loaded stylesheets. */
     media: string;
+    /** crossorigin attribute for the resource element. */
     crossOrigin: "anonymous" | "use-credentials" | string | null;
+    /** Subresource integrity hash. */
     integrity: string;
+    /** Referrer policy for the resource element. */
     referrerPolicy: "no-referrer" | "origin" | "strict-origin-when-cross-origin" | string;
+    /** nonce attribute for CSP-enabled environments. */
     nonce: string;
+    /** fetchpriority hint for the browser. */
     fetchPriority: "high" | "low" | "auto";
+    /** Number of attempts before rejecting. */
     attempts: number;
+    /** Cache-busting retry token key. */
     retryKey: boolean | string;
 }>;
 
+/** Virtual resource marker used to skip real network loading. */
 declare const VIRTUAL_RESOURCE: symbol;
+/** Load a stylesheet or script into the current document with retry support.
+ * @param req Resource URL or virtual resource symbol.
+ * @param type Resource type to load.
+ * @param options Resource loading options.
+ * @param w Window-like target used for DOM insertion.
+ * @returns Promise resolving to the created element or void.
+ */
 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>;
 
 export { type LimitedHandle, type LimitedOptions, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, VIRTUAL_RESOURCE, bindCleanupToSignal, breath, deepBreath, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isPOJO, isSameURL, isStr, isSym, limited, loadResource, mockAsync, removeScrollAssist, uid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t007/utils",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "High-performance, zero-dependency utility functions for the t007 ecosystem.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",
@@ -45,6 +45,6 @@
     "performance"
   ],
   "dependencies": {
-    "sia-reactor": "^0.0.25"
+    "sia-reactor": "^0.0.30"
   }
 }