@flikk/ui 1.0.0-beta.1

package/dist/hooks/useSelectPortal.js

@@ -0,0 +1,325 @@
+import { useRef, useState, useCallback, useLayoutEffect, useMemo } from 'react';
+
+// Simple debounce utility
+const debounce = (func, wait) => {
+    let timeout;
+    return () => {
+        clearTimeout(timeout);
+        timeout = setTimeout(func, wait);
+    };
+};
+/**
+ * Fixed dropdown positioning hook
+ * Uses position: fixed with pure viewport coordinates to properly follow scroll
+ * Fixes critical issues: dropdown not following scroll & multiple dropdowns not working
+ */
+const useSimpleDropdown = ({ triggerRef, isOpen, placement = "bottom-start", offset = 4, estimatedWidth, autoWidth = false, }) => {
+    const contentRef = useRef(null);
+    const [position, setPosition] = useState({ top: -9999, left: -9999, width: 0 });
+    const [cssVariables, setCssVariables] = useState({});
+    const [actualPlacement, setActualPlacement] = useState(placement);
+    const [isFlipped, setIsFlipped] = useState(false);
+    const [isReady, setIsReady] = useState(false);
+    const isInitialRenderRef = useRef(true);
+    const rafIdRef = useRef(null);
+    // Enhanced measurement system - use actual DOM measurements when available
+    const measureDropdownHeight = useCallback(() => {
+        if (contentRef.current) {
+            const rect = contentRef.current.getBoundingClientRect();
+            return rect.height || estimateDropdownHeight();
+        }
+        return estimateDropdownHeight();
+    }, []);
+    // Calculate estimated height based on content structure (fallback)
+    const estimateDropdownHeight = () => {
+        const baseHeight = 16; // Container padding/border
+        const itemHeight = 44; // Approximate height per option (padding + text)
+        const maxVisibleItems = 8; // Max items before scrolling kicks in
+        // Default to reasonable number if we can\'t determine actual count
+        const estimatedItems = Math.min(8, maxVisibleItems);
+        return baseHeight + (estimatedItems * itemHeight);
+    };
+    // Measure actual dropdown width from DOM
+    const measureDropdownWidth = useCallback(() => {
+        var _a;
+        // If autoWidth is true, ONLY measure from content.
+        if (autoWidth) {
+            if (contentRef.current) {
+                return contentRef.current.getBoundingClientRect().width;
+            }
+            return 0; // Return 0 initially, the rAF pass will correct it.
+        }
+        // If estimatedWidth is provided, ALWAYS use it (prevents width flickering during animations)
+        // This ensures dropdown width stays constant and matches trigger width
+        if (estimatedWidth) {
+            return estimatedWidth;
+        }
+        // Only measure content width if estimatedWidth was NOT provided
+        if (contentRef.current) {
+            const rect = contentRef.current.getBoundingClientRect();
+            return rect.width;
+        }
+        // Final fallback to trigger width
+        return ((_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect().width) || 0;
+    }, [contentRef, triggerRef, estimatedWidth, autoWidth]);
+    // Calculate position using viewport coordinates (for position: fixed)
+    const calculatePosition = useCallback(() => {
+        if (typeof window === "undefined")
+            return;
+        if (!triggerRef.current)
+            return;
+        const rect = triggerRef.current.getBoundingClientRect();
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        const margin = 16;
+        const dropdownHeight = measureDropdownHeight();
+        const dropdownWidth = measureDropdownWidth();
+        const spaceAbove = rect.top - margin;
+        const spaceBelow = viewportHeight - rect.bottom - margin;
+        const spaceLeft = rect.left - margin;
+        const spaceRight = viewportWidth - rect.right - margin;
+        // Improved edge detection logic using actual measurements
+        const shouldFlip = (preferredPlacement) => {
+            if (preferredPlacement.startsWith("bottom")) {
+                // Only flip if space below is insufficient AND space above is sufficient
+                return spaceBelow < dropdownHeight && spaceAbove >= dropdownHeight;
+            }
+            else if (preferredPlacement.startsWith("top")) {
+                // Only flip if space above is insufficient AND space below is sufficient
+                return spaceAbove < dropdownHeight && spaceBelow >= dropdownHeight;
+            }
+            else if (preferredPlacement.startsWith("right")) {
+                // Only flip if space right is insufficient AND space left is sufficient
+                return spaceRight < dropdownWidth && spaceLeft >= dropdownWidth;
+            }
+            else if (preferredPlacement.startsWith("left")) {
+                // Only flip if space left is insufficient AND space right is sufficient
+                return spaceLeft < dropdownWidth && spaceRight >= dropdownWidth;
+            }
+            return false;
+        };
+        // Determine optimal placement direction
+        let finalPlacement = placement;
+        const needsFlip = shouldFlip(placement);
+        if (needsFlip) {
+            // Preserve alignment when flipping
+            if (placement === "bottom-start")
+                finalPlacement = "top-start";
+            else if (placement === "bottom-end")
+                finalPlacement = "top-end";
+            else if (placement === "bottom")
+                finalPlacement = "top";
+            else if (placement === "top-start")
+                finalPlacement = "bottom-start";
+            else if (placement === "top-end")
+                finalPlacement = "bottom-end";
+            else if (placement === "top")
+                finalPlacement = "bottom";
+            else if (placement === "right-start")
+                finalPlacement = "left-start";
+            else if (placement === "right-end")
+                finalPlacement = "left-end";
+            else if (placement === "right")
+                finalPlacement = "left";
+            else if (placement === "left-start")
+                finalPlacement = "right-start";
+            else if (placement === "left-end")
+                finalPlacement = "right-end";
+            else if (placement === "left")
+                finalPlacement = "right";
+        }
+        setActualPlacement(finalPlacement);
+        setIsFlipped(needsFlip);
+        // Calculate position based on final placement
+        let top = 0;
+        let left = 0;
+        // Handle positioning based on placement direction
+        if (finalPlacement.startsWith("top") || finalPlacement.startsWith("bottom")) {
+            // TOP/BOTTOM PLACEMENTS: Handle horizontal alignment
+            if (finalPlacement.includes("start")) {
+                left = rect.left;
+            }
+            else if (finalPlacement.includes("end")) {
+                left = rect.right - dropdownWidth;
+            }
+            else {
+                // Center alignment
+                left = rect.left + (rect.width / 2) - (dropdownWidth / 2);
+            }
+            // Handle vertical positioning
+            if (finalPlacement.startsWith("top")) {
+                top = rect.top - dropdownHeight - offset;
+            }
+            else {
+                top = rect.bottom + offset;
+            }
+        }
+        else if (finalPlacement.startsWith("left") || finalPlacement.startsWith("right")) {
+            // LEFT/RIGHT PLACEMENTS: Handle vertical alignment
+            if (finalPlacement.includes("start")) {
+                top = rect.top;
+            }
+            else if (finalPlacement.includes("end")) {
+                top = rect.bottom - dropdownHeight;
+            }
+            else {
+                // Center alignment
+                top = rect.top + (rect.height / 2) - (dropdownHeight / 2);
+            }
+            // Handle horizontal positioning
+            if (finalPlacement.startsWith("left")) {
+                left = rect.left - dropdownWidth - offset;
+            }
+            else {
+                left = rect.right + offset;
+            }
+        }
+        // Collision detection - handle both horizontal and vertical overflow
+        // Horizontal bounds checking
+        const rightEdge = left + dropdownWidth;
+        const overflow = rightEdge - (viewportWidth - margin);
+        if (overflow > 0) {
+            // Shift left just enough to fit
+            const shiftedLeft = left - overflow;
+            if (shiftedLeft >= margin) {
+                left = shiftedLeft;
+            }
+            else {
+                // Clamp to viewport margin
+                left = margin;
+            }
+        }
+        // Handle left edge overflow
+        if (left < margin) {
+            left = margin;
+        }
+        // Vertical bounds checking
+        const bottomEdge = top + dropdownHeight;
+        const verticalOverflow = bottomEdge - (viewportHeight - margin);
+        if (verticalOverflow > 0) {
+            // Shift up just enough to fit
+            const shiftedTop = top - verticalOverflow;
+            if (shiftedTop >= margin) {
+                top = shiftedTop;
+            }
+            else {
+                // Clamp to viewport margin
+                top = margin;
+            }
+        }
+        // Handle top edge overflow
+        if (top < margin) {
+            top = margin;
+        }
+        setPosition({ top, left, width: dropdownWidth });
+        // Calculate available space based on placement direction
+        let availableSpace = 0;
+        if (finalPlacement.startsWith("top")) {
+            availableSpace = spaceAbove - offset;
+        }
+        else if (finalPlacement.startsWith("bottom")) {
+            availableSpace = spaceBelow - offset;
+        }
+        else if (finalPlacement.startsWith("left")) {
+            availableSpace = spaceLeft - offset;
+        }
+        else if (finalPlacement.startsWith("right")) {
+            availableSpace = spaceRight - offset;
+        }
+        const resolvedAvailableSpace = Math.max(0, availableSpace);
+        const cssVars = {
+            "--select-content-available-width": `${rect.width}px`,
+        };
+        if (resolvedAvailableSpace > 0) {
+            cssVars["--select-content-available-height"] = `${resolvedAvailableSpace}px`;
+        }
+        else {
+            delete cssVars["--select-content-available-height"];
+        }
+        if (isInitialRenderRef.current) {
+            cssVars.visibility = "hidden";
+            cssVars.pointerEvents = "none";
+        }
+        setCssVariables(cssVars);
+        // Mark initial render as complete after first calculation
+    }, [measureDropdownHeight, measureDropdownWidth, offset, placement, triggerRef]);
+    // Reset initial render flag when dropdown opens
+    useLayoutEffect(() => {
+        if (!isOpen) {
+            if (rafIdRef.current !== null) {
+                cancelAnimationFrame(rafIdRef.current);
+                rafIdRef.current = null;
+            }
+            setIsReady(false);
+            return;
+        }
+        isInitialRenderRef.current = true;
+        setIsReady(false);
+        // Perform an initial measurement (hidden) immediately
+        calculatePosition();
+        // Recalculate on next animation frame to allow layout to settle
+        if (rafIdRef.current !== null) {
+            cancelAnimationFrame(rafIdRef.current);
+        }
+        rafIdRef.current = window.requestAnimationFrame(() => {
+            rafIdRef.current = null;
+            isInitialRenderRef.current = false;
+            calculatePosition();
+            setIsReady(true);
+        });
+        return () => {
+            if (rafIdRef.current !== null) {
+                cancelAnimationFrame(rafIdRef.current);
+                rafIdRef.current = null;
+            }
+        };
+    }, [isOpen, calculatePosition]);
+    // Initial position calculation
+    useLayoutEffect(() => {
+        if (!isOpen)
+            return;
+        calculatePosition();
+    }, [isOpen, calculatePosition]);
+    // Debounced position updates for better performance
+    const debouncedCalculatePosition = useMemo(() => debounce(calculatePosition, 16), // ~60fps
+    [calculatePosition]);
+    // Update position on scroll and resize - debounced for performance
+    useLayoutEffect(() => {
+        if (!isOpen)
+            return;
+        window.addEventListener("scroll", debouncedCalculatePosition, { passive: true, capture: true });
+        window.addEventListener("resize", debouncedCalculatePosition, { passive: true });
+        return () => {
+            window.removeEventListener("scroll", debouncedCalculatePosition, true);
+            window.removeEventListener("resize", debouncedCalculatePosition);
+        };
+    }, [isOpen, debouncedCalculatePosition]);
+    // Recalculate when dropdown content resizes (e.g. search filtering)
+    useLayoutEffect(() => {
+        if (!isOpen)
+            return;
+        if (!contentRef.current)
+            return;
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => {
+            calculatePosition();
+        });
+        observer.observe(contentRef.current);
+        return () => {
+            observer.disconnect();
+        };
+    }, [isOpen, calculatePosition]);
+    return {
+        position,
+        cssVariables,
+        contentRef,
+        actualPlacement,
+        isFlipped,
+        isReady,
+    };
+};
+// Export with original name for backward compatibility
+const useSelectPortal = useSimpleDropdown;
+
+export { useSelectPortal, useSimpleDropdown };

