@qwickapps/react-framework 1.3.0

package/src/utils/__tests__/htmlTransform.test.tsx

@@ -0,0 +1,255 @@
+/**
+ * HTML Transform Utilities Tests
+ */
+
+import { render } from '@testing-library/react';
+import React from 'react';
+import { 
+  transformElement, 
+  transformHtmlToReact, 
+  stripHeaderFromContent,
+  defaultArticleRules,
+  defaultMarkdownRules
+} from '../htmlTransform';
+
+// Helper function to create DOM elements for testing
+function createElementFromHTML(html: string): Element {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+  return doc.body.firstElementChild!;
+}
+
+describe('HTML Transform Utilities', () => {
+  
+  describe('stripHeaderFromContent', () => {
+    it('removes blog headers from HTML content', () => {
+      const html = '<header class="blog-header"><h1>Title</h1></header><p>Content</p>';
+      const result = stripHeaderFromContent(html);
+      expect(result).not.toContain('<header');
+      expect(result).toContain('<p>Content</p>');
+    });
+
+    it('removes standalone h1 elements', () => {
+      const html = '<h1>Main Title</h1><p>Content follows</p>';
+      const result = stripHeaderFromContent(html);
+      expect(result).not.toContain('<h1>Main Title</h1>');
+      expect(result).toContain('<p>Content follows</p>');
+    });
+
+    it('preserves content when no headers present', () => {
+      const html = '<p>Just content</p><div>More content</div>';
+      const result = stripHeaderFromContent(html);
+      expect(result).toBe(html);
+    });
+
+    it('handles multiple header types', () => {
+      const html = '<header class="blog-header">Header 1</header><div class="blog-header">Header 2</div><p>Content</p>';
+      const result = stripHeaderFromContent(html);
+      expect(result).not.toContain('Header 1');
+      expect(result).not.toContain('Header 2');
+      expect(result).toContain('<p>Content</p>');
+    });
+  });
+
+  describe('transformElement', () => {
+    it('transforms pre+code elements to Code components', () => {
+      const element = createElementFromHTML('<pre><code class="language-javascript">console.log("test");</code></pre>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('console.log("test");');
+    });
+
+    it('transforms blog sections to Section components', () => {
+      const element = createElementFromHTML('<section class="blog-section"><h2>Section Title</h2><p>Content</p></section>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('Section Title');
+      expect(container.textContent).toContain('Content');
+    });
+
+    it('transforms button elements to Button components', () => {
+      const element = createElementFromHTML('<button data-variant="contained">Click Me</button>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('Click Me');
+    });
+
+    it('handles standalone code blocks', () => {
+      const element = createElementFromHTML('<code>multi\nline\ncode</code>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('multi\nline\ncode');
+    });
+
+    it('preserves inline code in paragraphs', () => {
+      const element = createElementFromHTML('<p>Text with <code>inline code</code> here</p>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('inline code');
+    });
+
+    it('handles void elements correctly', () => {
+      const element = createElementFromHTML('<img src="test.jpg" alt="test" />');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      const img = container.querySelector('img');
+      expect(img).toHaveAttribute('src', 'test.jpg');
+      expect(img).toHaveAttribute('alt', 'test');
+    });
+
+    it('falls back to SafeSpan for unknown elements', () => {
+      const element = createElementFromHTML('<div class="unknown">Some content</div>');
+      const result = transformElement(element, 'test-key', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('Some content');
+    });
+  });
+
+  describe('transformHtmlToReact', () => {
+    it('transforms entire HTML documents', () => {
+      const html = '<h1>Title</h1><p>Paragraph</p><pre><code>code block</code></pre>';
+      const components = transformHtmlToReact(html, { rules: defaultArticleRules });
+      
+      expect(components).toHaveLength(3); // h1, p, and code block
+      
+      const { container } = render(<>{components}</>);
+      expect(container.textContent).toContain('Title');
+      expect(container.textContent).toContain('Paragraph');
+      expect(container.textContent).toContain('code block');
+    });
+
+    it('returns empty array for empty HTML', () => {
+      const components = transformHtmlToReact('', { rules: defaultArticleRules });
+      expect(components).toEqual([]);
+    });
+
+    it('handles whitespace-only HTML', () => {
+      const components = transformHtmlToReact('   \n   ', { rules: defaultArticleRules });
+      expect(components).toEqual([]);
+    });
+
+    it('transforms complex nested structures', () => {
+      const html = `
+        <div class="container">
+          <section class="blog-section">
+            <h2>Section</h2>
+            <pre><code class="language-python">print("hello")</code></pre>
+          </section>
+        </div>
+      `;
+      const components = transformHtmlToReact(html, { rules: defaultArticleRules });
+      
+      const { container } = render(<>{components}</>);
+      expect(container.textContent).toContain('Section');
+      expect(container.textContent).toContain('print("hello")');
+    });
+  });
+
+  describe('defaultArticleRules', () => {
+    it('includes pre+code transformation rule', () => {
+      const preRule = defaultArticleRules.find(rule => rule.selector === 'pre');
+      expect(preRule).toBeDefined();
+    });
+
+    it('includes standalone code transformation rule', () => {
+      const codeRule = defaultArticleRules.find(rule => rule.selector === 'code');
+      expect(codeRule).toBeDefined();
+    });
+
+    it('includes blog section transformation rule', () => {
+      const sectionRule = defaultArticleRules.find(rule => rule.selector === 'section.blog-section');
+      expect(sectionRule).toBeDefined();
+    });
+
+    it('includes button transformation rule', () => {
+      const buttonRule = defaultArticleRules.find(rule => rule.selector === 'button');
+      expect(buttonRule).toBeDefined();
+    });
+  });
+
+  describe('defaultMarkdownRules', () => {
+    it('includes pre+code transformation rule', () => {
+      const preRule = defaultMarkdownRules.find(rule => rule.selector === 'pre');
+      expect(preRule).toBeDefined();
+    });
+
+    it('includes code rule that preserves inline code', () => {
+      const codeRule = defaultMarkdownRules.find(rule => rule.selector === 'code');
+      expect(codeRule).toBeDefined();
+      
+      // Test that inline code returns null (no transformation)
+      const element = createElementFromHTML('<code>inline</code>');
+      const result = codeRule!.transform(element, 'test');
+      expect(result).toBeNull();
+    });
+
+    it('has fewer rules than article rules (more conservative)', () => {
+      expect(defaultMarkdownRules.length).toBeLessThan(defaultArticleRules.length);
+    });
+  });
+
+  describe('Custom Transform Rules', () => {
+    it('applies custom transformation rules', () => {
+      const customRules = [{
+        selector: 'em',
+        transform: (element: Element, key: string) => (
+          <strong key={key}>EMPHASIZED: {element.textContent}</strong>
+        )
+      }];
+
+      const element = createElementFromHTML('<em>italic text</em>');
+      const result = transformElement(element, 'test', { rules: customRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('EMPHASIZED: italic text');
+    });
+
+    it('combines custom rules with default rules', () => {
+      const customRules = [...defaultArticleRules, {
+        selector: 'span.highlight',
+        transform: (element: Element, key: string) => (
+          <mark key={key}>{element.textContent}</mark>
+        )
+      }];
+
+      const html = '<span class="highlight">highlighted</span><pre><code>code</code></pre>';
+      const components = transformHtmlToReact(html, { rules: customRules });
+      
+      const { container } = render(<>{components}</>);
+      expect(container.textContent).toContain('highlighted');
+      expect(container.textContent).toContain('code');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles malformed HTML elements', () => {
+      const element = createElementFromHTML('<div>unclosed content');
+      const result = transformElement(element, 'test', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('unclosed content');
+    });
+
+    it('handles elements with missing attributes', () => {
+      const element = createElementFromHTML('<button>No attributes</button>');
+      const result = transformElement(element, 'test', { rules: defaultArticleRules });
+      
+      const { container } = render(<>{result}</>);
+      expect(container.textContent).toContain('No attributes');
+    });
+
+    it('handles empty elements', () => {
+      const element = createElementFromHTML('<div></div>');
+      const result = transformElement(element, 'test', { rules: defaultArticleRules });
+      
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/utils/breakpoints.ts

@@ -0,0 +1,87 @@
+/**
+ * Breakpoint utilities for QwickApps React Framework
+ * 
+ * Consolidates all breakpoint-related logic and type conversions
+ * to ensure consistency across components.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { MUIBreakpoint, BreakpointValue, ExtendedBreakpoint } from '../types';
+
+/**
+ * Standard MUI breakpoint pixel values
+ */
+export const MUI_BREAKPOINT_VALUES: Record<MUIBreakpoint, number> = {
+  xs: 0,
+  sm: 600,
+  md: 900,
+  lg: 1200,
+  xl: 1536,
+};
+
+/**
+ * Mapping from extended names to MUI breakpoint names
+ */
+const EXTENDED_TO_MUI_MAP: Record<ExtendedBreakpoint, MUIBreakpoint> = {
+  'extra-small': 'xs',
+  'small': 'sm',
+  'medium': 'md',
+  'large': 'lg',
+  'extra-large': 'xl',
+};
+
+/**
+ * Converts any breakpoint value to MUI breakpoint format
+ * Handles extended names, MUI names, and false values
+ */
+export function mapToMUIBreakpoint(value?: BreakpointValue): MUIBreakpoint | false {
+  if (value === false || value === undefined) {
+    return false;
+  }
+  
+  // Direct MUI breakpoint
+  if (value in MUI_BREAKPOINT_VALUES) {
+    return value as MUIBreakpoint;
+  }
+  
+  // Extended breakpoint name
+  if (value in EXTENDED_TO_MUI_MAP) {
+    return EXTENDED_TO_MUI_MAP[value as ExtendedBreakpoint];
+  }
+  
+  // Default fallback
+  return 'lg';
+}
+
+/**
+ * Gets the pixel value for a breakpoint
+ */
+export function getBreakpointPixelValue(breakpoint: MUIBreakpoint | BreakpointValue): number {
+  const muiBreakpoint = mapToMUIBreakpoint(breakpoint as BreakpointValue);
+  if (muiBreakpoint === false) {
+    return Infinity; // No max width
+  }
+  return MUI_BREAKPOINT_VALUES[muiBreakpoint];
+}
+
+/**
+ * Type guard to check if a value is a valid MUI breakpoint
+ */
+export function isMUIBreakpoint(value: unknown): value is MUIBreakpoint {
+  return typeof value === 'string' && value in MUI_BREAKPOINT_VALUES;
+}
+
+/**
+ * Type guard to check if a value is an extended breakpoint name
+ */
+export function isExtendedBreakpoint(value: unknown): value is ExtendedBreakpoint {
+  return typeof value === 'string' && value in EXTENDED_TO_MUI_MAP;
+}
+
+/**
+ * Type guard to check if a value is any valid breakpoint
+ */
+export function isBreakpointValue(value: unknown): value is BreakpointValue {
+  return value === false || isMUIBreakpoint(value) || isExtendedBreakpoint(value);
+}

package/src/utils/customPaletteManager.js

@@ -0,0 +1,214 @@
+/**
+ * Custom Palette Manager - Create and manage custom color palettes
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Saves a custom palette to localStorage
+ * @param {Object} palette - Palette object with id, name, colors, etc.
+ */
+export const saveCustomPalette = (palette) => {
+  const customPalettes = getCustomPalettes();
+  const updatedPalettes = customPalettes.filter(p => p.id !== palette.id);
+  updatedPalettes.push(palette);
+  
+  localStorage.setItem('qwickapps-custom-palettes', JSON.stringify(updatedPalettes));
+  
+  // Dispatch event to notify components
+  window.dispatchEvent(new CustomEvent('custom-palettes-changed', {
+    detail: { palettes: updatedPalettes }
+  }));
+};
+
+/**
+ * Gets all custom palettes from localStorage
+ * @returns {Array} Array of custom palette objects
+ */
+export const getCustomPalettes = () => {
+  try {
+    const stored = localStorage.getItem('qwickapps-custom-palettes');
+    return stored ? JSON.parse(stored) : [];
+  } catch (error) {
+    console.warn('Failed to load custom palettes:', error);
+    return [];
+  }
+};
+
+/**
+ * Deletes a custom palette
+ * @param {string} paletteId - ID of the palette to delete
+ */
+export const deleteCustomPalette = (paletteId) => {
+  const customPalettes = getCustomPalettes();
+  const updatedPalettes = customPalettes.filter(p => p.id !== paletteId);
+  
+  localStorage.setItem('qwickapps-custom-palettes', JSON.stringify(updatedPalettes));
+  
+  // Dispatch event to notify components
+  window.dispatchEvent(new CustomEvent('custom-palettes-changed', {
+    detail: { palettes: updatedPalettes }
+  }));
+};
+
+/**
+ * Exports a palette to a JSON file
+ * @param {Object} palette - Palette to export
+ */
+export const exportPalette = (palette) => {
+  const dataStr = JSON.stringify(palette, null, 2);
+  const dataBlob = new Blob([dataStr], { type: 'application/json' });
+  
+  const link = document.createElement('a');
+  link.href = URL.createObjectURL(dataBlob);
+  link.download = `qwickapps-palette-${palette.id}.json`;
+  link.click();
+  
+  URL.revokeObjectURL(link.href);
+};
+
+/**
+ * Imports a palette from a JSON file
+ * @param {File} file - JSON file containing palette data
+ * @returns {Promise<Object>} Parsed palette object
+ */
+export const importPalette = (file) => {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    
+    reader.onload = (event) => {
+      try {
+        const palette = JSON.parse(event.target.result);
+        
+        // Basic validation
+        if (!palette.id || !palette.name || !palette.primaryColor) {
+          reject(new Error('Invalid palette format'));
+          return;
+        }
+        
+        // Ensure unique ID
+        const customPalettes = getCustomPalettes();
+        if (customPalettes.find(p => p.id === palette.id)) {
+          palette.id = `${palette.id}-${Date.now()}`;
+        }
+        
+        resolve(palette);
+      } catch (error) {
+        reject(new Error('Failed to parse palette file'));
+      }
+    };
+    
+    reader.onerror = () => reject(new Error('Failed to read file'));
+    reader.readAsText(file);
+  });
+};
+
+/**
+ * Creates a new custom palette from current theme colors
+ * @param {string} name - Name for the new palette
+ * @param {string} description - Description for the palette
+ * @returns {Object} New palette object
+ */
+export const createPaletteFromCurrentTheme = (name, description) => {
+  const root = document.documentElement;
+  const style = getComputedStyle(root);
+  
+  // Extract current colors
+  const palette = {
+    id: `custom-${Date.now()}`,
+    name,
+    description,
+    isCustom: true,
+    createdAt: new Date().toISOString(),
+    primaryColor: style.getPropertyValue('--palette-primary-main').trim(),
+    colors: {
+      primary: {
+        main: style.getPropertyValue('--palette-primary-main').trim(),
+        light: style.getPropertyValue('--palette-primary-light').trim(),
+        dark: style.getPropertyValue('--palette-primary-dark').trim(),
+      },
+      secondary: {
+        main: style.getPropertyValue('--palette-secondary-main').trim(),
+        light: style.getPropertyValue('--palette-secondary-light').trim(),
+        dark: style.getPropertyValue('--palette-secondary-dark').trim(),
+      },
+      background: {
+        main: style.getPropertyValue('--palette-background-main').trim(),
+        secondary: style.getPropertyValue('--palette-background-dark').trim(),
+      },
+      surface: {
+        main: style.getPropertyValue('--palette-surface-main').trim(),
+        variant: style.getPropertyValue('--palette-surface-variant').trim(),
+        elevated: style.getPropertyValue('--palette-surface-elevated').trim(),
+      },
+      text: {
+        primary: style.getPropertyValue('--palette-text-primary').trim(),
+        secondary: style.getPropertyValue('--palette-text-secondary').trim(),
+        disabled: style.getPropertyValue('--palette-text-disabled').trim(),
+      },
+      border: {
+        main: style.getPropertyValue('--palette-border-main').trim(),
+        light: style.getPropertyValue('--palette-border-light').trim(),
+        medium: style.getPropertyValue('--palette-border-medium').trim(),
+      },
+      success: {
+        main: style.getPropertyValue('--palette-success-main').trim(),
+        light: style.getPropertyValue('--palette-success-light').trim(),
+        dark: style.getPropertyValue('--palette-success-dark').trim(),
+      },
+      error: {
+        main: style.getPropertyValue('--palette-error-main').trim(),
+        light: style.getPropertyValue('--palette-error-light').trim(),
+        dark: style.getPropertyValue('--palette-error-dark').trim(),
+      },
+      warning: {
+        main: style.getPropertyValue('--palette-warning-main').trim(),
+        light: style.getPropertyValue('--palette-warning-light').trim(),
+        dark: style.getPropertyValue('--palette-warning-dark').trim(),
+      },
+      info: {
+        main: style.getPropertyValue('--palette-info-main').trim(),
+        light: style.getPropertyValue('--palette-info-light').trim(),
+        dark: style.getPropertyValue('--palette-info-dark').trim(),
+      },
+    }
+  };
+  
+  return palette;
+};
+
+/**
+ * Applies a custom palette dynamically
+ * @param {Object} palette - Custom palette object
+ */
+export const applyCustomPalette = (palette) => {
+  const root = document.documentElement;
+  
+  // Apply colors to CSS custom properties
+  if (palette.colors) {
+    const { colors } = palette;
+    
+    // Apply primary colors
+    if (colors.primary) {
+      root.style.setProperty('--palette-primary-main', colors.primary.main);
+      root.style.setProperty('--palette-primary-light', colors.primary.light);
+      root.style.setProperty('--palette-primary-dark', colors.primary.dark);
+    }
+    
+    // Apply secondary colors
+    if (colors.secondary) {
+      root.style.setProperty('--palette-secondary-main', colors.secondary.main);
+      root.style.setProperty('--palette-secondary-light', colors.secondary.light);
+      root.style.setProperty('--palette-secondary-dark', colors.secondary.dark);
+    }
+    
+    // Apply background colors
+    if (colors.background) {
+      root.style.setProperty('--palette-background-main', colors.background.main);
+      root.style.setProperty('--palette-background-dark', colors.background.secondary);
+    }
+    
+    // Apply other color categories as needed...
+    // (This could be expanded to apply all color categories)
+  }
+};

package/src/utils/dimensions.ts

@@ -0,0 +1,147 @@
+/**
+ * Dimension utilities for QwickApps React Framework
+ * 
+ * Provides standardized dimension value resolution with t-shirt sizing
+ * and MUI breakpoint compatibility
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { DimensionValue, TShirtSize, MUIBreakpoint } from '../types';
+
+// Re-export the type for backward compatibility
+export type { DimensionValue };
+import { MUI_BREAKPOINT_VALUES } from './breakpoints';
+
+export type DimensionContext = 'width' | 'height' | 'maxWidth' | 'maxHeight' | 'minWidth' | 'minHeight';
+
+/**
+ * T-shirt size mappings for different dimension contexts
+ */
+const TSHIRT_SIZES: Record<DimensionContext, Record<TShirtSize, number>> = {
+  width: {
+    tiny: 120,
+    small: 200,
+    medium: 300,
+    large: 400,
+    'x-large': 500,
+    huge: 600,
+  },
+  height: {
+    tiny: 200,
+    small: 300,
+    medium: 400,
+    large: 500,
+    'x-large': 600,
+    huge: 800,
+  },
+  maxWidth: {
+    tiny: 300,
+    small: 600,
+    medium: 900,
+    large: 1200,
+    'x-large': 1536,
+    huge: 1920,
+  },
+  maxHeight: {
+    tiny: 200,
+    small: 400,
+    medium: 600,
+    large: 800,
+    'x-large': 1000,
+    huge: 1200,
+  },
+  minWidth: {
+    tiny: 50,
+    small: 100,
+    medium: 200,
+    large: 300,
+    'x-large': 400,
+    huge: 500,
+  },
+  minHeight: {
+    tiny: 50,
+    small: 100,
+    medium: 200,
+    large: 300,
+    'x-large': 400,
+    huge: 500,
+  },
+};
+
+/**
+ * CSS value pattern for validation
+ */
+const CSS_VALUE_PATTERN = /^(\d+(\.\d+)?(px|%|em|rem|vh|vw|fr|ch|ex)|auto|inherit|initial|unset|min-content|max-content|fit-content)$/;
+
+/**
+ * Resolves a dimension value to a valid CSS value
+ */
+export function resolveDimension(
+  value: DimensionValue,
+  context: DimensionContext = 'width'
+): string | number | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  // Number values are returned as-is
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  // Auto and grow are always valid
+  if (value === 'auto') {
+    return 'auto';
+  }
+  
+  if (value === 'grow') {
+    return '1';  // Flex grow: 1 for CSS flexbox
+  }
+
+  // Check for t-shirt sizes
+  const tshirtSizes = TSHIRT_SIZES[context];
+  if (tshirtSizes && value in tshirtSizes) {
+    return tshirtSizes[value as TShirtSize];
+  }
+  
+  // Check for MUI breakpoint values (for maxWidth/width contexts)
+  if ((context === 'maxWidth' || context === 'width') && value in MUI_BREAKPOINT_VALUES) {
+    return MUI_BREAKPOINT_VALUES[value as MUIBreakpoint];
+  }
+
+  // Validate CSS string values
+  if (typeof value === 'string') {
+    if (CSS_VALUE_PATTERN.test(value)) {
+      return value;
+    } else {
+      console.warn(
+        `[QwickApps] Invalid CSS dimension value: "${value}". Using as-is but consider using a valid CSS value or t-shirt size.`
+      );
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Resolves multiple dimension props at once
+ */
+export function resolveDimensions(props: {
+  width?: DimensionValue;
+  height?: DimensionValue;
+  minWidth?: DimensionValue;
+  minHeight?: DimensionValue;
+  maxWidth?: DimensionValue;
+  maxHeight?: DimensionValue;
+}) {
+  return {
+    width: resolveDimension(props.width, 'width'),
+    height: resolveDimension(props.height, 'height'),
+    minWidth: resolveDimension(props.minWidth, 'minWidth'),
+    minHeight: resolveDimension(props.minHeight, 'minHeight'),
+    maxWidth: resolveDimension(props.maxWidth, 'maxWidth'),
+    maxHeight: resolveDimension(props.maxHeight, 'maxHeight'),
+  };
+}