tekivex-ui 2.2.0 → 2.5.1

package/src/engine/tkx.ts

@@ -660,6 +660,10 @@ function resolveUtility(u: string): Declarations | null {
   // ── CSS variable passthrough: [--my-var:value] ────────────────────────────
   if ((m = u.match(/^\[(--[a-zA-Z0-9-]+):(.+)]$/))) { return { [m[1]]: m[2] }; }
 
+  // ── Plugin utilities ─────────────────────────────────────────────────────
+  const pluginResult = resolvePluginUtility(u);
+  if (pluginResult) return pluginResult;
+
   return null;
 }
 
@@ -705,6 +709,8 @@ function declarationsToCSS(decls: Declarations): string {
 
 const registry = new Map<string, string>(); // hash → full CSS block
 let styleEl: HTMLStyleElement | null = null;
+// Constructable CSSStyleSheet for O(1) rule insertion (Chrome 73+, Firefox 101+, Safari 16.4+)
+let adoptedSheet: CSSStyleSheet | null = null;
 
 function getOrCreateStyleEl(): HTMLStyleElement {
   if (!styleEl || !styleEl.isConnected) {
@@ -718,15 +724,66 @@ function getOrCreateStyleEl(): HTMLStyleElement {
   return styleEl;
 }
 
+function getAdoptedSheet(): CSSStyleSheet | null {
+  if (adoptedSheet) return adoptedSheet;
+  try {
+    // Constructable Stylesheets API — supported in all evergreen browsers
+    const sheet = new CSSStyleSheet();
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+    adoptedSheet = sheet;
+    return sheet;
+  } catch {
+    return null;
+  }
+}
+
 function registerBlock(hash: string, cssBlock: string): void {
   if (registry.has(hash)) return;
   registry.set(hash, cssBlock);
-  if (typeof document !== 'undefined') {
-    const el = getOrCreateStyleEl();
-    el.textContent += cssBlock + '\n';
+  if (typeof document === 'undefined') return;
+
+  const sheet = getAdoptedSheet();
+  if (sheet) {
+    // O(1) per rule — insertRule appends without touching existing text
+    // Split multi-rule blocks (e.g. base + media query) and insert each one.
+    // We use a simple regex split on top-level `}` boundaries.
+    const rules = splitCSSRules(cssBlock);
+    for (const rule of rules) {
+      try {
+        sheet.insertRule(rule, sheet.cssRules.length);
+      } catch {
+        // Fallback for any rule the browser rejects (e.g. invalid pseudo)
+        getOrCreateStyleEl().textContent += rule + '\n';
+      }
+    }
+  } else {
+    // Fallback for environments that don't support adoptedStyleSheets
+    getOrCreateStyleEl().textContent += cssBlock + '\n';
   }
 }
 
+/**
+ * Split a CSS string into individual top-level rules.
+ * Handles nested braces (media queries, @supports, etc.).
+ */
+function splitCSSRules(css: string): string[] {
+  const rules: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < css.length; i++) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}') {
+      depth--;
+      if (depth === 0) {
+        const rule = css.slice(start, i + 1).trim();
+        if (rule) rules.push(rule);
+        start = i + 1;
+      }
+    }
+  }
+  return rules;
+}
+
 // ── Main TKX function ─────────────────────────────────────────────────────────
 
 export type TkxInput = string | false | null | undefined | TkxInput[] | Record<string, boolean>;
@@ -862,6 +919,10 @@ export function extractAtomicCSS(): string {
 export function resetAtomicCSS(): void {
   registry.clear();
   styleEl = null;
+  if (adoptedSheet && typeof document !== 'undefined') {
+    document.adoptedStyleSheets = document.adoptedStyleSheets.filter(s => s !== adoptedSheet);
+    adoptedSheet = null;
+  }
 }
 
 // ── cx — className merge helper (like clsx but integrated) ────────────────────
@@ -872,3 +933,61 @@ export function resetAtomicCSS(): void {
 export function cx(...classes: (string | false | null | undefined)[]): string {
   return classes.filter(Boolean).join(' ');
 }
+
+// ── Plugin System ────────────────────────────────────────────────────────────
+/**
+ * TKX Plugin API — extend the utility engine with custom utilities.
+ *
+ * @example
+ * ```tsx
+ * import { tkxPlugin, tkx } from '@tekivex/ui';
+ *
+ * // Register custom utilities
+ * tkxPlugin({
+ *   name: 'brand',
+ *   utilities: {
+ *     'brand-gradient': { background: 'linear-gradient(135deg, #667eea, #764ba2)' },
+ *     'brand-text': { color: '#667eea', fontWeight: '700' },
+ *     'card-shadow': { boxShadow: '0 8px 32px rgba(102, 126, 234, 0.15)' },
+ *     'glass': {
+ *       background: 'rgba(255, 255, 255, 0.05)',
+ *       backdropFilter: 'blur(12px)',
+ *       border: '1px solid rgba(255, 255, 255, 0.1)',
+ *     },
+ *   },
+ * });
+ *
+ * // Use them like any built-in utility
+ * const cls = tkx('brand-gradient p-6 rounded-xl card-shadow');
+ * ```
+ */
+
+export interface TkxPluginDef {
+  name: string;
+  utilities: Record<string, Record<string, string>>;
+}
+
+const pluginRegistry = new Map<string, Record<string, Record<string, string>>>();
+
+export function tkxPlugin(plugin: TkxPluginDef): void {
+  pluginRegistry.set(plugin.name, plugin.utilities);
+}
+
+export function tkxRemovePlugin(name: string): void {
+  pluginRegistry.delete(name);
+}
+
+export function tkxListPlugins(): string[] {
+  return Array.from(pluginRegistry.keys());
+}
+
+/**
+ * Resolve a plugin utility to CSS properties.
+ * Called internally by the TKX engine — but also exported for inspection.
+ */
+export function resolvePluginUtility(name: string): Record<string, string> | null {
+  for (const utilities of pluginRegistry.values()) {
+    if (utilities[name]) return utilities[name];
+  }
+  return null;
+}

package/src/headless/index.ts

@@ -0,0 +1,44 @@
+// ── @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';

package/src/headless/useControllable.ts

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

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

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

@@ -0,0 +1,111 @@
+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 };
+}

package/src/headless/useIntersectionObserver.ts

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

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

@@ -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 };
+}