@rakeyshgidwani/roger-ui-bank-theme-harvey 0.2.52 → 0.3.1

package/src/themes/validation.ts

@@ -29,6 +29,32 @@ export class ThemeValidator {
     'meta.version'
   ];
 
+  // Phase 1 Enhancement: Required fields for new foundation primitives
+  private static readonly PHASE1_REQUIRED_FIELDS = [
+    // Enhanced Breakpoint System
+    'breakpoints.xs',
+    'breakpoints.sm',
+    'breakpoints.md',
+    'breakpoints.lg',
+    'breakpoints.xl',
+    'breakpoints.2xl',
+    'breakpoints.3xl',
+
+    // Content Density System
+    'contentDensity.compact.spacing.section',
+    'contentDensity.compact.typography.scale',
+    'contentDensity.comfortable.spacing.section',
+    'contentDensity.comfortable.typography.scale',
+    'contentDensity.spacious.spacing.section',
+    'contentDensity.spacious.typography.scale',
+
+    // Responsive Typography System
+    'responsiveTypography.heading1.xs',
+    'responsiveTypography.heading1.3xl',
+    'responsiveTypography.body.xs',
+    'responsiveTypography.body.3xl'
+  ];
+
   private static readonly COLOR_FORMATS = {
     hex: /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/,
     rgb: /^rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)$/,
@@ -49,6 +75,12 @@ export class ThemeValidator {
     // Validate required fields
     this.validateRequiredFields(theme, errors);
 
+    // Phase 1 Enhancement: Validate new foundation primitives
+    this.validatePhase1RequiredFields(theme, errors);
+    this.validateBreakpointSystem(theme, errors, warnings);
+    this.validateContentDensitySystem(theme, errors, warnings);
+    this.validateResponsiveTypographySystem(theme, errors, warnings);
+
     // Validate color formats
     this.validateColorFormats(theme, errors, warnings);
 
@@ -459,4 +491,221 @@ export class ThemeValidator {
       return false;
     }
   }
