@flikk/ui 1.0.0-beta.1

package/dist/hooks/useStreamingSSE.js

@@ -0,0 +1,236 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
+import { parseSSELine } from '../utils/sseFormatParsers.js';
+import { StreamingTimeoutError, StreamingServerError, StreamingNetworkError, normalizeError } from '../utils/streamingErrors.js';
+import { shouldRetry, calculateRetryDelay } from '../utils/retryUtils.js';
+
+/**
+ * useStreamingSSE Hook
+ * Handles Server-Sent Events (SSE) streaming for AI/LLM responses
+ * Supports OpenAI, Anthropic (Claude), and Google Gemini formats
+ */
+/**
+ * Hook for handling SSE streaming from AI/LLM APIs
+ *
+ * @example
+ * const {
+ *   accumulatedText,
+ *   isStreaming,
+ *   error,
+ *   start,
+ *   stop
+ * } = useStreamingSSE({
+ *   url: '/api/chat',
+ *   format: 'openai',
+ *   onToken: (token) => console.log('New token:', token),
+ *   onComplete: (text) => console.log('Complete:', text),
+ * });
+ */
+const useStreamingSSE = (options) => {
+    const { url, method = 'POST', headers, body, format = 'openai', autoStart = true, timeout = 30000, retry, onToken, onComplete, onError, onStart, onAbort, } = options;
+    // State
+    const [accumulatedText, setAccumulatedText] = useState('');
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = useState(null);
+    const [isComplete, setIsComplete] = useState(false);
+    const [retryAttempt, setRetryAttempt] = useState(0);
+    // Refs for cleanup and buffering
+    const abortControllerRef = useRef(null);
+    const timeoutRef = useRef(null);
+    const retryTimeoutRef = useRef(undefined);
+    const bufferRef = useRef(''); // For incomplete SSE lines
+    // Store callback props in refs to keep `start` stable
+    const onTokenRef = useRef(onToken);
+    const onCompleteRef = useRef(onComplete);
+    const onErrorRef = useRef(onError);
+    const onStartRef = useRef(onStart);
+    const onAbortRef = useRef(onAbort);
+    onTokenRef.current = onToken;
+    onCompleteRef.current = onComplete;
+    onErrorRef.current = onError;
+    onStartRef.current = onStart;
+    onAbortRef.current = onAbort;
+    /**
+     * Start streaming from the SSE endpoint
+     */
+    const start = useCallback(async () => {
+        var _a, _b, _c, _d, _e, _f;
+        // Abort any existing stream
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        // Create new AbortController
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        // Set timeout if configured
+        if (timeout) {
+            timeoutRef.current = setTimeout(() => {
+                var _a;
+                controller.abort();
+                const timeoutError = new StreamingTimeoutError(timeout);
+                setError(timeoutError);
+                setIsStreaming(false);
+                (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, timeoutError);
+            }, timeout);
+        }
+        // Reset state
+        setIsStreaming(true);
+        setError(null);
+        setIsComplete(false);
+        setAccumulatedText('');
+        bufferRef.current = '';
+        (_a = onStartRef.current) === null || _a === void 0 ? void 0 : _a.call(onStartRef);
+        try {
+            // Make fetch request
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers,
+                },
+                body: body ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined,
+                signal: controller.signal,
+            });
+            // Check for HTTP errors
+            if (!response.ok) {
+                throw new StreamingServerError(response.status, response.statusText, await response.text().catch(() => undefined));
+            }
+            // Get reader from response body stream
+            const reader = (_b = response.body) === null || _b === void 0 ? void 0 : _b.getReader();
+            if (!reader) {
+                throw new StreamingNetworkError('No response body available');
+            }
+            const decoder = new TextDecoder();
+            let fullText = '';
+            // Read stream chunks
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                // Decode chunk
+                const chunk = decoder.decode(value, { stream: true });
+                bufferRef.current += chunk;
+                // Parse complete lines (SSE lines end with \n or \n\n)
+                const lines = bufferRef.current.split('\n');
+                bufferRef.current = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue; // Skip empty lines
+                    const token = parseSSELine(line, format);
+                    if (token) {
+                        fullText += token;
+                        setAccumulatedText(fullText);
+                        (_c = onTokenRef.current) === null || _c === void 0 ? void 0 : _c.call(onTokenRef, token, fullText);
+                    }
+                }
+            }
+            // Clear timeout
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+                timeoutRef.current = null;
+            }
+            // Streaming completed successfully
+            setIsStreaming(false);
+            setIsComplete(true);
+            (_d = onCompleteRef.current) === null || _d === void 0 ? void 0 : _d.call(onCompleteRef, fullText);
+        }
+        catch (err) {
+            // Ignore AbortErrors (user cancelled or component unmounted)
+            if (err instanceof Error && err.name === 'AbortError') {
+                setIsStreaming(false);
+                (_e = onAbortRef.current) === null || _e === void 0 ? void 0 : _e.call(onAbortRef);
+                return;
+            }
+            // Handle real errors
+            const streamingError = normalizeError(err);
+            setError(streamingError);
+            setIsStreaming(false);
+            (_f = onErrorRef.current) === null || _f === void 0 ? void 0 : _f.call(onErrorRef, streamingError);
+            // Auto-retry if configured and error is retryable
+            if (shouldRetry(streamingError, retryAttempt, retry)) {
+                const delay = calculateRetryDelay(retryAttempt, retry);
+                if (process.env.NODE_ENV !== 'production') {
+                    console.log(`[useStreamingSSE] Retrying in ${delay}ms (attempt ${retryAttempt + 1}/${(retry === null || retry === void 0 ? void 0 : retry.maxAttempts) || 3})`);
+                }
+                retryTimeoutRef.current = setTimeout(() => {
+                    setRetryAttempt((prev) => prev + 1);
+                    start();
+                }, delay);
+            }
+        }
+    }, [
+        url,
+        method,
+        headers,
+        body,
+        format,
+        timeout,
+        retry,
+        retryAttempt,
+    ]);
+    /**
+     * Stop streaming (abort)
+     */
+    const stop = useCallback(() => {
+        var _a;
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+        clearTimeout(retryTimeoutRef.current);
+        setIsStreaming(false);
+        (_a = onAbortRef.current) === null || _a === void 0 ? void 0 : _a.call(onAbortRef);
+    }, []);
+    /**
+     * Retry streaming
+     */
+    const retryFn = useCallback(() => {
+        setRetryAttempt(0);
+        start();
+    }, [start]);
+    /**
+     * Reset to initial state
+     */
+    const reset = useCallback(() => {
+        stop();
+        setAccumulatedText('');
+        setError(null);
+        setIsComplete(false);
+        setRetryAttempt(0);
+        bufferRef.current = '';
+    }, [stop]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (abortControllerRef.current) {
+                abortControllerRef.current.abort();
+            }
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+            clearTimeout(retryTimeoutRef.current);
+        };
+    }, []);
+    // Auto-start if enabled
+    useEffect(() => {
+        if (autoStart) {
+            start();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []); // Only run on mount
+    return {
+        accumulatedText,
+        isStreaming,
+        error,
+        isComplete,
+        retryAttempt,
+        start,
+        stop,
+        retry: retryFn,
+        reset,
+    };
+};
+
+export { useStreamingSSE };

package/dist/hooks/useTypewriter.d.ts

@@ -0,0 +1,51 @@
+export interface UseTypewriterOptions {
+    /**
+     * The full text to animate
+     */
+    text: string;
+    /**
+     * Speed in milliseconds per word
+     * @default 100
+     */
+    speed?: number;
+    /**
+     * Whether the animation is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when animation completes
+     */
+    onComplete?: () => void;
+}
+export interface UseTypewriterReturn {
+    /**
+     * The currently visible text
+     */
+    displayText: string;
+    /**
+     * Whether the animation is complete
+     */
+    isComplete: boolean;
+    /**
+     * Reset the animation
+     */
+    reset: () => void;
+}
+/**
+ * Custom hook for word-by-word typing animation
+ * Shows first sentence immediately to establish bubble width,
+ * then animates remaining text word-by-word
+ *
+ * @example
+ * ```tsx
+ * const { displayText, isComplete } = useTypewriter({
+ *   text: "Hello world. This is a typing animation",
+ *   speed: 100,
+ *   enabled: true
+ * });
+ *
+ * return <div>{displayText}</div>;
+ * ```
+ */
+export declare const useTypewriter: ({ text, speed, enabled, onComplete, }: UseTypewriterOptions) => UseTypewriterReturn;

package/dist/hooks/useTypewriter.js

@@ -0,0 +1,120 @@
+import { useState, useRef, useEffect } from 'react';
+
+/**
+ * Helper function to find the first sentence in text
+ * A sentence ends with . ! or ? followed by a space or end of string
+ */
+const findFirstSentence = (text) => {
+    const sentenceEndRegex = /[.!?]\s/;
+    const match = text.match(sentenceEndRegex);
+    if (!match || match.index === undefined) {
+        // No sentence boundary found, treat entire text as first sentence
+        return { firstSentence: text, remaining: '' };
+    }
+    const endIndex = match.index + match[0].length;
+    const firstSentence = text.substring(0, endIndex).trim();
+    const remaining = text.substring(endIndex).trim();
+    return { firstSentence, remaining };
+};
+/**
+ * Custom hook for word-by-word typing animation
+ * Shows first sentence immediately to establish bubble width,
+ * then animates remaining text word-by-word
+ *
+ * @example
+ * ```tsx
+ * const { displayText, isComplete } = useTypewriter({
+ *   text: "Hello world. This is a typing animation",
+ *   speed: 100,
+ *   enabled: true
+ * });
+ *
+ * return <div>{displayText}</div>;
+ * ```
+ */
+const useTypewriter = ({ text, speed = 100, enabled = true, onComplete, }) => {
+    const [displayText, setDisplayText] = useState('');
+    const [isComplete, setIsComplete] = useState(false);
+    const firstSentenceRef = useRef('');
+    const remainingWordsRef = useRef([]);
+    const currentIndexRef = useRef(0);
+    const timerRef = useRef(undefined);
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    // Split text into first sentence and remaining words
+    useEffect(() => {
+        var _a;
+        if (!text) {
+            firstSentenceRef.current = '';
+            remainingWordsRef.current = [];
+            setDisplayText('');
+            setIsComplete(true);
+            return;
+        }
+        const { firstSentence, remaining } = findFirstSentence(text);
+        firstSentenceRef.current = firstSentence;
+        remainingWordsRef.current = remaining ? remaining.split(' ') : [];
+        currentIndexRef.current = 0;
+        // Show first sentence immediately
+        setDisplayText(firstSentence);
+        setIsComplete(false);
+        // If animation is disabled or no remaining text, show full text immediately
+        if (!enabled || !remaining) {
+            setDisplayText(text);
+            setIsComplete(true);
+            (_a = onCompleteRef.current) === null || _a === void 0 ? void 0 : _a.call(onCompleteRef);
+        }
+    }, [text, enabled]);
+    // Animate remaining words after first sentence
+    useEffect(() => {
+        if (!enabled || isComplete || remainingWordsRef.current.length === 0) {
+            return;
+        }
+        const animateNextWord = () => {
+            var _a, _b;
+            const currentIndex = currentIndexRef.current;
+            const remainingWords = remainingWordsRef.current;
+            const firstSentence = firstSentenceRef.current;
+            if (currentIndex >= remainingWords.length) {
+                setIsComplete(true);
+                (_a = onCompleteRef.current) === null || _a === void 0 ? void 0 : _a.call(onCompleteRef);
+                return;
+            }
+            // Build display text: first sentence + animated remaining words
+            const animatedWords = remainingWords.slice(0, currentIndex + 1);
+            const newDisplayText = firstSentence + (firstSentence ? ' ' : '') + animatedWords.join(' ');
+            setDisplayText(newDisplayText);
+            currentIndexRef.current += 1;
+            // Schedule next word
+            if (currentIndex + 1 < remainingWords.length) {
+                timerRef.current = setTimeout(animateNextWord, speed);
+            }
+            else {
+                setIsComplete(true);
+                (_b = onCompleteRef.current) === null || _b === void 0 ? void 0 : _b.call(onCompleteRef);
+            }
+        };
+        // Start animation
+        timerRef.current = setTimeout(animateNextWord, speed);
+        return () => {
+            if (timerRef.current) {
+                clearTimeout(timerRef.current);
+            }
+        };
+    }, [enabled, isComplete, speed]);
+    const reset = () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+        }
+        currentIndexRef.current = 0;
+        setDisplayText('');
+        setIsComplete(false);
+    };
+    return {
+        displayText,
+        isComplete,
+        reset,
+    };
+};
+
+export { useTypewriter };

