@shohojdhara/atomix 0.3.1 → 0.3.3

package/src/lib/theme/whitelabel/WhiteLabelManager.ts

@@ -0,0 +1,364 @@
+/**
+ * White Label Manager
+ * 
+ * Provides white labeling capabilities for themes
+ */
+
+import type { Theme, ThemeOptions } from '../types';
+import { createTheme } from '../createTheme';
+import { extendTheme } from '../composeTheme';
+
+/**
+ * Brand configuration
+ */
+export interface BrandConfig {
+  /** Brand name */
+  name: string;
+  /** Brand logo URL */
+  logo?: string;
+  /** Primary brand color */
+  primaryColor?: string;
+  /** Secondary brand color */
+  secondaryColor?: string;
+  /** Brand fonts */
+  fonts?: {
+    primary?: string;
+    secondary?: string;
+  };
+  /** Brand favicon */
+  favicon?: string;
+  /** Custom CSS */
+  customCSS?: string;
+  /** Custom meta tags */
+  metaTags?: Record<string, string>;
+}
+
+/**
+ * White label configuration
+ */
+export interface WhiteLabelConfig {
+  /** Brand configuration */
+  brand: BrandConfig;
+  /** Theme overrides */
+  themeOverrides?: Partial<ThemeOptions>;
+  /** Component overrides */
+  componentOverrides?: Record<string, any>;
+  /** CSS variable overrides */
+  cssVariableOverrides?: Record<string, string>;
+  /** Enable DOM mutations (default: false for headless/server safety) */
+  enableDOMOperations?: boolean;
+}
+
+/**
+ * White Label Manager
+ * 
+ * Manages white labeling for themes
+ */
+export class WhiteLabelManager {
+  private config: WhiteLabelConfig | null = null;
+  private baseTheme: Theme | null = null;
+
+  constructor(baseTheme?: Theme) {
+    if (baseTheme) {
+      this.baseTheme = baseTheme;
+    }
+  }
+
+  /**
+   * Set base theme
+   */
+  setBaseTheme(theme: Theme): void {
+    this.baseTheme = theme;
+  }
+
+  /**
+   * Configure white label
+   */
+  configure(config: WhiteLabelConfig): void {
+    this.config = config;
+    this.applyWhiteLabel();
+  }
+
+  /**
+   * Get white labeled theme
+   */
+  getWhiteLabeledTheme(): Theme | null {
+    if (!this.baseTheme || !this.config) {
+      return this.baseTheme;
+    }
+
+    // Create theme with white label overrides
+    const themeOptions: ThemeOptions = {
+      ...this.baseTheme,
+      name: this.config.brand.name,
+      ...this.config.themeOverrides,
+      palette: {
+        ...this.baseTheme.palette,
+        ...(this.config.brand.primaryColor && {
+          primary: {
+            ...this.baseTheme.palette.primary,
+            main: this.config.brand.primaryColor,
+          },
+        }),
+        ...(this.config.brand.secondaryColor && {
+          secondary: {
+            ...this.baseTheme.palette.secondary,
+            main: this.config.brand.secondaryColor,
+          },
+        }),
+        ...this.config.themeOverrides?.palette,
+      },
+      typography: {
+        ...this.baseTheme.typography,
+        ...(this.config.brand.fonts?.primary && {
+          fontFamily: this.config.brand.fonts.primary,
+        }),
+        ...this.config.themeOverrides?.typography,
+      },
+      custom: {
+        ...this.baseTheme.custom,
+        whiteLabel: {
+          brand: this.config.brand,
+          componentOverrides: this.config.componentOverrides,
+          cssVariableOverrides: this.config.cssVariableOverrides,
+        },
+      },
+    };
+
+    return createTheme(themeOptions);
+  }
+
+  /**
+   * Apply white label to DOM
+   */
+  private applyWhiteLabel(): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    const { brand } = this.config;
+
+    // Apply logo
+    if (brand.logo) {
+      this.applyLogo(brand.logo);
+    }
+
+    // Apply favicon
+    if (brand.favicon) {
+      this.applyFavicon(brand.favicon);
+    }
+
+    // Apply meta tags
+    if (brand.metaTags) {
+      this.applyMetaTags(brand.metaTags);
+    }
+
+    // Apply custom CSS
+    if (brand.customCSS) {
+      this.applyCustomCSS(brand.customCSS);
+    }
+
+    // Apply CSS variable overrides
+    if (this.config.cssVariableOverrides) {
+      this.applyCSSVariables(this.config.cssVariableOverrides);
+    }
+  }
+
+  /**
+   * Apply logo
+   */
+  applyLogo(logoUrl: string, selector?: string, element?: HTMLElement): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    // Find or create logo element
+    let logoElement = element || (selector ? document.querySelector(selector) : null) as HTMLImageElement | null;
+    
+    if (!logoElement) {
+      logoElement = document.querySelector('[data-whitelabel-logo]') as HTMLImageElement;
+    }
+    
+    if (!logoElement) {
+      logoElement = document.createElement('img');
+      logoElement.setAttribute('data-whitelabel-logo', 'true');
+      logoElement.style.maxHeight = '40px';
+      logoElement.style.maxWidth = '200px';
+      
+      // Try to find a container (e.g., header, navbar)
+      const container = selector 
+        ? document.querySelector(selector)
+        : document.querySelector('header, [role="banner"], .navbar, .header');
+      
+      if (container) {
+        container.insertBefore(logoElement, container.firstChild);
+      } else {
+        document.body.insertBefore(logoElement, document.body.firstChild);
+      }
+    }
+
+    (logoElement as HTMLImageElement).src = logoUrl;
+    (logoElement as HTMLImageElement).alt = this.config?.brand.name || 'Logo';
+  }
+
+  /**
+   * Apply favicon
+   */
+  applyFavicon(faviconUrl: string, selector?: string): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    // Remove existing favicons
+    const existingFavicons = document.querySelectorAll('link[rel="icon"], link[rel="shortcut icon"]');
+    existingFavicons.forEach(favicon => favicon.remove());
+
+    // Create new favicon link
+    const link = document.createElement('link');
+    link.rel = 'icon';
+    link.type = 'image/x-icon';
+    link.href = faviconUrl;
+    
+    const target = selector ? document.querySelector(selector) : document.head;
+    if (target) {
+      target.appendChild(link);
+    }
+  }
+
+  /**
+   * Apply meta tags
+   */
+  applyMetaTags(metaTags: Record<string, string>, selector?: string): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    const target = selector ? document.querySelector(selector) : document.head;
+    if (!target) {
+      return;
+    }
+
+    for (const [name, content] of Object.entries(metaTags)) {
+      // Check if meta tag exists
+      let metaElement = document.querySelector(`meta[name="${name}"]`) as HTMLMetaElement;
+      
+      if (!metaElement) {
+        metaElement = document.createElement('meta');
+        metaElement.name = name;
+        target.appendChild(metaElement);
+      }
+
+      metaElement.content = content;
+    }
+  }
+
+  /**
+   * Apply custom CSS
+   */
+  applyCustomCSS(css: string, styleId?: string): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    const id = styleId || 'whitelabel-custom-css';
+    
+    // Remove existing white label CSS
+    const existingStyle = document.getElementById(id);
+    if (existingStyle) {
+      existingStyle.remove();
+    }
+
+    // Create new style element
+    const style = document.createElement('style');
+    style.id = id;
+    style.textContent = css;
+    document.head.appendChild(style);
+  }
+
+  /**
+   * Apply CSS variables
+   */
+  applyCSSVariables(variables: Record<string, string>, root?: HTMLElement | string): void {
+    if (!this.config?.enableDOMOperations || typeof document === 'undefined') {
+      return;
+    }
+
+    let targetElement: HTMLElement;
+    
+    if (typeof root === 'string') {
+      const element = document.querySelector(root);
+      if (!element || !(element instanceof HTMLElement)) {
+        return;
+      }
+      targetElement = element;
+    } else if (root instanceof HTMLElement) {
+      targetElement = root;
+    } else {
+      targetElement = document.documentElement;
+    }
+
+    for (const [key, value] of Object.entries(variables)) {
+      targetElement.style.setProperty(key.startsWith('--') ? key : `--${key}`, value);
+    }
+  }
+
+  /**
+   * Remove white label
+   */
+  removeWhiteLabel(): void {
+    // Remove logo
+    const logo = document.querySelector('[data-whitelabel-logo]');
+    logo?.remove();
+
+    // Remove custom CSS
+    const customCSS = document.getElementById('whitelabel-custom-css');
+    customCSS?.remove();
+
+    // Remove CSS variables (would need to track original values)
+    if (this.config?.cssVariableOverrides) {
+      const root = document.documentElement;
+      for (const key of Object.keys(this.config.cssVariableOverrides)) {
+        root.style.removeProperty(key.startsWith('--') ? key : `--${key}`);
+      }
+    }
+
+    this.config = null;
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): WhiteLabelConfig | null {
+    return this.config;
+  }
+
+  /**
+   * Export configuration
+   */
+  exportConfig(): string {
+    if (!this.config) {
+      throw new Error('No white label configuration to export');
+    }
+
+    return JSON.stringify(this.config, null, 2);
+  }
+
+  /**
+   * Import configuration
+   */
+  importConfig(json: string): void {
+    try {
+      const config = JSON.parse(json) as WhiteLabelConfig;
+      this.configure(config);
+    } catch (error) {
+      throw new Error(`Failed to import white label configuration: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/**
+ * Create white label manager
+ */
+export function createWhiteLabelManager(baseTheme?: Theme): WhiteLabelManager {
+  return new WhiteLabelManager(baseTheme);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * White Label Module
+ */
+
+export * from './WhiteLabelManager';
+export {
+  WhiteLabelManager,
+  createWhiteLabelManager,
+} from './WhiteLabelManager';
+export type {
+  BrandConfig,
+  WhiteLabelConfig,
+} from './WhiteLabelManager';

package/src/lib/theme-tools.ts

@@ -0,0 +1,185 @@
+/**
+ * Theme Tools for Library Users
+ * 
+ * Developer-friendly utilities for working with Atomix themes
+ */
+
+import { Theme, ThemeMetadata } from './theme/types';
+import { createTheme } from './theme/createTheme';
+import { extendTheme, mergeTheme } from './theme/composeTheme';
+import { ComponentOverrideManager } from './theme/overrides/ComponentOverrides';
+import { WhiteLabelManager } from './theme/whitelabel/WhiteLabelManager';
+import { generateCSSVariables } from './theme/generateCSSVariables';
+
+/**
+ * Quick theme creator with sensible defaults
+ */
+export function quickTheme(name: string, primaryColor: string, secondaryColor?: string): Theme {
+  return createTheme({
+    name,
+    palette: {
+      primary: { main: primaryColor },
+      secondary: secondaryColor ? { main: secondaryColor } : undefined,
+    },
+  });
+}
+
+/**
+ * Create a dark theme variant from a light theme
+ */
+export function createDarkVariant(lightTheme: Theme): Theme {
+  return extendTheme(lightTheme, {
+    name: `${lightTheme.name} Dark`,
+    palette: {
+      mode: 'dark',
+      background: {
+        default: '#121212',
+        paper: '#1e1e1e',
+      },
+      text: {
+        primary: '#ffffff',
+        secondary: 'rgba(255, 255, 255, 0.7)',
+      },
+    },
+  });
+}
+
+/**
+ * Validate theme structure
+ */
+export function validateTheme(theme: Theme): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  
+  if (!theme.name) {
+    errors.push('Theme must have a name');
+  }
+  
+  if (!theme.palette) {
+    errors.push('Theme must have a palette');
+  }
+  
+  if (theme.palette && !theme.palette.primary) {
+    errors.push('Theme palette must have a primary color');
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Generate CSS string from theme
+ */
+export function themeToCSS(theme: Theme, selector = ':root'): string {
+  return generateCSSVariables(theme, {
+    selector,
+    prefix: 'atomix',
+  });
+}
+
+/**
+ * Apply overrides to theme easily
+ */
+export function applyOverrides(
+  theme: Theme,
+  overrides: Record<string, any>
+): Theme {
+  const manager = new ComponentOverrideManager(theme);
+  
+  Object.entries(overrides).forEach(([component, override]) => {
+    manager.addOverride(component, override);
+  });
+  
+  const overriddenTheme = manager.getThemeWithOverrides();
+  if (!overriddenTheme) {
+    throw new Error('Failed to get theme with overrides: theme was not set');
+  }
+  
+  return overriddenTheme;
+}
+
+/**
+ * Apply white label configuration
+ */
+export function applyWhiteLabel(
+  theme: Theme,
+  brand: {
+    name: string;
+    primaryColor: string;
+    logo?: string;
+  }
+): Theme {
+  const manager = new WhiteLabelManager(theme);
+  
+  manager.configure({
+    brand: {
+      name: brand.name,
+      primaryColor: brand.primaryColor,
+      logo: brand.logo,
+    },
+    themeOverrides: {
+      palette: {
+        primary: { main: brand.primaryColor },
+      },
+    },
+  });
+  
+  const whiteLabeledTheme = manager.getWhiteLabeledTheme();
+  if (!whiteLabeledTheme) {
+    throw new Error('Failed to get white labeled theme: theme was not set');
+  }
+  
+  return whiteLabeledTheme;
+}
+
+/**
+ * Get theme metadata
+ */
+export function getThemeMetadata(theme: Theme): ThemeMetadata {
+  return {
+    name: theme.name || 'Custom Theme',
+    description: theme.description,
+    author: theme.author,
+    version: theme.version || '1.0.0',
+    tags: theme.tags || [],
+    supportsDarkMode: theme.palette?.mode === 'dark',
+    status: 'stable',
+    color: theme.palette?.primary?.main || '#7AFFD7',
+  };
+}
+
+/**
+ * Check if theme supports dark mode
+ */
+export function supportsDarkMode(theme: Theme): boolean {
+  return theme.palette?.mode === 'dark' || 
+         theme.supportsDarkMode === true ||
+         Boolean(theme.a11y?.modes?.includes('dark'));
+}
+
+/**
+ * Export theme as JSON
+ */
+export function exportTheme(theme: Theme): string {
+  return JSON.stringify(theme, null, 2);
+}
+
+/**
+ * Import theme from JSON
+ */
+export function importTheme(json: string): Theme {
+  try {
+    return JSON.parse(json) as Theme;
+  } catch (error) {
+    throw new Error('Invalid theme JSON');
+  }
+}
+
+// Re-export commonly used functions
+export { createTheme, extendTheme, mergeTheme };
+export { generateCSSVariables };
+export { ComponentOverrideManager } from './theme/overrides/ComponentOverrides';
+export { WhiteLabelManager } from './theme/whitelabel/WhiteLabelManager';
+export { RTLManager } from './theme/i18n/rtl';
+export { ThemeAnalytics } from './theme/monitoring/ThemeAnalytics';