@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/hooks/index.d.ts

@@ -10,6 +10,10 @@ export type { NetworkStatusReturn } from "./useNetworkStatus";
 export * from "./useFormStateMachine";
 export { useFocusTrap } from "./useFocusTrap";
 export { useIsClient } from "./useIsClient";
+export { useElapsedTime } from "./useElapsedTime";
+export type { UseElapsedTimeOptions } from "./useElapsedTime";
 export { useClickOutside } from "./useClickOutside";
 export { useScaleBackground } from "./useScaleBackground";
 export type { UseScaleBackgroundOptions } from "./useScaleBackground";
+export { useMediaQuery } from "./useMediaQuery";
+export { useDarkMode } from './useDarkMode';

package/dist/hooks/useClickOutside.d.ts

@@ -1,7 +1,13 @@
 import { RefObject } from 'react';
 /**
- * Custom hook that handles clicks outside of the specified element
- * @param ref The reference to the element to detect clicks outside of
- * @param handler The callback function to execute when a click outside is detected
+ * Overload 1 — legacy API: useClickOutside(ref, handler)
+ * Preserves backward compatibility with existing callers.
  */
-export declare const useClickOutside: <T extends HTMLElement | null>(ref: RefObject<T>, handler: (event: MouseEvent | TouchEvent) => void) => void;
+export declare function useClickOutside<T extends HTMLElement | null>(ref: RefObject<T>, handler: (event: MouseEvent | TouchEvent) => void): void;
+/**
+ * Overload 2 — new API: useClickOutside(callback, isActive?, additionalRefs?)
+ * Returns a ref to attach to the primary element.
+ * Accepts an optional array of additional refs whose contents count as "inside"
+ * (useful for trigger+content patterns).
+ */
+export declare function useClickOutside(callback: () => void, isActive?: boolean, additionalRefs?: RefObject<HTMLElement | null>[]): RefObject<HTMLElement | null>;

package/dist/hooks/useClickOutside.js

@@ -1,28 +1,49 @@
-import { useRef, useEffect } from 'react';
+"use client";
+import { useRef, useCallback, useEffect } from 'react';
 
-/**
- * Custom hook that handles clicks outside of the specified element
- * @param ref The reference to the element to detect clicks outside of
- * @param handler The callback function to execute when a click outside is detected
- */
-const useClickOutside = (ref, handler) => {
-    const handlerRef = useRef(handler);
-    handlerRef.current = handler;
-    useEffect(() => {
-        const listener = (event) => {
-            const el = ref.current;
-            if (!el || el.contains(event.target)) {
+// Implementation
+function useClickOutside(refOrCallback, handlerOrIsActive, additionalRefs) {
+    const internalRef = useRef(null);
+    const legacyHandlerRef = useRef(null);
+    // Keep legacy handler ref current
+    if (typeof refOrCallback !== 'function' && typeof handlerOrIsActive === 'function') {
+        legacyHandlerRef.current = handlerOrIsActive;
+    }
+    const isLegacy = typeof refOrCallback !== 'function';
+    const isActive = isLegacy
+        ? true
+        : typeof handlerOrIsActive === 'boolean'
+            ? handlerOrIsActive
+            : true;
+    const handleClickOutside = useCallback((event) => {
+        var _a;
+        const target = event.target;
+        if (isLegacy) {
+            const legacyRef = refOrCallback;
+            const el = legacyRef.current;
+            if (!el || el.contains(target))
+                return;
+            (_a = legacyHandlerRef.current) === null || _a === void 0 ? void 0 : _a.call(legacyHandlerRef, event);
+        }
+        else {
+            if (internalRef.current && internalRef.current.contains(target))
                 return;
-            }
-            handlerRef.current(event);
-        };
-        document.addEventListener('mousedown', listener);
-        document.addEventListener('touchstart', listener);
-        return () => {
-            document.removeEventListener('mousedown', listener);
-            document.removeEventListener('touchstart', listener);
-        };
-    }, [ref]);
-};
+            if (additionalRefs === null || additionalRefs === void 0 ? void 0 : additionalRefs.some(r => { var _a; return (_a = r.current) === null || _a === void 0 ? void 0 : _a.contains(target); }))
+                return;
+            refOrCallback();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isLegacy, additionalRefs]);
+    useEffect(() => {
+        if (!isActive)
+            return;
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => document.removeEventListener('mousedown', handleClickOutside);
+    }, [handleClickOutside, isActive]);
+    if (isLegacy) {
+        return;
+    }
+    return internalRef;
+}
 
 export { useClickOutside };

package/dist/hooks/useDarkMode.d.ts

@@ -0,0 +1 @@
+export declare function useDarkMode(): boolean;

package/dist/hooks/useDarkMode.js

@@ -0,0 +1,43 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+const _subscribers = new Set();
+let _observer = null;
+function _getIsDark() {
+    if (typeof document === 'undefined')
+        return false;
+    return (document.documentElement.classList.contains('dark') ||
+        document.body.classList.contains('dark') ||
+        document.querySelector('.dark') !== null);
+}
+function _ensureObserver() {
+    if (_observer || typeof document === 'undefined')
+        return;
+    _getIsDark();
+    _observer = new MutationObserver(() => {
+        _getIsDark();
+        _subscribers.forEach((fn) => fn());
+    });
+    _observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['class'],
+    });
+    _observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ['class'],
+    });
+}
+function useDarkMode() {
+    const [, rerender] = useState(0);
+    useEffect(() => {
+        _ensureObserver();
+        const notify = () => rerender((n) => n + 1);
+        _subscribers.add(notify);
+        return () => {
+            _subscribers.delete(notify);
+        };
+    }, []);
+    return typeof document === 'undefined' ? false : _getIsDark();
+}
+
+export { useDarkMode };