package/dist/icons/Icon.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+export interface IconProps extends React.SVGProps<SVGSVGElement> {
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
+    color?: string;
+    strokeWidth?: number;
+    className?: string;
+    /**
+     * Force dark mode styling for the icon. Use when placing the icon
+     * on a dark background while the page is in light mode. This applies the
+     * 'dark' class to the container, making the icon use light colors for visibility.
+     * @default false
+     */
+    darkMode?: boolean;
+}
+export interface IconComponent extends React.FC<IconProps> {
+    displayName?: string;
+}
+/**
+ * Icon factory function to create consistent icons
+ * @param Svg - The SVG component to render
+ * @param displayName - The display name for the component
+ * @returns A standardized Icon component
+ */
+export declare function createIcon(Svg: React.FC<IconProps>, displayName: string): IconComponent;

package/dist/icons/Icon.js

@@ -0,0 +1,30 @@
+import { jsx } from 'react/jsx-runtime';
+
+/**
+ * Icon factory function to create consistent icons
+ * @param Svg - The SVG component to render
+ * @param displayName - The display name for the component
+ * @returns A standardized Icon component
+ */
+function createIcon(Svg, displayName) {
+    const Icon = ({ size = 'md', color = 'currentColor', strokeWidth = 2, className = '', darkMode = false, ...props }) => {
+        // Map size names to pixel values
+        const sizeMap = {
+            xs: '16px',
+            sm: '20px',
+            md: '24px',
+            lg: '32px',
+            xl: '40px',
+        };
+        const pixelSize = typeof size === 'string' ? sizeMap[size] || '24px' : `${size}px`;
+        const svg = (jsx(Svg, { width: pixelSize, height: pixelSize, fill: "none", stroke: color, strokeWidth: strokeWidth, className: className, "aria-hidden": "true", style: { width: pixelSize, height: pixelSize, ...props.style }, ...props }));
+        if (darkMode) {
+            return (jsx("span", { className: "dark inline-flex", children: svg }));
+        }
+        return svg;
+    };
+    Icon.displayName = displayName;
+    return Icon;
+}
+
+export { createIcon };

