@qwickapps/react-framework 1.3.4 → 1.4.0

package/src/contexts/PrintModeContext.tsx

@@ -0,0 +1,332 @@
+/**
+ * PrintModeContext - App-level print state management
+ * 
+ * Handles print mode state transitions at the application level,
+ * allowing pages to simply consume and react to print state changes.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { createContext, useContext, useCallback, useReducer, useEffect } from 'react';
+import { useQwickApp } from './QwickAppContext';
+import { useTheme } from './ThemeContext';
+import { usePalette } from './PaletteContext';
+import { PrintConfigSchema } from '../schemas/PrintConfigSchema';
+
+export type PrintModeStateType = 
+  | 'normal'
+  | 'applying_print_config'
+  | 'entering_print_mode'
+  | 'view_loading'
+  | 'config_applied'
+  | 'print_mode'
+  | 'exiting_print_mode'
+  | 'restoring_config';
+
+interface PrintModeState {
+  printModeState: PrintModeStateType;
+  printConfig: PrintConfigSchema;
+  originalTheme: string | null;
+  originalPalette: string | null;
+}
+
+type PrintModeAction = 
+  | { type: 'TRIGGER_PRINT'; config?: Partial<PrintConfigSchema> }
+  | { type: 'APPLY_CONFIG' }
+  | { type: 'ENTER_PRINT_MODE' }
+  | { type: 'VIEW_LOADING' }
+  | { type: 'VIEW_READY' }
+  | { type: 'CONFIG_APPLIED' }
+  | { type: 'EXIT_PRINT_MODE' }
+  | { type: 'RESTORE_CONFIG' }
+  | { type: 'RETURN_TO_NORMAL' }
+  | { type: 'SET_ORIGINAL_THEME'; theme: string }
+  | { type: 'SET_ORIGINAL_PALETTE'; palette: string };
+
+const DEFAULT_PRINT_CONFIG: PrintConfigSchema = {
+  theme: 'light',
+  palette: undefined,
+  hideScaffolding: true,
+  hideInteractiveElements: false,
+  optimizeForMonochrome: false,
+  showPrintDate: true,
+  pageMargins: '12mm',
+};
+
+function printModeReducer(state: PrintModeState, action: PrintModeAction): PrintModeState {
+  
+  switch (action.type) {
+    case 'TRIGGER_PRINT':
+      if (state.printModeState === 'normal') {
+        return {
+          ...state,
+          printModeState: 'applying_print_config',
+          printConfig: action.config ? { ...DEFAULT_PRINT_CONFIG, ...action.config } : DEFAULT_PRINT_CONFIG,
+        };
+      }
+      return state;
+
+    case 'APPLY_CONFIG':
+      if (state.printModeState === 'applying_print_config') {
+        return { ...state, printModeState: 'entering_print_mode' };
+      }
+      return state;
+
+    case 'VIEW_LOADING':
+      // Can transition to view_loading from entering_print_mode
+      // Ignore if already in view_loading or other states
+      if (state.printModeState === 'entering_print_mode') {
+        return { ...state, printModeState: 'view_loading' };
+      }
+      return state;
+
+    case 'VIEW_READY':
+      // Can transition to config_applied from view_loading, then wait for theme/palette changes
+      if (state.printModeState === 'view_loading') {
+        return { ...state, printModeState: 'config_applied' };
+      } else if (state.printModeState === 'exiting_print_mode') {
+        return { ...state, printModeState: 'restoring_config' };
+      }
+      return state;
+
+    case 'CONFIG_APPLIED':
+      if (state.printModeState === 'config_applied') {
+        return { ...state, printModeState: 'print_mode' };
+      }
+      return state;
+
+    case 'EXIT_PRINT_MODE':
+      // Exit from any print-related state
+      if (state.printModeState !== 'normal' && state.printModeState !== 'exiting_print_mode' && state.printModeState !== 'restoring_config') {
+        return { ...state, printModeState: 'exiting_print_mode' };
+      }
+      return state;
+
+    case 'RESTORE_CONFIG':
+      if (state.printModeState === 'restoring_config') {
+        return { ...state, printModeState: 'normal' };
+      }
+      return state;
+
+    case 'SET_ORIGINAL_THEME':
+      return { ...state, originalTheme: action.theme };
+
+    case 'SET_ORIGINAL_PALETTE':
+      return { ...state, originalPalette: action.palette };
+
+    default:
+      return state;
+  }
+}
+
+interface PrintModeContextValue {
+  // State
+  printModeState: PrintModeStateType;
+  isPrintMode: boolean;
+  printConfig: PrintConfigSchema;
+  
+  // Actions
+  triggerPrint: (config?: Partial<PrintConfigSchema>) => void;
+  exitPrintMode: () => void;
+  onViewLoading: () => void;
+  onViewReady: () => void;
+}
+
+const PrintModeContext = createContext<PrintModeContextValue | null>(null);
+
+export const usePrintMode = (): PrintModeContextValue => {
+  const context = useContext(PrintModeContext);
+  if (!context) {
+    throw new Error('usePrintMode must be used within a PrintModeProvider');
+  }
+  return context;
+};
+
+interface PrintModeProviderProps {
+  children: React.ReactNode;
+}
+
+export const PrintModeProvider: React.FC<PrintModeProviderProps> = ({ children }) => {
+  const [state, dispatch] = useReducer(printModeReducer, {
+    printModeState: 'normal',
+    printConfig: DEFAULT_PRINT_CONFIG,
+    originalTheme: null,
+    originalPalette: null,
+  });
+
+  const { updateConfig: updateQwickAppConfig } = useQwickApp();
+  const { setCurrentTheme, getCurrentTheme } = useTheme();
+  const { setCurrentPalette, getCurrentPalette } = usePalette();
+
+  // Computed derived state - only true when actually in print view
+  const isPrintMode = state.printModeState === 'entering_print_mode' || 
+                     state.printModeState === 'view_loading' ||
+                     state.printModeState === 'config_applied' ||
+                     state.printModeState === 'print_mode';
+
+  // Actions
+  const triggerPrint = useCallback((config?: Partial<PrintConfigSchema>) => {
+    dispatch({ type: 'TRIGGER_PRINT', config });
+  }, []);
+
+  const exitPrintMode = useCallback(() => {
+    dispatch({ type: 'EXIT_PRINT_MODE' });
+  }, []);
+
+  const onViewLoading = useCallback(() => {
+    dispatch({ type: 'VIEW_LOADING' });
+  }, []);
+
+  const onViewReady = useCallback(() => {
+    dispatch({ type: 'VIEW_READY' });
+  }, []);
+
+  // Effect to handle configuration application
+  useEffect(() => {
+    if (state.printModeState === 'applying_print_config') {
+      // Apply print configuration
+      if (state.printConfig.hideScaffolding) {
+        updateQwickAppConfig({ enableScaffolding: false });
+      }
+      
+      if (state.printConfig.theme) {
+        dispatch({ type: 'SET_ORIGINAL_THEME', theme: getCurrentTheme() });
+        setCurrentTheme(state.printConfig.theme as any);
+      }
+      
+      if (state.printConfig.palette) {
+        dispatch({ type: 'SET_ORIGINAL_PALETTE', palette: getCurrentPalette() });
+        setCurrentPalette(state.printConfig.palette);
+      }
+
+      if (typeof document !== 'undefined') {
+        document.body.classList.add('print-mode');
+        
+        if (state.printConfig.optimizeForMonochrome) {
+          document.body.classList.add('print-monochrome');
+        }
+        
+        if (state.printConfig.hideInteractiveElements) {
+          document.body.classList.add('print-hide-interactive');
+        }
+
+        // Apply custom page margins if specified
+        if (state.printConfig.pageMargins && state.printConfig.pageMargins !== '12mm') {
+          let printStyleElement = document.querySelector('#qwick-print-margins');
+          if (!printStyleElement) {
+            printStyleElement = document.createElement('style');
+            printStyleElement.id = 'qwick-print-margins';
+            document.head.appendChild(printStyleElement);
+          }
+          printStyleElement.textContent = `
+            @media print {
+              @page {
+                margin: ${state.printConfig.pageMargins};
+              }
+            }
+          `;
+        }
+      }
+
+      // Transition to entering print mode
+      dispatch({ type: 'APPLY_CONFIG' });
+    }
+  }, [state.printModeState, state.printConfig, updateQwickAppConfig, getCurrentTheme, getCurrentPalette, setCurrentTheme, setCurrentPalette]);
+
+  // Effect to detect when theme/palette changes are complete
+  useEffect(() => {
+    if (state.printModeState === 'config_applied') {
+      // Wait one render cycle to ensure theme/palette changes are applied
+      const rafId = requestAnimationFrame(() => {
+        dispatch({ type: 'CONFIG_APPLIED' });
+      });
+      
+      return () => cancelAnimationFrame(rafId);
+    }
+  }, [state.printModeState]);
+
+  // Effect to transition from exiting_print_mode to restoring_config
+  useEffect(() => {
+    if (state.printModeState === 'exiting_print_mode') {
+      // Use VIEW_READY action to transition to restoring_config
+      dispatch({ type: 'VIEW_READY' });
+    }
+  }, [state.printModeState]);
+
+  // Effect to handle configuration restoration  
+  useEffect(() => {
+    if (state.printModeState === 'restoring_config') {
+      // Restore QwickApp configuration
+      updateQwickAppConfig({ enableScaffolding: true });
+      
+      // Restore original theme and palette
+      if (state.originalTheme) {
+        setCurrentTheme(state.originalTheme as any);
+      }
+      
+      if (state.originalPalette) {
+        setCurrentPalette(state.originalPalette);
+      }
+
+      // Remove print mode classes and custom styles
+      if (typeof document !== 'undefined') {
+        document.body.classList.remove('print-mode', 'print-monochrome', 'print-hide-interactive');
+        
+        // Remove custom margins style
+        const printStyleElement = document.querySelector('#qwick-print-margins');
+        if (printStyleElement) {
+          printStyleElement.remove();
+        }
+      }
+
+      // Return to normal
+      dispatch({ type: 'RESTORE_CONFIG' });
+    }
+  }, [state.printModeState, state.originalTheme, state.originalPalette, updateQwickAppConfig, setCurrentTheme, setCurrentPalette]);
+
+  // Effect to handle print dialog
+  useEffect(() => {
+    if (state.printModeState === 'print_mode') {
+      if (typeof window !== 'undefined') {
+        window.print();
+      }
+    }
+  }, [state.printModeState]);
+
+  // Effect to handle browser print events (stable handlers using refs)
+  useEffect(() => {
+    const handleBeforePrint = () => {
+      triggerPrint();
+    };
+
+    const handleAfterPrint = () => {
+      exitPrintMode();
+    };
+
+    if (typeof window !== 'undefined') {
+      window.addEventListener('beforeprint', handleBeforePrint);
+      window.addEventListener('afterprint', handleAfterPrint);
+
+      return () => {
+        window.removeEventListener('beforeprint', handleBeforePrint);
+        window.removeEventListener('afterprint', handleAfterPrint);
+      };
+    }
+  }, []); // Empty dependency array for stable event handlers
+
+  const contextValue: PrintModeContextValue = {
+    printModeState: state.printModeState,
+    isPrintMode,
+    printConfig: state.printConfig,
+    triggerPrint,
+    exitPrintMode,
+    onViewLoading,
+    onViewReady,
+  };
+
+  return (
+    <PrintModeContext.Provider value={contextValue}>
+      {children}
+    </PrintModeContext.Provider>
+  );
+};

package/src/contexts/QwickAppContext.tsx

@@ -12,8 +12,8 @@ import type { MenuItem } from '../components/menu';
 import type { ScaffoldProps } from '../components/Scaffold';
 
 export interface QwickAppProps {
-  /** Application name displayed in header/title */
-  appName: string;
+  /** Application name displayed in header/title (optional when config is provided) */
+  appName?: string;
   /** Custom logo component - overrides the default logo */
   logo?: React.ReactNode;
   /** App identifier used for storage keys */