package/dist/hooks/useElapsedTime.d.ts

@@ -0,0 +1,28 @@
+export interface UseElapsedTimeOptions {
+    /**
+     * While `true` the value ticks. Flipping to `false` takes one final reading
+     * and then freezes, so a settled duration is exact rather than up to one
+     * interval stale.
+     * @default true
+     */
+    active?: boolean;
+    /**
+     * Tick interval in milliseconds. The default resolves tenths of a second,
+     * which is what sub-minute durations render.
+     * @default 100
+     */
+    intervalMs?: number;
+}
+/**
+ * Elapsed seconds since `startedAt` (epoch milliseconds).
+ *
+ * Returns `undefined` when `startedAt` is omitted, and on the server — the
+ * clock is only read inside an effect, so there is nothing non-deterministic
+ * to hydrate and no `window`/`Date.now()` in the render body.
+ *
+ * @example
+ * ```tsx
+ * const elapsed = useElapsedTime(startedAt, { active: !done });
+ * ```
+ */
+export declare function useElapsedTime(startedAt?: number, { active, intervalMs }?: UseElapsedTimeOptions): number | undefined;

package/dist/hooks/useElapsedTime.js

@@ -0,0 +1,37 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+/**
+ * Elapsed seconds since `startedAt` (epoch milliseconds).
+ *
+ * Returns `undefined` when `startedAt` is omitted, and on the server — the
+ * clock is only read inside an effect, so there is nothing non-deterministic
+ * to hydrate and no `window`/`Date.now()` in the render body.
+ *
+ * @example
+ * ```tsx
+ * const elapsed = useElapsedTime(startedAt, { active: !done });
+ * ```
+ */
+function useElapsedTime(startedAt, { active = true, intervalMs = 100 } = {}) {
+    const [elapsed, setElapsed] = useState(undefined);
+    useEffect(() => {
+        if (startedAt === undefined) {
+            setElapsed(undefined);
+            return;
+        }
+        const read = () => setElapsed(Math.max(0, (Date.now() - startedAt) / 1000));
+        // Settled: take one exact final reading, then stop. Without this the frozen
+        // value would be whatever the last tick happened to catch, up to intervalMs early.
+        if (!active) {
+            read();
+            return;
+        }
+        read();
+        const id = setInterval(read, intervalMs);
+        return () => clearInterval(id);
+    }, [startedAt, active, intervalMs]);
+    return elapsed;
+}
+
+export { useElapsedTime };

