tekivex-ui 2.5.1 → 2.5.3

package/src/engine/tkx.ts

@@ -99,11 +99,95 @@ const BREAKPOINTS: Record<string, string> = {
   sm: '640px', md: '768px', lg: '1024px', xl: '1280px', '2xl': '1536px',
 };
 
+// ── CSS Security Guards ───────────────────────────────────────────────────────
+// Prevent CSS injection via arbitrary values. Blocks:
+//   • javascript: / vbscript: / data: URL schemes
+//   • CSS expression() (IE legacy code-exec vector)
+//   • -moz-binding / behavior (remote XBL/HTC execution)
+//   • Embedded newlines that break out of style blocks
+//
+// Quantum confidence: values that pass all guards score 1.0;
+// values containing suspicious but non-blocked patterns score < 1.0
+// and are stripped in strict mode.
+
+/** Dangerous CSS value patterns — any match → reject the declaration. */
+const DANGEROUS_VALUE_RE =
+  /javascript\s*:|vbscript\s*:|data\s*:\s*text\/html|data\s*:\s*text\/javascript|expression\s*\(|[\r\n\x00]/i;
+
+/** Dangerous CSS property names. */
+const DANGEROUS_PROPS = new Set([
+  'behavior', '-moz-binding', '-webkit-binding', 'src',
+]);
+
+/**
+ * Allowlist of CSS properties accepted via arbitrary [prop:value] shorthand.
+ * Anything not in this set is silently dropped.
+ */
+const SAFE_CSS_PROPS = new Set([
+  // Box model
+  'width','min-width','max-width','height','min-height','max-height',
+  'margin','margin-top','margin-right','margin-bottom','margin-left',
+  'padding','padding-top','padding-right','padding-bottom','padding-left',
+  // Positioning
+  'position','top','right','bottom','left','z-index','inset',
+  // Flexbox / Grid
+  'flex','flex-grow','flex-shrink','flex-basis','flex-direction','flex-wrap',
+  'align-items','align-self','align-content','justify-content','justify-items','justify-self',
+  'gap','row-gap','column-gap',
+  'grid-template-columns','grid-template-rows','grid-column','grid-row',
+  'grid-area','grid-template-areas',
+  // Typography
+  'font-size','font-weight','font-family','font-style','line-height',
+  'letter-spacing','text-align','text-decoration','text-transform',
+  'text-overflow','white-space','word-break','word-wrap','overflow-wrap',
+  // Color / Background
+  'color','background','background-color','background-image',
+  'background-position','background-size','background-repeat',
+  'opacity',
+  // Border
+  'border','border-top','border-right','border-bottom','border-left',
+  'border-width','border-style','border-color','border-radius',
+  'outline','outline-offset',
+  // Effects
+  'box-shadow','text-shadow','filter','backdrop-filter','transform',
+  'transition','animation',
+  // Layout
+  'display','overflow','overflow-x','overflow-y','visibility',
+  'pointer-events','cursor','user-select',
+  // Misc safe
+  'aspect-ratio','object-fit','object-position','list-style',
+  'vertical-align','float','clear','resize','scroll-behavior',
+  'content',  // allow content: '' for pseudo-like patterns but value is guarded
+]);
+
+/**
+ * Sanitize an arbitrary CSS value.
+ * Returns the value unchanged if safe, or null if dangerous.
+ */
+function sanitizeCSSValue(value: string): string | null {
+  if (DANGEROUS_VALUE_RE.test(value)) return null;
+  // Strip any attempt to close a style block
+  if (value.includes('}') || value.includes('{') || value.includes('<') || value.includes('>')) return null;
+  return value;
+}
+
+/**
+ * Sanitize an arbitrary CSS property name.
+ * Returns the property unchanged if safe, or null if dangerous.
+ */
+function sanitizeCSSProp(prop: string): string | null {
+  const normalized = prop.toLowerCase().trim();
+  if (DANGEROUS_PROPS.has(normalized)) return null;
+  if (!SAFE_CSS_PROPS.has(normalized)) return null; // allowlist enforcement
+  return normalized;
+}
+
 // ── Arbitrary value extractor ─────────────────────────────────────────────────
 
 function extractArbitrary(value: string): string | null {
   const match = value.match(/^\[(.+)]$/);
-  return match ? match[1] : null;
+  if (!match) return null;
+  return sanitizeCSSValue(match[1]);
 }
 
 // ── Color value resolver ──────────────────────────────────────────────────────
@@ -116,9 +200,11 @@ function resolveColor(token: string): string {
   if (token === 'white') return '#ffffff';
   if (token === 'black') return '#000000';
   if (token === 'inherit') return 'inherit';
-  // Arbitrary: [#ff0000] or [rgb(0,0,0)]
+  // Arbitrary: [#ff0000] or [rgb(0,0,0)] — sanitized
   const arb = extractArbitrary(token);
   if (arb) return arb;
+  // Bare hex
+  if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(token)) return token;
   return token;
 }
 
