@t007/utils 0.0.33 → 0.0.35

package/dist/index.d.ts

@@ -1,19 +1,22 @@
-import { A as ArrowNavigationHandle } from './arrowNavigation-VenvPI4H.js';
-import { S as ScrollAssistHandle } from './scrollAssist-y9wFmYgt.js';
+import { A as ArrowNavigationHandle } from './arrowNavigation-B9bEdoqR.js';
+import { F as FocusTrapHandle, S as ScrollAssistHandle } from './scrollAssist-BNvPnsJq.js';
 export { NIL, NOOP } from 'sia-reactor';
-export { KeyStruct, assignEl, bindAllMethods, clamp, cleanKeyCombo, createEl, formatKeyForDisplay, formatKeyShortcutsForDisplay, getActiveEl, getTermsForKey, guardAllMethods, guardMethod, isObj, keyEventAllowed, keysSettings, matchKeys, onAllMethods, parseForARIAKS, parseKeyCombo, requestAnimationFrame, setInterval, setTimeout, stringifyKeyEvent } from 'sia-reactor/utils';
+export { KEYS_BLOCKS, KeyStruct, KeysSettings, assignEl, bindAllMethods, clamp, cleanKeyCombo, createEl, formatKeyForDisplay, formatKeyShortcutsForDisplay, getActiveEl, getTermsForKey, guardAllMethods, guardMethod, isObj, keyEventAllowed, matchKeys, onAllMethods, parseForARIAKS, parseKeyCombo, requestAnimationFrame, setInterval, setTimeout, stringifyKeyEvent } from 'sia-reactor/utils';
 
 declare global {
   interface T007Namespace {
     /** Symbol used to mark virtual resources that should not load a real asset. */
     VIRTUAL_RESOURCE: symbol;
     _resourceCache: Partial<Record<string, Promise<HTMLElement | void>>>;
-    _ftrappers?: WeakMap<HTMLElement, () => void>;
+    _throttlers?: Map<string, number>;
+    _debouncers?: Map<string, number>;
+    _RAFLoopers?: Map<string, Function>;
+    _ftrappers?: WeakMap<HTMLElement, FocusTrapHandle>;
     _outsiders?: WeakMap<HTMLElement, () => void>;
     _arrownavs?: WeakMap<HTMLElement, ArrowNavigationHandle>;
     _scrollers?: WeakMap<HTMLElement, ScrollAssistHandle>;
-    _ftrappers_stacks?: WeakMap<EventTarget, HTMLElement[]>;
-    _outsiders_stacks?: WeakMap<EventTarget, HTMLElement[]>;
+    _ftrappers_stack?: HTMLElement[];
+    _outsiders_stack?: HTMLElement[];
     _scrollers_r_observer?: ResizeObserver;
     _scrollers_m_observer?: MutationObserver;
   }
@@ -37,6 +40,27 @@ declare global {
   var t007: T007Namespace;
 }
 
+type TitleCase<S extends string> = S extends `${infer First}${infer Rest}`
+  ? `${Uppercase<First>}${Rest}`
+  : S;
+
+type CamelCase<S extends string> = S extends `${infer P1}_${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+  : S extends `${infer P1}-${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+  : S extends `${infer P1} ${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+  : Lowercase<S>;
+
+type NoCamelCase<
+  S extends string,
+  Sep extends string = " "
+> = S extends `${infer First}${infer Rest}`
+  ? First extends Uppercase<First>
+    ? `${Sep}${Lowercase<First>}${NoCamelCase<Rest, Sep>}`
+    : `${First}${NoCamelCase<Rest, Sep>}`
+  : S;
+
 declare function isDef(val: any): boolean;
 declare function isSym<T extends symbol = symbol>(val: any): val is T;
 declare function isBool<T extends boolean = boolean>(val: any): val is T;
@@ -49,20 +73,52 @@ 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;
 
+/**
+ * Finds the longest increasing subsequence in an array of numbers.
+ * @param array The input array of numbers
+ * @returns An array of indices representing the longest increasing subsequence
+ */
+declare function longestIncreasingSubsequence(array: number[]): number[];
+
 /** 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;
+/** Capitalize the first letter of a string, leaving the rest unchanged.
+ * @param word The string to capitalize.
+ * @returns The input string with the first letter capitalized.
+ */
+declare function capitalize<T extends string>(word?: T): TitleCase<T>;
+/** Convert a string to camelCase by removing separators and capitalizing subsequent words.
+ * @param str The input string to convert.
+ * @param options.source A regex or string defining word separators. @default  whitespace, underscores, and hyphens (`[\s_-]+`).
+ * @param options.preserveInnerCase If true, preserves the original casing of letters; if false, converts the entire string to lowercase before processing. @default  `true`.
+ * @param options.upperFirst If true, capitalizes the first letter of the resulting string (PascalCase); if false, lowercases the first letter (camelCase). @default  `false`.
+ * @returns The camelCase version of the input string.
+ */
+declare function camelize<T extends string>(str?: T, { source }?: RegExp, { preserveInnerCase: pIC, upperFirst: uF }?: {
+    preserveInnerCase?: boolean | undefined;
+    upperFirst?: boolean | undefined;
+}): CamelCase<T>;
+/** Convert a camelCase or PascalCase string to a separator-based format (e.g. "helloWorld" to "hello-world").
+ * @param str The camelCase or PascalCase string to convert.
+ * @param separator The string to insert between words. @default  a hyphen ("-").
+ * @returns The uncamelized version of the input string with separators.
+ * @example
+ * uncamelize("helloWorld") // "hello-world"
+ * uncamelize("HelloWorld", "_") // "hello_world"
+ */
+declare function uncamelize<T extends string, S extends string = " ">(str: T, separator?: S): NoCamelCase<T, S>;
 /** Convert a rem value to pixels based on the font size of a given element.
  * @param rem The rem value to convert.
- * @param el The element to use for font size reference. Defaults to the root element.
+ * @param el The element to use for font size reference. @default  the root element.
  * @returns The equivalent pixel value.
  */
 declare function remToPx(rem: number, el?: HTMLElement): number;
 /** Convert a pixel value to rem based on the font size of a given element.
  * @param px The pixel value to convert.
- * @param el The element to use for font size reference. Defaults to the root element.
+ * @param el The element to use for font size reference. @default  the root element.
  * @returns The equivalent rem value.
  */
 declare function pxToRem(px: number, el?: HTMLElement): number;
@@ -73,7 +129,7 @@ declare function pxToRem(px: number, el?: HTMLElement): number;
 declare function parseCSSTime(time: any): number;
 /** Parse a CSS size value (i.e. "16px" or "1.5rem") into pixels.
  * @param size The CSS size string to parse.
- * @param el The element to use for rem reference if needed. Defaults to the root element.
+ * @param el The element to use for rem reference if needed. @default  the root element.
  * @returns The equivalent value in pixels.
  */
 declare function parseCSSSize(size: any, el?: HTMLElement): number;
@@ -89,11 +145,45 @@ declare function cleanURL(url: string): string;
  */
 declare function isSameURL(url1: unknown, url2: unknown): boolean;
 
+/** Throttles a function, ensuring it's only called once within a specified delay period.
+ * @param key Unique identifier for the throttled function, used to track its last execution time.
+ * @param fn Function to be throttled.
+ * @param delay Time in milliseconds to wait before allowing the function to be called again. @default  `30ms`.
+ * @param strict If `true`, exact timestamp difference between calls will be used else a `setTimeout()` will clear the throttle, allowing for more thread leniency. @default  `true`.
+ * @param signal Optional `AbortSignal` to automatically clear the throttle when aborted.
+ * @param win Optional `Window` object for scheduling the throttle timeout, useful for testing or if running in a non-browser environment.
+ */
+declare function throttle(key: string, fn: Function, delay?: number, strict?: ((fn: Function) => number) | boolean, signal?: AbortSignal, win?: Window): void;
+/** Debounces a function, ensuring it's only called after a quiet period of no further calls.
+ * @param key Unique identifier for the debounced function, used to track pending calls.
+ * @param fn Function to be debounced.
+ * @param delay Time in milliseconds to wait after the latest call before invoking the function. @default  `30ms`.
+ * @param strict If `true`, exact timestamp difference between calls will be used else pending timeout is reset each call for practical thread leniency. @default  `true`.
+ * @param signal Optional `AbortSignal` to automatically clear scheduled debounce execution when aborted.
+ * @param win Optional `Window` object for scheduling/clearing the debounce timeout, useful for testing or if running in a non-browser environment.
+ */
+declare function debounce(key: string, fn: Function, delay?: number, strict?: boolean, signal?: AbortSignal, win?: Window): void;
+/** Creates a loop using `requestAnimationFrame`, allowing for efficient execution of a function on every frame.
+ * @param key Unique identifier for the loop, used to manage its execution and allow for updates or cancellation.
+ * @param fn Function to be executed on every frame.
+ * @param signal Optional `AbortSignal` to automatically cancel the loop when aborted.
+ * @param win Optional `Window` object for scheduling the animation frame, useful for testing or if running in a non-browser environment.
+ *
+ * Game-like loops will be our lil secret... ~ "The Smoooth Criminal" :)
+ */
+declare function RAFLoop(key: string, fn: Function, signal?: AbortSignal, win?: Window & typeof globalThis): void;
+/** Cancels a loop created by `RAFLoop`.
+ * @param key Unique identifier for the loop to be cancelled.
+ * @returns True if the loop was successfully cancelled, false if no loop with the given key exists.
+ */
+declare const cancelRAFLoop: (key: string) => boolean;
 interface LimitedOptions {
     /** Storage key used to persist call counts. */
     key?: string;
-    /** Maximum number of allowed calls. */
+    /** Maximum number of allowed calls. @default 1 */
     maxTimes?: number;
+    /** Only allow calling once per session, regardless of maxTimes. @default true */
+    oncePerSession?: boolean;
 }
 interface LimitedHandle<T extends (...args: any[]) => any> {
     /** Call the wrapped function with the original arguments. */
@@ -137,7 +227,7 @@ declare const deepBreath: (w?: Window & typeof globalThis) => Promise<unknown>;
 declare function bindCleanupToSignal<Cb extends () => any>(cleanup: Cb, signal?: AbortSignal): Cb;
 
 /** Exhaustive Selector used for interactive, tabbable UI controls. */
-declare const INTERACTIVE_SELECTOR = ":is(button,[href],input:not([type='hidden']),select,textarea,details>summary,[contenteditable='true'],iframe,audio[controls],video[controls],[tabindex]):not([disabled],[tabindex='-1'],[data-focus-guard],[inert],[inert] *)";
+declare const INTERACTIVE_SELECTOR = ":is(button,[href],input:not([type='hidden']),select,textarea,details>summary,[contenteditable],iframe,audio[controls],video[controls],[tabindex]):not([disabled],[tabindex='-1'],[data-focus-guard],[inert],[inert] *)";
 /** Check whether an event target points to an interactive element. */
 declare const isInteractive: (target: EventTarget | null) => boolean;
 /** Resource type accepted by loadResource. */
@@ -169,16 +259,53 @@ declare const VIRTUAL_RESOURCE: symbol;
  * @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.
+ * @param win 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>;
+declare function loadResource(req: string | symbol, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, win?: Window & typeof globalThis): Promise<HTMLElement | void>;
 
 /** Get the window object associated with a given element.
  * @param el The element to get the window for, defaults to the main window.
- * @returns The window object or undefined if none found.
+ * @returns The `Window` object or undefined if none found.
+ */
+declare function getWindow(el?: any): Window & typeof globalThis;
+/** Options for configuring a list renderer */
+type ListRendererOptions<T, El extends HTMLElement = HTMLElement> = {
+    /** The container element to render the list into */
+    container: HTMLElement;
+    /** Function to extract a unique key from each item.
+     * @param item The item to extract the key from
+     * @returns A unique string key for the item
+     */
+    getKey: (item: T) => string;
+    /** Function to create a DOM node for an item.
+     * @param item The item to create a node for
+     * @returns An HTMLElement representing the item, or null/undefined to skip rendering
+     */
+    createNode: (item: T) => El | null | undefined;
+    /** Optional function to update an existing node with new item data, called when an item is reused.
+     * @param node The existing DOM node for the item
+     * @param item The new item data to update the node with
+     */
+    updateNode?: (node: El, item: T) => void;
+    /** Optional function to clean up a DOM node when an item is removed, called before the node is removed from the DOM.
+     * @param node The DOM node to be removed
+     * @param key The unique key of the item associated with the node
+     */
+    destroyNode?: (node: El, key: string) => void;
+    /** Optional function called once during initialization for each existing child node in the container.
+     * Allows seeding the registry with pre-existing markup so nodes are reused instead of destroyed.
+     * @param node The pre-existing DOM node
+     * @param register A callback to register the node with its corresponding item key
+     */
+    initNode?: (node: El, register: (key: string) => void) => void;
+};
+/**
+ * Creates a list renderer function for efficiently updating a DOM list based on a new array of items using the L.I.S(Longest Increasing Subsequence) algorithm.
+ * @param param0 The options for configuring the list renderer
+ * @returns A function that synchronizes the DOM with the new array of items
  */
-declare function getWindow(el?: any): (Window & typeof globalThis) | undefined;
+declare function createListRenderer<T, El extends HTMLElement = HTMLElement>({ container, getKey, createNode, updateNode, destroyNode, initNode }: ListRendererOptions<T, El>): (array: T[], strict?: boolean) => void;
 
 /** Format a file size for display.
  * @param size Size in bytes.
@@ -188,4 +315,4 @@ declare function getWindow(el?: any): (Window & typeof globalThis) | undefined;
  */
 declare function formatSize(bytes: number, decimals?: number, base?: number): string;
 
-export { INTERACTIVE_SELECTOR, type LimitedHandle, type LimitedOptions, type LoadResourceOptions, type ResourceType, VIRTUAL_RESOURCE, bindCleanupToSignal, breath, cleanURL, deepBreath, formatSize, getWindow, inBoolArrOpt, isArr, isBool, isDef, isFunc, isInteractive, isIter, isNum, isPOJO, isSameURL, isStr, isSym, limited, loadResource, mockAsync, parseCSSSize, parseCSSTime, pxToRem, remToPx, uid };
+export { type CamelCase, INTERACTIVE_SELECTOR, type LimitedHandle, type LimitedOptions, type ListRendererOptions, type LoadResourceOptions, type NoCamelCase, RAFLoop, type ResourceType, type TitleCase, VIRTUAL_RESOURCE, bindCleanupToSignal, breath, camelize, cancelRAFLoop, capitalize, cleanURL, createListRenderer, debounce, deepBreath, formatSize, getWindow, inBoolArrOpt, isArr, isBool, isDef, isFunc, isInteractive, isIter, isNum, isPOJO, isSameURL, isStr, isSym, limited, loadResource, longestIncreasingSubsequence, mockAsync, parseCSSSize, parseCSSTime, pxToRem, remToPx, throttle, uid, uncamelize };

package/dist/index.js

@@ -1,16 +1,23 @@
 import {
   INTERACTIVE_SELECTOR,
+  KEYS_BLOCKS,
   NIL,
   NOOP,
+  RAFLoop,
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
   bindCleanupToSignal,
   breath,
+  camelize,
+  cancelRAFLoop,
+  capitalize,
   clamp,
   cleanKeyCombo,
   cleanURL,
   createEl,
+  createListRenderer,
+  debounce,
   deepBreath,
   formatKeyForDisplay,
   formatKeyShortcutsForDisplay,
@@ -36,6 +43,7 @@ import {
   keyEventAllowed,
   limited,
   loadResource,
+  longestIncreasingSubsequence,
   matchKeys,
   mockAsync,
   onAllMethods,
@@ -49,21 +57,30 @@ import {
   setInterval,
   setTimeout,
   stringifyKeyEvent,
-  uid
-} from "./chunk-4O76EZJ4.js";
+  throttle,
+  uid,
+  uncamelize
+} from "./chunk-ZALPHCSJ.js";
 export {
   INTERACTIVE_SELECTOR,
+  KEYS_BLOCKS,
   NIL,
   NOOP,
+  RAFLoop,
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
   bindCleanupToSignal,
   breath,
+  camelize,
+  cancelRAFLoop,
+  capitalize,
   clamp,
   cleanKeyCombo,
   cleanURL,
   createEl,
+  createListRenderer,
+  debounce,
   deepBreath,
   formatKeyForDisplay,
   formatKeyShortcutsForDisplay,
@@ -89,6 +106,7 @@ export {
   keyEventAllowed,
   limited,
   loadResource,
+  longestIncreasingSubsequence,
   matchKeys,
   mockAsync,
   onAllMethods,
@@ -102,5 +120,7 @@ export {
   setInterval,
   setTimeout,
   stringifyKeyEvent,
-  uid
+  throttle,
+  uid,
+  uncamelize
 };

package/dist/ripple-D1kGErTn.d.cts

@@ -0,0 +1,55 @@
+interface OutsideClickConfig {
+    /** Enables or disables outside-click handling. @default  `false`. */
+    enabled?: boolean;
+    /** Callback invoked when an outside interaction is detected. @default  `()=>{}`. */
+    onOutside?: (e: MouseEvent | TouchEvent | KeyboardEvent | FocusEvent) => void;
+    /** Whether pointer/touch outside interactions should trigger callback. @default  `true`. */
+    outOnClick?: boolean;
+    /** Whether Escape key should trigger callback. @default  `true`. */
+    outOnEscape?: boolean;
+    /** Whether focus leaving the container should trigger callback. @default  `false`. */
+    outOnFocusOut?: boolean;
+    /** Allow only clicks inside `el` bounding client rectangle to be considered valid, otherwise uses `el.contains(target)`. @default  `false . */
+    allowBounds?: boolean;
+    /** Allow interactive elements including outsiders to bypass click callback. @default  `false`. */
+    allowInputs?: boolean;
+    /** Optional root used to scope focus listeners to an element instead of the window. @default  `window`. */
+    root?: HTMLElement | Document | Window;
+    /** Whether the outside click handling is scoped to the root provided it is an HTMLElement. @default  `true`. */
+    scoped?: boolean;
+    /** Passed down to all event listeners used. @default  `true`. */
+    capture?: boolean;
+}
+/** Hook to attach outside-click, escape, and optional focus-out handling to an element. */
+declare function initOutsideClick(el: HTMLElement, { enabled, onOutside, outOnClick, outOnEscape, outOnFocusOut, allowBounds, allowInputs, root, scoped, capture }?: OutsideClickConfig): (() => void) | void;
+/** Remove outside-click handling from an element. */
+declare const removeOutsideClick: (el: HTMLElement) => void | undefined;
+
+interface RippleConfig {
+    /** Optional explicit ripple host element. @default  event currentTarget. */
+    target?: HTMLElement | null;
+    /** Forces the ripple origin to the center of the host. By default, the ripple will originate from the pointer event coordinates. */
+    forceCenter?: boolean;
+    /** CSS class added to the ripple wrapper element. @default  `"t007-ripple-wrapper"`. */
+    wrapperClassName?: string;
+    /** CSS general class added to the ripple element. @default  `"t007-ripple"`. */
+    className?: string;
+    /** CSS class added to the ripple element while the pointer is held down. Should contain the initial expansion animation. @default  `"t007-ripple-hold"`. */
+    holdClassName?: string;
+    /** CSS class added to the ripple element when released. Should contain the fade-out animation. @default  `"t007-ripple-fade"`. */
+    fadeClassName?: string;
+    /** Maximum duration for the ripple animation, force-ejects when elapsed. @default  1000ms. */
+    maxDuration?: number;
+}
+/** Render and control a material-style ripple animation on an element.
+ * @param e Pointer event used to place and gate the ripple.
+ * @param options Ripple configuration options.
+ * @details
+ * The ripple will be triggered on the event's currentTarget by default, but an explicit target can be provided.
+ * The ripple will originate from the pointer coordinates relative to the target, unless forceCenter is enabled.
+ * The ripple element will receive a hold class until the pointer is released, at which point it will switch to a fade class and be removed after the animation completes.
+ * Pointer events that are not left-clicks or that originate from interactive elements other than the currentTarget will be ignored to prevent interference with native behaviors.
+ */
+declare function rippleHandler(e: Pick<PointerEvent, "target" | "currentTarget" | "button" | "clientX" | "clientY" | "stopPropagation">, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName, maxDuration }?: RippleConfig): void;
+
+export { type OutsideClickConfig as O, type RippleConfig as R, rippleHandler as a, initOutsideClick as i, removeOutsideClick as r };

