@qwickapps/react-framework 1.4.0 → 1.4.2

package/src/components/shared/createSerializableView.tsx

@@ -0,0 +1,280 @@
+/**
+ * createSerializableView - Factory for schema-driven components
+ * 
+ * Creates functional components that:
+ * - Normalize schema props using normalizeViewProps
+ * - Apply useBaseProps exactly once for style/html/grid processing
+ * - Optionally integrate data binding (gated by enabled flag)
+ * - Attach static tagName/version/fromJson/toJson for serialization
+ * 
+ * Works seamlessly with existing BaseComponentProps system and provides
+ * the foundation for the new schema-driven architecture.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { ComponentType, ReactElement, ReactNode } from 'react';
+// SerializableConstructor type is defined inline below
+import { useBaseProps, useDataBinding, QWICKAPP_COMPONENT } from '../../hooks';
+import { normalizeViewProps, ViewProps } from './viewProps';
+
+/**
+ * Helper function to convert React children to text content
+ * Used for content-prop strategy to map JSX children to content strings
+ */
+function toText(node: ReactNode): string | undefined {
+  if (node == null || typeof node === 'boolean') return undefined;
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(toText).filter(Boolean).join('');
+  return undefined;
+}
+
+/**
+ * Children handling strategy for serialization
+ */
+type ChildrenStrategy =
+  | { mode: 'react-children' }
+  | { mode: 'content-prop'; propName?: string };
+
+/**
+ * Component factory configuration
+ */
+interface CreateSerializableViewConfig<P extends ViewProps> {
+  /** Component tag name for serialization */
+  tagName: string;
+  /** Component version for serialization */
+  version: string;
+  /** Component role: 'view' for display components, 'container' for layout components */
+  role: 'view' | 'container';
+  /** View function that renders the component */
+  View: ComponentType<P>;
+  /** Children handling strategy - defaults to 'react-children' */
+  childrenStrategy?: ChildrenStrategy;
+  /** Optional prop finalizer function */
+  finalize?: (props: P) => P;
+}
+
+/**
+ * Serializable component interface with all required static properties
+ */
+export interface SerializableComponent<P extends ViewProps> {
+  (props: P): ReactElement;
+  tagName: string;
+  version: string;
+  fromJson: (data: any) => ReactElement;
+  toJson: (props: P) => any;
+  displayName?: string;
+  [QWICKAPP_COMPONENT]: symbol;
+}
+
+/**
+ * Create a serializable view component using the factory pattern
+ * 
+ * @param config - Factory configuration
+ * @returns Serializable component with attached static methods
+ */
+export function createSerializableView<P extends ViewProps>(
+  config: CreateSerializableViewConfig<P>
+): SerializableComponent<P> {
+  const { tagName, version, role, View, childrenStrategy = { mode: 'react-children' }, finalize } = config;
+
+  // Create the main component function
+  function SerializableViewComponent(props: P): ReactElement {
+    const { dataSource, bindingOptions, children, ...schemaProps } = props as any;
+
+    // Step 1: Handle content-prop strategy (map JSX children → content)
+    let propsForProcessing = schemaProps;
+    if (childrenStrategy.mode === 'content-prop') {
+      const propName = childrenStrategy.propName || 'content';
+      if (propsForProcessing[propName] == null) {
+        const textContent = toText(children);
+        if (typeof textContent === 'string') {
+          propsForProcessing = { ...propsForProcessing, [propName]: textContent };
+        }
+      }
+    }
+
+    // Step 2: Normalize schema props to runtime-friendly format
+    const normalizedProps = normalizeViewProps(propsForProcessing);
+
+    // Step 2: ALWAYS call all hooks first (Rules of Hooks)
+    const { loading, error, ...resolvedProps } = useDataBinding(
+      dataSource || undefined, // Pass undefined if no dataSource
+      normalizedProps,
+      undefined, // Schema - let the hook infer it
+      dataSource ? { cache: true, cacheTTL: 300000, strict: false, ...bindingOptions } : { enabled: false }
+    );
+    
+    // Determine which props to use based on data binding state
+    let boundProps = normalizedProps;
+    if (dataSource && !error) {
+      boundProps = { ...normalizedProps, ...resolvedProps };
+    }
+
+    // Step 3: Apply useBaseProps for style/html/grid processing (ALWAYS call this hook)
+    const { gridProps, styleProps, htmlProps, restProps } = useBaseProps(boundProps);
+
+    // Step 4: Handle special states AFTER all hooks have been called
+    if (dataSource && loading) {
+      return <div>Loading...</div> as ReactElement;
+    }
+    
+    if (dataSource && error) {
+      console.error('Data binding error:', error);
+      if (process.env.NODE_ENV !== 'production') {
+        return <div style={{ color: 'red', padding: '1rem', border: '1px solid red' }}>
+          Error loading data: {error.message}
+        </div> as ReactElement;
+      }
+      // In production, continue with fallback props (already set above)
+    }
+
+    // Step 5: Prepare final props and apply optional finalize function
+    let viewProps = {
+      ...restProps,
+      ...styleProps,
+      ...htmlProps,
+      // Grid props are passed separately if needed by container components
+      ...(role === 'container' && gridProps ? { gridProps } : {}),
+    } as P;
+
+    // Apply finalize function if provided
+    if (finalize) {
+      viewProps = finalize(viewProps);
+    }
+
+    // Step 6: Render with appropriate children strategy
+    if (childrenStrategy.mode === 'content-prop') {
+      // For content-prop components, don't pass children to the view
+      return <View {...viewProps} />;
+    } else {
+      // For react-children components, pass children through
+      return <View {...viewProps}>{children}</View>;
+    }
+  }
+
+  // Attach static properties for serialization
+  const component = SerializableViewComponent as unknown as SerializableComponent<P>;
+  
+  // Component identification
+  component.tagName = tagName;
+  component.version = version;
+  component[QWICKAPP_COMPONENT] = QWICKAPP_COMPONENT;
+
+  // Serialization methods
+  component.fromJson = function fromJson(data: any): ReactElement {
+    const { tagName: dataTagName, version: dataVersion, data: componentData } = data;
+    
+    // Validate deserialization data
+    if (dataTagName !== tagName) {
+      throw new Error(`Tag name mismatch: expected ${tagName}, got ${dataTagName}`);
+    }
+    
+    if (dataVersion !== version) {
+      console.warn(`Version mismatch for ${tagName}: expected ${version}, got ${dataVersion}`);
+    }
+
+    // Handle deserialization based on children strategy
+    if (childrenStrategy.mode === 'content-prop') {
+      const propName = childrenStrategy.propName || 'content';
+      const { children: _ignored, ...rest } = componentData || {};
+      const contentData = { ...rest, [propName]: componentData?.[propName] || '' };
+      return React.createElement(component as ComponentType<P>, contentData as P);
+    } else {
+      // For react-children strategy, recursively deserialize children
+      const deserializedData = { ...componentData };
+      if (componentData.children !== undefined) {
+        // Import ComponentTransformer here to avoid circular dependency
+        const { ComponentTransformer } = require('../../schemas/transformers/ComponentTransformer');
+        deserializedData.children = ComponentTransformer.deserialize(componentData.children);
+      }
+      return React.createElement(component as ComponentType<P>, deserializedData as P);
+    }
+  };
+
+  component.toJson = function toJson(props: P): any {
+    // Handle serialization based on children strategy
+    if (childrenStrategy.mode === 'content-prop') {
+      const propName = childrenStrategy.propName || 'content';
+      const { children: _ignored, ...rest } = props || {};
+      const contentValue = (props as any)?.[propName] ?? toText((props as any)?.children);
+      
+      // Clean props for content-prop serialization
+      const cleanProps: any = {};
+      for (const [key, value] of Object.entries(rest)) {
+        if (typeof value === 'function' && key.startsWith('on')) {
+          cleanProps[key] = value.toString();
+        } else if (typeof value !== 'function' && value !== undefined && value !== null) {
+          cleanProps[key] = value;
+        }
+      }
+      
+      return {
+        tagName,
+        version,
+        data: { ...cleanProps, [propName]: contentValue || '' },
+      };
+    } else {
+      // Handle react-children strategy (existing logic)
+      const cleanProps: any = {};
+      
+      for (const [key, value] of Object.entries(props)) {
+        if (typeof value === 'function' && key.startsWith('on')) {
+          // Convert event handlers to string representation
+          cleanProps[key] = value.toString();
+        } else if (typeof value === 'function') {
+          // Skip non-event handler functions
+          continue;
+        } else if (key === 'children') {
+          // IMPORTANT: Include children as-is for recursive serialization by ComponentTransformer
+          // The ComponentTransformer.serializeNode() will handle the recursive serialization
+          cleanProps[key] = value;
+        } else if (value !== undefined && value !== null) {
+          // Include all other serializable props
+          cleanProps[key] = value;
+        }
+      }
+
+      return {
+        tagName,
+        version,
+        data: cleanProps,
+      };
+    }
+  };
+
+  // Set display name for debugging
+  component.displayName = `SerializableView(${tagName})`;
+
+  return component;
+}
+
+/**
+ * Type helper for components created with createSerializableView
+ */
+export type SerializableViewComponent<P extends ViewProps> = SerializableComponent<P>;
+
+/**
+ * Type guard to check if a component is serializable
+ */
+export function isSerializableComponent(component: any): component is SerializableComponent<any> {
+  return component && 
+    typeof component === 'function' &&
+    typeof component.tagName === 'string' &&
+    typeof component.version === 'string' &&
+    typeof component.fromJson === 'function' &&
+    typeof component.toJson === 'function' &&
+    component[QWICKAPP_COMPONENT] === QWICKAPP_COMPONENT;
+}
+
+/**
+ * Extract component metadata for registration
+ */
+export function getComponentMetadata(component: SerializableComponent<any>) {
+  return {
+    tagName: component.tagName,
+    version: component.version,
+    fromJson: component.fromJson,
+    toJson: component.toJson,
+  };
+}

