@qwickapps/react-framework 1.4.1 → 1.4.2

package/src/stories/_templates/SerializationTemplate.tsx

@@ -0,0 +1,165 @@
+/**
+ * SerializationTemplate - Reusable template for component serialization demos
+ * 
+ * Creates standardized serialization stories that demonstrate:
+ * - Component serialization to JSON
+ * - JSON deserialization back to component
+ * - Round-trip validation
+ * - JSON structure visualization
+ * 
+ * Usage:
+ * ```tsx
+ * import { makeSerializationStory } from '../_templates/SerializationTemplate';
+ * 
+ * export const SerializationDemo = makeSerializationStory(() => (
+ *   <Button variant="primary" label="Click Me" />
+ * ));
+ * ```
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import { ComponentTransformer } from '../../schemas/transformers/ComponentTransformer';
+import { registerSerializableComponents } from '../../schemas/transformers/registry';
+import { Code } from '../../components/blocks/Code';
+import { Box, Typography } from '@mui/material';
+
+// Ensure all serializable components are registered
+registerSerializableComponents();
+
+/**
+ * Creates a serialization demo story for any React element
+ * 
+ * @param makeElement - Function that returns the React element to serialize
+ * @returns Story component that demonstrates serialization round-trip
+ */
+export const makeSerializationStory = (makeElement: () => React.ReactElement) => () => {
+  const element = makeElement();
+  
+  let serialized: string;
+  let roundTrip: React.ReactNode;
+  let error: string | null = null;
+  
+  try {
+    // Serialize the element to JSON
+    serialized = ComponentTransformer.serialize(element);
+    
+    // Deserialize back to component
+    roundTrip = ComponentTransformer.deserialize(serialized);
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+    serialized = '{}';
+    roundTrip = <div style={{ color: 'red', padding: '16px' }}>Serialization Error: {error}</div>;
+  }
+  
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+      {/* Original Component */}
+      <Box>
+        <Typography variant="h6" component="h3" gutterBottom>
+          Original Component
+        </Typography>
+        <Box sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+          {element}
+        </Box>
+      </Box>
+      
+      {/* Round-trip Component */}
+      <Box>
+        <Typography variant="h6" component="h3" gutterBottom>
+          Deserialized Component (Round-trip)
+        </Typography>
+        <Box sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+          {roundTrip}
+        </Box>
+      </Box>
+      
+      {/* Serialized JSON */}
+      <Box>
+        <Typography variant="h6" component="h3" gutterBottom>
+          Serialized JSON
+        </Typography>
+        {error ? (
+          <Box sx={{ p: 2, bgcolor: 'error.light', color: 'error.contrastText', borderRadius: 1 }}>
+            <Typography variant="body2">Error: {error}</Typography>
+          </Box>
+        ) : (
+          <Code 
+            language="json" 
+            content={JSON.stringify(JSON.parse(serialized), null, 2)}
+            showCopy={true}
+            showLineNumbers={true}
+            wrapLines={false}
+          />
+        )}
+      </Box>
+      
+      {/* Metadata */}
+      <Box sx={{ mt: 2, p: 2, bgcolor: 'background.paper', borderRadius: 1, border: '1px solid', borderColor: 'divider' }}>
+        <Typography variant="body2" color="text.secondary">
+          <strong>How it works:</strong><br />
+          1. The original component is serialized to JSON using ComponentTransformer<br />
+          2. The JSON is then deserialized back into a React component<br />
+          3. Both components should render identically, proving serialization fidelity<br />
+          4. The JSON shows the exact structure stored for the component
+        </Typography>
+      </Box>
+    </Box>
+  );
+};
+
+/**
+ * Creates a batch serialization demo for multiple elements
+ * 
+ * @param makeElements - Function that returns array of React elements to serialize
+ * @returns Story component that demonstrates batch serialization
+ */
+export const makeBatchSerializationStory = (makeElements: () => React.ReactElement[]) => () => {
+  const elements = makeElements();
+  
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+      <Typography variant="h5" component="h2" gutterBottom>
+        Batch Serialization Demo
+      </Typography>
+      
+      {elements.map((element, index) => {
+        const StoryComponent = makeSerializationStory(() => element);
+        return (
+          <Box key={index} sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+            <Typography variant="h6" component="h3" gutterBottom>
+              Component #{index + 1}: {element.type?.toString() || 'Unknown'}
+            </Typography>
+            <StoryComponent />
+          </Box>
+        );
+      })}
+    </Box>
+  );
+};
+
+/**
+ * Creates a complex serialization demo with nested components
+ * 
+ * @param makeComplexElement - Function that returns a complex nested React element
+ * @returns Story component that demonstrates nested component serialization
+ */
+export const makeComplexSerializationStory = (makeComplexElement: () => React.ReactElement) => () => {
+  const ComplexStory = makeSerializationStory(makeComplexElement);
+  
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <Box sx={{ p: 2, bgcolor: 'info.light', borderRadius: 1 }}>
+        <Typography variant="body2" color="info.contrastText">
+          <strong>Complex Serialization:</strong> This demo shows how nested components with multiple
+          levels of children are serialized and deserialized while maintaining their structure and behavior.
+        </Typography>
+      </Box>
+      
+      <ComplexStory />
+    </Box>
+  );
+};
+
+export default makeSerializationStory;

