@qwickapps/react-framework 1.4.0 → 1.4.2

package/README.md

@@ -4,15 +4,48 @@ A complete React framework for building modern, responsive applications with int
 
 ## What's New
 
-### January 5, 2025 - Component Serialization System ("WebView for React")
+### September 29, 2025 - Production Ready Release (v1.4.2)
+
+- **NPM Publishing Ready**: Package prepared for official NPM distribution with optimized build configuration and comprehensive exports
+- **Enhanced Build System**: Improved rollup configuration with both development and production builds, automatic CSS bundling, and TypeScript declarations
+- **Complete API Exports**: All framework components, utilities, and configuration modules properly exported for external consumption
+- **Project Creation Scripts**: Included automated project scaffolding tools for rapid QwickApps React Framework adoption
+- **Storybook Integration**: Full component documentation and interactive examples ready for developers
+- **Production Optimizations**: Stripped logging in production builds, optimized bundle sizes, and enhanced performance characteristics
+- **Publishing Pipeline**: Configured with proper package metadata, repository links, and NPM publishing workflows
+
+### September 13, 2025 - Schema-Driven Factory Pattern Architecture Completed ✅
+
+- **Phase 2 Migration Complete**: Successfully migrated 10+ core components to schema-driven factory pattern with 100% feature parity maintained
+- **Factory Pattern Architecture**: Complete implementation of `createSerializableView` factory generating functional components with static serialization methods
+- **Container vs View Components**: Clear architectural distinction established - Container components (Section, HeroBlock, GridLayout) use `react-children` strategy, View components use appropriate serialization patterns
+- **Security Enhancement**: Content-prop strategy from Phase 1 successfully maintained, preventing JSON deserialization vulnerabilities
+- **Schema Integration**: Components extend ViewSchema or ContainerSchema for standardized prop definitions with existing BaseComponentProps compatibility
+- **QA Results**: All unit tests updated and passing, all Storybook stories rendering correctly, serialization round-trip tests working, build passes successfully
+- **Component Roster**: Section, HeroBlock, GridLayout, GridCell, Image, Button, TextInputField, SelectInputField, HtmlInputField, ChoiceInputField, SwitchInputField migrated
+- **Performance**: All components maintain sub-millisecond serialization performance, factory pattern establishes foundation for future development
+- **Architecture Ready**: Phase 3 cleanup now ready to remove ModelView legacy code and complete transition to modern schema-driven architecture
+
+### September 9, 2025 - Advanced Print System with Professional Layout Control (v1.4.1)
+
+- **Complete Print View System**: Professional print functionality for React Framework with intelligent detection, dynamic configuration, and sophisticated print layouts
+- **Multi-Channel Print Detection**: Browser event integration (Ctrl+P/Cmd+P), and manual print mode controls with comprehensive state management
+- **Advanced Print Configuration**: Complete PrintConfigSchema with theme control (light/dark), palette selection, monochrome optimization, and interactive element hiding
+- **Dynamic Header/Footer System**: ReactNode | string support for print headers and footers with separate first-page variants, automatic height measurement, and CSS variable-driven positioning
+- **Edge-to-Edge Printing**: Configurable page margins (0mm, 6mm, 12mm, 20mm, 25mm) with automatic CSS class application and complete borderless printing capabilities
+- **Print Background Control**: Full background image/color support for printed pages with separate first-page backgrounds and professional document styling
+- **CSS Variable Architecture**: Dynamic injection of print-specific variables (--print-header-height, --print-footer-height, --print-background) with automatic @page rule generation
+- **Schema-Driven Architecture**: Complete integration with PageTemplateSchema for CMS-managed print configurations and serializable page content
+
+### September 5, 2025 - Component Serialization System ("WebView for React")
 
 - **Complete Component Serialization**: Full "WebView for React" functionality enabling components to be serialized to JSON and reconstructed while preserving functionality
 - **Data Binding Preservation**: Serialization system seamlessly preserves data binding configuration across serialize/deserialize cycles
 - **Code Component Reference Implementation**: Code component serves as the canonical example with <1ms serialization performance and comprehensive ReactNode handling
