@t007/utils 0.0.33 → 0.0.34

package/dist/index.d.ts

@@ -1,13 +1,16 @@
-import { A as ArrowNavigationHandle } from './arrowNavigation-VenvPI4H.js';
-import { S as ScrollAssistHandle } from './scrollAssist-y9wFmYgt.js';
+import { A as ArrowNavigationHandle } from './arrowNavigation-DF7ul3A3.js';
+import { S as ScrollAssistHandle } from './scrollAssist-l0V2H-jx.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>>>;
+    _throttlers?: Map<string, number>;
+    _debouncers?: Map<string, number>;
+    _RAFLoopers?: Map<string, Function>;
     _ftrappers?: WeakMap<HTMLElement, () => void>;
     _outsiders?: WeakMap<HTMLElement, () => void>;
     _arrownavs?: WeakMap<HTMLElement, ArrowNavigationHandle>;
@@ -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,6 +145,38 @@ 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;
@@ -137,7 +225,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 +257,47 @@ 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> = {
+    /** 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) => HTMLElement | 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: HTMLElement, 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: HTMLElement, key: string) => 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>({ container, getKey, createNode, updateNode, destroyNode }: ListRendererOptions<T>): (array: T[], strict?: boolean) => void;
 
 /** Format a file size for display.
  * @param size Size in bytes.
@@ -188,4 +307,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-HGUYOV3P.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-C5MfEErC.d.cts → ripple-87VO-U7A.d.cts}

@@ -1,23 +1,23 @@
 interface OutsideClickConfig {
-    /** Enables or disables outside-click handling. Defaults to `false`. */
+    /** Enables or disables outside-click handling. @default  `false`. */
     enabled?: boolean;
-    /** Callback invoked when an outside interaction is detected. Defaults to `()=>{}`. */
+    /** Callback invoked when an outside interaction is detected. @default  `()=>{}`. */
     onOutside?: (e: MouseEvent | TouchEvent | KeyboardEvent | FocusEvent) => void;
-    /** Whether pointer/touch outside interactions should trigger callback. Defaults to `true`. */
+    /** Whether pointer/touch outside interactions should trigger callback. @default  `true`. */
     outOnClick?: boolean;
-    /** Whether Escape key should trigger callback. Defaults to `true`. */
+    /** Whether Escape key should trigger callback. @default  `true`. */
     outOnEscape?: boolean;
-    /** Whether focus leaving the container should trigger callback. Defaults to `false`. */
+    /** 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)`. Defaults to `false . */
+    /** 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. Defaults to `false`. */
+    /** 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. Defaults to `window`. */
+    /** 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. Defaults to `true`. */
+    /** 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. Defaults to `true`. */
+    /** 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. */
@@ -26,17 +26,17 @@ declare function initOutsideClick(el: HTMLElement, { enabled, onOutside, outOnCl
 declare const removeOutsideClick: (el: HTMLElement) => void | undefined;
 
 interface FocusTrapConfig {
-    /** Enables or disables the focus trap. Defaults to `false`. */
+    /** 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. Defaults to `[data-autofocus]`. */
+    /** 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. Defaults to `"focus-outline"`. */
+    /** 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. Defaults to `window`. */
+    /** 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. Defaults to `true`. */
+    /** 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. Defaults to `true`. */
+    /** Passed down to all event listeners used. @default  `true`. */
     capture?: boolean;
 }
 /** Hook to keep focus trapped inside an element until disabled. */
@@ -45,18 +45,20 @@ declare function initFocusTrap(el: HTMLElement, { enabled, initialSelector, ring
 declare const removeFocusTrap: (el: HTMLElement) => void | undefined;
 
 interface RippleConfig {
-    /** Optional explicit ripple host element. Defaults to event currentTarget. */
-    target?: HTMLElement;
+    /** 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. Defaults to `"t007-ripple-wrapper"`. */
+    /** CSS class added to the ripple wrapper element. @default  `"t007-ripple-wrapper"`. */
     wrapperClassName?: string;
-    /** CSS general class added to the ripple element. Defaults to `"t007-ripple"`. */
+    /** 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. Defaults to `"t007-ripple-hold"`. */
+    /** 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. Defaults to `"t007-ripple-fade"`. */
+    /** 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.
@@ -67,7 +69,6 @@ interface RippleConfig {
  * 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: RipplePointerLikeEvent, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName }?: RippleConfig): void;
-type RipplePointerLikeEvent = Pick<PointerEvent, "target" | "currentTarget" | "pointerType" | "button" | "clientX" | "clientY" | "stopPropagation">;
+declare function rippleHandler(e: Pick<PointerEvent, "target" | "currentTarget" | "button" | "clientX" | "clientY" | "stopPropagation">, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName, maxDuration }?: RippleConfig): void;
 
 export { type FocusTrapConfig as F, type OutsideClickConfig as O, type RippleConfig as R, initOutsideClick as a, removeOutsideClick as b, rippleHandler as c, initFocusTrap as i, removeFocusTrap as r };

package/dist/{ripple-C5MfEErC.d.ts → ripple-87VO-U7A.d.ts}

@@ -1,23 +1,23 @@
 interface OutsideClickConfig {
-    /** Enables or disables outside-click handling. Defaults to `false`. */
+    /** Enables or disables outside-click handling. @default  `false`. */
     enabled?: boolean;
-    /** Callback invoked when an outside interaction is detected. Defaults to `()=>{}`. */
+    /** Callback invoked when an outside interaction is detected. @default  `()=>{}`. */
     onOutside?: (e: MouseEvent | TouchEvent | KeyboardEvent | FocusEvent) => void;
-    /** Whether pointer/touch outside interactions should trigger callback. Defaults to `true`. */
+    /** Whether pointer/touch outside interactions should trigger callback. @default  `true`. */
     outOnClick?: boolean;
-    /** Whether Escape key should trigger callback. Defaults to `true`. */
+    /** Whether Escape key should trigger callback. @default  `true`. */
     outOnEscape?: boolean;
-    /** Whether focus leaving the container should trigger callback. Defaults to `false`. */
+    /** 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)`. Defaults to `false . */
+    /** 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. Defaults to `false`. */
+    /** 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. Defaults to `window`. */
+    /** 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. Defaults to `true`. */
+    /** 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. Defaults to `true`. */
+    /** 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. */
@@ -26,17 +26,17 @@ declare function initOutsideClick(el: HTMLElement, { enabled, onOutside, outOnCl
 declare const removeOutsideClick: (el: HTMLElement) => void | undefined;
 
 interface FocusTrapConfig {
-    /** Enables or disables the focus trap. Defaults to `false`. */
+    /** 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. Defaults to `[data-autofocus]`. */
+    /** 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. Defaults to `"focus-outline"`. */
+    /** 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. Defaults to `window`. */
+    /** 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. Defaults to `true`. */
+    /** 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. Defaults to `true`. */
+    /** Passed down to all event listeners used. @default  `true`. */
     capture?: boolean;
 }
 /** Hook to keep focus trapped inside an element until disabled. */
@@ -45,18 +45,20 @@ declare function initFocusTrap(el: HTMLElement, { enabled, initialSelector, ring
 declare const removeFocusTrap: (el: HTMLElement) => void | undefined;
 
 interface RippleConfig {
-    /** Optional explicit ripple host element. Defaults to event currentTarget. */
-    target?: HTMLElement;
+    /** 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. Defaults to `"t007-ripple-wrapper"`. */
+    /** CSS class added to the ripple wrapper element. @default  `"t007-ripple-wrapper"`. */
     wrapperClassName?: string;
-    /** CSS general class added to the ripple element. Defaults to `"t007-ripple"`. */
+    /** 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. Defaults to `"t007-ripple-hold"`. */
+    /** 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. Defaults to `"t007-ripple-fade"`. */
+    /** 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.
@@ -67,7 +69,6 @@ interface RippleConfig {
  * 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: RipplePointerLikeEvent, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName }?: RippleConfig): void;
-type RipplePointerLikeEvent = Pick<PointerEvent, "target" | "currentTarget" | "pointerType" | "button" | "clientX" | "clientY" | "stopPropagation">;
+declare function rippleHandler(e: Pick<PointerEvent, "target" | "currentTarget" | "button" | "clientX" | "clientY" | "stopPropagation">, { target, forceCenter, wrapperClassName, className, holdClassName, fadeClassName, maxDuration }?: RippleConfig): void;
 
 export { type FocusTrapConfig as F, type OutsideClickConfig as O, type RippleConfig as R, initOutsideClick as a, removeOutsideClick as b, rippleHandler as c, initFocusTrap as i, removeFocusTrap as r };

package/dist/{scrollAssist-y9wFmYgt.d.cts → scrollAssist-l0V2H-jx.d.cts}

@@ -1,36 +1,36 @@
 type KeyEvent = Partial<KeyboardEvent> & Pick<KeyboardEvent, "key">;
 type Config = {
-    /** Enables or disables navigation logic. Defaults to `null`. */
+    /** Enables or disables navigation logic. @default  `null`. */
     enabled?: boolean | null;
-    /** CSS selector used to collect focusable nav items. Defaults to `"[data-arrow-item]"` */
+    /** CSS selector used to collect focusable nav items. @default  `"[data-arrow-item]"` */
     selector?: string;
-    /** Whether hover should also move active selection. Defaults to `true`. */
+    /** Whether hover should also move active selection. @default  `true`. */
     focusOnHover?: boolean;
-    /** Whether directional movement wraps around edges. Defaults to `true`. */
+    /** Whether directional movement wraps around edges. @default  `true`. */
     loop?: boolean;
-    /** Enables virtual focus (aria-activedescendant) mode. Defaults to `false`. */
+    /** Enables virtual focus (aria-activedescendant) mode. @default  `false`. */
     virtual?: boolean;
-    /** Enables alphanumeric type-ahead matching. Defaults to `false`. */
+    /** Enables alphanumeric type-ahead matching. @default  `false`. */
     typeahead?: boolean;
-    /** Idle timeout before clearing type-ahead buffer (ms). Defaults to `500`. */
+    /** Idle timeout before clearing type-ahead buffer (ms). @default  `500`. */
     resetMs?: number;
-    /** Explicit RTL override; null auto-detects from computed style. Defaults to `null`. */
+    /** Explicit RTL override; null auto-detects from computed style. @default  `null`. */
     rtl?: boolean | null;
-    /** Enables roving tabindex when not in virtual mode. Defaults to `null`. */
+    /** Enables roving tabindex when not in virtual mode. @default  `null`. */
     rovingTab?: boolean | null;
-    /** Default tabbable index when no active item is selected. Defaults to `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. Defaults to `"0"`. */
+    /** Base tabindex for non-active items, use `"-1"` to kill virtual list. @default  `"0"`. */
     baseTabIndex?: string;
-    /** Class applied to active item in virtual mode. Defaults to `"focus-outlined"`. */
+    /** Class applied to active item in virtual mode. @default  `"focus-outlined"`. */
     activeClass?: string;
-    /** Selector used for keyboard event source in virtual mode. Defaults to `"input[value],textarea,[contenteditable='true']"`. */
+    /** Selector used for keyboard event source in virtual mode. @default  `"input[value],textarea,[contenteditable]"`. */
     inputSelector?: string;
-    /** Scroll behavior options used when moving active item. Defaults to `{ block: "nearest", inline: "nearest" }`. */
+    /** Scroll behavior options used when moving active item. @default  `{ block: "nearest", inline: "nearest" }`. */
     scrollIntoView?: ScrollIntoViewOptions;
-    /** Focus behavior options used in non-virtual mode. Defaults to `{ preventScroll: false }`. */
+    /** Focus behavior options used in non-virtual mode. @default  `{ preventScroll: false }`. */
     focusOptions?: FocusOptions;
-    /** Explicit or computed grid dimensions for navigation math. Defaults to `{}`. */
+    /** 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;
@@ -48,13 +48,13 @@ interface ScrollAssistHandle {
 }
 /** Configuration for scroll assist overlays. */
 interface ScrollAssistConfig {
-    /** Scroll speed in pixels per second. Defaults to `80`. */
+    /** Scroll speed in pixels per second. @default  `80`. */
     pxPerSecond?: number;
-    /** Class name applied to assist overlays. Defaults to `"t007-scroll-assist"`. */
+    /** Class name applied to assist overlays. @default  `"t007-scroll-assist"`. */
     assistClassName?: string;
-    /** Enable vertical assist overlays. Defaults to `true`. */
+    /** Enable vertical assist overlays. @default  `true`. */
     vertical?: boolean;
-    /** Enable horizontal assist overlays. Defaults to `true`. */
+    /** 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.

package/dist/{scrollAssist-y9wFmYgt.d.ts → scrollAssist-l0V2H-jx.d.ts}

@@ -1,36 +1,36 @@
 type KeyEvent = Partial<KeyboardEvent> & Pick<KeyboardEvent, "key">;
 type Config = {
-    /** Enables or disables navigation logic. Defaults to `null`. */
+    /** Enables or disables navigation logic. @default  `null`. */
     enabled?: boolean | null;
-    /** CSS selector used to collect focusable nav items. Defaults to `"[data-arrow-item]"` */
+    /** CSS selector used to collect focusable nav items. @default  `"[data-arrow-item]"` */
     selector?: string;
-    /** Whether hover should also move active selection. Defaults to `true`. */
+    /** Whether hover should also move active selection. @default  `true`. */
     focusOnHover?: boolean;
-    /** Whether directional movement wraps around edges. Defaults to `true`. */
+    /** Whether directional movement wraps around edges. @default  `true`. */
     loop?: boolean;
-    /** Enables virtual focus (aria-activedescendant) mode. Defaults to `false`. */
+    /** Enables virtual focus (aria-activedescendant) mode. @default  `false`. */
     virtual?: boolean;
-    /** Enables alphanumeric type-ahead matching. Defaults to `false`. */
+    /** Enables alphanumeric type-ahead matching. @default  `false`. */
     typeahead?: boolean;
-    /** Idle timeout before clearing type-ahead buffer (ms). Defaults to `500`. */
+    /** Idle timeout before clearing type-ahead buffer (ms). @default  `500`. */
     resetMs?: number;
-    /** Explicit RTL override; null auto-detects from computed style. Defaults to `null`. */
+    /** Explicit RTL override; null auto-detects from computed style. @default  `null`. */
     rtl?: boolean | null;
-    /** Enables roving tabindex when not in virtual mode. Defaults to `null`. */
+    /** Enables roving tabindex when not in virtual mode. @default  `null`. */
     rovingTab?: boolean | null;
-    /** Default tabbable index when no active item is selected. Defaults to `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. Defaults to `"0"`. */
+    /** Base tabindex for non-active items, use `"-1"` to kill virtual list. @default  `"0"`. */
     baseTabIndex?: string;
-    /** Class applied to active item in virtual mode. Defaults to `"focus-outlined"`. */
+    /** Class applied to active item in virtual mode. @default  `"focus-outlined"`. */
     activeClass?: string;
-    /** Selector used for keyboard event source in virtual mode. Defaults to `"input[value],textarea,[contenteditable='true']"`. */
+    /** Selector used for keyboard event source in virtual mode. @default  `"input[value],textarea,[contenteditable]"`. */
     inputSelector?: string;
-    /** Scroll behavior options used when moving active item. Defaults to `{ block: "nearest", inline: "nearest" }`. */
+    /** Scroll behavior options used when moving active item. @default  `{ block: "nearest", inline: "nearest" }`. */
     scrollIntoView?: ScrollIntoViewOptions;
-    /** Focus behavior options used in non-virtual mode. Defaults to `{ preventScroll: false }`. */
+    /** Focus behavior options used in non-virtual mode. @default  `{ preventScroll: false }`. */
     focusOptions?: FocusOptions;
-    /** Explicit or computed grid dimensions for navigation math. Defaults to `{}`. */
+    /** 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;
@@ -48,13 +48,13 @@ interface ScrollAssistHandle {
 }
 /** Configuration for scroll assist overlays. */
 interface ScrollAssistConfig {
-    /** Scroll speed in pixels per second. Defaults to `80`. */
+    /** Scroll speed in pixels per second. @default  `80`. */
     pxPerSecond?: number;
-    /** Class name applied to assist overlays. Defaults to `"t007-scroll-assist"`. */
+    /** Class name applied to assist overlays. @default  `"t007-scroll-assist"`. */
     assistClassName?: string;
-    /** Enable vertical assist overlays. Defaults to `true`. */
+    /** Enable vertical assist overlays. @default  `true`. */
     vertical?: boolean;
-    /** Enable horizontal assist overlays. Defaults to `true`. */
+    /** 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.