@qwickapps/react-framework 1.4.8 → 1.5.0

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();
+}

package/src/utils/paletteManifest.ts

@@ -0,0 +1,268 @@
+/**
+ * Palette Manifest Utilities - Fetch and manage palette manifests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Manifest structure
+export interface PaletteManifestEntry {
+  id: string;
+  name: string;
+  description: string;
+  author?: string;
+  license?: string;
+  version: string;
+  file: string;
+  fileMinified?: string;
+  thumbnail?: string;
+  primaryColor: string;
+  inlined?: boolean;
+}
+
+export interface PaletteManifest {
+  version: string;
+  palettes: PaletteManifestEntry[];
+}
+
+// Configuration
+export interface PaletteManifestConfig {
+  /** Enable/disable remote palette loading */
+  enableRemote?: boolean;
+  /** Custom remote URL for palette manifest */
+  remoteUrl?: string;
+  /** Custom local path for palette manifest */
+  localPath?: string;
+}
+
+// Default configuration
+const DEFAULT_CONFIG: Required<PaletteManifestConfig> = {
+  enableRemote: true,
+  remoteUrl: 'https://qwickapps.com/palettes/manifest.json',
+  localPath: '/palettes/manifest.json',
+};
+
+// Cache for loaded manifests
+let cachedManifest: PaletteManifest | null = null;
+let manifestLoadAttempted = false;
+
+/**
+ * Fetch a manifest from a URL
+ */
+async function fetchManifestFromUrl(url: string): Promise<PaletteManifest | null> {
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Accept': 'application/json',
+      },
+      // Short timeout for better UX
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (!response.ok) {
+      console.warn(`[PaletteManifest] Failed to fetch from ${url}: ${response.status} ${response.statusText}`);
+      return null;
+    }
+
+    const manifest: PaletteManifest = await response.json();
+
+    // Basic validation
+    if (!manifest.version || !Array.isArray(manifest.palettes)) {
+      console.warn(`[PaletteManifest] Invalid manifest structure from ${url}`);
+      return null;
+    }
+
+    return manifest;
+  } catch (error) {
+    // Only log in development
+    if ((import.meta as Record<string, unknown>).env?.DEV) {
+      console.warn(`[PaletteManifest] Error fetching from ${url}:`, error);
+    }
+    return null;
+  }
+}
+
+/**
+ * Merge multiple manifests, with later manifests overriding earlier ones
+ */
+function mergeManifests(...manifests: (PaletteManifest | null)[]): PaletteManifest {
+  const paletteMap = new Map<string, PaletteManifestEntry>();
+  let latestVersion = '0.0.0';
+
+  for (const manifest of manifests) {
+    if (!manifest) continue;
+
+    // Track latest version
+    if (manifest.version > latestVersion) {
+      latestVersion = manifest.version;
+    }
+
+    // Merge palettes (later manifests override)
+    for (const palette of manifest.palettes) {
+      paletteMap.set(palette.id, palette);
+    }
+  }
+
+  return {
+    version: latestVersion,
+    palettes: Array.from(paletteMap.values()),
+  };
+}
+
+/**
+ * Load palette manifest from configured sources
+ */
+export async function loadPaletteManifest(
+  config: PaletteManifestConfig = {}
+): Promise<PaletteManifest> {
+  // Return cached manifest if available
+  if (cachedManifest) {
+    return cachedManifest;
+  }
+
+  // Only attempt once
+  if (manifestLoadAttempted) {
+    return getFallbackManifest();
+  }
+
+  manifestLoadAttempted = true;
+
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+  const manifests: (PaletteManifest | null)[] = [];
+
+  // Try remote manifest first (if enabled)
+  if (finalConfig.enableRemote) {
+    const remoteManifest = await fetchManifestFromUrl(finalConfig.remoteUrl);
+    manifests.push(remoteManifest);
+  }
+
+  // Try local manifest
+  if (typeof window !== 'undefined') {
+    const localManifest = await fetchManifestFromUrl(finalConfig.localPath);
+    manifests.push(localManifest);
+  }
+
+  // Merge all loaded manifests
+  const mergedManifest = mergeManifests(...manifests);
+
+  // If no manifests loaded, use fallback
+  if (mergedManifest.palettes.length === 0) {
+    if ((import.meta as Record<string, unknown>).env?.DEV) {
+      console.warn('[PaletteManifest] No manifests loaded, using fallback');
+    }
+    cachedManifest = getFallbackManifest();
+    return cachedManifest;
+  }
+
+  cachedManifest = mergedManifest;
+  return cachedManifest;
+}
+
+/**
+ * Get fallback manifest with built-in palettes
+ */
+function getFallbackManifest(): PaletteManifest {
+  return {
+    version: '1.4.9',
+    palettes: [
+      {
+        id: 'default',
+        name: 'Default',
+        description: 'Classic blue and neutral color scheme',
+        version: '1.4.9',
+        file: 'PaletteDefault.css',
+        primaryColor: '#007bff',
+        inlined: true,
+      },
+      {
+        id: 'autumn',
+        name: 'Autumn',
+        description: 'Warm oranges, golden yellows, and earthy browns',
+        version: '1.4.9',
+        file: 'PaletteAutumn.css',
+        primaryColor: '#ea580c',
+        inlined: false,
+      },
+      {
+        id: 'cosmic',
+        name: 'Cosmic',
+        description: 'Modern purple gradient for creative and tech brands',
+        version: '1.4.9',
+        file: 'PaletteCosmic.css',
+        primaryColor: '#8b5cf6',
+        inlined: false,
+      },
+      {
+        id: 'ocean',
+        name: 'Ocean',
+        description: 'Deep blues, aqua teals, and seafoam greens',
+        version: '1.4.9',
+        file: 'PaletteOcean.css',
+        primaryColor: '#0891b2',
+        inlined: false,
+      },
+      {
+        id: 'spring',
+        name: 'Spring',
+        description: 'Fresh greens, soft pinks, and bright yellows',
+        version: '1.4.9',
+        file: 'PaletteSpring.css',
+        primaryColor: '#16a34a',
+        inlined: false,
+      },
+      {
+        id: 'winter',
+        name: 'Winter',
+        description: 'Cool blues, icy whites, and frosty grays',
+        version: '1.4.9',
+        file: 'PaletteWinter.css',
+        primaryColor: '#0077be',
+        inlined: false,
+      },
+    ],
+  };
+}
+
+/**
+ * Get a specific palette from the manifest
+ */
+export async function getPaletteFromManifest(
+  paletteId: string,
+  config?: PaletteManifestConfig
+): Promise<PaletteManifestEntry | null> {
+  const manifest = await loadPaletteManifest(config);
+  return manifest.palettes.find(p => p.id === paletteId) || null;
+}
+
+/**
+ * Get all available palettes
+ */
+export async function getAvailablePalettes(
+  config?: PaletteManifestConfig
+): Promise<PaletteManifestEntry[]> {
+  const manifest = await loadPaletteManifest(config);
+  return manifest.palettes;
+}
+
+/**
+ * Clear the cached manifest (useful for testing)
+ */
+export function clearManifestCache(): void {
+  cachedManifest = null;
+  manifestLoadAttempted = false;
+}
+
+/**
+ * Register a custom palette dynamically
+ */
+export function registerCustomPalette(palette: PaletteManifestEntry): void {
+  if (!cachedManifest) {
+    cachedManifest = getFallbackManifest();
+  }
+
+  // Remove existing palette with same ID
+  cachedManifest.palettes = cachedManifest.palettes.filter(p => p.id !== palette.id);
+
+  // Add new palette
+  cachedManifest.palettes.push(palette);
+}

