tekivex-ui 2.5.15 → 2.6.0

package/src/headless/useInfiniteQuery.ts

@@ -1,155 +0,0 @@
-'use client';
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-export interface InfiniteQueryOptions<T, C = unknown> {
-  queryFn: (cursor: C | null, pageIndex: number) => Promise<{ data: T[]; nextCursor: C | null; hasMore: boolean }>;
-  initialCursor?: C | null;
-  pageSize?: number;
-  enabled?: boolean;
-  dedupKey?: string;
-}
-
-export interface InfiniteQueryState<T, C = unknown> {
-  data: T[];
-  pages: T[][];
-  status: 'idle' | 'loading' | 'success' | 'error' | 'fetching-more';
-  error: Error | null;
-  hasMore: boolean;
-  isFetchingMore: boolean;
-  fetchMore: () => void;
-  reset: () => void;
-  pageIndex: number;
-  totalLoaded: number;
-}
-
-/**
- * Headless infinite-scroll / pagination hook with cursor-based querying,
- * dedup protection, and safe unmount cleanup.
- *
- * @example
- * const query = useInfiniteQuery({
- *   queryFn: async (cursor) => fetchPosts({ cursor }),
- * });
- * // In your component: query.data, query.fetchMore(), query.hasMore
- */
-export function useInfiniteQuery<T, C = unknown>(
-  options: InfiniteQueryOptions<T, C>,
-): InfiniteQueryState<T, C> {
-  const {
-    queryFn,
-    initialCursor = null,
-    enabled = true,
-    dedupKey,
-  } = options;
-
-  const [pages, setPages] = useState<T[][]>([]);
-  const [status, setStatus] = useState<InfiniteQueryState<T, C>['status']>('idle');
-  const [error, setError] = useState<Error | null>(null);
-  const [hasMore, setHasMore] = useState(false);
-  const [pageIndex, setPageIndex] = useState(0);
-
-  const cursorRef = useRef<C | null>(initialCursor ?? null);
-  const isFetchingRef = useRef(false);
-  const mountedRef = useRef(true);
-  const lastDedupKeyRef = useRef<string | undefined>(undefined);
-
-  const queryFnRef = useRef(queryFn);
-  queryFnRef.current = queryFn;
-
-  const loadPage = useCallback(
-    async (cursor: C | null, index: number, isFirstPage: boolean) => {
-      if (isFetchingRef.current) return;
-
-      // Dedup: skip if same key as last completed fetch
-      if (dedupKey !== undefined && dedupKey === lastDedupKeyRef.current) return;
-
-      isFetchingRef.current = true;
-      let aborted = false;
-
-      if (mountedRef.current) {
-        setStatus(isFirstPage ? 'loading' : 'fetching-more');
-        setError(null);
-      }
-
-      try {
-        const result = await queryFnRef.current(cursor, index);
-
-        if (aborted || !mountedRef.current) return;
-
-        if (dedupKey !== undefined) {
-          lastDedupKeyRef.current = dedupKey;
-        }
-
-        cursorRef.current = result.nextCursor;
-
-        setPages(prev => {
-          if (isFirstPage) return [result.data];
-          return [...prev, result.data];
-        });
-        setHasMore(result.hasMore);
-        setPageIndex(index);
-        setStatus('success');
-      } catch (err) {
-        if (aborted || !mountedRef.current) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setStatus('error');
-      } finally {
-        if (!aborted) isFetchingRef.current = false;
-      }
-
-      // Return cleanup so callers can signal abort
-      return () => { aborted = true; };
-    },
-    // dedupKey intentionally included to allow re-checking on each call
-    [dedupKey],
-  );
-
-  const fetchMore = useCallback(() => {
-    if (!hasMore || isFetchingRef.current) return;
-    void loadPage(cursorRef.current, pageIndex + 1, false);
-  }, [hasMore, pageIndex, loadPage]);
-
-  const reset = useCallback(() => {
-    isFetchingRef.current = false;
-    lastDedupKeyRef.current = undefined;
-    cursorRef.current = initialCursor ?? null;
-    setPages([]);
-    setStatus('idle');
-    setError(null);
-    setHasMore(false);
-    setPageIndex(0);
-  }, [initialCursor]);
-
-  // Initial load
-  useEffect(() => {
-    mountedRef.current = true;
-
-    if (enabled) {
-      void loadPage(initialCursor ?? null, 0, true);
-    }
-
-    return () => {
-      mountedRef.current = false;
-    };
-  // Only run on mount / when enabled changes
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled]);
-
-  const data = pages.flat();
-  const isFetchingMore = status === 'fetching-more';
-  const totalLoaded = data.length;
-
-  return {
-    data,
-    pages,
-    status,
-    error,
-    hasMore,
-    isFetchingMore,
-    fetchMore,
-    reset,
-    pageIndex,
-    totalLoaded,
-  };
-}