package/dist/icons/Index.d.ts

@@ -0,0 +1,16 @@
+export * from './Icon';
+export * from './core/PlusIcon';
+export * from './core/MinusIcon';
+export * from './core/SearchIcon';
+export * from './core/LockIcon';
+export * from './core/DollarIcon';
+export * from './core/TickIcon';
+import React from 'react';
+interface IconProps {
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    className?: string;
+}
+export declare const CalendarIcon: React.FC<IconProps>;
+export declare const ClockIcon: React.FC<IconProps>;
+export declare const ChartBarIcon: React.FC<IconProps>;
+export declare const UserIcon: React.FC<IconProps>;

package/dist/icons/core/ChevronUpDown.d.ts

@@ -0,0 +1 @@
+export declare const ChevronUpDownIcon: import("../Icon").IconComponent;

package/dist/icons/core/ChevronUpDown.js

@@ -0,0 +1,7 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const ChevronUpDownSvg = (props) => (jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: [jsx("path", { d: "m7 15 5 5 5-5" }), jsx("path", { d: "m7 9 5-5 5 5" })] }));
+const ChevronUpDownIcon = createIcon(ChevronUpDownSvg, 'ChevronUpDownIcon');
+
+export { ChevronUpDownIcon };

package/dist/icons/core/DollarIcon.d.ts