-- **Image Component ModelView Integration**: Image component successfully converted to ModelView architecture with 300-500x performance targets exceeded and 100% backward compatibility
-- **Text Component ModelView Integration**: Text component successfully converted to ModelView architecture with 125-500x performance targets exceeded, comprehensive typography serialization, and 96.3% test coverage
+- **Image Component Schema Integration**: Image component successfully converted to Schema architecture with 300-500x performance targets exceeded and 100% backward compatibility
+- **Text Component Schema Integration**: Text component successfully converted to Schema architecture with 125-500x performance targets exceeded, comprehensive typography serialization, and 96.3% test coverage
 - **HeroBlock Component Complex Serialization**: **First component with nested component serialization** - HeroBlock successfully converted with Button actions array support and 500x performance targets exceeded (0.0009ms basic, 0.0058ms complex serialization)
-- **GridLayout & GridCell Components**: **First responsive grid system with complete serialization** - GridLayout and GridCell components successfully converted to ModelView with 3-169x performance targets exceeded and complete responsive breakpoint preservation
+- **GridLayout & GridCell Components**: **First responsive grid system with complete serialization** - GridLayout and GridCell components successfully converted to Schema with 3-169x performance targets exceeded and complete responsive breakpoint preservation
 - **Responsive Grid Breakthrough**: GridLayout and GridCell establish patterns for responsive layout serialization with all breakpoint configurations (xs,sm,md,lg,xl) preserved through serialization cycles
 - **Complex Layout Support**: GridLayout handles 1-6 column responsive layouts with nested GridCell components, maintaining complete functionality after reconstruction
 - **Nested Component Breakthrough**: HeroBlock establishes architectural patterns for complex components with nested React elements, demonstrating serialization system capability for sophisticated component hierarchies
@@ -28,8 +61,8 @@ A complete React framework for building modern, responsive applications with int
 - **Preventive Lint Rule**: Repo now enforces a custom `no-inline-component-wrapper` ESLint rule (scoped rollout) to block reintroduction of the remount pattern.
 - **Internal Refactor Only**: No public API changes; safe patch update.
 
-
 ### September 2, 2025 - Built-in Error Handling & Accessibility
+
 - **Automatic Error Boundaries**: QwickApp now automatically wraps all content with ErrorBoundary for robust error handling
 - **Built-in Accessibility**: AccessibilityProvider automatically included for WCAG 2.1 AA compliance
 - **Generic Components**: Moved ErrorBoundary, AccessibilityProvider, and Breadcrumbs to framework level
@@ -37,12 +70,14 @@ A complete React framework for building modern, responsive applications with int
 - **Zero Configuration**: Error handling and accessibility features work out-of-the-box with QwickApp
 
 ### September 1, 2025 - Optional Dependencies & Performance
+
 - **Optional Logging**: Made `@qwickapps/logging` an optional dependency with console fallback
 - **Reduced Bundle Size**: Core framework no longer includes logging overhead by default
 - **React Error Fixes**: Fixed React error #62 in Markdown mixed content scenarios
 - **DOM Nesting**: Added automatic cleanup of invalid DOM nesting from marked.js output
 
 ### August 31, 2025 - CMS Content Components  
+
 - **Html Component**: Transform HTML strings into React components with configurable transformation rules
 - **Markdown Component**: Convert Markdown to React components using marked library with Html component integration
 - **Transform System**: Extensible HTML transformation architecture with optimized rule sets for Article and Markdown content
@@ -51,12 +86,14 @@ A complete React framework for building modern, responsive applications with int
 ## Features
 
 ### 🧭 **Responsive Navigation**
+
 - **Mobile**: Bottom navigation bar for touch-friendly access
 - **Tablet**: Expandable nav rail with collapsible sidebar
 - **Desktop**: Top navigation with overflow drawer
 - **Automatic**: Adapts based on screen size without configuration
 
 ### 📐 **Flexible Layout System**
+
 - **Hero Blocks**: Full-width hero sections with background images/gradients
 - **Multi-Column Layouts**: Responsive 2-5 column layouts with equal heights
 - **Content Blocks**: Styled containers with variants (elevated, outlined, filled)