package/dist/ripple-D1kGErTn.d.ts

@@ -0,0 +1,55 @@
+interface OutsideClickConfig {
+    /** Enables or disables outside-click handling. @default  `false`. */
+    enabled?: boolean;
+    /** Callback invoked when an outside interaction is detected. @default  `()=>{}`. */
+    onOutside?: (e: MouseEvent | TouchEvent | KeyboardEvent | FocusEvent) => void;
+    /** Whether pointer/touch outside interactions should trigger callback. @default  `true`. */
+    outOnClick?: boolean;
+    /** Whether Escape key should trigger callback. @default  `true`. */
+    outOnEscape?: boolean;
+    /** Whether focus leaving the container should trigger callback. @default  `false`. */
+    outOnFocusOut?: boolean;
+    /** Allow only clicks inside `el` bounding client rectangle to be considered valid, otherwise uses `el.contains(target)`. @default  `false . */
+    allowBounds?: boolean;
+    /** Allow interactive elements including outsiders to bypass click callback. @default  `false`. */
+    allowInputs?: boolean;
+    /** Optional root used to scope focus listeners to an element instead of the window. @default  `window`. */
+    root?: HTMLElement | Document | Window;
+    /** Whether the outside click handling is scoped to the root provided it is an HTMLElement. @default  `true`. */
+    scoped?: boolean;
+    /** Passed down to all event listeners used. @default  `true`. */
+    capture?: boolean;
+}
+/** Hook to attach outside-click, escape, and optional focus-out handling to an element. */
+declare function initOutsideClick(el: HTMLElement, { enabled, onOutside, outOnClick, outOnEscape, outOnFocusOut, allowBounds, allowInputs, root, scoped, capture }?: OutsideClickConfig): (() => void) | void;
+/** Remove outside-click handling from an element. */
+declare const removeOutsideClick: (el: HTMLElement) => void | undefined;
+
+interface RippleConfig {
+    /** Optional explicit ripple host element. @default  event currentTarget. */
+    target?: HTMLElement | null;
+    /** Forces the ripple origin to the center of the host. By default, the ripple will originate from the pointer event coordinates. */
+    forceCenter?: boolean;
+    /** CSS class added to the ripple wrapper element. @default  `"t007-ripple-wrapper"`. */
+    wrapperClassName?: string;
+    /** CSS general class added to the ripple element. @default  `"t007-ripple"`. */
+    className?: string;
+    /** CSS class added to the ripple element while the pointer is held down. Should contain the initial expansion animation. @default  `"t007-ripple-hold"`. */
+    holdClassName?: string;
+    /** CSS class added to the ripple element when released. Should contain the fade-out animation. @default  `"t007-ripple-fade"`. */
+    fadeClassName?: string;
+    /** Maximum duration for the ripple animation, force-ejects when elapsed. @default  1000ms. */
+    maxDuration?: number;
+}
+/** Render and control a material-style ripple animation on an element.
+ * @param e Pointer event used to place and gate the ripple.
+ * @param options Ripple configuration options.
+ * @details
+ * The ripple will be triggered on the event's currentTarget by default, but an explicit target can be provided.
+ * The ripple will originate from the pointer coordinates relative to the target, unless forceCenter is enabled.
+ * The ripple element will receive a hold class until the pointer is released, at which point it will switch to a fade class and be removed after the animation completes.
+ * Pointer events that are not left-clicks or that originate from interactive elements other than the currentTarget will be ignored to prevent interference with native behaviors.
+ */
+declare function rippleHandler(e: Pick<PointerEvent, "target" | "currentTarget" | "button" | "clientX" | "clientY" | "stopPropagation">, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName, maxDuration }?: RippleConfig): void;
+
+export { type OutsideClickConfig as O, type RippleConfig as R, rippleHandler as a, initOutsideClick as i, removeOutsideClick as r };