@@ -0,0 +1 @@
+export declare const DollarIcon: import("../Icon").IconComponent;

package/dist/icons/core/DollarIcon.js

@@ -0,0 +1,5 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const DollarSvg = (props) => (jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: [jsx("line", { x1: "12", x2: "12", y1: "2", y2: "22" }), jsx("path", { d: "M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" })] }));
+createIcon(DollarSvg, 'DollarIcon');

package/dist/icons/core/LockIcon.d.ts

@@ -0,0 +1 @@
+export declare const LockIcon: import("../Icon").IconComponent;

package/dist/icons/core/LockIcon.js

@@ -0,0 +1,5 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const LockSvg = (props) => (jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: [jsx("rect", { width: "18", height: "11", x: "3", y: "11", rx: "2", ry: "2" }), jsx("path", { d: "M7 11V7a5 5 0 0 1 10 0v4" })] }));
+createIcon(LockSvg, 'LockIcon');

package/dist/icons/core/MinusIcon.d.ts

@@ -0,0 +1 @@
+export declare const MinusIcon: import("../Icon").IconComponent;

package/dist/icons/core/MinusIcon.js

@@ -0,0 +1,7 @@
+import { jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const MinusSvg = (props) => (jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: jsx("path", { d: "M5 12h14" }) }));
+const MinusIcon = createIcon(MinusSvg, 'MinusIcon');
+
+export { MinusIcon };