@@ -65,12 +102,14 @@ A complete React framework for building modern, responsive applications with int
 - **CollapsibleLayout**: Advanced expandable/collapsible containers with state management
 
 ### 🎨 **Advanced Theming**
+
 - **Theme Management**: Light, dark, and system theme support
 - **Color Palettes**: Multiple built-in palettes (Ocean, Autumn, Spring, Winter)
 - **CSS Variables**: Dynamic theme switching without re-renders
 - **Custom Palettes**: Easy to create and integrate custom color schemes
 
 ### 🧩 **Component Library**
+
 - **Logo Component**: Dynamic, customizable logos with badges and animations
 - **Theme Controls**: Built-in theme and palette switchers
 - **Form Components**: Accessible, themed form inputs with complete serialization support
@@ -82,9 +121,10 @@ A complete React framework for building modern, responsive applications with int
 - **Transform System**: Extensible HTML element transformation with fallback handling
 
 ### 🔄 **Component Serialization System**
+
 - **"WebView for React" Functionality**: Serialize React components to JSON and reconstruct with full functionality preserved
 - **Complete Form Serialization**: **First form state management serialization system** - All form components preserve controlled component state, validation rules, and error handling
-- **Production-Ready Components**: 11 components with complete ModelView architecture and comprehensive QA validation (Code, Image, Text, HeroBlock, GridLayout, GridCell, TextInputField, SelectInputField, HtmlInputField, ChoiceInputField, SwitchInputField, FormBlock)
+- **Production-Ready Components**: 11 components with complete Schema architecture and comprehensive QA validation (Code, Image, Text, HeroBlock, GridLayout, GridCell, TextInputField, SelectInputField, HtmlInputField, ChoiceInputField, SwitchInputField, FormBlock)
 - **Form Components Innovation**: TextInputField, SelectInputField, HtmlInputField, ChoiceInputField, SwitchInputField, and FormBlock with 97.5% test pass rate and 0.4ms average serialization
 - **Complex Form Data Handling**: Options arrays, HTML content, validation configurations, choice fields, and boolean controls fully supported through serialization
 - **Production Form Workflows**: Complete form creation, editing, validation, and submission workflows preserved through serialize/deserialize cycles
@@ -99,13 +139,15 @@ A complete React framework for building modern, responsive applications with int
 - **Cross-Platform**: Consistent serialization across all major browsers and environments
 
 ### 🛡️ **Built-in Error Handling & Accessibility**
+
 - **ErrorBoundary**: Automatic error catching with user-friendly fallback UI and retry functionality
 - **AccessibilityProvider**: WCAG 2.1 AA compliance with system preference detection and ARIA announcements
 - **Breadcrumbs**: Accessible navigation hierarchy with keyboard support and customization
 - **Automatic Integration**: All features automatically enabled in QwickApp without configuration
 
 ### 📄 **Serializable Page System with Advanced Print Support**
-- **Schema-Driven Architecture**: Complete page templates with ViewModelSchema, PrintConfigSchema, and PageTemplateSchema for full serialization
+
+- **Schema-Driven Architecture**: Complete page templates with ViewSchema, PrintConfigSchema, and PageTemplateSchema for full serialization
 - **Intelligent Print Detection**: Automatic print mode activation via browser events (Ctrl+P/Cmd+P) with comprehensive state management
 - **Advanced Print Configuration**: Complete print theming system with headers, footers, backgrounds, page margins (0mm-25mm), and CSS variable-driven positioning
 - **Dynamic Print Layout**: Edge-to-edge printing capabilities with configurable page margins, automatic height measurement, and proper page break handling
@@ -115,6 +157,7 @@ A complete React framework for building modern, responsive applications with int
 - **Page Context System**: Automatic QwickApp scaffolding integration with print-aware navigation and routing
 
 ### 🚀 **Developer Experience**
+
 - **TypeScript First**: Full TypeScript support with comprehensive types
 - **Storybook**: Interactive component documentation
 - **Performance**: Optimized rendering and minimal bundle size