+
+  // Phase 1 Enhancement: New validation methods for foundation primitives
+
+  /**
+   * Validate Phase 1 required fields
+   */
+  private static validatePhase1RequiredFields(
+    theme: MultiThemeConfig,
+    errors: ThemeValidationError[]
+  ): void {
+    this.PHASE1_REQUIRED_FIELDS.forEach(fieldPath => {
+      const value = this.getNestedValue(theme, fieldPath);
+      if (value === undefined || value === null || value === '') {
+        errors.push({
+          path: fieldPath,
+          message: `Required Phase 1 field '${fieldPath}' is missing`,
+          severity: 'critical'
+        });
+      }
+    });
+  }
+
+  /**
+   * Validate enhanced breakpoint system
+   */
+  private static validateBreakpointSystem(
+    theme: MultiThemeConfig,
+    errors: ThemeValidationError[],
+    warnings: ThemeValidationWarning[]
+  ): void {
+    if (!theme.breakpoints) {
+      errors.push({
+        path: 'breakpoints',
+        message: 'Breakpoint system is required for Phase 1 compliance',
+        severity: 'critical'
+      });
+      return;
+    }
+
+    const requiredBreakpoints = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'];
+    const expectedValues = {
+      xs: '475px',
+      sm: '640px',
+      md: '768px',
+      lg: '1024px',
+      xl: '1280px',
+      '2xl': '1536px',
+      '3xl': '1920px'
+    };
+
+    requiredBreakpoints.forEach(breakpoint => {
+      const value = theme.breakpoints![breakpoint as keyof typeof theme.breakpoints];
+      if (!value) {
+        errors.push({
+          path: `breakpoints.${breakpoint}`,
+          message: `Breakpoint '${breakpoint}' is required`,
+          severity: 'error'
+        });
+      } else {
+        // Validate format (should end with 'px')
+        if (!value.endsWith('px')) {
+          warnings.push({
+            path: `breakpoints.${breakpoint}`,
+            message: `Breakpoint '${breakpoint}' should use px units`,
+            severity: 'warning'
+          });
+        }
+
+        // Validate expected values for consistency
+        if (value !== expectedValues[breakpoint as keyof typeof expectedValues]) {
+          warnings.push({
+            path: `breakpoints.${breakpoint}`,
+            message: `Breakpoint '${breakpoint}' value '${value}' differs from specification '${expectedValues[breakpoint as keyof typeof expectedValues]}'`,
+            severity: 'info'
+          });
+        }
+      }
+    });
+  }
+
+  /**
+   * Validate content density system
+   */
+  private static validateContentDensitySystem(
+    theme: MultiThemeConfig,
+    errors: ThemeValidationError[],
+    warnings: ThemeValidationWarning[]
+  ): void {
+    if (!theme.contentDensity) {
+      errors.push({
+        path: 'contentDensity',
+        message: 'Content density system is required for Phase 1 compliance',
+        severity: 'critical'
+      });
+      return;
+    }
+
+    const densityLevels = ['compact', 'comfortable', 'spacious'];
+
+    densityLevels.forEach(level => {
+      const density = theme.contentDensity![level as keyof typeof theme.contentDensity];
+      if (!density) {
+        errors.push({
+          path: `contentDensity.${level}`,
+          message: `Density level '${level}' is required`,
+          severity: 'error'
+        });
+        return;
+      }
+
+      // Validate spacing structure
+      if (!density.spacing) {
+        errors.push({
+          path: `contentDensity.${level}.spacing`,
+          message: `Spacing configuration is required for density level '${level}'`,
+          severity: 'error'
+        });
+      } else {
+        ['section', 'component', 'element'].forEach(spacingType => {
+          const spacingValue = density.spacing[spacingType as keyof typeof density.spacing];
+          if (!spacingValue) {
+            warnings.push({
+              path: `contentDensity.${level}.spacing.${spacingType}`,
+              message: `Spacing type '${spacingType}' is recommended for density level '${level}'`,
+              severity: 'warning'
+            });
+          }
+        });
+      }
+
+      // Validate typography structure
+      if (!density.typography) {
+        errors.push({
+          path: `contentDensity.${level}.typography`,
+          message: `Typography configuration is required for density level '${level}'`,
+          severity: 'error'
+        });
+      } else {
+        if (typeof density.typography.scale !== 'number') {
+          errors.push({
+            path: `contentDensity.${level}.typography.scale`,
+            message: `Typography scale must be a number for density level '${level}'`,
+            severity: 'error'
+          });
+        }
+        if (typeof density.typography.lineHeight !== 'number') {
+          errors.push({
+            path: `contentDensity.${level}.typography.lineHeight`,
+            message: `Typography lineHeight must be a number for density level '${level}'`,
+            severity: 'error'
+          });
+        }
+      }
+
+      // Validate touch targets for mobile-focused densities
+      if (level === 'compact' && !density.touchTargets) {
+        warnings.push({
+          path: `contentDensity.${level}.touchTargets`,
+          message: `Touch targets configuration is recommended for compact density level`,
+          severity: 'warning'
+        });
+      }
+    });
+  }
+
+  /**
+   * Validate responsive typography system
+   */
+  private static validateResponsiveTypographySystem(
+    theme: MultiThemeConfig,
+    errors: ThemeValidationError[],
+    warnings: ThemeValidationWarning[]
+  ): void {
+    if (!theme.responsiveTypography) {
+      errors.push({
+        path: 'responsiveTypography',
+        message: 'Responsive typography system is required for Phase 1 compliance',
+        severity: 'critical'
+      });
+      return;
+    }
+
+    const typographyLevels = ['heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', 'body', 'bodyLarge', 'bodySmall', 'caption'];
+    const breakpoints = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'];
+
+    typographyLevels.forEach(level => {
+      const typography = theme.responsiveTypography![level as keyof typeof theme.responsiveTypography];
+      if (!typography) {
+        warnings.push({
+          path: `responsiveTypography.${level}`,
+          message: `Typography level '${level}' is recommended for complete responsive scaling`,
+          severity: 'warning'
+        });
+        return;
+      }
+
+      breakpoints.forEach(breakpoint => {
+        const value = typography[breakpoint as keyof typeof typography];
+        if (!value) {
+          warnings.push({
+            path: `responsiveTypography.${level}.${breakpoint}`,
+            message: `Breakpoint '${breakpoint}' is missing for typography level '${level}'`,
+            severity: 'warning'
+          });
+        } else {
+          // Validate format (should end with 'px' or be a number)
+          if (typeof value === 'string' && !value.endsWith('px') && !value.endsWith('rem') && !value.endsWith('em')) {
+            warnings.push({
+              path: `responsiveTypography.${level}.${breakpoint}`,
+              message: `Typography value should include units (px, rem, or em) for '${level}.${breakpoint}'`,
+              severity: 'warning'
+            });
+          }
+        }
+      });
+    });
+  }
 }

