@flikk/ui 1.0.0-beta.1

package/dist/utils/performanceMonitor.d.ts

@@ -0,0 +1,56 @@
+import { PerformanceMetrics } from '../components/core/ScrollArea/smooth/SmoothScrollEngine.types';
+/**
+ * Performance monitoring for smooth scroll engine
+ * Tracks FPS, frame drops, and average frame time
+ */
+export declare class PerformanceMonitor {
+    private frames;
+    private droppedFrames;
+    private totalFrames;
+    private lastReportTime;
+    private targetFPS;
+    private targetFrameTime;
+    private onUpdate;
+    private reportInterval;
+    constructor(targetFPS?: number);
+    /**
+     * Record a frame
+     * @param timestamp - Current timestamp from RAF
+     */
+    recordFrame(timestamp: number): void;
+    /**
+     * Record a dropped frame
+     */
+    recordDroppedFrame(): void;
+    /**
+     * Calculate and report metrics
+     */
+    private report;
+    /**
+     * Set callback for metrics updates
+     */
+    setOnUpdate(callback: (metrics: PerformanceMetrics) => void): void;
+    /**
+     * Update target FPS
+     */
+    setTargetFPS(fps: number): void;
+    /**
+     * Get target frame time
+     */
+    getTargetFrameTime(): number;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Destroy the monitor
+     */
+    destroy(): void;
+}
+/**
+ * React hook wrapper for PerformanceMonitor
+ * @param targetFPS - Target frames per second
+ * @param onUpdate - Callback for metrics updates
+ * @returns PerformanceMonitor instance
+ */
+export declare function usePerformanceMonitor(targetFPS?: number, onUpdate?: (metrics: PerformanceMetrics) => void): PerformanceMonitor;

package/dist/utils/performanceMonitor.js

@@ -0,0 +1,102 @@
+import 'react';
+
+/**
+ * Performance monitoring for smooth scroll engine
+ * Tracks FPS, frame drops, and average frame time
+ */
+class PerformanceMonitor {
+    constructor(targetFPS = 60) {
+        this.frames = [];
+        this.droppedFrames = 0;
+        this.totalFrames = 0;
+        this.lastReportTime = 0;
+        this.onUpdate = null;
+        this.reportInterval = 1000; // Report every second
+        this.targetFPS = targetFPS;
+        this.targetFrameTime = 1000 / targetFPS;
+    }
+    /**
+     * Record a frame
+     * @param timestamp - Current timestamp from RAF
+     */
+    recordFrame(timestamp) {
+        this.frames.push(timestamp);
+        this.totalFrames++;
+        // Keep only last second of frames
+        const oneSecondAgo = timestamp - 1000;
+        this.frames = this.frames.filter((t) => t > oneSecondAgo);
+        // Report metrics every interval
+        if (timestamp - this.lastReportTime >= this.reportInterval) {
+            this.report(timestamp);
+            this.lastReportTime = timestamp;
+        }
+    }
+    /**
+     * Record a dropped frame
+     */
+    recordDroppedFrame() {
+        this.droppedFrames++;
+    }
+    /**
+     * Calculate and report metrics
+     */
+    report(timestamp) {
+        if (!this.onUpdate || this.frames.length < 2)
+            return;
+        // Calculate FPS from frames in last second
+        const fps = this.frames.length;
+        // Calculate average frame time
+        let totalFrameTime = 0;
+        for (let i = 1; i < this.frames.length; i++) {
+            totalFrameTime += this.frames[i] - this.frames[i - 1];
+        }
+        const avgFrameTime = this.frames.length > 1 ? totalFrameTime / (this.frames.length - 1) : 0;
+        // Check if below target (within 10% tolerance)
+        const isBelowTarget = fps < this.targetFPS * 0.9;
+        const metrics = {
+            fps,
+            avgFrameTime,
+            droppedFrames: this.droppedFrames,
+            totalFrames: this.totalFrames,
+            isBelowTarget,
+        };
+        this.onUpdate(metrics);
+    }
+    /**
+     * Set callback for metrics updates
+     */
+    setOnUpdate(callback) {
+        this.onUpdate = callback;
+    }
+    /**
+     * Update target FPS
+     */
+    setTargetFPS(fps) {
+        this.targetFPS = fps;
+        this.targetFrameTime = 1000 / fps;
+    }
+    /**
+     * Get target frame time
+     */
+    getTargetFrameTime() {
+        return this.targetFrameTime;
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        this.frames = [];
+        this.droppedFrames = 0;
+        this.totalFrames = 0;
+        this.lastReportTime = 0;
+    }
+    /**
+     * Destroy the monitor
+     */
+    destroy() {
+        this.frames = [];
+        this.onUpdate = null;
+    }
+}
+
+export { PerformanceMonitor };

