tekivex-ui 2.5.15 → 2.6.0

package/src/engine/wcag.ts

@@ -1,276 +0,0 @@
-// ── WCAG Accessibility Engine ────────────────────────────────────────────────
-// Contrast calculation, focus management, keyboard patterns, screen reader
-
-// ── Color Contrast ───────────────────────────────────────────────────────────
-
-function hexToRgb(hex: string): [number, number, number] {
-  if (!hex || typeof hex !== 'string') return [0, 0, 0];
-  const clean = hex.replace('#', '');
-  const full = clean.length === 3
-    ? clean.split('').map((c) => c + c).join('')
-    : clean;
-  const r = parseInt(full.slice(0, 2), 16);
-  const g = parseInt(full.slice(2, 4), 16);
-  const b = parseInt(full.slice(4, 6), 16);
-  return [isNaN(r) ? 0 : r, isNaN(g) ? 0 : g, isNaN(b) ? 0 : b];
-}
-
-export function relativeLuminance(hex: string): number {
-  const [r, g, b] = hexToRgb(hex).map((c) => {
-    const s = c / 255;
-    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
-  });
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-
-export function contrastRatio(fg: string, bg: string): number {
-  const l1 = relativeLuminance(fg);
-  const l2 = relativeLuminance(bg);
-  const lighter = Math.max(l1, l2);
-  const darker = Math.min(l1, l2);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
-export function meetsAA(fg: string, bg: string, largeText = false): boolean {
-  return contrastRatio(fg, bg) >= (largeText ? 3 : 4.5);
-}
-
-export function meetsAAA(fg: string, bg: string, largeText = false): boolean {
-  return contrastRatio(fg, bg) >= (largeText ? 4.5 : 7);
-}
-
-export function getAccessibleForeground(bg: string, candidates?: string[]): string {
-  const defaults = ['#ffffff', '#000000'];
-  const pool = candidates ?? defaults;
-  return pool.reduce((best, candidate) => {
-    return contrastRatio(candidate, bg) > contrastRatio(best, bg) ? candidate : best;
-  }, pool[0]);
-}
-
-// ── LiveRegion Announcer ─────────────────────────────────────────────────────
-
-export interface Announcer {
-  announce(message: string, politeness?: 'polite' | 'assertive'): void;
-  destroy(): void;
-}
-
-export function createAnnouncer(): Announcer {
-  const politeEl = document.createElement('div');
-  const assertiveEl = document.createElement('div');
-
-  for (const el of [politeEl, assertiveEl]) {
-    el.setAttribute('aria-atomic', 'true');
-    el.style.cssText =
-      'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
-    document.body.appendChild(el);
-  }
-
-  politeEl.setAttribute('aria-live', 'polite');
-  assertiveEl.setAttribute('aria-live', 'assertive');
-
-  return {
-    announce(message, politeness = 'polite') {
-      const el = politeness === 'assertive' ? assertiveEl : politeEl;
-      el.textContent = '';
-      setTimeout(() => {
-        el.textContent = message;
-      }, 0);
-    },
-    destroy() {
-      politeEl.remove();
-      assertiveEl.remove();
-    },
-  };
-}
-
-// ── Focus Trap ───────────────────────────────────────────────────────────────
-
-const FOCUSABLE_SELECTORS = [
-  'a[href]',
-  'button:not([disabled])',
-  'input:not([disabled])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  '[tabindex]:not([tabindex="-1"])',
-  'details > summary',
-].join(', ');
-
-export interface FocusTrap {
-  activate(): void;
-  deactivate(): void;
-}
-
-export function createFocusTrap(container: HTMLElement): FocusTrap {
-  let previousFocus: Element | null = null;
-  let keyHandler: ((e: KeyboardEvent) => void) | null = null;
-
-  function getFocusable(): HTMLElement[] {
-    return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS)).filter(
-      (el) => !el.closest('[hidden]') && !el.closest('[aria-hidden="true"]'),
-    );
-  }
-
-  return {
-    activate() {
-      previousFocus = document.activeElement;
-      const focusable = getFocusable();
-      if (focusable.length > 0) focusable[0].focus();
-
-      keyHandler = (e: KeyboardEvent) => {
-        if (e.key !== 'Tab') return;
-        const focusable = getFocusable();
-        if (focusable.length === 0) return;
-
-        const first = focusable[0];
-        const last = focusable[focusable.length - 1];
-
-        if (e.shiftKey) {
-          if (document.activeElement === first) {
-            e.preventDefault();
-            last.focus();
-          }
-        } else {
-          if (document.activeElement === last) {
-            e.preventDefault();
-            first.focus();
-          }
-        }
-      };
-
-      container.addEventListener('keydown', keyHandler);
-    },
-    deactivate() {
-      if (keyHandler) container.removeEventListener('keydown', keyHandler);
-      if (previousFocus instanceof HTMLElement) previousFocus.focus();
-      previousFocus = null;
-      keyHandler = null;
-    },
-  };
-}
-
-// ── WAI-ARIA Keyboard Handlers ───────────────────────────────────────────────
-
-export function handleTabsKeyboard(
-  e: KeyboardEvent,
-  currentIndex: number,
-  tabCount: number,
-  onSelect: (index: number) => void,
-): void {
-  let next = currentIndex;
-
-  switch (e.key) {
-    case 'ArrowLeft':
-    case 'ArrowUp':
-      e.preventDefault();
-      next = currentIndex === 0 ? tabCount - 1 : currentIndex - 1;
-      break;
-    case 'ArrowRight':
-    case 'ArrowDown':
-      e.preventDefault();
-      next = currentIndex === tabCount - 1 ? 0 : currentIndex + 1;
-      break;
-    case 'Home':
-      e.preventDefault();
-      next = 0;
-      break;
-    case 'End':
-      e.preventDefault();
-      next = tabCount - 1;
-      break;
-    case 'Enter':
-    case ' ':
-      e.preventDefault();
-      onSelect(currentIndex);
-      return;
-    default:
-      return;
-  }
-
-  onSelect(next);
-}
-
-export function handleMenuKeyboard(
-  e: KeyboardEvent,
-  currentIndex: number,
-  itemCount: number,
-  onSelect: (index: number) => void,
-  onClose?: () => void,
-): void {
-  let next = currentIndex;
-
-  switch (e.key) {
-    case 'ArrowUp':
-      e.preventDefault();
-      next = currentIndex === 0 ? itemCount - 1 : currentIndex - 1;
-      break;
-    case 'ArrowDown':
-      e.preventDefault();
-      next = currentIndex === itemCount - 1 ? 0 : currentIndex + 1;
-      break;
-    case 'Home':
-      e.preventDefault();
-      next = 0;
-      break;
-    case 'End':
-      e.preventDefault();
-      next = itemCount - 1;
-      break;
-    case 'Enter':
-    case ' ':
-      e.preventDefault();
-      onSelect(currentIndex);
-      return;
-    case 'Escape':
-      e.preventDefault();
-      onClose?.();
-      return;
-    default:
-      return;
-  }
-
-  onSelect(next);
-}
-
-// ── Media Query Detection ────────────────────────────────────────────────────
-
-export function prefersReducedMotion(): boolean {
-  if (typeof window === 'undefined') return false;
-  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-}
-
-export function prefersHighContrast(): boolean {
-  if (typeof window === 'undefined') return false;
-  return window.matchMedia('(forced-colors: active)').matches;
-}
-
-export function announceToScreenReader(message: string, politeness: 'polite' | 'assertive' = 'polite'): void {
-  if (typeof document === 'undefined') return;
-  let el = document.getElementById('tkx-live-region');
-  if (!el) {
-    el = document.createElement('div');
-    el.id = 'tkx-live-region';
-    el.setAttribute('aria-live', politeness);
-    el.setAttribute('aria-atomic', 'true');
-    el.style.cssText =
-      'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
-    document.body.appendChild(el);
-  }
-  el.textContent = '';
-  setTimeout(() => {
-    if (el) el.textContent = message;
-  }, 0);
-}
-
-export const WCAGEngine = {
-  contrastRatio,
-  meetsAA,
-  meetsAAA,
-  getAccessibleForeground,
-  createAnnouncer,
-  createFocusTrap,
-  handleTabsKeyboard,
-  handleMenuKeyboard,
-  prefersReducedMotion,
-  prefersHighContrast,
-  announce: announceToScreenReader,
-};

