tekivex-ui 2.3.0 → 2.5.2

package/src/components/TkxForm.tsx

@@ -43,6 +43,12 @@ export interface TkxFormProps {
   children: ReactNode;
   className?: string;
   style?: CSSProperties;
+  /**
+   * An external FormInstance created via useTkxForm().
+   * When provided, the form exposes its internal instance through this reference,
+   * enabling programmatic control from outside the component tree.
+   */
+  form?: FormInstance;
 }
 
 // ── Form Field Props ────────────────────────────────────────────────────────
@@ -185,24 +191,63 @@ function hasRequiredRule(rules: ValidationRule[]): boolean {
 // ── useTkxForm Hook ─────────────────────────────────────────────────────────
 
 /**
- * Create a FormInstance for programmatic access to form state.
- * Can be used standalone or connected to a <TkxForm> via context.
+ * Returns a FormInstance for programmatic access to form state.
+ *
+ * - Inside a <TkxForm>: returns the form's live instance (reads/writes real field state).
+ * - Outside a <TkxForm>: returns a standalone instance backed by a ref store.
+ *   Pass it to <TkxForm form={instance}> to connect it to a form.
+ *
+ * @example — programmatic access inside a form
+ * ```tsx
+ * function MyInnerButtons() {
+ *   const form = useTkxForm(); // connected to parent TkxForm
+ *   return <button onClick={() => form.resetFields()}>Reset</button>;
+ * }
+ * ```
+ *
+ * @example — external instance (Ant Design pattern)
+ * ```tsx
+ * function Parent() {
+ *   const form = useTkxForm();
+ *   return (
+ *     <TkxForm form={form}>
+ *       <TkxFormField name="email" label="Email"><TkxInput label="Email" /></TkxFormField>
+ *       <button onClick={() => console.log(form.getFieldsValue())}>Log</button>
+ *     </TkxForm>
+ *   );
+ * }
+ * ```
  */
 export function useTkxForm(): FormInstance {
   const ctx = useContext(FormContext);
 
-  // If used inside a TkxForm, return its instance directly
-  if (ctx) {
-    return ctx.instance;
-  }
+  // Always call hooks unconditionally (Rules of Hooks).
+  // These refs back the standalone instance when used outside a TkxForm.
+  const valuesRef = useRef<Record<string, any>>({});
+  const errorsRef = useRef<Record<string, string | null>>({});
+  const touchedRef = useRef<Record<string, boolean>>({});
 
-  // Standalone usage — maintain internal ref so the same object is returned
-  // across renders. Note: without a TkxForm provider, the standalone instance
-  // is inert (no UI binding), but callers can still use it as a value store.
-  throw new Error(
-    'useTkxForm() must be called inside a <TkxForm> provider. ' +
-    'Wrap your component tree with <TkxForm> first.',
-  );
+  const standaloneInstance = useMemo<FormInstance>(() => ({
+    getFieldValue: (name: string) => valuesRef.current[name],
+    setFieldValue: (name: string, value: any) => { valuesRef.current[name] = value; },
+    getFieldsValue: () => ({ ...valuesRef.current }),
+    setFieldsValue: (values: Record<string, any>) => {
+      Object.assign(valuesRef.current, values);
+    },
+    validateFields: () => Promise.resolve({ ...valuesRef.current }),
+    validateField: (_name: string) => Promise.resolve(true),
+    resetFields: () => {
+      valuesRef.current = {};
+      errorsRef.current = {};
+      touchedRef.current = {};
+    },
+    getFieldError: (name: string) => errorsRef.current[name] ?? null,
+    isFieldTouched: (name: string) => touchedRef.current[name] ?? false,
+  }), []);
+
+  // If inside a TkxForm context, return the live connected instance.
+  // Otherwise return the standalone ref-backed instance.
+  return ctx ? ctx.instance : standaloneInstance;
 }
 
 // ── TkxForm Component ───────────────────────────────────────────────────────
@@ -216,6 +261,7 @@ export function TkxForm({
   children,
   className,
   style,
+  form: externalInstance,
 }: TkxFormProps) {
   const theme = useTheme();
 
@@ -362,6 +408,10 @@ export function TkxForm({
     : tkx('flex flex-col gap-5');
 
   // ─── Context Value ─────────────────────────────────────────────────────
+  // When an external form instance is provided via the `form` prop, expose it
+  // through the context so that useTkxForm() inside children returns it.
+  const activeInstance = externalInstance ?? instance;
+
   const contextValue = useMemo<FormContextValue>(() => ({
     state,
     initialValues: initialValuesRef.current,
@@ -374,13 +424,15 @@ export function TkxForm({
     registerField,
     unregisterField,
     validateField,
-    instance,
-  }), [state, layout, disabled, setFieldValue, setFieldError, setFieldTouched, registerField, unregisterField, validateField, instance]);
+    instance: activeInstance,
+  }), [state, layout, disabled, setFieldValue, setFieldError, setFieldTouched, registerField, unregisterField, validateField, activeInstance]);
 
   return (
     <FormContext.Provider value={contextValue}>
       <form
         noValidate
+        role="form"
+        aria-label="Form"
         onSubmit={handleSubmit}
         className={cx(layoutClass, className)}
         style={{

package/src/components/TkxImage.tsx

@@ -70,7 +70,7 @@ export function TkxImage({
   ratio = 'auto',
   radius = 'none',
   caption,
-  lazy = false,
+  lazy = true,
   preview = false,
   className,
   style,

package/src/components/TkxTypography.tsx

@@ -206,12 +206,14 @@ export function TkxText({
     );
   }
 
+  // Use semantic HTML elements when appropriate
+  const tag = strong ? 'strong' : italic ? 'em' : 'span';
+
   return createElement(
-    'span',
+    tag,
     {
       style: {
         color,
-        fontWeight: strong ? 600 : 'inherit',
         fontStyle: italic ? 'italic' : 'normal',
         textDecoration: decorations.length > 0 ? decorations.join(' ') : 'none',
         ...style,

package/src/engine/tkx.ts

@@ -709,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) {
@@ -722,13 +724,64 @@ 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 ─────────────────────────────────────────────────────────
@@ -866,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) ────────────────────

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