@qwickapps/react-framework 1.3.0

package/src/utils/htmlTransform.tsx

@@ -0,0 +1,323 @@
+/**
+ * HTML Transform Utilities - Shared transformation logic for HTML content
+ * 
+ * Provides configurable HTML element transformation rules to convert
+ * standard HTML elements into Framework components.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { Box, Typography } from '@mui/material';
+import React from 'react';
+import Code from '../components/blocks/Code';
+import Section from '../components/blocks/Section';
+import { Button } from '../components/buttons/Button';
+import SafeSpan from '../components/SafeSpan';
+
+export interface TransformRule {
+  selector: string;
+  transform: (element: Element, key: string) => React.ReactNode;
+}
+
+export interface TransformConfig {
+  rules: TransformRule[];
+  sanitize?: boolean;
+  sanitizeOptions?: any;
+  fallbackComponent?: (element: Element, key: string) => React.ReactNode;
+}
+
+/**
+ * Default transformation rules for article/blog content
+ */
+export const defaultArticleRules: TransformRule[] = [
+  // Pre + Code blocks → Code component with syntax highlighting
+  {
+    selector: 'pre',
+    transform: (element: Element, key: string) => {
+      const codeChild = element.querySelector('code');
+      if (!codeChild) return null;
+
+      const language = Array.from(codeChild.classList)
+        .find(cls => cls.startsWith('language-'))
+        ?.replace('language-', '') || 'text';
+
+      return (
+        <Box key={key} sx={{ my: 1.5 }}>
+          <Code
+            language={language}
+            showCopy={true}
+            showLineNumbers={false}
+          >
+            {codeChild.textContent || ''}
+          </Code>
+        </Box>
+      );
+    }
+  },
+
+  // Standalone complex code blocks → Code component
+  {
+    selector: 'code',
+    transform: (element: Element, key: string) => {
+      // Skip if inside pre (already handled above)
+      if (element.closest('pre')) return null;
+
+      const text = element.textContent || '';
+      const hasMultipleLines = text.includes('\n');
+      const hasComplexContent = element.children.length > 0;
+
+      // Check if code is in an inline context (would violate DOM nesting rules)
+      const inlineParents = ['p', 'span', 'a', 'strong', 'em', 'b', 'i', 'u', 'small'];
+      const isInInlineContext = inlineParents.some(tag => element.closest(tag));
+
+      if ((hasMultipleLines || hasComplexContent) && !isInInlineContext) {
+        return (
+          <Box key={key} sx={{ my: 1.5 }}>
+            <Code
+              language="text"
+              showCopy={true}
+              showLineNumbers={false}
+            >
+              {text}
+            </Code>
+          </Box>
+        );
+      }
+
+      return null; // Let default handling take over
+    }
+  },
+
+  // Blog sections → Section component
+  {
+    selector: 'section.blog-section',
+    transform: (element: Element, key: string) => {
+      const children = Array.from(element.children);
+      const title = element.querySelector('h2')?.textContent || '';
+      const content = children.filter(child => child.tagName !== 'H2');
+      const spacing = element.getAttribute('data-padding') || 'none';
+
+      return (
+        <Section key={key} padding={spacing as any}>
+          <Box sx={{ maxWidth: 'lg', mx: 'auto' }}>
+            {title && (
+              <Typography variant="h4" component="h2" sx={{ mb: 2 }}>
+                {title}
+              </Typography>
+            )}
+            <Box>
+              {content.map((child, index) =>
+                transformElement(child, `${key}-${index}`, { rules: defaultArticleRules })
+              )}
+            </Box>
+          </Box>
+        </Section>
+      );
+    }
+  },
+
+  // Button elements → Button component
+  {
+    selector: 'button',
+    transform: (element: Element, key: string) => {
+      const text = element.textContent || '';
+      const variant = element.getAttribute('data-variant') || 'contained';
+      const disabled = element.hasAttribute('disabled');
+
+      return (
+        <Button
+          key={key}
+          variant={variant as any}
+          disabled={disabled}
+        >
+          {text}
+        </Button>
+      );
+    }
+  }
+];
+
+/**
+ * Transform rules optimized for Markdown content
+ */
+export const defaultMarkdownRules: TransformRule[] = [
+  // Pre + Code blocks → Code component (same as article)
+  {
+    selector: 'pre',
+    transform: (element: Element, key: string) => {
+      const codeChild = element.querySelector('code');
+      if (!codeChild) return null;
+
+      const language = Array.from(codeChild.classList)
+        .find(cls => cls.startsWith('language-'))
+        ?.replace('language-', '') || 'text';
+
+      return (
+        <Box key={key} sx={{ my: 1.5 }}>
+          <Code
+            language={language}
+            showCopy={true}
+            showLineNumbers={false}
+          >
+            {codeChild.textContent || ''}
+          </Code>
+        </Box>
+      );
+    }
+  },
+
+  // Inline code → preserve as regular code element (no transformation)
+  {
+    selector: 'code',
+    transform: (element: Element, key: string) => {
+      // Skip if inside pre (already handled above)
+      if (element.closest('pre')) return null;
+
+      // For Markdown, keep inline code as-is
+      return null;
+    }
+  }
+];
+
+/**
+ * Default fallback component - renders element as-is with SafeSpan content
+ */
+export const defaultFallback = (element: Element, key: string): React.ReactNode => {
+  const tagName = element.tagName.toLowerCase();
+
+  // Check if this is a void element (self-closing)
+  const voidElements = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr'
+  ]);
+
+  const props = {
+    key,
+    ...(element.className ? { className: element.className } : {}),
+    ...(element.id ? { id: element.id } : {}),
+    ...Object.fromEntries(
+      Array.from(element.attributes)
+        .filter(attr => !['class', 'id'].includes(attr.name))
+        .map(attr => [attr.name, attr.value])
+    )
+  };
+
+  if (voidElements.has(tagName)) {
+    // Void elements can't have children
+    return React.createElement(tagName, props);
+  }
+
+  // Regular elements with content
+  return React.createElement(
+    tagName,
+    props,
+    React.createElement(SafeSpan, { html: element.innerHTML })
+  );
+};
+
+/**
+ * Check if an element needs recursive processing
+ */
+function needsRecursiveTransform(element: Element, rules: TransformRule[]): boolean {
+  const children = Array.from(element.children);
+
+  return children.some(child => {
+    // Check if any rule applies to this child
+    const matchingRule = rules.find(rule => child.matches(rule.selector));
+    if (matchingRule) return true;
+
+    // Check if child has transformable descendants
+    return rules.some(rule => child.querySelector(rule.selector));
+  });
+}
+
+/**
+ * Transform a single HTML element to React component
+ */
+export function transformElement(
+  element: Element, 
+  key: string, 
+  config: TransformConfig = { rules: defaultArticleRules }
+): React.ReactNode {
+  const { rules, fallbackComponent = defaultFallback } = config;
+
+  // Try to find a matching rule for this element
+  const matchingRule = rules.find(rule => element.matches(rule.selector));
+  if (matchingRule) {
+    const result = matchingRule.transform(element, key);
+    if (result !== null) return result;
+  }
+
+  // Check if this element needs recursive processing
+  if (needsRecursiveTransform(element, rules)) {
+    const children = Array.from(element.children);
+    const tagName = element.tagName.toLowerCase();
+
+    const transformedChildren = children.map((child, index) =>
+      transformElement(child, `${key}-${index}`, config)
+    );
+
+    return React.createElement(
+      tagName,
+      {
+        key,
+        ...(element.className ? { className: element.className } : {}),
+        ...(element.id ? { id: element.id } : {}),
+        ...Object.fromEntries(
+          Array.from(element.attributes)
+            .filter(attr => !['class', 'id'].includes(attr.name))
+            .map(attr => [attr.name, attr.value])
+        )
+      },
+      ...transformedChildren
+    );
+  }
+
+  // No transformation needed - use fallback
+  return fallbackComponent(element, key);
+}
+
+/**
+ * Transform HTML string to React components
+ */
+export function transformHtmlToReact(
+  html: string,
+  config: TransformConfig = { rules: defaultArticleRules }
+): React.ReactNode[] {
+  if (!html.trim()) return [];
+
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+  
+  return Array.from(doc.body.children).map((element, index) =>
+    transformElement(element, index.toString(), config)
+  );
+}
+
+/**
+ * Strip header elements from HTML content (for articles)
+ */
+export function stripHeaderFromContent(html: string): string {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+
+  // Remove header elements that are handled by PageBannerHeader
+  const elementsToRemove = [
+    'header.blog-header',
+    '.blog-header',
+    'header[class*="blog"]',
+  ];
+
+  elementsToRemove.forEach(selector => {
+    const elements = doc.querySelectorAll(selector);
+    elements.forEach(el => el.remove());
+  });
+
+  // Remove standalone h1 if it's the first child and looks like a title
+  const firstChild = doc.body.firstElementChild;
+  if (firstChild && firstChild.tagName === 'H1') {
+    firstChild.remove();
+  }
+
+  return doc.body.innerHTML;
+}

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Utility functions and types for QwickApps React Framework
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export * from './customPaletteManager';
+export * from './dimensions';
+export * from './logger';
+export * from './paletteUtils';
+export * from './persistenceUtils';
+export * from './reactUtils';
+export * from './spacing';
+export * from './themePerformanceMonitor';
+export * from './themeUtils';
+
+// Old data binding utilities removed - using new schema system in schemas/

