@object-ui/core 0.5.0 → 3.0.0

package/dist/theme/ThemeEngine.js

@@ -0,0 +1,469 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// Color Utilities
+// ============================================================================
+/**
+ * Convert a hex color (#RRGGBB or #RGB) to an HSL string "H S% L%".
+ * Returns null if the input is not a valid hex color.
+ */
+export function hexToHSL(hex) {
+    // Expand shorthand (#RGB → #RRGGBB)
+    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;
+    const r = parseInt(match[1], 16) / 255;
+    const g = parseInt(match[2], 16) / 255;
+    const b = parseInt(match[3], 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let h = 0;
+    let s = 0;
+    const l = (max + min) / 2;
+    if (max !== min) {
+        const d = max - min;
+        s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+        switch (max) {
+            case r:
+                h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / d + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / d + 4) / 6;
+                break;
+        }
+    }
+    return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`;
+}
+/**
+ * Detect if a color string is a hex value.
+ */
+function isHex(color) {
+    return /^#([a-f\d]{3}|[a-f\d]{6})$/i.test(color);
+}
+/**
+ * Convert a color to a CSS-ready value.
+ * - Hex colors → HSL format for Shadcn CSS variable compatibility
+ * - Non-hex colors → passed through as-is (rgb, hsl, oklch, etc.)
+ */
+export function toCSSColor(color) {
+    if (isHex(color)) {
+        return hexToHSL(color) ?? color;
+    }
+    return color;
+}
+// ============================================================================
+// Theme → CSS Variable Mapping
+// ============================================================================
+/**
+ * Mapping from spec ColorPalette keys → Shadcn CSS variable names.
+ *
+ * The spec uses semantic names (primary, secondary, error, text, surface, etc.)
+ * while Shadcn uses its own naming (--primary, --secondary, --destructive, etc.)
+ * This maps the spec keys to the closest Shadcn equivalent.
+ */
+const COLOR_TO_CSS_MAP = {
+    primary: '--primary',
+    secondary: '--secondary',
+    accent: '--accent',
+    success: '--success',
+    warning: '--warning',
+    error: '--destructive',
+    info: '--info',
+    background: '--background',
+    surface: '--card',
+    text: '--foreground',
+    textSecondary: '--muted-foreground',
+    border: '--border',
+    disabled: '--muted',
+    primaryLight: '--primary-light',
+    primaryDark: '--primary-dark',
+    secondaryLight: '--secondary-light',
+    secondaryDark: '--secondary-dark',
+};
+/**
+ * Generate CSS custom properties from a Theme's color palette.
+ */
+export function generateColorVars(colors) {
+    const vars = {};
+    for (const [key, cssVar] of Object.entries(COLOR_TO_CSS_MAP)) {
+        const value = colors[key];
+        if (value) {
+            const cssValue = toCSSColor(value);
+            if (Array.isArray(cssVar)) {
+                for (const v of cssVar) {
+                    vars[v] = cssValue;
+                }
+            }
+            else {
+                vars[cssVar] = cssValue;
+            }
+        }
+    }
+    return vars;
+}
+/**
+ * Generate CSS custom properties from a Theme's typography config.
+ */
+export function generateTypographyVars(typography) {
+    const vars = {};
+    if (typography.fontFamily?.base) {
+        vars['--font-sans'] = typography.fontFamily.base;
+    }
+    if (typography.fontFamily?.heading) {
+        vars['--font-heading'] = typography.fontFamily.heading;
+    }
+    if (typography.fontFamily?.mono) {
+        vars['--font-mono'] = typography.fontFamily.mono;
+    }
+    if (typography.fontSize) {
+        for (const [key, value] of Object.entries(typography.fontSize)) {
+            if (value)
+                vars[`--font-size-${key}`] = value;
+        }
+    }
+    if (typography.fontWeight) {
+        for (const [key, value] of Object.entries(typography.fontWeight)) {
+            if (value != null)
+                vars[`--font-weight-${key}`] = String(value);
+        }
+    }
+    if (typography.lineHeight) {
+        for (const [key, value] of Object.entries(typography.lineHeight)) {
+            if (value)
+                vars[`--line-height-${key}`] = value;
+        }
+    }
+    if (typography.letterSpacing) {
+        for (const [key, value] of Object.entries(typography.letterSpacing)) {
+            if (value)
+                vars[`--letter-spacing-${key}`] = value;
+        }
+    }
+    return vars;
+}
+/**
+ * Generate CSS custom properties from a Theme's border radius config.
+ */
+export function generateBorderRadiusVars(borderRadius) {
+    const vars = {};
+    const map = {
+        none: '--radius-none',
+        sm: '--radius-sm',
+        base: '--radius',
+        md: '--radius-md',
+        lg: '--radius-lg',
+        xl: '--radius-xl',
+        '2xl': '--radius-2xl',
+        full: '--radius-full',
+    };
+    for (const [key, cssVar] of Object.entries(map)) {
+        const value = borderRadius[key];
+        if (value)
+            vars[cssVar] = value;
+    }
+    return vars;
+}
+/**
+ * Generate CSS custom properties from a Theme's shadow config.
+ */
+export function generateShadowVars(shadows) {
+    const vars = {};
+    const map = {
+        none: '--shadow-none',
+        sm: '--shadow-sm',
+        base: '--shadow',
+        md: '--shadow-md',
+        lg: '--shadow-lg',
+        xl: '--shadow-xl',
+        '2xl': '--shadow-2xl',
+        inner: '--shadow-inner',
+    };
+    for (const [key, cssVar] of Object.entries(map)) {
+        const value = shadows[key];
+        if (value)
+            vars[cssVar] = value;
+    }
+    return vars;
+}
+/**
+ * Generate CSS custom properties from a Theme's animation config.
+ */
+export function generateAnimationVars(animation) {
+    const vars = {};
+    if (animation.duration) {
+        for (const [key, value] of Object.entries(animation.duration)) {
+            if (value)
+                vars[`--duration-${key}`] = value;
+        }
+    }
+    if (animation.timing) {
+        for (const [key, value] of Object.entries(animation.timing)) {
+            if (value)
+                vars[`--timing-${key}`] = value;
+        }
+    }
+    return vars;
+}
+/**
+ * Generate CSS custom properties from a Theme's z-index config.
+ */
+export function generateZIndexVars(zIndex) {
+    const vars = {};
+    for (const [key, value] of Object.entries(zIndex)) {
+        if (value != null)
+            vars[`--z-${key}`] = String(value);
+    }
+    return vars;
+}
+/**
+ * Generate ALL CSS custom properties from a complete Theme.
+ * This is the main entry point for theme → CSS conversion.
+ */
+export function generateThemeVars(theme) {
+    const vars = {};
+    // Colors (always present — colors.primary is required)
+    Object.assign(vars, generateColorVars(theme.colors));
+    // Typography
+    if (theme.typography) {
+        Object.assign(vars, generateTypographyVars(theme.typography));
+    }
+    // Border Radius
+    if (theme.borderRadius) {
+        Object.assign(vars, generateBorderRadiusVars(theme.borderRadius));
+    }
+    // Shadows
+    if (theme.shadows) {
+        Object.assign(vars, generateShadowVars(theme.shadows));
+    }
+    // Animation
+    if (theme.animation) {
+        Object.assign(vars, generateAnimationVars(theme.animation));
+    }
+    // Z-Index
+    if (theme.zIndex) {
+        Object.assign(vars, generateZIndexVars(theme.zIndex));
+    }
+    // Custom CSS variables (passthrough)
+    if (theme.customVars) {
+        for (const [key, value] of Object.entries(theme.customVars)) {
+            // Ensure CSS variable prefix
+            const varName = key.startsWith('--') ? key : `--${key}`;
+            vars[varName] = value;
+        }
+    }
+    return vars;
+}
+// ============================================================================
+// Theme Inheritance
+// ============================================================================
+/**
+ * Deep-merge two Theme objects. The `child` overrides the `parent`.
+ * Only defined properties in child override; undefined falls back to parent.
+ */
+export function mergeThemes(parent, child) {
+    return {
+        ...parent,
+        ...child,
+        // Deep-merge colors
+        colors: {
+            ...parent.colors,
+            ...(child.colors ?? {}),
+        },
+        // Deep-merge typography
+        typography: child.typography || parent.typography
+            ? {
+                ...parent.typography,
+                ...child.typography,
+                fontFamily: {
+                    ...parent.typography?.fontFamily,
+                    ...child.typography?.fontFamily,
+                },
+                fontSize: {
+                    ...parent.typography?.fontSize,
+                    ...child.typography?.fontSize,
+                },
+                fontWeight: {
+                    ...parent.typography?.fontWeight,
+                    ...child.typography?.fontWeight,
+                },
+                lineHeight: {
+                    ...parent.typography?.lineHeight,
+                    ...child.typography?.lineHeight,
+                },
+                letterSpacing: {
+                    ...parent.typography?.letterSpacing,
+                    ...child.typography?.letterSpacing,
+                },
+            }
+            : undefined,
+        // Deep-merge border radius
+        borderRadius: child.borderRadius || parent.borderRadius
+            ? { ...parent.borderRadius, ...child.borderRadius }
+            : undefined,
+        // Deep-merge shadows
+        shadows: child.shadows || parent.shadows
+            ? { ...parent.shadows, ...child.shadows }
+            : undefined,
+        // Deep-merge breakpoints
+        breakpoints: child.breakpoints || parent.breakpoints
+            ? { ...parent.breakpoints, ...child.breakpoints }
+            : undefined,
+        // Deep-merge animation
+        animation: child.animation || parent.animation
+            ? {
+                ...parent.animation,
+                ...child.animation,
+                duration: {
+                    ...parent.animation?.duration,
+                    ...child.animation?.duration,
+                },
+                timing: {
+                    ...parent.animation?.timing,
+                    ...child.animation?.timing,
+                },
+            }
+            : undefined,
+        // Deep-merge zIndex
+        zIndex: child.zIndex || parent.zIndex
+            ? { ...parent.zIndex, ...child.zIndex }
+            : undefined,
+        // Deep-merge spacing
+        spacing: child.spacing || parent.spacing
+            ? { ...parent.spacing, ...child.spacing }
+            : undefined,
+        // Deep-merge customVars
+        customVars: child.customVars || parent.customVars
+            ? { ...parent.customVars, ...child.customVars }
+            : undefined,
+        // Deep-merge logo
+        logo: child.logo || parent.logo
+            ? { ...parent.logo, ...child.logo }
+            : undefined,
+    };
+}
+/**
+ * Resolve theme inheritance from a registry of themes.
+ * If a theme has `extends`, the parent is looked up and merged recursively.
+ *
+ * @param theme - The theme to resolve
+ * @param registry - Map of theme name → Theme
+ * @param visited - Set of already-visited names (cycle detection)
+ * @returns The fully resolved theme
+ */
+export function resolveThemeInheritance(theme, registry, visited = new Set()) {
+    if (!theme.extends)
+        return theme;
+    // Cycle detection
+    if (visited.has(theme.name))
+        return theme;
+    visited.add(theme.name);
+    const parent = registry.get(theme.extends);
+    if (!parent)
+        return theme;
+    // Recursively resolve parent first
+    const resolvedParent = resolveThemeInheritance(parent, registry, visited);
+    return mergeThemes(resolvedParent, theme);
+}
+// ============================================================================
+// Mode Resolution
+// ============================================================================
+/**
+ * Resolve the effective mode from a ThemeMode value.
+ * 'auto' checks the system preference (prefers-color-scheme).
+ *
+ * @param mode - The declared mode
+ * @param systemDark - Whether the system prefers dark mode (for SSR or testing)
+ * @returns 'light' or 'dark'
+ */
+export function resolveMode(mode = 'auto', systemDark) {
+    if (mode === 'light' || mode === 'dark')
+        return mode;
+    // 'auto' — check system preference
+    if (systemDark !== undefined)
+        return systemDark ? 'dark' : 'light';
+    if (typeof window !== 'undefined' && window.matchMedia) {
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    return 'light'; // fallback
+}
+// ============================================================================
+// WCAG Contrast Checking (v2.0.7)
+// ============================================================================
+/**
+ * Parse a hex color string to RGB values [0-255].
+ */
+function hexToRGB(hex) {
+    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, g, b) {
+    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, hex2) {
+    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, hex2, level = 'AA', isLargeText = false) {
+    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/dist/theme/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/theme/index.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/utils/debug.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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';
+/**
+ * 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 declare function debugLog(category: DebugCategory, message: string, data?: unknown): void;
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export declare function debugTime(label: string): void;
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export declare function debugTimeEnd(label: string): void;
+export {};

package/dist/utils/debug.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+function isDebugEnabled() {
+    try {
+        const g = typeof globalThis !== 'undefined' && globalThis.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, message, data) {
+    if (!isDebugEnabled())
+        return;
+    if (data !== undefined) {
+        console.log(`[ObjectUI Debug][${category}] ${message}`, data);
+    }
+    else {
+        console.log(`[ObjectUI Debug][${category}] ${message}`);
+    }
+}
+const timers = new Map();
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export function debugTime(label) {
+    if (!isDebugEnabled())
+        return;
+    timers.set(label, performance.now());
+}
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export function debugTimeEnd(label) {
+    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/dist/validation/index.d.ts

@@ -2,7 +2,7 @@
  * @object-ui/core - Validation Module
  *
  * Phase 3.5: Validation engine
- * ObjectStack Spec v0.7.1: Object-level validation
+ * ObjectStack Spec v2.0.1: Object-level validation
  */
 export * from './validation-engine.js';
 export * from './schema-validator.js';

package/dist/validation/index.js

@@ -2,7 +2,7 @@
  * @object-ui/core - Validation Module
  *
  * Phase 3.5: Validation engine
- * ObjectStack Spec v0.7.1: Object-level validation
+ * ObjectStack Spec v2.0.1: Object-level validation
  */
 export * from './validation-engine.js';
 export * from './schema-validator.js';

package/dist/validation/validation-engine.d.ts

@@ -17,11 +17,29 @@
  * @module validation-engine
  * @packageDocumentation
  */
-import type { AdvancedValidationSchema, ValidationContext, AdvancedValidationResult, AdvancedValidationError } from '@object-ui/types';
+import type { AdvancedValidationSchema, ValidationFunction, AsyncValidationFunction, ValidationContext, AdvancedValidationResult, AdvancedValidationError } from '@object-ui/types';
 /**
  * Validation Engine - Executes validation rules
  */
 export declare class ValidationEngine {
+    private customValidators;
+    private customAsyncValidators;
+    /**
+     * Register a custom synchronous validator by name
+     */
+    registerValidator(name: string, fn: ValidationFunction): void;
+    /**
+     * Register a custom asynchronous validator by name
+     */
+    registerAsyncValidator(name: string, fn: AsyncValidationFunction): void;
+    /**
+     * Check if a custom validator is registered
+     */
+    hasValidator(name: string): boolean;
+    /**
+     * Get all registered custom validator names
+     */
+    getValidatorNames(): string[];
     /**
      * Validate a value against validation schema
      */