package/dist/scrollAssist-BNvPnsJq.d.cts

@@ -0,0 +1,97 @@
+type KeyEvent = Partial<KeyboardEvent> & Pick<KeyboardEvent, "key">;
+type Config = {
+    /** Enables or disables navigation logic. @default  `null`. */
+    enabled?: boolean | null;
+    /** CSS selector used to collect focusable nav items. @default  `"[data-arrow-item]"` */
+    selector?: string;
+    /** Whether hover should also move active selection. @default  `true`. */
+    focusOnHover?: boolean;
+    /** Whether directional movement wraps around edges. @default  `true`. */
+    loop?: boolean;
+    /** Enables virtual focus (aria-activedescendant) mode. @default  `false`. */
+    virtual?: boolean;
+    /** Enables alphanumeric type-ahead matching. @default  `false`. */
+    typeahead?: boolean;
+    /** Idle timeout before clearing type-ahead buffer (ms). @default  `500`. */
+    resetMs?: number;
+    /** Explicit RTL override; null auto-detects from computed style. @default  `null`. */
+    rtl?: boolean | null;
+    /** Enables roving tabindex when not in virtual mode. @default  `null`. */
+    rovingTab?: boolean | null;
+    /** Default tabbable index when no active item is selected. @default  `null`. */
+    defaultTabbableIndex?: number | null;
+    /** Base tabindex for non-active items, use `"-1"` to kill virtual list. @default  `"0"`. */
+    baseTabIndex?: string;
+    /** Class applied to active item in virtual mode. @default  `"focus-outlined"`. */
+    activeClass?: string;
+    /** Selector used for keyboard event source in virtual mode. @default  `"input[value],textarea,[contenteditable]"`. */
+    inputSelector?: string;
+    /** Scroll behavior options used when moving active item. @default  `{ block: "nearest", inline: "nearest" }`. */
+    scrollIntoView?: ScrollIntoViewOptions;
+    /** Focus behavior options used in non-virtual mode. @default  `{ preventScroll: false }`. */
+    focusOptions?: FocusOptions;
+    /** Explicit or computed grid dimensions for navigation math. @default  `{}`. */
+    grid?: Partial<Record<"x" | "y" | "vY", number>>;
+    /** Callback fired when an item becomes active/selected. */
+    onSelect?: (el: HTMLElement, e: KeyEvent) => void;
+    /** Callback fired when focus leaves the navigation container. */
+    onFocusOut?: (e: FocusEvent) => void;
+};
+
+interface FocusTrapConfig {
+    /** Enables or disables the focus trap. @default  `false`. */
+    enabled?: boolean;
+    /** The preferred initial focus target selector within the element, overrides whatever was focused. Try `autofocus` attribute if working with dialogs before this. @default  `[data-autofocus]`. */
+    initialSelector?: string;
+    /** The class name for the initial focus ring since programmatic focus is not always visible, `autofocus` attribute in dialogs might work fine as an alternative. @default  `"focus-outline"`. */
+    ringClassName?: string;
+    /** Optional root used to scope focus listeners to an element instead of the window. @default  `window`. */
+    root?: HTMLElement | Document | Window;
+    /** Whether the focus trap is scoped to the root provided it is an HTMLElement. @default  `true`. */
+    scoped?: boolean;
+    /** Passed down to all event listeners used. @default  `true`. */
+    capture?: boolean;
+}
+interface FocusTrapHandle {
+    destroy: () => void;
+    sync: () => void;
+}
+/** Hook to keep focus trapped inside an element until disabled. */
+declare function initFocusTrap(el: HTMLElement, { enabled, initialSelector, ringClassName, root, scoped, capture }?: FocusTrapConfig): FocusTrapHandle | void;
+/** Remove the focus trap guard from an element. */
+declare const removeFocusTrap: (el: HTMLElement) => void | undefined;
+/** Synchronize the focus trap guards. */
+declare const syncFocusTrap: (el: HTMLElement) => void | undefined;
+
+type ScrollDir = "left" | "right" | "up" | "down";
+/** Scroll assist control object returned by initScrollAssist. */
+interface ScrollAssistHandle {
+    /** Recompute assist visibility. */
+    update: () => void;
+    /** Tear down observers and assist elements. */
+    destroy: () => void;
+}
+/** Configuration for scroll assist overlays. */
+interface ScrollAssistConfig {
+    /** Scroll speed in pixels per second. @default  `80`. */
+    pxPerSecond?: number;
+    /** Class name applied to assist overlays. @default  `"t007-scroll-assist"`. */
+    assistClassName?: string;
+    /** Enable vertical assist overlays. @default  `true`. */
+    vertical?: boolean;
+    /** Enable horizontal assist overlays. @default  `true`. */
+    horizontal?: boolean;
+}
+/** Hook to add edge-scrolling assist to an element. It creates invisible "hot zones" at the edges of the element that, when hovered or dragged into, will scroll the element in that direction.
+ * The assist is automatically disabled when the element is too small or contains interactive elements near the edges to prevent interference.
+ * @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 }?: ScrollAssistConfig): ScrollAssistHandle | void;
+/** Remove scroll assist from an element.
+ * @param el Target element.
+ */
+declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
+
+export { type Config as C, type FocusTrapHandle as F, type KeyEvent as K, type ScrollAssistHandle as S, type ScrollAssistConfig as a, type FocusTrapConfig as b, type ScrollDir as c, initScrollAssist as d, removeScrollAssist as e, initFocusTrap as i, removeFocusTrap as r, syncFocusTrap as s };