package/src/templates/TemplateResolver.ts

@@ -4,7 +4,7 @@
 * 
 * Copyright (c) 2025 QwickApps.com. All rights reserved.
 */
-import { Logger, createLogger } from '../utils/logger';
+import { Logger, getLogger } from '../utils/logger';
 import { CachedDataProvider, DataResponse, ICacheProvider, IDataProvider, MemoryCacheProvider, Model, MustacheTemplateProvider, SelectOptions } from '@qwickapps/schema';
 import {
   DataProxy,
@@ -51,7 +51,7 @@ export class TemplateResolver implements ITemplateResolver {
   private log: Logger;
 
   constructor(config: TemplateResolverConfig) {
-    this.log = createLogger('ContentResolver');
+    this.log = getLogger('ContentResolver');
     this.enableLogging = config.enableLogging || false;
     this.templateResolver = config.templateResolver || new MustacheTemplateProvider();
     if (config.cacheProvider === true) {

package/src/types/CollapsibleLayout.ts

@@ -8,7 +8,7 @@
  */
 
 import React, { ReactNode } from 'react';
-import type { WithDataBinding, ModelProps } from '@qwickapps/schema';
+import type { WithDataBinding, SchemaProps } from '@qwickapps/schema';
 import type { WithBaseProps } from '../hooks/useBaseProps';
 import CollapsibleLayoutModel from '../schemas/CollapsibleLayoutSchema';
 
@@ -18,7 +18,7 @@ import CollapsibleLayoutModel from '../schemas/CollapsibleLayoutSchema';
  * This interface combines the schema-defined properties with React-specific types
  * and additional component functionality not captured in the schema.
  */
-export type CollapsibleLayoutViewProps = ModelProps<CollapsibleLayoutModel> & 
+export type CollapsibleLayoutViewProps = SchemaProps<CollapsibleLayoutModel> & 
   WithBaseProps & {
     // ========================================
     // React Event Handlers

package/src/utils/cssUtils.ts

@@ -0,0 +1,49 @@
+/**
+ * Utility functions for CSS value conversions.
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Converts a value to a CSS length string.
+ * @param value The value to convert (number, string, etc.).
+ * @param opts Options for controlling the conversion.
+ * @returns The CSS length string (e.g., "10px", "100%", etc.).
+ */
+export function toCssLength(
+  value: unknown,
+  opts: {
+    defaultUnit?: string;
+    allowedUnits?: string[];
+    allowKeywords?: boolean;
+    fallback?: string;
+  } = {}
+): string {
+  const {
+    defaultUnit = 'px',
+    allowedUnits = ['px','mm','cm','in','pt','pc'],
+    allowKeywords = false,
+    fallback = `0${defaultUnit}`
+  } = opts;
+
+  if (value == null) return fallback;
+
+  if (typeof value === 'number' && isFinite(value)) {
+    return `${value}${defaultUnit}`;
+  }
+
+  const s = String(value).trim();
+  if (!s) return fallback;
+
+  if (allowKeywords && /^(auto|inherit|initial|unset)$/.test(s)) return s;
+
+  // Pure numeric string
+  if (/^-?\d+(\.\d+)?$/.test(s)) return `${s}${defaultUnit}`;
+
+  // Number + allowed unit
+  const unitPattern = new RegExp(
+    `^-?\\d+(?:\\.\\d+)?(${allowedUnits.map(u => u.replace(/[-/\\^$*+?.()|[\]{}]/g,'\\$&')).join('|')})$`
+  );
+  if (unitPattern.test(s)) return s;
+
+  return fallback;
+}

package/src/utils/index.ts

@@ -3,6 +3,7 @@
  * 
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
+export * from './cssUtils';
 export * from './customPaletteManager';
 export * from './dimensions';
 export * from './logger';

package/src/utils/logger.ts

@@ -51,11 +51,11 @@ class NoOpLogger implements Logger {
 /**
  * Create logger with optional @qwickapps/logging dependency
  */
-function createLogger(name: string): Logger {
+function getLogger(name: string): Logger {
   try {
     // Try to use @qwickapps/logging if available
     const logging = require('@qwickapps/logging');
-    return logging.createLogger(name);
+    return logging.getLogger(name);
   } catch {
     // Fallback to console-based logger
     return new ConsoleLogger(name);
@@ -63,21 +63,21 @@ function createLogger(name: string): Logger {
 }
 
 /**
- * Re-export Logger type and createLogger function for compatibility
+ * Re-export Logger type and getLogger function for compatibility
  */
-export { createLogger };
+export { getLogger };
 
 /**
  * Framework-specific loggers
  */
 export const loggers: Record<string, Logger> = {
-  scaffold: createLogger('Scaffold'),
-  navigation: createLogger('Navigation'),
-  auth: createLogger('Auth'),
-  theme: createLogger('Theme'),
-  palette: createLogger('Palette'),
-  form: createLogger('Form'),
-  layout: createLogger('Layout'),
-  menu: createLogger('Menu'),
-  router: createLogger('Router'),
+  scaffold: getLogger('Scaffold'),
+  navigation: getLogger('Navigation'),
+  auth: getLogger('Auth'),
+  theme: getLogger('Theme'),
+  palette: getLogger('Palette'),
+  form: getLogger('Form'),
+  layout: getLogger('Layout'),
+  menu: getLogger('Menu'),
+  router: getLogger('Router'),
 };

package/src/__tests__/components/base/ModelView.test.tsx

@@ -1,220 +0,0 @@
-/**
- * ModelView Base Class Tests
- * 
- * Tests the base ModelView functionality and ensures that components
- * extending it work correctly with serialization.
- * 
- * Copyright (c) 2025 QwickApps.com. All rights reserved.
- */
-
-import React from 'react';
-import { ComponentTransformer } from '../../../schemas/transformers/ComponentTransformer';
-import { Code } from '../../../components/base/../blocks/Code';
-import { Section } from '../../../components/base/../blocks/Section';
-import Button from '../../../components/base/../buttons/Button';
-
-describe('ModelView Base Class', () => {
-  beforeEach(() => {
-    ComponentTransformer.clearRegistry();
-  });
-
-  describe('Component Registration', () => {
-    it('should register all ModelView-based components successfully', () => {
-      ComponentTransformer.registerComponent(Code as any);
-      ComponentTransformer.registerComponent(Section as any);
-      ComponentTransformer.registerComponent(Button as any);
-
-      const registeredComponents = ComponentTransformer.getRegisteredComponents();
-      
-      expect(registeredComponents).toContain('Code');
-      expect(registeredComponents).toContain('Section'); 
-      expect(registeredComponents).toContain('Button');
-    });
-
-    it('should have correct tagName and version properties', () => {
-      expect(Code.tagName).toBe('Code');
-      expect(Code.version).toBe('1.0.0');
-      
-      expect(Section.tagName).toBe('Section');
-      expect(Section.version).toBe('1.0.0');
-      
-      expect(Button.tagName).toBe('Button');
-      expect(Button.version).toBe('1.0.0');
-    });
-  });
-
-  describe('Serialization Pattern', () => {
-    beforeEach(() => {
-      ComponentTransformer.registerComponent(Code as any);
-      ComponentTransformer.registerComponent(Section as any);
-      ComponentTransformer.registerComponent(Button as any);
-    });
-
-    it('should serialize Code component correctly', () => {
-      const codeElement = <Code language="javascript" showCopy={true}>
-        console.log("Hello, World!");
-      </Code>;
-
-      const codeInstance = new Code({
-        language: 'javascript',
-        showCopy: true,
-        children: 'console.log("Hello, World!");'
-      });
-
-      const serialized = codeInstance.toJson();
-
-      expect(serialized).toMatchObject({
-        children: 'console.log("Hello, World!");',
-        language: 'javascript',
-        showCopy: true,
-        dataSource: undefined,
-        bindingOptions: undefined
-      });
-    });
-
-    it('should serialize Section component correctly', () => {
-      const sectionInstance = new Section({
-        background: '#f5f5f5',
-        padding: 'large',
-        children: 'Section content'
-      });
-
-      const serialized = sectionInstance.toJson();
-
-      expect(serialized).toMatchObject({
-        children: 'Section content',
-        background: '#f5f5f5',
-        padding: 'large',
-        dataSource: undefined,
-        bindingOptions: undefined
-      });
-    });
-
-    it('should serialize Button component correctly', () => {
-      const buttonInstance = new Button({
-        label: 'Click me',
-        variant: 'primary',
-        disabled: false,
-        children: 'Click me'
-      });
-
-      const serialized = buttonInstance.toJson();
-
-      expect(serialized).toMatchObject({
-        children: 'Click me',
-        label: 'Click me',
-        variant: 'primary',
-        disabled: false,
-        dataSource: undefined,
-        bindingOptions: undefined
-      });
-    });
-  });
-
-  describe('Data Binding Props', () => {
-    it('should include data binding props in serialization when present', () => {
-      const codeInstance = new Code({
-        language: 'javascript',
-        children: 'test code',
-        dataSource: 'api.code.example',
-        bindingOptions: { cache: true, strict: false }
-      });
-
-      const serialized = codeInstance.toJson();
-
-      expect(serialized.dataSource).toBe('api.code.example');
-      expect(serialized.bindingOptions).toEqual({ cache: true, strict: false });
-    });
-  });
-
-  describe('Common Base Props', () => {
-    it('should handle common props like className and id', () => {
-      const codeInstance = new Code({
-        language: 'javascript',
-        children: 'test',
-        className: 'my-custom-code',
-        id: 'code-block-1'
-      });
-
-      const serialized = codeInstance.toJson();
-
-      expect(serialized.className).toBe('my-custom-code');
-      expect(serialized.id).toBe('code-block-1');
-    });
-  });
-
-  describe('Deserialization', () => {
-    beforeEach(() => {
-      ComponentTransformer.registerComponent(Code as any);
-      ComponentTransformer.registerComponent(Section as any);
-      ComponentTransformer.registerComponent(Button as any);
-    });
-
-    it('should deserialize Code component correctly', () => {
-      const jsonData = {
-        children: 'console.log("test");',
-        language: 'javascript',
-        showCopy: true
-      };
-
-      const element = Code.fromJson(jsonData);
-      
-      expect(React.isValidElement(element)).toBe(true);
-      expect(element.type).toBe(Code);
-      expect(element.props).toMatchObject(jsonData);
-    });
-
-    it('should deserialize Section component correctly', () => {
-      const jsonData = {
-        children: 'Section content',
-        background: '#ffffff',
-        padding: 'medium'
-      };
-
-      const element = Section.fromJson(jsonData);
-      
-      expect(React.isValidElement(element)).toBe(true);
-      expect(element.type).toBe(Section);
-      expect(element.props).toMatchObject(jsonData);
-    });
-
-    it('should deserialize Button component correctly', () => {
-      const jsonData = {
-        label: 'Test Button',
-        variant: 'outlined',
-        disabled: false
-      };
-
-      const element = Button.fromJson(jsonData);
-      
-      expect(React.isValidElement(element)).toBe(true);
-      expect(element.type).toBe(Button);
-      expect(element.props).toMatchObject(jsonData);
-    });
-  });
-
-  describe('Rendering Patterns', () => {
-    it('should render traditional props correctly', () => {
-      const codeInstance = new Code({
-        language: 'javascript',
-        children: 'test code'
-      });
-
-      const rendered = codeInstance.render();
-      
-      expect(React.isValidElement(rendered)).toBe(true);
-    });
-
-    it('should render with data binding when dataSource is present', () => {
-      const codeInstance = new Code({
-        language: 'javascript',
-        children: 'test code',
-        dataSource: 'api.code.example'
-      });
-
-      const rendered = codeInstance.render();
-      
-      expect(React.isValidElement(rendered)).toBe(true);
-    });
-  });
-});

package/src/__tests__/schemas/ViewModelSchema.test.ts

@@ -1,80 +0,0 @@
-/**
- * ViewModel Schema Tests
- * 
- * Tests for ViewModelSchema functionality and validation
- */
-
-import { ViewModelSchema } from '../../schemas/ViewModelSchema';
-
-describe('ViewModelSchema', () => {
-  it('should create a valid ViewModelSchema instance', () => {
-    const viewModel = new ViewModelSchema();
-    expect(viewModel).toBeInstanceOf(ViewModelSchema);
-  });
-
-  it('should have correct schema metadata', () => {
-    const schema = ViewModelSchema.getSchema();
-    expect(schema.name).toBe('ViewModel');
-    expect(schema.version).toBe('1.0.0');
-  });
-
-  it('should validate optional properties correctly', async () => {
-    const data = {
-      className: 'test-class',
-      id: 'test-id',
-      hidden: true,
-      'aria-label': 'Test label',
-      'data-testid': 'test-element'
-    };
-    
-    const result = await ViewModelSchema.validate(data);
-    expect(result.isValid).toBe(true);
-    expect(result.errors).toHaveLength(0);
-  });
-
-  it('should validate style property as string', async () => {
-    const data = {
-      style: '{"color": "red", "margin": "10px"}'
-    };
-    
-    const result = await ViewModelSchema.validate(data);
-    expect(result.isValid).toBe(true);
-    expect(result.errors).toHaveLength(0);
-  });
-
-  it('should handle empty instance without errors', async () => {
-    const data = {};
-    
-    const result = await ViewModelSchema.validate(data);
-    expect(result.isValid).toBe(true);
-    expect(result.errors).toHaveLength(0);
-  });
-
-  it('should create instance with default values', () => {
-    const data = {
-      className: 'test-class',
-      id: 'test-id',
-      hidden: true
-    };
-    
-    const viewModel = ViewModelSchema.createWithDefaults(data);
-    expect(viewModel.className).toBe('test-class');
-    expect(viewModel.id).toBe('test-id');
-    expect(viewModel.hidden).toBe(true);
-  });
-
-  it('should create instance from JSON data correctly', () => {
-    const jsonData = {
-      className: 'restored-class',
-      id: 'restored-id',
-      hidden: false,
-      'aria-label': 'Restored label'
-    };
-    
-    const viewModel = ViewModelSchema.createWithDefaults(jsonData);
-    expect(viewModel.className).toBe('restored-class');
-    expect(viewModel.id).toBe('restored-id');
-    expect(viewModel.hidden).toBe(false);
-    expect(viewModel['aria-label']).toBe('Restored label');
-  });
-});