@qwickapps/react-framework 1.3.0

package/src/types/DataTypes.ts

@@ -0,0 +1,196 @@
+/**
+ * Content Types for QwickApps React Framework
+ *
+ * These interfaces define the framework-agnostic content structure that can be
+ * automatically created and managed across different CMS systems and used
+ * for template resolution and component rendering.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+
+/**
+ * Base content structure - common properties for all content elements
+ */
+export interface BaseContent {
+  /** Unique identifier for this content element */
+  name: string;
+  /** Display title for this content element */
+  title?: string;
+  /** Subtitle or description */
+  subtitle?: string;
+  /** Short text displayed above the title */
+  overline?: string;
+  /** Icon identifier or URL for this content element */
+  icon?: string;
+}
+
+
+/**
+ * Individual content field definition
+ */
+export interface Field extends BaseContent {
+  /** The type of field */
+  type: string;
+  /** Current value of the field */
+  value?: any;
+  /** Default value for the field */
+  defaultValue?: any;
+  /** Whether this field is required */
+  required?: boolean;
+  /** Placeholder text for input fields */
+  placeholder?: string;
+  /** Help text or instructions */
+  instructions?: string;
+  /** Options for select/radio/checkbox fields */
+  choices?: Array<{ label: string; value: any }>;
+  /** Minimum value (for numbers) or length (for text) */
+  min?: number;
+  /** Maximum value (for numbers) or length (for text) */
+  max?: number;
+  /** Regular expression for validation */
+  pattern?: string;
+}
+
+/**
+ * HTTP methods for form submission
+ */
+export enum FormMethod {
+  POST = 'POST',
+  PUT = 'PUT',
+  PATCH = 'PATCH'
+}
+
+/**
+ * Action types for interactive elements
+ */
+export enum ActionType {
+  NAVIGATE = 'navigate',
+  SUBMIT = 'submit',
+  RESET = 'reset',
+  CANCEL = 'cancel'
+}
+
+/**
+ * Action definition for interactive elements
+ */
+export interface Action extends BaseContent {
+  /** The type of action */
+  type: ActionType;
+  /** Target URL for navigation actions */
+  target?: string;
+  /** JavaScript handler function name */
+  handler?: string;
+  /** Whether the action is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Field group - container for fields and nested field groups
+ */
+export interface FieldGroup extends BaseContent {
+  /** Child fields in this group */
+  fields?: Field[];
+  /** Nested field groups */
+  fieldGroups?: FieldGroup[];
+  /** Actions available for this field group */
+  actions?: Action[];
+  /** Whether this field group is repeatable */
+  repeatable?: boolean;
+  /** Minimum number of repetitions */
+  minRows?: number;
+  /** Maximum number of repetitions */
+  maxRows?: number;
+}
+
+/**
+ * Form-specific field with validation
+ */
+export interface FormField extends Field {
+  /** Validation rules for forms */
+  validation?: {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    custom?: (value: any) => boolean | string;
+  };
+}
+
+/**
+ * Form-specific action
+ */
+export interface FormAction extends Action {
+  type: ActionType;
+  /** Form validation behavior */
+  validateOnAction?: boolean;
+}
+
+/**
+ * Form field group
+ */
+export interface FormFieldGroup extends FieldGroup {
+  fields?: FormField[];
+  actions?: FormAction[];
+  /** Form submission endpoint */
+  submitUrl?: string;
+  /** Form method */
+  method?: FormMethod;
+}
+
+/**
+ * Content represents any structured data that can be persisted and managed
+ * through the CMS. All content is essentially a field group with a unique type name.
+ * 
+ * Content types are string-based for maximum flexibility - can be anything
+ * as long as it's unique (e.g., 'contact', 'product', 'blog-post', 'testimonial').
+ */
+export interface Data extends FieldGroup {
+  /** The type of content - flexible string identifier */
+  type: string;
+  /** Whether this content should be auto-created if missing */
+  autoCreate?: boolean;
+}
+
+/**
+ * Generic link interface for database persistence
+ * This is a simple data structure, not a Content type
+ */
+export interface Link {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** URL */
+  url: string;
+  /** Icon identifier or URL */
+  icon?: string;
+}
+
+/**
+ * Social media link extending base Link
+ * This is a simple data structure, not a Content type
+ */
+export interface SocialLink extends Link {
+  /** Social media platform */
+  platform: string;
+  /** Social media handle or username */
+  handle?: string;
+}
+
+/**
+ * Footer section containing multiple links
+ * This is a simple data structure, not a Content type
+ */
+export interface FooterSection {
+  /** Unique section identifier */
+  id: string;
+  /** Section title */
+  title: string;
+  /** Links in this section */
+  items: Link[];
+  /** Display order */
+  order?: number;
+  /** Whether section is visible */
+  visible?: boolean;
+}

package/src/types/TemplateProvider.ts

@@ -0,0 +1,9 @@
+/**
+ * Pure template resolution provider interface
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export interface TemplateProvider {
+  /** Resolve template with given context using mustache syntax */
+  resolve(template: string, context: any): string;
+}

