@qwickapps/react-framework 1.3.0

package/src/templates/TemplateResolver.ts

@@ -0,0 +1,156 @@
+/** 
+* ContentResolver provides a unified interface to fetch and render content
+* using data providers, template resolvers, and optional caching.
+* 
+* Copyright (c) 2025 QwickApps.com. All rights reserved.
+*/
+import { Logger } from '@qwickapps/logging';
+import { CachedDataProvider, DataResponse, ICacheProvider, IDataProvider, MemoryCacheProvider, Model, MustacheTemplateProvider, SelectOptions } from '@qwickapps/schema';
+import {
+  DataProxy,
+  ITemplateResolver,
+  TemplateProvider,
+  TemplateResolverConfig
+} from "../types";
+
+/**
+ * ContentResolver - Combines data, template, and cache providers
+ * 
+ * This class follows the orchestrator pattern:
+ * - Delegates data fetching to IDataProvider
+ * - Delegates template resolution to ITemplateResolver  
+ * - Optionally wraps data provider with ICacheProvider
+ * - Creates ContentProxy objects for framework compatibility
+ * 
+ * Usage:
+ * ```typescript
+ * const resolver = new ContentResolver({
+ *   dataProvider: new JsonDataProvider({ data: {...} }),
+ *   templateResolver: new MustacheTemplateResolver(),
+ *   cacheProvider: new MemoryCacheProvider({ maxSize: 50, defaultTtl: 60000 })
+ * });
+ * 
+ * // Or with boolean cacheProvider (uses default MemoryCacheProvider)
+ * const resolver = new ContentResolver({
+ *   dataProvider: new JsonDataProvider({ data: {...} }),
+ *   cacheProvider: true
+ * });
+ * 
+ * // Or no caching
+ * const resolver = new ContentResolver({
+ *   dataProvider: new JsonDataProvider({ data: {...} }),
+ *   cacheProvider: false // or omit entirely
+ * });
+ * ```
+ */
+export class TemplateResolver implements ITemplateResolver {
+  private dataProvider: IDataProvider;
+  private templateResolver: TemplateProvider;
+  private cacheProvider?: ICacheProvider<any[]>;  
+  private enableLogging: boolean;
+  private log: Logger;
+
+  constructor(config: TemplateResolverConfig) {
+    this.log = new Logger({
+      namespace: 'ContentResolver',
+      enabled: config.enableLogging || false
+    });
+
+    this.enableLogging = config.enableLogging || false;
+    this.templateResolver = config.templateResolver || new MustacheTemplateProvider();
+    if (config.cacheProvider === true) {
+      const cacheProvider = new MemoryCacheProvider<any[]>({enableLogging: config.enableLogging || false});
+      this.dataProvider = new CachedDataProvider(config.dataProvider);
+    } else if (config.cacheProvider === false) {
+      this.dataProvider = config.dataProvider;
+    } else {
+      const cacheProvider = new MemoryCacheProvider<any[]>({enableLogging: config.enableLogging || false});
+      this.dataProvider = new CachedDataProvider(config.dataProvider);
+    }
+
+    
+    this.log.debug('ContentResolver initialized', {
+      dataProvider: config.dataProvider ? config.dataProvider.constructor.name : 'none',
+      templateResolver: this.templateResolver.constructor.name,
+      cacheProvider: config.cacheProvider ?
+        (config.cacheProvider === true ? 'MemoryCacheProvider(default)' : config.cacheProvider.constructor.name) :
+        'disabled'
+    });
+  }
+
+  async get<T extends Model>(slug: string): Promise<DataResponse<T>> {
+    return this.dataProvider.get<T>(slug);
+  }
+
+  async select<T extends Model>(schema: string, options?: SelectOptions): Promise<DataResponse<T[]>> {
+    return this.dataProvider.select<T>(schema, options);
+  }
+
+  /**
+   * Resolve template with lazy context loading
+   */
+  async resolveTemplate(template: string): Promise < string > {
+      this.log.debug(`Resolving template: ${template}`);
+
+      if(!template || !template.includes('{{')) {
+      // No mustache syntax, return as-is
+      return template;
+    }
+
+    // Create lazy context proxy
+    const context = await this.createLazyContext(template);
+
+    // Resolve using template resolver
+    try {
+      const resolved = this.templateResolver.resolve(template, context);
+      this.log.debug(`Template resolved: ${template} -> ${resolved}`);
+      return resolved;
+    } catch (error) {
+      this.log.debug(`Template resolution failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Create lazy loading context for template resolution
+   * Only fetches data when accessed by mustache template
+   */
+  private async createLazyContext(template: string): Promise<any> {
+    // Extract field group IDs from template
+    const mustachePattern = /\{\{([^}]+)\}\}/g;
+    const matches = Array.from(template.matchAll(mustachePattern));
+    const fieldGroups = new Set<string>();
+
+    for (const match of matches) {
+      const fullPath = match[1].trim();
+      const [fieldGroupId] = fullPath.split('.');
+      fieldGroups.add(fieldGroupId);
+    }
+
+    // Fetch all needed data
+    const contextData: Record<string, any> = {};
+
+    for (const fieldGroupId of fieldGroups) {
+      try {
+        // First try to get it as an array using select
+        const arrayData = await this.select(fieldGroupId);
+        
+        if (arrayData.data && arrayData.data.length > 0) {
+          // Use first item for template context - use data directly
+          contextData[fieldGroupId] = arrayData.data[0];
+        } else {
+          // Fallback to get single item
+          const data = await this.get(fieldGroupId);
+          if (data.data) {
+            contextData[fieldGroupId] = data.data;
+          }
+        }
+      } catch (error) {
+        this.log.error(`Failed to load data for ${fieldGroupId}: ${error instanceof Error ? error.message : String(error)}`);
+        // Continue with other field groups
+      }
+    }
+
+    return contextData;
+  }
+}

package/src/templates/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Index file for templates module
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export * from './TemplateResolver';

package/src/tests/ConsoleWarningTest.tsx

@@ -0,0 +1,30 @@
+/**
+ * Quick test to verify console warning functionality
+ */
+
+import React from 'react';
+import { PaletteProvider, PaletteSwitcher } from '../index';
+import { Typography, Box } from '@mui/material';
+
+export default function ConsoleWarningTest() {
+  return (
+    <Box sx={{ p: 3 }}>
+      <Typography variant="h5" gutterBottom>
+        Console Warning Test
+      </Typography>
+      <Typography variant="body1" sx={{ mb: 2 }}>
+        Open your browser's developer console to see the warning message for auto-generated storage keys.
+      </Typography>
+      
+      {/* This should trigger the console warning */}
+      <PaletteProvider>
+        <Box sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+          <Typography variant="h6" gutterBottom>
+            Auto Key (Default - triggers warning)
+          </Typography>
+          <PaletteSwitcher />
+        </Box>
+      </PaletteProvider>
+    </Box>
+  );
+}

package/src/tests/StorageKeyTest.tsx

@@ -0,0 +1,110 @@
+/**
+ * Storage Key Strategy Test Component
+ * Demonstrates the three different storage strategies
+ */
+
+import React from 'react';
+import { PaletteProvider, PaletteSwitcher, usePalette } from '../index';
+import { Box, Typography, Paper } from '@mui/material';
+
+function PaletteInfo({ 
+  title, 
+  appId, 
+  description 
+}: { 
+  title: string; 
+  appId: string | true | false;
+  description: string;
+}) {
+  const { currentPalette } = usePalette();
+  
+  // Helper to show what the actual storage key would be
+  const getActualKey = () => {
+    if (appId === false) return null;
+    if (appId === true || appId === undefined) {
+      return 'qwickapps-react-framework-palette';
+    }
+    return `${appId}.palette`;
+  };
+  
+  const actualKey = getActualKey();
+  
+  return (
+    <Paper sx={{ p: 2, mb: 2 }}>
+      <Typography variant="h6" gutterBottom>
+        {title}
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1, color: 'text.secondary' }}>
+        {description}
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1 }}>
+        Config: <code>{String(appId)}</code>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1 }}>
+        Actual Key: <code>{actualKey || 'none (no persistence)'}</code>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 2 }}>
+        Current Palette: <strong>{currentPalette}</strong>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 2 }}>
+        localStorage: <code>{actualKey ? (localStorage.getItem(actualKey) || 'null') : 'disabled'}</code>
+      </Typography>
+      <PaletteSwitcher />
+    </Paper>
+  );
+}
+
+export default function StorageKeyTest() {
+  return (
+    <Box sx={{ p: 3, maxWidth: 900, margin: '0 auto' }}>
+      <Typography variant="h4" gutterBottom>
+        Storage Key Strategy Test
+      </Typography>
+      
+      <Typography variant="body1" sx={{ mb: 3 }}>
+        This test demonstrates the three storage strategies. Change palettes in each section 
+        and notice the different behaviors. Reload the page to see persistence differences.
+      </Typography>
+
+      <PaletteProvider appId="com.test.explicit-key">
+        <PaletteInfo 
+          title="1. Explicit App ID Strategy" 
+          appId="com.test.explicit-key"
+          description="Uses appId to generate storage key 'com.test.explicit-key.palette'. Recommended for production apps." 
+        />
+      </PaletteProvider>
+
+      <PaletteProvider appId={true}>
+        <PaletteInfo 
+          title="2. Default Key Strategy" 
+          appId={true}
+          description="Uses default key 'qwickapps-react-framework-palette'. Good for development/demos. Shows console warning." 
+        />
+      </PaletteProvider>
+
+      <PaletteProvider appId={false}>
+        <PaletteInfo 
+          title="3. No Persistence Strategy" 
+          appId={false}
+          description="Session-only storage, no localStorage persistence. Settings reset on page reload." 
+        />
+      </PaletteProvider>
+
+      <Paper sx={{ p: 2, mt: 3, backgroundColor: 'var(--palette-surface-variant)' }}>
+        <Typography variant="h6" gutterBottom>
+          Test Instructions:
+        </Typography>
+        <Typography variant="body2" component="div">
+          <ol style={{ paddingLeft: '20px' }}>
+            <li>Select different palettes in each section above</li>
+            <li>Notice the three different behaviors: explicit app ID, default key with warning, and no persistence</li>
+            <li>Section 1 uses custom appId, Section 2 uses default key with warning, Section 3 has no persistence</li>
+            <li>Reload the page - Sections 1 & 2 remember their selections, Section 3 resets</li>
+            <li>Open browser DevTools → Application → Local Storage to see the different keys</li>
+            <li>Check the console to see the warning for the default key usage</li>
+          </ol>
+        </Typography>
+      </Paper>
+    </Box>
+  );
+}

package/src/tests/ThemeStorageKeyTest.tsx

@@ -0,0 +1,114 @@
+/**
+ * Theme Storage Key Strategy Test Component
+ * Demonstrates the three different storage strategies for ThemeProvider
+ */
+
+import React from 'react';
+import { ThemeProvider, ThemeSwitcher, useTheme } from '../index';
+import { Box, Typography, Paper } from '@mui/material';
+
+function ThemeInfo({ 
+  title, 
+  appId, 
+  description 
+}: { 
+  title: string; 
+  appId: string | true | false;
+  description: string;
+}) {
+  const { currentTheme, actualThemeMode } = useTheme();
+  
+  // Helper to show what the actual storage key would be
+  const getActualKey = () => {
+    if (appId === false) return null;
+    if (appId === true) {
+      return 'qwickapps-react-framework-theme';
+    }
+    return `${appId}.theme`;
+  };
+  
+  const actualKey = getActualKey();
+  
+  return (
+    <Paper sx={{ p: 2, mb: 2 }}>
+      <Typography variant="h6" gutterBottom>
+        {title}
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1, color: 'text.secondary' }}>
+        {description}
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1 }}>
+        Config: <code>{String(appId)}</code>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1 }}>
+        Actual Key: <code>{actualKey || 'none (no persistence)'}</code>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 1 }}>
+        Theme Mode: <strong>{currentTheme}</strong>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 2 }}>
+        Actual Theme: <strong>{actualThemeMode}</strong>
+      </Typography>
+      <Typography variant="body2" sx={{ mb: 2 }}>
+        localStorage: <code>{actualKey ? (localStorage.getItem(actualKey) || 'null') : 'disabled'}</code>
+      </Typography>
+      <ThemeSwitcher />
+    </Paper>
+  );
+}
+
+export default function ThemeStorageKeyTest() {
+  return (
+    <Box sx={{ p: 3, maxWidth: 900, margin: '0 auto' }}>
+      <Typography variant="h4" gutterBottom>
+        Theme Storage Key Strategy Test
+      </Typography>
+      
+      <Typography variant="body1" sx={{ mb: 3 }}>
+        This test demonstrates the three storage strategies for ThemeProvider. Change themes in each section 
+        and notice the different behaviors. Reload the page to see persistence differences.
+      </Typography>
+
+      <ThemeProvider appId="com.test.explicit-theme">
+        <ThemeInfo 
+          title="1. Explicit App ID Strategy" 
+          appId="com.test.explicit-theme"
+          description="Uses appId to generate storage key 'com.test.explicit-theme.theme'. Recommended for production apps." 
+        />
+      </ThemeProvider>
+
+      <ThemeProvider>
+        <ThemeInfo 
+          title="2. Default Key Strategy" 
+          appId={true}
+          description="Uses default key 'qwickapps-react-framework-theme'. Good for development/demos. Shows console warning." 
+        />
+      </ThemeProvider>
+
+      <ThemeProvider appId={false}>
+        <ThemeInfo 
+          title="3. No Persistence Strategy" 
+          appId={false}
+          description="Disables localStorage persistence. Theme resets to 'system' on page reload." 
+        />
+      </ThemeProvider>
+
+      <Paper sx={{ p: 2, mt: 3, backgroundColor: 'var(--palette-surface-variant)' }}>
+        <Typography variant="h6" gutterBottom>
+          Test Instructions:
+        </Typography>
+        <Typography variant="body2" component="div">
+          <ol style={{ paddingLeft: '20px' }}>
+            <li>Select different themes in each section above</li>
+            <li>Notice that sections 1 & 2 save to localStorage with different keys, section 3 doesn't persist</li>
+            <li>Section 1 uses custom appId, Section 2 uses default key with warning, Section 3 has no persistence</li>
+            <li>Reload the page - sections 1 & 2 remember their selections, section 3 resets to system</li>
+            <li>Open browser DevTools → Application → Local Storage to see the different keys</li>
+            <li>Check the console to see the warning for the default key usage</li>
+            <li>Try switching your OS theme preference to see "system" mode behavior</li>
+          </ol>
+        </Typography>
+      </Paper>
+    </Box>
+  );
+}

package/src/types/CacheProvider.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure cache provider interface - Single Responsibility: Caching only
+ */
+
+export interface ICacheProvider<T> {
+  /** Get cached value by key */
+  get(key: string): T | null;
+  /** Set cached value with optional TTL */
+  set(key: string, value: T, ttl?: number): void;
+  /** Clear cache entry or all entries */
+  clear(key?: string): void;
+  /** Get cache statistics */
+  getStats?(): { size: number; maxSize: number; keys: string[]; };
+}

package/src/types/ContentProxy.ts

@@ -0,0 +1,99 @@
+/**
+ * DataProxy class to enhance Data with nested property access
+ * This class wraps a Data object and provides a proxy to allow
+ * accessing nested properties using dot notation, e.g., {{company.name}}
+ * 
+ * Copyright (c) 2024 QwickApps.com. All rights reserved.
+ */
+import { Data, Field, FieldGroup, Action } from "./DataTypes";
+
+/**
+ * Enhanced data with nested property access for template resolution
+ * Supports deep nested access like {{company.profile.address.city}}
+ */
+export class DataProxy implements Data {
+  public name!: string;
+  public type!: string;
+  public title?: string;
+  public subtitle?: string;
+  public overline?: string;
+  public icon?: string;
+  public fields?: Field[];
+  public fieldGroups?: FieldGroup[];
+  public actions?: Action[];
+  public repeatable?: boolean;
+  public minRows?: number;
+  public maxRows?: number;
+  public autoCreate?: boolean;
+
+  private data: Record<string, any>;
+
+  constructor(content: Data, data: Record<string, any> = {}) {
+    Object.assign(this, content);
+    this.data = data;
+
+    // Create proxy to enable nested property access
+    return new Proxy(this, {
+      get: (target, prop: string | symbol) => {
+        // Return existing properties first
+        if (prop in target || typeof prop === 'symbol') {
+          return target[prop as keyof DataProxy];
+        }
+
+        // Handle nested property access for data
+        return this.getNestedValue(String(prop));
+      }
+    });
+  }
+
+  /**
+   * Get nested value from data using dot notation
+   * Supports: company.name, user.profile.avatar.url, etc.
+   */
+  private getNestedValue(path: string): any {
+    const keys = path.split('.');
+    let current = this.data;
+
+    for (const key of keys) {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      current = current[key];
+    }
+
+    return current;
+  }
+
+  /**
+   * Set nested value in data using dot notation
+   */
+  public setNestedValue(path: string, value: any): void {
+    const keys = path.split('.');
+    const lastKey = keys.pop()!;
+    let current = this.data;
+
+    // Create nested objects as needed
+    for (const key of keys) {
+      if (!(key in current) || typeof current[key] !== 'object') {
+        current[key] = {};
+      }
+      current = current[key];
+    }
+
+    current[lastKey] = value;
+  }
+
+  /**
+   * Get all data including nested structures
+   */
+  public getData(): Record<string, any> {
+    return this.data;
+  }
+
+  /**
+   * Update data while preserving nested structure
+   */
+  public updateData(newData: Record<string, any>): void {
+    this.data = { ...this.data, ...newData };
+  }
+}