@flikk/ui 1.0.0-beta.1

package/dist/hooks/useNetworkStatus.d.ts

@@ -0,0 +1,40 @@
+/**
+ * useNetworkStatus Hook
+ * Detects online/offline status and network quality
+ */
+/**
+ * Network status return type
+ */
+export interface NetworkStatusReturn {
+    /** Whether the browser is currently online */
+    isOnline: boolean;
+    /** Whether the browser was offline and just came back online */
+    wasOffline: boolean;
+    /** Network effective type (if available via Network Information API) */
+    effectiveType?: "slow-2g" | "2g" | "3g" | "4g";
+    /** Estimated downlink speed in Mbps (if available) */
+    downlink?: number;
+    /** Round-trip time estimate in ms (if available) */
+    rtt?: number;
+    /** Whether data saver mode is enabled (if available) */
+    saveData?: boolean;
+}
+/**
+ * Hook for detecting online/offline status and network quality
+ *
+ * @example
+ * const { isOnline, wasOffline, effectiveType } = useNetworkStatus();
+ *
+ * // Process queued actions when coming back online
+ * useEffect(() => {
+ *   if (wasOffline && isOnline) {
+ *     processQueuedActions();
+ *   }
+ * }, [wasOffline, isOnline]);
+ *
+ * // Show quality indicator
+ * if (effectiveType === 'slow-2g' || effectiveType === '2g') {
+ *   return <SlowNetworkWarning />;
+ * }
+ */
+export declare const useNetworkStatus: () => NetworkStatusReturn;

package/dist/hooks/useNetworkStatus.js

@@ -0,0 +1,90 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+/**
+ * useNetworkStatus Hook
+ * Detects online/offline status and network quality
+ */
+/**
+ * Get the Network Information API connection object
+ */
+const getConnection = () => {
+    if (typeof navigator === "undefined")
+        return undefined;
+    const nav = navigator;
+    return nav.connection || nav.mozConnection || nav.webkitConnection;
+};
+/**
+ * Hook for detecting online/offline status and network quality
+ *
+ * @example
+ * const { isOnline, wasOffline, effectiveType } = useNetworkStatus();
+ *
+ * // Process queued actions when coming back online
+ * useEffect(() => {
+ *   if (wasOffline && isOnline) {
+ *     processQueuedActions();
+ *   }
+ * }, [wasOffline, isOnline]);
+ *
+ * // Show quality indicator
+ * if (effectiveType === 'slow-2g' || effectiveType === '2g') {
+ *   return <SlowNetworkWarning />;
+ * }
+ */
+const useNetworkStatus = () => {
+    const [isOnline, setIsOnline] = useState(() => typeof navigator !== "undefined" ? navigator.onLine : true);
+    const [wasOffline, setWasOffline] = useState(false);
+    const [networkInfo, setNetworkInfo] = useState({});
+    const updateNetworkInfo = useCallback(() => {
+        const connection = getConnection();
+        if (connection) {
+            setNetworkInfo({
+                effectiveType: connection.effectiveType,
+                downlink: connection.downlink,
+                rtt: connection.rtt,
+                saveData: connection.saveData,
+            });
+        }
+    }, []);
+    const onlineTimerRef = useRef(undefined);
+    useEffect(() => {
+        const handleOnline = () => {
+            setIsOnline(true);
+            setWasOffline(true);
+            updateNetworkInfo();
+            // Reset wasOffline after a short delay
+            // This gives consuming code time to react to the transition
+            onlineTimerRef.current = setTimeout(() => setWasOffline(false), 1000);
+        };
+        const handleOffline = () => {
+            setIsOnline(false);
+        };
+        const handleConnectionChange = () => {
+            updateNetworkInfo();
+        };
+        // Set up online/offline listeners
+        window.addEventListener("online", handleOnline);
+        window.addEventListener("offline", handleOffline);
+        // Set up Network Information API listener
+        const connection = getConnection();
+        if (connection) {
+            connection.addEventListener("change", handleConnectionChange);
+            updateNetworkInfo(); // Get initial values
+        }
+        return () => {
+            clearTimeout(onlineTimerRef.current);
+            window.removeEventListener("online", handleOnline);
+            window.removeEventListener("offline", handleOffline);
+            if (connection) {
+                connection.removeEventListener("change", handleConnectionChange);
+            }
+        };
+    }, [updateNetworkInfo]);
+    return {
+        isOnline,
+        wasOffline,
+        ...networkInfo,
+    };
+};
+
+export { useNetworkStatus };

