@qwickapps/react-framework 1.3.0

package/src/components/Logo.tsx

@@ -0,0 +1,370 @@
+/**
+ * Dynamic Logo Component - Generic theme-aware logo
+ * 
+ * Features:
+ * - Automatic text width calculation with dynamic SVG sizing
+ * - Semantic badge positioning (top-left, top-right, center, etc.)
+ * - Customizable badge position via custom coordinates or relative offset
+ * - Multiple badge shapes: circle, star, square, heart
+ * - Theme-aware styling with multiple variants
+ * - Accessibility support with proper ARIA labels
+ * - Customizable styling via CSS classes for each text part
+ * - Text formatting with escape sequences
+ * 
+ * Text Formatting (TWO PARTS MAXIMUM):
+ * - Use \n for line breaks (second part appears on new line)
+ * - Use \s for explicit spaces (useful for custom spacing)
+ * - Default: Two-word logos appear as one word in two colors (no space)
+ * - Limitation: Only TWO parts supported - multiple \n will not create more than two lines
+ * - Examples: "QwickApps" (one word, one color), "Qwick Apps" (two parts, two colors), "Qwick\sApps" (two parts with space), "Qwick\nApps" (two parts on two lines)
+ * 
+ * Badge Positioning:
+ * - Semantic: Use 'top-left', 'top-right', 'center', etc. (automatically adapts to logo size)
+ * - Default: 'top-right' - positions at top-right of text
+ * - Offset: Use badgeOffset to fine-tune any position (automatically scales with size)
+ * - None: Use 'none' to hide the badge
+ * - Flexible: Combine any semantic position with custom offsets for precise control
+ * 
+ * Text Styling:
+ * - Use firstPartClass and secondPartClass for custom CSS styling
+ * - Default classes: 'logo-first-part' and 'logo-second-part'
+ * - Font family and weight can be set via props for basic customization
+ * - Advanced styling (colors, effects, transforms) via CSS classes
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useRef, useEffect, useState, useCallback } from 'react';
+import { WithBaseProps, useBaseProps, QWICKAPP_COMPONENT } from '../hooks/useBaseProps';
+import './Logo.css';
+
+export type LogoVariant = 'default' | 'high-contrast' | 'monochrome' | 'on-primary';
+export type LogoSize = 'tiny' | 'small' | 'medium' | 'large' | 'extra-large';
+export type LogoBadgeShape = 'circle' | 'star' | 'square' | 'heart';
+export type BadgePositionType = 
+  | 'none'
+  | 'top-left' 
+  | 'top-center' 
+  | 'top-right' 
+  | 'center-left' 
+  | 'center' 
+  | 'center-right' 
+  | 'bottom-left' 
+  | 'bottom-center' 
+  | 'bottom-right';
+
+export interface BadgeOffset {
+  /** Horizontal offset from the calculated position (positive = right, negative = left) */
+  x?: number;
+  /** Vertical offset from the calculated position (positive = down, negative = up) */
+  y?: number;
+}
+
+export interface LogoProps extends WithBaseProps, Omit<React.SVGProps<SVGSVGElement>, 'width' | 'height' | 'className' | 'style' | 'role' | 'onClick' | 'onMouseEnter' | 'onMouseLeave' | 'onFocus' | 'onBlur'> {
+  /** Logo name/text to display. Supports up to TWO parts with \n for line breaks and \s for explicit spaces. */
+  name?: string;
+  /** Click handler for the logo */
+  onClick?: (event: React.MouseEvent<SVGSVGElement>) => void;
+  /** Additional inline styles */
+  style?: React.CSSProperties;
+  /** Visual variant of the logo */
+  variant?: LogoVariant;
+  /** Size variant of the logo (controls both text size and visual height) */
+  size?: LogoSize;
+  /** Additional CSS class names */
+  className?: string;
+  /** Badge position and visibility. 'none' hides the badge, others show it at the specified position. */
+  badge?: BadgePositionType;
+  /** Shape of the badge */
+  badgeShape?: LogoBadgeShape;
+  /** Offset from the calculated badge position. Applied after position calculation. Automatically scales with logo size. */
+  badgeOffset?: BadgeOffset;
+  /** Font family for the logo text */
+  fontFamily?: string;
+  /** Font weight for the logo text */
+  fontWeight?: string | number;
+  /** CSS class name for the first part of the logo text. Defaults to 'logo-first-part'. */
+  firstPartClass?: string;
+  /** CSS class name for the second part of the logo text. Defaults to 'logo-second-part'. */
+  secondPartClass?: string;
+}
+
+const Logo: React.FC<LogoProps> = (props) => {
+  const { styleProps, htmlProps, restProps } = useBaseProps(props);
+  const {
+    name = 'Qwick Apps',
+    variant = 'default',
+    size = 'medium',
+    badge = 'top-right',
+    badgeShape = 'circle',
+    badgeOffset,
+    fontFamily = 'Segoe UI, sans-serif',
+    fontWeight = 'bold',
+    firstPartClass = 'logo-first-part',
+    secondPartClass = 'logo-second-part',
+    ...svgProps
+  } = restProps;
+  
+  // Mark as QwickApp component
+  (Logo as any)[QWICKAPP_COMPONENT] = true;
+  
+  const textRef = useRef<SVGTextElement>(null);
+  const [calculatedBadgePosition, setCalculatedBadgePosition] = useState({ x: 155, y: 20 });
+  const [svgWidth, setSvgWidth] = useState(180);
+
+  // Parse name with support for escape sequences to determine structure
+  const parseNameParts = useCallback((text: string) => {
+    // Handle line breaks first
+    if (text.includes('\\n')) {
+      const [first, ...rest] = text.split('\\n');
+      return {
+        firstPart: first.replace(/\\s/g, ' '),
+        secondPart: rest.join('\\n').replace(/\\s/g, ' '),
+        isNewLine: true
+      };
+    }
+    
+    // Check if text contains explicit \s sequences
+    if (text.includes('\\s')) {
+      // Handle explicit spaces - split by \s and treat as two parts
+      const parts = text.split('\\s');
+      if (parts.length >= 2) {
+        return {
+          firstPart: parts[0],
+          secondPart: parts.slice(1).join(' '), // Join remaining parts with spaces
+          isNewLine: false
+        };
+      } else {
+        return { firstPart: parts[0], secondPart: '', isNewLine: false };
+      }
+    }
+    
+    // Regular word splitting (no explicit \s)
+    const nameParts = text.trim().split(/\s+/);
+    
+    if (nameParts.length === 1) {
+      return { firstPart: nameParts[0], secondPart: '', isNewLine: false };
+    } else if (nameParts.length === 2) {
+      return { firstPart: nameParts[0], secondPart: nameParts[1], isNewLine: false };
+    } else {
+      // More than 2 words: everything except last word goes to first part
+      return {
+        firstPart: nameParts.slice(0, -1).join(' '),
+        secondPart: nameParts[nameParts.length - 1],
+        isNewLine: false
+      };
+    }
+  }, []);
+
+  const { firstPart, secondPart, isNewLine } = parseNameParts(name);
+  
+  // Check if original name contained explicit spaces
+  const hasExplicitSpaces = name.includes('\\s');
+
+  // Determine size class, font size, and component height (accounting for line breaks)
+  const sizeClass = `logo-${size}`;
+  const getSizeConfig = (size: LogoSize, hasLineBreak: boolean) => {
+    const baseConfig = {
+      'tiny': { fontSize: 16, height: 32 },
+      'small': { fontSize: 20, height: 40 },
+      'medium': { fontSize: 28, height: 50 },
+      'large': { fontSize: 36, height: 64 },
+      'extra-large': { fontSize: 48, height: 84 }
+    };
+    
+    const config = baseConfig[size] || baseConfig.medium;
+    
+    // Add extra height for line breaks (approximately 1.4x the font size for proper spacing)
+    if (hasLineBreak) {
+      config.height += Math.round(config.fontSize * 1.4);
+    }
+    
+    return config;
+  };
+  const { fontSize, height } = getSizeConfig(size, isNewLine);
+
+  // Calculate badge position based on semantic positioning system
+  const calculateBadgePosition = useCallback((textBBox: DOMRect, svgWidth: number, svgHeight: number) => {
+    // Scale factor based on font size (medium/28px is the baseline)
+    const scale = fontSize / 28; // 28 is the medium/default font size
+    const scaledOffset = 8 * scale;
+    
+    // Scale custom offset based on size
+    const scaledOffsetX = (badgeOffset?.x ?? 0) * scale;
+    const scaledOffsetY = (badgeOffset?.y ?? 0) * scale;
+    
+    // Calculate position based on semantic positioning
+    let x: number, y: number;
+    
+    switch (badge) {
+      case 'top-left':
+        x = textBBox.x - scaledOffset;
+        y = textBBox.y + scaledOffset;
+        break;
+      case 'top-center':
+        x = textBBox.x + textBBox.width / 2;
+        y = textBBox.y + scaledOffset;
+        break;
+      case 'top-right':
+        x = textBBox.x + textBBox.width + scaledOffset;
+        y = textBBox.y + scaledOffset;
+        break;
+      case 'center-left':
+        x = textBBox.x - scaledOffset;
+        y = textBBox.y + textBBox.height / 2;
+        break;
+      case 'center':
+        x = textBBox.x + textBBox.width / 2;
+        y = textBBox.y + textBBox.height / 2;
+        break;
+      case 'center-right':
+        x = textBBox.x + textBBox.width + scaledOffset;
+        y = textBBox.y + textBBox.height / 2;
+        break;
+      case 'bottom-left':
+        x = textBBox.x - scaledOffset;
+        y = textBBox.y + textBBox.height - scaledOffset;
+        break;
+      case 'bottom-center':
+        x = textBBox.x + textBBox.width / 2;
+        y = textBBox.y + textBBox.height - scaledOffset;
+        break;
+      case 'bottom-right':
+        x = textBBox.x + textBBox.width + scaledOffset;
+        y = textBBox.y + textBBox.height - scaledOffset;
+        break;
+      default:
+        // Default: top-right of text
+        x = textBBox.x + textBBox.width + scaledOffset;
+        y = textBBox.y + scaledOffset;
+        break;
+    }
+    
+    return {
+      x: x + scaledOffsetX,
+      y: y + scaledOffsetY
+    };
+  }, [badge, badgeOffset, fontSize]);
+
+  // Calculate badge position and SVG width based on text width
+  useEffect(() => {
+    if (textRef.current) {
+      const textBBox = textRef.current.getBBox();
+      // Calculate badge position using semantic positioning
+      const badgePos = calculateBadgePosition(textBBox, svgWidth, height);
+      // Ensure SVG is wide enough to accommodate text and badge
+      const requiredWidth = Math.max(180, textBBox.x + textBBox.width + 20);
+      
+      setCalculatedBadgePosition(badgePos);
+      setSvgWidth(requiredWidth);
+    }
+  }, [name, badge, badgeOffset, calculateBadgePosition, fontSize, height, parseNameParts]);
+  
+  // Determine CSS class for variant
+  let variantClass = '';
+  if (variant === 'high-contrast' || variant === 'monochrome' || variant === 'on-primary') {
+    variantClass = `logo-${variant}`;
+  } else if (variant !== 'default') {
+    variantClass = `logo-${variant}`;
+  } else {
+    variantClass = 'logo-default';
+  }
+  
+  // Create aria-label from the logo name
+  const ariaLabel = `${name} Logo`;
+  
+  // Render badge shape
+  const renderBadgeShape = (): React.ReactNode => {
+    if (badge === 'none') return null;
+    
+    const baseProps = {
+      className: `logo-badge logo-badge-${badgeShape}`,
+    };
+    
+    // Use the calculated position (which includes custom position logic)
+    const { x, y } = calculatedBadgePosition;
+    
+    // Scale badge size based on font size
+    const scale = fontSize / 28; // 28 is the medium/default font size
+    const badgeRadius = 5 * scale;
+    const badgeSize = 10 * scale;
+    
+    switch (badgeShape) {
+      case 'circle':
+        return (
+          <circle cx={x} cy={y} r={badgeRadius} {...baseProps}>
+            <animate attributeName="r" values={`${badgeRadius};${badgeRadius + 1};${badgeRadius}`} dur="1.5s" repeatCount="indefinite" />
+          </circle>
+        );
+      case 'star':
+        const starScale = scale;
+        return (
+          <polygon 
+            points={`${x},${y-5*starScale} ${x+2*starScale},${y} ${x+7*starScale},${y} ${x+3*starScale},${y+3*starScale} ${x+5*starScale},${y+8*starScale} ${x},${y+5*starScale} ${x-5*starScale},${y+8*starScale} ${x-3*starScale},${y+3*starScale} ${x-7*starScale},${y} ${x-2*starScale},${y}`}
+            {...baseProps}
+          >
+            <animate attributeName="opacity" values="0.8;1;0.8" dur="1.5s" repeatCount="indefinite" />
+          </polygon>
+        );
+      case 'square':
+        return (
+          <rect x={x-badgeRadius} y={y-badgeRadius} width={badgeSize} height={badgeSize} {...baseProps}>
+            <animate attributeName="opacity" values="0.8;1;0.8" dur="1.5s" repeatCount="indefinite" />
+          </rect>
+        );
+      case 'heart':
+        const heartScale = scale;
+        return (
+          <path
+            d={`M${x},${y+6*heartScale} C${x},${y+6*heartScale} ${x-7*heartScale},${y} ${x-7*heartScale},${y-4*heartScale} C${x-7*heartScale},${y-6*heartScale} ${x-5*heartScale},${y-8*heartScale} ${x-3*heartScale},${y-8*heartScale} C${x-2*heartScale},${y-8*heartScale} ${x},${y-7*heartScale} ${x},${y-5*heartScale} C${x},${y-7*heartScale} ${x+2*heartScale},${y-8*heartScale} ${x+3*heartScale},${y-8*heartScale} C${x+5*heartScale},${y-8*heartScale} ${x+7*heartScale},${y-6*heartScale} ${x+7*heartScale},${y-4*heartScale} C${x+7*heartScale},${y} ${x},${y+6*heartScale} ${x},${y+6*heartScale} Z`}
+            {...baseProps}
+          >
+            <animate attributeName="fill-opacity" values="0.7;1;0.7" dur="1.5s" repeatCount="indefinite" />
+          </path>
+        );
+      default:
+        return (
+          <circle cx={x} cy={y} r={badgeRadius} {...baseProps}>
+            <animate attributeName="r" values={`${badgeRadius};${badgeRadius + 1};${badgeRadius}`} dur="1.5s" repeatCount="indefinite" />
+          </circle>
+        );
+    }
+  };
+  
+  return (
+    <svg 
+      width={svgWidth} 
+      height={height} 
+      viewBox={`0 0 ${svgWidth} ${height}`} 
+      fill="none" 
+      xmlns="http://www.w3.org/2000/svg"
+      {...htmlProps}
+      {...styleProps}
+      className={`logo dynamic-logo ${sizeClass} ${variantClass} ${styleProps.className || ''}`.trim()}
+      style={{ 
+        height: `${height}px`, 
+        cursor: htmlProps.onClick ? 'pointer' : 'default',
+        ...styleProps.style 
+      }}
+      role="img"
+      aria-label={ariaLabel}
+      {...svgProps}
+    >
+      <text ref={textRef} fontFamily={fontFamily} fontSize={fontSize} fontWeight={fontWeight}>
+        <tspan x="15" y={isNewLine ? height * 0.4 : height * 0.7} className={firstPartClass}>{firstPart}</tspan>
+        {secondPart && (
+          <tspan 
+            x={isNewLine ? "15" : undefined}
+            dy={isNewLine ? fontSize * 1.2 : undefined}
+            className={secondPartClass}
+          >
+            {isNewLine ? secondPart : (hasExplicitSpaces ? ` ${secondPart}` : secondPart)}
+          </tspan>
+        )}
+      </text>
+      {renderBadgeShape()}
+    </svg>
+  );
+};
+
+export default Logo;

