@qwickapps/react-framework 1.3.0

package/src/contexts/DimensionsContext.tsx

@@ -0,0 +1,154 @@
+/**
+ * Dimensions Context - Responsive design tokens for typography, spacing, and sizing
+ * 
+ * Provides consistent design tokens that adapt to screen size and user preferences.
+ * Works alongside MUI theme system for comprehensive responsive design.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { createContext, useContext, useEffect, useState } from 'react';
+
+export interface DimensionTokens {
+  // Border radius
+  borderRadius: {
+    small: number;
+    medium: number;
+    large: number;
+  };
+  
+  // Typography scale (multipliers for MUI typography)
+  typography: {
+    scaleMultiplier: number;
+    lineHeightMultiplier: number;
+  };
+  
+  // Spacing scale (multipliers for MUI spacing)
+  spacing: {
+    scaleMultiplier: number;
+  };
+  
+  // Component sizing
+  component: {
+    buttonHeight: number;
+    inputHeight: number;
+    iconSize: number;
+  };
+}
+
+export interface DimensionsContextValue {
+  tokens: DimensionTokens;
+  screenSize: 'mobile' | 'tablet' | 'desktop';
+  isCompact: boolean;
+  setCompactMode: (compact: boolean) => void;
+}
+
+const DimensionsContext = createContext<DimensionsContextValue | undefined>(undefined);
+
+// Default dimension tokens
+const getDefaultTokens = (screenSize: 'mobile' | 'tablet' | 'desktop', isCompact: boolean): DimensionTokens => {
+  const compactMultiplier = isCompact ? 0.9 : 1.0;
+  
+  let baseTokens: DimensionTokens;
+  
+  switch (screenSize) {
+    case 'mobile':
+      baseTokens = {
+        borderRadius: { small: 6, medium: 10, large: 14 },
+        typography: { scaleMultiplier: 0.9, lineHeightMultiplier: 1.0 },
+        spacing: { scaleMultiplier: 0.8 },
+        component: { buttonHeight: 44, inputHeight: 44, iconSize: 20 },
+      };
+      break;
+    case 'tablet':
+      baseTokens = {
+        borderRadius: { small: 8, medium: 12, large: 16 },
+        typography: { scaleMultiplier: 0.95, lineHeightMultiplier: 1.0 },
+        spacing: { scaleMultiplier: 0.9 },
+        component: { buttonHeight: 40, inputHeight: 40, iconSize: 22 },
+      };
+      break;
+    case 'desktop':
+    default:
+      baseTokens = {
+        borderRadius: { small: 8, medium: 12, large: 16 },
+        typography: { scaleMultiplier: 1.0, lineHeightMultiplier: 1.0 },
+        spacing: { scaleMultiplier: 1.0 },
+        component: { buttonHeight: 36, inputHeight: 36, iconSize: 24 },
+      };
+      break;
+  }
+  
+  // Apply compact mode multiplier
+  return {
+    ...baseTokens,
+    typography: {
+      scaleMultiplier: baseTokens.typography.scaleMultiplier * compactMultiplier,
+      lineHeightMultiplier: baseTokens.typography.lineHeightMultiplier * compactMultiplier,
+    },
+    spacing: {
+      scaleMultiplier: baseTokens.spacing.scaleMultiplier * compactMultiplier,
+    },
+    component: {
+      buttonHeight: Math.round(baseTokens.component.buttonHeight * compactMultiplier),
+      inputHeight: Math.round(baseTokens.component.inputHeight * compactMultiplier),
+      iconSize: Math.round(baseTokens.component.iconSize * compactMultiplier),
+    },
+  };
+};
+
+export interface DimensionsProviderProps {
+  children: React.ReactNode;
+  defaultCompactMode?: boolean;
+}
+
+export const DimensionsProvider: React.FC<DimensionsProviderProps> = ({
+  children,
+  defaultCompactMode = false,
+}) => {
+  const [screenSize, setScreenSize] = useState<'mobile' | 'tablet' | 'desktop'>('desktop');
+  const [isCompact, setIsCompact] = useState(defaultCompactMode);
+
+  // Detect screen size
+  useEffect(() => {
+    const updateScreenSize = () => {
+      const width = window.innerWidth;
+      if (width < 768) {
+        setScreenSize('mobile');
+      } else if (width < 1024) {
+        setScreenSize('tablet');
+      } else {
+        setScreenSize('desktop');
+      }
+    };
+
+    updateScreenSize();
+    window.addEventListener('resize', updateScreenSize);
+    return () => window.removeEventListener('resize', updateScreenSize);
+  }, []);
+
+  const tokens = getDefaultTokens(screenSize, isCompact);
+
+  const contextValue: DimensionsContextValue = {
+    tokens,
+    screenSize,
+    isCompact,
+    setCompactMode: setIsCompact,
+  };
+
+  return (
+    <DimensionsContext.Provider value={contextValue}>
+      {children}
+    </DimensionsContext.Provider>
+  );
+};
+
+export const useDimensions = (): DimensionsContextValue => {
+  const context = useContext(DimensionsContext);
+  if (context === undefined) {
+    throw new Error('useDimensions must be used within a DimensionsProvider');
+  }
+  return context;
+};
+
+export default DimensionsProvider;

package/src/contexts/PaletteContext.tsx

@@ -0,0 +1,217 @@
+/**
+ * Palette Context - Manages color palette state and switching
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { createContext, useContext, useState, useEffect, ReactNode } from 'react';
+import { AllPalettes } from '../palettes';
+import { 
+  loadUserPalettePreference, 
+  saveUserPalettePreference, 
+  clearUserPalettePreference 
+} from '../utils/persistenceUtils';
+
+// Type definitions
+export interface PaletteConfig {
+  id: string;
+  name: string;
+  description: string;
+  primaryColor: string;
+}
+
+export interface PaletteContextValue {
+  /** The palette currently being applied to the UI (resolved from preferred/default) */
+  currentPalette: string;
+  /** The user's preferred palette setting, or null if not set */
+  preferredPalette: string | null;
+  /** List of all available palettes */
+  availablePalettes: PaletteConfig[];
+  /** Whether preferences are persisted to localStorage */
+  isPersistent: boolean;
+  
+  // Palette preference management
+  /** Set user's preferred palette (saves to localStorage if persistent) */
+  setPreferredPalette: (paletteId: string) => void;
+  /** Clear user's preferred palette (removes from localStorage) */
+  clearPreferredPalette: () => void;
+  /** Get user's preferred palette */
+  getPreferredPalette: () => string | null;
+  
+  // Current palette management (for admin/preview overrides)
+  /** Get currently applied palette */
+  getCurrentPalette: () => string;
+  /** Temporarily override current palette (does not affect user preference) */
+  setCurrentPalette: (paletteId: string) => void;
+}
+
+export interface PaletteProviderProps {
+  children: ReactNode;
+  /** 
+   * App identifier for generating unique storage key, or persistence strategy.
+   * - string: Use as app identifier to generate key 'appId.palette'
+   * - true (default): Use default key 'qwickapps-react-framework-palette'
+   * - false: Disable persistence (session-only)
+   * @example 'com.mycompany.myapp' | true | false
+   */
+  appId?: string | true | false;
+  /**
+   * Default palette for the application when no user preference exists. The default is 'default'.
+   * This can be overridden by user settings.
+   * @example 'ocean' | 'autumn' | 'spring' | 'winter' | 'default'
+   */
+  defaultPalette?: string;
+}
+
+// Create context with proper typing
+const PaletteContext = createContext<PaletteContextValue | null>(null);
+
+export const usePalette = (): PaletteContextValue => {
+  const context = useContext(PaletteContext);
+  if (!context) {
+    throw new Error('usePalette must be used within a PaletteProvider');
+  }
+  return context;
+};
+
+// Use imported palette configurations
+const AVAILABLE_PALETTES: PaletteConfig[] = AllPalettes;
+
+/**
+ * Resolve the default palette ID based on user preference or fallback
+ * @param paletteId - The desired palette ID
+ * @param warn - Whether to issue a warning for invalid palette IDs
+ * @returns The resolved palette ID
+ */
+const resolveDefaultPalette = (paletteId: string | undefined, warn = true): string => {
+  if (paletteId && AVAILABLE_PALETTES.some(p => p.id === paletteId)) {
+    return paletteId;
+  }
+  if (warn) {
+    console.warn(`[PaletteProvider] Invalid defaultPalette '${paletteId}'. Using 'default'.`);
+  }
+  return 'default';
+};
+
+export const PaletteProvider: React.FC<PaletteProviderProps> = ({ 
+  children, 
+  appId,
+  defaultPalette = 'default'
+}) => {
+  // Determine storage key based on appId
+  const actualStorageKey = React.useMemo(() => {
+    if (appId === false) {
+      return null; // No persistence
+    }
+    
+    if (typeof appId === 'string') {
+      return `${appId}.palette`;
+    }
+    
+    // appId is true or undefined - use default key with warning
+    const defaultKey = 'qwickapps-react-framework-palette';
+    console.warn(
+      `[PaletteProvider] Using default storage key '${defaultKey}'. ` +
+      `Consider providing an appId for production apps to avoid conflicts. ` +
+      `Example: <PaletteProvider appId="com.mycompany.myapp">`
+    );
+    
+    return defaultKey;
+  }, [appId]);
+  
+  // Available palette IDs for validation
+  const availablePaletteIds = AVAILABLE_PALETTES.map(p => p.id);
+
+  // User's preferred palette (what they explicitly chose)
+  const [preferredPalette, setPreferredPaletteState] = useState<string | null>(() => {
+    return loadUserPalettePreference(actualStorageKey, availablePaletteIds);
+  });
+
+  // Current palette being applied (resolved from preferred/default)
+  const [currentPalette, setCurrentPaletteState] = useState<string>(() => {
+    const userPreference = loadUserPalettePreference(actualStorageKey, availablePaletteIds);
+    return userPreference || resolveDefaultPalette(defaultPalette);
+  });
+
+  // Apply palette to document root immediately and on changes
+  useEffect(() => {
+    if (typeof document !== 'undefined') {
+      document.documentElement.setAttribute('data-palette', currentPalette);
+      
+      // Dispatch custom event to notify theme system (with small delay to ensure CSS is applied)
+      setTimeout(() => {
+        const event = new CustomEvent('palette-changed', {
+          detail: { palette: currentPalette }
+        });
+        window.dispatchEvent(event);
+      }, 50);
+    }
+  }, [currentPalette]);
+
+  // Note: We no longer automatically save to localStorage on every change
+  // localStorage is only updated via setPreferredPalette() method
+
+  // Palette preference management methods
+  const setPreferredPalette = (paletteId: string): void => {
+    const targetPalette = AVAILABLE_PALETTES.find(p => p.id === paletteId);
+    if (targetPalette) {
+      setPreferredPaletteState(paletteId);
+      setCurrentPaletteState(paletteId);
+      saveUserPalettePreference(actualStorageKey, paletteId);
+    } else {
+      console.warn(`Palette "${paletteId}" not found. Available palettes:`, AVAILABLE_PALETTES.map(p => p.id));
+    }
+  };
+
+  const clearPreferredPalette = (): void => {
+    setPreferredPaletteState(null);
+    clearUserPalettePreference(actualStorageKey);
+    
+    // Reset to default palette
+    const fallbackPalette = resolveDefaultPalette(defaultPalette, false);
+    setCurrentPaletteState(fallbackPalette);
+  };
+
+  const getPreferredPalette = (): string | null => {
+    return preferredPalette;
+  };
+
+  // Current palette management methods (for admin/preview overrides)
+  const getCurrentPalette = (): string => {
+    return currentPalette;
+  };
+
+  const setCurrentPalette = (paletteId: string): void => {
+    const targetPalette = AVAILABLE_PALETTES.find(p => p.id === paletteId);
+    if (targetPalette) {
+      setCurrentPaletteState(paletteId);
+      // Note: This does NOT update preferredPalette or localStorage
+    } else {
+      console.warn(`Palette "${paletteId}" not found. Available palettes:`, AVAILABLE_PALETTES.map(p => p.id));
+    }
+  };
+
+  const value: PaletteContextValue = {
+    currentPalette,
+    preferredPalette,
+    availablePalettes: AVAILABLE_PALETTES,
+    isPersistent: actualStorageKey !== null,
+    
+    // Palette preference management
+    setPreferredPalette,
+    clearPreferredPalette,
+    getPreferredPalette,
+    
+    // Current palette management
+    getCurrentPalette,
+    setCurrentPalette,
+  };
+
+  return (
+    <PaletteContext.Provider value={value}>
+      {children}
+    </PaletteContext.Provider>
+  );
+};
+
+export default PaletteProvider;