package/src/headless/index.ts

@@ -1,52 +0,0 @@
-'use client';
-
-// ── @tekivex/ui/headless ─────────────────────────────────────────────────────
-// Behavior-only primitives, hooks, and utilities — zero styles shipped.
-// Use these to build completely custom UI on top of TekiVex's battle-tested
-// accessibility, form, and interaction logic.
-//
-// Import from '@tekivex/ui/headless' — no CSS, no theme tokens, no components.
-//
-// @example
-// import { useDisclosure, useFocusTrap, useFormState, useRovingTabIndex } from '@tekivex/ui/headless';
-// ─────────────────────────────────────────────────────────────────────────────
-
-// ── Accessibility hooks ──────────────────────────────────────────────────────
-export {
-  useReducedMotion,
-  useHighContrast,
-  useFocusTrap,
-  useAnnounce,
-  useEscapeKey,
-  useClickOutside,
-} from '../hooks';
-
-// ── Form primitives ──────────────────────────────────────────────────────────
-export { useTkxForm } from '../components/TkxForm';
-export type { FormInstance, ValidationRule } from '../components/TkxForm';
-
-// ── Engine utilities ─────────────────────────────────────────────────────────
-export { extractAtomicCSS, resetAtomicCSS, cx, tkxPlugin, tkxRemovePlugin, tkxListPlugins } from '../engine/tkx';
-export { extractCSS, resetStyles, injectStyles, cssVar } from '../engine/css';
-export { meetsAA, meetsAAA, contrastRatio } from '../engine/wcag';
-export { sanitizeString, sanitizeProps } from '../engine/security';
-
-// ── Interaction hooks ────────────────────────────────────────────────────────
-// Additional behavior primitives beyond the base hook set.
-
-export { useDisclosure } from './useDisclosure';
-export { useRovingTabIndex } from './useRovingTabIndex';
-export { useFormState } from './useFormState';
-export { useListSelection } from './useListSelection';
-export { useDebounce } from './useDebounce';
-export { useThrottle } from './useThrottle';
-export { useControllable } from './useControllable';
-export { useMediaQuery } from './useMediaQuery';
-export { useLocalStorage } from './useLocalStorage';
-export { useIntersectionObserver } from './useIntersectionObserver';
-export { useWebSocket } from './useWebSocket';
-export type { WebSocketOptions, WebSocketState } from './useWebSocket';
-export { useSSE } from './useSSE';
-export type { SSEOptions, SSEState } from './useSSE';
-export { useInfiniteQuery } from './useInfiniteQuery';
-export type { InfiniteQueryOptions, InfiniteQueryState } from './useInfiniteQuery';