package/src/headless/useIntersectionObserver.ts

@@ -1,53 +0,0 @@
-'use client';
-
-import { useState, useEffect, useRef, type RefObject } from 'react';
-
-export interface UseIntersectionObserverOptions {
-  threshold?: number | number[];
-  rootMargin?: string;
-  root?: Element | null;
-  /** Unobserve after first intersection (useful for lazy-load). Default: false */
-  once?: boolean;
-}
-
-export interface UseIntersectionObserverReturn {
-  ref: RefObject<HTMLElement | null>;
-  isIntersecting: boolean;
-  entry: IntersectionObserverEntry | null;
-}
-
-/**
- * Observe when an element enters or leaves the viewport.
- * Perfect for lazy loading, infinite scroll, and scroll-triggered animations.
- *
- * @example
- * const { ref, isIntersecting } = useIntersectionObserver({ threshold: 0.1 });
- * return <div ref={ref} style={{ opacity: isIntersecting ? 1 : 0 }}>Animated content</div>;
- */
-export function useIntersectionObserver({
-  threshold = 0,
-  rootMargin = '0px',
-  root = null,
-  once = false,
-}: UseIntersectionObserverOptions = {}): UseIntersectionObserverReturn {
-  const ref = useRef<HTMLElement>(null);
-  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
-  const observerRef = useRef<IntersectionObserver | null>(null);
-
-  useEffect(() => {
-    const el = ref.current;
-    if (!el || typeof IntersectionObserver === 'undefined') return;
-
-    observerRef.current = new IntersectionObserver(
-      ([e]) => {
-        setEntry(e);
-        if (once && e.isIntersecting) observerRef.current?.unobserve(el);
-      },
-      { threshold, rootMargin, root },
-    );
-    observerRef.current.observe(el);
-    return () => observerRef.current?.disconnect();
-  }, [threshold, rootMargin, root, once]);
-
-  return { ref, isIntersecting: entry?.isIntersecting ?? false, entry };
-}

package/src/headless/useListSelection.ts

@@ -1,103 +0,0 @@
-'use client';
-
-import { useState, useCallback, useMemo } from 'react';
-
-export interface UseListSelectionOptions {
-  items: string[];
-  initialSelected?: string[];
-  /** Allow selecting multiple items. Default: true */
-  multiple?: boolean;
-}
-
-export interface UseListSelectionReturn {
-  selected: Set<string>;
-  isSelected: (id: string) => boolean;
-  toggle: (id: string) => void;
-  select: (id: string) => void;
-  deselect: (id: string) => void;
-  selectAll: () => void;
-  deselectAll: () => void;
-  toggleAll: () => void;
-  allSelected: boolean;
-  someSelected: boolean;
-  selectedCount: number;
-  selectedArray: string[];
-}
-
-/**
- * Manages selection state for lists, tables, and grids.
- * Supports single and multi-select modes.
- *
- * @example
- * const { isSelected, toggle, selectedArray } = useListSelection({ items: rows.map(r => r.id) });
- */
-export function useListSelection({
-  items,
-  initialSelected = [],
-  multiple = true,
-}: UseListSelectionOptions): UseListSelectionReturn {
-  const [selected, setSelected] = useState<Set<string>>(() => new Set(initialSelected));
-
-  const toggle = useCallback((id: string) => {
-    setSelected(prev => {
-      const next = new Set(prev);
-      if (next.has(id)) {
-        next.delete(id);
-      } else {
-        if (!multiple) next.clear();
-        next.add(id);
-      }
-      return next;
-    });
-  }, [multiple]);
-
-  const select = useCallback((id: string) => {
-    setSelected(prev => {
-      if (prev.has(id)) return prev;
-      const next = multiple ? new Set(prev) : new Set<string>();
-      next.add(id);
-      return next;
-    });
-  }, [multiple]);
-
-  const deselect = useCallback((id: string) => {
-    setSelected(prev => {
-      if (!prev.has(id)) return prev;
-      const next = new Set(prev);
-      next.delete(id);
-      return next;
-    });
-  }, []);
-
-  const selectAll = useCallback(() => {
-    if (multiple) setSelected(new Set(items));
-  }, [items, multiple]);
-
-  const deselectAll = useCallback(() => setSelected(new Set()), []);
-
-  const toggleAll = useCallback(() => {
-    setSelected(prev => {
-      const allSel = items.every(id => prev.has(id));
-      return allSel ? new Set() : new Set(items);
-    });
-  }, [items]);
-
-  const allSelected = items.length > 0 && items.every(id => selected.has(id));
-  const someSelected = items.some(id => selected.has(id));
-  const selectedArray = useMemo(() => Array.from(selected), [selected]);
-
-  return {
-    selected,
-    isSelected: useCallback((id: string) => selected.has(id), [selected]),
-    toggle,
-    select,
-    deselect,
-    selectAll,
-    deselectAll,
-    toggleAll,
-    allSelected,
-    someSelected,
-    selectedCount: selected.size,
-    selectedArray,
-  };
-}

