customizable-toast-notification 3.14.0 → 3.16.0

package/dist/index.d.ts

@@ -1,3 +1,76 @@
+/**
+ * Updates global toast configuration.
+ * @param {Partial<ToastGlobalConfig>} [options]
+ * @returns {ToastGlobalConfig}
+ */
+declare function setConfig(options?: Partial<ToastGlobalConfig$1>): ToastGlobalConfig$1;
+/**
+ * Resets global toast configuration back to pristine defaults.
+ * Cleans up DOM attributes attached to document.documentElement.
+ * @returns {ToastGlobalConfig}
+ */
+declare function resetConfig(): ToastGlobalConfig$1;
+/**
+ * Returns a snapshot of the current global toast configuration.
+ * @returns {ToastGlobalConfig}
+ */
+declare function getConfig(): ToastGlobalConfig$1;
+/**
+ * Whether toast animations should be reduced for accessibility.
+ * @returns {boolean}
+ */
+declare function shouldReduceMotion(): boolean;
+type ReducedMotionMode$1 = "auto" | "always" | "never";
+type ToastTheme$1 = "light" | "dark" | "high-contrast" | "compact" | "spacious" | "glass";
+type ToastMountTarget$1 = Element | DocumentFragment | ShadowRoot;
+type ToastMetrics$1 = {
+    /**
+     * - Currently rendered active toasts
+     */
+    activeCount: number;
+    /**
+     * - Number of queued toasts waiting to be displayed
+     */
+    queueDepth: number;
+    /**
+     * - Count of currently visible toasts
+     */
+    visibleCount: number;
+    /**
+     * - Number of toasts dropped due to queue overflow
+     */
+    droppedCount: number;
+    /**
+     * - Epoch timestamp (ms) when metrics were recorded
+     */
+    timestamp: number;
+};
+type ToastGlobalConfig$1 = {
+    maxVisible: number;
+    maxQueueSize: number;
+    zIndex: number;
+    targetNode: ToastMountTarget$1 | null;
+    disableInlineStyles: boolean;
+    reducedMotion: ReducedMotionMode$1;
+    defaultPosition: string;
+    theme: ToastTheme$1;
+    stacked: boolean;
+    swipeToDismiss: boolean;
+    sound: boolean;
+    soundPreset?: "modern" | "retro" | "futuristic" | "subtle" | "bell" | string;
+    syncTabs: boolean;
+    aiPrioritization: boolean;
+    priorityScorer?: ((context: any) => number | {
+        score: number;
+    }) | null;
+    onMetrics?: ((metrics: ToastMetrics$1) => void) | null;
+};
+
+/**
+ * Returns a real-time snapshot of toast manager telemetry metrics.
+ * @returns {import('../utils/config.js').ToastMetrics}
+ */
+declare function getToastMetrics(): ToastMetrics$1;
 declare function resetToastManager(): void;
 /**
  * Updates an active, pending, or queued toast in-place with new options.
@@ -8,15 +81,40 @@ declare function updateToastByKey(key: string, newOptions?: Partial<ToastOptions
 
 declare function resetContainerRegistry(): void;
 
+/**
+ * Returns a shared AnalyserNode for real-time waveform visualization.
+ * @returns {AnalyserNode | null}
+ */
+declare function getAudioAnalyser(): AnalyserNode | null;
 /**
  * Synthesizes a pleasant audio chime or tone using pure Web Audio API oscillators.
  * Zero external audio assets or network requests.
- * @param {'success' | 'error' | 'warning' | 'info' | 'pop' | string} toneType
+ * @param {'success' | 'error' | 'warning' | 'info' | 'pop' | string} [toneType="info"]
+ * @param {'modern' | 'retro' | 'futuristic' | 'subtle' | 'bell' | string} [preset="modern"]
+ * @returns {void}
+ */
+declare function playTone(toneType?: "success" | "error" | "warning" | "info" | "pop" | string, preset?: "modern" | "retro" | "futuristic" | "subtle" | "bell" | string): void;
+/**
+ * Registers a custom sound synthesis preset.
+ * @param {string} name - Name of the preset (e.g. 'arcade')
+ * @param {(ctx: AudioContext, toneType: string, now: number) => void} synthesizerFn
+ * @returns {boolean} True if successfully registered
+ */
+declare function registerSoundPreset(name: string, synthesizerFn: (ctx: AudioContext, toneType: string, now: number) => void): boolean;
+/**
+ * Returns a list of all currently available sound presets (built-in + custom).
+ * @returns {string[]}
+ */
+declare function getSoundPresets(): string[];
+/**
+ * Clears custom sound presets (primarily for testing and environment resets).
+ * @returns {void}
  */