package/dist/hooks/useFocusTrap.js

@@ -1,3 +1,4 @@
+"use client";
 import { useRef, useEffect } from 'react';
 
 const FOCUSABLE_SELECTOR = [

package/dist/hooks/useFormStateMachine.d.ts

@@ -1,5 +1,5 @@
 import { StateMachineConfig, StateIdentifier } from "../utils/stateMachine";
-export interface UseFormStateMachineOptions<TData = any> {
+export interface UseFormStateMachineOptions<TData = unknown> {
     /** Initial form data */
     initialData?: TData;
     /** Callback when state changes */

package/dist/hooks/useIsClient.js

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useEffect } from 'react';
 
 /**

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook to detect if a media query matches.
+ * Returns false during SSR and on first render (safe default).
+ */
+export declare const useMediaQuery: (query: string) => boolean;

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,22 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+/**
+ * Hook to detect if a media query matches.
+ * Returns false during SSR and on first render (safe default).
+ */
+const useMediaQuery = (query) => {
+    const [matches, setMatches] = useState(false);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const mql = window.matchMedia(query);
+        setMatches(mql.matches);
+        const handler = (e) => setMatches(e.matches);
+        mql.addEventListener("change", handler);
+        return () => mql.removeEventListener("change", handler);
+    }, [query]);
+    return matches;
+};
+
+export { useMediaQuery };

package/dist/hooks/useNetworkStatus.d.ts

@@ -1,7 +1,3 @@
-/**
- * useNetworkStatus Hook
- * Detects online/offline status and network quality
- */
 /**
  * Network status return type
  */

package/dist/hooks/useNetworkStatus.js

@@ -1,9 +1,6 @@
+"use client";
 import { useState, useCallback, useRef, useEffect } from 'react';
 
-/**
- * useNetworkStatus Hook
- * Detects online/offline status and network quality
- */
 /**
  * Get the Network Information API connection object
  */