package/src/components/shared/viewProps.ts

@@ -0,0 +1,207 @@
+/**
+ * ViewProps - Runtime-friendly props derived from ViewSchema
+ * 
+ * Provides normalized view props that integrate seamlessly with the existing 
+ * BaseComponentProps system and useBaseProps hook. Handles type conversion
+ * from schema strings to proper React prop types including event handlers,
+ * styling props, and grid values.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { SchemaProps, WithDataBinding } from '@qwickapps/schema';
+import { BaseComponentProps } from '../../hooks/useBaseProps';
+import { ViewSchema } from '../../schemas/ViewSchema';
+
+/**
+ * ViewProps - Single source of truth for all base component props
+ * 
+ * Extends SchemaProps<ViewSchema> to get all base properties with proper types
+ * and adds WithDataBinding for CMS integration. ViewSchema is the authoritative
+ * source for all base props including styling, grid, events, accessibility, etc.
+ */
+export interface ViewProps extends SchemaProps<ViewSchema>, WithDataBinding {
+  // Add children prop for components that need it
+  children?: React.ReactNode;
+}
+
+/**
+ * Type for string event handlers in schema
+ */
+type EventHandlerValue = string | React.MouseEventHandler<any> | React.FocusEventHandler<any> | undefined;
+
+/**
+ * Runtime event handler conversion map
+ */
+interface EventHandlers {
+  onClick?: React.MouseEventHandler<any>;
+  onMouseEnter?: React.MouseEventHandler<any>;
+  onMouseLeave?: React.MouseEventHandler<any>;
+  onFocus?: React.FocusEventHandler<any>;
+  onBlur?: React.FocusEventHandler<any>;
+}
+
+/**
+ * Convert string event handlers to React function handlers
+ * @param eventHandlers - Object containing string or function event handlers
+ * @returns Object with converted function handlers
+ */
+function parseEventHandlers(eventHandlers: Record<string, EventHandlerValue>): EventHandlers {
+  const result: EventHandlers = {};
+  
+  for (const [key, value] of Object.entries(eventHandlers)) {
+    if (typeof value === 'string' && value.trim()) {
+      try {
+        // Convert string to function - safe eval for event handlers
+        // This creates a function that executes the string as code
+        const func = new Function('event', value);
+        result[key as keyof EventHandlers] = func as any;
+      } catch (error) {
+        console.warn(`Invalid event handler string for ${key}:`, value, error);
+        // Keep as undefined for invalid handlers
+      }
+    } else if (typeof value === 'function') {
+      // Already a function, use as-is
+      result[key as keyof EventHandlers] = value as any;
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * Parse SX props from string or object
+ * @param sx - SX prop as string or object
+ * @returns Parsed SX props
+ */
+function parseSxProps(sx: string | SxProps<Theme> | undefined): SxProps<Theme> | undefined {
+  if (!sx) return undefined;
+  
+  if (typeof sx === 'string') {
+    try {
+      return JSON.parse(sx);
+    } catch (error) {
+      console.warn('Invalid sx JSON string:', sx, error);
+      return undefined;
+    }
+  }
+  
+  return sx;
+}
+
+/**
+ * Parse style props from string or object
+ * @param style - Style prop as string or object
+ * @returns Parsed style props
+ */
+function parseStyleProps(style: string | React.CSSProperties | undefined): React.CSSProperties | undefined {
+  if (!style) return undefined;
+  
+  if (typeof style === 'string') {
+    try {
+      return JSON.parse(style);
+    } catch (error) {
+      console.warn('Invalid style JSON string:', style, error);
+      return undefined;
+    }
+  }
+  
+  return style;
+}
+
+/**
+ * Coerce grid values from strings to numbers/keywords
+ * @param value - Grid value as string or number
+ * @returns Coerced value
+ */
+function coerceGridValue(value: string | number | undefined): number | 'auto' | 'grow' | undefined {
+  if (value === undefined || value === null) return undefined;
+  
+  if (typeof value === 'number') return value;
+  
+  if (typeof value === 'string') {
+    // Handle keyword values
+    if (value === 'auto' || value === 'grow') return value;
+    
+    // Try to parse as number
+    const parsed = parseInt(value, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  
+  return undefined;
+}
+
+/**
+ * Normalize ViewProps for runtime use
+ * 
+ * Converts schema-friendly string props to runtime-friendly React props:
+ * - Parses sx/style JSON strings
+ * - Converts string event handlers to functions
+ * - Coerces grid span/breakpoint values from strings to numbers/keywords
+ * - Maintains compatibility with BaseComponentProps system
+ * 
+ * @param props - Raw ViewProps from schema
+ * @returns Normalized props compatible with useBaseProps
+ */
+export function normalizeViewProps<T extends ViewProps>(props: T): T & BaseComponentProps {
+  const {
+    sx,
+    style,
+    onClick,
+    onMouseEnter,
+    onMouseLeave,
+    onFocus,
+    onBlur,
+    span,
+    xs,
+    sm,
+    md,
+    lg,
+    xl,
+    backgroundColor,
+    ...restProps
+  } = props;
+
+  // Parse style and sx props
+  const normalizedSx = parseSxProps(sx);
+  const normalizedStyle = parseStyleProps(style);
+
+  // Parse event handlers
+  const eventHandlers = parseEventHandlers({
+    onClick,
+    onMouseEnter,
+    onMouseLeave,
+    onFocus,
+    onBlur,
+  });
+
+  // Coerce grid values
+  const normalizedGridProps = {
+    span: coerceGridValue(span),
+    xs: coerceGridValue(xs),
+    sm: coerceGridValue(sm),
+    md: coerceGridValue(md),
+    lg: coerceGridValue(lg),
+    xl: coerceGridValue(xl),
+  };
+
+  // Canonicalize background prop (backgroundColor → background)
+  const canonicalBackground = (restProps as any).background ?? backgroundColor;
+
+  // Return normalized props with proper typing
+  const normalized = {
+    ...restProps,
+    ...normalizedGridProps,
+    sx: normalizedSx,
+    style: normalizedStyle,
+    ...eventHandlers,
+    // Set canonical background prop
+    background: canonicalBackground,
+  } as T & BaseComponentProps;
+
+  // Remove backgroundColor to avoid duplication
+  delete (normalized as any).backgroundColor;
+  
+  return normalized;
+}

package/src/config/__tests__/AppConfigBuilder.test.ts

@@ -107,7 +107,7 @@ describe('AppConfigBuilder', () => {
         .withId('custom-app')
         .withShortName('Custom')
         .withDescription('A custom application')
-        .withVersion('2.0.0')
+        .withVersion('1.0.0')
         .withLogo('./custom-logo.svg')
         .withPort(4000)
         .withPreviewPort(5000)
@@ -118,7 +118,7 @@ describe('AppConfigBuilder', () => {
 
       expect(config.app.shortName).toBe('Custom');
       expect(config.app.description).toBe('A custom application');
-      expect(config.app.version).toBe('2.0.0');
+      expect(config.app.version).toBe('1.0.0');
       expect(config.app.logo).toBe('./custom-logo.svg');
       expect(config.build.port).toBe(4000);
       expect(config.build.previewPort).toBe(5000);

package/src/contexts/DataContext.tsx

@@ -202,7 +202,7 @@ export function useResolveTemplate(template: string) {
     let isMounted = true;
 
     async function resolve() {
-      if (!template || !template.includes('{{')) {
+      if (!template) {
         setResolved(template);
         return;
       }

package/src/schemas/ButtonSchema.ts

@@ -6,10 +6,11 @@
 
 import { IsBoolean, IsOptional, IsString, IsIn } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import { ViewSchema } from './ViewSchema';
 
 @Schema('Button', '1.0.0')
-export class ButtonModel extends Model {
+export class ButtonModel extends ViewSchema {
   @Field()
   @Editor({
     field_type: FieldType.TEXT,

package/src/schemas/CardListGridSchema.ts

@@ -6,10 +6,11 @@
 
 import { IsArray, IsOptional, IsNumber, IsIn, IsBoolean, IsObject, IsString } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import { ContainerSchema } from './ContainerSchema';
 
 @Schema('CardListGrid', '1.0.0')
-export class CardListGridModel extends Model {
+export class CardListGridModel extends ContainerSchema {
   @Field()
   @Editor({
     field_type: FieldType.REPEATER,

package/src/schemas/ChoiceInputFieldSchema.ts

@@ -6,10 +6,11 @@
 
 import { IsArray, IsBoolean, IsNumber, IsOptional, IsString } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import { ViewSchema } from './ViewSchema';
 
 @Schema('ChoiceInputField', '1.0.0')
-export class ChoiceInputFieldModel extends Model {
+export class ChoiceInputFieldModel extends ViewSchema {
   @Field()
   @Editor({
     field_type: FieldType.TEXT,

package/src/schemas/CodeSchema.ts

@@ -7,19 +7,21 @@
 import type { ReactNode } from 'react';
 import { IsBoolean, IsOptional, IsString } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import ViewSchema from './ViewSchema';
 
 @Schema('Code', '1.0.0')
-export class CodeModel extends Model {
+export class CodeModel extends ViewSchema {
   @Field()
   @Editor({
     field_type: FieldType.TEXTAREA,
-    label: 'Code Content',
-    description: 'The code content to display with syntax highlighting',
+    label: 'Content',
+    description: 'Raw code text. If provided, React children are ignored in serialization.',
     placeholder: 'Enter code content...'
   })
-  @IsString() // Schema validation: must be string for serialization
-  children?: ReactNode; // Runtime type: supports natural React usage
+  @IsOptional()
+  @IsString()
+  content?: string;
 
   @Field()
   @Editor({

package/src/schemas/ContainerSchema.ts

@@ -0,0 +1,25 @@
+/**
+ * ContainerSchema - Comprehensive base class for all container components
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { Editor, Field, FieldType, Schema } from '@qwickapps/schema';
+import { IsOptional, IsString } from 'class-validator';
+import type { ReactNode } from 'react';
+import 'reflect-metadata';
+import ViewSchema from './ViewSchema';
+
+@Schema('ContainerSchema', '1.0.0')
+export class ContainerSchema extends ViewSchema {
+    @Field()
+    @Editor({
+        field_type: FieldType.TEXTAREA,
+        label: 'Content',
+        description: 'Main content shown when expanded (HTML supported)',
+        placeholder: 'Enter main content...'
+    })
+    @IsOptional()
+    @IsString()
+    children?: ReactNode;
+}

package/src/schemas/FeatureCardSchema.ts

@@ -80,7 +80,7 @@ export class FeatureCardActionModel extends Model {
   disabled?: boolean;
 }
 
-@Schema('FeatureCard', '2.0.0')
+@Schema('FeatureCard', '1.0.0')
 export class FeatureCardModel extends Model {
   @Field({ type: DataType.OBJECT })
   @Editor({

package/src/schemas/FormBlockSchema.ts

@@ -6,10 +6,11 @@
 
 import { IsBoolean, IsIn, IsOptional, IsString } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import { ContainerSchema } from './ContainerSchema';
 
 @Schema('FormBlock', '1.0.0')
-export class FormBlockModel extends Model {
+export class FormBlockModel extends ContainerSchema {
   @Field()
   @Editor({
     field_type: FieldType.TEXT,

package/src/schemas/GridCellSchema.ts

@@ -7,18 +7,12 @@
 import type { ReactNode } from 'react';
 import { IsOptional, IsString, IsNumber, IsIn } from 'class-validator';
 import 'reflect-metadata';
-import { Editor, Field, Schema, Model, FieldType } from '@qwickapps/schema';
+import { Editor, Field, Schema, FieldType } from '@qwickapps/schema';
+import { ContainerSchema } from './ContainerSchema';
 
 @Schema('GridCell', '1.0.0')
-export class GridCellModel extends Model {
-  @Field()
-  @Editor({
-    field_type: FieldType.TEXTAREA,
-    label: 'Children',
-    description: 'Content to display inside the grid cell',
-    placeholder: 'Nested components will be serialized automatically'
-  })
-  children?: ReactNode; // Runtime type: supports natural React usage
+export class GridCellModel extends ContainerSchema {
+  // children field inherited from ContainerSchema
 
   // Grid responsive properties
   @Field()