@qwickapps/react-framework 1.4.9 → 1.5.1

package/src/utils/iconMap.tsx

@@ -0,0 +1,244 @@
+/**
+ * Icon Mapping Utility
+ * 
+ * Provides centralized icon mapping for both Material-UI components and emoji representations.
+ * Used across the framework for consistent icon rendering in buttons, navigation, admin UI, etc.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import {
+  Article,
+  Home,
+  Book,
+  Download,
+  CloudDownload,
+  CloudUpload,
+  Computer,
+  Settings,
+  Dashboard,
+  Info,
+  Inventory,
+  Inventory2,
+  Help,
+  Add,
+  Edit,
+  Delete,
+  Check,
+  Close,
+  ArrowForward,
+  ArrowBack,
+  Menu,
+  Search,
+  Favorite,
+  Star,
+  Share,
+  Save,
+  Send,
+  Email,
+  Phone,
+  Person,
+  Group,
+  Business,
+  ShoppingCart,
+  Speed,
+  SupportAgent,
+  Tune,
+  AttachMoney,
+  Lock,
+  LockOpen,
+  Visibility,
+  VisibilityOff,
+  // New icons for seed content
+  Psychology,
+  Autorenew,
+  Code,
+  IntegrationInstructions,
+  Construction,
+  Work,
+  Layers,
+  TrendingUp,
+  Route,
+  Sync,
+  Architecture,
+  Security,
+  VerifiedUser,
+  // Additional icons for control panels and admin UIs
+  VpnKey,
+  Key,
+  PersonSearch,
+  ManageAccounts,
+  Storage,
+  Refresh,
+  Block,
+  CheckCircle,
+  RotateRight,
+  Memory,
+} from '@mui/icons-material';
+
+/**
+ * Icon mapping entry with both Material-UI component and emoji representation
+ */
+export interface IconMapping {
+  emoji: string;
+  component: React.ComponentType;
+}
+
+/**
+ * Centralized icon registry mapping icon names to their representations
+ * Supports both Material-UI components and emoji for different contexts
+ */
+export const iconMap: Record<string, IconMapping> = {
+  // Navigation & Layout
+  home: { emoji: '🏠', component: Home },
+  menu: { emoji: '☰', component: Menu },
+  dashboard: { emoji: '📊', component: Dashboard },
+  
+  // Information & Help
+  info: { emoji: 'ℹ️', component: Info },
+  about: { emoji: 'ℹ️', component: Info },
+  help: { emoji: '❓', component: Help },
+  book: { emoji: '📖', component: Book },
+  
+  // Communication
+  email: { emoji: '📧', component: Email },
+  contact: { emoji: '📧', component: Email },
+  phone: { emoji: '📱', component: Phone },
+  send: { emoji: '📤', component: Send },
+  
+  // Actions
+  add: { emoji: '➕', component: Add },
+  edit: { emoji: '✏️', component: Edit },
+  delete: { emoji: '🗑️', component: Delete },
+  save: { emoji: '💾', component: Save },
+  check: { emoji: '✓', component: Check },
+  close: { emoji: '✕', component: Close },
+  
+  // Navigation
+  arrowforward: { emoji: '→', component: ArrowForward },
+  arrowback: { emoji: '←', component: ArrowBack },
+  
+  // Content
+  search: { emoji: '🔍', component: Search },
+  share: { emoji: '🔗', component: Share },
+  download: { emoji: '⬇️', component: Download },
+  clouddownload: { emoji: '☁️⬇️', component: CloudDownload },
+  cloudupload: { emoji: '☁️⬆️', component: CloudUpload },
+  
+  // User & Social
+  person: { emoji: '👤', component: Person },
+  user: { emoji: '👤', component: Person },
+  group: { emoji: '👥', component: Group },
+  favorite: { emoji: '❤️', component: Favorite },
+  star: { emoji: '⭐', component: Star },
+  verified_user: { emoji: '✅', component: VerifiedUser },
+  
+  // Business
+  business: { emoji: '🏢', component: Business },
+  shoppingcart: { emoji: '🛒', component: ShoppingCart },
+  cart: { emoji: '🛒', component: ShoppingCart },
+  attachmoney: { emoji: '💰', component: AttachMoney },
+  
+  // Security
+  lock: { emoji: '🔒', component: Lock },
+  lockopen: { emoji: '🔓', component: LockOpen },
+  visibility: { emoji: '👁️', component: Visibility },
+  visibilityoff: { emoji: '🙈', component: VisibilityOff },
+  
+  // System
+  settings: { emoji: '⚙️', component: Settings },
+  computer: { emoji: '💻', component: Computer },
+  
+  // Content Types
+  article: { emoji: '📰', component: Article },
+  blog: { emoji: '📝', component: Book },
+  news: { emoji: '📰', component: Book },
+  products: { emoji: '🛍️', component: ShoppingCart },
+  services: { emoji: '⚙️', component: Settings },
+  portfolio: { emoji: '💼', component: Business },
+  gallery: { emoji: '🖼️', component: Business },
+  inventory: { emoji: '📦', component: Inventory },
+  inventory_2: { emoji: '📦', component: Inventory2 },
+  speed: { emoji: '⚡', component: Speed },
+  support_agent: { emoji: '🛎️', component: SupportAgent },
+  tune: { emoji: '🎛️', component: Tune },
+
+  // Development & Technology
+  code: { emoji: '💻', component: Code },
+  psychology: { emoji: '🧠', component: Psychology },
+  autorenew: { emoji: '🔄', component: Autorenew },
+  integration_instructions: { emoji: '🔌', component: IntegrationInstructions },
+  construction: { emoji: '🚧', component: Construction },
+  work: { emoji: '💼', component: Work },
+  layers: { emoji: '📚', component: Layers },
+  trending_up: { emoji: '📈', component: TrendingUp },
+  route: { emoji: '🗺️', component: Route },
+  sync: { emoji: '🔄', component: Sync },
+  architecture: { emoji: '🏛️', component: Architecture },
+  security: { emoji: '🔐', component: Security },
+
+  // Control Panel & Admin UI Icons
+  key: { emoji: '🔑', component: Key },
+  vpn_key: { emoji: '🔐', component: VpnKey },
+  person_search: { emoji: '🔍', component: PersonSearch },
+  manage_accounts: { emoji: '👥', component: ManageAccounts },
+  storage: { emoji: '💾', component: Storage },
+  refresh: { emoji: '🔄', component: Refresh },
+  block: { emoji: '🚫', component: Block },
+  check_circle: { emoji: '✅', component: CheckCircle },
+  rotate_right: { emoji: '🔄', component: RotateRight },
+  memory: { emoji: '🧠', component: Memory },
+};
+
+/**
+ * Get emoji representation of an icon
+ * @param iconName - Icon name (case-insensitive)
+ * @param fallback - Fallback emoji if icon not found (default: 🔗)
+ * @returns Emoji string
+ */
+export function getIconEmoji(iconName: string | undefined, fallback: string = '🔗'): string {
+  if (!iconName) return fallback;
+  const mapping = iconMap[iconName.toLowerCase()];
+  return mapping?.emoji || iconName;
+}
+
+/**
+ * Get Material-UI component representation of an icon
+ * @param iconName - Icon name (case-insensitive)
+ * @returns React element or null if not found
+ */
+export function getIconComponent(iconName: string | undefined): React.ReactElement | null {
+  if (!iconName) return null;
+  
+  const mapping = iconMap[iconName.toLowerCase()];
+  if (!mapping?.component) {
+    console.warn(`[IconMap] Icon "${iconName}" not found in registry`);
+    return null;
+  }
+  
+  const IconComponent = mapping.component;
+  return <IconComponent />;
+}
+
+/**
+ * Register a new icon or override an existing one
+ * Useful for application-specific icon extensions
+ */
+export function registerIcon(name: string, mapping: IconMapping): void {
+  iconMap[name.toLowerCase()] = mapping;
+}
+
+/**
+ * Check if an icon is registered
+ */
+export function hasIcon(iconName: string): boolean {
+  return iconName.toLowerCase() in iconMap;
+}
+
+/**
+ * Get all registered icon names
+ */
+export function getRegisteredIcons(): string[] {
+  return Object.keys(iconMap);
+}

