tekivex-ui 2.3.0 → 2.5.1

package/src/headless/useLocalStorage.ts

@@ -0,0 +1,46 @@
+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

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,84 @@
+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/useThrottle.ts

@@ -0,0 +1,46 @@
+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]);
+}

package/src/i18n/I18nProvider.tsx

@@ -28,7 +28,7 @@ export function I18nProvider({
 
   return (
     <I18nContext.Provider value={value}>
-      <div dir={value.direction} style={{ direction: value.direction }}>
+      <div dir={value.direction} style={{ direction: value.direction, display: 'contents' }}>
         {children}
       </div>
     </I18nContext.Provider>