@qwickapps/react-framework 1.4.0 → 1.4.2

package/src/schemas/README.md

@@ -1,661 +0,0 @@
-# QwickApps React Framework - Schema System
-
-**Component Serialization & Data Binding Architecture**
-
-## Overview
-
-The QwickApps Schema System provides comprehensive component serialization and data binding capabilities, enabling "WebView for React" functionality. This system allows React components to be serialized to JSON, transmitted across boundaries, and reconstructed while preserving full functionality and data binding.
-
-## Table of Contents
-
-1. [Architecture Overview](#architecture-overview)
-2. [Serialization System](#serialization-system)
-3. [Data Binding Integration](#data-binding-integration)
-4. [Component Schemas](#component-schemas)
-5. [Transformers](#transformers)
-6. [Usage Examples](#usage-examples)
-7. [Performance Characteristics](#performance-characteristics)
-8. [Testing](#testing)
-
-## Architecture Overview
-
-```
-Schema System Architecture
-├── Serialization Layer
-│   ├── Serializable Interface (types/Serializable.ts)
-│   ├── ComponentTransformer (transformers/ComponentTransformer.ts)
-│   ├── ReactNodeTransformer (transformers/ReactNodeTransformer.ts)
-│   └── Registry System
-├── Data Binding Layer  
-│   ├── Schema Models (CodeSchema.ts, etc.)
-│   ├── Model Base Classes
-│   └── Binding Integration
-└── Component Integration
-    ├── Class-Based Components
-    ├── View Delegation Pattern
-    └── Automatic Registration
-```
-
-## Serialization System
-
-### Core Interfaces
-
-#### Serializable Interface
-```typescript
-// types/Serializable.ts
-interface Serializable {
-  toJson(): any;  // Component instance → JSON data
-}
-
-interface SerializableConstructor {
-  readonly tagName: string;    // Unique component identifier
-  readonly version: string;    // Semantic version
-  fromJson(jsonData: any): ReactElement;  // JSON data → React element
-  new (...args: any[]): Serializable;
-}
-```
-
-#### Data Format
-Serialized components use a standardized structure:
-```json
-{
-  "tag": "ComponentName",
-  "version": "1.0.0",
-  "data": {
-    "prop1": "value1",
-    "prop2": "value2",
-    "dataSource": "api/data/source",
-    "bindingOptions": { "cache": true }
-  }
-}
-```
-
-### Component Self-Declaration Pattern
-
-Components declare their own serialization identity:
-```typescript
-export class MyComponent extends React.Component<MyComponentProps> implements Serializable {
-  // Self-declaration
-  static readonly tagName = 'MyComponent';
-  static readonly version = '1.0.0';
-  
-  // Deserialization
-  static fromJson(jsonData: any): ReactElement {
-    return <MyComponent {...jsonData} />;
-  }
-  
-  // Serialization
-  toJson(): any {
-    return {
-      title: this.props.title,
-      dataSource: this.props.dataSource,
-      bindingOptions: this.props.bindingOptions
-    };
-  }
-}
-```
-
-## Transformers
-
-### ComponentTransformer - Primary Serialization Engine
-
-Located: `transformers/ComponentTransformer.ts`
-
-**Key Features:**
-- Component registration and discovery
-- Bidirectional transformation (serialize/deserialize)
-- Fallback handling for unregistered components
-- Performance optimization with caching
-
-**Primary Methods:**
-```typescript
-class ComponentTransformer {
-  // Register component for serialization
-  static registerComponent(componentClass: SerializableConstructor): void
-
-  // Serialize React nodes to JSON string
-  static serialize(node: ReactNode | ReactNode[]): string
-
-  // Deserialize JSON to React nodes
-  static deserialize(input: string | object | object[]): ReactNode | ReactNode[]
-
-  // Registry management
-  static getRegisteredComponents(): string[]
-  static clearRegistry(): void
-}
-```
-
-**Usage Example:**
-```typescript
-import { ComponentTransformer } from './transformers/ComponentTransformer';
-
-// Serialize component
-const component = <Code language="javascript">console.log('Hello');</Code>;
-const serialized = ComponentTransformer.serialize(component);
-
-// Deserialize back to component
-const deserialized = ComponentTransformer.deserialize(serialized);
-```
-
-### ReactNodeTransformer - Fallback System
-
-Located: `transformers/ReactNodeTransformer.ts`
-
-**Purpose:**
-Handles serialization of unregistered components, HTML elements, and standard React content.
-
-**Capabilities:**
-- Primitive value serialization (strings, numbers, booleans)
-- Array and object handling
-- React element metadata preservation
-- HTML element reconstruction
-- Graceful fallback rendering
-
-**Data Structures:**
-```typescript
-// Primitive values
-{ type: 'primitive', value: 'Hello World' }
-
-// React elements  
-{
-  type: 'react-element',
-  elementType: 'div',
-  props: { className: 'example', children: 'Content' },
-  key: 'unique-key'
-}
-
-// Arrays
-{ type: 'array', children: [/* serialized items */] }
-```
-
-## Data Binding Integration
-
-### Schema Models
-
-Component schemas define data structures for binding:
-
-```typescript
-// Example: CodeSchema.ts
-@Schema('Code', '1.0.0')
-export class CodeModel extends Model {
-  children?: string;
-  language?: string;
-  showCopy?: boolean;
-  showLineNumbers?: boolean;
-  title?: string;
-  wrapLines?: boolean;
-  codeBackground?: string;
-  
-  static getSchema() {
-    return {
-      type: 'object',
-      properties: {
-        children: { type: 'string' },
-        language: { type: 'string', default: 'text' },
-        showCopy: { type: 'boolean', default: true },
-        // ... other properties
-      }
-    };
-  }
-}
-```
-
-### Data Binding Preservation
-
-Serializable components must preserve data binding configuration:
-```typescript
-toJson(): any {
-  return {
-    // Component-specific props
-    title: this.props.title,
-    language: this.props.language,
-    
-    // CRITICAL: Always preserve data binding
-    dataSource: this.props.dataSource,
-    bindingOptions: this.props.bindingOptions
-  };
-}
-```
-
-### Binding Integration Pattern
-
-```typescript
-// Component with data binding support
-export interface ComponentProps extends WithDataBinding {
-  title: string;
-  // ... other props
-}
-
-export class Component extends React.Component<ComponentProps> implements Serializable {
-  render() {
-    // Route based on data binding presence
-    return this.props.dataSource ? 
-      <ComponentWithDataBinding {...this.props} /> : 
-      <ComponentView {...this.props} />;
-  }
-}
-
-// Data binding wrapper
-function ComponentWithDataBinding(props: ComponentProps) {
-  const { dataSource, bindingOptions, ...restProps } = props;
-
-  const { loading, error, ...boundProps } = useDataBinding(
-    dataSource!,
-    restProps,
-    ComponentModel.getSchema(),
-    { cache: true, ...bindingOptions }
-  );
-
-  if (loading) return <LoadingState />;
-  if (error) return <ErrorState error={error} />;
-  
-  return <ComponentView {...boundProps} />;
-}
-```
-
-## Component Schemas
-
-### Schema Definition Pattern
-
-```typescript
-// Base schema structure for all components
-@Schema('ComponentName', '1.0.0')
-export class ComponentModel extends Model {
-  // Core component properties
-  title?: string;
-  visible?: boolean;
-  
-  // Data binding properties (inherited from WithDataBinding)
-  dataSource?: string;
-  bindingOptions?: BindingOptions;
-  
-  // Component-specific properties
-  customProp?: string;
-  
-  static getSchema() {
-    return {
-      type: 'object',
-      properties: {
-        title: { type: 'string' },
-        visible: { type: 'boolean', default: true },
-        customProp: { type: 'string' },
-        // Data binding schema included automatically
-      },
-      required: ['title']
-    };
-  }
-}
-```
-
-### Schema Versioning
-
-```typescript
-// Handle schema evolution with version migrations
-@Schema('Component', '2.0.0')
-export class ComponentModelV2 extends Model {
-  // New property structure
-  config?: ComponentConfig;
-  
-  static migrateFromV1(v1Data: any): ComponentModelV2 {
-    return new ComponentModelV2({
-      title: v1Data.title,
-      config: {
-        theme: v1Data.oldThemeProp || 'default',
-        layout: v1Data.oldLayoutProp || 'standard'
-      }
-    });
-  }
-}
-```
-
-## Usage Examples
-
-### Basic Serialization
-
-```typescript
-import { Code } from '../components/blocks/Code';
-import { ComponentTransformer } from './transformers/ComponentTransformer';
-
-// Create component
-const codeBlock = (
-  <Code language="typescript" showCopy={true}>
-    const example: string = 'Hello World';
-    console.log(example);
-  </Code>
-);
-
-// Serialize
-const serializedJson = ComponentTransformer.serialize(codeBlock);
-console.log('Serialized:', serializedJson);
-
-// Deserialize  
-const reconstructed = ComponentTransformer.deserialize(serializedJson);
-// reconstructed is a fully functional React component
-```
-
-### CMS Integration
-
-```typescript
-// CMS provides serialized component data
-const cmsResponse = {
-  components: [
-    {
-      tag: "Code",
-      version: "1.0.0", 
-      data: {
-        children: "// CMS-provided code\nconst cms = 'integration';",
-        language: "javascript",
-        title: "CMS Example"
-      }
-    }
-  ]
-};
-
-// Render CMS components
-const cmsComponents = cmsResponse.components.map((componentData, index) => (
-  <div key={index}>
-    {ComponentTransformer.deserialize(componentData)}
-  </div>
-));
-```
-
-### Data Binding with Serialization
-
-```typescript
-// Component with data binding
-const dataBoundCode = (
-  <Code 
-    dataSource="api/code-examples/fibonacci"
-    bindingOptions={{ cache: true, cacheTTL: 300000 }}
-    language="javascript"
-    showCopy={true}
-  />
-);
-
-// Serialization preserves data binding
-const serialized = ComponentTransformer.serialize(dataBoundCode);
-
-// After deserialization, data binding continues to work
-const deserialized = ComponentTransformer.deserialize(serialized);
-// Component will still load data from "api/code-examples/fibonacci"
-```
-
-### Component Collections
-
-```typescript
-// Serialize multiple components
-const componentArray = [
-  <Code language="js">const a = 1;</Code>,
-  <Code language="py">print("hello")</Code>,
-  <Code language="html">&lt;div&gt;Hello&lt;/div&gt;</Code>
-];
-
-const serializedArray = ComponentTransformer.serialize(componentArray);
-const deserializedArray = ComponentTransformer.deserialize(serializedArray);
-// Returns array of functional components
-```
-
-## Performance Characteristics
-
-### Benchmarks (QA Validated)
-
-| Operation | Typical Performance | Large Data (1000+ components) | Memory Usage |
-|-----------|-------------------|--------------------------------|--------------|
-| **Serialization** | <1ms | <50ms | <10MB |
-| **Deserialization** | <1ms | <50ms | <10MB |
-| **Round-trip** | <3ms | <100ms | <20MB |
-| **Registry Lookup** | <0.1ms | <0.1ms | Minimal |
-| **Deep Nesting (30 levels)** | <5ms | N/A | <5MB |
-
-### Performance Optimizations
-
-```typescript
-// Registry caching
-const componentRegistry = new Map<string, SerializableConstructor>();
-
-// Lazy processing
-const serializeNode = memoize((node: ReactNode) => {
-  // Expensive serialization operations are cached
-});
-
-// Memory management
-componentWillUnmount() {
-  // Automatic cleanup of cached references
-}
-```
-
-### Performance Testing
-
-```typescript
-// Performance validation test
-test('serialization performance benchmark', () => {
-  const largeComponent = createLargeComponent(1000); // 1000 child components
-  
-  const startTime = performance.now();
-  const serialized = ComponentTransformer.serialize(largeComponent);
-  const serializeTime = performance.now() - startTime;
-  
-  const deserializeStart = performance.now();
-  const deserialized = ComponentTransformer.deserialize(serialized);
-  const deserializeTime = performance.now() - deserializeStart;
-  
-  expect(serializeTime).toBeLessThan(50);   // <50ms for 1000 components
-  expect(deserializeTime).toBeLessThan(50); // <50ms for 1000 components
-});
-```
-
-## Error Handling
-
-### Graceful Degradation
-
-```typescript
-// Unknown component handling
-{
-  tag: "__react_node__",  // Fallback tag
-  version: "1.0.0",
-  data: {
-    type: "react-element",
-    elementType: "div",
-    props: { children: "Fallback content" }
-  }
-}
-
-// Error recovery in deserialization
-static fromJson(jsonData: any): ReactElement {
-  try {
-    return <Component {...jsonData} />;
-  } catch (error) {
-    console.warn('Component deserialization error:', error);
-    return <ErrorFallbackComponent error={error} />;
-  }
-}
-```
-
-### Development vs Production
-
-```typescript
-// Development: Detailed error information
-if (process.env.NODE_ENV === 'development') {
-  console.error('Detailed serialization error:', error, stackTrace);
-}
-
-// Production: Silent fallback
-return <SafeFallbackComponent />;
-```
-
-## Testing
-
-### Test Structure
-
-```
-src/schemas/transformers/__tests__/
-├── ComponentTransformer.test.ts        # Core transformer tests
-├── SerializationIntegration.test.tsx   # Multi-component scenarios
-├── SerializationPerformance.test.ts    # Performance benchmarks  
-├── SerializationErrorHandling.test.ts  # Error scenarios
-├── ComponentSerializationPatterns.test.tsx # Standardized patterns
-├── RealWorldScenarios.test.tsx         # Production use cases
-└── CrossBrowserCompatibility.test.ts   # Browser compatibility
-```
-
-### Test Categories
-
-#### 1. Unit Tests
-```typescript
-describe('ComponentTransformer', () => {
-  test('should serialize component correctly', () => {
-    const component = <Code>test</Code>;
-    const serialized = ComponentTransformer.serialize(component);
-    expect(serialized).toBeTruthy();
-  });
-  
-  test('should deserialize component correctly', () => {
-    const data = { tag: 'Code', version: '1.0.0', data: { children: 'test' } };
-    const component = ComponentTransformer.deserialize(data);
-    expect(component).toBeTruthy();
-  });
-});
-```
-
-#### 2. Integration Tests
-```typescript
-test('should handle nested component serialization', () => {
-  const nested = (
-    <Code title="Parent">
-      <Code language="js">const nested = true;</Code>
-    </Code>
-  );
-  
-  const serialized = ComponentTransformer.serialize(nested);
-  const deserialized = ComponentTransformer.deserialize(serialized);
-  expect(deserialized).toBeTruthy();
-});
-```
-
-#### 3. Performance Tests
-```typescript
-test('should handle large component trees efficiently', () => {
-  const largeTree = createDeepComponentTree(1000);
-  
-  const { duration } = measurePerformance(() => {
-    ComponentTransformer.serialize(largeTree);
-  });
-  
-  expect(duration).toBeLessThan(50); // <50ms for 1000 components
-});
-```
-
-### Generic Test Utilities
-
-```typescript
-// Reusable test helper for component serialization
-export function testComponentSerialization<T>(
-  componentName: string,
-  ComponentClass: any,
-  testCases: Array<{ name: string; props: T }>
-) {
-  describe(`${componentName} Serialization`, () => {
-    testCases.forEach(({ name, props }) => {
-      test(name, () => {
-        const component = React.createElement(ComponentClass, props);
-        const serialized = ComponentTransformer.serialize(component);
-        const deserialized = ComponentTransformer.deserialize(serialized);
-        
-        expect(deserialized).toBeTruthy();
-        expect(JSON.parse(serialized).tag).toBe(ComponentClass.tagName);
-      });
-    });
-  });
-}
-```
-
-## File Structure
-
-```
-src/schemas/
-├── README.md                          # This file
-├── index.ts                           # Main exports
-├── types/
-│   └── Serializable.ts               # Core serialization interfaces
-├── transformers/
-│   ├── ComponentTransformer.ts        # Primary serialization engine
-│   ├── ReactNodeTransformer.ts       # Fallback transformer
-│   ├── registry.ts                   # Component registration utilities
-│   └── __tests__/                    # Comprehensive test suites
-├── models/                            # Schema model definitions
-│   ├── CodeSchema.ts                 # Code component schema
-│   └── [Other component schemas]
-└── utils/
-    └── serializationUtils.ts         # Utility functions
-```
-
-## Migration Guide
-
-### From Non-Serializable Components
-
-1. **Convert to Class Component** (if functional)
-2. **Implement Serializable Interface**
-3. **Add Static Properties** (tagName, version, fromJson)
-4. **Implement toJson Method**
-5. **Preserve Data Binding** (if applicable)
-6. **Add Comprehensive Tests**
-
-See: [Component Serialization Migration Guide](/docs/SERIALIZATION_MIGRATION.md)
-
-## Best Practices
-
-### Implementation Guidelines
-- Use semantic versioning for component evolution
-- Always preserve `dataSource` and `bindingOptions` in serialization
-- Exclude function props from serialization
-- Handle edge cases with proper validation
-- Implement comprehensive error handling
-- Test with realistic data sizes and structures
-
-### Performance Guidelines
-- Cache expensive serialization operations
-- Use memoization for repeated transformations
-- Implement lazy evaluation where possible
-- Monitor memory usage in production
-- Provide fallbacks for performance degradation
-
-### Security Guidelines
-- Validate all deserialized data
-- Sanitize user-generated content
-- Use safe fallback components for unknown data
-- Implement Content Security Policy compatibility
-- Avoid eval() or similar unsafe operations
-
-## Contributing
-
-### Component Registration
-New serializable components are automatically registered when imported. Follow the established patterns:
-
-1. **Implement Serializable interface**
-2. **Follow naming conventions** (PascalCase tagName)
-3. **Use semantic versioning**
-4. **Include comprehensive tests**
-5. **Document serialization behavior**
-
-### Testing Requirements
-All serializable components must include:
-- Basic serialization/deserialization tests
-- Edge case handling tests  
-- Performance benchmark tests
-- Data binding preservation tests (if applicable)
-- Cross-browser compatibility validation
-
-## References
-
-- [Component Serialization Guide](/docs/COMPONENT_SERIALIZATION_GUIDE.md) - Complete implementation guide
-- [Serializable Component Templates](/docs/SERIALIZABLE_COMPONENT_TEMPLATE.md) - Copy-paste boilerplate
-- [Architecture Documentation](/ARCHITECTURE.md#component-serialization-system-architecture) - System architecture
-- [Code Component README](/src/components/blocks/Code.md) - Reference implementation
-
----
-
-## License
-
-Copyright (c) 2025 QwickApps.com. All rights reserved.
-
-The QwickApps Schema System enables powerful "WebView for React" functionality while maintaining component integrity, performance, and developer experience across the entire framework ecosystem.