package/dist/utils/retryUtils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Retry Logic Utilities
+ * Handles exponential backoff and retry decision logic for streaming errors
+ */
+import type { StreamingError } from './streamingErrors';
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelay?: number;
+    /** Delay multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelay?: number;
+    /** Custom retry logic function */
+    shouldRetry?: (error: StreamingError, attempt: number) => boolean;
+}
+/**
+ * Calculate retry delay using exponential backoff
+ *
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns Delay in milliseconds before next retry
+ *
+ * @example
+ * calculateRetryDelay(0) // Returns: 1000ms
+ * calculateRetryDelay(1) // Returns: 2000ms
+ * calculateRetryDelay(2) // Returns: 4000ms
+ * calculateRetryDelay(3) // Returns: 8000ms
+ * calculateRetryDelay(4) // Returns: 10000ms (capped at maxDelay)
+ */
+export declare const calculateRetryDelay: (attempt: number, config?: RetryConfig) => number;
+/**
+ * Determine if a streaming error should be retried
+ *
+ * @param error - The streaming error that occurred
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns True if should retry, false otherwise
+ *
+ * @example
+ * shouldRetry(networkError, 0) // Returns: true
+ * shouldRetry(networkError, 3) // Returns: false (max attempts reached)
+ * shouldRetry(parseError, 0) // Returns: false (not retryable)
+ */
+export declare const shouldRetry: (error: StreamingError, attempt: number, config?: RetryConfig) => boolean;

package/dist/utils/retryUtils.js

@@ -0,0 +1,53 @@
+/**
+ * Retry Logic Utilities
+ * Handles exponential backoff and retry decision logic for streaming errors
+ */
+/**
+ * Calculate retry delay using exponential backoff
+ *
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns Delay in milliseconds before next retry
+ *
+ * @example
+ * calculateRetryDelay(0) // Returns: 1000ms
+ * calculateRetryDelay(1) // Returns: 2000ms
+ * calculateRetryDelay(2) // Returns: 4000ms
+ * calculateRetryDelay(3) // Returns: 8000ms
+ * calculateRetryDelay(4) // Returns: 10000ms (capped at maxDelay)
+ */
+const calculateRetryDelay = (attempt, config) => {
+    const initialDelay = (config === null || config === void 0 ? void 0 : config.initialDelay) || 1000;
+    const multiplier = (config === null || config === void 0 ? void 0 : config.backoffMultiplier) || 2;
+    const maxDelay = (config === null || config === void 0 ? void 0 : config.maxDelay) || 10000;
+    const delay = initialDelay * Math.pow(multiplier, attempt);
+    return Math.min(delay, maxDelay);
+};
+/**
+ * Determine if a streaming error should be retried
+ *
+ * @param error - The streaming error that occurred
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns True if should retry, false otherwise
+ *
+ * @example
+ * shouldRetry(networkError, 0) // Returns: true
+ * shouldRetry(networkError, 3) // Returns: false (max attempts reached)
+ * shouldRetry(parseError, 0) // Returns: false (not retryable)
+ */
+const shouldRetry = (error, attempt, config) => {
+    const maxAttempts = (config === null || config === void 0 ? void 0 : config.maxAttempts) || 3;
+    // Use custom retry logic if provided
+    if (config === null || config === void 0 ? void 0 : config.shouldRetry) {
+        return config.shouldRetry(error, attempt);
+    }
+    // Don't retry if max attempts reached
+    if (attempt >= maxAttempts) {
+        return false;
+    }
+    // Only retry if error is marked as retryable
+    return error.retryable;
+};
+
+export { calculateRetryDelay, shouldRetry };

