@object-ui/core 2.0.0 → 3.0.1

package/src/theme/ThemeEngine.ts

@@ -450,3 +450,81 @@ export function resolveMode(
 
   return 'light'; // fallback
 }
+
+// ============================================================================
+// WCAG Contrast Checking (v2.0.7)
+// ============================================================================
+
+/**
+ * Parse a hex color string to RGB values [0-255].
+ */
+function hexToRGB(hex: string): [number, number, number] | null {
+  let clean = hex.replace(/^#/, '');
+  if (clean.length === 3) {
+    clean = clean[0] + clean[0] + clean[1] + clean[1] + clean[2] + clean[2];
+  }
+  const match = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(clean);
+  if (!match) return null;
+  return [parseInt(match[1], 16), parseInt(match[2], 16), parseInt(match[3], 16)];
+}
+
+/**
+ * Calculate relative luminance per WCAG 2.1 spec.
+ * @see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function relativeLuminance(r: number, g: number, b: number): number {
+  const [rs, gs, bs] = [r, g, b].map(c => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+/**
+ * Calculate the WCAG 2.1 contrast ratio between two hex colors.
+ * Returns a value between 1 and 21.
+ *
+ * @param hex1 - First color in hex format (#RGB or #RRGGBB)
+ * @param hex2 - Second color in hex format (#RGB or #RRGGBB)
+ * @returns Contrast ratio (1-21), or null if colors are invalid
+ */
+export function contrastRatio(hex1: string, hex2: string): number | null {
+  const rgb1 = hexToRGB(hex1);
+  const rgb2 = hexToRGB(hex2);
+  if (!rgb1 || !rgb2) return null;
+
+  const l1 = relativeLuminance(...rgb1);
+  const l2 = relativeLuminance(...rgb2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Check if two colors meet the specified WCAG contrast level.
+ *
+ * WCAG levels:
+ * - AA: 4.5:1 for normal text, 3:1 for large text
+ * - AAA: 7:1 for normal text, 4.5:1 for large text
+ *
+ * @param hex1 - First color in hex format
+ * @param hex2 - Second color in hex format
+ * @param level - WCAG level: 'AA' or 'AAA'
+ * @param isLargeText - Whether the text is large (18pt+ or 14pt+ bold)
+ * @returns true if the color pair meets the required contrast level
+ */
+export function meetsContrastLevel(
+  hex1: string,
+  hex2: string,
+  level: 'AA' | 'AAA' = 'AA',
+  isLargeText = false,
+): boolean {
+  const ratio = contrastRatio(hex1, hex2);
+  if (ratio === null) return false;
+
+  if (level === 'AAA') {
+    return isLargeText ? ratio >= 4.5 : ratio >= 7;
+  }
+  // AA
+  return isLargeText ? ratio >= 3 : ratio >= 4.5;
+}

package/src/theme/__tests__/ThemeEngine.test.ts

@@ -21,6 +21,8 @@ import {
   mergeThemes,
   resolveThemeInheritance,
   resolveMode,
+  contrastRatio,
+  meetsContrastLevel,
 } from '../ThemeEngine';
 
 // ============================================================================
@@ -604,3 +606,63 @@ describe('resolveMode', () => {
     window.matchMedia = original;
   });
 });
+
+// ============================================================================
+// WCAG Contrast Checking (v2.0.7)
+// ============================================================================
+
+describe('contrastRatio', () => {
+  it('should return 21 for black and white', () => {
+    expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 0);
+  });
+
+  it('should return 1 for identical colors', () => {
+    expect(contrastRatio('#336699', '#336699')).toBeCloseTo(1, 1);
+  });
+
+  it('should return null for invalid hex', () => {
+    expect(contrastRatio('invalid', '#000000')).toBeNull();
+    expect(contrastRatio('#000000', 'xyz')).toBeNull();
+  });
+
+  it('should handle shorthand hex (#RGB)', () => {
+    const ratio = contrastRatio('#000', '#fff');
+    expect(ratio).toBeCloseTo(21, 0);
+  });
+
+  it('should be order-independent', () => {
+    const ratio1 = contrastRatio('#000000', '#336699');
+    const ratio2 = contrastRatio('#336699', '#000000');
+    expect(ratio1).toBe(ratio2);
+  });
+});
+
+describe('meetsContrastLevel', () => {
+  it('should pass AA for black on white (normal text)', () => {
+    expect(meetsContrastLevel('#000000', '#ffffff', 'AA')).toBe(true);
+  });
+
+  it('should pass AAA for black on white (normal text)', () => {
+    expect(meetsContrastLevel('#000000', '#ffffff', 'AAA')).toBe(true);
+  });
+
+  it('should fail AA for similar grays', () => {
+    // #777 on #999 gives ~1.6:1 ratio
+    expect(meetsContrastLevel('#777777', '#999999', 'AA')).toBe(false);
+  });
+
+  it('should use lower threshold for large text (AA)', () => {
+    // #767676 on white gives ~4.54:1 (passes AA normal, passes AA large)
+    expect(meetsContrastLevel('#767676', '#ffffff', 'AA', false)).toBe(true);
+    expect(meetsContrastLevel('#767676', '#ffffff', 'AA', true)).toBe(true);
+  });
+
+  it('should use lower threshold for large text (AAA)', () => {
+    // Black on white: 21:1 — passes both
+    expect(meetsContrastLevel('#000000', '#ffffff', 'AAA', true)).toBe(true);
+  });
+
+  it('should return false for invalid colors', () => {
+    expect(meetsContrastLevel('invalid', '#ffffff', 'AA')).toBe(false);
+  });
+});

