shru-design-system 0.1.5 → 0.1.8

package/scripts/themeConfig.js

@@ -0,0 +1,214 @@
+/**
+ * Theme Configuration
+ * Registry of all available themes organized by category
+ *
+ * Base themes are defined here. Additional themes can be discovered dynamically
+ * by scanning the /tokens/themes/ directory structure.
+ */
+
+/**
+ * Centralized theme category order
+ * Used everywhere to ensure consistency
+ * This is the SINGLE SOURCE OF TRUTH for category order
+ * Custom category is included but handled specially (optional, user-created files)
+ * 
+ * ⚠️ IF YOU UPDATE THIS, ALSO UPDATE:
+ * 1. src/themes/themeConfig.ts - THEME_CATEGORY_ORDER (TypeScript source)
+ * 2. scripts/apply-theme-sync.js - THEME_CATEGORY_ORDER constant (standalone script, can't import)
+ */
+export const THEME_CATEGORY_ORDER = ['color', 'typography', 'shape', 'density', 'animation', 'custom'];
+
+// Base theme categories (always available)
+export const baseThemeCategories = {
+    color: {
+        name: 'Color',
+        order: 1.0,
+        themes: {
+            white: {
+                name: 'White',
+                file: 'color/white.json',
+                icon: '🎨',
+                description: 'Light theme with white background'
+            },
+            dark: {
+                name: 'Dark',
+                file: 'color/dark.json',
+                icon: '🌙',
+                description: 'Dark theme with dark background'
+            }
+        }
+    },
+    typography: {
+        name: 'Typography',
+        order: 2.0,
+        themes: {
+            sans: {
+                name: 'Sans',
+                file: 'typography/sans.json',
+                icon: '📝',
+                description: 'Sans-serif font family'
+            },
+            serif: {
+                name: 'Serif',
+                file: 'typography/serif.json',
+                icon: '📖',
+                description: 'Serif font family'
+            }
+        }
+    },
+    shape: {
+        name: 'Shape',
+        order: 3.0,
+        themes: {
+            smooth: {
+                name: 'Smooth',
+                file: 'shape/smooth.json',
+                icon: '🔲',
+                description: 'Smooth rounded corners'
+            },
+            sharp: {
+                name: 'Sharp',
+                file: 'shape/sharp.json',
+                icon: '⬜',
+                description: 'Sharp square corners'
+            }
+        }
+    },
+    density: {
+        name: 'Density',
+        order: 4.0,
+        themes: {
+            comfortable: {
+                name: 'Comfortable',
+                file: 'density/comfortable.json',
+                icon: '📏',
+                description: 'Comfortable spacing'
+            },
+            compact: {
+                name: 'Compact',
+                file: 'density/compact.json',
+                icon: '📐',
+                description: 'Compact spacing'
+            }
+        }
+    },
+    animation: {
+        name: 'Animation',
+        order: 5.0,
+        themes: {
+            gentle: {
+                name: 'Gentle',
+                file: 'animation/gentle.json',
+                icon: '✨',
+                description: 'Gentle animations'
+            },
+            brisk: {
+                name: 'Brisk',
+                file: 'animation/brisk.json',
+                icon: '⚡',
+                description: 'Fast, brisk animations'
+            }
+        }
+    },
+    // Custom themes are not included in base config
+    // They should be discovered dynamically or registered by users
+    // Users can add custom themes by creating files in /tokens/themes/custom/
+    // and registering them using registerTheme()
+};
+// Cache for dynamically discovered themes
+let discoveredThemesCache = null;
+/**
+ * Discover themes by scanning token directory structure
+ * Scans /tokens/themes/ to find all available theme files
+ */
+export async function discoverThemes() {
+    if (discoveredThemesCache) {
+        return discoveredThemesCache;
+    }
+    const discovered = JSON.parse(JSON.stringify(baseThemeCategories));
+    try {
+        // Get base path for tokens
+        const tokensBase = typeof window !== 'undefined' && window.__THEME_TOKENS_BASE__
+            ? window.__THEME_TOKENS_BASE__
+            : '/tokens';
+        // Known categories from base config
+        const knownCategories = Object.keys(baseThemeCategories);
+        // For each category, try to discover additional themes
+        for (const category of knownCategories) {
+            const categoryPath = `${tokensBase}/themes/${category}`;
+            // Try to fetch an index or scan common theme files
+            // Since we can't list directories via fetch, we'll try common patterns
+            // Users can add themes by following the naming convention
+            // For now, we'll rely on users to add themes to the config
+            // But we can validate that theme files exist when requested
+        }
+        discoveredThemesCache = discovered;
+        return discovered;
+    }
+    catch (error) {
+        // Only log in debug mode
+        if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+            console.warn('Error discovering themes:', error);
+        }
+        return baseThemeCategories;
+    }
+}
+/**
+ * Register a custom theme dynamically
+ * Allows users to add themes without modifying the base config
+ */
+export function registerTheme(category, themeId, metadata) {
+    if (!discoveredThemesCache) {
+        discoveredThemesCache = JSON.parse(JSON.stringify(baseThemeCategories));
+    }
+    // TypeScript now knows discoveredThemesCache is not null after the check above
+    const cache = discoveredThemesCache;
+    // Create category if it doesn't exist
+    if (!cache[category]) {
+        cache[category] = {
+            name: category.charAt(0).toUpperCase() + category.slice(1),
+            order: 99, // Custom categories get high order
+            themes: {}
+        };
+    }
+    // Register the theme
+    cache[category].themes[themeId] = {
+        name: metadata.name,
+        file: metadata.file,
+        icon: metadata.icon || '🎨',
+        description: metadata.description || ''
+    };
+    return cache;
+}
+/**
+ * Get merged theme categories (base + discovered)
+ */
+export async function getThemeCategories() {
+    return await discoverThemes();
+}
+// For backward compatibility, export baseThemeCategories as themeCategories
+export const themeCategories = baseThemeCategories;
+/**
+ * Get theme file path
+ */
+export function getThemeFilePath(category, themeId) {
+    const categories = discoveredThemesCache || baseThemeCategories;
+    const theme = categories[category]?.themes[themeId];
+    if (!theme)
+        return null;
+    return `/tokens/themes/${theme.file}`;
+}
+/**
+ * Get all themes for a category
+ */
+export async function getThemesForCategory(category) {
+    const categories = await getThemeCategories();
+    return categories[category]?.themes || {};
+}
+/**
+ * Get theme by ID
+ */
+export async function getTheme(category, themeId) {
+    const categories = await getThemeCategories();
+    return categories[category]?.themes[themeId] || null;
+}