package/dist/hooks/useOverlay.d.ts

@@ -0,0 +1,47 @@
+export interface UseOverlayOptions {
+    /** Whether the overlay is currently open */
+    isOpen: boolean;
+    /** Callback to close the overlay */
+    onClose: () => void;
+    /** Whether pressing Escape should close the overlay (default: true) */
+    closeOnEsc?: boolean;
+    /** Whether clicking the overlay backdrop should close it (default: true) */
+    closeOnOverlayClick?: boolean;
+    /** Whether to lock body scroll when overlay is open (default: true) */
+    enableScrollLock?: boolean;
+    /** Custom handler for overlay click (called before default behavior) */
+    onOverlayClick?: (event: React.MouseEvent) => void;
+    /** Custom handler for Escape key (called before default behavior) */
+    onEscapeKey?: (event: KeyboardEvent) => void;
+}
+export interface UseOverlayReturn {
+    /** Handler for overlay backdrop click events */
+    handleOverlayClick: (event: React.MouseEvent) => void;
+    /** Handler for Escape key press */
+    handleEscKey: (event: KeyboardEvent) => void;
+}
+/**
+ * Shared hook for overlay behavior (escape key, scroll lock, click handling)
+ *
+ * Provides consistent overlay interaction patterns across Modal, Drawer,
+ * CommandPalette, and other overlay-based components.
+ *
+ * @example
+ * ```tsx
+ * const { handleOverlayClick, handleEscKey } = useOverlay({
+ *   isOpen,
+ *   onClose,
+ *   closeOnEsc: true,
+ *   closeOnOverlayClick: true,
+ * });
+ *
+ * return (
+ *   <div onClick={handleOverlayClick}>
+ *     <div onClick={(e) => e.stopPropagation()}>
+ *       Content
+ *     </div>
+ *   </div>
+ * );
+ * ```
+ */
+export declare const useOverlay: ({ isOpen, onClose, closeOnEsc, closeOnOverlayClick, enableScrollLock, onOverlayClick, onEscapeKey, }: UseOverlayOptions) => UseOverlayReturn;

package/dist/hooks/useOverlay.js

@@ -0,0 +1,71 @@
+import { useCallback, useEffect } from 'react';
+
+/**
+ * Shared hook for overlay behavior (escape key, scroll lock, click handling)
+ *
+ * Provides consistent overlay interaction patterns across Modal, Drawer,
+ * CommandPalette, and other overlay-based components.
+ *
+ * @example
+ * ```tsx
+ * const { handleOverlayClick, handleEscKey } = useOverlay({
+ *   isOpen,
+ *   onClose,
+ *   closeOnEsc: true,
+ *   closeOnOverlayClick: true,
+ * });
+ *
+ * return (
+ *   <div onClick={handleOverlayClick}>
+ *     <div onClick={(e) => e.stopPropagation()}>
+ *       Content
+ *     </div>
+ *   </div>
+ * );
+ * ```
+ */
+const useOverlay = ({ isOpen, onClose, closeOnEsc = true, closeOnOverlayClick = true, enableScrollLock = true, onOverlayClick, onEscapeKey, }) => {
+    // Handle overlay click
+    const handleOverlayClick = useCallback((event) => {
+        // Allow custom handler to run first
+        onOverlayClick === null || onOverlayClick === void 0 ? void 0 : onOverlayClick(event);
+        // Default close behavior: only close if clicking the overlay itself,
+        // not child elements (event.target === event.currentTarget)
+        if (event.target === event.currentTarget && closeOnOverlayClick) {
+            onClose();
+        }
+    }, [closeOnOverlayClick, onClose, onOverlayClick]);
+    // Handle ESC key
+    const handleEscKey = useCallback((event) => {
+        // Allow custom handler to run first
+        onEscapeKey === null || onEscapeKey === void 0 ? void 0 : onEscapeKey(event);
+        // Default close behavior
+        if (event.key === 'Escape' && closeOnEsc) {
+            onClose();
+        }
+    }, [closeOnEsc, onClose, onEscapeKey]);
+    // Setup event listeners and scroll lock
+    useEffect(() => {
+        if (isOpen) {
+            // Add Escape key listener
+            document.addEventListener('keydown', handleEscKey);
+            // Lock body scroll to prevent background scrolling
+            if (enableScrollLock) {
+                document.body.style.overflow = 'hidden';
+            }
+            // Cleanup on unmount or when overlay closes
+            return () => {
+                document.removeEventListener('keydown', handleEscKey);
+                if (enableScrollLock) {
+                    document.body.style.overflow = 'unset';
+                }
+            };
+        }
+    }, [isOpen, handleEscKey, enableScrollLock]);
+    return {
+        handleOverlayClick,
+        handleEscKey,
+    };
+};
+
+export { useOverlay };