package/src/contexts/ThemeContext.tsx

@@ -302,8 +302,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
           },
         },
       },
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+  });
   }, [actualThemeMode, paletteChangeCounter]); // paletteChangeCounter is needed to force theme rebuild // Re-create theme when palette changes
 
   // Theme preference management methods

package/src/contexts/index.ts

@@ -7,3 +7,5 @@ export { PaletteProvider, usePalette } from './PaletteContext';
 export type { PaletteConfig, PaletteContextValue } from './PaletteContext';
 export { ThemeProvider, useTheme } from './ThemeContext';
 export type { ActualThemeMode, ThemeContextValue, ThemeMode } from './ThemeContext';
+export { PrintModeProvider, usePrintMode } from './PrintModeContext';
+export type { PrintModeStateType } from './PrintModeContext';

package/src/hooks/index.ts

@@ -8,4 +8,8 @@ export type { BaseComponentProps, WithBaseProps } from './useBaseProps';
 
 // Data Binding hooks for AI-driven component system
 export { useDataBinding } from './useDataBinding';
-export { QWICKAPP_COMPONENT } from './useBaseProps';
+export { QWICKAPP_COMPONENT } from './useBaseProps';
+
+// Print mode detection and management (legacy hook - use PrintModeProvider instead)
+export { usePrintMode as usePrintModeHook } from './usePrintMode';
+export type { PrintModeState } from './usePrintMode';

