@qwickapps/react-framework 1.5.5 → 1.5.7

package/src/contexts/NavigationContext.tsx

@@ -0,0 +1,168 @@
+/**
+ * Navigation Context - Smart navigation that auto-detects React Router
+ *
+ * Provides navigation functions that work with React Router when available,
+ * falling back to window.location for non-router apps or SSR.
+ *
+ * Usage:
+ * - Wrap your app with NavigationProvider (done automatically by QwickApp)
+ * - Use useNavigation() hook to get navigate function and location
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+import {
+  useNavigate,
+  useLocation,
+  useInRouterContext,
+} from 'react-router-dom';
+
+/**
+ * Location type matching React Router's location shape
+ */
+export interface NavigationLocation {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+/**
+ * Navigate function type
+ */
+export type NavigateFunction = (to: string | number) => void;
+
+/**
+ * Navigation context value
+ */
+export interface NavigationContextValue {
+  navigate: NavigateFunction;
+  location: NavigationLocation | undefined;
+}
+
+const NavigationContext = createContext<NavigationContextValue | null>(null);
+
+/**
+ * Internal provider that uses React Router hooks
+ * Only rendered when we're inside a Router context
+ */
+function ReactRouterNavigationProvider({ children }: { children: ReactNode }) {
+  const reactRouterNavigate = useNavigate();
+  const reactRouterLocation = useLocation();
+
+  const navigate: NavigateFunction = (to) => {
+    if (typeof to === 'string') {
+      reactRouterNavigate(to);
+    } else if (typeof to === 'number') {
+      reactRouterNavigate(to);
+    }
+  };
+
+  // Defensive check for location - fall back to window.location if React Router's location is undefined
+  const location: NavigationLocation | undefined = reactRouterLocation
+    ? {
+        pathname: reactRouterLocation.pathname,
+        search: reactRouterLocation.search,
+        hash: reactRouterLocation.hash,
+      }
+    : typeof window !== 'undefined'
+      ? {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        }
+      : undefined;
+
+  return (
+    <NavigationContext.Provider value={{ navigate, location }}>
+      {children}
+    </NavigationContext.Provider>
+  );
+}
+
+/**
+ * Internal provider that uses window.location fallback
+ * Used when not inside a React Router context
+ */
+function FallbackNavigationProvider({ children }: { children: ReactNode }) {
+  const navigate: NavigateFunction = (to) => {
+    if (typeof window === 'undefined') return;
+
+    if (typeof to === 'string') {
+      window.location.href = to;
+    } else if (typeof to === 'number') {
+      window.history.go(to);
+    }
+  };
+
+  const location: NavigationLocation | undefined =
+    typeof window !== 'undefined'
+      ? {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        }
+      : undefined;
+
+  return (
+    <NavigationContext.Provider value={{ navigate, location }}>
+      {children}
+    </NavigationContext.Provider>
+  );
+}
+
+/**
+ * Smart Navigation Provider
+ *
+ * Automatically detects if the app is inside a React Router context:
+ * - If inside Router: uses React Router's useNavigate/useLocation (respects basename)
+ * - If outside Router: falls back to window.location
+ *
+ * This is included automatically by QwickApp - you don't need to add it manually.
+ */
+export function NavigationProvider({ children }: { children: ReactNode }) {
+  // Check if we're inside a React Router using the official hook
+  // This is more reliable than checking internal UNSAFE contexts
+  const isInRouter = useInRouterContext();
+
+  if (isInRouter) {
+    // We're inside a Router, use React Router's navigation
+    return (
+      <ReactRouterNavigationProvider>{children}</ReactRouterNavigationProvider>
+    );
+  }
+
+  // Not inside a Router, use window.location fallback
+  return <FallbackNavigationProvider>{children}</FallbackNavigationProvider>;
+}
+
+/**
+ * Hook to access navigation functions
+ *
+ * @returns Object containing navigate function and current location
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { navigate, location } = useNavigation();
+ *
+ *   const handleClick = () => {
+ *     navigate('/dashboard');
+ *   };
+ *
+ *   return <button onClick={handleClick}>Go to Dashboard</button>;
+ * }
+ * ```
+ */
+export function useNavigation(): NavigationContextValue {
+  const context = useContext(NavigationContext);
+
+  if (!context) {
+    throw new Error(
+      'useNavigation must be used within a NavigationProvider. ' +
+        'Make sure your component is wrapped in QwickApp or NavigationProvider.'
+    );
+  }
+
+  return context;
+}

package/src/contexts/index.ts

@@ -3,6 +3,8 @@ export { DataProvider, t, T, useData, useDataContext, useDataProvider, useResolv
 export type { DataProviderProps } from './DataContext';
 export { DimensionsProvider, useDimensions } from './DimensionsContext';
 export type { DimensionsContextValue, DimensionTokens } from './DimensionsContext';
+export { NavigationProvider, useNavigation } from './NavigationContext';
+export type { NavigateFunction, NavigationContextValue, NavigationLocation } from './NavigationContext';
 export { PaletteProvider, usePalette } from './PaletteContext';
 export type { PaletteConfig, PaletteContextValue } from './PaletteContext';
 export { ThemeProvider, useTheme } from './ThemeContext';

package/src/utils/iconMap.tsx

@@ -1,80 +1,101 @@
 /**
  * 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.
- * 
+ *
+ * Features:
+ * - Static map for commonly used icons with emoji support
+ * - Fallback to HelpOutline icon for unmapped icons (with console warning)
+ * - Runtime icon registration via registerIcon() for app-specific icons
+ *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
 import React from 'react';
+
+// Material UI Icons - sorted alphabetically
 import {
+  AccountCircle,
+  Add,
+  Architecture,
+  ArrowBack,
+  ArrowForward,
   Article,
-  Home,
+  AttachMoney,
+  Autorenew,
+  Block,
   Book,
-  Download,
+  Business,
+  Check,
+  CheckCircle,
+  Close,
+  Cloud,
   CloudDownload,
   CloudUpload,
+  Code,
   Computer,
-  Settings,
+  Construction,
   Dashboard,
+  Delete,
+  Download,
+  Edit,
+  Email,
+  Explore,
+  Favorite,
+  Group,
+  Help,
+  HelpOutline,
+  Home,
   Info,
+  InsertPhoto,
+  IntegrationInstructions,
   Inventory,
   Inventory2,
-  Help,
-  Add,
-  Edit,
-  Delete,
-  Check,
-  Close,
-  ArrowForward,
-  ArrowBack,
+  Key,
+  Layers,
+  LibraryBooks,
+  LocalOffer,
+  Lock,
+  LockOpen,
+  Login,
+  Logout,
+  ManageAccounts,
+  Memory,
   Menu,
-  Search,
-  Favorite,
-  Star,
-  Share,
+  Notifications,
+  People,
+  Person,
+  PersonSearch,
+  Phone,
+  PhotoLibrary,
+  PlayArrow,
+  Psychology,
+  Refresh,
+  Rocket,
+  RotateRight,
+  Route,
   Save,
+  Search,
+  Security,
   Send,
-  Email,
-  Phone,
-  Person,
-  Group,
-  Business,
+  Settings,
+  Share,
+  Shield,
   ShoppingCart,
   Speed,
+  Star,
+  Storage,
   SupportAgent,
+  Sync,
+  TrendingUp,
   Tune,
-  AttachMoney,
-  Lock,
-  LockOpen,
+  VerifiedUser,
   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,
+  Work,
+  WorkspacePremium,
 } from '@mui/icons-material';
 
 /**
@@ -86,139 +107,175 @@ export interface IconMapping {
 }
 
 /**
- * Centralized icon registry mapping icon names to their representations
- * Supports both Material-UI components and emoji for different contexts
+ * Centralized icon registry mapping icon names to their representations.
+ * Sorted alphabetically by category, then by key within each category.
+ *
+ * For icons not in this map, getIconComponent() will return a HelpOutline fallback
+ * and log a warning. Use registerIcon() to add app-specific icons at runtime.
  */
 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
+  // === Actions ===
   add: { emoji: '➕', component: Add },
-  edit: { emoji: '✏️', component: Edit },
-  delete: { emoji: '🗑️', component: Delete },
-  save: { emoji: '💾', component: Save },
   check: { emoji: '✓', component: Check },
+  check_circle: { emoji: '✅', component: CheckCircle },
   close: { emoji: '✕', component: Close },
-  
-  // Navigation
-  arrowforward: { emoji: '→', component: ArrowForward },
-  arrowback: { emoji: '←', component: ArrowBack },
-  
-  // Content
+  delete: { emoji: '🗑️', component: Delete },
+  edit: { emoji: '✏️', component: Edit },
+  refresh: { emoji: '🔄', component: Refresh },
+  rotate_right: { emoji: '🔄', component: RotateRight },
+  save: { emoji: '💾', component: Save },
   search: { emoji: '🔍', component: Search },
+  send: { emoji: '📤', component: Send },
   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
+  sync: { emoji: '🔄', component: Sync },
+
+  // === Authentication & Security ===
+  block: { emoji: '🚫', component: Block },
+  key: { emoji: '🔑', component: Key },
   lock: { emoji: '🔒', component: Lock },
-  lockopen: { emoji: '🔓', component: LockOpen },
+  lock_open: { emoji: '🔓', component: LockOpen },
+  lockopen: { emoji: '🔓', component: LockOpen }, // alias
+  login: { emoji: '🔑', component: Login },
+  logout: { emoji: '🚪', component: Logout },
+  security: { emoji: '🔐', component: Security },
+  shield: { emoji: '🛡️', component: Shield },
+  verified_user: { emoji: '✅', component: VerifiedUser },
   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 },
+  visibility_off: { emoji: '🙈', component: VisibilityOff },
+  visibilityoff: { emoji: '🙈', component: VisibilityOff }, // alias
+  vpn_key: { emoji: '🔐', component: VpnKey },
+
+  // === Business & Commerce ===
+  attach_money: { emoji: '💰', component: AttachMoney },
+  attachmoney: { emoji: '💰', component: AttachMoney }, // alias
+  business: { emoji: '🏢', component: Business },
+  cart: { emoji: '🛒', component: ShoppingCart }, // alias
+  shopping_cart: { emoji: '🛒', component: ShoppingCart },
+  shoppingcart: { emoji: '🛒', component: ShoppingCart }, // alias
+  work: { emoji: '💼', component: Work },
+  workspace_premium: { emoji: '⭐', component: WorkspacePremium },
+
+  // === Communication ===
+  contact: { emoji: '📧', component: Email }, // alias
+  email: { emoji: '📧', component: Email },
+  mail: { emoji: '📧', component: Email }, // alias
+  notifications: { emoji: '🔔', component: Notifications },
+  phone: { emoji: '📱', component: Phone },
   support_agent: { emoji: '🛎️', component: SupportAgent },
-  tune: { emoji: '🎛️', component: Tune },
 
-  // Development & Technology
-  code: { emoji: '💻', component: Code },
-  psychology: { emoji: '🧠', component: Psychology },
+  // === Content & Media ===
+  article: { emoji: '📰', component: Article },
+  blog: { emoji: '📝', component: Book }, // alias
+  book: { emoji: '📖', component: Book },
+  gallery: { emoji: '🖼️', component: InsertPhoto }, // alias
+  image: { emoji: '🖼️', component: InsertPhoto },
+  insert_photo: { emoji: '🖼️', component: InsertPhoto },
+  library_books: { emoji: '📚', component: LibraryBooks },
+  news: { emoji: '📰', component: Article }, // alias
+  photo_library: { emoji: '📸', component: PhotoLibrary },
+  play: { emoji: '▶️', component: PlayArrow }, // alias
+  play_arrow: { emoji: '▶️', component: PlayArrow },
+  portfolio: { emoji: '💼', component: Business }, // alias
+
+  // === Development & Technology ===
+  architecture: { emoji: '🏛️', component: Architecture },
   autorenew: { emoji: '🔄', component: Autorenew },
-  integration_instructions: { emoji: '🔌', component: IntegrationInstructions },
+  cloud: { emoji: '☁️', component: Cloud },
+  cloud_download: { emoji: '☁️⬇️', component: CloudDownload },
+  cloud_upload: { emoji: '☁️⬆️', component: CloudUpload },
+  clouddownload: { emoji: '☁️⬇️', component: CloudDownload }, // alias
+  cloudupload: { emoji: '☁️⬆️', component: CloudUpload }, // alias
+  code: { emoji: '💻', component: Code },
+  computer: { emoji: '💻', component: Computer },
   construction: { emoji: '🚧', component: Construction },
-  work: { emoji: '💼', component: Work },
+  integration_instructions: { emoji: '🔌', component: IntegrationInstructions },
+  memory: { emoji: '🧠', component: Memory },
+  psychology: { emoji: '🧠', component: Psychology },
+  rocket: { emoji: '🚀', component: Rocket },
+  storage: { emoji: '💾', component: Storage },
+
+  // === Navigation & Layout ===
+  arrow_back: { emoji: '←', component: ArrowBack },
+  arrow_forward: { emoji: '→', component: ArrowForward },
+  arrowback: { emoji: '←', component: ArrowBack }, // alias
+  arrowforward: { emoji: '→', component: ArrowForward }, // alias
+  dashboard: { emoji: '📊', component: Dashboard },
+  download: { emoji: '⬇️', component: Download },
+  explore: { emoji: '🧭', component: Explore },
+  home: { emoji: '🏠', component: Home },
   layers: { emoji: '📚', component: Layers },
-  trending_up: { emoji: '📈', component: TrendingUp },
+  menu: { emoji: '☰', component: Menu },
   route: { emoji: '🗺️', component: Route },
-  sync: { emoji: '🔄', component: Sync },
-  architecture: { emoji: '🏛️', component: Architecture },
-  security: { emoji: '🔐', component: Security },
+  settings: { emoji: '⚙️', component: Settings },
+  trending_up: { emoji: '📈', component: TrendingUp },
+  tune: { emoji: '🎛️', component: Tune },
 
-  // Control Panel & Admin UI Icons
-  key: { emoji: '🔑', component: Key },
-  vpn_key: { emoji: '🔐', component: VpnKey },
+  // === Products & Inventory ===
+  inventory: { emoji: '📦', component: Inventory },
+  inventory_2: { emoji: '📦', component: Inventory2 },
+  local_offer: { emoji: '🏷️', component: LocalOffer },
+  products: { emoji: '🛍️', component: ShoppingCart }, // alias
+  services: { emoji: '⚙️', component: Settings }, // alias
+  speed: { emoji: '⚡', component: Speed },
+
+  // === Status & Feedback ===
+  about: { emoji: 'ℹ️', component: Info }, // alias
+  favorite: { emoji: '❤️', component: Favorite },
+  heart: { emoji: '❤️', component: Favorite }, // alias
+  help: { emoji: '❓', component: Help },
+  info: { emoji: 'ℹ️', component: Info },
+  star: { emoji: '⭐', component: Star },
+
+  // === Users & People ===
+  account_circle: { emoji: '👤', component: AccountCircle },
+  group: { emoji: '👥', component: Group },
+  manage_accounts: { emoji: '👤', component: ManageAccounts },
+  people: { emoji: '👥', component: People },
+  person: { emoji: '👤', component: Person },
   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 },