package/src/utils/index.ts

@@ -1,12 +1,15 @@
 /**
  * Utility functions and types for QwickApps React Framework
- * 
+ *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 export * from './cssUtils';
 export * from './customPaletteManager';
 export * from './dimensions';
+export * from './iconMap';
 export * from './logger';
+export * from './paletteLoader';
+export * from './paletteManifest';
 export * from './paletteUtils';
 export * from './persistenceUtils';
 export * from './reactUtils';

package/src/utils/logger.ts

@@ -7,10 +7,10 @@
  */
 
 export interface Logger {
-  debug(message: string, ...args: any[]): void;
-  info(message: string, ...args: any[]): void;
-  warn(message: string, ...args: any[]): void;
-  error(message: string, ...args: any[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
 }
 
 /**
@@ -19,34 +19,39 @@ export interface Logger {
 class ConsoleLogger implements Logger {
   constructor(private name: string) {}
 
-  debug(message: string, ...args: any[]): void {
+  debug(message: string, ...args: unknown[]): void {
     if (process.env.NODE_ENV !== 'production') {
       console.debug(`[${this.name}] ${message}`, ...args);
     }
   }
 
-  info(message: string, ...args: any[]): void {
+  info(message: string, ...args: unknown[]): void {
     console.info(`[${this.name}] ${message}`, ...args);
   }
 
-  warn(message: string, ...args: any[]): void {
+  warn(message: string, ...args: unknown[]): void {
     console.warn(`[${this.name}] ${message}`, ...args);
   }
 
-  error(message: string, ...args: any[]): void {
+  error(message: string, ...args: unknown[]): void {
     console.error(`[${this.name}] ${message}`, ...args);
   }
 }
 
 /**
  * No-op logger for when logging should be disabled
+ * Not currently used but available for future configuration options
  */
-class NoOpLogger implements Logger {
-  debug(): void {}
-  info(): void {}
-  warn(): void {}
-  error(): void {}
-}
+// class NoOpLogger implements Logger {
+//   // intentionally empty - no-op logger
+//   debug(): void {}
+//   // intentionally empty - no-op logger
+//   info(): void {}
+//   // intentionally empty - no-op logger
+//   warn(): void {}
+//   // intentionally empty - no-op logger
+//   error(): void {}
+// }
 
 /**
  * Create logger with optional @qwickapps/logging dependency
@@ -54,6 +59,7 @@ class NoOpLogger implements Logger {
 function getLogger(name: string): Logger {
   try {
     // Try to use @qwickapps/logging if available
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
     const logging = require('@qwickapps/logging');
     return logging.getLogger(name);
   } catch {

package/src/utils/paletteLoader.ts

@@ -0,0 +1,218 @@
+/**
+ * Palette CSS Loader - Dynamically loads palette CSS files on demand using manifest
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import {
+  getPaletteFromManifest,
+  type PaletteManifestConfig,
+} from './paletteManifest';
+
+// Track loaded palettes to avoid duplicate loading
+const loadedPalettes = new Set<string>();
+
+// Track loading promises to avoid race conditions
+const loadingPalettes = new Map<string, Promise<void>>();
+
+// Default CDN URLs (prioritized)
+const DEFAULT_CDN_URLS = [
+  'https://qwickapps.com/palettes/',  // Primary CDN (Cloudflare)
+  '/palettes/',  // Local fallback
+];
+
+// Global configuration
+let globalConfig: PaletteManifestConfig = { enableRemote: true };
+
+/**
+ * Configure palette loader
+ */
+export function configurePaletteLoader(config: PaletteManifestConfig): void {
+  globalConfig = { ...globalConfig, ...config };
+}
+
+/**
+ * Dynamically load a palette CSS file
+ *
+ * @param paletteId - The ID of the palette to load (e.g., 'autumn', 'ocean')
+ * @param config - Optional configuration override
+ * @returns Promise that resolves when the palette is loaded
+ */
+export async function loadPalette(
+  paletteId: string,
+  config?: PaletteManifestConfig
+): Promise<void> {
+  // Skip if already loaded
+  if (loadedPalettes.has(paletteId)) {
+    return Promise.resolve();
+  }
+
+  // Return existing loading promise if already loading
+  if (loadingPalettes.has(paletteId)) {
+    return loadingPalettes.get(paletteId)!;
+  }
+
+  // Create new loading promise
+  const loadingPromise = loadPaletteInternal(paletteId, config);
+
+  // Store the loading promise
+  loadingPalettes.set(paletteId, loadingPromise);
+
+  return loadingPromise;
+}
+
+/**
+ * Internal palette loading logic
+ */
+async function loadPaletteInternal(
+  paletteId: string,
+  config?: PaletteManifestConfig
+): Promise<void> {
+  const finalConfig = { ...globalConfig, ...config };
+
+  // Don't load the default palette as it's already inlined in QwickApp.css
+  if (paletteId === 'default') {
+    loadedPalettes.add(paletteId);
+    loadingPalettes.delete(paletteId);
+    return;
+  }
+
+  // Check if we're in a browser environment
+  if (typeof document === 'undefined') {
+    // SSR environment - mark as loaded and continue
+    loadedPalettes.add(paletteId);
+    loadingPalettes.delete(paletteId);
+    return;
+  }
+
+  // Check if the palette link already exists
+  const existingLink = document.querySelector(`link[data-palette-id="${paletteId}"]`);
+  if (existingLink) {
+    loadedPalettes.add(paletteId);
+    loadingPalettes.delete(paletteId);
+    return;
+  }
+
+  try {
+    // Get palette metadata from manifest
+    const paletteEntry = await getPaletteFromManifest(paletteId, finalConfig);
+
+    if (!paletteEntry) {
+      // Palette not found in manifest
+      if ((import.meta as Record<string, unknown>).env?.DEV) {
+        console.warn(
+          `[PaletteLoader] Palette "${paletteId}" not found in manifest. ` +
+          `Available palettes will be limited. Falling back to default palette.`
+        );
+      }
+      loadedPalettes.add(paletteId);
+      loadingPalettes.delete(paletteId);
+      return;
+    }
+
+    // Skip if inlined (already available)
+    if (paletteEntry.inlined) {
+      loadedPalettes.add(paletteId);
+      loadingPalettes.delete(paletteId);
+      return;
+    }
+
+    // Determine which CSS file to use (minified in production, unminified in dev)
+    const isDevelopment = (import.meta as Record<string, unknown>).env?.DEV ?? false;
+    const useMinified = !isDevelopment && paletteEntry.fileMinified;
+    const filename = useMinified ? paletteEntry.fileMinified : paletteEntry.file;
+
+    // Build list of URLs to try
+    const urlsToTry: string[] = [];
+
+    // Add remote CDN URLs if enabled
+    if (finalConfig.enableRemote) {
+      urlsToTry.push(`${DEFAULT_CDN_URLS[0]}${filename}`);
+    }
+
+    // Add local URL
+    urlsToTry.push(`${DEFAULT_CDN_URLS[1]}${filename}`);
+
+    // Try loading from each URL in order
+    let loaded = false;
+    for (const url of urlsToTry) {
+      const success = await tryLoadPaletteFromUrl(url, paletteId);
+      if (success) {
+        loaded = true;
+        break;
+      }
+    }
+
+    if (!loaded) {
+      // All attempts failed
+      if ((import.meta as Record<string, unknown>).env?.DEV) {
+        console.warn(
+          `[PaletteLoader] Failed to load palette "${paletteId}" from all sources. ` +
+          `Falling back to default palette. Tried URLs:`,
+          urlsToTry
+        );
+      }
+    }
+
+    loadedPalettes.add(paletteId);
+    loadingPalettes.delete(paletteId);
+  } catch (error) {
+    if ((import.meta as Record<string, unknown>).env?.DEV) {
+      console.error(`[PaletteLoader] Error loading palette "${paletteId}":`, error);
+    }
+    loadedPalettes.add(paletteId);
+    loadingPalettes.delete(paletteId);
+  }
+}
+
+/**
+ * Try to load a palette from a specific URL
+ */
+function tryLoadPaletteFromUrl(url: string, paletteId: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = url;
+    link.setAttribute('data-palette-id', paletteId);
+
+    link.onload = () => {
+      resolve(true);
+    };
+
+    link.onerror = () => {
+      // Remove failed link
+      document.head.removeChild(link);
+      resolve(false);
+    };
+
+    document.head.appendChild(link);
+  });
+}
+
+/**
+ * Preload multiple palettes at once
+ * @param paletteIds - Array of palette IDs to preload
+ * @param config - Optional configuration
+ */
+export async function preloadPalettes(
+  paletteIds: string[],
+  config?: PaletteManifestConfig
+): Promise<void> {
+  await Promise.all(paletteIds.map(id => loadPalette(id, config)));
+}
+
+/**
+ * Check if a palette is loaded
+ * @param paletteId - The palette ID to check
+ */
+export function isPaletteLoaded(paletteId: string): boolean {
+  return loadedPalettes.has(paletteId);
+}
+
+/**
+ * Clear loaded palettes cache (useful for testing)
+ */
+export function clearPaletteCache(): void {
+  loadedPalettes.clear();
+  loadingPalettes.clear();
+}