package/src/hooks/usePrintMode.ts

@@ -0,0 +1,73 @@
+/**
+ * usePrintMode hook - Simple wrapper around PrintModeContext
+ * 
+ * @deprecated Use usePrintMode from PrintModeContext directly
+ * This file maintained for backward compatibility during migration
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { usePrintMode as usePrintModeContext } from '../contexts/PrintModeContext';
+import { PrintConfigSchema } from '../schemas/PrintConfigSchema';
+
+export type PrintModeStateType = 
+  | 'normal'
+  | 'applying_print_config'
+  | 'entering_print_mode'
+  | 'view_loading'
+  | 'config_applied'
+  | 'print_mode'
+  | 'exiting_print_mode'
+  | 'restoring_config';
+
+export interface PrintModeState {
+  /** Whether the app is currently in print mode */
+  isPrintMode: boolean;
+  /** Print configuration to apply */
+  printConfig: PrintConfigSchema;
+  /** Current state of the print mode state machine */
+  printModeState: PrintModeStateType;
+  /** Manually enter print mode */
+  enterPrintMode: (config?: Partial<PrintConfigSchema>) => void;
+  /** Exit print mode */
+  exitPrintMode: () => void;
+  /** Toggle print mode */
+  togglePrintMode: (config?: Partial<PrintConfigSchema>) => void;
+  /** Enter print mode and trigger print dialog */
+  triggerPrint: (config?: Partial<PrintConfigSchema>) => void;
+  /** Callback to signal current view is loading */
+  onViewLoading: () => void;
+  /** Callback to signal current view is ready */
+  onViewReady: () => void;
+}
+
+/**
+ * Hook to access print mode state from app-level context
+ * 
+ * @param initialConfig - Initial print configuration (ignored, use context provider config)
+ * @returns Print mode state and controls
+ */
+export function usePrintMode(initialConfig?: Partial<PrintConfigSchema>): PrintModeState {
+  const context = usePrintModeContext();
+  
+  // Map context interface to legacy interface
+  return {
+    isPrintMode: context.isPrintMode,
+    printConfig: context.printConfig,
+    printModeState: context.printModeState,
+    enterPrintMode: context.triggerPrint,
+    exitPrintMode: context.exitPrintMode,
+    togglePrintMode: (config?: Partial<PrintConfigSchema>) => {
+      if (context.isPrintMode) {
+        context.exitPrintMode();
+      } else {
+        context.triggerPrint(config);
+      }
+    },
+    triggerPrint: context.triggerPrint,
+    onViewLoading: context.onViewLoading,
+    onViewReady: context.onViewReady,
+  };
+}
+
+export default usePrintMode;

