@shohojdhara/atomix 0.3.6 → 0.3.7

package/dist/theme.d.ts

@@ -302,7 +302,7 @@ declare function createTokens(overrides?: Partial<DesignTokens>): DesignTokens;
 /**
  * Theme metadata interface matching themes.config.js structure
  */
-interface ThemeMetadata {
+interface ThemeMetadata$1 {
     /** Display name of the theme */
     name: string;
     /** Unique identifier/class name for the theme */
@@ -385,7 +385,7 @@ interface UseThemeReturn {
     /** Function to change theme (supports string, Theme, or DesignTokens) */
     setTheme: (theme: string | Theme | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
-    availableThemes: ThemeMetadata[];
+    availableThemes: ThemeMetadata$1[];
     /** Whether a theme is currently loading */
     isLoading: boolean;
     /** Current error, if any */
@@ -454,7 +454,7 @@ interface ThemeProviderProps {
     /** Default theme */
     defaultTheme?: string | Theme;
     /** Available themes */
-    themes?: Record<string, ThemeMetadata>;
+    themes?: Record<string, ThemeMetadata$1>;
     /** Base path for theme CSS */
     basePath?: string;
     /** CDN path for theme CSS */
@@ -487,7 +487,7 @@ interface ThemeContextValue {
     /** Set theme function (supports string, Theme, or DesignTokens) */
     setTheme: (theme: string | Theme | DesignTokens | Partial<DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
-    availableThemes: ThemeMetadata[];
+    availableThemes: ThemeMetadata$1[];
     /** Loading state */
     isLoading: boolean;
     /** Error state */
@@ -714,7 +714,7 @@ interface ThemeCustomProperties {
  * Theme configuration options for createTheme
  * Extends ThemeMetadata to support both CSS and JS theme properties
  */
-interface ThemeOptions extends Partial<ThemeMetadata> {
+interface ThemeOptions extends Partial<ThemeMetadata$1> {
     /** Color palette configuration */
     palette?: PaletteOptions;
     /** Typography configuration */
@@ -738,7 +738,7 @@ interface ThemeOptions extends Partial<ThemeMetadata> {
  * Complete theme object with computed values
  * Generated by createTheme function
  */
-interface Theme extends ThemeMetadata {
+interface Theme extends ThemeMetadata$1 {
     /** Color palette with computed values */
     palette: {
         primary: PaletteColor;
@@ -864,7 +864,7 @@ declare function generateCSSVariablesForSelector(tokens: DesignTokens, selector:
 /**
  * Core Theme Functions
  *
- * Unified theme system that handles both DesignTokens and Theme objects.
+ * Simplified theme system that handles both DesignTokens and Theme objects.
  * Config-first approach: loads from atomix.config.ts when no input is provided.
  * Config file is required for automatic loading.
  */
@@ -936,14 +936,14 @@ declare function createThemeObject(...options: ThemeOptions[]): Theme;
 /**
  * Theme Composition Utilities
  *
- * Utilities for composing, merging, and extending themes.
+ * Simplified utilities for composing, merging, and extending themes.
  */
 
 /**
  * Deep merge multiple objects
  * Later objects override earlier ones
  */
-declare function deepMerge<T extends Record<string, any>>(...objects: Partial<T>[]): T;
+declare function deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T;
 /**
  * Merge multiple theme options into a single theme options object
  *
@@ -976,286 +976,130 @@ declare function mergeTheme(...themes: ThemeOptions[]): ThemeOptions;
 declare function extendTheme(baseTheme: Theme | ThemeOptions, extension: ThemeOptions): Theme;
 
 /**
- * Atomix Configuration System
- *
- * Tailwind-like configuration for customizing the Atomix Design System.
- *
- * External developers can create `atomix.config.ts` in their project root
- * to customize design tokens, similar to Tailwind's tailwind.config.js
- *
- * @example
- * ```typescript
- * // atomix.config.ts (in your project)
- * import { defineConfig } from '@shohojdhara/atomix/config';
- *
- * export default defineConfig({
- *   theme: {
- *     extend: {
- *       colors: {
- *         primary: { main: '#7AFFD7' },
- *       },
- *     },
- *   },
- * });
- * ```
- */
-
-/**
- * CSS Theme Definition
+ * Theme Metadata interface
  */
-interface CSSThemeDefinition {
-    type: 'css';
+interface ThemeMetadata {
     name: string;
-    class?: string;
+    class: string;
     description?: string;
-    author?: string;
     version?: string;
-    tags?: string[];
-    supportsDarkMode?: boolean;
-    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
-    a11y?: {
-        contrastTarget?: number;
-        modes?: string[];
-    };
-    color?: string;
-    features?: string[];
-    dependencies?: string[];
-    cssPath?: string;
+    [key: string]: any;
 }
 /**
- * JavaScript Theme Definition
+ * Theme Registry type - a record of theme IDs to metadata
  */
-interface JSThemeDefinition {
-    type: 'js';
-    name: string;
-    class?: string;
-    description?: string;
-    author?: string;
-    version?: string;
-    tags?: string[];
-    supportsDarkMode?: boolean;
-    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
-    a11y?: {
-        contrastTarget?: number;
-        modes?: string[];
-    };
-    color?: string;
-    features?: string[];
-    dependencies?: string[];
-    createTheme: () => Theme;
-}
+type ThemeRegistry = Record<string, ThemeMetadata>;
 /**
- * Theme Definition (CSS or JS)
+ * Create a new theme registry
  */
-type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
+declare function createThemeRegistry(): ThemeRegistry;
 /**
- * Build configuration (migrated from theme.config.ts)
+ * Register a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ * @param metadata - Theme metadata
  */
-interface BuildConfig {
-    output?: {
-        directory?: string;
-        formats?: {
-            expanded?: string;
-            compressed?: string;
-        };
-    };
-    sass?: {
-        style?: 'expanded' | 'compressed';
-        sourceMap?: boolean;
-        loadPaths?: string[];
-    };
-}
+declare function registerTheme(registry: ThemeRegistry, id: string, metadata: ThemeMetadata): void;
 /**
- * Runtime configuration (migrated from theme.config.ts)
+ * Unregister a theme
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
  */
-interface RuntimeConfig {
-    basePath?: string;
-    cdnPath?: string | null;
-    preload?: string[];
-    lazy?: boolean;
-    defaultTheme?: string;
-    storageKey?: string;
-    dataAttribute?: string;
-    enablePersistence?: boolean;
-    useMinified?: boolean;
-}
+declare function unregisterTheme(registry: ThemeRegistry, id: string): boolean;
 /**
- * Integration settings (migrated from theme.config.ts)
+ * Check if a theme is registered
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
  */
-interface IntegrationConfig {
-    cssVariables?: Record<string, string>;
-    classNames?: {
-        theme?: string;
-        colorMode?: string;
-    };
-}
-
+declare function hasTheme(registry: ThemeRegistry, id: string): boolean;
 /**
- * Theme Configuration Types
- *
- * Type definitions for the theme configuration system
+ * Get theme metadata
+ * @param registry - Theme registry object
+ * @param id - Theme identifier
+ */
+declare function getTheme(registry: ThemeRegistry, id: string): ThemeMetadata | undefined;
+/**
+ * Get all registered theme metadata
+ * @param registry - Theme registry object
+ */
+declare function getAllThemes(registry: ThemeRegistry): ThemeMetadata[];
+/**
+ * Get all registered theme IDs
+ * @param registry - Theme registry object
+ */
+declare function getThemeIds(registry: ThemeRegistry): string[];
+/**
+ * Clear all registered themes
+ * @param registry - Theme registry object
  */
+declare function clearThemes(registry: ThemeRegistry): void;
+/**
+ * Get the number of registered themes
+ * @param registry - Theme registry object
+ */
+declare function getThemeCount(registry: ThemeRegistry): number;
 
 /**
- * Loaded and validated theme configuration
- */
-interface LoadedThemeConfig {
-    /** Registered themes */
-    themes: Record<string, ThemeDefinition>;
-    /** Build configuration */
-    build: BuildConfig;
-    /** Runtime configuration */
-    runtime: RuntimeConfig;
-    /** Integration settings */
-    integration: IntegrationConfig;
-    /** Theme dependencies mapping */
-    dependencies: Record<string, string[]>;
-    /** Whether config was validated */
-    validated: boolean;
-    /** Validation errors (if any) */
-    errors?: string[];
-    /** Validation warnings (if any) */
-    warnings?: string[];
-    /** Internal tokens (for generator) */
-    __tokens?: any;
-    /** Internal extensions (for generator) */
-    __extend?: any;
+ * Naming Utilities
+ *
+ * Provides consistent naming conventions across the theme system
+ */
+interface NamingOptions {
+    prefix?: string;
+    component?: string;
+    variant?: string;
+    state?: string;
 }
+/**
+ * Generate consistent CSS class names following BEM methodology
+ */
+declare function generateClassName(block: string, element?: string, modifiers?: Record<string, boolean | string>): string;
+/**
+ * Generate consistent CSS variable names
+ */
+declare function generateCSSVariableName(property: string, options?: NamingOptions): string;
+/**
+ * Normalize theme tokens to consistent naming convention
+ */
+declare function normalizeThemeTokens(tokens: Record<string, any>): Record<string, any>;
+/**
+ * Convert camelCase to kebab-case for CSS custom properties
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Convert theme property to CSS variable name
+ */
+declare function themePropertyToCSSVar(propertyPath: string, prefix?: string): string;
 
 /**
- * Theme Registry
+ * Component Theming Utilities
  *
- * Central registry for all themes with discovery and dependency management
+ * Provides consistent patterns for applying theme values to components
  */
 
-/**
- * Registry entry
- */
-interface RegistryEntry {
-    /** Theme ID */
-    id: string;
-    /** Theme definition from config */
-    definition: ThemeDefinition;
-    /** Resolved theme object (for JS themes) */
-    theme?: Theme;
-    /** Whether theme is loaded */
-    loaded: boolean;
-    /** Loading promise (if currently loading) */
-    loading?: Promise<Theme | void>;
-    /** Dependencies */
-    dependencies: string[];
-    /** Dependent themes (themes that depend on this one) */
-    dependents: string[];
+interface ComponentThemeOptions {
+    component: string;
+    variant?: string;
+    size?: string;
+    theme: Theme;
 }
 /**
- * Theme Registry
- *
- * Manages theme registration, discovery, and dependency resolution
+ * Get a theme value for a specific component using CSS variables
+ * This ensures all components access theme values consistently
  */
-declare class ThemeRegistry {
-    private entries;
-    private config;
-    private initialized;
-    /**
-     * Initialize registry from config
-     */
-    initialize(config?: LoadedThemeConfig): Promise<void>;
-    /**
-     * Register a theme
-     */
-    register(themeId: string, definition: ThemeDefinition): void;
-    /**
-     * Get theme entry
-     */
-    get(themeId: string): RegistryEntry | undefined;
-    /**
-     * Check if theme exists
-     */
-    has(themeId: string): boolean;
-    /**
-     * Get all theme IDs
-     */
-    getAllIds(): string[];
-    /**
-     * Get all theme metadata
-     */
-    getAllMetadata(): ThemeMetadata[];
-    /**
-     * Get theme definition
-     */
-    getDefinition(themeId: string): ThemeDefinition | undefined;
-    /**
-     * Check if a theme is loaded
-     */
-    isThemeLoaded(themeId: string): boolean;
-    /**
-     * Mark a theme as loaded
-     */
-    markLoaded(themeId: string, theme?: Theme): void;
-    /**
-     * Get theme object (for JS themes)
-     */
-    getTheme(themeId: string): Theme | undefined;
-    /**
-     * Get dependencies for a theme
-     */
-    getDependencies(themeId: string): string[];
-    /**
-     * Get dependents for a theme (themes that depend on this one)
-     */
-    getDependents(themeId: string): string[];
-    /**
-     * Resolve all dependencies in correct order
-     */
-    resolveDependencyOrder(themeId: string): string[];
-    /**
-     * Resolve dependencies and build dependency graph
-     */
-    private resolveDependencies;
-    /**
-     * Validate all themes
-     */
-    validate(): {
-        valid: boolean;
-        errors: string[];
-    };
-    /**
-     * Clear registry
-     */
-    clear(): void;
-}
-
+declare function getComponentThemeValue(component: string, property: string, variant?: string, size?: string): string;
 /**
- * CSS File Utilities
- *
- * Save CSS to file system (Node.js only).
+ * Generate component-specific CSS variables from theme
  */
+declare function generateComponentCSSVars(component: string, theme: Theme, variant?: string, size?: string): Record<string, string>;
 /**
- * Save CSS to file
- *
- * Writes CSS string to a file. Only works in Node.js environment.
- *
- * @param css - CSS string to save
- * @param filePath - Output file path
- * @throws Error if called in browser environment
- *
- * @example
- * ```typescript
- * const css = ':root { --atomix-color-primary: #7AFFD7; }';
- * await saveCSSFile(css, './themes/custom.css');
- * ```
+ * Apply consistent theme to component style object
  */
-declare function saveCSSFile(css: string, filePath: string): Promise<void>;
+declare function applyComponentTheme(component: string, style?: React.CSSProperties, variant?: string, size?: string, theme?: Theme): React.CSSProperties;
 /**
- * Save CSS to file (synchronous version)
- *
- * Synchronous version of saveCSSFile. Only works in Node.js environment.
- *
- * @param css - CSS string to save
- * @param filePath - Output file path
- * @throws Error if called in browser environment
+ * Create a hook for consistent component theming
  */
-declare function saveCSSFileSync(css: string, filePath: string): void;
+declare function useComponentTheme(component: string, variant?: string, size?: string, theme?: Theme): (property: string) => string;
 
 /**
  * CSS Injection Utilities
@@ -1304,78 +1148,49 @@ declare function removeCSS(id?: string): void;
 declare function isCSSInjected(id?: string): boolean;
 
 /**
- * Config Loader
+ * Theme Configuration Loader
  *
- * Load design tokens from atomix.config.ts and convert to flat token format.
+ * Provides functions to load theme configurations from atomix.config.ts
+ * Includes both sync and async versions, with automatic fallbacks
  */
 
 /**
- * Load theme tokens from atomix.config.ts
- *
- * Loads atomix.config.ts and extracts theme tokens.
- * Config file is required - throws error if not found.
- *
- * @param configPath - Optional custom config path (default: 'atomix.config.ts')
- * @returns Partial DesignTokens from config
- * @throws Error if config file is not found or cannot be loaded
- *
- * @example
- * ```typescript
- * const tokens = await loadThemeFromConfig();
- * const css = createTheme(tokens);
- * injectTheme(css);
- * ```
+ * Load theme from config file (synchronous, Node.js only)
+ * @param configPath - Path to config file (default: atomix.config.ts)
+ * @returns DesignTokens from theme configuration
+ * @throws Error if config loading is not available in browser environment
  */
-declare function loadThemeFromConfig(configPath?: string): Promise<Partial<DesignTokens>>;
+declare function loadThemeFromConfigSync(options?: {
+    configPath?: string;
+    required?: boolean;
+}): DesignTokens;
 /**
- * Load theme tokens from atomix.config.ts (synchronous version)
- *
- * Synchronous version that uses require() instead of dynamic import.
- * Only works in Node.js environment.
- * Config file is required - throws error if not found.
- *
- * @param configPath - Optional custom config path
- * @returns Partial DesignTokens from config
- * @throws Error if config file is not found or cannot be loaded
+ * Load theme from config file (asynchronous)
+ * @param configPath - Path to config file (default: atomix.config.ts)
+ * @returns Promise resolving to DesignTokens from theme configuration
  */
-declare function loadThemeFromConfigSync(configPath?: string): Partial<DesignTokens>;
+declare function loadThemeFromConfig(options?: {
+    configPath?: string;
+    required?: boolean;
+}): Promise<DesignTokens>;
 
 /**
  * Theme Provider
  *
- * React context provider for theme management
+ * React context provider for theme management with separated concerns
+ * Updated to use the new simplified theme system
  */
 
 /**
- * ThemeProvider component
- *
- * Provides theme context to child components and manages theme state.
- *
- * **Config-First Approach**: If `defaultTheme` is not provided, loads from `atomix.config.ts`.
- * Config file is required when `defaultTheme` is not provided.
- *
- * @example
- * ```tsx
- * import { ThemeProvider } from '@shohojdhara/atomix/theme';
+ * Theme Provider
  *
- * // Loads from atomix.config.ts (config file required)
- * function App() {
- *   return (
- *     <ThemeProvider>
- *       <YourApp />
- *     </ThemeProvider>
- *   );
- * }
+ * React context provider for theme management with separated concerns.
+ * Simplified version focusing on core functionality:
+ * - String-based themes (CSS files)
+ * - JS Theme objects
+ * - Persistence via localStorage
  *
- * // Provide explicit theme (bypasses config)
- * function App() {
- *   return (
- *     <ThemeProvider defaultTheme="dark">
- *       <YourApp />
- *     </ThemeProvider>
- *   );
- * }
- * ```
+ * Falls back to 'default' theme if no configuration is found.
  */
 declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
 
@@ -1408,6 +1223,39 @@ declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
  */
 declare function useTheme(): UseThemeReturn;
 
+/**
+ * Standardized hook for accessing theme tokens in components
+ *
+ * Provides consistent access to theme values across all components
+ * using either CSS custom properties or theme object values.
+ */
+type ThemeTokens = {
+    theme: string;
+    activeTheme: Theme | null;
+    getToken: (tokenName: string, fallback?: string) => string;
+    getThemeValue: (path: string, fallback?: any) => any;
+    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>;
+};
+declare function useThemeTokens(): ThemeTokens;
+
 /**
  * Theme context with default values
  */
@@ -1529,7 +1377,7 @@ declare function getThemeApplicator(): ThemeApplicator;
 /**
  * Apply theme using global applicator
  */
-declare function applyTheme(theme: Theme): void;
+declare function applyTheme(theme: Theme | DesignTokens): void;
 
 /**
  * Theme Preview Component
@@ -1698,7 +1546,7 @@ declare class ThemeValidator {
     /**
      * Validate theme
      */
-    validate(theme: Theme, metadata?: ThemeMetadata): ValidationResult;
+    validate(theme: Theme, metadata?: ThemeMetadata$1): ValidationResult;
     /**
      * Validate palette
      */
@@ -1866,25 +1714,6 @@ interface CSSVariableNamingOptions {
     /** Whether to include component name in variable (default: true) */
     includeComponent?: boolean;
 }
-/**
- * Generate CSS variable name from parts
- *
- * @example
- * generateCSSVariableName('button', 'bg', { prefix: 'atomix' })
- * // Returns: '--atomix-button-bg'
- */
-declare function generateCSSVariableName(component: string, property: string, options?: CSSVariableNamingOptions): string;
-/**
- * Generate CSS variables object from configuration
- *
- * @example
- * const vars = generateComponentCSSVars({
- *   component: 'button',
- *   properties: { bg: '#000', color: '#fff' }
- * })
- * // Returns: { '--atomix-button-bg': '#000', '--atomix-button-color': '#fff' }
- */
-declare function generateComponentCSSVars(config: CSSVariableConfig, options?: CSSVariableNamingOptions): Record<string, string>;
 /**
  * Map SCSS tokens to CSS custom properties
  *
@@ -2118,5 +1947,5 @@ declare function removeTheme(id?: string): void;
  */
 declare function saveTheme(css: string, filePath: string): Promise<void>;
 
-export { RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeRegistry, ThemeValidator, applyCSSVariables, applyTheme, createDesignTokensFromTheme, createTheme, createThemeObject, createTokens, cssVarsToStyle, deepMerge, defaultTokens, designTokensToCSSVars, designTokensToTheme, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables, generateCSSVariablesForSelector, generateComponentCSSVars, getCSSVariable, getDesignTokensFromTheme, getThemeApplicator, injectCSS, injectTheme, isCSSInjected, isDesignTokens, isThemeObject, isValidCSSVariableName, loadThemeFromConfig, loadThemeFromConfigSync, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, removeCSS, removeCSSVariables, removeTheme, saveCSSFile, saveCSSFileSync, saveTheme, themeToDesignTokens, useHistory, useTheme };
-export type { A11yIssue, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOverride, DesignTokens, GenerateCSSVariablesOptions, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemeMetadata, ThemePreviewProps, ThemeProviderProps, ThemeValidationResult, UseHistoryOptions, UseHistoryReturn, UseThemeReturn, ValidationResult };
+export { RTLManager, ThemeApplicator, ThemeComparator, ThemeContext, ThemeErrorBoundary, ThemeInspector, ThemeLiveEditor, ThemePreview, ThemeProvider, ThemeValidator, applyCSSVariables, applyComponentTheme, applyTheme, camelToKebab, clearThemes, createDesignTokensFromTheme, createTheme, createThemeObject, createThemeRegistry, createTokens, cssVarsToStyle, deepMerge, defaultTokens, designTokensToCSSVars, designTokensToTheme, extendTheme, extractComponentName, generateCSSVariableName, generateCSSVariables, generateCSSVariablesForSelector, generateClassName, generateComponentCSSVars, getAllThemes, getCSSVariable, getComponentThemeValue, getDesignTokensFromTheme, getTheme, getThemeApplicator, getThemeCount, getThemeIds, hasTheme, injectCSS, injectTheme, isCSSInjected, isDesignTokens, isThemeObject, isValidCSSVariableName, loadThemeFromConfig, loadThemeFromConfigSync, mapSCSSTokensToCSSVars, mergeCSSVars, mergeTheme, normalizeThemeTokens, registerTheme, removeCSS, removeCSSVariables, removeTheme, saveTheme, themePropertyToCSSVar, themeToDesignTokens, unregisterTheme, useComponentTheme, useHistory, useTheme, useThemeTokens };
+export type { A11yIssue, CSSVariableConfig, CSSVariableNamingOptions, ComponentThemeOptions, ComponentThemeOverride, DesignTokens, GenerateCSSVariablesOptions, NamingOptions, RTLConfig, Theme, ThemeChangeEvent, ThemeComparatorProps, ThemeComponentOverrides, ThemeContextValue, ThemeErrorBoundaryProps, ThemeInspectorProps, ThemeLiveEditorProps, ThemeLoadOptions, ThemePreviewProps, ThemeProviderProps, ThemeValidationResult, UseHistoryOptions, UseHistoryReturn, UseThemeReturn, ValidationResult };