tekivex-ui 2.0.0

package/src/engine/wcag.ts

@@ -0,0 +1,275 @@
+// ── WCAG Accessibility Engine ────────────────────────────────────────────────
+// Contrast calculation, focus management, keyboard patterns, screen reader
+
+// ── Color Contrast ───────────────────────────────────────────────────────────
+
+function hexToRgb(hex: string): [number, number, number] {
+  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 [r, g, 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/hooks/index.ts

@@ -0,0 +1,120 @@
+import {
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  type RefObject,
+} from 'react';
+import {
+  prefersReducedMotion,
+  prefersHighContrast,
+  createFocusTrap,
+  createAnnouncer,
+  type Announcer,
+} from '../engine/wcag';
+
+// ── useReducedMotion ─────────────────────────────────────────────────────────
+
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return prefersReducedMotion();
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handler = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  return reduced;
+}
+
+// ── useHighContrast ──────────────────────────────────────────────────────────
+
+export function useHighContrast(): boolean {
+  const [highContrast, setHighContrast] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return prefersHighContrast();
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const mq = window.matchMedia('(forced-colors: active)');
+    const handler = (e: MediaQueryListEvent) => setHighContrast(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  return highContrast;
+}
+
+// ── useFocusTrap ─────────────────────────────────────────────────────────────
+
+export function useFocusTrap(active: boolean): RefObject<HTMLElement | null> {
+  const ref = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (!active || !ref.current) return;
+    const trap = createFocusTrap(ref.current);
+    trap.activate();
+    return () => trap.deactivate();
+  }, [active]);
+
+  return ref;
+}
+
+// ── useAnnounce ──────────────────────────────────────────────────────────────
+
+export function useAnnounce(): (message: string, politeness?: 'polite' | 'assertive') => void {
+  const announcerRef = useRef<Announcer | null>(null);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    announcerRef.current = createAnnouncer();
+    return () => {
+      announcerRef.current?.destroy();
+    };
+  }, []);
+
+  return useCallback((message: string, politeness: 'polite' | 'assertive' = 'polite') => {
+    announcerRef.current?.announce(message, politeness);
+  }, []);
+}
+
+// ── useEscapeKey ─────────────────────────────────────────────────────────────
+
+export function useEscapeKey(handler: () => void, active = true): void {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    if (!active) return;
+    const listener = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') handlerRef.current();
+    };
+    document.addEventListener('keydown', listener);
+    return () => document.removeEventListener('keydown', listener);
+  }, [active]);
+}
+
+// ── useClickOutside ──────────────────────────────────────────────────────────
+
+export function useClickOutside(
+  ref: RefObject<HTMLElement | null>,
+  handler: () => void,
+): void {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener = (e: PointerEvent) => {
+      if (!ref.current || ref.current.contains(e.target as Node)) return;
+      handlerRef.current();
+    };
+    document.addEventListener('pointerdown', listener);
+    return () => document.removeEventListener('pointerdown', listener);
+  }, [ref]);
+}

package/src/styles/global.css