package/src/index.ts

@@ -19,5 +19,8 @@ export * from './utils';
 // Types (includes ContentTypes)
 export * from './types';
 
+// Configuration
+export * from './config';
+
 // Schemas (includes component schemas and builders)
 export * from './schemas';

package/src/schemas/CodeSchema.ts

@@ -4,6 +4,7 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
+import type { ReactNode } from 'react';
 import { IsBoolean, IsOptional, IsString } from 'class-validator';
 import 'reflect-metadata';
 import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
@@ -17,8 +18,8 @@ export class CodeModel extends Model {
     description: 'The code content to display with syntax highlighting',
     placeholder: 'Enter code content...'
   })
-  @IsString()
-  children?: string;
+  @IsString() // Schema validation: must be string for serialization
+  children?: ReactNode; // Runtime type: supports natural React usage
 
   @Field()
   @Editor({
@@ -84,5 +85,4 @@ export class CodeModel extends Model {
   codeBackground?: string;
 }
 
-
 export default CodeModel;

package/src/schemas/CollapsibleLayoutSchema.ts

@@ -15,6 +15,7 @@ import {
   FieldType 
 } from '@qwickapps/schema';
 import { IsOptional, IsString, IsBoolean, IsIn } from 'class-validator';
+import { ReactNode } from 'react';
 
 @Schema('CollapsibleLayout', '1.0.0')
 export class CollapsibleLayoutModel extends Model {
@@ -115,7 +116,7 @@ export class CollapsibleLayoutModel extends Model {
   })
   @IsOptional()
   @IsString()
-  children?: string;
+  children?: ReactNode | string;
 
   @Field()
   @Editor({

package/src/schemas/ContentSchema.ts

@@ -9,6 +9,7 @@ import { Type } from 'class-transformer';
 import 'reflect-metadata';
 import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
 import { ActionModel } from './ActionSchema';
+import { ReactNode } from 'react';
 
 @Schema('Content', '1.0.0')
 export class ContentModel extends Model {
@@ -43,7 +44,7 @@ export class ContentModel extends Model {
   })
   @IsOptional()
   @IsString()
-  children?: string;
+  children?: ReactNode | string;
 
   @Field()
   @Editor({

package/src/schemas/GridCellSchema.ts

@@ -0,0 +1,164 @@
+/**
+ * Schema for GridCell component - Grid layout cell wrapper
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { ReactNode } from 'react';
+import { IsOptional, IsString, IsNumber, IsIn } from 'class-validator';
+import 'reflect-metadata';
+import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+
+@Schema('GridCell', '1.0.0')
+export class GridCellModel extends Model {
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXTAREA,
+    label: 'Children',
+    description: 'Content to display inside the grid cell',
+    placeholder: 'Nested components will be serialized automatically'
+  })
+  children?: ReactNode; // Runtime type: supports natural React usage
+
+  // Grid responsive properties
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'Span',
+    description: 'Number of columns to span (1-12)',
+    placeholder: '12'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  span?: number;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'XS (Mobile)',
+    description: 'Columns on extra small screens (1-12)',
+    placeholder: '12'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  xs?: number;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'SM (Tablet)',
+    description: 'Columns on small screens (1-12)',
+    placeholder: '6'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  sm?: number;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'MD (Desktop)',
+    description: 'Columns on medium screens (1-12)',
+    placeholder: '4'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  md?: number;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'LG (Large Desktop)',
+    description: 'Columns on large screens (1-12)',
+    placeholder: '3'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  lg?: number;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'XL (Extra Large)',
+    description: 'Columns on extra large screens (1-12)',
+    placeholder: '2'
+  })
+  @IsOptional()
+  @IsNumber()
+  @IsIn([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])
+  xl?: number;
+
+  // Styling properties from WithBaseProps
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Background',
+    description: 'Background color or theme color (e.g., "primary.main", "#ffffff")',
+    placeholder: 'transparent'
+  })
+  @IsOptional()
+  @IsString()
+  background?: string;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Padding',
+    description: 'Internal spacing (e.g., "medium", "16px", "1rem")',
+    placeholder: 'medium'
+  })
+  @IsOptional()
+  @IsString()
+  padding?: string;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Margin',
+    description: 'External spacing (e.g., "small", "8px", "0.5rem")',
+    placeholder: '0'
+  })
+  @IsOptional()
+  @IsString()
+  margin?: string;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Height',
+    description: 'Cell height (e.g., "200px", "medium")',
+    placeholder: 'auto'
+  })
+  @IsOptional()
+  @IsString()
+  height?: string;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Width',
+    description: 'Cell width (e.g., "100%", "300px")',
+    placeholder: '100%'
+  })
+  @IsOptional()
+  @IsString()
+  width?: string;
+
+  @Field()
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'CSS Class',
+    description: 'Additional CSS class names',
+    placeholder: 'custom-cell-class'
+  })
+  @IsOptional()
+  @IsString()
+  className?: string;
+}
+
+export default GridCellModel;