@@ -32,7 +29,7 @@ const getConnection = () => {
  * }
  */
 const useNetworkStatus = () => {
-    const [isOnline, setIsOnline] = useState(() => typeof navigator !== "undefined" ? navigator.onLine : true);
+    const [isOnline, setIsOnline] = useState(typeof navigator !== "undefined" ? navigator.onLine : true);
     const [wasOffline, setWasOffline] = useState(false);
     const [networkInfo, setNetworkInfo] = useState({});
     const updateNetworkInfo = useCallback(() => {

package/dist/hooks/useOverlay.d.ts

@@ -1,3 +1,5 @@
+export declare function lockScroll(): void;
+export declare function unlockScroll(): void;
 export interface UseOverlayOptions {
     /** Whether the overlay is currently open */
     isOpen: boolean;

package/dist/hooks/useOverlay.js

@@ -1,5 +1,40 @@
+"use client";
 import { useCallback, useEffect } from 'react';
 
+// ── Scroll-lock manager (ref-counted) ──────────────────────────────────
+// Supports nested overlays: only the first lock measures the scrollbar
+// and compensates; subsequent locks just bump the counter.
+let lockCount = 0;
+let savedOverflow = '';
+let savedPaddingRight = '';
+function lockScroll() {
+    if (typeof window === 'undefined')
+        return;
+    lockCount++;
+    if (lockCount === 1) {
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        // Save originals before mutating
+        savedOverflow = document.body.style.overflow;
+        savedPaddingRight = document.body.style.paddingRight;
+        // Expose width as CSS variable so fixed-position elements can compensate
+        // e.g.  position: fixed; padding-right: var(--scrollbar-width, 0px);
+        document.documentElement.style.setProperty('--scrollbar-width', `${scrollbarWidth}px`);
+        if (scrollbarWidth > 0) {
+            document.body.style.paddingRight = `${scrollbarWidth}px`;
+        }
+        document.body.style.overflow = 'hidden';
+    }
+}
+function unlockScroll() {
+    if (typeof window === 'undefined')
+        return;
+    lockCount = Math.max(0, lockCount - 1);
+    if (lockCount === 0) {
+        document.body.style.overflow = savedOverflow;
+        document.body.style.paddingRight = savedPaddingRight;
+        document.documentElement.style.removeProperty('--scrollbar-width');
+    }
+}
 /**
  * Shared hook for overlay behavior (escape key, scroll lock, click handling)
  *
@@ -49,15 +84,15 @@ const useOverlay = ({ isOpen, onClose, closeOnEsc = true, closeOnOverlayClick =
         if (isOpen) {
             // Add Escape key listener
             document.addEventListener('keydown', handleEscKey);
-            // Lock body scroll to prevent background scrolling
+            // Lock body scroll (ref-counted so nested overlays work)
             if (enableScrollLock) {
-                document.body.style.overflow = 'hidden';
+                lockScroll();
             }
             // Cleanup on unmount or when overlay closes
             return () => {
                 document.removeEventListener('keydown', handleEscKey);
                 if (enableScrollLock) {
-                    document.body.style.overflow = 'unset';
+                    unlockScroll();
                 }
             };
         }
@@ -68,4 +103,4 @@ const useOverlay = ({ isOpen, onClose, closeOnEsc = true, closeOnOverlayClick =
     };
 };
 
-export { useOverlay };
+export { lockScroll, unlockScroll, useOverlay };

package/dist/hooks/useScaleBackground.js

@@ -1,6 +1,8 @@
-import { useRef, useLayoutEffect, useEffect } from 'react';
+"use client";
+import { useRef, useEffect, useLayoutEffect } from 'react';
 import { animate } from 'motion/react';
 
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 const WRAPPER_SELECTOR = "[data-flik-drawer-wrapper]";
 /**
  * useScaleBackground
@@ -22,7 +24,9 @@ function useScaleBackground({ isOpen, scale = 0.94, borderRadius = 24, position
     const controlsRef = useRef(null);
     // Track current animation progress so rapid toggling picks up where it left off
     const progressRef = useRef(0);
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
+        if (typeof window === 'undefined')
+            return;
         // Skip if no scaling needed
         if (scale >= 1)
             return;

package/dist/hooks/useSelectPortal.d.ts

@@ -6,6 +6,24 @@ export interface UseSimpleDropdownOptions {
     offset?: number;
     estimatedWidth?: number;
     autoWidth?: boolean;
+    onClose?: () => void;
+    stickyTracking?: boolean;
+    /**
+     * Clamp the dropdown horizontally so it never overflows the viewport edges.
+     * Runs even when `stickyTracking` is on, because horizontal position is
+     * independent of vertical scroll and so cannot fight the scroll-follow
+     * behavior. Vertical clamping remains gated on `!stickyTracking`.
+     * @default true
+     */
+    clampToViewport?: boolean;
+    /**
+     * Opt-in escape hatch for triggers that move on their own (e.g. a dragged
+     * slider thumb) without a scroll/resize/content-resize event to key off of.
+     * Position recalculates whenever this value changes (reference/value
+     * inequality), in addition to the normal open/scroll/resize triggers.
+     * Unused by default, so existing consumers are unaffected.
+     */
+    recalcTrigger?: unknown;
 }
 export interface SimpleDropdownReturn {
     position: {
@@ -24,5 +42,5 @@ export interface SimpleDropdownReturn {
  * 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;
+export declare const useSimpleDropdown: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, onClose, stickyTracking, clampToViewport, recalcTrigger, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;
+export declare const useSelectPortal: ({ triggerRef, isOpen, placement, offset, estimatedWidth, autoWidth, onClose, stickyTracking, clampToViewport, recalcTrigger, }: UseSimpleDropdownOptions) => SimpleDropdownReturn;