package/src/headless/useLocalStorage.ts

@@ -1,48 +0,0 @@
-'use client';
-
-import { useState, useCallback } from 'react';
-
-/**
- * Persists state to localStorage. Falls back to in-memory on parse errors or
- * SSR (where localStorage is unavailable).
- *
- * @example
- * const [theme, setTheme] = useLocalStorage('theme', 'dark');
- */
-export function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void, () => void] {
-  const [storedValue, setStoredValue] = useState<T>(() => {
-    if (typeof window === 'undefined') return initialValue;
-    try {
-      const item = window.localStorage.getItem(key);
-      return item !== null ? (JSON.parse(item) as T) : initialValue;
-    } catch {
-      return initialValue;
-    }
-  });
-
-  const setValue = useCallback(
-    (value: T | ((prev: T) => T)) => {
-      setStoredValue(prev => {
-        const next = typeof value === 'function' ? (value as (p: T) => T)(prev) : value;
-        if (typeof window !== 'undefined') {
-          try {
-            window.localStorage.setItem(key, JSON.stringify(next));
-          } catch {
-            // Quota exceeded or private browsing — silently ignore
-          }
-        }
-        return next;
-      });
-    },
-    [key],
-  );
-
-  const removeValue = useCallback(() => {
-    setStoredValue(initialValue);
-    if (typeof window !== 'undefined') {
-      try { window.localStorage.removeItem(key); } catch { /* ignore */ }
-    }
-  }, [key, initialValue]);
-
-  return [storedValue, setValue, removeValue];
-}

package/src/headless/useMediaQuery.ts

@@ -1,39 +0,0 @@
-'use client';
-
-import { useState, useEffect } from 'react';
-
-/**
- * Reactive media query hook. Returns true while the query matches.
- *
- * @example
- * const isMobile = useMediaQuery('(max-width: 767px)');
- * const isDark = useMediaQuery('(prefers-color-scheme: dark)');
- * const isTouch = useMediaQuery('(hover: none) and (pointer: coarse)');
- */
-export function useMediaQuery(query: string): boolean {
-  const [matches, setMatches] = useState(() => {
-    if (typeof window === 'undefined') return false;
-    return window.matchMedia(query).matches;
-  });
-
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-    const mq = window.matchMedia(query);
-    setMatches(mq.matches);
-    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
-    mq.addEventListener('change', handler);
-    return () => mq.removeEventListener('change', handler);
-  }, [query]);
-
-  return matches;
-}
-
-/** Preset breakpoint hooks matching TekiVex's breakpoint scale. */
-export function useBreakpoint() {
-  const sm = useMediaQuery('(min-width: 640px)');
-  const md = useMediaQuery('(min-width: 768px)');
-  const lg = useMediaQuery('(min-width: 1024px)');
-  const xl = useMediaQuery('(min-width: 1280px)');
-  const xxl = useMediaQuery('(min-width: 1536px)');
-  return { sm, md, lg, xl, xxl, isMobile: !sm, isTablet: sm && !lg, isDesktop: lg };
-}

package/src/headless/useRovingTabIndex.ts