package/src/utils/logger.ts

@@ -0,0 +1,28 @@
+/**
+ * QwickApps React Framework - Logger Utility
+ * 
+ * Re-exports from @qwickapps/logging with framework-specific loggers
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Re-export everything from the logging package
+export * from '@qwickapps/logging';
+
+// Import createLogger and Logger type to create framework-specific loggers
+import { createLogger, Logger } from '@qwickapps/logging';
+
+/**
+ * Framework-specific loggers
+ */
+export const loggers: Record<string, Logger> = {
+  scaffold: createLogger('Scaffold'),
+  navigation: createLogger('Navigation'),
+  auth: createLogger('Auth'),
+  theme: createLogger('Theme'),
+  palette: createLogger('Palette'),
+  form: createLogger('Form'),
+  layout: createLogger('Layout'),
+  menu: createLogger('Menu'),
+  router: createLogger('Router'),
+};

package/src/utils/paletteUtils.ts

@@ -0,0 +1,78 @@
+// Palette utilities for QwickApps Theme System
+
+import { PaletteConfig } from '../contexts/PaletteContext';
+
+/**
+ * Available palette options
+ */
+export const AVAILABLE_PALETTES: PaletteConfig[] = [
+  { id: 'default', name: 'Default', description: 'Classic blue and neutral colors', primaryColor: '#007bff' },
+  { id: 'winter', name: 'Winter', description: 'Cool blues and icy whites', primaryColor: '#0077be' },
+  { id: 'autumn', name: 'Autumn', description: 'Warm oranges and golden yellows', primaryColor: '#ea580c' },
+  { id: 'spring', name: 'Spring', description: 'Fresh greens and soft pinks', primaryColor: '#16a34a' },
+  { id: 'ocean', name: 'Ocean', description: 'Deep blues and aqua teals', primaryColor: '#0891b2' }
+];
+
+/**
+ * Get the current palette from CSS variables
+ */
+export const getCurrentPalette = (): string => {
+  const root = document.documentElement;
+  return root.getAttribute('data-palette') || 'default';
+};
+
+/**
+ * Set palette and update CSS variables
+ */
+export const setPalette = (palette: string): void => {
+  const root = document.documentElement;
+  root.setAttribute('data-palette', palette);
+  
+  // Trigger custom event for palette change
+  window.dispatchEvent(new CustomEvent('paletteChange', { detail: { palette } }));
+};
+
+/**
+ * Get palette display name
+ */
+export const getPaletteName = (paletteId: string): string => {
+  const palette = AVAILABLE_PALETTES.find(p => p.id === paletteId);
+  return palette ? palette.name : paletteId;
+};
+
+/**
+ * Get palette configuration by ID
+ */
+export const getPaletteConfig = (paletteId: string): PaletteConfig | undefined => {
+  return AVAILABLE_PALETTES.find(p => p.id === paletteId);
+};
+
+/**
+ * Initialize palette system
+ */
+export const initializePalette = (): void => {
+  const savedPalette = localStorage.getItem('palette') || 'default';
+  setPalette(savedPalette);
+};
+
+/**
+ * Save palette preference to localStorage
+ */
+export const savePalettePreference = (palette: string): void => {
+  localStorage.setItem('palette', palette);
+  setPalette(palette);
+};
+
+/**
+ * Get CSS custom property value
+ */
+export const getCSSVariable = (property: string): string => {
+  return getComputedStyle(document.documentElement).getPropertyValue(property).trim();
+};
+
+/**
+ * Set CSS custom property value
+ */
+export const setCSSVariable = (property: string, value: string): void => {
+  document.documentElement.style.setProperty(property, value);
+};