package/dist/scrollAssist-BNvPnsJq.d.ts

@@ -0,0 +1,97 @@
+type KeyEvent = Partial<KeyboardEvent> & Pick<KeyboardEvent, "key">;
+type Config = {
+    /** Enables or disables navigation logic. @default  `null`. */
+    enabled?: boolean | null;
+    /** CSS selector used to collect focusable nav items. @default  `"[data-arrow-item]"` */
+    selector?: string;
+    /** Whether hover should also move active selection. @default  `true`. */
+    focusOnHover?: boolean;
+    /** Whether directional movement wraps around edges. @default  `true`. */
+    loop?: boolean;
+    /** Enables virtual focus (aria-activedescendant) mode. @default  `false`. */
+    virtual?: boolean;
+    /** Enables alphanumeric type-ahead matching. @default  `false`. */
+    typeahead?: boolean;
+    /** Idle timeout before clearing type-ahead buffer (ms). @default  `500`. */
+    resetMs?: number;
+    /** Explicit RTL override; null auto-detects from computed style. @default  `null`. */
+    rtl?: boolean | null;
+    /** Enables roving tabindex when not in virtual mode. @default  `null`. */
+    rovingTab?: boolean | null;
+    /** Default tabbable index when no active item is selected. @default  `null`. */
+    defaultTabbableIndex?: number | null;
+    /** Base tabindex for non-active items, use `"-1"` to kill virtual list. @default  `"0"`. */
+    baseTabIndex?: string;
+    /** Class applied to active item in virtual mode. @default  `"focus-outlined"`. */
+    activeClass?: string;
+    /** Selector used for keyboard event source in virtual mode. @default  `"input[value],textarea,[contenteditable]"`. */
+    inputSelector?: string;
+    /** Scroll behavior options used when moving active item. @default  `{ block: "nearest", inline: "nearest" }`. */
+    scrollIntoView?: ScrollIntoViewOptions;
+    /** Focus behavior options used in non-virtual mode. @default  `{ preventScroll: false }`. */
+    focusOptions?: FocusOptions;
+    /** Explicit or computed grid dimensions for navigation math. @default  `{}`. */
+    grid?: Partial<Record<"x" | "y" | "vY", number>>;
+    /** Callback fired when an item becomes active/selected. */
+    onSelect?: (el: HTMLElement, e: KeyEvent) => void;
+    /** Callback fired when focus leaves the navigation container. */
+    onFocusOut?: (e: FocusEvent) => void;
+};
+
+interface FocusTrapConfig {
+    /** Enables or disables the focus trap. @default  `false`. */
+    enabled?: boolean;
+    /** The preferred initial focus target selector within the element, overrides whatever was focused. Try `autofocus` attribute if working with dialogs before this. @default  `[data-autofocus]`. */
+    initialSelector?: string;
+    /** The class name for the initial focus ring since programmatic focus is not always visible, `autofocus` attribute in dialogs might work fine as an alternative. @default  `"focus-outline"`. */
+    ringClassName?: string;
+    /** Optional root used to scope focus listeners to an element instead of the window. @default  `window`. */
+    root?: HTMLElement | Document | Window;
+    /** Whether the focus trap is scoped to the root provided it is an HTMLElement. @default  `true`. */
+    scoped?: boolean;
+    /** Passed down to all event listeners used. @default  `true`. */
+    capture?: boolean;
+}
+interface FocusTrapHandle {
+    destroy: () => void;
+    sync: () => void;
+}
+/** Hook to keep focus trapped inside an element until disabled. */
+declare function initFocusTrap(el: HTMLElement, { enabled, initialSelector, ringClassName, root, scoped, capture }?: FocusTrapConfig): FocusTrapHandle | void;
+/** Remove the focus trap guard from an element. */
+declare const removeFocusTrap: (el: HTMLElement) => void | undefined;
+/** Synchronize the focus trap guards. */
+declare const syncFocusTrap: (el: HTMLElement) => void | undefined;
+
+type ScrollDir = "left" | "right" | "up" | "down";
+/** Scroll assist control object returned by initScrollAssist. */
+interface ScrollAssistHandle {
+    /** Recompute assist visibility. */
+    update: () => void;
+    /** Tear down observers and assist elements. */
+    destroy: () => void;
+}
+/** Configuration for scroll assist overlays. */
+interface ScrollAssistConfig {
+    /** Scroll speed in pixels per second. @default  `80`. */
+    pxPerSecond?: number;
+    /** Class name applied to assist overlays. @default  `"t007-scroll-assist"`. */
+    assistClassName?: string;
+    /** Enable vertical assist overlays. @default  `true`. */
+    vertical?: boolean;
+    /** Enable horizontal assist overlays. @default  `true`. */
+    horizontal?: boolean;
+}
+/** Hook to add edge-scrolling assist to an element. It creates invisible "hot zones" at the edges of the element that, when hovered or dragged into, will scroll the element in that direction.
+ * The assist is automatically disabled when the element is too small or contains interactive elements near the edges to prevent interference.
+ * @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 }?: ScrollAssistConfig): ScrollAssistHandle | void;
+/** Remove scroll assist from an element.
+ * @param el Target element.
+ */
+declare const removeScrollAssist: (el: HTMLElement) => void | undefined;
+
+export { type Config as C, type FocusTrapHandle as F, type KeyEvent as K, type ScrollAssistHandle as S, type ScrollAssistConfig as a, type FocusTrapConfig as b, type ScrollDir as c, initScrollAssist as d, removeScrollAssist as e, initFocusTrap as i, removeFocusTrap as r, syncFocusTrap as s };

package/dist/{useHighlight-DMpDCILK.d.cts → useHighlight-DYc_GF0R.d.cts}

@@ -1,7 +1,7 @@
 interface HighlightOptions {
-    /** Whether to trim individual query strings. Defaults to `true`. */
+    /** Whether to trim individual query strings. @default  `true`. */
     trimQuery?: boolean;
-    /** Whether to match whole words only. Defaults to `false`. */
+    /** Whether to match whole words only. @default  `false`. */
     wholeWord?: boolean;
 }
 /** React hook to process a text string and identify parts that match a given query, returning an array of text chunks with information on whether they match the query.

package/dist/{useHighlight-DMpDCILK.d.ts → useHighlight-DYc_GF0R.d.ts}

@@ -1,7 +1,7 @@
 interface HighlightOptions {
-    /** Whether to trim individual query strings. Defaults to `true`. */
+    /** Whether to trim individual query strings. @default  `true`. */
     trimQuery?: boolean;
-    /** Whether to match whole words only. Defaults to `false`. */
+    /** Whether to match whole words only. @default  `false`. */
     wholeWord?: boolean;
 }
 /** React hook to process a text string and identify parts that match a given query, returning an array of text chunks with information on whether they match the query.