@@ -1,86 +0,0 @@
-'use client';
-
-import { useState, useCallback, useRef, type KeyboardEvent } from 'react';
-
-export interface UseRovingTabIndexOptions {
-  count: number;
-  initialIndex?: number;
-  orientation?: 'horizontal' | 'vertical' | 'both';
-  /** Wrap around at boundaries. Default: true */
-  loop?: boolean;
-}
-
-export interface UseRovingTabIndexReturn {
-  focusedIndex: number;
-  setFocusedIndex: (index: number) => void;
-  getItemProps: (index: number) => {
-    tabIndex: number;
-    onKeyDown: (e: KeyboardEvent) => void;
-    onFocus: () => void;
-    'data-focused': boolean;
-  };
-}
-
-/**
- * Implements the WAI-ARIA roving tabIndex pattern for composite widgets
- * (toolbars, tab lists, radio groups, menu items, etc.)
- *
- * Only one item in the group is in the tab sequence at a time.
- * Arrow keys move focus within the group.
- *
- * @example
- * const { getItemProps } = useRovingTabIndex({ count: tabs.length });
- * return tabs.map((tab, i) => (
- *   <button key={tab.id} {...getItemProps(i)}>{tab.label}</button>
- * ));
- */
-export function useRovingTabIndex({
-  count,
-  initialIndex = 0,
-  orientation = 'horizontal',
-  loop = true,
-}: UseRovingTabIndexOptions): UseRovingTabIndexReturn {
-  const [focusedIndex, setFocusedIndex] = useState(initialIndex);
-  const itemRefs = useRef<(HTMLElement | null)[]>([]);
-
-  const moveFocus = useCallback(
-    (delta: number) => {
-      setFocusedIndex(prev => {
-        let next = prev + delta;
-        if (loop) {
-          next = ((next % count) + count) % count;
-        } else {
-          next = Math.max(0, Math.min(count - 1, next));
-        }
-        // Focus the element after state update
-        requestAnimationFrame(() => {
-          itemRefs.current[next]?.focus();
-        });
-        return next;
-      });
-    },
-    [count, loop],
-  );
-
-  const getItemProps = useCallback(
-    (index: number) => ({
-      tabIndex: index === focusedIndex ? 0 : -1,
-      'data-focused': index === focusedIndex,
-      onFocus: () => setFocusedIndex(index),
-      onKeyDown: (e: KeyboardEvent) => {
-        const isHorizontal = orientation === 'horizontal' || orientation === 'both';
-        const isVertical = orientation === 'vertical' || orientation === 'both';
-
-        if (isHorizontal && e.key === 'ArrowRight') { e.preventDefault(); moveFocus(1); }
-        if (isHorizontal && e.key === 'ArrowLeft') { e.preventDefault(); moveFocus(-1); }
-        if (isVertical && e.key === 'ArrowDown') { e.preventDefault(); moveFocus(1); }
-        if (isVertical && e.key === 'ArrowUp') { e.preventDefault(); moveFocus(-1); }
-        if (e.key === 'Home') { e.preventDefault(); setFocusedIndex(0); requestAnimationFrame(() => itemRefs.current[0]?.focus()); }
-        if (e.key === 'End') { e.preventDefault(); setFocusedIndex(count - 1); requestAnimationFrame(() => itemRefs.current[count - 1]?.focus()); }
-      },
-    }),
-    [focusedIndex, moveFocus, orientation, count],
-  );
-
-  return { focusedIndex, setFocusedIndex, getItemProps };
-}

package/src/headless/useSSE.ts