package/src/utils/persistenceUtils.ts

@@ -0,0 +1,107 @@
+/**
+ * Persistence utilities for theme and palette preferences
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { ThemeMode } from '../contexts/ThemeContext';
+
+/**
+ * Load user theme preference from localStorage
+ */
+export const loadUserThemePreference = (storageKey: string | null): ThemeMode | null => {
+  if (!storageKey || typeof window === 'undefined') {
+    return null;
+  }
+  
+  try {
+    const saved = localStorage.getItem(storageKey) as ThemeMode;
+    if (saved && ['light', 'dark', 'system'].includes(saved)) {
+      return saved;
+    }
+  } catch (error) {
+    console.warn('[persistenceUtils] Theme localStorage read failed:', error);
+  }
+  
+  return null;
+};
+
+/**
+ * Save user theme preference to localStorage
+ */
+export const saveUserThemePreference = (storageKey: string | null, theme: ThemeMode): void => {
+  if (!storageKey || typeof window === 'undefined') {
+    return;
+  }
+  
+  try {
+    localStorage.setItem(storageKey, theme);
+  } catch (error) {
+    console.warn('[persistenceUtils] Theme localStorage write failed:', error);
+  }
+};
+
+/**
+ * Clear user theme preference from localStorage
+ */
+export const clearUserThemePreference = (storageKey: string | null): void => {
+  if (!storageKey || typeof window === 'undefined') {
+    return;
+  }
+  
+  try {
+    localStorage.removeItem(storageKey);
+  } catch (error) {
+    console.warn('[persistenceUtils] Theme localStorage clear failed:', error);
+  }
+};
+
+/**
+ * Load user palette preference from localStorage
+ */
+export const loadUserPalettePreference = (storageKey: string | null, availablePalettes: string[]): string | null => {
+  if (!storageKey || typeof window === 'undefined') {
+    return null;
+  }
+  
+  try {
+    const saved = localStorage.getItem(storageKey);
+    if (saved && availablePalettes.includes(saved)) {
+      return saved;
+    }
+  } catch (error) {
+    console.warn('[persistenceUtils] Palette localStorage read failed:', error);
+  }
+  
+  return null;
+};
+
+/**
+ * Save user palette preference to localStorage
+ */
+export const saveUserPalettePreference = (storageKey: string | null, palette: string): void => {
+  if (!storageKey || typeof window === 'undefined') {
+    return;
+  }
+  
+  try {
+    localStorage.setItem(storageKey, palette);
+  } catch (error) {
+    console.warn('[persistenceUtils] Palette localStorage write failed:', error);
+  }
+};
+
+/**
+ * Clear user palette preference from localStorage
+ */
+export const clearUserPalettePreference = (storageKey: string | null): void => {
+  if (!storageKey || typeof window === 'undefined') {
+    return;
+  }
+  
+  try {
+    localStorage.removeItem(storageKey);
+  } catch (error) {
+    console.warn('[persistenceUtils] Palette localStorage clear failed:', error);
+  }
+};

package/src/utils/reactUtils.tsx

@@ -0,0 +1,37 @@
+/**
+ * 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 { useLocation, useNavigate } from 'react-router-dom';
+
+/** Location type for React Router */
+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
+ */
+export const useSafeLocation = (): LocationType | undefined => {
+  try {
+    return useLocation();
+  } catch (error) {
+    console.warn('React Router context not available:', error);
+    return undefined;
+  }
+};
+
+/**
+ * Custom hook to get the navigate function
+ * @returns {Function | undefined} - The navigate function if React Router is available, otherwise undefined
+ */
+export const useSafeNavigate = (): Function | undefined => {
+  try {
+    return useNavigate();
+  } catch (error) {
+    console.warn('React Router context not available:', error);
+    return undefined;
+  }
+};