@qwickapps/react-framework 1.3.4 → 1.4.0

package/src/schemas/transformers/ComponentTransformer.ts

@@ -0,0 +1,403 @@
+/**
+ * ComponentTransformer - Core component serialization and HTML pattern transformation system
+ * 
+ * Enables "WebView for React" functionality by providing serialization
+ * and deserialization of React components to/from JSON structures.
+ * Also supports HTML pattern-based transformations where components can
+ * register HTML patterns they can handle.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { ReactNode, ReactElement } from 'react';
+import { SerializableConstructor } from '../types/Serializable';
+import { ReactNodeTransformer } from './ReactNodeTransformer';
+
+/**
+ * Registry for component classes that support serialization
+ */
+const componentRegistry = new Map<string, SerializableConstructor>();
+
+/**
+ * Registry for HTML pattern handlers
+ */
+const patternRegistry = new Map<string, PatternHandler>();
+
+/**
+ * Type for HTML pattern transformation handlers
+ */
+export type PatternHandler = (element: Element) => any;
+
+/**
+ * Core transformer for React component serialization
+ * Provides static methods for component registration and transformation
+ */
+export class ComponentTransformer {
+  /**
+   * Register a component class for serialization
+   * Component must declare its own tagName and version via static properties
+   * @param componentClass - Component class that implements Serializable interface
+   */
+  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`);
+    }
+    
+    if (componentRegistry.has(tagName)) {
+      console.warn(`Component '${tagName}' is already registered. Overwriting existing registration.`);
+    }
+    
+    componentRegistry.set(tagName, componentClass);
+    
+    // Register HTML patterns if component supports them
+    if (typeof (componentClass as any).registerPatternHandlers === 'function') {
+      (componentClass as any).registerPatternHandlers(ComponentTransformer);
+    }
+  }
+
+  /**
+   * Serialize React node(s) to JSON string
+   * @param node - React node or array of nodes to serialize
+   * @returns JSON string representation
+   */
+  static serialize(node: ReactNode | ReactNode[]): string {
+    const serializedData = ComponentTransformer.serializeNode(node);
+    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
+   */
+  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;
+        }
+      }
+    } else {
+      parsedData = input;
+    }
+
+    return ComponentTransformer.deserializeData(parsedData);
+  }
+
+  /**
+   * Internal method to serialize a single React node
+   * @param node - React node to serialize
+   * @returns Serializable data structure
+   */
+  private static serializeNode(node: ReactNode): any {
+    if (node === null || node === undefined) {
+      return null;
+    }
+
+    // Handle arrays of nodes
+    if (Array.isArray(node)) {
+      return node.map(child => ComponentTransformer.serializeNode(child));
+    }
+
+    // Handle primitive values
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
+      return node;
+    }
+
+    // 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);
+        }
+        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
+          };
+        }
+      }
+
+      // For unregistered components, use ReactNodeTransformer fallback
+      return ComponentTransformer.serializeUnregisteredComponent(element);
+    }
+
+    // Fallback for other node types
+    return String(node);
+  }
+
+  /**
+   * Internal method to deserialize data back to React nodes
+   * @param data - Data to deserialize
+   * @returns React node(s)
+   */
+  private static deserializeData(data: any): ReactNode | ReactNode[] {
+    if (data === null || data === undefined) {
+      return null;
+    }
+
+    // Handle arrays
+    if (Array.isArray(data)) {
+      return data.map(item => ComponentTransformer.deserializeData(item));
+    }
+
+    // Handle primitive values
+    if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+      return data;
+    }
+
+    // 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);
+      }
+
+      // Validate that componentData exists
+      if (componentData === undefined) {
+        throw new Error(`Malformed component data: missing 'data' property for component '${tag}'`);
+      }
+
+      // Call static fromJson method to recreate the component
+      return componentClass.fromJson(componentData);
+    }
+
+    // Fallback - return as-is
+    return data;
+  }
+
+
+  /**
+   * 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)
+    };
+  }
+
+  /**
+   * Deserialize unregistered components using ReactNodeTransformer
+   * @param data - Serialized data
+   * @returns React node
+   */
+  private static deserializeUnregisteredComponent(data: any): ReactNode {
+    return ReactNodeTransformer.deserialize(data);
+  }
+
+  /**
+   * Find the tag name for a given component constructor
+   * @param componentType - Component constructor function
+   * @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;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get list of registered component tags (for debugging/testing)
+   * @returns Array of registered tag names
+   */
+  static getRegisteredComponents(): string[] {
+    return Array.from(componentRegistry.keys());
+  }
+
+  /**
+   * Clear all registered components (for testing)
+   */
+  static clearRegistry(): void {
+    componentRegistry.clear();
+    patternRegistry.clear();
+  }
+
+  // HTML Pattern Methods
+
+  /**
+   * Register an HTML pattern handler
+   * @param pattern - CSS selector pattern (e.g., 'pre code', 'section.blog-section')
+   * @param handler - Function to transform matching elements to component data
+   */
+  static registerPattern(pattern: string, handler: PatternHandler): void {
+    if (patternRegistry.has(pattern)) {
+      console.warn(`Pattern '${pattern}' is already registered. Overwriting existing handler.`);
+    }
+    patternRegistry.set(pattern, handler);
+  }
+
+  /**
+   * Check if a pattern is registered
+   * @param pattern - CSS selector pattern to check
+   * @returns True if pattern is registered
+   */
+  static hasPattern(pattern: string): boolean {
+    return patternRegistry.has(pattern);
+  }
+
+  /**
+   * Transform an HTML element to React component if a matching pattern exists
+   * @param element - DOM Element to transform
+   * @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 {
+          const componentData = handler(element);
+          return ComponentTransformer.deserialize(componentData);
+        } catch (error) {
+          console.warn(`Error transforming element with pattern '${pattern}':`, error);
+          return null;
+        }
+      }
+    }
+    return null; // No pattern matched
+  }
+
+  /**
+   * Transform HTML string to React nodes using registered patterns
+   * @param html - HTML string to transform
+   * @returns Array of React nodes
+   */
+  static transformHTML(html: string): ReactNode[] {
+    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}`)
+    );
+  }
+
+  /**
+   * Recursively transform an element and its children
+   * @param element - DOM Element to transform
+   * @param key - React key for the element
+   * @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;
+    }
+
+    // No pattern matched - check for nested transformable content
+    const children = Array.from(element.children);
+    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
+        },
+        transformedChildren
+      );
+    }
+
+    // Fallback - use ReactNodeTransformer to handle as unregistered HTML
+    return ReactNodeTransformer.deserialize({
+      type: 'react-element',
+      elementType: element.tagName.toLowerCase(),
+      props: {
+        key,
+        className: element.className || undefined,
+        id: element.id || undefined,
+        dangerouslySetInnerHTML: { __html: element.innerHTML }
+      }
+    });
+  }
+
+  /**
+   * Get list of registered patterns (for debugging/testing)
+   * @returns Array of registered patterns
+   */
+  static getRegisteredPatterns(): string[] {
+    return Array.from(patternRegistry.keys());
+  }
+}