package/src/headless/useControllable.ts

@@ -1,42 +0,0 @@
-'use client';
-
-import { useState, useCallback, useRef } from 'react';
-
-/**
- * Unified controlled/uncontrolled state management.
- * The component accepts both a controlled `value` + `onChange` pair
- * OR works standalone with internal state when they're not provided.
- *
- * This is the same pattern used by Radix UI, Mantine, and Ant Design internally.
- *
- * @example — in a custom Select component:
- * const [currentValue, setCurrentValue] = useControllable({
- *   value: props.value,       // may be undefined (uncontrolled)
- *   onChange: props.onChange, // may be undefined
- *   defaultValue: '',
- * });
- */
-export function useControllable<T>({
-  value,
-  onChange,
-  defaultValue,
-}: {
-  value?: T;
-  onChange?: (value: T) => void;
-  defaultValue: T;
-}): [T, (next: T) => void] {
-  const isControlled = value !== undefined;
-  const [internalValue, setInternalValue] = useState<T>(defaultValue);
-  const onChangeRef = useRef(onChange);
-  onChangeRef.current = onChange;
-
-  const setValue = useCallback(
-    (next: T) => {
-      if (!isControlled) setInternalValue(next);
-      onChangeRef.current?.(next);
-    },
-    [isControlled],
-  );
-
-  return [isControlled ? value! : internalValue, setValue];
-}

package/src/headless/useDebounce.ts

@@ -1,37 +0,0 @@
-'use client';
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-
-/**
- * Returns a debounced version of the value that only updates after the
- * specified delay has passed without changes.
- *
- * @example
- * const debouncedSearch = useDebounce(searchQuery, 300);
- * useEffect(() => { fetchResults(debouncedSearch); }, [debouncedSearch]);
- */
-export function useDebounce<T>(value: T, delay: number): T {
-  const [debouncedValue, setDebouncedValue] = useState(value);
-  useEffect(() => {
-    const timer = setTimeout(() => setDebouncedValue(value), delay);
-    return () => clearTimeout(timer);
-  }, [value, delay]);
-  return debouncedValue;
-}
-
-/**
- * Returns a debounced callback that only fires after the delay.
- */
-export function useDebouncedCallback<T extends (...args: any[]) => any>(
-  fn: T,
-  delay: number,
-): (...args: Parameters<T>) => void {
-  const fnRef = useRef(fn);
-  fnRef.current = fn;
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  return useCallback((...args: Parameters<T>) => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    timerRef.current = setTimeout(() => fnRef.current(...args), delay);
-  }, [delay]);
-}

package/src/headless/useDisclosure.ts