package/src/components/Markdown.tsx

@@ -0,0 +1,191 @@
+/**
+ * Markdown Component - Transforms Markdown strings into Framework components
+ *
+ * Accepts Markdown string as children and converts it through a
+ * Markdown → HTML → React components pipeline using the Html component
+ * with Markdown-optimized transformation rules.
+ *
+ * Features:
+ * - Full Markdown syntax support via marked library
+ * - Transform rules optimized for Markdown content
+ * - Code block syntax highlighting
+ * - Preserves inline code elements (no transformation)
+ * - TypeScript support with proper props interface
+ * - Error handling and fallback to Html component
+ *
+ * Usage:
+ * - Basic: <Markdown>{markdownString}</Markdown>
+ * - Custom config: <Markdown htmlTransformConfig={customConfig}>{markdownString}</Markdown>
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { Box } from '@mui/material';
+import { marked } from 'marked';
+import React from 'react';
+import { QWICKAPP_COMPONENT, useBaseProps, WithBaseProps } from '../hooks';
+import Html from './Html';
+import SafeSpan from './SafeSpan';
+import { TransformConfig, defaultMarkdownRules } from '../utils/htmlTransform';
+
+export interface MarkdownProps extends WithBaseProps {
+  /** Markdown content as string */
+  children: string;
+  /** Custom transformation configuration for HTML conversion */
+  htmlTransformConfig?: TransformConfig;
+  /** Whether to sanitize HTML output (default: true) */
+  sanitize?: boolean;
+  /** Custom sanitization options */
+  sanitizeOptions?: any;
+  /** Fallback content when Markdown is empty */
+  placeholder?: string;
+  /** Container element type */
+  component?: React.ElementType;
+  /** Marked options for Markdown parsing */
+  markedOptions?: marked.MarkedOptions;
+}
+
+/**
+ * Configure marked with security and GitHub Flavored Markdown support
+ */
+const getMarkedOptions = (customOptions?: marked.MarkedOptions): marked.MarkedOptions => ({
+  // GitHub Flavored Markdown
+  gfm: true,
+  // Convert line breaks to <br> tags
+  breaks: false,
+  // Pedantic compliance to original markdown.pl
+  pedantic: false,
+  // Sanitize HTML (we handle this in Html component)
+  sanitize: false,
+  // Smart punctuation
+  smartypants: false,
+  // Custom renderer options
+  renderer: new marked.Renderer(),
+  // Override with user options
+  ...customOptions
+});
+
+/**
+ * Markdown component - converts Markdown to React components via Html
+ */
+export function Markdown({
+  children = '',
+  htmlTransformConfig,
+  sanitize = true,
+  sanitizeOptions,
+  placeholder,
+  component = 'div',
+  markedOptions,
+  ...restProps
+}: MarkdownProps) {
+  const { styleProps, htmlProps, restProps: otherProps } = useBaseProps(restProps);
+
+  // Mark as QwickApp component
+  (Markdown as any)[QWICKAPP_COMPONENT] = true;
+
+  // Return placeholder if no Markdown content
+  if (!children || !children.trim()) {
+    if (placeholder) {
+      return (
+        <Box
+          component={component}
+          {...htmlProps}
+          {...styleProps}
+          {...otherProps}
+          sx={{
+            opacity: 0.6,
+            fontStyle: 'italic',
+            ...styleProps.sx
+          }}
+        >
+          {placeholder}
+        </Box>
+      );
+    }
+    return null;
+  }
+
+  try {
+    // Configure marked
+    const options = getMarkedOptions(markedOptions);
+    
+    // Convert Markdown to HTML
+    const htmlContent = marked(children, options);
+
+    // Use provided transform config or default markdown rules
+    const transformConfig: TransformConfig = htmlTransformConfig || {
+      rules: defaultMarkdownRules,
+      sanitize,
+      sanitizeOptions
+    };
+
+    // Pass HTML to Html component for transformation
+    return (
+      <Html
+        transformConfig={transformConfig}
+        sanitize={sanitize}
+        sanitizeOptions={sanitizeOptions}
+        component={component}
+        {...htmlProps}
+        {...styleProps}
+        {...otherProps}
+      >
+        {htmlContent}
+      </Html>
+    );
+
+  } catch (error) {
+    console.error('Error processing Markdown content:', error);
+    
+    // Fallback handling
+    if (process.env.NODE_ENV !== 'production') {
+      return (
+        <Box
+          component={component}
+          {...htmlProps}
+          {...styleProps}
+          {...otherProps}
+          sx={{
+            p: 2,
+            border: '1px solid orange',
+            borderRadius: 1,
+            backgroundColor: 'rgba(255, 165, 0, 0.1)',
+            ...styleProps.sx
+          }}
+        >
+          <strong>Markdown Processing Error:</strong> {error instanceof Error ? error.message : 'Unknown error'}
+          <SafeSpan html={children} placeholder="Failed to process Markdown" />
+        </Box>
+      );
+    }
+
+    // Production fallback - try to use Html component with raw content
+    try {
+      return (
+        <Html
+          sanitize={sanitize}
+          sanitizeOptions={sanitizeOptions}
+          component={component}
+          {...htmlProps}
+          {...styleProps}
+          {...otherProps}
+        >
+          {children}
+        </Html>
+      );
+    } catch (htmlError) {
+      // Last resort fallback
+      return (
+        <SafeSpan 
+          html={children} 
+          placeholder={placeholder || "Content unavailable"} 
+          {...htmlProps}
+          {...styleProps}
+          {...otherProps}
+        />
+      );
+    }
+  }
+}
+
+export default Markdown;