package/src/utils/paletteUtils.ts

@@ -17,6 +17,9 @@ export const AVAILABLE_PALETTES: PaletteConfig[] = [
  * Get the current palette from CSS variables
  */
 export const getCurrentPalette = (): string => {
+  if (typeof document === 'undefined') {
+    return 'default'; // SSR fallback
+  }
   const root = document.documentElement;
   return root.getAttribute('data-palette') || 'default';
 };
@@ -25,9 +28,12 @@ export const getCurrentPalette = (): string => {
  * Set palette and update CSS variables
  */
 export const setPalette = (palette: string): void => {
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    return; // SSR - no-op
+  }
   const root = document.documentElement;
   root.setAttribute('data-palette', palette);
-  
+
   // Trigger custom event for palette change
   window.dispatchEvent(new CustomEvent('paletteChange', { detail: { palette } }));
 };
@@ -51,6 +57,9 @@ export const getPaletteConfig = (paletteId: string): PaletteConfig | undefined =
  * Initialize palette system
  */
 export const initializePalette = (): void => {
+  if (typeof localStorage === 'undefined') {
+    return; // SSR - no-op
+  }
   const savedPalette = localStorage.getItem('palette') || 'default';
   setPalette(savedPalette);
 };
@@ -59,6 +68,9 @@ export const initializePalette = (): void => {
  * Save palette preference to localStorage
  */
 export const savePalettePreference = (palette: string): void => {
+  if (typeof localStorage === 'undefined') {
+    return; // SSR - no-op
+  }
   localStorage.setItem('palette', palette);
   setPalette(palette);
 };
@@ -67,6 +79,9 @@ export const savePalettePreference = (palette: string): void => {
  * Get CSS custom property value
  */
 export const getCSSVariable = (property: string): string => {
+  if (typeof document === 'undefined') {
+    return ''; // SSR fallback
+  }
   return getComputedStyle(document.documentElement).getPropertyValue(property).trim();
 };
 
@@ -74,5 +89,8 @@ export const getCSSVariable = (property: string): string => {
  * Set CSS custom property value
  */
 export const setCSSVariable = (property: string, value: string): void => {
+  if (typeof document === 'undefined') {
+    return; // SSR - no-op
+  }
   document.documentElement.style.setProperty(property, value);
 };

package/src/utils/reactUtils.tsx

@@ -1,54 +1,55 @@
 /**
  * QwickApps React Framework - React Utilities
  * This module provides utility functions for React components in the QwickApps React Framework.
- * 
+ *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
 import { ReactNode } from 'react';
-import { useLocation, useNavigate } from 'react-router-dom';
 
-/** Location type for React Router */
+/** Location type for routing */
 type LocationType = { pathname: string, search: string, hash: string };
 
 /**
- * Custom hook to get the current location
- * @returns {object | undefined} - The location object if React Router is available, otherwise undefined
+ * Get the current location from browser or undefined in SSR
+ * Works without relying on routing libraries
+ * @returns {object | undefined} - The location object if in browser, otherwise undefined
  */
 export const useSafeLocation = (): LocationType | undefined => {
-  try {
-    return useLocation();
-  } catch (error) {
-    console.warn('React Router context not available:', error);
-    return undefined;
+  // Use browser location if available (works in any React app)
+  if (typeof window !== 'undefined') {
+    return {
+      pathname: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash
+    };
   }
+  return undefined;
 };
 
 /**
- * Custom hook to get the navigate function with fallback
- * @returns {Function} - The navigate function (React Router or window.location fallback)
+ * Navigate function type
+ */
+export type NavigateFunction = (to: string | number, options?: unknown) => void;
+
+/**
+ * Get a navigation function with fallback to window.location
+ * Works without relying on routing libraries
+ * @returns {NavigateFunction} - The navigate function
  */
-export const useSafeNavigate = (): Function => {
-  try {
-    const navigate = useNavigate();
-    return navigate;
-  } catch (error) {
-    // Return fallback function that uses window.location.href
-    return (to: string | number, options?: any) => {
-      console.warn('React Router context not available, using window.location as fallback to navigate to:', to);
-      if (typeof to === 'string') {
-        // Handle relative and absolute paths
-        if (typeof window !== 'undefined') {
-          window.location.href = to;
-        }
-      } else if (typeof to === 'number') {
-        // Handle history.go() equivalent
-        if (typeof window !== 'undefined' && window.history) {
-          window.history.go(to);
-        }
+export const useSafeNavigate = (): NavigateFunction => {
+  // Return function that uses window.location
+  return (to: string | number) => {
+    if (typeof to === 'string') {
+      if (typeof window !== 'undefined') {
+        window.location.href = to;
       }
-    };
-  }
+    } else if (typeof to === 'number') {
+      if (typeof window !== 'undefined' && window.history) {
+        window.history.go(to);
+      }
+    }
+  };
 };
 
 /**
@@ -77,7 +78,7 @@ export function extractTextFromReactNode(node: ReactNode): string {
 
   // For React elements, try to extract text content
   if (typeof node === 'object' && node !== null && 'props' in node) {
-    const element = node as any;
+    const element = node as { props?: { children?: ReactNode } };
     if (element.props && element.props.children) {
       return extractTextFromReactNode(element.props.children);
     }