package/src/schemas/transformers/ReactNodeTransformer.ts

@@ -0,0 +1,236 @@
+/**
+ * ReactNodeTransformer - Fallback transformer for standard React content
+ * 
+ * Provides serialization/deserialization for unregistered React components,
+ * HTML elements, and other React content that doesn't implement the 
+ * Serializable interface.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { ReactNode, ReactElement, isValidElement, createElement } from 'react';
+import SafeSpan from '../../components/SafeSpan';
+
+/**
+ * Transformer for standard React content and HTML elements
+ * Used as fallback when components are not registered in ComponentTransformer
+ */
+export class ReactNodeTransformer {
+  /**
+   * Serialize a React node to JSON-compatible structure
+   * @param node - React node to serialize
+   * @returns Serializable data structure
+   */
+  static serialize(node: ReactNode): any {
+    if (node === null || node === undefined) {
+      return null;
+    }
+
+    // Handle arrays of nodes
+    if (Array.isArray(node)) {
+      return {
+        type: 'array',
+        children: node.map(child => ReactNodeTransformer.serialize(child))
+      };
+    }
+
+    // Handle primitive values
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
+      return {
+        type: 'primitive',
+        value: node
+      };
+    }
+
+    // Handle React elements
+    if (isValidElement(node)) {
+      const element = node as ReactElement;
+      
+      return {
+        type: 'react-element',
+        elementType: typeof element.type === 'string' 
+          ? element.type 
+          : (element.type as any).name || 'Anonymous',
+        props: ReactNodeTransformer.serializeProps(element.props),
+        key: element.key
+      };
+    }
+
+    // Handle plain objects
+    if (typeof node === 'object' && node !== null) {
+      try {
+        const serialized: any = { type: 'object', data: {} };
+        for (const [key, value] of Object.entries(node)) {
+          serialized.data[key] = ReactNodeTransformer.serialize(value);
+        }
+        return serialized;
+      } catch {
+        return {
+          type: 'string',
+          value: String(node)
+        };
+      }
+    }
+
+    // Fallback for other types
+    return {
+      type: 'string',
+      value: String(node)
+    };
+  }
+
+  /**
+   * Deserialize data back to React node
+   * @param data - Data to deserialize
+   * @returns React node
+   */
+  static deserialize(data: any): ReactNode {
+    if (data === null || data === undefined) {
+      return null;
+    }
+
+    // Handle serialized data with type information
+    if (typeof data === 'object' && data.type) {
+      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') {
+            for (const [key, value] of Object.entries(data.data)) {
+              result[key] = ReactNodeTransformer.deserialize(value);
+            }
+          }
+          return result;
+          
+        default:
+          return String(data.value || data);
+      }
+    }
+
+    // Handle direct primitive values (backward compatibility)
+    if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+      return data;
+    }
+
+    // Fallback
+    return String(data);
+  }
+
+  /**
+   * Serialize props object, handling nested React nodes
+   * @param props - Props object to serialize
+   * @returns Serialized props
+   */
+  private static serializeProps(props: any): any {
+    if (!props || typeof props !== 'object') {
+      return props;
+    }
+
+    const serialized: any = {};
+    for (const [key, value] of Object.entries(props)) {
+      if (key === 'children') {
+        // Special handling for children prop
+        serialized[key] = ReactNodeTransformer.serialize(value as ReactNode);
+      } else if (typeof value === 'function') {
+        // Skip functions in serialization
+        serialized[key] = null;
+      } else {
+        serialized[key] = value;
+      }
+    }
+
+    return serialized;
+  }
+
+  /**
+   * Deserialize React element data back to React element
+   * @param data - Serialized React element data
+   * @returns React element or fallback content
+   */
+  private static deserializeReactElement(data: any): ReactNode {
+    const { elementType, props, key } = data;
+
+    try {
+      // Handle HTML elements
+      if (typeof elementType === 'string') {
+        const deserializedProps = ReactNodeTransformer.deserializeProps(props);
+        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}`);
+    }
+  }
+
+  /**
+   * Deserialize props object, handling nested React nodes
+   * @param props - Serialized props object
+   * @returns Deserialized props
+   */
+  private static deserializeProps(props: any): any {
+    if (!props || typeof props !== 'object') {
+      return props;
+    }
+
+    const deserialized: any = {};
+    for (const [key, value] of Object.entries(props)) {
+      if (key === 'children') {
+        // Special handling for children prop
+        deserialized[key] = ReactNodeTransformer.deserialize(value);
+      } else {
+        deserialized[key] = value;
+      }
+    }
+
+    return deserialized;
+  }
+
+  /**
+   * Extract text content from props for fallback rendering
+   * @param props - Props object
+   * @returns Text content or null
+   */
+  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;
+  }
+}