@qwickapps/react-framework 1.3.0

package/src/utils/spacing.ts

@@ -0,0 +1,155 @@
+/**
+ * Spacing utilities for QwickApps React Framework
+ * 
+ * Provides standardized spacing value resolution with t-shirt sizing
+ * Based on Material-UI's 8px spacing system
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export type SpacingValue = number | 'none' | 'tiny' | 'small' | 'medium' | 'large' | 'huge' | string | undefined;
+
+export type SpacingContext = 'padding' | 'margin' | 'gap';
+
+/**
+ * T-shirt size mappings for spacing (based on MUI's 8px system)
+ * Numbers represent multipliers for the base spacing unit
+ */
+const SPACING_SIZES: Record<string, number> = {
+  none: 0,
+  tiny: 0.5,   // 4px
+  small: 1,    // 8px
+  medium: 2,   // 16px
+  large: 3,    // 24px
+  huge: 4      // 32px
+};
+
+/**
+ * CSS spacing value pattern for validation
+ */
+const CSS_SPACING_PATTERN = /^(\d+(\.\d+)?(px|em|rem|%)|0|auto|inherit|initial|unset)$/;
+
+/**
+ * Resolves a spacing value to MUI spacing units or CSS value
+ */
+export function resolveSpacing(
+  value: SpacingValue,
+  context: SpacingContext = 'padding'
+): number | string | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  // Number values are returned as-is (MUI spacing units)
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  // Check for t-shirt sizes
+  if (value in SPACING_SIZES) {
+    return SPACING_SIZES[value];
+  }
+
+  // Validate CSS string values
+  if (typeof value === 'string') {
+    // Check if it's a space-separated value (for margin/padding shorthand)
+    const parts = value.split(' ');
+    if (parts.length > 1) {
+      // Validate each part
+      const validParts = parts.every(part => 
+        CSS_SPACING_PATTERN.test(part) || part in SPACING_SIZES
+      );
+      if (validParts) {
+        // Convert t-shirt sizes in the string
+        return parts.map(part => {
+          if (part in SPACING_SIZES) {
+            return `${SPACING_SIZES[part] * 8}px`;
+          }
+          return part;
+        }).join(' ');
+      }
+    }
+
+    // Single value validation
+    if (CSS_SPACING_PATTERN.test(value)) {
+      return value;
+    } else {
+      console.warn(
+        `[QwickApps] Invalid CSS spacing value: "${value}". Using as-is but consider using a valid CSS value or t-shirt size.`
+      );
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Resolves spacing props with support for directional values
+ */
+export function resolveSpacingProps(props: {
+  padding?: SpacingValue;
+  paddingTop?: SpacingValue;
+  paddingRight?: SpacingValue;
+  paddingBottom?: SpacingValue;
+  paddingLeft?: SpacingValue;
+  paddingX?: SpacingValue;
+  paddingY?: SpacingValue;
+  margin?: SpacingValue;
+  marginTop?: SpacingValue;
+  marginRight?: SpacingValue;
+  marginBottom?: SpacingValue;
+  marginLeft?: SpacingValue;
+  marginX?: SpacingValue;
+  marginY?: SpacingValue;
+}) {
+  const resolved: any = {};
+
+  // Padding
+  if (props.padding !== undefined) {
+    resolved.p = resolveSpacing(props.padding, 'padding');
+  }
+  if (props.paddingTop !== undefined) {
+    resolved.pt = resolveSpacing(props.paddingTop, 'padding');
+  }
+  if (props.paddingRight !== undefined) {
+    resolved.pr = resolveSpacing(props.paddingRight, 'padding');
+  }
+  if (props.paddingBottom !== undefined) {
+    resolved.pb = resolveSpacing(props.paddingBottom, 'padding');
+  }
+  if (props.paddingLeft !== undefined) {
+    resolved.pl = resolveSpacing(props.paddingLeft, 'padding');
+  }
+  if (props.paddingX !== undefined) {
+    resolved.px = resolveSpacing(props.paddingX, 'padding');
+  }
+  if (props.paddingY !== undefined) {
+    resolved.py = resolveSpacing(props.paddingY, 'padding');
+  }
+
+  // Margin
+  if (props.margin !== undefined) {
+    resolved.m = resolveSpacing(props.margin, 'margin');
+  }
+  if (props.marginTop !== undefined) {
+    resolved.mt = resolveSpacing(props.marginTop, 'margin');
+  }
+  if (props.marginRight !== undefined) {
+    resolved.mr = resolveSpacing(props.marginRight, 'margin');
+  }
+  if (props.marginBottom !== undefined) {
+    resolved.mb = resolveSpacing(props.marginBottom, 'margin');
+  }
+  if (props.marginLeft !== undefined) {
+    resolved.ml = resolveSpacing(props.marginLeft, 'margin');
+  }
+  if (props.marginX !== undefined) {
+    resolved.mx = resolveSpacing(props.marginX, 'margin');
+  }
+  if (props.marginY !== undefined) {
+    resolved.my = resolveSpacing(props.marginY, 'margin');
+  }
+
+  return resolved;
+}

package/src/utils/themePerformanceMonitor.js

@@ -0,0 +1,113 @@
+/**
+ * Theme Performance Monitor - Track theme switching performance
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+class ThemePerformanceMonitor {
+  constructor() {
+    this.measurements = [];
+    this.isEnabled = process.env.NODE_ENV === 'development';
+    
+    if (this.isEnabled) {
+      this.initializeListeners();
+    }
+  }
+
+  initializeListeners() {
+    // Listen for theme changes
+    window.addEventListener('theme-changed', (event) => {
+      this.measureThemeSwitch('theme', event.detail?.theme);
+    });
+
+    // Listen for palette changes
+    window.addEventListener('palette-changed', (event) => {
+      this.measureThemeSwitch('palette', event.detail?.palette);
+    });
+  }
+
+  measureThemeSwitch(type, value) {
+    if (!this.isEnabled) return;
+
+    const startTime = performance.now();
+    
+    // Use requestAnimationFrame to measure when the visual change is complete
+    requestAnimationFrame(() => {
+      // Wait for another frame to ensure CSS has been applied
+      requestAnimationFrame(() => {
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        
+        const measurement = {
+          type,
+          value,
+          duration,
+          timestamp: new Date().toISOString(),
+        };
+        
+        this.measurements.push(measurement);
+        
+        // Keep only last 50 measurements
+        if (this.measurements.length > 50) {
+          this.measurements.shift();
+        }
+        
+        // Log if it takes too long
+        if (duration > 100) {
+          console.warn(`Slow ${type} switch detected:`, measurement);
+        } else {
+          console.log(`${type} switch performance:`, `${duration.toFixed(2)}ms`);
+        }
+      });
+    });
+  }
+
+  getStatistics() {
+    if (!this.isEnabled || this.measurements.length === 0) {
+      return null;
+    }
+
+    const durations = this.measurements.map(m => m.duration);
+    const average = durations.reduce((a, b) => a + b, 0) / durations.length;
+    const min = Math.min(...durations);
+    const max = Math.max(...durations);
+    
+    return {
+      totalMeasurements: this.measurements.length,
+      averageDuration: average.toFixed(2),
+      minDuration: min.toFixed(2),
+      maxDuration: max.toFixed(2),
+      recentMeasurements: this.measurements.slice(-10),
+    };
+  }
+
+  logStatistics() {
+    if (!this.isEnabled) return;
+
+    const stats = this.getStatistics();
+    if (stats) {
+      console.group('Theme Performance Statistics');
+      console.log('Total measurements:', stats.totalMeasurements);
+      console.log('Average duration:', stats.averageDuration + 'ms');
+      console.log('Min duration:', stats.minDuration + 'ms');
+      console.log('Max duration:', stats.maxDuration + 'ms');
+      console.log('Recent measurements:', stats.recentMeasurements);
+      console.groupEnd();
+    }
+  }
+
+  reset() {
+    this.measurements = [];
+  }
+}
+
+// Create a singleton instance
+const themePerformanceMonitor = new ThemePerformanceMonitor();
+
+// Export methods
+export const getThemePerformanceStats = () => themePerformanceMonitor.getStatistics();
+export const logThemePerformanceStats = () => themePerformanceMonitor.logStatistics();
+export const resetThemePerformanceStats = () => themePerformanceMonitor.reset();
+
+// Export the monitor instance for advanced usage
+export default themePerformanceMonitor;

package/src/utils/themeUtils.ts

@@ -0,0 +1,67 @@
+// Theme utilities for QwickApps Theme System
+
+import { ThemeMode, ActualThemeMode } from '../contexts/ThemeContext';
+
+// Re-export types for convenience
+export type { ThemeMode, ActualThemeMode } from '../contexts/ThemeContext';
+
+/**
+ * Get the current theme mode from CSS variables
+ */
+export const getCurrentTheme = (): ThemeMode => {
+  const root = document.documentElement;
+  const theme = root.getAttribute('data-theme') as ThemeMode;
+  return theme || 'system';
+};
+
+/**
+ * Set theme mode and update CSS variables
+ */
+export const setTheme = (theme: ThemeMode): void => {
+  const root = document.documentElement;
+  root.setAttribute('data-theme', theme);
+  
+  // Trigger custom event for theme change
+  window.dispatchEvent(new CustomEvent('themeChange', { detail: { theme } }));
+};
+
+/**
+ * Get system preference for dark mode
+ */
+export const getSystemTheme = (): ActualThemeMode => {
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+};
+
+/**
+ * Get computed theme (resolves 'system' to actual light/dark)
+ */
+export const getComputedTheme = (theme: ThemeMode = getCurrentTheme()): ActualThemeMode => {
+  if (theme === 'system') {
+    return getSystemTheme();
+  }
+  return theme as ActualThemeMode;
+};
+
+/**
+ * Initialize theme system
+ */
+export const initializeTheme = (): void => {
+  const savedTheme = (localStorage.getItem('theme') as ThemeMode) || 'system';
+  setTheme(savedTheme);
+  
+  // Listen for system theme changes
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    if (getCurrentTheme() === 'system') {
+      // Trigger re-render for system theme changes
+      window.dispatchEvent(new CustomEvent('themeChange', { detail: { theme: 'system' } }));
+    }
+  });
+};
+
+/**
+ * Save theme preference to localStorage
+ */
+export const saveThemePreference = (theme: ThemeMode): void => {
+  localStorage.setItem('theme', theme);
+  setTheme(theme);
+};