package/scripts/themeUtils.js

@@ -0,0 +1,452 @@
+/**
+ * Theme Utilities
+ * Pure utility functions for theme management
+ * Note: generateAndApplyTheme has side effects (modifies DOM) but is the main theme application utility
+ */
+import { getThemeCategories, THEME_CATEGORY_ORDER } from './themeConfig';
+/**
+ * Generate theme combination name
+ */
+export function getThemeName(selectedThemes) {
+    const parts = [];
+    if (selectedThemes.color)
+        parts.push(selectedThemes.color);
+    if (selectedThemes.typography)
+        parts.push(selectedThemes.typography);
+    if (selectedThemes.shape)
+        parts.push(selectedThemes.shape);
+    if (selectedThemes.density)
+        parts.push(selectedThemes.density);
+    if (selectedThemes.animation)
+        parts.push(selectedThemes.animation);
+    return parts.length > 0 ? parts.join('-') : 'default';
+}
+/**
+ * Validate theme selection
+ */
+export function validateThemeSelection(selectedThemes, themeCategories) {
+    const errors = [];
+    for (const [category, themeId] of Object.entries(selectedThemes)) {
+        if (!themeId)
+            continue;
+        const categoryConfig = themeCategories[category];
+        if (!categoryConfig) {
+            errors.push(`Unknown category: ${category}`);
+            continue;
+        }
+        const theme = categoryConfig.themes[themeId];
+        if (!theme) {
+            errors.push(`Theme ${themeId} not found in category ${category}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Get default theme selections
+ * 
+ * ⚠️ IF YOU UPDATE THIS, ALSO UPDATE:
+ * 1. src/themes/themeUtils.ts - getDefaultThemes() function (TypeScript source)
+ * 2. scripts/apply-theme-sync.js - DEFAULT_THEMES constant (standalone script, can't import)
+ */
+export function getDefaultThemes() {
+    return {
+        color: 'white',
+        typography: 'sans',
+        shape: 'smooth',
+        density: 'comfortable',
+        animation: 'gentle'
+    };
+}
+/**
+ * Deep clone object
+ */
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/**
+ * Check if value is an object
+ */
+function isObject(item) {
+    return item && typeof item === 'object' && !Array.isArray(item);
+}
+/**
+ * Deep merge objects
+ */
+export function deepMerge(target, source) {
+    const output = { ...target };
+    if (isObject(target) && isObject(source)) {
+        Object.keys(source).forEach(key => {
+            if (isObject(source[key])) {
+                if (!(key in target)) {
+                    Object.assign(output, { [key]: source[key] });
+                }
+                else {
+                    output[key] = deepMerge(target[key], source[key]);
+                }
+            }
+            else {
+                Object.assign(output, { [key]: source[key] });
+            }
+        });
+    }
+    return output;
+}
+// Cache for loaded JSON files
+const tokenCache = new Map();
+/**
+ * Load JSON file with caching
+ */
+export async function loadTokenFile(path) {
+    if (tokenCache.has(path)) {
+        return deepClone(tokenCache.get(path));
+    }
+    try {
+        const response = await fetch(path);
+        if (!response.ok) {
+            // 404 means file doesn't exist - return null instead of throwing
+            if (response.status === 404) {
+                return null;
+            }
+            throw new Error(`Failed to load ${path}: ${response.statusText}`);
+        }
+        const contentType = response.headers.get('content-type');
+        // Check if response is actually JSON (not HTML error page)
+        if (!contentType || !contentType.includes('application/json')) {
+            // Likely got HTML error page instead of JSON
+            return null;
+        }
+        const data = await response.json();
+        tokenCache.set(path, data);
+        return deepClone(data);
+    }
+    catch (error) {
+        // Only log errors in debug mode
+        if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+            console.warn(`Error loading token file ${path}:`, error);
+        }
+        // Return null instead of throwing - allows theme to continue with other files
+        return null;
+    }
+}
+/**
+ * Resolve token references
+ * {palette.blue.500} → actual color value
+ */
+function resolveReferences(tokens, palette) {
+    const resolved = JSON.parse(JSON.stringify(tokens));
+    function resolveValue(value) {
+        if (typeof value !== 'string')
+            return value;
+        // Match {path.to.token} pattern
+        const match = value.match(/^\{([^}]+)\}$/);
+        if (!match)
+            return value;
+        const path = match[1].split('.');
+        let current = { palette, ...resolved };
+        for (const key of path) {
+            if (current && typeof current === 'object' && key in current) {
+                current = current[key];
+            }
+            else {
+                // Token reference not found - return original value
+                // Only warn in debug mode
+                if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+                    console.warn(`Token reference not found: {${match[1]}}`);
+                }
+                return value; // Return original if not found
+            }
+        }
+        return typeof current === 'string' ? current : value;
+    }
+    function traverse(obj) {
+        for (const key in obj) {
+            if (typeof obj[key] === 'object' && obj[key] !== null) {
+                traverse(obj[key]);
+            }
+            else {
+                obj[key] = resolveValue(obj[key]);
+            }
+        }
+    }
+    traverse(resolved);
+    return resolved;
+}
+/**
+ * Convert hex color to HSL format (without hsl() wrapper)
+ * Returns format: "h s% l%" for use with hsl(var(--color))
+ */
+function hexToHSL(hex) {
+    // Remove # if present
+    hex = hex.replace('#', '');
+    // Parse RGB
+    const r = parseInt(hex.substring(0, 2), 16) / 255;
+    const g = parseInt(hex.substring(2, 4), 16) / 255;
+    const b = parseInt(hex.substring(4, 6), 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;
+        }
+    }
+    h = Math.round(h * 360);
+    s = Math.round(s * 100);
+    const lPercent = Math.round(l * 100);
+    return `${h} ${s}% ${lPercent}%`;
+}
+/**
+ * Check if a string is a hex color
+ */
+function isHexColor(value) {
+    return /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(value);
+}
+/**
+ * Flatten nested object to CSS variables
+ * Maps token structure to CSS variable naming:
+ * - color.primary → --primary (semantic colors are flat)
+ * - font.body → --font-body
+ * - radius.button → --radius-button
+ * - font.body → --font-body
+ * - spacing.component.md → --spacing-component-md
+ */
+function flattenToCSS(tokens, prefix = '', result = {}, isColorContext = false) {
+    for (const key in tokens) {
+        const value = tokens[key];
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Token files are already in correct structure (no nested typography/shape wrappers)
+            const enteringColor = key === 'color' && prefix === '';
+            const inColorContext = isColorContext || enteringColor;
+            if (enteringColor) {
+                // When entering color object, flatten without "color-" prefix
+                flattenToCSS(value, '', result, true);
+            }
+            else if (inColorContext) {
+                // Already in color context, continue with empty prefix
+                flattenToCSS(value, '', result, true);
+            }
+            else {
+                // For all other tokens, use simple prefix-based flattening
+                // font.body → --font-body, radius.button → --radius-button, spacing.component.md → --spacing-component-md
+                const newPrefix = prefix ? `${prefix}-${key}` : key;
+                flattenToCSS(value, newPrefix, result, false);
+            }
+        }
+        else {
+            // Generate CSS variable name
+            let cssKey;
+            if (isColorContext || (prefix === '' && key === 'color')) {
+                // Semantic colors: --primary, --background, etc. (no "color-" prefix)
+                cssKey = `--${key}`;
+            }
+            else if (prefix === '') {
+                // Top-level tokens (non-color)
+                cssKey = `--${key}`;
+            }
+            else {
+                // Nested tokens: --font-body, --radius-button, --spacing-component-md, etc.
+                cssKey = `--${prefix}-${key}`;
+            }
+            // Convert hex colors to HSL format for Tailwind compatibility
+            let finalValue = value;
+            if (isColorContext && typeof value === 'string' && isHexColor(value)) {
+                finalValue = hexToHSL(value);
+            }
+            result[cssKey] = finalValue;
+        }
+    }
+    return result;
+}
+/**
+ * Map theme variables to Tailwind-compatible CSS variables
+ * This function automatically passes through ALL CSS variables
+ * and only adds convenience mappings for Tailwind-specific needs
+ */
+function mapToTailwindVars(cssVars) {
+    // Start with all generated variables - they're all valid CSS variables
+    const mapped = { ...cssVars };
+    // Only add convenience mappings for Tailwind's expected variable names
+    // These are optional - the actual variables are already in the map
+    // Map radius-button to --radius for Tailwind's rounded-* utilities
+    if (cssVars['--radius-button'] && !cssVars['--radius']) {
+        mapped['--radius'] = cssVars['--radius-button'];
+    }
+    // Map radius-card to --radius-lg for larger rounded corners
+    if (cssVars['--radius-card'] && !cssVars['--radius-lg']) {
+        mapped['--radius-lg'] = cssVars['--radius-card'];
+    }
+    // Map font-body to --font-sans for Tailwind's font-sans utility
+    if (cssVars['--font-body'] && !cssVars['--font-sans']) {
+        mapped['--font-sans'] = cssVars['--font-body'];
+    }
+    // Map spacing-base or spacing-component-md to --spacing for convenience
+    if (cssVars['--spacing-base'] && !cssVars['--spacing']) {
+        mapped['--spacing'] = cssVars['--spacing-base'];
+    }
+    else if (cssVars['--spacing-component-md'] && !cssVars['--spacing']) {
+        mapped['--spacing'] = cssVars['--spacing-component-md'];
+    }
+    return mapped;
+}
+/**
+ * Generate CSS string from CSS variables
+ */
+function generateCSSString(cssVars) {
+    const mappedVars = mapToTailwindVars(cssVars);
+    const vars = Object.entries(mappedVars)
+        .sort(([a], [b]) => a.localeCompare(b)) // Sort alphabetically for easier debugging
+        .map(([key, value]) => `  ${key}: ${value};`)
+        .join('\n');
+    // Debug mode: log all CSS variables in development
+    if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+        console.group('🎨 Design System CSS Variables');
+        console.table(mappedVars);
+        console.log('Total variables:', Object.keys(mappedVars).length);
+        console.groupEnd();
+    }
+    return `:root {\n${vars}\n}`;
+}
+/**
+ * Apply CSS to DOM
+ */
+function applyThemeCSS(css) {
+    let styleTag = document.getElementById('dynamic-theme');
+    if (!styleTag) {
+        styleTag = document.createElement('style');
+        styleTag.id = 'dynamic-theme';
+        document.head.appendChild(styleTag);
+    }
+    styleTag.textContent = css;
+}
+/**
+ * Debug helper: Enable debug mode to see all CSS variables in console
+ * Call this in browser console: window.__DESIGN_SYSTEM_DEBUG__ = true
+ */
+export function enableDebugMode() {
+    if (typeof window !== 'undefined') {
+        window.__DESIGN_SYSTEM_DEBUG__ = true;
+        console.log('🔍 Design System debug mode enabled');
+        console.log('CSS variables will be logged when themes change');
+    }
+}
+/**
+ * Debug helper: Get all current CSS variables
+ */
+export function getCurrentCSSVariables() {
+    if (typeof window === 'undefined')
+        return {};
+    const styleTag = document.getElementById('dynamic-theme');
+    if (!styleTag)
+        return {};
+    const cssText = styleTag.textContent || '';
+    const vars = {};
+    const matches = cssText.matchAll(/--([^:]+):\s*([^;]+);/g);
+    for (const match of matches) {
+        vars[`--${match[1].trim()}`] = match[2].trim();
+    }
+    return vars;
+}
+/**
+ * Generate and apply theme
+ * Main function that composes everything
+ */
+export async function generateAndApplyTheme(selectedThemes = {}) {
+    try {
+        // Get theme categories (with dynamic discovery)
+        const themeCategories = await getThemeCategories();
+        // Validate theme selection (but be lenient with custom themes - they might not exist yet)
+        const validation = validateThemeSelection(selectedThemes, themeCategories);
+        if (!validation.valid) {
+            // Filter out custom theme errors - custom themes are optional
+            const nonCustomErrors = validation.errors.filter(err => !err.includes('custom'));
+            if (nonCustomErrors.length > 0) {
+                // Only log in debug mode
+                if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+                    console.error('Invalid theme selection:', nonCustomErrors);
+                }
+                throw new Error(`Invalid theme selection: ${nonCustomErrors.join(', ')}`);
+            }
+            // If only custom theme errors, just warn and continue
+            if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+                console.warn('Custom theme files not found, continuing without them:', validation.errors);
+            }
+        }
+        // 1. Load base tokens
+        const base = await loadTokenFile('/tokens/base.json');
+        if (!base) {
+            throw new Error('Failed to load base tokens from /tokens/base.json');
+        }
+        // 2. Load palette
+        const palettes = await loadTokenFile('/tokens/palettes.json');
+        if (!palettes || !palettes.palette) {
+            throw new Error('Failed to load palette from /tokens/palettes.json');
+        }
+        const palette = palettes.palette;
+        // 3. Deep merge: base → palette
+        let merged = deepMerge(base, { palette });
+        // 4. Load and merge category themes in order (includes custom, use centralized order from themeConfig.js)
+        for (const category of THEME_CATEGORY_ORDER) {
+            const themeId = selectedThemes[category];
+            if (!themeId)
+                continue;
+            const themePath = `/tokens/themes/${category}/${themeId}.json`;
+            const themeData = await loadTokenFile(themePath);
+            // Only merge if theme data was successfully loaded
+            if (themeData) {
+                merged = deepMerge(merged, themeData);
+            }
+            else {
+                // For custom themes, silently skip if not found (user-created, optional)
+                // For other categories, warn in debug mode
+                if (category !== 'custom' && typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+                    console.warn(`Theme file not found: ${themePath}`);
+                }
+                else if (category === 'custom' && typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+                    console.warn(`Custom theme file not found: ${themePath} (this is normal if you haven't created it yet)`);
+                }
+            }
+        }
+        // 6. Resolve references
+        const resolved = resolveReferences(merged, palette);
+        // 7. Flatten to CSS variables
+        const cssVars = flattenToCSS(resolved);
+        // 8. Generate CSS string
+        const css = generateCSSString(cssVars);
+        // 9. Apply to DOM
+        if (typeof document !== 'undefined') {
+            applyThemeCSS(css);
+            // Debug: expose CSS variables to window for inspection
+            if (window.__DESIGN_SYSTEM_DEBUG__) {
+                window.__DESIGN_SYSTEM_VARS__ = cssVars;
+                console.log('💡 Access CSS variables via: window.__DESIGN_SYSTEM_VARS__');
+            }
+        }
+        return {
+            success: true,
+            themeName: getThemeName(selectedThemes),
+            cssVars
+        };
+    }
+    catch (error) {
+        // Only log in debug mode
+        if (typeof window !== 'undefined' && window.__DESIGN_SYSTEM_DEBUG__) {
+            console.error('Error generating theme:', error);
+        }
+        throw error;
+    }
+}