package/dist/hooks/useScaleBackground.d.ts

@@ -0,0 +1,34 @@
+export interface UseScaleBackgroundOptions {
+    /** Whether the overlay is open */
+    isOpen: boolean;
+    /**
+     * Scale factor for the background wrapper (0–1).
+     * `1` = no scaling, `0.94` = iOS-style default.
+     * @default 0.94
+     */
+    scale?: number;
+    /**
+     * Border-radius (in px) for the scaled wrapper.
+     * @default 12
+     */
+    borderRadius?: number;
+    /**
+     * The position of the drawer/overlay to determine the push direction.
+     * @default "bottom"
+     */
+    position?: "left" | "right" | "top" | "bottom";
+}
+/**
+ * useScaleBackground
+ *
+ * Applies an iOS-style scale-down + rounded-corners effect to a wrapper
+ * element marked with `data-flik-drawer-wrapper` when an overlay opens.
+ *
+ * Uses Framer Motion's `animate()` to tween a progress value (0→1) and
+ * applies interpolated styles via `onUpdate` for perfect synchronisation.
+ *
+ * Usage:
+ * 1. Wrap your app content with `<div data-flik-drawer-wrapper>...</div>`
+ * 2. Call this hook from any overlay component (Drawer, Modal, etc.)
+ */
+export declare function useScaleBackground({ isOpen, scale, borderRadius, position, }: UseScaleBackgroundOptions): void;

package/dist/hooks/useScaleBackground.js