package/dist/hooks/useSlidingNumber.d.ts

@@ -0,0 +1,34 @@
+export interface UseSlidingNumberOptions {
+    /**
+     * The current number value to display
+     */
+    value: number;
+    /**
+     * Whether the animation is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Format function to customize number display
+     * @default (n) => n.toString()
+     */
+    formatNumber?: (value: number) => string;
+}
+export interface UseSlidingNumberReturn {
+    /**
+     * The current formatted value
+     */
+    displayValue: string;
+    /**
+     * The direction of the change (1 for up, -1 for down, 0 for no change)
+     */
+    direction: number;
+    /**
+     * Array of digit positions and their values for animation
+     */
+    digits: Array<{
+        value: string;
+        isChanging: boolean;
+    }>;
+}
+export declare const useSlidingNumber: ({ value, enabled, formatNumber, }: UseSlidingNumberOptions) => UseSlidingNumberReturn;

package/dist/hooks/useSlidingNumber.js

@@ -0,0 +1,67 @@
+import { useState, useRef, useEffect, useMemo } from 'react';
+
+/**
+ * Custom hook for sliding number animations
+ * Detects direction of change and provides digit-level animation data
+ *
+ * @example
+ * ```tsx
+ * const { displayValue, direction, digits } = useSlidingNumber({
+ *   value: count,
+ *   enabled: true,
+ *   formatNumber: (n) => n.toFixed(2)
+ * });
+ *
+ * return (
+ *   <div>
+ *     {digits.map((digit, i) => (
+ *       <motion.span
+ *         key={i}
+ *         animate={{ y: digit.isChanging ? [10, 0] : 0 }}
+ *       >
+ *         {digit.value}
+ *       </motion.span>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+const defaultFormatNumber = (n) => n.toString();
+const useSlidingNumber = ({ value, enabled = true, formatNumber = defaultFormatNumber, }) => {
+    const [displayValue, setDisplayValue] = useState(formatNumber(value));
+    const [direction, setDirection] = useState(0);
+    const prevValueRef = useRef(value);
+    useEffect(() => {
+        const prevValue = prevValueRef.current;
+        const newDisplayValue = formatNumber(value);
+        // Determine direction
+        if (value > prevValue) {
+            setDirection(1);
+        }
+        else if (value < prevValue) {
+            setDirection(-1);
+        }
+        else {
+            setDirection(0);
+        }
+        setDisplayValue(newDisplayValue);
+        prevValueRef.current = value;
+    }, [value, formatNumber]);
+    // Split display value into individual digits for animation
+    const digits = useMemo(() => displayValue.split('').map((char, index) => {
+        // Check if this digit changed from previous value
+        const prevDisplay = formatNumber(prevValueRef.current);
+        const isChanging = enabled && prevDisplay[index] !== char;
+        return {
+            value: char,
+            isChanging,
+        };
+    }), [displayValue, enabled, formatNumber]);
+    return {
+        displayValue,
+        direction,
+        digits,
+    };
+};
+
+export { useSlidingNumber };

package/dist/hooks/useStreamingSSE.d.ts

@@ -0,0 +1,80 @@
+/**
+ * useStreamingSSE Hook
+ * Handles Server-Sent Events (SSE) streaming for AI/LLM responses
+ * Supports OpenAI, Anthropic (Claude), and Google Gemini formats
+ */
+import { type SSEFormat, type SSEParser } from '../utils/sseFormatParsers';
+import { type StreamingError } from '../utils/streamingErrors';
+import { type RetryConfig } from '../utils/retryUtils';
+/**
+ * Options for useStreamingSSE hook
+ */
+export interface UseStreamingSSEOptions {
+    /** The SSE endpoint URL */
+    url: string;
+    /** HTTP method (default: 'POST') */
+    method?: 'GET' | 'POST';
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (for POST requests) */
+    body?: Record<string, unknown> | string;
+    /** Stream format parser (default: 'openai') */
+    format?: SSEFormat | SSEParser;
+    /** Whether to auto-start streaming on mount (default: true) */
+    autoStart?: boolean;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Called when a new token arrives */
+    onToken?: (token: string, accumulatedText: string) => void;
+    /** Called when streaming completes successfully */
+    onComplete?: (fullText: string) => void;
+    /** Called when an error occurs */
+    onError?: (error: StreamingError) => void;
+    /** Called when streaming starts */
+    onStart?: () => void;
+    /** Called when streaming is aborted */
+    onAbort?: () => void;
+}
+/**
+ * Return value from useStreamingSSE hook
+ */
+export interface UseStreamingSSEReturn {
+    /** Current accumulated text */
+    accumulatedText: string;
+    /** Whether actively streaming */
+    isStreaming: boolean;
+    /** Current error state */
+    error: StreamingError | null;
+    /** Whether streaming completed successfully */
+    isComplete: boolean;
+    /** Current retry attempt (0-indexed) */
+    retryAttempt: number;
+    /** Start streaming */
+    start: () => void;
+    /** Stop streaming (abort) */
+    stop: () => void;
+    /** Retry streaming */
+    retry: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * 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),
+ * });
+ */
+export declare const useStreamingSSE: (options: UseStreamingSSEOptions) => UseStreamingSSEReturn;