@shohojdhara/atomix 0.3.6 → 0.3.8

package/src/lib/theme/runtime/index.ts

@@ -7,6 +7,7 @@
 export { ThemeProvider } from './ThemeProvider';
 export { ThemeErrorBoundary } from './ThemeErrorBoundary';
 export { useTheme } from './useTheme';
+export { useThemeTokens } from './useThemeTokens';
 export { ThemeApplicator, getThemeApplicator, applyTheme } from './ThemeApplicator';
 export type { ThemeErrorBoundaryProps } from './ThemeErrorBoundary';
 

package/src/lib/theme/runtime/useTheme.ts

@@ -38,7 +38,7 @@ export function useTheme(): UseThemeReturn {
 
     return {
         theme: context.theme,
-        activeTheme: context.activeTheme,
+        activeTokens: context.activeTokens,
         setTheme: context.setTheme,
         availableThemes: context.availableThemes,
         isLoading: context.isLoading,

package/src/lib/theme/runtime/useThemeTokens.ts

@@ -0,0 +1,122 @@
+import { useCallback } from 'react';
+import { useTheme } from './useTheme';
+import type { DesignTokens } from '../tokens/tokens';
+
+/**
+ * Standardized hook for accessing theme tokens in components
+ *
+ * Provides consistent access to theme values using CSS custom properties
+ * and DesignTokens.
+ */
+type ThemeTokens = {
+    theme: string;
+    activeTokens: DesignTokens | null;
+    getToken: (tokenName: string, fallback?: string) => string;
+    colors: {
+      primary: string;
+      secondary: string;
+      error: string;
+      success: string;
+      warning: string;
+      info: string;
+      light: string;
+      dark: string;
+    };
+    spacing: Record<string, string>;
+    borderRadius: Record<string, string>;
+    typography: {
+      fontFamily: Record<string, string>;
+      fontSize: Record<string, string>;
+      fontWeight: Record<string, string>;
+    };
+    shadows: Record<string, string>;
+    transitions: Record<string, string>;
+  };
+
+export function useThemeTokens(): ThemeTokens {
+  const { theme, activeTokens } = useTheme();
+
+  // Helper function to get CSS variable value
+  const getToken = useCallback((tokenName: string, fallback?: string) => {
+    if (typeof window === 'undefined') return fallback || '';
+
+    const cssVarName = `--atomix-${tokenName}`;
+    const computedStyle = getComputedStyle(document.documentElement);
+    return computedStyle.getPropertyValue(cssVarName).trim() || fallback || '';
+  }, []);
+
+  // Return unified API for accessing theme values
+  // Note: For SSR or direct token access, use activeTokens directly
+  return <ThemeTokens>{
+    theme,
+    activeTokens,
+    getToken,
+    // Commonly used tokens with fallbacks
+    colors: {
+      primary: getToken('primary', '#3b82f6'),
+      secondary: getToken('secondary', '#10b981'),
+      error: getToken('error', '#ef4444'),
+      success: getToken('success', '#22c55e'),
+      warning: getToken('warning', '#eab308'),
+      info: getToken('info', '#3b82f6'),
+      light: getToken('light', '#f9fafb'),
+      dark: getToken('dark', '#111827'),
+    },
+    spacing: {
+      1: getToken('spacing-1', '0.25rem'),
+      2: getToken('spacing-2', '0.5rem'),
+      3: getToken('spacing-3', '0.75rem'),
+      4: getToken('spacing-4', '1rem'),
+      5: getToken('spacing-5', '1.25rem'),
+      6: getToken('spacing-6', '1.5rem'),
+      8: getToken('spacing-8', '2rem'),
+      10: getToken('spacing-10', '2.5rem'),
+      12: getToken('spacing-12', '3rem'),
+      16: getToken('spacing-16', '4rem'),
+      20: getToken('spacing-20', '5rem'),
+    },
+    borderRadius: {
+      sm: getToken('border-radius-sm', '0.25rem'),
+      md: getToken('border-radius-md', '0.5rem'),
+      lg: getToken('border-radius-lg', '0.75rem'),
+      xl: getToken('border-radius-xl', '1rem'),
+      full: getToken('border-radius-full', '9999px'),
+    },
+    typography: {
+      fontFamily: {
+        sans: getToken('font-sans-serif', 'Inter, system-ui, sans-serif'),
+        serif: getToken('font-serif', 'Georgia, serif'),
+        mono: getToken('font-monospace', 'Fira Code, monospace'),
+      },
+      fontSize: {
+        xs: getToken('font-size-xs', '0.75rem'),
+        sm: getToken('font-size-sm', '0.875rem'),
+        md: getToken('font-size-md', '1rem'),
+        lg: getToken('font-size-lg', '1.125rem'),
+        xl: getToken('font-size-xl', '1.25rem'),
+        '2xl': getToken('font-size-2xl', '1.5rem'),
+        '3xl': getToken('font-size-3xl', '1.875rem'),
+        '4xl': getToken('font-size-4xl', '2.25rem'),
+      },
+      fontWeight: {
+        light: getToken('font-weight-light', '300'),
+        normal: getToken('font-weight-normal', '400'),
+        medium: getToken('font-weight-medium', '500'),
+        semibold: getToken('font-weight-semibold', '600'),
+        bold: getToken('font-weight-bold', '700'),
+      },
+    },
+    shadows: {
+      sm: getToken('box-shadow-sm', '0 1px 2px 0 rgba(0, 0, 0, 0.05)'),
+      md: getToken('box-shadow-md', '0 4px 6px -1px rgba(0, 0, 0, 0.1)'),
+      lg: getToken('box-shadow-lg', '0 10px 15px -3px rgba(0, 0, 0, 0.1)'),
+      xl: getToken('box-shadow-xl', '0 20px 25px -5px rgba(0, 0, 0, 0.1)'),
+      inset: getToken('box-shadow-inset', 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)'),
+    },
+    transitions: {
+      fast: getToken('transition-fast', '150ms'),
+      base: getToken('transition-base', '200ms'),
+      slow: getToken('transition-slow', '300ms'),
+    },
+  };
+}

package/src/lib/theme/test/testTheme.ts

@@ -270,7 +270,8 @@ export function createTestThemeObject(): Theme {
  */
 export function generateTestThemeCSSFromObject(): string {
   const theme = createTestThemeObject();
-  return createTheme(theme); // createTheme accepts both formats
+  const tokens = themeToDesignTokens(theme);
+  return createTheme(tokens);
 }
 
 // ============================================================================

package/src/lib/theme/types.ts

@@ -50,8 +50,8 @@ export interface ThemeChangeEvent {
     previousTheme: string | null;
     /** New theme name */
     currentTheme: string;
-    /** Theme object (for JS themes) */
-    themeObject?: Theme | null;
+    /** DesignTokens if using tokens-based theme */
+    tokens?: import('./tokens').DesignTokens | null;
     /** Timestamp of the change */
     timestamp: number;
     /** Whether the change was from user action or system */
@@ -126,7 +126,7 @@ export interface UseThemeOptions {
     /** Custom storage key */
     storageKey?: string;
     /** Callback when theme changes */
-    onChange?: (theme: string | Theme | import('./tokens').DesignTokens) => void;
+    onChange?: (theme: string | import('./tokens').DesignTokens) => void;
 }
 
 /**
@@ -135,10 +135,10 @@ export interface UseThemeOptions {
 export interface UseThemeReturn {
     /** Current theme name */
     theme: string;
-    /** Current active theme object (for JS themes) */
-    activeTheme: Theme | null;
-    /** Function to change theme (supports string, Theme, or DesignTokens) */
-    setTheme: (theme: string | Theme | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Current active DesignTokens (if using tokens-based theme) */
+    activeTokens: import('./tokens').DesignTokens | null;
+    /** Function to change theme (supports string or DesignTokens) */
+    setTheme: (theme: string | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
     availableThemes: ThemeMetadata[];
     /** Whether a theme is currently loading */
@@ -213,8 +213,8 @@ export interface ThemeComponentOverrides {
 export interface ThemeProviderProps {
     /** Child components */
     children: React.ReactNode;
-    /** Default theme */
-    defaultTheme?: string | Theme;
+    /** Default theme (string name or DesignTokens) */
+    defaultTheme?: string | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>;
     /** Available themes */
     themes?: Record<string, ThemeMetadata>;
     /** Base path for theme CSS */
@@ -234,7 +234,7 @@ export interface ThemeProviderProps {
     /** Use minified CSS */
     useMinified?: boolean;
     /** Callback when theme changes */
-    onThemeChange?: (theme: string | Theme | import('./tokens').DesignTokens) => void;
+    onThemeChange?: (theme: string | import('./tokens').DesignTokens) => void;
     /** Callback on error */
     onError?: (error: Error, themeName: string) => void;
 }
@@ -245,10 +245,10 @@ export interface ThemeProviderProps {
 export interface ThemeContextValue {
     /** Current theme name */
     theme: string;
-    /** Current active theme object (for JS themes) */
-    activeTheme: Theme | null;
-    /** Set theme function (supports string, Theme, or DesignTokens) */
-    setTheme: (theme: string | Theme | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
+    /** Current active DesignTokens (if using tokens-based theme) */
+    activeTokens: import('./tokens').DesignTokens | null;
+    /** Set theme function (supports string or DesignTokens) */
+    setTheme: (theme: string | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
     availableThemes: ThemeMetadata[];
     /** Loading state */

package/src/lib/theme/utils/componentTheming.ts

@@ -0,0 +1,140 @@
+/**
+ * Component Theming Utilities
+ * 
+ * Provides consistent patterns for applying theme values to components
+ * using DesignTokens and CSS variables
+ */
+
+import type { DesignTokens } from '../tokens/tokens';
+
+export interface ComponentThemeOptions {
+  component: string;
+  variant?: string;
+  size?: string;
+  tokens?: Partial<DesignTokens>;
+}
+
+/**
+ * Get a theme value for a specific component using CSS variables
+ * This ensures all components access theme values consistently
+ */
+export function getComponentThemeValue(
+  component: string,
+  property: string,
+  variant?: string,
+  size?: string
+): string {
+  // Build CSS variable name following consistent pattern
+  const parts = ['atomix', component];
+  
+  if (variant) {
+    parts.push(variant);
+  }
+  
+  if (size) {
+    parts.push(size);
+  }
+  
+  parts.push(property);
+  
+  const cssVarName = `--${parts.join('-')}`;
+  const fallbackVarName = `--atomix-${property}`;
+  
+  // Return CSS variable reference with fallback
+  return `var(${cssVarName}, var(${fallbackVarName}, initial))`;
+}
+
+/**
+ * Generate component-specific CSS variables from DesignTokens
+ */
+export function generateComponentCSSVars(
+  component: string,
+  tokens?: Partial<DesignTokens>,
+  variant?: string,
+  size?: string
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+  
+  if (!tokens) return vars;
+  
+  const prefixParts = ['atomix', component];
+  
+  if (variant) {
+    prefixParts.push(variant);
+  }
+  
+  if (size) {
+    prefixParts.push(size);
+  }
+  
+  const prefix = prefixParts.join('-');
+  
+  // Map common DesignTokens to component-specific CSS variables
+  if (tokens.primary) {
+    vars[`--${prefix}-color`] = tokens.primary;
+  }
+  if (tokens['primary-9']) {
+    vars[`--${prefix}-color-hover`] = tokens['primary-9'];
+  }
+  if (tokens['body-color']) {
+    vars[`--${prefix}-color-disabled`] = tokens['body-color'];
+  }
+  
+  if (tokens['body-font-family']) {
+    vars[`--${prefix}-font-family`] = tokens['body-font-family'];
+  }
+  if (tokens['body-font-size']) {
+    vars[`--${prefix}-font-size`] = tokens['body-font-size'];
+  }
+  
+  if (tokens['spacing-1']) {
+    vars[`--${prefix}-spacing-sm`] = tokens['spacing-1'];
+  }
+  if (tokens['spacing-2']) {
+    vars[`--${prefix}-spacing-md`] = tokens['spacing-2'];
+  }
+  if (tokens['spacing-4']) {
+    vars[`--${prefix}-spacing-lg`] = tokens['spacing-4'];
+  }
+  
+  return vars;
+}
+
+/**
+ * Apply consistent theme to component style object using DesignTokens
+ */
+export function applyComponentTheme(
+  component: string,
+  style: React.CSSProperties = {},
+  variant?: string,
+  size?: string,
+  tokens?: Partial<DesignTokens>
+): React.CSSProperties {
+  // If no tokens provided, return original style
+  if (!tokens) {
+    return style;
+  }
+  
+  // Generate component-specific CSS variables
+  const componentVars = generateComponentCSSVars(component, tokens, variant, size);
+  
+  // Merge with existing style
+  return {
+    ...componentVars,
+    ...style,
+  };
+}
+
+/**
+ * Create a hook for consistent component theming
+ */
+export function useComponentTheme(
+  component: string,
+  variant?: string,
+  size?: string,
+  tokens?: Partial<DesignTokens>
+): (property: string) => string {
+  return (property: string) => {
+    return getComponentThemeValue(component, property, variant, size);
+  };
+}

package/src/lib/theme/utils/domUtils.ts

@@ -7,6 +7,7 @@
 
 import type { ThemeMetadata, ThemeValidationResult } from '../types';
 import { THEME_LINK_ID_PREFIX } from '../constants/constants';
+import { ThemeError, ThemeErrorCode } from '../errors/errors';
 
 /**
  * Check if code is running in a browser environment
@@ -29,6 +30,20 @@ export const getThemeLinkId = (themeName: string): string => {
     return `${THEME_LINK_ID_PREFIX}${themeName}`;
 };
 
+/**
+ * Sanitize path to prevent path injection attacks
+ * 
+ * @param path - Path to sanitize
+ * @returns Sanitized path
+ */
+const sanitizePath = (path: string): string => {
+    return path
+        .replace(/[<>"']/g, '') // Remove dangerous characters
+        .replace(/\.\./g, '') // Remove path traversal attempts
+        .replace(/\/+/g, '/') // Normalize multiple slashes
+        .replace(/^\/+|\/+$/g, ''); // Trim leading/trailing slashes
+};
+
 /**
  * Build the CSS file path for a theme
  * 
@@ -37,6 +52,7 @@ export const getThemeLinkId = (themeName: string): string => {
  * @param useMinified - Whether to use minified CSS
  * @param cdnPath - Optional CDN path
  * @returns Full path to the theme CSS file
+ * @throws Error if theme name is invalid
  */
 export const buildThemePath = (
     themeName: string,
@@ -46,21 +62,24 @@ export const buildThemePath = (
 ): string => {
     // Validate theme name to prevent path injection
     if (!isValidThemeName(themeName)) {
-        throw new Error(`Invalid theme name: "${themeName}". Theme names must be lowercase alphanumeric with hyphens.`);
+        throw new ThemeError(
+            `Invalid theme name: "${themeName}". Theme names must be lowercase alphanumeric with hyphens (e.g., "my-theme").`,
+            ThemeErrorCode.INVALID_THEME_NAME,
+            { themeName, pattern: /^[a-z0-9]+(-[a-z0-9]+)*$/ }
+        );
     }
 
     const extension = useMinified ? '.min.css' : '.css';
     const fileName = `${themeName}${extension}`;
 
     if (cdnPath) {
-        // Validate CDN path doesn't contain dangerous characters
-        const cleanCdnPath = cdnPath.replace(/[<>"']/g, '');
+        // Sanitize CDN path to prevent path injection
+        const cleanCdnPath = sanitizePath(cdnPath);
         return `${cleanCdnPath}/${fileName}`;
     }
 
-    // Ensure basePath doesn't end with slash and fileName doesn't start with slash
-    // Also sanitize basePath to prevent path injection
-    const cleanBasePath = basePath.replace(/\/$/, '').replace(/[<>"']/g, '');
+    // Sanitize basePath to prevent path injection
+    const cleanBasePath = sanitizePath(basePath);
     const cleanFileName = fileName.replace(/^\//, '');
 
     return `${cleanBasePath}/${cleanFileName}`;
@@ -110,7 +129,11 @@ export const loadThemeCSS = (
         link.onerror = () => {
             // Remove failed link element
             link.remove();
-            reject(new Error(`Failed to load theme CSS: ${fullPath}`));
+            reject(new ThemeError(
+                `Failed to load theme CSS from: ${fullPath}. Please check that the file exists and is accessible.`,
+                ThemeErrorCode.THEME_LOAD_FAILED,
+                { fullPath, linkId }
+            ));
         };
 
         // Append to head
@@ -166,8 +189,10 @@ export const applyThemeAttributes = (
         return;
     }
 
-    // Set data attribute on body
-    document.body.setAttribute(dataAttribute, themeName);
+    // Set data attribute on body (with null check)
+    if (document.body) {
+        document.body.setAttribute(dataAttribute, themeName);
+    }
 
     // Also set on documentElement for broader compatibility
     document.documentElement.setAttribute(dataAttribute, themeName);
@@ -185,7 +210,12 @@ export const removeThemeAttributes = (
         return;
     }
 
-    document.body.removeAttribute(dataAttribute);
+    // Remove from body (with null check)
+    if (document.body) {
+        document.body.removeAttribute(dataAttribute);
+    }
+
+    // Remove from documentElement
     document.documentElement.removeAttribute(dataAttribute);
 };
 
@@ -202,8 +232,10 @@ export const getCurrentThemeFromDOM = (
         return null;
     }
 
-    return document.body.getAttribute(dataAttribute) ||
-        document.documentElement.getAttribute(dataAttribute);
+    // Add null checks for SSR safety
+    const bodyTheme = document.body?.getAttribute(dataAttribute);
+    const htmlTheme = document.documentElement?.getAttribute(dataAttribute);
+    return bodyTheme || htmlTheme || null;
 };
 
 /**
@@ -377,15 +409,15 @@ export const createLocalStorageAdapter = () => {
  * 
  * @param func - Function to debounce
  * @param wait - Wait time in milliseconds
- * @returns Debounced function
+ * @returns Debounced function with cancel method
  */
 export const debounce = <T extends (...args: any[]) => any>(
     func: T,
     wait: number
-): ((...args: Parameters<T>) => void) => {
+): ((...args: Parameters<T>) => void) & { cancel: () => void } => {
     let timeout: ReturnType<typeof setTimeout> | null = null;
 
-    return function executedFunction(...args: Parameters<T>) {
+    const debounced = function executedFunction(...args: Parameters<T>) {
         const later = () => {
             timeout = null;
             func(...args);
@@ -396,4 +428,14 @@ export const debounce = <T extends (...args: any[]) => any>(
         }
         timeout = setTimeout(later, wait);
     };
+
+    // Add cancel method for cleanup
+    debounced.cancel = () => {
+        if (timeout !== null) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+    };
+
+    return debounced;
 };

package/src/lib/theme/utils/injectCSS.ts

@@ -34,7 +34,6 @@ export function injectCSS(
   id: string = 'atomix-theme'
 ): void {
   if (!isBrowser()) {
-    console.warn('injectCSS: Not in browser environment, CSS not injected');
     return;
   }
 

package/src/lib/theme/utils/naming.ts

@@ -0,0 +1,100 @@
+/**
+ * Naming Utilities
+ * 
+ * Provides consistent naming conventions across the theme system
+ */
+
+export interface NamingOptions {
+  prefix?: string;
+  component?: string;
+  variant?: string;
+  state?: string;
+}
+
+/**
+ * Generate consistent CSS class names following BEM methodology
+ */
+export function generateClassName(block: string, element?: string, modifiers?: Record<string, boolean | string>): string {
+  let className = block;
+  
+  if (element) {
+    className += `__${element}`;
+  }
+  
+  if (modifiers) {
+    Object.entries(modifiers).forEach(([key, value]) => {
+      if (value) {
+        className += `--${key}`;
+        if (typeof value === 'string' && value !== key) {
+          className += `-${value}`;
+        }
+      }
+    });
+  }
+  
+  return className;
+}
+
+/**
+ * Generate consistent CSS variable names
+ */
+export function generateCSSVariableName(property: string, options: NamingOptions = {}): string {
+  const { prefix = 'atomix', component, variant, state } = options;
+  
+  const parts = [prefix];
+  
+  if (component) {
+    parts.push(component);
+  }
+  
+  if (variant) {
+    parts.push(variant);
+  }
+  
+  if (state) {
+    parts.push(state);
+  }
+  
+  parts.push(property);
+  
+  return `--${parts.join('-')}`;
+}
+
+/**
+ * Normalize theme tokens to consistent naming convention
+ */
+export function normalizeThemeTokens(tokens: Record<string, any>): Record<string, any> {
+  const normalized: Record<string, any> = {};
+  
+  for (const [key, value] of Object.entries(tokens)) {
+    if (typeof value === 'object' && value !== null) {
+      // Recursively normalize nested objects
+      normalized[key] = normalizeThemeTokens(value);
+    } else {
+      // Apply consistent naming transformation
+      normalized[key] = value;
+    }
+  }
+  
+  return normalized;
+}
+
+/**
+ * Convert camelCase to kebab-case for CSS custom properties
+ */
+export function camelToKebab(str: string): string {
+  return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+
+/**
+ * Convert theme property to CSS variable name
+ */
+export function themePropertyToCSSVar(propertyPath: string, prefix: string = 'atomix'): string {
+  // Convert nested property paths to kebab-case
+  const path = propertyPath
+    .split('.')
+    .map(part => camelToKebab(part))
+    .join('-');
+  
+  return `--${prefix}-${path}`;
+}

package/src/lib/theme/utils/themeHelpers.ts

@@ -1,34 +1,10 @@
 /**
  * Theme Helper Functions
  * 
- * Utility functions for working with themes and DesignTokens
+ * Utility functions for working with DesignTokens
  */
 
-import type { Theme } from '../types';
 import type { DesignTokens } from '../tokens/tokens';
-import { createDesignTokensFromTheme } from '../adapters/themeAdapter';
-
-/**
- * Get DesignTokens from current theme
- * 
- * Converts a Theme object to DesignTokens. Useful when you need to
- * work with DesignTokens but have a Theme object.
- * 
- * @param theme - Theme object to convert
- * @returns DesignTokens object
- * 
- * @example
- * ```typescript
- * // If you have a Theme object, convert it to DesignTokens
- * const tokens = getDesignTokensFromTheme(theme);
- * // Now you can use tokens with unified theme system
- * const css = createTheme(tokens);
- * ```
- */
-export function getDesignTokensFromTheme(theme: Theme | null): DesignTokens | null {
-  if (!theme) return null;
-  return createDesignTokensFromTheme(theme);
-}
 
 /**
  * Check if a value is DesignTokens
@@ -62,17 +38,3 @@ export function isDesignTokens(value: unknown): value is DesignTokens {
   return hasDesignTokenKeys;
 }
 
-/**
- * Check if a value is a Theme object
- * 
- * Type guard to check if an object is a Theme.
- * 
- * @param value - Value to check
- * @returns True if value is Theme
- */
-export function isThemeObject(value: unknown): value is Theme {
-  if (!value || typeof value !== 'object') return false;
-  const obj = value as Record<string, unknown>;
-  return '__isJSTheme' in obj || ('palette' in obj && 'typography' in obj);
-}
-