package/src/types/TemplateResolver.ts

@@ -0,0 +1,26 @@
+import { ICacheProvider, IDataProvider } from "@qwickapps/schema";
+import { TemplateProvider } from "./TemplateProvider";
+
+/**
+ * Configuration for Data Provider orchestrator
+ */
+
+export interface TemplateResolverConfig {
+  /** Data provider for fetching raw data */
+  dataProvider: IDataProvider;
+  /** Template resolver (optional, defaults to MustacheTemplateResolver) */
+  templateResolver?: TemplateProvider;
+  /** Cache provider (optional, defaults to MemoryCacheProvider, false = no cache) */
+  cacheProvider?: ICacheProvider<any[]> | boolean;
+  /** Enable debug logging */
+  enableLogging?: boolean;
+}/**
+ * Content resolver interface
+ * This is now an orchestrator that combines data, template, and cache providers
+ */
+
+export interface ITemplateResolver extends IDataProvider {
+  /** Resolve template string with mustache syntax */
+  resolveTemplate(template: string): Promise<string>;
+}
+

package/src/types/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Centralized Type Definitions for QwickApps React Framework
+ * 
+ * This file consolidates all common types used throughout the framework
+ * to ensure consistency and eliminate duplication.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Standard t-shirt sizing system used across the framework
+ */
+export type TShirtSize = 'tiny' | 'small' | 'medium' | 'large' | 'x-large' | 'huge';
+
+/**
+ * MUI breakpoint values for responsive design
+ */
+export type MUIBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Extended MUI breakpoint names for better readability
+ */
+export type ExtendedBreakpoint = 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large';
+
+/**
+ * Combined breakpoint type supporting all naming conventions
+ */
+export type BreakpointValue = MUIBreakpoint | ExtendedBreakpoint | false;
+
+/**
+ * Height presets commonly used in layout components
+ */
+export type HeightPreset = TShirtSize | 'viewport' | 'auto';
+
+/**
+ * Note: SpacingValue is defined in utils/spacing.ts to avoid circular dependencies
+ */
+
+/**
+ * Dimension values supporting CSS units and t-shirt sizes
+ */
+export type DimensionValue = TShirtSize | MUIBreakpoint | number | 'auto' | 'grow' | string | undefined;
+
+/**
+ * Background variant types for themed components
+ */
+export type BackgroundVariant = 'default' | 'primary' | 'secondary' | 'surface' | 'paper';
+
+/**
+ * Text alignment options
+ */
+export type TextAlignment = 'left' | 'center' | 'right' | 'justify';
+
+/**
+ * Common spacing presets for layout components
+ */
+export type SpacingPreset = 'none' | 'compact' | 'comfortable' | 'spacious';
+
+/**
+ * Component size variants (different from dimension sizes)
+ */
+export type ComponentSize = 'small' | 'medium' | 'large';
+
+/**
+ * Elevation levels for Material-UI components
+ */
+export type ElevationLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 12 | 16 | 24;
+
+/**
+ * Common variant styles for components
+ */
+export type ComponentVariant = 'default' | 'elevated' | 'outlined' | 'filled' | 'text';
+
+/**
+ * Animation durations
+ */
+export type AnimationDuration = 'fast' | 'medium' | 'slow' | number;
+
+/**
+ * Grid span values for layout systems
+ */
+export type GridSpan = number | 'auto' | 'grow';
+
+/**
+ * Color intensity levels
+ */
+export type ColorIntensity = 'light' | 'main' | 'dark';
+
+/**
+ * Common loading states
+ */
+export type LoadingState = 'idle' | 'loading' | 'success' | 'error';
+
+// Export all content-related types
+export * from './CacheProvider';
+export * from './ContentProxy';
+export * from './DataTypes';
+export * from './TemplateProvider';
+export * from './TemplateResolver';

package/src/utils/__tests__/createDataDrivenComponent.test.tsx.disabled