@@ -130,9 +216,14 @@ type Declarations = Record<string, string>;
 
 // eslint-disable-next-line complexity
 function resolveUtility(u: string): Declarations | null {
-  // ── Arbitrary value shorthand: [css-prop:value] ────────────────────────────
+  // ── Arbitrary value shorthand: [css-prop:value] — security-guarded ────────
   const fullArb = u.match(/^\[([a-zA-Z-]+):(.+)]$/);
-  if (fullArb) return { [fullArb[1]]: fullArb[2] };
+  if (fullArb) {
+    const safeProp = sanitizeCSSProp(fullArb[1]);
+    const safeVal  = sanitizeCSSValue(fullArb[2]);
+    if (safeProp && safeVal) return { [safeProp]: safeVal };
+    return null; // silently drop dangerous declaration
+  }
 
   // ── Display ────────────────────────────────────────────────────────────────
   const displayMap: Record<string, string> = {

package/src/headless/index.ts

@@ -42,3 +42,9 @@ 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/useInfiniteQuery.ts

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

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

@@ -0,0 +1,229 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+export interface WebSocketOptions {
+  url: string;
+  protocols?: string | string[];
+  reconnect?: boolean;
+  reconnectDelay?: number;
+  reconnectAttempts?: number;
+  heartbeatInterval?: number;
+  heartbeatMessage?: string;
+  onOpen?: (event: Event) => void;
+  onClose?: (event: CloseEvent) => void;
+  onError?: (event: Event) => void;
+  onMessage?: (data: unknown) => void;
+}
+
+export interface WebSocketState<T = unknown> {
+  status: 'connecting' | 'connected' | 'disconnected' | 'error';
+  lastMessage: T | null;
+  messages: T[];
+  send: (data: string | object) => void;
+  connect: () => void;
+  disconnect: () => void;
+  reconnectCount: number;
+  latency: number | null;
+}
+
+/**
+ * Headless WebSocket hook with auto-reconnect, heartbeat, latency tracking,
+ * and a send queue that flushes on connect.
+ *
+ * @example
+ * const ws = useWebSocket({ url: 'wss://example.com/ws' });
+ * ws.send({ type: 'subscribe', channel: 'updates' });
+ */
+export function useWebSocket<T = unknown>(options: WebSocketOptions): WebSocketState<T> {
+  const {
+    url,
+    protocols,
+    reconnect = true,
+    reconnectDelay = 1000,
+    reconnectAttempts = 10,
+    heartbeatInterval = 30000,
+    heartbeatMessage = 'ping',
+    onOpen,
+    onClose,
+    onError,
+    onMessage,
+  } = options;
+
+  const [status, setStatus] = useState<WebSocketState<T>['status']>('disconnected');
+  const [lastMessage, setLastMessage] = useState<T | null>(null);
+  const [messages, setMessages] = useState<T[]>([]);
+  const [reconnectCount, setReconnectCount] = useState(0);
+  const [latency, setLatency] = useState<number | null>(null);
+
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectCountRef = useRef(0);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const heartbeatTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const pingTimeRef = useRef<number | null>(null);
+  const sendQueueRef = useRef<Array<string | object>>([]);
+  const mountedRef = useRef(true);
+  const manualDisconnectRef = useRef(false);
+
+  // Keep option callbacks in refs so connect() closure stays stable
+  const onOpenRef = useRef(onOpen);
+  const onCloseRef = useRef(onClose);
+  const onErrorRef = useRef(onError);
+  const onMessageRef = useRef(onMessage);
+  onOpenRef.current = onOpen;
+  onCloseRef.current = onClose;
+  onErrorRef.current = onError;
+  onMessageRef.current = onMessage;
+
+  const clearTimers = useCallback(() => {
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = null;
+    }
+    if (heartbeatTimerRef.current) {
+      clearInterval(heartbeatTimerRef.current);
+      heartbeatTimerRef.current = null;
+    }
+  }, []);
+
+  const flushQueue = useCallback((ws: WebSocket) => {
+    while (sendQueueRef.current.length > 0) {
+      const msg = sendQueueRef.current.shift();
+      if (msg !== undefined) {
+        ws.send(typeof msg === 'string' ? msg : JSON.stringify(msg));
+      }
+    }
+  }, []);
+
+  const connect = useCallback(() => {
+    if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) return;
+
+    manualDisconnectRef.current = false;
+    clearTimers();
+
+    if (mountedRef.current) setStatus('connecting');
+
+    const ws = new WebSocket(url, protocols);
+    wsRef.current = ws;
+
+    ws.onopen = (event) => {
+      if (!mountedRef.current) return;
+      setStatus('connected');
+      reconnectCountRef.current = 0;
+      setReconnectCount(0);
+      onOpenRef.current?.(event);
+      flushQueue(ws);
+
+      // Start heartbeat
+      heartbeatTimerRef.current = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          pingTimeRef.current = Date.now();
+          try {
+            ws.send(JSON.stringify({ type: 'ping', t: pingTimeRef.current }));
+          } catch {
+            // If send fails the error handler will manage reconnect
+          }
+        }
+      }, heartbeatInterval);
+    };
+
+    ws.onmessage = (event) => {
+      if (!mountedRef.current) return;
+
+      let parsed: T;
+      try {
+        parsed = JSON.parse(event.data as string) as T;
+      } catch {
+        parsed = event.data as unknown as T;
+      }
+
+      // Latency tracking: respond to pong
+      const asRecord = parsed as Record<string, unknown>;
+      if (
+        asRecord &&
+        typeof asRecord === 'object' &&
+        asRecord.type === 'pong' &&
+        typeof asRecord.t === 'number'
+      ) {
+        setLatency(Date.now() - asRecord.t);
+        return;
+      }
+
+      // Also measure latency if message text matches heartbeatMessage
+      if (parsed === heartbeatMessage && pingTimeRef.current !== null) {
+        setLatency(Date.now() - pingTimeRef.current);
+        pingTimeRef.current = null;
+        return;
+      }
+
+      setLastMessage(parsed);
+      setMessages(prev => {
+        const next = [...prev, parsed];
+        return next.length > 100 ? next.slice(next.length - 100) : next;
+      });
+      onMessageRef.current?.(parsed);
+    };
+
+    ws.onerror = (event) => {
+      if (!mountedRef.current) return;
+      setStatus('error');
+      onErrorRef.current?.(event);
+    };
+
+    ws.onclose = (event) => {
+      if (!mountedRef.current) return;
+      clearTimers();
+      setStatus('disconnected');
+      onCloseRef.current?.(event);
+
+      if (
+        !manualDisconnectRef.current &&
+        reconnect &&
+        reconnectCountRef.current < reconnectAttempts
+      ) {
+        const attempt = reconnectCountRef.current;
+        const delay = reconnectDelay * Math.pow(1.5, attempt);
+        reconnectCountRef.current += 1;
+        setReconnectCount(reconnectCountRef.current);
+        reconnectTimerRef.current = setTimeout(() => {
+          if (mountedRef.current) connect();
+        }, delay);
+      }
+    };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url, protocols, reconnect, reconnectDelay, reconnectAttempts, heartbeatInterval, heartbeatMessage, clearTimers, flushQueue]);
+
+  const disconnect = useCallback(() => {
+    manualDisconnectRef.current = true;
+    clearTimers();
+    if (wsRef.current) {
+      wsRef.current.close();
+      wsRef.current = null;
+    }
+    if (mountedRef.current) setStatus('disconnected');
+  }, [clearTimers]);
+
+  const send = useCallback((data: string | object) => {
+    if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+      wsRef.current.send(typeof data === 'string' ? data : JSON.stringify(data));
+    } else {
+      sendQueueRef.current.push(data);
+    }
+  }, []);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    connect();
+    return () => {
+      mountedRef.current = false;
+      manualDisconnectRef.current = true;
+      clearTimers();
+      if (wsRef.current) {
+        wsRef.current.close();
+        wsRef.current = null;
+      }
+    };
+  // connect is stable (useCallback with stable deps), so this is intentional
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { status, lastMessage, messages, send, connect, disconnect, reconnectCount, latency };
+}