+  user: { emoji: '👤', component: Person }, // alias
+  users: { emoji: '👥', component: People }, // alias
 };
 
 /**
  * Get emoji representation of an icon
- * @param iconName - Icon name (case-insensitive)
+ * @param iconName - Icon name (case-insensitive, supports snake_case)
  * @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;
+  const normalized = iconName.toLowerCase();
+  const mapping = iconMap[normalized];
+  return mapping?.emoji || fallback;
 }
 
 /**
- * Get Material-UI component representation of an icon
- * @param iconName - Icon name (case-insensitive)
- * @returns React element or null if not found
+ * Get Material-UI component representation of an icon.
+ *
+ * Uses the static iconMap for known icons. For unmapped icons,
+ * returns a HelpOutline fallback and logs a warning.
+ *
+ * @param iconName - Icon name (case-insensitive, supports snake_case)
+ * @returns React element (mapped icon or HelpOutline fallback), or null if no name provided
  */
 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 normalized = iconName.toLowerCase();
+  const mapping = iconMap[normalized];
+
+  if (mapping?.component) {
+    const IconComponent = mapping.component;
+    return <IconComponent />;
+  }
+
+  // Fallback: Return HelpOutline icon and warn about unmapped icon
+  // Use registerIcon() to add app-specific icons at runtime
+  if (process.env.NODE_ENV !== 'production') {
+    console.warn(`[IconMap] Icon "${iconName}" not found. Add it to iconMap or use registerIcon().`);
   }