@@ -0,0 +1,193 @@
+/**
+ * Tests for createDataDrivenComponent factory
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { createDataDrivenComponent } from '../createDataDrivenComponent';
+import { DataProvider } from '../../contexts/DataContext';
+import { JsonDataProvider } from '../../providers/JsonDataProvider';
+
+// Simple test component
+interface TestProps {
+  html?: string;
+  placeholder?: string;
+  testProp?: string;
+}
+
+const BaseTestComponent: React.FC<TestProps> = ({ html, placeholder, testProp, ...otherProps }) => (
+  <div data-testid="base-component" {...otherProps}>
+    <div data-testid="html">{html}</div>
+    <div data-testid="placeholder">{placeholder}</div>
+    <div data-testid="test-prop">{testProp}</div>
+  </div>
+);
+
+describe('createDataDrivenComponent', () => {
+  const testData = {
+    'company.description': [
+      {
+        html: '<p>QwickApps React Framework</p>',
+        placeholder: 'Loading...',
+        testProp: 'data-driven-value'
+      }
+    ]
+  };
+
+  const dataProvider = new JsonDataProvider(testData);
+
+  it('should create a component that works without dataSource', () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const { getByTestId } = render(
+      <DataDrivenTest html="<p>Direct prop</p>" placeholder="Direct placeholder" testProp="direct-value" />
+    );
+
+    expect(getByTestId('html')).toHaveTextContent('Direct prop');
+    expect(getByTestId('placeholder')).toHaveTextContent('Direct placeholder');
+    expect(getByTestId('test-prop')).toHaveTextContent('direct-value');
+  });
+
+  it('should resolve props from dataSource when provided', async () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const { getByTestId } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest dataSource="company.description" />
+      </DataProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('html')).toHaveTextContent('QwickApps React Framework');
+      expect(getByTestId('placeholder')).toHaveTextContent('Loading...');
+      expect(getByTestId('test-prop')).toHaveTextContent('data-driven-value');
+    });
+  });
+
+  it('should merge dataSource props with direct props', async () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const { getByTestId } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest 
+          dataSource="company.description" 
+          testProp="override-value" // This should be overridden by dataSource
+          placeholder="direct-placeholder" // This should be overridden by dataSource
+        />
+      </DataProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('html')).toHaveTextContent('QwickApps React Framework');
+      // dataSource should override direct props
+      expect(getByTestId('placeholder')).toHaveTextContent('Loading...');
+      expect(getByTestId('test-prop')).toHaveTextContent('data-driven-value');
+    });
+  });
+
+  it('should add data attributes to the component', async () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const { getByTestId } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest dataSource="company.description" />
+      </DataProvider>
+    );
+
+    await waitFor(() => {
+      const component = getByTestId('base-component');
+      expect(component).toHaveAttribute('data-component', 'SafeSpan');
+      expect(component).toHaveAttribute('data-data-source', 'company.description');
+      expect(component).toHaveAttribute('data-cached', 'false');
+    });
+  });
+
+  it('should show loading state when data is loading', () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const { getByText } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest dataSource="nonexistent.data" />
+      </DataProvider>
+    );
+
+    // Should show loading initially
+    expect(getByText('Loading SafeSpan...')).toBeInTheDocument();
+  });
+
+  it('should handle fallback options', async () => {
+    const DataDrivenTest = createDataDrivenComponent(
+      BaseTestComponent, 
+      undefined,
+      {
+        fallback: {
+          html: '<p>Fallback content</p>',
+          placeholder: 'Fallback placeholder'
+        }
+      }
+    );
+
+    const { getByTestId } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest dataSource="nonexistent.data" />
+      </DataProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('html')).toHaveTextContent('Fallback content');
+      expect(getByTestId('placeholder')).toHaveTextContent('Fallback placeholder');
+    });
+  });
+
+  it('should support custom binding options per component instance', async () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+
+    const customOptions = {
+      fallback: {
+        html: '<p>Custom fallback</p>',
+        placeholder: 'Custom placeholder'
+      },
+      strict: true
+    };
+
+    const { getByTestId } = render(
+      <DataProvider dataSource={dataProvider}>
+        <DataDrivenTest 
+          dataSource="nonexistent.data" 
+          bindingOptions={customOptions}
+        />
+      </DataProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('html')).toHaveTextContent('Custom fallback');
+      expect(getByTestId('placeholder')).toHaveTextContent('Custom placeholder');
+    });
+  });
+
+  it('should set correct display name', () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+    expect(DataDrivenTest.displayName).toBe('DataDriven(BaseTestComponent)');
+  });
+
+  it('should attach schema to the component', () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+    expect((DataDrivenTest as any).schema).toBe(undefined);
+  });
+
+  it('should forward refs correctly', () => {
+    const DataDrivenTest = createDataDrivenComponent(BaseTestComponent, undefined);
+    const ref = React.createRef<HTMLDivElement>();
+
+    render(
+      <DataDrivenTest 
+        ref={ref}
+        html="<p>Test content</p>" 
+      />
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+  });
+});