package/src/types.ts

@@ -22,7 +22,12 @@ export interface MultiThemeConfig {
   shimmer: ShimmerThemeConfig;
   meta: ThemeMetadata;
   extends?: string; // Optional property for theme inheritance
-  
+
+  // Phase 1 Enhancements: Breakpoint and Content Density Systems
+  breakpoints?: BreakpointThemeConfig;
+  contentDensity?: ContentDensityThemeConfig;
+  responsiveTypography?: ResponsiveTypographyThemeConfig;
+
   // NEW: Add light/dark mode configuration (colors only)
   modes?: {
     light?: {
@@ -462,3 +467,74 @@ export interface CompleteThemeConfig extends MultiThemeConfig {
   inheritance?: ThemeInheritance;
   validation: ThemeValidationResult;
 }
+
+// Phase 1 Enhancement: Enhanced Breakpoint System
+export interface BreakpointThemeConfig {
+  xs: string;   // 475px - Large phones (iPhone 14 Plus, etc.)
+  sm: string;   // 640px - Small tablets, large phones landscape
+  md: string;   // 768px - Tablets (iPad Mini, etc.)
+  lg: string;   // 1024px - Desktop, large tablets
+  xl: string;   // 1280px - Large desktop (MacBook Pro 13")
+  '2xl': string; // 1536px - Ultra-wide (MacBook Pro 16", external monitors)
+  '3xl': string; // 1920px - Large external monitors, TV displays
+}
+
+// Phase 1 Enhancement: Content Density System
+export interface ContentDensityThemeConfig {
+  compact: DensityLevel;     // xs to md breakpoints
+  comfortable: DensityLevel; // md to lg breakpoints
+  spacious: DensityLevel;    // lg+ breakpoints
+}
+
+export interface DensityLevel {
+  spacing: DensitySpacing;
+  typography: DensityTypography;
+  touchTargets?: DensityTouchTargets;
+  interactions?: DensityInteractions;
+}
+
+export interface DensitySpacing {
+  section: string;   // Section-level spacing
+  component: string; // Component-level spacing
+  element: string;   // Element-level spacing
+}
+
+export interface DensityTypography {
+  scale: number;     // Typography scale multiplier
+  lineHeight: number; // Line height ratio
+}
+
+export interface DensityTouchTargets {
+  minimum: string;   // Minimum touch target size
+  preferred: string; // Preferred touch target size
+}
+
+export interface DensityInteractions {
+  hover?: boolean;     // Enable hover states
+  tooltips?: boolean;  // Enable tooltips
+  shortcuts?: boolean; // Enable keyboard shortcuts
+}
+
+// Phase 1 Enhancement: Responsive Typography System
+export interface ResponsiveTypographyThemeConfig {
+  heading1: ResponsiveTypographyScale;
+  heading2: ResponsiveTypographyScale;
+  heading3: ResponsiveTypographyScale;
+  heading4: ResponsiveTypographyScale;
+  heading5: ResponsiveTypographyScale;
+  heading6: ResponsiveTypographyScale;
+  body: ResponsiveTypographyScale;
+  bodyLarge: ResponsiveTypographyScale;
+  bodySmall: ResponsiveTypographyScale;
+  caption: ResponsiveTypographyScale;
+}
+
+export interface ResponsiveTypographyScale {
+  xs: string;   // Large phone
+  sm: string;   // Small tablet
+  md: string;   // Tablet
+  lg: string;   // Desktop
+  xl: string;   // Large desktop
+  '2xl': string; // Ultra-wide
+  '3xl': string; // Large displays
+}

package/src/utils/progressive-css-injector.ts

@@ -0,0 +1,254 @@
+/**
+ * Progressive CSS Injector
+ * Runtime utility to load progressive CSS for desktop enhancement
+ *
+ * This is a simplified, production-ready approach that:
+ * 1. Detects desktop viewport (>= 1024px)
+ * 2. Dynamically loads progressive.css
+ * 3. Handles viewport changes and preloading
+ */
+
+interface ProgressiveLoaderConfig {
+  desktopBreakpoint: number
+  progressiveCSSPath: string
+  enablePreload: boolean
+  enableViewportDetection: boolean
+}
+
+const DEFAULT_CONFIG: ProgressiveLoaderConfig = {
+  desktopBreakpoint: 1024, // lg breakpoint
+  progressiveCSSPath: '/progressive.css',
+  enablePreload: true,
+  enableViewportDetection: true
+}
+
+class ProgressiveCSSInjector {
+  private config: ProgressiveLoaderConfig
+  private isLoaded = false
+  private linkElement: HTMLLinkElement | null = null
+  private preloadElement: HTMLLinkElement | null = null
+
+  constructor(config: Partial<ProgressiveLoaderConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  /**
+   * Initialize the progressive CSS loader
+   */
+  init(): void {
+    if (typeof window === 'undefined') return // SSR safety
+
+    // Only run in production or when explicitly enabled
+    // In development, progressive.css likely doesn't exist
+    const isProduction = typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD === true
+    const isDevelopment = typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV === true
+
+    if (isDevelopment && !this.config.enableViewportDetection) {
+      console.log('Progressive CSS: Skipping in development (set enableViewportDetection: true to override)')
+      return
+    }
+
+    // In production, check if progressive CSS file exists
+    if (isProduction) {
+      this.checkFileExists()
+        .then(exists => {
+          if (!exists) {
+            console.log('Progressive CSS file not found, skipping enhancement')
+            return
+          }
+          this.initializeFeatures()
+        })
+        .catch(error => {
+          console.warn('Progressive CSS loader initialization failed:', error)
+        })
+    } else {
+      // In development with explicit enablement, skip file check
+      this.initializeFeatures()
+    }
+  }
+
+  /**
+   * Initialize progressive CSS features
+   */
+  private initializeFeatures(): void {
+    // Initial viewport check
+    this.checkAndLoadProgressiveCSS()
+
+    // Setup viewport change listener if enabled
+    if (this.config.enableViewportDetection) {
+      this.setupViewportListener()
+    }
+
+    // Setup preloading if enabled
+    if (this.config.enablePreload) {
+      this.setupPreloading()
+    }
+  }
+
+  /**
+   * Check if the progressive CSS file exists
+   */
+  private async checkFileExists(): Promise<boolean> {
+    try {
+      const response = await fetch(this.config.progressiveCSSPath, { method: 'HEAD' })
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Check viewport and load progressive CSS if needed
+   */
+  private checkAndLoadProgressiveCSS(): void {
+    const isDesktop = window.innerWidth >= this.config.desktopBreakpoint
+
+    if (isDesktop && !this.isLoaded) {
+      this.loadProgressiveCSS()
+    } else if (!isDesktop && this.isLoaded) {
+      this.unloadProgressiveCSS()
+    }
+  }
+
+  /**
+   * Load progressive CSS
+   */
+  private loadProgressiveCSS(): void {
+    if (this.isLoaded || this.linkElement) return
+
+    this.linkElement = document.createElement('link')
+    this.linkElement.rel = 'stylesheet'
+    this.linkElement.href = this.config.progressiveCSSPath
+    this.linkElement.media = `screen and (min-width: ${this.config.desktopBreakpoint}px)`
+
+    this.linkElement.onload = () => {
+      this.isLoaded = true
+      console.log(`Progressive CSS loaded for viewport >= ${this.config.desktopBreakpoint}px`)
+    }
+
+    this.linkElement.onerror = () => {
+      console.warn('Failed to load progressive CSS')
+      this.cleanup()
+    }
+
+    document.head.appendChild(this.linkElement)
+  }
+
+  /**
+   * Unload progressive CSS (for mobile/tablet)
+   */
+  private unloadProgressiveCSS(): void {
+    if (this.linkElement) {
+      document.head.removeChild(this.linkElement)
+      this.linkElement = null
+      this.isLoaded = false
+      console.log('Progressive CSS unloaded for mobile/tablet viewport')
+    }
+  }
+
+  /**
+   * Setup viewport change listener
+   */
+  private setupViewportListener(): void {
+    let resizeTimeout: number
+
+    const handleResize = () => {
+      clearTimeout(resizeTimeout)
+      resizeTimeout = window.setTimeout(() => {
+        this.checkAndLoadProgressiveCSS()
+      }, 150) // Debounce resize events
+    }
+
+    window.addEventListener('resize', handleResize)
+  }
+
+  /**
+   * Setup preloading for fast desktop switches
+   */
+  private setupPreloading(): void {
+    // Only preload on tablet+ to avoid mobile data usage
+    if (window.innerWidth >= 768) {
+      this.preloadElement = document.createElement('link')
+      this.preloadElement.rel = 'preload'
+      this.preloadElement.href = this.config.progressiveCSSPath
+      this.preloadElement.as = 'style'
+
+      document.head.appendChild(this.preloadElement)
+      console.log('Progressive CSS preloaded for fast desktop enhancement')
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  private cleanup(): void {
+    if (this.linkElement) {
+      this.linkElement = null
+    }
+    if (this.preloadElement) {
+      document.head.removeChild(this.preloadElement)
+      this.preloadElement = null
+    }
+    this.isLoaded = false
+  }
+
+  /**
+   * Force load progressive CSS (for testing/debugging)
+   */
+  forceLoad(): void {
+    this.loadProgressiveCSS()
+  }
+
+  /**
+   * Force unload progressive CSS (for testing/debugging)
+   */
+  forceUnload(): void {
+    this.unloadProgressiveCSS()
+  }
+
+  /**
+   * Get current load status
+   */
+  getStatus() {
+    return {
+      isLoaded: this.isLoaded,
+      hasLinkElement: !!this.linkElement,
+      hasPreloadElement: !!this.preloadElement,
+      currentViewport: window.innerWidth,
+      isDesktopViewport: window.innerWidth >= this.config.desktopBreakpoint
+    }
+  }
+}
+
+// Export singleton instance for easy use
+export const progressiveLoader = new ProgressiveCSSInjector()
+
+// Export class for custom instances
+export { ProgressiveCSSInjector }
+
+// Export initialization function for manual control
+export function initializeProgressiveCSS(config?: Partial<ProgressiveLoaderConfig>): void {
+  // Only initialize in browser environment
+  if (typeof window === 'undefined') {
+    console.log('Progressive CSS: Skipping initialization (non-browser environment)')
+    return
+  }
+
+  // Respect production gating by default
+  const isProduction = typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD === true
+  const isDevelopment = typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV === true
+
+  if (isDevelopment && !config?.enableViewportDetection) {
+    console.log('Progressive CSS: Skipping in development (pass enableViewportDetection: true to override)')
+    return
+  }
+
+  void isProduction // Use the variable to avoid unused warning
+
+  if (config) {
+    const customLoader = new ProgressiveCSSInjector(config)
+    customLoader.init()
+  } else {
+    progressiveLoader.init()
+  }
+}