@@ -122,8 +165,31 @@ A complete React framework for building modern, responsive applications with int
 
 ## Installation
 
+### 🚀 Quick Start (Recommended)
+
+**Create a new QwickApps project in one command:**
+
 ```bash
-npm install @qwickapps/react-framework
+npx @qwickapps/react-framework/scripts/create-qwickapps-project my-qwickapps-project
+cd my-qwickapps-project
+npm start
+```
+
+This will:
+
+1. Create a new React app with TypeScript
+2. Install QwickApps React Framework and all dependencies
+3. Set up a complete QwickApps application template
+4. Start the development server
+
+Your app will be running at `http://localhost:3000` with QwickApps pre-configured!
+
+### 📦 Manual Installation
+
+If you have an existing React project, install the framework manually:
+
+```bash
+npm install @qwickapps/react-framework @emotion/react @emotion/styled @mui/material @mui/icons-material react-router-dom
 ```
 
 ### Optional Dependencies
@@ -138,7 +204,13 @@ This will enable structured logging with configurable levels and outputs. If not
 
 ## Quick Start
 
-### Basic Setup
+### ⚡ Already Used the Quick Start Script?
+
+If you used the quick start script above, your app is already set up and running! Skip to the [Advanced Usage](#advanced-usage) section.
+
+### 🔧 Manual Setup (for existing React projects)
+
+If you're adding QwickApps to an existing React project or installed manually:
 
 ```tsx
 import { 
@@ -255,6 +327,7 @@ function App() {
 ```
 
 **Responsive Behavior:**
+
 - **Mobile (< 768px)**: Bottom navigation bar
 - **Tablet (768-1024px)**: Collapsible sidebar nav rail  
 - **Desktop (> 1024px)**: Top navigation with drawer for overflow
@@ -386,6 +459,7 @@ import { CollapsibleLayout } from '@qwickapps/react-framework';
 ```
 
 **Key Features:**
+
 - **Controlled & Uncontrolled State**: Use `collapsed` prop for controlled state or `defaultCollapsed` for uncontrolled
 - **State Persistence**: `persistState` option saves collapsed state to localStorage
 - **Multiple Animations**: Choose from fade, slide, or scale animations with customizable duration
@@ -467,6 +541,7 @@ const customRules = [
 ```
 
 **Default Transformations:**
+
 - `<pre><code>` → Code component with syntax highlighting
 - `<section class="blog-section">` → Section component
 - `<button>` → Button component
@@ -517,9 +592,10 @@ And some inline \`code\` here.
 ```
 
 **Key Features:**
+
 - GitHub Flavored Markdown support via marked library
 - Automatic syntax highlighting for code blocks
-- Inline code preservation 
+- Inline code preservation
 - Custom transformation rules for HTML elements
 - Error handling with development debugging
 - TypeScript support with comprehensive props interface
@@ -567,6 +643,7 @@ const config: TransformConfig = {
 ```
 
 **Built-in Rule Sets:**
+
 - `defaultArticleRules` - Optimized for blog/article content with header stripping
 - `defaultMarkdownRules` - Optimized for Markdown content with inline code preservation
 
@@ -622,18 +699,21 @@ The QwickApps React Framework includes a sophisticated Page System that enables
 ### Core Page System Features
 
 #### 🎯 **Schema-Driven Architecture**
-- **ViewModelSchema**: Base schema with common UI attributes (styling, accessibility, layout)
+
+- **ViewSchema**: Base schema with common UI attributes (styling, accessibility, layout)
 - **PrintConfigSchema**: Complete print mode configuration with theming and optimization
-- **PageTemplateSchema**: Full page models extending ViewModel with metadata, SEO, and print settings
+- **PageTemplateSchema**: Full page models extending ViewSchema with metadata, SEO, and print settings
 - **JSON Serialization**: Complete page configurations stored and transmitted as JSON
 
 #### 🖨️ **Intelligent Print Detection**
+
 - **Automatic URL Detection**: `?print=true` parameter triggers print mode instantly
 - **Browser Event Integration**: Captures Ctrl+P and print menu events automatically
 - **Manual Control**: Programmatic print mode activation with custom configurations
 - **Scaffolding Awareness**: Automatically hides navigation and headers in print mode
 
 #### 📊 **CMS Integration Ready**
+
 - **Database Storage**: Store complete page templates as JSON in any database
 - **Headless CMS**: Direct integration with Strapi, Contentful, Sanity, and custom APIs
 - **Dynamic Loading**: Fetch page templates at runtime with fallback handling
@@ -642,6 +722,7 @@ The QwickApps React Framework includes a sophisticated Page System that enables
 ### Page Component Usage
 
 #### Basic Page Implementation
+
 ```tsx
 import { Page, usePrintMode, PageTemplateSchema } from '@qwickapps/react-framework';
 
@@ -703,12 +784,13 @@ function AboutPage() {
 
 ### Schema Architecture
 
-#### ViewModelSchema - Base UI Schema
+#### ViewSchema - Base UI Schema
+
 ```tsx
-import { ViewModelSchema } from '@qwickapps/react-framework';
+import { ViewSchema } from '@qwickapps/react-framework';
 
 // Base schema for all UI components - provides consistent styling and accessibility
-interface ViewModelSchema {
+interface ViewSchema {
   // Styling Properties
   className?: string;              // CSS class name for custom styling
   style?: string;                  // Inline styles as JSON string
@@ -725,19 +807,20 @@ interface ViewModelSchema {
   'data-testid'?: string;          // Test automation identifier
 }
 
-// Example: Custom component extending ViewModelSchema
-class CustomCard extends ViewModelSchema {
+// Example: Custom component extending ViewSchema
+class CustomCard extends ViewSchema {
   @Field()
   title?: string;
   
   @Field()
   content?: string;
   
-  // Inherits all styling and accessibility properties from ViewModelSchema
+  // Inherits all styling and accessibility properties from ViewSchema
 }
 ```
 
 #### PrintConfigSchema - Print Configuration
+
 ```tsx
 import { PrintConfigSchema } from '@qwickapps/react-framework';
 
@@ -782,10 +865,11 @@ const invoicePrintConfig: PrintConfigSchema = {
 ```
 
 #### PageTemplateSchema - Complete Page Model
+
 ```tsx
 import { PageTemplateSchema, PrintConfigSchema } from '@qwickapps/react-framework';
 
-interface PageTemplateSchema extends ViewModelSchema {
+interface PageTemplateSchema extends ViewSchema {
   // Page Identity & Navigation
   slug?: string;                    // URL-friendly identifier (e.g., "about-us")
   name?: string;                    // Human-readable page name
@@ -898,6 +982,7 @@ const adminDashboardTemplate: PageTemplateSchema = {
 ### Print Mode Integration
 
 #### usePrintMode Hook - Comprehensive Print Control
+
 ```tsx
 import { usePrintMode } from '@qwickapps/react-framework';
 
@@ -974,6 +1059,7 @@ function DocumentPage() {
 ```
 
 #### Print URL Integration
+
 ```tsx
 // Automatic print mode via URL
 // Navigate to: https://yourapp.com/document?print=true
@@ -1005,6 +1091,7 @@ function App() {
 ### CMS and Database Integration
 
 #### Dynamic Page Loading from CMS
+
 ```tsx
 import { Page, PageTemplateSchema } from '@qwickapps/react-framework';
 
@@ -1100,6 +1187,7 @@ async function fetchPageFromCMS(slug: string): Promise<PageTemplateSchema> {
 ```
 
 #### Database Storage Example
+
 ```tsx
 // Example: Storing page templates in database
 const pageTemplates = [
@@ -1140,6 +1228,7 @@ function DatabasePage({ pageId }: { pageId: number }) {
 ### Page Context and Lifecycle
 
 #### Advanced Page Context Usage
+
 ```tsx
 import { usePageContext, usePage } from '@qwickapps/react-framework';
 
@@ -1182,6 +1271,7 @@ function PageAwareComponent() {
 ### Page Variants and Layout Options
 
 #### Advanced Page Styling
+
 ```tsx
 // Different page layout variants for different use cases
 function LayoutExamples() {
@@ -1254,6 +1344,7 @@ The QwickApps React Framework includes a sophisticated print system that enables
 The print system automatically detects print mode through multiple channels:
 
 #### URL Parameter Detection
+
 ```tsx
 // Navigate to URL with print parameter to automatically enter print mode
 https://yourapp.com/document?print=true
@@ -1262,6 +1353,7 @@ https://yourapp.com/document?print=true
 ```
 
 #### Browser Print Event Detection
+
 ```tsx
 // Automatic detection of Ctrl+P (Windows/Linux) or Cmd+P (Mac)
 // Also detects File > Print menu usage
@@ -1269,6 +1361,7 @@ https://yourapp.com/document?print=true
 ```
 
 #### Manual Print Mode Control
+
 ```tsx
 import { usePrintMode } from '@qwickapps/react-framework';
 
@@ -1317,6 +1410,7 @@ function DocumentPage() {
 ### Print Configuration System
 
 #### Complete Print Configuration Options
+
 ```tsx
 import { PrintConfigSchema } from '@qwickapps/react-framework';
 
@@ -1352,6 +1446,7 @@ const advancedPrintConfig: PrintConfigSchema = {
 ```
 
 #### Page Component with Print Configuration
+
 ```tsx
 import { Page, PrintConfigSchema } from '@qwickapps/react-framework';
 
@@ -1387,6 +1482,7 @@ function ReportPage() {
 ### Page Margins and Layout Options
 
 #### Edge-to-Edge Printing (0mm margins)
+
 ```tsx
 const borderlessPrintConfig = {
   pageMargins: '0mm',        // Complete edge-to-edge printing
@@ -1395,6 +1491,7 @@ const borderlessPrintConfig = {
 ```
 
 #### Standard Margin Options
+
 ```tsx
 const marginOptions = {
   compact: { pageMargins: '6mm' },      // Minimal margins
@@ -1429,6 +1526,7 @@ The print system uses CSS variables for dynamic header/footer positioning:
 ### Advanced Print Headers and Footers
 
 #### ReactNode Headers/Footers
+
 ```tsx
 import { SafeSpan } from '@qwickapps/react-framework';
 
@@ -1461,6 +1559,7 @@ const customPrintConfig = {
 ```
 
 #### Template Variables in Headers/Footers
+
 ```tsx
 const templatePrintConfig = {
   printFooter: 'Page [page] of [total] • Generated on [date] • company.com',
@@ -1478,6 +1577,7 @@ const templatePrintConfig = {
 ### Print-Specific Page Variants
 
 #### Different Layout Variants for Print
+
 ```tsx
 function DocumentPage() {
   return (
@@ -1522,6 +1622,7 @@ function DataTablePage() {
 ### Integration with Page Templates
 
 #### Schema-Driven Print Configuration
+
 ```tsx
 import { PageTemplateSchema } from '@qwickapps/react-framework';
 
@@ -1564,6 +1665,7 @@ function FinancialReportPage() {
 ### Print Mode Context and State Management
 
 #### Accessing Print State Throughout App
+
 ```tsx
 import { usePageContext } from '@qwickapps/react-framework';
 
@@ -1602,6 +1704,7 @@ function PrintAwareComponent() {
 ### Print CSS Classes and Styling
 
 #### Automatic Print Mode Classes
+
 ```css
 /* Page automatically gets print mode classes */
 .page-print-mode {
@@ -1630,6 +1733,7 @@ function PrintAwareComponent() {
 ```
 
 #### Custom Print Styling
+
 ```css
 /* Print-specific component styling */
 @media print {
@@ -1679,6 +1783,7 @@ function PrintAwareComponent() {
 ### Print System Best Practices
 
 #### Performance Optimization
+
 ```tsx
 // Efficient print mode detection
 const { isPrintMode } = usePrintMode();
@@ -1695,6 +1800,7 @@ const printConfig = useMemo(() => ({
 ```
 
 #### Accessibility in Print Mode
+
 ```tsx
 const accessiblePrintConfig = {
   // High contrast for accessibility
@@ -1710,6 +1816,7 @@ const accessiblePrintConfig = {
 ```
 
 #### Multi-Page Document Handling
+
 ```tsx
 function MultiPageDocument() {
   return (
@@ -1741,6 +1848,7 @@ function MultiPageDocument() {
 ### Migration Guide
 
 #### Converting Legacy Pages to New System
+
 ```tsx
 // BEFORE: Legacy page implementation
 function LegacyHomePage() {
@@ -1818,6 +1926,7 @@ function CMSHomePage() {
 ```
 
 #### Print-Aware Migration
+
 ```tsx
 // BEFORE: Manual print handling
 function LegacyPrintablePage() {
@@ -1867,6 +1976,7 @@ function NewPrintablePage() {
 ### Best Practices
 
 #### Page System Best Practices
+
 1. **Use Templates for CMS**: Always use `PageTemplateSchema` for CMS-driven content
 2. **Print Configuration**: Define print behavior early in development
 3. **SEO Optimization**: Always include title, description, and metadata
@@ -1874,6 +1984,7 @@ function NewPrintablePage() {
 5. **Performance**: Lazy load heavy content and optimize images for print
 
 #### Schema Design Patterns
+
 ```tsx
 // Good: Comprehensive page template
 const wellDesignedTemplate: PageTemplateSchema = {
@@ -2302,6 +2413,7 @@ The framework exposes CSS custom properties for consistent theming:
 ```
 
 **Available Variables:**
+
 - `--theme-primary`, `--theme-on-primary`
 - `--theme-secondary`, `--theme-on-secondary`
 - `--theme-surface`, `--theme-on-surface`
@@ -2673,6 +2785,7 @@ myLogger.info('Component initialized');
 ```
 
 **Key Benefits:**
+
 - ✅ No boilerplate conditionals
 - ✅ Automatic production silencing
 - ✅ Namespaced for clarity
@@ -2723,6 +2836,7 @@ QwickApp automatically includes robust error handling and accessibility features
 ### ErrorBoundary
 
 All QwickApp instances are automatically wrapped with an ErrorBoundary that:
+
 - Catches JavaScript errors anywhere in the component tree
 - Displays user-friendly fallback UI with retry functionality
 - Shows error details in development mode
@@ -2745,6 +2859,7 @@ const SafeComponent = withErrorBoundary(MyComponent, {
 ### AccessibilityProvider
 
 All QwickApp instances automatically include accessibility features:
+
 - **System Preferences**: Detects high contrast, reduced motion preferences
 - **Keyboard Navigation**: Enhanced focus indicators for keyboard users
 - **Screen Reader Support**: ARIA live announcements
@@ -2814,12 +2929,14 @@ function DynamicBreadcrumbs() {
 This software is licensed under the **PolyForm Shield License 1.0.0**.
 
 ### 📋 **Quick Summary**
+
 - ✅ **Free to use** for non-competitive purposes
 - ✅ **Source code available** for learning and development
 - ❌ **Cannot be used** to compete with QwickApps
 - ❌ **Cannot be reverse engineered** for competitive purposes
 
 ### ✅ **Permitted Uses**
+
 - Internal business applications
 - Learning and educational projects
 - Non-competitive commercial applications
@@ -2827,6 +2944,7 @@ This software is licensed under the **PolyForm Shield License 1.0.0**.
 - Contributing to this project
 
 ### ❌ **Prohibited Uses**
+
 - Creating competing React frameworks
 - Building competing CMS or application builder tools
 - Reselling or redistributing as a competing product
@@ -2834,10 +2952,102 @@ This software is licensed under the **PolyForm Shield License 1.0.0**.
 
 For complete license terms, see [LICENSE](./LICENSE) and [LICENSE-POLYFORM-SHIELD.txt](./LICENSE-POLYFORM-SHIELD.txt).
 
-**Need commercial licensing?** Contact us at **legal@qwickapps.com**
+**Need commercial licensing?** Contact us at **<legal@qwickapps.com>**
+
+## 📚 Complete Documentation
+
+The QwickApps React Framework includes comprehensive documentation covering all aspects of development, architecture, and usage.
+
+### 🎯 **Quick Links**
+
+- **[📖 Documentation Hub](./docs/README.md)** - Complete documentation index and navigation
+- **[🏗️ Component Architecture](./docs/architecture/component-system.md)** - Modern component architecture with ViewSchema v2.0.0
+- **[🔄 Migration Guide](./docs/architecture/migration-guides/useBaseProps-to-viewmodelschema.md)** - Migrate from useBaseProps to ViewSchema pattern
+- **[⚡ Serialization Guide](./docs/guides/COMPONENT_SERIALIZATION_GUIDE.md)** - Complete component serialization implementation guide
+
+### 🧩 **Component Documentation**
+
+#### Core Components
+
+- **[ViewSchema v2.0.0](./docs/components/base/ViewSchema.md)** - Comprehensive base schema (40+ properties)
+- **[Container](./docs/components/Container.md)** - Core schema-driven component implementation
+- **[Page System](./docs/components/pages/Page.md)** - Advanced page component with print support
+
+#### Layout & Content
+
+- **[GridLayout](./docs/components/layout/GridLayout.md)** - Responsive grid system with serialization
+- **[HeroBlock](./docs/components/blocks/HeroBlock.md)** - Hero sections with complex serialization
+- **[Code Component](./docs/components/blocks/Code.md)** - Reference implementation for serialization
+
+#### Form System
+
+- **[FormBlock](./docs/components/forms/FormBlock.md)** - Form container with state management
+- **[TextInputField](./docs/components/input/TextInputField.md)** - Text input with serialization support
+- **[SelectInputField](./docs/components/input/SelectInputField.md)** - Select dropdown with options serialization
+
+### 📋 **Quick Start with Documentation**
+
+```tsx
+import { 
+  QwickApp, 
+  Container,
+  ViewSchema 
+} from '@qwickapps/react-framework';
+
+// Use ViewSchema v2.0.0 for complete UI control
+interface MyComponentProps extends SchemaProps<ViewSchema> {
+  title: string;
+}
+
+function MyComponent({ title, ...schemaProps }: MyComponentProps) {
+  return (
+    <Container {...schemaProps}>
+      <h1>{title}</h1>
+    </Container>
+  );
+}
+```
+
+For detailed implementation examples, architecture explanations, and migration guides, visit the **[Documentation Hub](./docs/README.md)**.
 
 ## About QwickApps
 
 This framework is part of the QwickApps ecosystem, providing high-quality solutions for educational and productivity applications.
 
-For more information, visit [QwickApps.com](https://qwickapps.com).
+For more information, visit [QwickApps.com](https://qwickapps.com).
+
+## Troubleshooting
+
+### ❌ "react-scripts is not recognized" Error
+
+**Problem**: You're getting an error like `'react-scripts' is not recognized as an internal or external command`
+
+**Solution**: This happens when trying to use QwickApps React Framework without first setting up a React project. QwickApps is a React framework library, not a project generator.
+
+**Fix Options:**
+
+1. **Use the Quick Start Script (Recommended)**:
+
+   ```bash
+   npx @qwickapps/react-framework/scripts/create-qwickapps-project my-project-name
+   ```
+
+2. **Create React App First**:
+
+   ```bash
+   npx create-react-app my-project --template typescript
+   cd my-project
+   npm install @qwickapps/react-framework @emotion/react @emotion/styled @mui/material @mui/icons-material react-router-dom
+   ```
+
+3. **Use with Existing React Project**:
+   - QwickApps works with any existing React 16.8+ project
+   - Just install the dependencies and follow the manual setup guide above
+
+### Other Common Issues
+
+- **Node.js Version**: Make sure you're using Node.js 16 or later
+- **Clear Cache**: If installation fails, try `npm cache clean --force`
+- **Dependency Conflicts**: Delete `node_modules` and `package-lock.json`, then run `npm install`
+
+For more help, [open an issue](https://github.com/raajkumars/qwickapps/issues) on GitHub.