@@ -1,30 +0,0 @@
-'use client';
-
-import { useState, useCallback } from 'react';
-
-export interface UseDisclosureReturn {
-  isOpen: boolean;
-  open: () => void;
-  close: () => void;
-  toggle: () => void;
-}
-
-/**
- * Manages boolean open/close state for modals, drawers, popovers, dropdowns, etc.
- *
- * @example
- * const { isOpen, open, close, toggle } = useDisclosure();
- * return (
- *   <>
- *     <button onClick={open}>Open</button>
- *     {isOpen && <MyModal onClose={close} />}
- *   </>
- * );
- */
-export function useDisclosure(initialState = false): UseDisclosureReturn {
-  const [isOpen, setIsOpen] = useState(initialState);
-  const open = useCallback(() => setIsOpen(true), []);
-  const close = useCallback(() => setIsOpen(false), []);
-  const toggle = useCallback(() => setIsOpen(v => !v), []);
-  return { isOpen, open, close, toggle };
-}

package/src/headless/useFormState.ts

@@ -1,113 +0,0 @@
-'use client';
-
-import { useState, useCallback, useRef } from 'react';
-
-export type FormFieldValue = string | number | boolean | string[] | null | undefined;
-
-export interface FieldState {
-  value: FormFieldValue;
-  error: string | null;
-  touched: boolean;
-  dirty: boolean;
-}
-
-export interface UseFormStateOptions<T extends Record<string, FormFieldValue>> {
-  initialValues: T;
-  validate?: (values: T) => Partial<Record<keyof T, string>>;
-}
-
-export interface UseFormStateReturn<T extends Record<string, FormFieldValue>> {
-  values: T;
-  errors: Partial<Record<keyof T, string>>;
-  touched: Partial<Record<keyof T, boolean>>;
-  dirty: boolean;
-  isValid: boolean;
-  setValue: (name: keyof T, value: FormFieldValue) => void;
-  setValues: (values: Partial<T>) => void;
-  touchField: (name: keyof T) => void;
-  validate: () => boolean;
-  reset: () => void;
-  getFieldProps: (name: keyof T) => {
-    value: FormFieldValue;
-    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => void;
-    onBlur: () => void;
-    'aria-invalid': boolean | undefined;
-    'aria-describedby': string | undefined;
-  };
-}
-
-/**
- * Headless form state manager — no components, no context, no validation library required.
- * Works with any input elements.
- *
- * @example
- * const { values, errors, getFieldProps, validate } = useFormState({
- *   initialValues: { email: '', password: '' },
- *   validate: ({ email }) => ({
- *     email: !email.includes('@') ? 'Invalid email' : undefined,
- *   }),
- * });
- */
-export function useFormState<T extends Record<string, FormFieldValue>>({
-  initialValues,
-  validate: validateFn,
-}: UseFormStateOptions<T>): UseFormStateReturn<T> {
-  const [values, setValuesState] = useState<T>({ ...initialValues });
-  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
-  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
-  const initialRef = useRef(initialValues);
-
-  const setValue = useCallback((name: keyof T, value: FormFieldValue) => {
-    setValuesState(prev => ({ ...prev, [name]: value }));
-  }, []);
-
-  const setValues = useCallback((partial: Partial<T>) => {
-    setValuesState(prev => ({ ...prev, ...partial }));
-  }, []);
-
-  const touchField = useCallback((name: keyof T) => {
-    setTouched(prev => ({ ...prev, [name]: true }));
-  }, []);
-
-  const validate = useCallback(() => {
-    if (!validateFn) return true;
-    const newErrors = validateFn(values);
-    const filtered = Object.fromEntries(
-      Object.entries(newErrors).filter(([, v]) => v != null),
-    ) as Partial<Record<keyof T, string>>;
-    setErrors(filtered);
-    // Touch all fields so errors show
-    const allTouched = Object.fromEntries(
-      Object.keys(values).map(k => [k, true]),
-    ) as Partial<Record<keyof T, boolean>>;
-    setTouched(allTouched);
-    return Object.keys(filtered).length === 0;
-  }, [values, validateFn]);
-
-  const reset = useCallback(() => {
-    setValuesState({ ...initialRef.current });
-    setErrors({});
-    setTouched({});
-  }, []);
-
-  const dirty = Object.keys(values).some(
-    k => values[k as keyof T] !== initialRef.current[k as keyof T],
-  );
-
-  const isValid = Object.keys(errors).length === 0;
-
-  const getFieldProps = useCallback(
-    (name: keyof T) => ({
-      value: values[name],
-      onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => {
-        setValue(name, e.target.value);
-      },
-      onBlur: () => touchField(name),
-      'aria-invalid': touched[name] && !!errors[name] ? true : undefined,
-      'aria-describedby': errors[name] ? `${String(name)}-error` : undefined,
-    }),
-    [values, errors, touched, setValue, touchField],
-  );
-
-  return { values, errors, touched, dirty, isValid, setValue, setValues, touchField, validate, reset, getFieldProps };
-}