-  
-  const IconComponent = mapping.component;
-  return <IconComponent />;
+  return <HelpOutline />;
 }
 
 /**
@@ -230,14 +287,15 @@ export function registerIcon(name: string, mapping: IconMapping): void {
 }
 
 /**
- * Check if an icon is registered
+ * Check if an icon is registered in the static map
+ * If false, getIconComponent will return HelpOutline fallback
  */
 export function hasIcon(iconName: string): boolean {
   return iconName.toLowerCase() in iconMap;
 }
 
 /**
- * Get all registered icon names
+ * Get all registered icon names from the static map
  */
 export function getRegisteredIcons(): string[] {
   return Object.keys(iconMap);

package/src/utils/reactUtils.tsx

@@ -7,55 +7,10 @@
 
 import { ReactNode } from 'react';
 
-/** Location type for routing */
-type LocationType = { pathname: string, search: string, hash: string };
-
-/**
- * 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 => {
-  // 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;
-};
-
-/**
- * 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 = (): 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);
-      }
-    }
-  };
-};
-
 /**
  * Extract text content from ReactNode for code processing
  * Handles natural React usage like <Code>const x = 1;</Code>
- * 
+ *
  * @param node - The ReactNode to extract text from
  * @returns String representation of the node's text content
  */
@@ -73,7 +28,7 @@ export function extractTextFromReactNode(node: ReactNode): string {
   }
 
   if (Array.isArray(node)) {
-    return node.map(child => extractTextFromReactNode(child)).join('');
+    return node.map((child) => extractTextFromReactNode(child)).join('');
   }
 
   // For React elements, try to extract text content