@@ -0,0 +1,167 @@
+/* TekiVex UI — Global Styles */
+
+/* ── Reset ────────────────────────────────────────────────────────────────── */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+/* ── CSS Custom Property Defaults (Quantum Dark) ──────────────────────────── */
+:root {
+  --tkx-bg: #0a0a0f;
+  --tkx-surface: #12121a;
+  --tkx-surfaceAlt: #1a1a2e;
+  --tkx-border: #2a2a3e;
+  --tkx-text: #e8e8f4;
+  --tkx-textMuted: #8888aa;
+  --tkx-primary: #00f5d4;
+  --tkx-secondary: #7b2ff7;
+  --tkx-danger: #f72585;
+  --tkx-warning: #ffbe0b;
+  --tkx-success: #06d6a0;
+  --tkx-info: #3a86ff;
+
+  /* Spacing scale */
+  --tkx-space-xs: 4px;
+  --tkx-space-sm: 8px;
+  --tkx-space-md: 16px;
+  --tkx-space-lg: 24px;
+  --tkx-space-xl: 32px;
+
+  /* Border radius */
+  --tkx-radius-sm: 4px;
+  --tkx-radius-md: 8px;
+  --tkx-radius-lg: 12px;
+  --tkx-radius-full: 9999px;
+
+  /* Typography */
+  --tkx-font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --tkx-font-mono: 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+
+  /* Transitions */
+  --tkx-transition: 200ms ease;
+  --tkx-transition-fast: 100ms ease;
+}
+
+/* ── Focus-Visible Styles ─────────────────────────────────────────────────── */
+.tkx-focus-ring:focus-visible {
+  outline: 2px solid var(--tkx-primary);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+:focus:not(:focus-visible) {
+  outline: none;
+}
+
+/* ── Skip Navigation ──────────────────────────────────────────────────────── */
+.tkx-skip-nav {
+  position: absolute;
+  top: -9999px;
+  left: 0;
+  z-index: 9999;
+  padding: 8px 16px;
+  background: var(--tkx-primary);
+  color: var(--tkx-bg);
+  font-weight: 600;
+  text-decoration: none;
+  border-radius: 0 0 4px 0;
+  transition: top var(--tkx-transition-fast);
+}
+
+.tkx-skip-nav:focus {
+  top: 0;
+  outline: 2px solid var(--tkx-bg);
+  outline-offset: 2px;
+}
+
+/* ── Visually Hidden (Screen-reader only) ─────────────────────────────────── */
+.tkx-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ── Animation Keyframes ──────────────────────────────────────────────────── */
+@keyframes tkx-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes tkx-slide-up {
+  from {
+    transform: translateY(8px);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+@keyframes tkx-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+@keyframes tkx-spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+@keyframes tkx-shimmer {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+@keyframes tkx-ripple {
+  0% {
+    transform: scale(0);
+    opacity: 0.6;
+  }
+  100% {
+    transform: scale(4);
+    opacity: 0;
+  }
+}
+
+/* ── Reduced Motion ───────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ── High Contrast (prefers-contrast: more) ───────────────────────────────── */
+@media (prefers-contrast: more) {
+  :root {
+    --tkx-border: currentColor;
+  }
+
+  .tkx-focus-ring:focus-visible {
+    outline-width: 3px;
+  }
+}
+
+/* ── Forced Colors (Windows High Contrast Mode) ───────────────────────────── */
+@media (forced-colors: active) {
+  .tkx-button,
+  .tkx-badge,
+  .tkx-toggle,
+  .tkx-input,
+  .tkx-card {
+    forced-color-adjust: none;
+  }
+}

package/src/themes/index.ts

@@ -0,0 +1,111 @@
+import { createContext, useContext, useEffect, type ReactNode, createElement } from 'react';
+import { cssVar } from '../engine/css';
+import { meetsAA } from '../engine/wcag';
+
+// ── Theme Token Type ─────────────────────────────────────────────────────────
+
+export interface ThemeTokens {
+  bg: string;
+  surface: string;
+  surfaceAlt: string;
+  border: string;
+  text: string;
+  textMuted: string;
+  primary: string;
+  secondary: string;
+  danger: string;
+  warning: string;
+  success: string;
+  info: string;
+}
+
+// ── Built-in Themes ──────────────────────────────────────────────────────────
+
+export const quantumDark: ThemeTokens = {
+  bg: '#0a0a0f',
+  surface: '#12121a',
+  surfaceAlt: '#1a1a2e',
+  border: '#2a2a3e',
+  text: '#e8e8f4',
+  textMuted: '#8888aa',
+  primary: '#00f5d4',
+  secondary: '#7b2ff7',
+  danger: '#f72585',
+  warning: '#ffbe0b',
+  success: '#06d6a0',
+  info: '#3a86ff',
+};
+
+export const auroraLight: ThemeTokens = {
+  bg: '#f8f6f1',
+  surface: '#ffffff',
+  surfaceAlt: '#f0ede6',
+  border: '#ddd8cc',
+  text: '#1a1815',
+  textMuted: '#6b6560',
+  primary: '#0d7c5f',
+  secondary: '#6930c3',
+  danger: '#c1121f',
+  warning: '#d4a017',
+  success: '#0d7c5f',
+  info: '#1d4ed8',
+};
+
+// ── Theme Factory ────────────────────────────────────────────────────────────
+
+const HEX_PATTERN = /^#[0-9a-fA-F]{3,8}$/;
+
+export function createTheme(base: ThemeTokens, overrides?: Partial<ThemeTokens>): ThemeTokens {
+  const theme = { ...base, ...overrides };
+
+  for (const [key, value] of Object.entries(theme)) {
+    if (!HEX_PATTERN.test(value)) {
+      throw new Error(`Invalid hex color for theme token '${key}': ${value}`);
+    }
+  }
+
+  if (!meetsAA(theme.text, theme.bg)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[TekiVex] Theme contrast warning: text (${theme.text}) vs bg (${theme.bg}) does not meet WCAG AA minimum (4.5:1)`,
+    );
+  }
+  if (!meetsAA(theme.primary, theme.bg)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[TekiVex] Theme contrast warning: primary (${theme.primary}) vs bg (${theme.bg}) does not meet WCAG AA minimum`,
+    );
+  }
+
+  return theme;
+}
+
+// ── Theme Context ────────────────────────────────────────────────────────────
+
+export const ThemeContext = createContext<ThemeTokens>(quantumDark);
+
+export interface ThemeProviderProps {
+  theme?: ThemeTokens;
+  children: ReactNode;
+}
+
+export function ThemeProvider({ theme = quantumDark, children }: ThemeProviderProps) {
+  useEffect(() => {
+    const vars = (Object.entries(theme) as [keyof ThemeTokens, string][])
+      .map(([key, value]) => cssVar(key, value))
+      .join(' ');
+    let styleEl = document.getElementById('tkx-theme') as HTMLStyleElement | null;
+    if (!styleEl) {
+      styleEl = document.createElement('style');
+      styleEl.id = 'tkx-theme';
+      document.head.appendChild(styleEl);
+    }
+    styleEl.textContent = `:root { ${vars} }`;
+  }, [theme]);
+
+  return createElement(ThemeContext.Provider, { value: theme }, children);
+}
+
+export function useTheme(): ThemeTokens {
+  return useContext(ThemeContext);
+}