@qwickapps/react-framework 1.4.1 → 1.4.2

package/src/schemas/transformers/ComponentTransformer.ts

@@ -28,11 +28,39 @@ const patternRegistry = new Map<string, PatternHandler>();
  */
 export type PatternHandler = (element: Element) => any;
 
+/**
+ * Strict mode: throw on unregistered components
+ * When true, the transformer will throw errors instead of using fallback
+ */
+let strictMode = true;
+
+/**
+ * Fallback tag for unregistered components / html / text (legacy mode only)
+ */
+const FALLBACK_TAG = '__react_node__';
+const FALLBACK_VERSION = '1.0.0';
+
 /**
  * Core transformer for React component serialization
  * Provides static methods for component registration and transformation
  */
 export class ComponentTransformer {
+  /**
+   * Enable or disable strict mode
+   * @param enabled - Whether to enable strict mode (throws on unregistered components)
+   */
+  static setStrictMode(enabled: boolean): void {
+    strictMode = enabled;
+  }
+
+  /**
+   * Check if strict mode is enabled
+   * @returns True if strict mode is enabled
+   */
+  static isStrictMode(): boolean {
+    return strictMode;
+  }
+
   /**
    * Register a component class for serialization
    * Component must declare its own tagName and version via static properties
@@ -40,21 +68,26 @@ export class ComponentTransformer {
    */
   static registerComponent(componentClass: SerializableConstructor): void {
     const { tagName, version } = componentClass;
-    
+
     if (!tagName || typeof tagName !== 'string') {
       throw new Error(`Component class must have a static 'tagName' property`);
     }
-    
+
     if (!version || typeof version !== 'string') {
-      throw new Error(`Component class must have a static 'version' property`);
+      throw new Error(`Component class '${tagName}' must have a static 'version' property`);
     }
-    
+
+    if (typeof (componentClass as any).fromJson !== 'function') {
+      throw new Error(`Component class '${tagName}' must implement static 'fromJson' method`);
+    }
+
     if (componentRegistry.has(tagName)) {
       console.warn(`Component '${tagName}' is already registered. Overwriting existing registration.`);
     }
-    
+
+    console.log(`TEST: Registering component: ${tagName} (version ${version})`);
     componentRegistry.set(tagName, componentClass);
-    
+
     // Register HTML patterns if component supports them
     if (typeof (componentClass as any).registerPatternHandlers === 'function') {
       (componentClass as any).registerPatternHandlers(ComponentTransformer);
@@ -63,185 +96,169 @@ export class ComponentTransformer {
 
   /**
    * Serialize React node(s) to JSON string
-   * @param node - React node or array of nodes to serialize
-   * @returns JSON string representation
+   * In strict mode: throws on unregistered components
+   * In legacy mode: uses fallback tag for unregistered components/html/text
    */
   static serialize(node: ReactNode | ReactNode[]): string {
-    const serializedData = ComponentTransformer.serializeNode(node);
+    const serializedData = ComponentTransformer.serializeNode(node as any);
     return JSON.stringify(serializedData);
   }
 
   /**
    * Deserialize JSON input to React node(s)
-   * @param input - JSON string or parsed object/array to deserialize
-   * @returns React node or array of nodes
+   * In strict mode: throws on unregistered components
+   * In legacy mode: never throws; always returns a valid ReactNode (or array) or null
+   * - Strings: try JSON.parse; if fails, return the string as a text node
+   * - Objects/arrays: only schema objects are transformed; non-schema become text via JSON.stringify
    */
   static deserialize(input: string | object | object[]): ReactNode | ReactNode[] {
-    let parsedData: any;
-
-    // Handle string input - parse JSON only if it looks like JSON
     if (typeof input === 'string') {
-      // Check if string looks like JSON (starts with { [ or " or is a boolean/number/null)
-      const trimmed = input.trim();
-      if (trimmed.startsWith('{') || trimmed.startsWith('[') || trimmed.startsWith('"') || 
-          trimmed === 'null' || trimmed === 'true' || trimmed === 'false' || 
-          (!isNaN(Number(trimmed)) && trimmed !== '')) {
-        try {
-          parsedData = JSON.parse(input);
-        } catch (error) {
-          throw new Error(`Invalid JSON input: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-      } else {
-        // For strings that contain JSON-like characters but aren't valid JSON, try to parse anyway
-        if (trimmed.includes('{') || trimmed.includes('[')) {
-          try {
-            parsedData = JSON.parse(input);
-          } catch (error) {
-            throw new Error(`Invalid JSON input: ${error instanceof Error ? error.message : 'Unknown error'}`);
-          }
-        } else {
-          // Treat as plain string
-          parsedData = input;
-        }
+      try {
+        const parsed = JSON.parse(input);
+        return ComponentTransformer.deserializeData(parsed);
+      } catch {
+        // Not JSON; plain string is a valid ReactNode
+        return input;
       }
-    } else {
-      parsedData = input;
     }
 
-    return ComponentTransformer.deserializeData(parsedData);
+    if (input == null) return null;
+    return ComponentTransformer.deserializeData(input as any);
   }
 
   /**
-   * Internal method to serialize a single React node
-   * @param node - React node to serialize
-   * @returns Serializable data structure
+ * Type guard for serialized component schema objects
+ * Requires: { tagName: string; version: string; data: any }
+ * Optional: key?: string
+ */
+  private static isSerializedComponent(obj: any): obj is { tagName: string; version: string; data: any; key?: string } {
+    return !!obj
+      && typeof obj === 'object'
+      && typeof (obj as any).tagName === 'string'
+      && typeof (obj as any).version === 'string'
+      && 'data' in (obj as any);
+  }
+
+  /**
+   * Internal method to deserialize data back to React nodes
+   * @param data - Data to deserialize
+   * @returns React node(s)
    */
-  private static serializeNode(node: ReactNode): any {
-    if (node === null || node === undefined) {
-      return null;
-    }
+  private static deserializeData(data: any): ReactNode | ReactNode[] {
+    if (data == null) return null;
 
-    // Handle arrays of nodes
-    if (Array.isArray(node)) {
-      return node.map(child => ComponentTransformer.serializeNode(child));
+    // Arrays: map recursively
+    if (Array.isArray(data)) {
+      return data.map(item => ComponentTransformer.deserializeData(item));
     }
 
-    // Handle primitive values
-    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
-      return node;
-    }
+    if (ComponentTransformer.isSerializedComponent(data)) {
+      const { key, tagName, data: componentData } = data;
 
-    // Handle plain objects (non-React elements)
-    if (typeof node === 'object' && node !== null && !('type' in node)) {
-      // For plain objects, try to serialize recursively or convert to string
       try {
-        const serialized: any = {};
-        for (const [key, value] of Object.entries(node)) {
-          serialized[key] = ComponentTransformer.serializeNode(value);
+        const componentClass = componentRegistry.get(tagName);
+
+        if (!componentClass) {
+          if (strictMode) {
+            throw new Error(`Component '${tagName}' is not registered in strict mode`);
+          }
+          // Legacy fallback
+          const node = ComponentTransformer.deserializeUnregisteredComponent(componentData);
+          return key ? React.cloneElement(node as ReactElement, { key }) : node;
         }
-        return serialized;
-      } catch {
-        return String(node);
-      }
-    }
 
-    // Handle React elements
-    if (typeof node === 'object' && node !== null && 'type' in node) {
-      const element = node as ReactElement;
-      
-      // Check if this is a registered component
-      const componentType = element.type;
-      if (typeof componentType === 'function') {
-        // Find the tag name for this component
-        const tagName = ComponentTransformer.findTagNameForComponent(componentType);
-        if (tagName) {
-          const componentClass = componentRegistry.get(tagName)!;
-          // Create a temporary instance to call toJson
-          const instance = new (componentClass as any)(element.props);
-          const serializedData = instance.toJson();
-          
-          return {
-            tag: tagName,
-            version: componentClass.version,
-            data: serializedData
-          };
+        const node = componentClass.fromJson(data);
+        // Apply key if provided
+        return key ? React.cloneElement(node as ReactElement, { key }) : node;
+      } catch (error) {
+        if (strictMode) {
+          throw error; // Re-throw in strict mode
         }
+        console.error(`TEST: Error deserializing component '${tagName}':`, error);
       }
-
-      // For unregistered components, use ReactNodeTransformer fallback
-      return ComponentTransformer.serializeUnregisteredComponent(element);
     }
 
-    // Fallback for other node types
-    return String(node);
+    console.warn(`TEST: Unrecognized data:`, data);
+    return String(data);
   }
 
   /**
-   * Internal method to deserialize data back to React nodes
-   * @param data - Data to deserialize
-   * @returns React node(s)
+   * Internal method to serialize a single React node
+   * @param node - React node to serialize
+   * @returns Serializable data structure { tagName, version, data }
    */
-  private static deserializeData(data: any): ReactNode | ReactNode[] {
-    if (data === null || data === undefined) {
-      return null;
-    }
+  private static serializeNode(node: any): any {
+    if (node == null) return null;
 
-    // Handle arrays
-    if (Array.isArray(data)) {
-      return data.map(item => ComponentTransformer.deserializeData(item));
+    // Handle arrays of nodes (produce array of schema objects/null)
+    if (Array.isArray(node)) {
+      return node.map(child => ComponentTransformer.serializeNode(child));
     }
 
-    // Handle primitive values
-    if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
-      return data;
+    // Handle primitive values (strings, numbers, booleans) - these are valid React children
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
+      return node;
     }
 
-    // Handle serialized component data
-    if (typeof data === 'object' && data.tag) {
-      const { tag, data: componentData } = data;
-      
-      // Handle unregistered components using ReactNodeTransformer
-      if (tag === '__react_node__') {
-        return ComponentTransformer.deserializeUnregisteredComponent(componentData);
-      }
-      
-      const componentClass = componentRegistry.get(tag);
-      if (!componentClass) {
-        // Fallback to ReactNodeTransformer for unknown registered components
-        console.warn(`Unknown component: ${tag}. Using ReactNodeTransformer fallback.`);
-        return ComponentTransformer.deserializeUnregisteredComponent(componentData);
-      }
+    // React elements
+    if (typeof node === 'object' && 'type' in node) {
+      const element = node as ReactElement;
+      const key = element.key ? { key: String(element.key) } : {};
 
-      // Validate that componentData exists
-      if (componentData === undefined) {
-        throw new Error(`Malformed component data: missing 'data' property for component '${tag}'`);
-      }
+      // Registered component?
+      const componentType = element.type;
+      if (typeof componentType === 'function') {
+        const tagName = ComponentTransformer.findTagNameForComponent(componentType);
+        if (tagName) {
+          console.log(`TEST: Serializing component instance of ${tagName}:`, element.props);
+          const componentClass = componentRegistry.get(tagName)!;
 
-      // Call static fromJson method to recreate the component
-      return componentClass.fromJson(componentData);
-    }
+          let serializedData: any = null;
+          console.log(`TEST: Element type:`, typeof (element as any).toJson);
+          console.log(`TEST: Component type:`, typeof (componentClass as any).toJson);
+          if (typeof (componentClass as any).toJson === 'function') {
+            console.log(`TEST: Serializing via component toJson method ${tagName}:`, element.props);
+            serializedData = (componentClass as any).toJson(element.props);
+          }
 
-    // Fallback - return as-is
-    return data;
-  }
+          if (serializedData !== null) {
+            // Process children recursively if they exist in the data
+            if (serializedData.data && serializedData.data.children !== undefined) {
+              serializedData.data.children = ComponentTransformer.serializeNode(serializedData.data.children);
+            }
+            
+            const result = {
+              ...key,
+              ...serializedData
+            };
+            console.log(`TEST: Serialized component ${tagName}:`, result);
+            return result;
+          }
+        } else if (strictMode) {
+          // In strict mode, throw if we can't find a tag name for the component
+          const componentName = (componentType as any).displayName || (componentType as any).name || 'Unknown';
+          throw new Error(`Unregistered component '${componentName}' cannot be serialized in strict mode`);
+        }
+      }
+    }
 
+    if (strictMode) {
+      throw new Error(`Cannot serialize unregistered node in strict mode: ${typeof node === 'object' && node && 'type' in node ? node.type : typeof node}`);
+    }
 
-  /**
-   * Serialize unregistered React components using ReactNodeTransformer
-   * @param element - React element to serialize
-   * @returns Serializable data structure
-   */
-  private static serializeUnregisteredComponent(element: ReactElement): any {
-    return {
-      tag: '__react_node__',
-      version: '1.0.0',
-      data: ReactNodeTransformer.serialize(element)
+    const result = {
+      tagName: FALLBACK_TAG,
+      version: FALLBACK_VERSION,
+      data: ReactNodeTransformer.serialize(node)
     };
+    console.log(`TEST: Serialized unregistered node as ${FALLBACK_TAG}:`, result, node);
+    console.log(`TEST: Component Registry:`, componentRegistry);
+    return result;
   }
 
   /**
-   * Deserialize unregistered components using ReactNodeTransformer
-   * @param data - Serialized data
+   * Deserialize unregistered nodes using ReactNodeTransformer
+   * @param data - Serialized data from ReactNodeTransformer
    * @returns React node
    */
   private static deserializeUnregisteredComponent(data: any): ReactNode {
@@ -254,14 +271,30 @@ export class ComponentTransformer {
    * @returns Tag name or null if not found
    */
   private static findTagNameForComponent(componentType: any): string | null {
-    const entries = Array.from(componentRegistry.entries());
-    for (const [tagName, registeredClass] of entries) {
-      // This is a simplified check - in a real implementation you might need
-      // more sophisticated matching based on the component's static methods
-      if (registeredClass === componentType) {
-        return tagName;
-      }
+    // Direct constructor match
+    for (const [tagName, registeredClass] of componentRegistry.entries()) {
+      if (registeredClass === componentType) return tagName;
+    }
+
+    // If the component exposes a tagName, prefer it
+    const explicitTag = componentType?.tagName;
+    if (typeof explicitTag === 'string' && componentRegistry.has(explicitTag)) {
+      return explicitTag;
+    }
+
+    // Unwrap common HOC/wrapper names
+    const name: string | undefined = componentType?.displayName || componentType?.name;
+    if (name) {
+      // ForwardRef(Typography) -> Typography, Styled(Typography) -> Typography
+      // WithDataBinding(Text) -> Text, TextWithDataBinding -> Text
+      const unwrapped =
+        name.replace(/^[A-Za-z]+?\(([^)]+)\)$/, '$1')
+            .replace(/WithDataBinding$/, '');
+
+      if (componentRegistry.has(unwrapped)) return unwrapped;
+      if (componentRegistry.has(name)) return name;
     }
+
     return null;
   }
 
@@ -310,7 +343,6 @@ export class ComponentTransformer {
    * @returns React node if pattern matches, null otherwise
    */
   static transformHTMLElement(element: Element): ReactNode | null {
-    // Find matching pattern handler
     for (const [pattern, handler] of patternRegistry) {
       if (element.matches(pattern)) {
         try {
@@ -322,7 +354,7 @@ export class ComponentTransformer {
         }
       }
     }
-    return null; // No pattern matched
+    return null;
   }
 
   /**
@@ -331,13 +363,9 @@ export class ComponentTransformer {
    * @returns Array of React nodes
    */
   static transformHTML(html: string): ReactNode[] {
-    if (!html.trim()) {
-      return [];
-    }
-
+    if (!html.trim()) return [];
     const parser = new DOMParser();
     const doc = parser.parseFromString(html, 'text/html');
-    
     return Array.from(doc.body.children).map((element, index) =>
       ComponentTransformer.transformElement(element, `element-${index}`)
     );
@@ -350,28 +378,22 @@ export class ComponentTransformer {
    * @returns React node
    */
   private static transformElement(element: Element, key: string): ReactNode {
-    // Try to find a registered pattern handler
     const transformedNode = ComponentTransformer.transformHTMLElement(element);
-    if (transformedNode) {
-      return transformedNode;
-    }
+    if (transformedNode) return transformedNode;
 
-    // No pattern matched - check for nested transformable content
     const children = Array.from(element.children);
-    const hasTransformableChildren = children.some(child => 
+    const hasTransformableChildren = children.some(child =>
       Array.from(patternRegistry.keys()).some(pattern => child.matches(pattern))
     );
 
     if (hasTransformableChildren) {
-      // Transform children recursively
       const transformedChildren = children.map((child, index) =>
         ComponentTransformer.transformElement(child, `${key}-${index}`)
       );
-      
-      // Create element with transformed children
+
       return React.createElement(
         element.tagName.toLowerCase(),
-        { 
+        {
           key,
           className: element.className || undefined,
           id: element.id || undefined

package/src/schemas/transformers/ReactNodeTransformer.ts

@@ -8,8 +8,8 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
-import { ReactNode, ReactElement, isValidElement, createElement } from 'react';
-import SafeSpan from '../../components/SafeSpan';
+import { ReactElement, ReactNode, createElement, isValidElement } from 'react';
+import { Html } from '../../components/Html';
 
 /**
  * Transformer for standard React content and HTML elements
@@ -45,12 +45,23 @@ export class ReactNodeTransformer {
     // Handle React elements
     if (isValidElement(node)) {
       const element = node as ReactElement;
-      
+      console.log(`TEST: isValidElement:`, element);
+
+      const comp: any = element.type;
+      const rawName =
+        typeof comp === 'string'
+          ? comp
+          : comp?.render?.name || comp?.name || comp?.muiName || comp?.displayName || 'Anonymous';
+
+      // Normalize wrapper names like ForwardRef(Typography), Styled(Typography)
+      const displayName =
+        typeof rawName === 'string'
+          ? (rawName.match(/^[A-Za-z]+?\(([^)]+)\)$/)?.[1] || rawName)
+          : 'Anonymous';
+
       return {
         type: 'react-element',
-        elementType: typeof element.type === 'string' 
-          ? element.type 
-          : (element.type as any).name || 'Anonymous',
+        elementType: displayName,
         props: ReactNodeTransformer.serializeProps(element.props),
         key: element.key
       };
@@ -94,16 +105,16 @@ export class ReactNodeTransformer {
       switch (data.type) {
         case 'primitive':
           return data.value;
-          
+
         case 'string':
           return data.value;
-          
+
         case 'array':
           return data.children?.map((child: any) => ReactNodeTransformer.deserialize(child)) || [];
-          
+
         case 'react-element':
           return ReactNodeTransformer.deserializeReactElement(data);
-          
+
         case 'object':
           const result: any = {};
           if (data.data && typeof data.data === 'object') {
@@ -112,7 +123,7 @@ export class ReactNodeTransformer {
             }
           }
           return result;
-          
+
         default:
           return String(data.value || data);
       }
@@ -165,23 +176,15 @@ export class ReactNodeTransformer {
       // Handle HTML elements
       if (typeof elementType === 'string') {
         const deserializedProps = ReactNodeTransformer.deserializeProps(props);
+        console.log(`TEST: Create Element:`, elementType, deserializedProps);
         return createElement(elementType, { key, ...deserializedProps });
       }
-
-      // For unknown component types, check if we have HTML content
-      if (props && typeof props.children === 'string' && props.children.includes('<')) {
-        // Use SafeSpan component to render HTML content safely
-        return createElement(SafeSpan, { key, html: props.children });
-      }
-
-      // Fallback to div with text content
-      const textContent = ReactNodeTransformer.extractTextContent(props);
-      return createElement('div', { key }, textContent || `Unknown component: ${elementType}`);
-      
     } catch (error) {
       console.warn('Error deserializing React element:', error);
-      return createElement('div', { key }, `Error rendering component: ${elementType}`);
     }
+
+    // Use Html component to render HTML content safely
+    return createElement(Html, { key, children: props.children });
   }
 
   /**
@@ -214,23 +217,23 @@ export class ReactNodeTransformer {
    */
   private static extractTextContent(props: any): string | null {
     if (!props) return null;
-    
+
     if (typeof props.children === 'string') {
       return props.children;
     }
-    
+
     if (props.title && typeof props.title === 'string') {
       return props.title;
     }
-    
+
     if (props.label && typeof props.label === 'string') {
       return props.label;
     }
-    
+
     if (props.text && typeof props.text === 'string') {
       return props.text;
     }
-    
+
     return null;
   }
 }

package/src/schemas/transformers/registry.ts

@@ -8,27 +8,34 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
-import { ComponentTransformer } from './ComponentTransformer';
+import { Container } from '../../components/base/Container';
 import { Code } from '../../components/blocks/Code';
-import { Section } from '../../components/blocks/Section';
+import { HeroBlock } from '../../components/blocks/HeroBlock';
 import { Image } from '../../components/blocks/Image';
+import { Section } from '../../components/blocks/Section';
 import { Text } from '../../components/blocks/Text';
-import { HeroBlock } from '../../components/blocks/HeroBlock';
-import Button from '../../components/buttons/Button';
-import { GridLayout } from '../../components/layout/GridLayout';
-import { GridCell } from '../../components/layout/GridCell';
-import { TextInputField } from '../../components/input/TextInputField';
-import { SelectInputField } from '../../components/input/SelectInputField';
-import { HtmlInputField } from '../../components/input/HtmlInputField';
+import { Button } from '../../components/buttons/Button';
+import { FormBlock } from '../../components/forms/FormBlock';
 import { ChoiceInputField } from '../../components/input/ChoiceInputField';
+import { HtmlInputField } from '../../components/input/HtmlInputField';
+import { SelectInputField } from '../../components/input/SelectInputField';
 import { SwitchInputField } from '../../components/input/SwitchInputField';
-import { FormBlock } from '../../components/forms/FormBlock';
+import { TextInputField } from '../../components/input/TextInputField';
+import { GridCell } from '../../components/layout/GridCell';
+import { GridLayout } from '../../components/layout/GridLayout';
+import { ComponentTransformer } from './ComponentTransformer';
 
 /**
  * Register all serializable components with the ComponentTransformer
  * This function should be called once during application initialization
+ * 
+ * Phase 0: Foundation in place - ready for component migration
+ * Phase 1+: Components will be migrated to createSerializableView factory
  */
 export function registerSerializableComponents(): void {
+  // Register Container component - Base layout component with child serialization support
+  ComponentTransformer.registerComponent(Container as any);
+
   // Register Code component - First production component with serialization support
   ComponentTransformer.registerComponent(Code as any);