@@ -1,167 +0,0 @@
-'use client';
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-export interface SSEOptions {
-  url: string;
-  events?: string[];
-  withCredentials?: boolean;
-  reconnect?: boolean;
-  reconnectDelay?: number;
-  onOpen?: () => void;
-  onError?: (error: Event) => void;
-}
-
-export interface SSEState<T = unknown> {
-  status: 'connecting' | 'connected' | 'error' | 'closed';
-  lastEvent: { type: string; data: T; id?: string } | null;
-  events: Array<{ type: string; data: T; id?: string; timestamp: number }>;
-  connect: () => void;
-  disconnect: () => void;
-  eventCount: number;
-}
-
-/**
- * Headless Server-Sent Events hook supporting multiple named event types,
- * auto-reconnect, and JSON auto-parsing.
- *
- * @example
- * const sse = useSSE({ url: '/api/stream', events: ['update', 'notification'] });
- * console.log(sse.lastEvent);
- */
-export function useSSE<T = unknown>(options: SSEOptions): SSEState<T> {
-  const {
-    url,
-    events = ['message'],
-    withCredentials = false,
-    reconnect = true,
-    reconnectDelay = 3000,
-    onOpen,
-    onError,
-  } = options;
-
-  const [status, setStatus] = useState<SSEState<T>['status']>('connecting');
-  const [lastEvent, setLastEvent] = useState<SSEState<T>['lastEvent']>(null);
-  const [eventList, setEventList] = useState<SSEState<T>['events']>([]);
-  const [eventCount, setEventCount] = useState(0);
-
-  const esRef = useRef<EventSource | null>(null);
-  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const mountedRef = useRef(true);
-  const manualCloseRef = useRef(false);
-
-  const onOpenRef = useRef(onOpen);
-  const onErrorRef = useRef(onError);
-  onOpenRef.current = onOpen;
-  onErrorRef.current = onError;
-
-  const clearReconnectTimer = useCallback(() => {
-    if (reconnectTimerRef.current) {
-      clearTimeout(reconnectTimerRef.current);
-      reconnectTimerRef.current = null;
-    }
-  }, []);
-
-  const connect = useCallback(() => {
-    if (typeof EventSource === 'undefined') {
-      if (mountedRef.current) setStatus('error');
-      return;
-    }
-
-    manualCloseRef.current = false;
-    clearReconnectTimer();
-
-    if (esRef.current) {
-      esRef.current.close();
-      esRef.current = null;
-    }
-
-    if (mountedRef.current) setStatus('connecting');
-
-    const es = new EventSource(url, { withCredentials });
-    esRef.current = es;
-
-    es.onopen = () => {
-      if (!mountedRef.current) return;
-      setStatus('connected');
-      onOpenRef.current?.();
-    };
-
-    es.onerror = (event) => {
-      if (!mountedRef.current) return;
-      setStatus('error');
-      onErrorRef.current?.(event);
-
-      if (!manualCloseRef.current && reconnect) {
-        clearReconnectTimer();
-        reconnectTimerRef.current = setTimeout(() => {
-          if (mountedRef.current) connect();
-        }, reconnectDelay);
-      }
-    };
-
-    const handleEvent = (type: string) => (raw: MessageEvent) => {
-      if (!mountedRef.current) return;
-
-      let parsed: T;
-      try {
-        parsed = JSON.parse(raw.data as string) as T;
-      } catch {
-        parsed = raw.data as unknown as T;
-      }
-
-      const entry: SSEState<T>['events'][number] = {
-        type,
-        data: parsed,
-        timestamp: Date.now(),
-        ...(raw.lastEventId ? { id: raw.lastEventId } : {}),
-      };
-
-      setLastEvent({ type: entry.type, data: entry.data, id: entry.id });
-      setEventList(prev => {
-        const next = [...prev, entry];
-        return next.length > 200 ? next.slice(next.length - 200) : next;
-      });
-      setEventCount(c => c + 1);
-    };
-
-    for (const eventType of events) {
-      es.addEventListener(eventType, handleEvent(eventType) as EventListener);
-    }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [url, withCredentials, reconnect, reconnectDelay, clearReconnectTimer]);
-
-  const disconnect = useCallback(() => {
-    manualCloseRef.current = true;
-    clearReconnectTimer();
-    if (esRef.current) {
-      esRef.current.close();
-      esRef.current = null;
-    }
-    if (mountedRef.current) setStatus('closed');
-  }, [clearReconnectTimer]);
-
-  useEffect(() => {
-    mountedRef.current = true;
-    connect();
-    return () => {
-      mountedRef.current = false;
-      manualCloseRef.current = true;
-      clearReconnectTimer();
-      if (esRef.current) {
-        esRef.current.close();
-        esRef.current = null;
-      }
-    };
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  return {
-    status,
-    lastEvent,
-    events: eventList,
-    connect,
-    disconnect,
-    eventCount,
-  };
-}

package/src/headless/useThrottle.ts

@@ -1,48 +0,0 @@
-'use client';
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-/**
- * Returns a throttled version of the value — updates at most once per interval.
- */
-export function useThrottle<T>(value: T, interval: number): T {
-  const [throttledValue, setThrottledValue] = useState(value);
-  const lastUpdated = useRef(Date.now());
-
-  useEffect(() => {
-    const now = Date.now();
-    const remaining = interval - (now - lastUpdated.current);
-    if (remaining <= 0) {
-      lastUpdated.current = now;
-      setThrottledValue(value);
-    } else {
-      const timer = setTimeout(() => {
-        lastUpdated.current = Date.now();
-        setThrottledValue(value);
-      }, remaining);
-      return () => clearTimeout(timer);
-    }
-  }, [value, interval]);
-
-  return throttledValue;
-}
-
-/**
- * Returns a throttled callback — executes at most once per interval.
- */
-export function useThrottledCallback<T extends (...args: any[]) => any>(
-  fn: T,
-  interval: number,
-): (...args: Parameters<T>) => void {
-  const fnRef = useRef(fn);
-  fnRef.current = fn;
-  const lastCalledRef = useRef(0);
-
-  return useCallback((...args: Parameters<T>) => {
-    const now = Date.now();
-    if (now - lastCalledRef.current >= interval) {
-      lastCalledRef.current = now;
-      fnRef.current(...args);
-    }
-  }, [interval]);
-}