package/src/theme/index.ts

@@ -19,4 +19,6 @@ export {
   mergeThemes,
   resolveThemeInheritance,
   resolveMode,
+  contrastRatio,
+  meetsContrastLevel,
 } from './ThemeEngine';

package/src/utils/__tests__/debug.test.ts

@@ -0,0 +1,83 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { debugLog, debugTime, debugTimeEnd } from '../debug';
+
+describe('Debug Utilities', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    (globalThis as any).OBJECTUI_DEBUG = undefined;
+  });
+
+  describe('debugLog', () => {
+    it('should not log when debug is disabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = false;
+      debugLog('schema', 'test message');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should log when OBJECTUI_DEBUG is true', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugLog('schema', 'Resolving component');
+      expect(consoleSpy).toHaveBeenCalledWith('[ObjectUI Debug][schema] Resolving component');
+    });
+
+    it('should log with data when provided', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugLog('registry', 'Registered', { type: 'Button' });
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[ObjectUI Debug][registry] Registered',
+        { type: 'Button' }
+      );
+    });
+
+    it('should not log when debug is undefined', () => {
+      debugLog('action', 'test');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('debugTime / debugTimeEnd', () => {
+    it('should not log timing when debug is disabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = false;
+      debugTime('test-timer');
+      debugTimeEnd('test-timer');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should measure and log elapsed time when debug is enabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugTime('render-test');
+
+      // Simulate some delay via a busy loop
+      const start = performance.now();
+      while (performance.now() - start < 5) {
+        // wait ~5ms
+      }
+
+      debugTimeEnd('render-test');
+      expect(consoleSpy).toHaveBeenCalledTimes(1);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringMatching(/^\[ObjectUI Debug\]\[perf\] render-test: \d+\.\d{2}ms$/)
+      );
+    });
+
+    it('should not log if debugTimeEnd is called without debugTime', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugTimeEnd('nonexistent');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/utils/debug.ts

@@ -0,0 +1,66 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render';
+
+function isDebugEnabled(): boolean {
+  try {
+    const g = typeof globalThis !== 'undefined' && (globalThis as any).OBJECTUI_DEBUG;
+    return (
+      (g === true || g === 'true') ||
+      (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true')
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Log a debug message when OBJECTUI_DEBUG is enabled.
+ * No-op in production or when debug mode is off.
+ *
+ * @example
+ * ```ts
+ * // Enable debug mode
+ * globalThis.OBJECTUI_DEBUG = true;
+ *
+ * debugLog('schema', 'Resolving component', { type: 'Button' });
+ * // [ObjectUI Debug][schema] Resolving component { type: 'Button' }
+ * ```
+ */
+export function debugLog(category: DebugCategory, message: string, data?: unknown): void {
+  if (!isDebugEnabled()) return;
+  if (data !== undefined) {
+    console.log(`[ObjectUI Debug][${category}] ${message}`, data);
+  } else {
+    console.log(`[ObjectUI Debug][${category}] ${message}`);
+  }
+}
+
+const timers = new Map<string, number>();
+
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export function debugTime(label: string): void {
+  if (!isDebugEnabled()) return;
+  timers.set(label, performance.now());
+}
+
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export function debugTimeEnd(label: string): void {
+  if (!isDebugEnabled()) return;
+  const start = timers.get(label);
+  if (start !== undefined) {
+    const elapsed = (performance.now() - start).toFixed(2);
+    console.log(`[ObjectUI Debug][perf] ${label}: ${elapsed}ms`);
+    timers.delete(label);
+  }
+}

package/src/validation/validation-engine.ts

@@ -401,7 +401,15 @@ export class ValidationEngine {
    */
   private evaluateCondition(condition: any, values: Record<string, any>): boolean {
     if (typeof condition === 'function') {
-      console.warn('Function-based conditions are deprecated and will be removed. Use declarative conditions instead.');
+      console.warn(
+        'Function-based conditions are deprecated and will be removed. Use declarative conditions instead.\n\n' +
+        '  Migration:\n' +
+        '  // Before (deprecated):\n' +
+        '  { condition: (values) => values.age > 18 }\n\n' +
+        '  // After:\n' +
+        '  { condition: { field: "age", operator: ">", value: 18 } }\n\n' +
+        '  See: https://github.com/objectstack-ai/objectui/blob/main/MIGRATION_GUIDE.md'
+      );
       return false; // Security: reject function-based conditions
     }