package/dist/utils/smoothScrollUtils.d.ts

@@ -0,0 +1,92 @@
+import { ScrollDirection } from '../components/core/ScrollArea/smooth/SmoothScrollEngine.types';
+/**
+ * Calculate velocity from position change
+ *
+ * @param current - Current position
+ * @param previous - Previous position
+ * @param deltaTime - Time elapsed in milliseconds
+ * @returns Velocity in pixels per frame
+ */
+export declare function calculateVelocity(current: number, previous: number, deltaTime: number): number;
+/**
+ * Clamp scroll position to valid bounds
+ *
+ * @param position - Position to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped position
+ */
+export declare function clampScroll(position: number, min: number, max: number): number;
+/**
+ * Detect scroll direction from velocity
+ *
+ * @param velocity - Current velocity
+ * @param threshold - Minimum velocity to detect direction (default: 0.1)
+ * @returns 1 for down/right, -1 for up/left, 0 for stationary
+ */
+export declare function detectScrollDirection(velocity: number, threshold?: number): ScrollDirection;
+/**
+ * Check if user prefers reduced motion
+ *
+ * @returns True if prefers-reduced-motion is set
+ */
+export declare function isReducedMotion(): boolean;
+/**
+ * Linear interpolation between two values
+ *
+ * @param start - Start value
+ * @param end - End value
+ * @param factor - Interpolation factor (0-1)
+ * @returns Interpolated value
+ */
+export declare function lerp(start: number, end: number, factor: number): number;
+/**
+ * Calculate scroll progress as percentage
+ *
+ * @param current - Current scroll position
+ * @param max - Maximum scroll position
+ * @returns Progress from 0 to 1
+ */
+export declare function calculateScrollProgress(current: number, max: number): number;
+/**
+ * Normalize wheel delta across different browsers and input devices
+ *
+ * @param event - WheelEvent
+ * @param orientation - Scroll orientation ('vertical' uses deltaY, 'horizontal' uses deltaX)
+ * @returns Normalized delta and device detection
+ */
+export declare function normalizeWheelDelta(event: WheelEvent, orientation?: 'vertical' | 'horizontal'): {
+    delta: number;
+    isTouchpad: boolean;
+};
+/**
+ * Check if element is scrollable
+ *
+ * @param element - Element to check
+ * @returns True if element has scrollable overflow
+ */
+export declare function isScrollable(element: HTMLElement | null): boolean;
+/**
+ * Get maximum scroll position for element
+ *
+ * @param element - Scrollable element
+ * @param orientation - Scroll orientation
+ * @returns Maximum scroll position
+ */
+export declare function getMaxScroll(element: HTMLElement, orientation?: 'vertical' | 'horizontal'): number;
+/**
+ * Debounce function for performance optimization
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle function for performance optimization
+ *
+ * @param fn - Function to throttle
+ * @param limit - Time limit in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;

package/dist/utils/smoothScrollUtils.js

@@ -0,0 +1,122 @@
+/**
+ * Calculate velocity from position change
+ *
+ * @param current - Current position
+ * @param previous - Previous position
+ * @param deltaTime - Time elapsed in milliseconds
+ * @returns Velocity in pixels per frame
+ */
+function calculateVelocity(current, previous, deltaTime) {
+    if (deltaTime === 0)
+        return 0;
+    // Convert to pixels per frame (assuming 60fps = 16.67ms per frame)
+    const frameTime = 16.67;
+    return ((current - previous) / deltaTime) * frameTime;
+}
+/**
+ * Clamp scroll position to valid bounds
+ *
+ * @param position - Position to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped position
+ */
+function clampScroll(position, min, max) {
+    return Math.max(min, Math.min(max, position));
+}
+/**
+ * Detect scroll direction from velocity
+ *
+ * @param velocity - Current velocity
+ * @param threshold - Minimum velocity to detect direction (default: 0.1)
+ * @returns 1 for down/right, -1 for up/left, 0 for stationary
+ */
+function detectScrollDirection(velocity, threshold = 0.1) {
+    if (Math.abs(velocity) < threshold)
+        return 0;
+    return velocity > 0 ? 1 : -1;
+}
+/**
+ * Check if user prefers reduced motion
+ *
+ * @returns True if prefers-reduced-motion is set
+ */
+function isReducedMotion() {
+    if (typeof window === 'undefined')
+        return false;
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Linear interpolation between two values
+ *
+ * @param start - Start value
+ * @param end - End value
+ * @param factor - Interpolation factor (0-1)
+ * @returns Interpolated value
+ */
+function lerp(start, end, factor) {
+    return start + (end - start) * factor;
+}
+/**
+ * Calculate scroll progress as percentage
+ *
+ * @param current - Current scroll position
+ * @param max - Maximum scroll position
+ * @returns Progress from 0 to 1
+ */
+function calculateScrollProgress(current, max) {
+    if (max === 0)
+        return 0;
+    return Math.max(0, Math.min(1, current / max));
+}
+/**
+ * Normalize wheel delta across different browsers and input devices
+ *
+ * @param event - WheelEvent
+ * @param orientation - Scroll orientation ('vertical' uses deltaY, 'horizontal' uses deltaX)
+ * @returns Normalized delta and device detection
+ */
+function normalizeWheelDelta(event, orientation = 'vertical') {
+    // Pick the axis that matches orientation.
+    // For horizontal, prefer deltaX but fall back to deltaY (shift+wheel on
+    // some browsers sends deltaY even for horizontal scrolling).
+    const rawDelta = orientation === 'horizontal'
+        ? (event.deltaX !== 0 ? event.deltaX : event.deltaY)
+        : event.deltaY;
+    let delta = 0;
+    // Determine delta based on deltaMode
+    switch (event.deltaMode) {
+        case 0: // Pixels (most common)
+            delta = rawDelta;
+            break;
+        case 1: // Lines
+            delta = rawDelta * 16; // Approximate line height
+            break;
+        case 2: // Pages
+            delta =
+                rawDelta *
+                    (orientation === 'horizontal'
+                        ? window.innerWidth
+                        : window.innerHeight);
+            break;
+    }
+    // Detect trackpad vs mouse wheel
+    // Trackpad typically has smaller, more frequent deltas
+    const isTouchpad = Math.abs(delta) < 50;
+    return { delta, isTouchpad };
+}
+/**
+ * Get maximum scroll position for element
+ *
+ * @param element - Scrollable element
+ * @param orientation - Scroll orientation
+ * @returns Maximum scroll position
+ */
+function getMaxScroll(element, orientation = 'vertical') {
+    if (orientation === 'horizontal') {
+        return element.scrollWidth - element.clientWidth;
+    }
+    return element.scrollHeight - element.clientHeight;
+}
+
+export { calculateScrollProgress, calculateVelocity, clampScroll, detectScrollDirection, getMaxScroll, isReducedMotion, lerp, normalizeWheelDelta };

package/dist/utils/sseFormatParsers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SSE Format Parsers for different AI providers
+ * Handles parsing Server-Sent Events from OpenAI, Anthropic (Claude), and Google Gemini APIs
+ */
+export type SSEFormat = 'openai' | 'anthropic' | 'google-gemini';
+export type SSEParser = (line: string) => string | null;
+/**
+ * OpenAI streaming format parser
+ * Format: data: {"choices":[{"delta":{"content":"token"}}]}
+ * End signal: data: [DONE]
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseOpenAI('data: {"choices":[{"delta":{"content":"Hello"}}]}')
+ * // Returns: "Hello"
+ */
+export declare const parseOpenAI: SSEParser;
+/**
+ * Anthropic (Claude) streaming format parser
+ * Format:
+ *   event: content_block_delta
+ *   data: {"delta":{"type":"text_delta","text":"token"}}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseAnthropic('data: {"delta":{"type":"text_delta","text":"Hello"}}')
+ * // Returns: "Hello"
+ */
+export declare const parseAnthropic: SSEParser;
+/**
+ * Google Gemini streaming format parser
+ * Format: data: {"candidates":[{"content":{"parts":[{"text":"token"}]}}]}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseGemini('data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}')
+ * // Returns: "Hello"
+ */
+export declare const parseGemini: SSEParser;
+/**
+ * Parser registry mapping format names to parser functions
+ */
+export declare const SSE_PARSERS: Record<SSEFormat, SSEParser>;
+/**
+ * Parse an SSE line using the specified format parser
+ *
+ * @param line - Raw SSE line from stream
+ * @param format - AI provider format or custom parser function
+ * @returns Extracted token or null
+ *
+ * @example
+ * // Using predefined format
+ * parseSSELine('data: {...}', 'openai')
+ *
+ * // Using custom parser
+ * parseSSELine('data: {...}', (line) => customParser(line))
+ */
+export declare const parseSSELine: (line: string, format: SSEFormat | SSEParser) => string | null;

package/dist/utils/sseFormatParsers.js

@@ -0,0 +1,124 @@
+/**
+ * SSE Format Parsers for different AI providers
+ * Handles parsing Server-Sent Events from OpenAI, Anthropic (Claude), and Google Gemini APIs
+ */
+/**
+ * OpenAI streaming format parser
+ * Format: data: {"choices":[{"delta":{"content":"token"}}]}
+ * End signal: data: [DONE]
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseOpenAI('data: {"choices":[{"delta":{"content":"Hello"}}]}')
+ * // Returns: "Hello"
+ */
+const parseOpenAI = (line) => {
+    var _a, _b, _c;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    // Handle stream end signal
+    if (data === '[DONE]')
+        return null;
+    try {
+        const parsed = JSON.parse(data);
+        return ((_c = (_b = (_a = parsed.choices) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.delta) === null || _c === void 0 ? void 0 : _c.content) || null;
+    }
+    catch (_d) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Anthropic (Claude) streaming format parser
+ * Format:
+ *   event: content_block_delta
+ *   data: {"delta":{"type":"text_delta","text":"token"}}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseAnthropic('data: {"delta":{"type":"text_delta","text":"Hello"}}')
+ * // Returns: "Hello"
+ */
+const parseAnthropic = (line) => {
+    var _a, _b;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    try {
+        const parsed = JSON.parse(data);
+        // Anthropic sends different event types - we only care about text deltas
+        if (parsed.type === 'content_block_delta') {
+            return ((_a = parsed.delta) === null || _a === void 0 ? void 0 : _a.text) || null;
+        }
+        // Also handle direct delta format
+        if (((_b = parsed.delta) === null || _b === void 0 ? void 0 : _b.type) === 'text_delta') {
+            return parsed.delta.text || null;
+        }
+        return null;
+    }
+    catch (_c) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Google Gemini streaming format parser
+ * Format: data: {"candidates":[{"content":{"parts":[{"text":"token"}]}}]}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseGemini('data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}')
+ * // Returns: "Hello"
+ */
+const parseGemini = (line) => {
+    var _a, _b, _c, _d, _e;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    try {
+        const parsed = JSON.parse(data);
+        return ((_e = (_d = (_c = (_b = (_a = parsed.candidates) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.content) === null || _c === void 0 ? void 0 : _c.parts) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.text) || null;
+    }
+    catch (_f) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Parser registry mapping format names to parser functions
+ */
+const SSE_PARSERS = {
+    'openai': parseOpenAI,
+    'anthropic': parseAnthropic,
+    'google-gemini': parseGemini,
+};
+/**
+ * Parse an SSE line using the specified format parser
+ *
+ * @param line - Raw SSE line from stream
+ * @param format - AI provider format or custom parser function
+ * @returns Extracted token or null
+ *
+ * @example
+ * // Using predefined format
+ * parseSSELine('data: {...}', 'openai')
+ *
+ * // Using custom parser
+ * parseSSELine('data: {...}', (line) => customParser(line))
+ */
+const parseSSELine = (line, format) => {
+    var _a;
+    if (typeof format === 'function') {
+        return format(line);
+    }
+    return ((_a = SSE_PARSERS[format]) === null || _a === void 0 ? void 0 : _a.call(SSE_PARSERS, line)) || null;
+};
+
+export { SSE_PARSERS, parseAnthropic, parseGemini, parseOpenAI, parseSSELine };