-declare function playTone(toneType?: "success" | "error" | "warning" | "info" | "pop" | string): void;
+declare function resetSoundPresets(): void;
 /**
  * Globally enable or disable synthesized notification sounds.
  * @param {boolean} enabled
+ * @returns {void}
  */
 declare function setAudioEnabled(enabled: boolean): void;
 /**
@@ -24,7 +122,408 @@ declare function setAudioEnabled(enabled: boolean): void;
  * @returns {boolean}
  */
 declare function isAudioEnabled(): boolean;
+/**
+ * Resets the cached AudioContext instance (useful for test isolation).
+ * @returns {void}
+ */
+declare function resetAudioContext(): void;
 
+/**
+ * Get or create the global toast pool instance
+ * @param {number} [initialSize=5] - Initial pool size
+ * @param {number} [maxSize=50] - Maximum pool size
+ * @returns {ToastElementPool}
+ */
+declare function getToastPool(initialSize?: number, maxSize?: number): ToastElementPool;
+/**
+ * Reset pool instance (for testing)
+ */
+declare function resetToastPool(): void;
+/**
+ * @typedef {Object} PooledToastElement
+ * @property {HTMLElement} element - The reusable toast element
+ * @property {boolean} inUse - Whether element is currently allocated
+ * @property {string | null} id - Unique toast ID
+ */
+declare class ToastElementPool {
+    constructor(initialSize?: number, maxSize?: number);
+    initialSize: number;
+    maxSize: number;
+    /** @type {Array<{element: HTMLElement, inUse: boolean, id: string | null}>} */
+    pool: Array<{
+        element: HTMLElement;
+        inUse: boolean;
+        id: string | null;
+    }>;
+    inUseCount: number;
+    /**
+     * Create a new toast element template
+     * @private
+     * @returns {HTMLElement}
+     */
+    private _createToastElement;
+    /**
+     * Acquire a toast element from pool or create new one
+     * @param {string} toastId - Unique identifier for this toast
+     * @returns {HTMLElement} - Ready-to-use toast element
+     */
+    acquire(toastId: string): HTMLElement;
+    /**
+     * Release a toast element back to pool
+     * @param {HTMLElement} element - The element to release
+     * @param {string} toastId - The toast ID being released
+     * @returns {void}
+     */
+    release(element: HTMLElement, toastId: string): void;
+    /**
+     * Get pool statistics for monitoring
+     * @returns {{total: number, inUse: number, available: number, utilization: number, maxSize: number}} - Pool stats
+     */
+    getStats(): {
+        total: number;
+        inUse: number;
+        available: number;
+        utilization: number;
+        maxSize: number;
+    };
+    /**
+     * Clear all pooled elements (for cleanup/testing)
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Compact pool (remove unused elements above initial size)
+     * Useful for long-running apps with temporary toast spikes
+     * @returns {void}
+     */
+    compact(): void;
+}
+
+/**
+ * Get or create the global broadcaster instance
+ * @returns {ToastBroadcaster}
+ */
+declare function getToastBroadcaster(): ToastBroadcaster;
+/**
+ * Reset broadcaster instance (for testing)
+ */
+declare function resetToastBroadcaster(): void;
+/**
+ * @typedef {Object} ToastSyncMessage
+ * @property {string} type - Message type: 'create', 'update', 'dismiss', 'sync-request', 'sync-response'
+ * @property {string} toastId - Unique toast identifier
+ * @property {Object} payload - Message-specific data
+ * @property {number} timestamp - Message timestamp
+ * @property {string} tabId - Originating tab ID
+ */
+declare class ToastBroadcaster {
+    channel: BroadcastChannel;
+    tabId: string;
+    isLeadTab: boolean;
+    listeners: Map<any, any>;
+    supportsBroadcastChannel: boolean;
+    /**
+     * Generate unique tab identifier with high cross-tab entropy.
+     * Unlike DOM element IDs (which rely on monotonic counters within a single thread),
+     * tab IDs must guarantee uniqueness across independent browser processes/tabs
+     * that do not share memory even if opened in the exact same millisecond.
+     *
+     * @private
+     * @returns {string} Unique tab ID matching /^tab-[a-z0-9]+-[a-z0-9]+$/
+     */
+    private _generateTabId;
+    /**
+     * Initialize BroadcastChannel if available
+     * @private
+     */
+    private _initBroadcastChannel;
+    /**
+     * Attempt to become the lead tab
+     * @private
+     */
+    private _becomeLeadIfNeeded;
+    leaderTimer: any;
+    /**
+     * Broadcast a toast event to other tabs
+     * @param {string} type - Event type
+     * @param {string} [toastId=''] - Toast ID
+     * @param {Object} [payload={}] - Event payload
+     */
+    broadcast(type: string, toastId?: string, payload?: any): void;
+    /**
+     * Handle incoming message from other tab
+     * @private
+     * @param {ToastSyncMessage} message
+     */
+    private _handleMessage;
+    /**
+     * Register listener for toast events
+     * @param {string} type - Event type to listen for
+     * @param {Function} callback - Callback function
+     * @returns {Function} - Unsubscribe function
+     */
+    on(type: string, callback: Function): Function;
+    /**
+     * Register active toasts getter (set by ToastManager)
+     * @param {Function} getter
+     */
+    registerActiveToastsGetter(getter: Function): void;
+    _getActiveToasts: Function;
+    /**
+     * Register queued toasts getter (set by ToastManager)
+     * @param {Function} getter
+     */
+    registerQueuedToastsGetter(getter: Function): void;
+    _getQueuedToasts: Function;
+    /**
+     * Check if cross-tab sync is supported
+     * @returns {boolean}
+     */
+    isSupported(): boolean;
+    /**
+     * Get current tab ID
+     * @returns {string}
+     */
+    getTabId(): string;
+    /**
+     * Is this the lead tab
+     * @returns {boolean}
+     */
+    isLeadingTab(): boolean;
+    /**
+     * Cleanup on unload
+     */
+    destroy(): void;
+}
+
+/**
+ * Calculate priority score for toast based on type, message, and context
+ * @param {ToastScoringContext} context
+ * @returns {ScorerResult}
+ */
+declare function calculateToastPriority(context: ToastScoringContext): ScorerResult;
+/**
+ * Extract semantic category from toast message
+ * @param {string} message
+ * @returns {string[]} - Categories (security, performance, user, system, etc.)
+ */
+declare function categorizeToast(message: string): string[];
+type ToastScoringContext = {
+    /**
+     * - Toast type (success, error, warning, info)
+     */
+    type: string;
+    /**
+     * - Toast message content
+     */
+    message: string;
+    /**
+     * - Duration in milliseconds
+     */
+    duration: number;
+    /**
+     * - Full toast options
+     */
+    options: any;
+};
+type ScorerResult = {
+    /**
+     * - Priority score (0-100)
+     */
+    score: number;
+    /**
+     * - Score breakdown by factor
+     */
+    breakdown: any;
+    /**
+     * - Detected keywords affecting score
+     */
+    keywords: string[];
+};
+
+/**
+ * Calculate velocity of a swipe gesture
+ * @param {number} distance - Distance traveled in pixels
+ * @param {number} duration - Duration in milliseconds
+ * @returns {number} - Velocity in pixels/millisecond
+ */
+declare function calculateVelocity(distance: number, duration: number): number;
+/**
+ * Detect if gesture is a flick (fast swipe with high velocity)
+ * @param {number} velocity - Gesture velocity (px/ms)
+ * @param {number} distance - Distance traveled (px)
+ * @param {number} [velocityThreshold=0.5] - Minimum velocity for flick (default 0.5 px/ms)
+ * @param {number} [distanceThreshold=50] - Minimum distance for flick (default 50px)
+ * @returns {boolean}
+ */
+declare function isFlick(velocity: number, distance: number, velocityThreshold?: number, distanceThreshold?: number): boolean;
+/**
+ * Detect pinch gesture (two-finger distance change)
+ * @param {GestureState} state
+ * @param {number} sensitivityThreshold - Minimum distance change for pinch (default 20px)
+ * @returns {Object} - Pinch info { isPinch, scale, direction }
+ */
+declare function detectPinch(state: GestureState, sensitivityThreshold?: number): any;
+/**
+ * Create gesture detector function for element
+ * @param {HTMLElement} element
+ * @param {Object} options
+ * @returns {Object} - Detector with attach/detach methods
+ */
+declare function createGestureDetector(element: HTMLElement, options?: any): any;
+type TouchPoint = {
+    /**
+     * - X coordinate
+     */
+    x: number;
+    /**
+     * - Y coordinate
+     */
+    y: number;
+    /**
+     * - Touch identifier
+     */
+    id: number;
+    /**
+     * - Timestamp
+     */
+    time: number;
+};
+type GestureState = {
+    /**
+     * - Current touch points
+     */
+    touches: TouchPoint[];
+    /**
+     * - Initial touch points
+     */
+    startTouches: TouchPoint[];
+    /**
+     * - Gesture start time
+     */
+    startTime: number;
+    /**
+     * - Initial distance between touches (for pinch)
+     */
+    startDistance: number;
+    /**
+     * - Current distance between touches
+     */
+    currentDistance: number;
+};
+
+/**
+ * Reset the internal monotonic counter (primarily for test isolation)
+ * @returns {void}
+ */
+declare function resetToastIdCounter(): void;
+/**
+ * Generate unique, CSS-safe ID for DOM elements.
+ * Combines sanitized prefix, millisecond timestamp, and monotonic counter with session salt.
+ * Guarantees 0% collision rate without HTTP/HTTPS secure context restrictions.
+ *
+ * @param {string} [prefix="toast"] - Optional prefix for ID
+ * @returns {string} Unique ID matching /^toast-[a-z0-9]+-[a-z0-9]+$/
+ */
+declare function generateToastId(prefix?: string): string;
+
+/**
+ * Register a custom named spring preset.
+ * @param {string} name - Unique preset identifier
+ * @param {SpringConfig & { bezierFallback?: string }} config - Spring parameters
+ */
+declare function registerSpringPreset(name: string, config: SpringConfig$1 & {
+    bezierFallback?: string;
+}): void;
+/**
+ * Retrieve list of registered spring preset names.
+ * @returns {string[]}
+ */
+declare function getSpringPresets(): string[];
+/**
+ * Reset all registered custom spring presets back to defaults.
+ */
+declare function resetSpringPresets(): void;
+/**
+ * Resolves a spring input into concrete numerical physics constants.
+ * @param {boolean | SpringPreset | SpringConfig} spring - Preset name or custom parameters
+ * @returns {{ stiffness: number, damping: number, mass: number, bezierFallback: string } | null}
+ */
+declare function resolveSpringConfig(spring: boolean | SpringPreset$1 | SpringConfig$1): {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    bezierFallback: string;
+} | null;
+/**
+ * Solves the damped harmonic oscillator step response at time t (in seconds).
+ * Returns displacement value y(t) transitioning from 0 to 1.
+ *
+ * @param {number} t - Time in seconds (t >= 0)
+ * @param {{ stiffness: number, damping: number, mass: number }} config
+ * @returns {number} Value of step response at time t
+ */
+declare function solveSpring(t: number, config: {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}): number;
+/**
+ * Calculates the duration (in milliseconds) required for the spring to settle
+ * within an acceptable error threshold (default: 0.005 / 0.5%).
+ *
+ * @param {{ stiffness: number, damping: number, mass: number }} config
+ * @param {number} [threshold=0.005]
+ * @returns {number} Settling duration in milliseconds
+ */
+declare function calculateSpringSettlingDuration(config: {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}, threshold?: number): number;
+/**
+ * Generates a modern CSS linear(...) timing function representation of the spring motion.
+ * @param {{ stiffness: number, damping: number, mass: number }} config
+ * @param {number} [points=32]
+ * @returns {string} CSS linear(...) curve string
+ */
+declare function generateSpringLinearEasing(config: {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}, points?: number): string;
+/**
+ * Returns comprehensive transition timing, easing, and duration parameters for a toast with spring physics.
+ * @param {boolean | SpringPreset | SpringConfig} spring
+ * @returns {{ config: { stiffness: number, damping: number, mass: number }, duration: number, easing: string, isSpring: boolean } | null}
+ */
+declare function getSpringTransition(spring: boolean | SpringPreset$1 | SpringConfig$1): {
+    config: {
+        stiffness: number;
+        damping: number;
+        mass: number;
+    };
+    duration: number;
+    easing: string;
+    isSpring: boolean;
+} | null;
+type SpringConfig$1 = {
+    /**
+     * - Spring tension / stiffness constant (k > 0)
+     */
+    stiffness?: number;
+    /**
+     * - Damping friction coefficient (c > 0)
+     */
+    damping?: number;
+    /**
+     * - Inertial mass (m > 0)
+     */
+    mass?: number;
+};
+type SpringPreset$1 = "default" | "gentle" | "wobbly" | "stiff" | "bouncy" | string;
+
+type SoundPreset = "modern" | "retro" | "futuristic" | "subtle" | "bell" | string;
 type ToastType = "info" | "success" | "error" | "warning";
 type ToastPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center" | "top-full-width" | "bottom-full-width" | "center";
 type CTAOptions = {
@@ -37,6 +536,35 @@ type CTAOptions = {
     autoClose?: boolean;
     onClick?: (e: MouseEvent) => void | Promise<void>;
 };
+type UndoOptions = {
+    /**
+     * - Button text label (default: 'Undo')
+     */
+    label?: string;
+    /**
+     * - Whether to display decaying seconds counter (default: true)
+     */
+    showCountdown?: boolean;
+    /**
+     * - Callback fired when clicked
+     */
+    onUndo?: (e: MouseEvent, toast: HTMLElement) => void | Promise<void>;
+};
+type SpringConfig = {
+    /**
+     * - Spring stiffness constant (k > 0)
+     */
+    stiffness?: number;
+    /**
+     * - Damping friction coefficient (c > 0)
+     */
+    damping?: number;
+    /**
+     * - Inertial mass (m > 0)
+     */
+    mass?: number;
+};
+type SpringPreset = "default" | "gentle" | "wobbly" | "stiff" | "bouncy" | string;
 type ToastLoaderOptions = {
     /**
      * - Spinner size in pixels (default 14)
@@ -80,11 +608,63 @@ type ToastOptions = {
     fontDirection?: "auto" | "ltr" | "rtl";
     fontPadding?: string;
     className?: string;
-    cta?: CTAOptions;
+    cta?: CTAOptions | CTAOptions[];
+    undo?: ((e: MouseEvent, toast: HTMLElement) => void | Promise<void>) | UndoOptions;
+    spring?: boolean | SpringPreset | SpringConfig;
     stacked?: boolean;
     sound?: boolean | "success" | "error" | "warning" | "info" | "pop" | string;
+    soundPreset?: SoundPreset;
     swipeToDismiss?: boolean;
     progress?: number;
+    syncTabs?: boolean;
+    aiPrioritization?: boolean;
+    priority?: number;
+    usePool?: boolean;
+};
+type ReducedMotionMode = "auto" | "always" | "never";
+type ToastTheme = "light" | "dark" | "high-contrast" | "compact" | "spacious" | "glass";
+type ToastMountTarget = Element | DocumentFragment | ShadowRoot;
+type ToastMetrics = {
+    /**
+     * - Currently rendered active toasts
+     */
+    activeCount: number;
+    /**
+     * - Number of queued toasts waiting to be displayed
+     */
+    queueDepth: number;
+    /**
+     * - Count of currently visible toasts
+     */
+    visibleCount: number;
+    /**
+     * - Number of toasts dropped due to queue overflow
+     */
+    droppedCount: number;
+    /**
+     * - Epoch timestamp (ms) when metrics were recorded
+     */
+    timestamp: number;
+};
+type ToastGlobalConfig = {
+    maxVisible?: number;
+    maxQueueSize?: number;
+    zIndex?: number;
+    targetNode?: ToastMountTarget | null;
+    disableInlineStyles?: boolean;
+    reducedMotion?: ReducedMotionMode;
+    defaultPosition?: ToastPosition | string;
+    theme?: ToastTheme;
+    stacked?: boolean;
+    swipeToDismiss?: boolean;
+    sound?: boolean;
+    soundPreset?: SoundPreset;
+    syncTabs?: boolean;
+    aiPrioritization?: boolean;
+    priorityScorer?: ((context: any) => number | {
+        score: number;
+    }) | null;
+    onMetrics?: ((metrics: ToastMetrics) => void) | null;
 };
 type ToastHandle = {
     dismiss: () => Promise<void>;
@@ -113,7 +693,7 @@ declare function setDefaultColors(colors: Partial<Record<ToastType, string>>): v
 declare function setDefaultMessages(messages: Partial<Record<ToastType, string>>): void;
 declare function dismissToast(): Promise<void>;
 declare function noopAll(): Promise<void>;
-declare const version: "3.13.0";
+declare const version: any;
 /**
  * Wraps a promise or function with automatic loading, success, and error toasts.
  * @template T
@@ -124,5 +704,5 @@ declare const version: "3.13.0";
  */
 declare function toastPromise<T>(promiseOrFn: Promise<T> | (() => Promise<T> | T), messages?: ToastPromiseMessages, options?: ToastOptions): Promise<T>;
 
-export { createToastWithPriority as createToast, dismissToast as dismiss, isAudioEnabled, noopAll as noop, playTone, resetContainerRegistry, resetToastManager, setAudioEnabled, setDefaultColors, setDefaultMessages, toastPromise, updateToastByKey, version };
-export type { CTAOptions, ToastHandle, ToastLoaderOptions, ToastOptions, ToastPosition, ToastPromiseMessages, ToastType };
+export { calculateSpringSettlingDuration, calculateToastPriority, calculateVelocity, categorizeToast, createGestureDetector, createToastWithPriority as createToast, detectPinch, dismissToast as dismiss, generateSpringLinearEasing, generateToastId, getAudioAnalyser, getConfig, getSoundPresets, getSpringPresets, getSpringTransition, getToastBroadcaster, getToastMetrics, getToastPool, isAudioEnabled, isFlick, noopAll as noop, playTone, registerSoundPreset, registerSpringPreset, resetAudioContext, resetConfig, resetContainerRegistry, resetSoundPresets, resetSpringPresets, resetToastBroadcaster, resetToastIdCounter, resetToastManager, resetToastPool, resolveSpringConfig, setAudioEnabled, setConfig, setDefaultColors, setDefaultMessages, shouldReduceMotion, solveSpring, toastPromise, updateToastByKey, version };
+export type { CTAOptions, ReducedMotionMode, SoundPreset, SpringConfig, SpringPreset, ToastGlobalConfig, ToastHandle, ToastLoaderOptions, ToastMetrics, ToastMountTarget, ToastOptions, ToastPosition, ToastPromiseMessages, ToastTheme, ToastType, UndoOptions };