package/src/contexts/QwickAppContext.tsx

@@ -0,0 +1,95 @@
+/**
+ * QwickApp Context - Application-level context for QwickApp configuration
+ * 
+ * Provides app-level state and configuration that can be accessed by components
+ * within the QwickApp provider hierarchy.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import type { MenuItem } from '../components/menu';
+import type { ScaffoldProps } from '../components/Scaffold';
+
+export interface QwickAppProps {
+  /** Application name displayed in header/title */
+  appName: string;
+  /** Custom logo component - overrides the default logo */
+  logo?: React.ReactNode;
+  /** App identifier used for storage keys */
+  appId?: string | true | false;
+  /** Application version string */
+  appVersion?: string;
+  /** Theme mode preference (light/dark/auto) */
+  defaultTheme?: 'light' | 'dark' | 'system';
+  /** Default palette to use */
+  defaultPalette?: string;
+  /** Enable scaffolding with navigation system (default: false) */
+  enableScaffolding?: boolean;
+  /** Primary navigation items for scaffolding */
+  navigationItems?: MenuItem[];
+  /** App bar configuration for scaffolding */
+  appBar?: ScaffoldProps['appBar'];
+  /** Whether to show app bar when scaffolding is enabled (default: true) */
+  showAppBar?: boolean;
+  /** Custom app bar height when scaffolding is enabled */
+  appBarHeight?: number;
+  /** Whether to show theme switcher in app bar (default: false) */
+  showThemeSwitcher?: boolean;
+  /** Whether to show palette switcher in app bar (default: false) */
+  showPaletteSwitcher?: boolean;
+  /** Callback when logo is clicked */
+  onLogoClick?: () => void;
+}
+
+export interface QwickAppContextValue {
+  /** Application name */
+  appName: string;
+  /** Custom logo component */
+  logo?: React.ReactNode;
+  /** App identifier used for storage keys */
+  appId?: string | true | false;
+  /** Whether scaffolding is enabled */
+  enableScaffolding: boolean;
+  /** Navigation items for scaffolding */
+  navigationItems: MenuItem[];
+  /** App bar configuration */
+  appBar?: ScaffoldProps['appBar'];
+  /** Whether to show app bar */
+  showAppBar: boolean;
+  /** App bar height */
+  appBarHeight: number;
+  /** Whether to show theme switcher in app bar */
+  showThemeSwitcher: boolean;
+  /** Whether to show palette switcher in app bar */
+  showPaletteSwitcher: boolean;
+  /** Callback when logo is clicked */
+  onLogoClick?: () => void;
+  /** Update app configuration (excludes appName and appId for security) */
+  updateConfig: (updates: Partial<Pick<QwickAppProps, 'logo' | 'enableScaffolding' | 'navigationItems' | 'appBar' | 'showAppBar' | 'appBarHeight' | 'showThemeSwitcher' | 'showPaletteSwitcher'>>) => void;
+  // Navigation removed - now handled by AuthProvider when routing needed
+}
+
+const QwickAppContext = React.createContext<QwickAppContextValue>({
+  appName: 'QwickApps',
+  logo: undefined,
+  appId: true,
+  enableScaffolding: false,
+  navigationItems: [],
+  appBar: undefined,
+  showAppBar: true,
+  appBarHeight: 64,
+  showThemeSwitcher: false,
+  showPaletteSwitcher: false,
+  updateConfig: () => {},
+});
+
+export { QwickAppContext };
+
+export const useQwickApp = (): QwickAppContextValue => {
+  const context = React.useContext(QwickAppContext);
+  if (!context) {
+    throw new Error('useQwickApp must be used within a QwickApp provider');
+  }
+  return context;
+};