package/dist/icons/core/PlusIcon.d.ts

@@ -0,0 +1 @@
+export declare const PlusIcon: import("../Icon").IconComponent;

package/dist/icons/core/PlusIcon.js

@@ -0,0 +1,7 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const PlusSvg = (props) => (jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: [jsx("path", { d: "M5 12h14" }), jsx("path", { d: "M12 5v14" })] }));
+const PlusIcon = createIcon(PlusSvg, 'PlusIcon');
+
+export { PlusIcon };

package/dist/icons/core/SearchIcon.d.ts

@@ -0,0 +1 @@
+export declare const SearchIcon: import("../Icon").IconComponent;

package/dist/icons/core/SearchIcon.js

@@ -0,0 +1,7 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const SearchSvg = (props) => (jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: [jsx("circle", { cx: "11", cy: "11", r: "8" }), jsx("path", { d: "m21 21-4.3-4.3" })] }));
+const SearchIcon = createIcon(SearchSvg, 'SearchIcon');
+
+export { SearchIcon };

package/dist/icons/core/TickIcon.d.ts

@@ -0,0 +1 @@
+export declare const TickIcon: import("../Icon").IconComponent;

package/dist/icons/core/TickIcon.js

@@ -0,0 +1,5 @@
+import { jsx } from 'react/jsx-runtime';
+import { createIcon } from '../Icon.js';
+
+const TickSvg = (props) => (jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", ...props, children: jsx("path", { d: "M19 6L9 18L4.5 13.5" }) }));
+createIcon(TickSvg, 'TickIcon');

package/dist/icons/core/User.d.ts

@@ -0,0 +1 @@
+export declare const UserIcon: import("../Icon").IconComponent;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./components/core";
+export * from "./components/forms";
+export * from "./components/charts";
+export * from "./components/effects";
+export { cn } from "./utils/cn";
+export { debounce } from "./utils/debounce";
+export { useClickOutside } from "./hooks/useClickOutside";
+export { useOverlay } from "./hooks/useOverlay";
+export { useSlidingNumber } from "./hooks/useSlidingNumber";
+export { useTypewriter } from "./hooks/useTypewriter";