@@ -0,0 +1,168 @@
+import { useRef, useLayoutEffect, useEffect } from 'react';
+import { animate } from 'motion/react';
+
+const WRAPPER_SELECTOR = "[data-flik-drawer-wrapper]";
+/**
+ * useScaleBackground
+ *
+ * Applies an iOS-style scale-down + rounded-corners effect to a wrapper
+ * element marked with `data-flik-drawer-wrapper` when an overlay opens.
+ *
+ * Uses Framer Motion's `animate()` to tween a progress value (0→1) and
+ * applies interpolated styles via `onUpdate` for perfect synchronisation.
+ *
+ * Usage:
+ * 1. Wrap your app content with `<div data-flik-drawer-wrapper>...</div>`
+ * 2. Call this hook from any overlay component (Drawer, Modal, etc.)
+ */
+function useScaleBackground({ isOpen, scale = 0.94, borderRadius = 24, position = "bottom", }) {
+    const originalBodyBg = useRef("");
+    const originalHtmlBg = useRef("");
+    const wrapperRef = useRef(null);
+    const controlsRef = useRef(null);
+    // Track current animation progress so rapid toggling picks up where it left off
+    const progressRef = useRef(0);
+    useLayoutEffect(() => {
+        // Skip if no scaling needed
+        if (scale >= 1)
+            return;
+        // Respect prefers-reduced-motion
+        if (typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+            return;
+        }
+        const wrapper = document.querySelector(WRAPPER_SELECTOR);
+        if (!wrapper) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn("[Drawer] No element found with `data-flik-drawer-wrapper` attribute. " +
+                    "The scale background effect requires a wrapper element. " +
+                    "Wrap your app content: <div data-flik-drawer-wrapper>...</div>");
+            }
+            return;
+        }
+        wrapperRef.current = wrapper;
+        // Cancel any in-flight animation before starting a new one
+        if (controlsRef.current) {
+            controlsRef.current.stop();
+            controlsRef.current = null;
+        }
+        // Calculate translate offset based on drawer position
+        const TRANSLATE_AMT = 14;
+        let targetX = 0;
+        let targetY = 0;
+        switch (position) {
+            case "bottom":
+                targetY = -TRANSLATE_AMT;
+                break;
+            case "top":
+                targetY = TRANSLATE_AMT;
+                break;
+            case "left":
+                targetX = TRANSLATE_AMT;
+                break;
+            case "right":
+                targetX = -TRANSLATE_AMT;
+                break;
+        }
+        // Helper to apply styles at a given progress value (0 = closed, 1 = open)
+        const applyStyles = (t) => {
+            const s = 1 + (scale - 1) * t;
+            const r = borderRadius * t;
+            const tx = targetX * t;
+            const ty = targetY * t;
+            wrapper.style.transform = `scale(${s}) translate3d(${tx}px, ${ty}px, 0)`;
+            wrapper.style.borderRadius = `${r}px`;
+        };
+        if (isOpen) {
+            // Store original backgrounds once
+            originalBodyBg.current = document.body.style.background || "";
+            originalHtmlBg.current = document.documentElement.style.background || "";
+            // Read the theme-aware backdrop color from CSS variable
+            const scaleBg = getComputedStyle(document.documentElement)
+                .getPropertyValue("--color-scale-background")
+                .trim() || "black";
+            // Force backdrop colour
+            document.body.style.setProperty("background", scaleBg, "important");
+            document.documentElement.style.setProperty("background", scaleBg, "important");
+            // Anchor transform origin to viewport center relative to wrapper
+            const vh = window.innerHeight;
+            const rect = wrapper.getBoundingClientRect();
+            const originY = vh / 2 - rect.top;
+            wrapper.style.transformOrigin = `center ${originY}px`;
+            wrapper.style.overflow = "hidden";
+            wrapper.style.willChange = "transform, border-radius";
+            // Animate progress: current → 1
+            const startFrom = progressRef.current;
+            controlsRef.current = animate(startFrom, 1, {
+                duration: 0.4 * Math.abs(1 - startFrom),
+                ease: [0.42, 0, 0.58, 1],
+                onUpdate: (t) => {
+                    progressRef.current = t;
+                    applyStyles(t);
+                },
+            });
+        }
+        else {
+            // Animate progress: current → 0
+            const startFrom = progressRef.current;
+            controlsRef.current = animate(startFrom, 0, {
+                duration: 0.38 * startFrom,
+                ease: [0.42, 0, 0.58, 1],
+                onUpdate: (t) => {
+                    progressRef.current = t;
+                    applyStyles(t);
+                },
+                onComplete: () => {
+                    // Restore original backgrounds
+                    if (originalBodyBg.current) {
+                        document.body.style.background = originalBodyBg.current;
+                    }
+                    else {
+                        document.body.style.removeProperty("background");
+                    }
+                    if (originalHtmlBg.current) {
+                        document.documentElement.style.background = originalHtmlBg.current;
+                    }
+                    else {
+                        document.documentElement.style.removeProperty("background");
+                    }
+                    // Clean up all inline animation styles
+                    wrapper.style.transform = "";
+                    wrapper.style.transformOrigin = "";
+                    wrapper.style.borderRadius = "";
+                    wrapper.style.overflow = "";
+                    wrapper.style.willChange = "";
+                },
+            });
+        }
+    }, [isOpen, scale, borderRadius, position]);
+    // Full cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (controlsRef.current) {
+                controlsRef.current.stop();
+            }
+            const wrapper = wrapperRef.current;
+            if (wrapper) {
+                wrapper.style.transform = "";
+                wrapper.style.transformOrigin = "";
+                wrapper.style.borderRadius = "";
+                wrapper.style.overflow = "";
+                wrapper.style.willChange = "";
+            }
+            if (originalBodyBg.current) {
+                document.body.style.background = originalBodyBg.current;
+            }
+            else {
+                document.body.style.removeProperty("background");
+            }
+            if (originalHtmlBg.current) {
+                document.documentElement.style.background = originalHtmlBg.current;
+            }
+            else {
+                document.documentElement.style.removeProperty("background");
+            }
+        };
+    }, []);
+}
+
+export { useScaleBackground };

package/dist/hooks/useSelectPortal.d.ts

@@ -0,0 +1,28 @@
+export type SelectPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
+export interface UseSimpleDropdownOptions {
+    triggerRef: React.RefObject<HTMLElement | null>;
+    isOpen: boolean;
+    placement?: SelectPlacement;
+    offset?: number;
+    estimatedWidth?: number;
+    autoWidth?: boolean;
+}
+export interface SimpleDropdownReturn {
+    position: {
+        top: number;
+        left: number;
+        width: number;
+    };
+    cssVariables: React.CSSProperties;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    actualPlacement: SelectPlacement;
+    isFlipped: boolean;
+    isReady: boolean;
+}
+/**
+ * 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
+ */
+export declare const useSimpleDropdown: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;
+export declare const useSelectPortal: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;