@qwickapps/react-framework 1.3.0

package/src/hooks/useBaseProps.ts

@@ -0,0 +1,267 @@
+/**
+ * Base props hook for QwickApps React Framework components
+ * 
+ * Provides standardized prop handling for all framework components
+ * including grid behavior, dimensions, spacing, and styling
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { useMemo } from 'react';
+import { SxProps, Theme } from '@mui/material';
+import { DimensionValue, resolveDimensions } from '../utils/dimensions';
+import { SpacingValue, resolveSpacingProps } from '../utils/spacing';
+
+/**
+ * Base props that all QwickApps components support
+ */
+export interface BaseComponentProps {
+  // Grid behavior - when used inside ColumnLayout
+  span?: number | 'auto' | 'grow';
+  xs?: number | 'auto';
+  sm?: number | 'auto';
+  md?: number | 'auto';
+  lg?: number | 'auto';
+  xl?: number | 'auto';
+  
+  // Common styling
+  className?: string;
+  sx?: SxProps<Theme>;
+  style?: React.CSSProperties;
+  
+  // Dimensions with t-shirt sizing
+  width?: DimensionValue;
+  height?: DimensionValue;
+  minWidth?: DimensionValue;
+  minHeight?: DimensionValue;
+  maxWidth?: DimensionValue;
+  maxHeight?: DimensionValue;
+  
+  // Spacing with t-shirt sizing
+  padding?: SpacingValue;
+  paddingTop?: SpacingValue;
+  paddingRight?: SpacingValue;
+  paddingBottom?: SpacingValue;
+  paddingLeft?: SpacingValue;
+  paddingX?: SpacingValue;
+  paddingY?: SpacingValue;
+  margin?: SpacingValue;
+  marginTop?: SpacingValue;
+  marginRight?: SpacingValue;
+  marginBottom?: SpacingValue;
+  marginLeft?: SpacingValue;
+  marginX?: SpacingValue;
+  marginY?: SpacingValue;
+  
+  // Background
+  background?: string; // color, gradient, or theme path
+  backgroundImage?: string;
+  backgroundGradient?: string;
+  
+  // Text alignment
+  textAlign?: 'left' | 'center' | 'right' | 'justify';
+  
+  // Common HTML attributes
+  id?: string;
+  role?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  'data-testid'?: string;
+  
+  // Common event handlers (generic for compatibility)
+  onClick?: React.MouseEventHandler<any>;
+  onMouseEnter?: React.MouseEventHandler<any>;
+  onMouseLeave?: React.MouseEventHandler<any>;
+  onFocus?: React.FocusEventHandler<any>;
+  onBlur?: React.FocusEventHandler<any>;
+}
+
+/**
+ * Marker to identify QwickApps components
+ */
+export const QWICKAPP_COMPONENT = Symbol('QwickAppComponent');
+
+/**
+ * Hook to process base component props
+ */
+export function useBaseProps<T extends BaseComponentProps>(props: T) {
+  const {
+    // Grid props
+    span,
+    xs,
+    sm,
+    md,
+    lg,
+    xl,
+    
+    // Style props
+    className,
+    sx,
+    style,
+    
+    // Dimension props
+    width,
+    height,
+    minWidth,
+    minHeight,
+    maxWidth,
+    maxHeight,
+    
+    // Spacing props
+    padding,
+    paddingTop,
+    paddingRight,
+    paddingBottom,
+    paddingLeft,
+    paddingX,
+    paddingY,
+    margin,
+    marginTop,
+    marginRight,
+    marginBottom,
+    marginLeft,
+    marginX,
+    marginY,
+    
+    // Background props
+    background,
+    backgroundImage,
+    backgroundGradient,
+    
+    // Text alignment
+    textAlign,
+    
+    // HTML attributes
+    id,
+    role,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
+    'data-testid': dataTestId,
+    
+    // Event handlers
+    onClick,
+    onMouseEnter,
+    onMouseLeave,
+    onFocus,
+    onBlur,
+    
+    // Rest of the props
+    ...restProps
+  } = props;
+
+  // Memoize grid props
+  const gridProps = useMemo(() => {
+    if (span || xs || sm || md || lg || xl) {
+      return {
+        span,
+        xs: span || xs,
+        sm: span || sm,
+        md: span || md,
+        lg: span || lg,
+        xl: span || xl,
+      };
+    }
+    return null;
+  }, [span, xs, sm, md, lg, xl]);
+
+  // Memoize resolved dimensions
+  const dimensions = useMemo(() => {
+    return resolveDimensions({
+      width,
+      height,
+      minWidth,
+      minHeight,
+      maxWidth,
+      maxHeight,
+    });
+  }, [width, height, minWidth, minHeight, maxWidth, maxHeight]);
+
+  // Memoize resolved spacing
+  const spacing = useMemo(() => {
+    return resolveSpacingProps({
+      padding,
+      paddingTop,
+      paddingRight,
+      paddingBottom,
+      paddingLeft,
+      paddingX,
+      paddingY,
+      margin,
+      marginTop,
+      marginRight,
+      marginBottom,
+      marginLeft,
+      marginX,
+      marginY,
+    });
+  }, [
+    padding, paddingTop, paddingRight, paddingBottom, paddingLeft, paddingX, paddingY,
+    margin, marginTop, marginRight, marginBottom, marginLeft, marginX, marginY
+  ]);
+
+  // Memoize background and text styles
+  const backgroundAndTextStyles = useMemo(() => {
+    const styles: any = {};
+    
+    if (backgroundGradient) {
+      styles.background = backgroundGradient;
+    } else if (backgroundImage) {
+      styles.backgroundImage = `url(${backgroundImage})`;
+      styles.backgroundSize = 'cover';
+      styles.backgroundPosition = 'center';
+      styles.backgroundRepeat = 'no-repeat';
+    } else if (background) {
+      // Could be a color or theme path
+      styles.background = background;
+    }
+    
+    if (textAlign) {
+      styles.textAlign = textAlign;
+    }
+    
+    return styles;
+  }, [background, backgroundImage, backgroundGradient, textAlign]);
+
+  // Combine all style props
+  const combinedSx = useMemo(() => {
+    return {
+      ...dimensions,
+      ...spacing,
+      ...backgroundAndTextStyles,
+      ...sx,
+    };
+  }, [dimensions, spacing, backgroundAndTextStyles, sx]);
+
+  // HTML attributes and event handlers
+  const htmlProps = {
+    id,
+    role,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
+    'data-testid': dataTestId,
+    onClick,
+    onMouseEnter,
+    onMouseLeave,
+    onFocus,
+    onBlur,
+  };
+
+  return {
+    gridProps,
+    styleProps: {
+      className,
+      sx: combinedSx,
+      style,
+    },
+    htmlProps,
+    restProps: restProps as Omit<T, keyof BaseComponentProps>,
+  };
+}
+
+/**
+ * Type helper for components using base props
+ */
+export type WithBaseProps<P = {}> = P & BaseComponentProps;

package/src/hooks/useDataBinding.ts

@@ -0,0 +1,77 @@
+/**
+ * Data Binding Hook for AI-Driven Component System
+ * 
+ * This hook enables components to resolve props from CMS data sources
+ * instead of hardcoded props, allowing AI agents to generate both
+ * content and presentation dynamically.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { DataBindingMeta, DataBindingOptions, Model, SchemaDefinition } from '@qwickapps/schema';
+import { useMemo } from 'react';
+import { useDataSafe } from '../contexts/DataContext';
+
+/**
+ * Hook for resolving component props from data sources
+ * 
+ * @param dataSource - Data source identifier (e.g., "company.description", "pages.home.hero-block")
+ * @param fallbackProps - Props to use when dataSource is unavailable
+ * @param schema - Component schema for validation
+ * @param options - Data binding configuration options
+ * @returns Resolved props with data binding metadata
+ */
+export function useDataBinding<T extends Model>(
+  dataSource?: string,
+  fallbackProps?: Partial<T>,
+  schema?: SchemaDefinition,
+  options?: DataBindingOptions
+): T & DataBindingMeta {
+  // Determine if we should use data binding
+  const isDataSourceAvailable = dataSource && dataSource.trim().length > 0;
+
+  // Get data if dataSource is provided
+  const safeDataResult = isDataSourceAvailable ? useDataSafe(dataSource) : { data: undefined, loading: false, error: null };
+
+  // Resolve the final props
+  const resolvedData = useMemo(() => {
+    if (!isDataSourceAvailable || safeDataResult.data === undefined) {
+      // No data source provided, use fallback props as-is
+      return fallbackProps || ({} as Partial<T>);
+    }
+
+    const resolved = {
+      ...(fallbackProps || {}),
+      ...safeDataResult.data
+    } as Partial<T>;
+
+    return resolved;
+
+  }, [isDataSourceAvailable, safeDataResult.data, fallbackProps, schema, options]);
+
+  // Build the data binding metadata
+  const metadata: DataBindingMeta = {
+    loading: safeDataResult.loading,
+    error: safeDataResult.error,
+    dataSource,
+    cached: false // TODO: Implement cache detection
+  };
+
+  // Return resolved data with metadata, ensuring data properties aren't overridden
+  return {
+    ...resolvedData,
+    // Metadata with explicit property names to avoid conflicts with data
+    $loading: safeDataResult.loading,
+    $error: safeDataResult.error,
+    $dataSource: dataSource,
+    $cached: false,
+    // Keep old names for backward compatibility, but data takes precedence
+    ...(resolvedData.hasOwnProperty('loading') ? {} : { loading: safeDataResult.loading }),
+    ...(resolvedData.hasOwnProperty('error') ? {} : { error: safeDataResult.error }),
+    cached: false
+  } as any;
+}
+
+// Old validation function removed - using new schema system
+
+export default useDataBinding;

package/src/index.ts

@@ -0,0 +1,23 @@
+// QwickApps React Framework
+// Main export file for the QwickApps React Framework
+
+// Components
+export * from './components';
+
+// Contexts (includes DataProvider)
+export * from './contexts';
+
+// Hooks
+export * from './hooks';
+
+// Palette Configurations
+export * from './palettes';
+
+// Utilities
+export * from './utils';
+
+// Types (includes ContentTypes)
+export * from './types';
+
+// Schemas (includes component schemas and builders)
+export * from './schemas';

package/src/palettes/PaletteAutumn.css

@@ -0,0 +1,172 @@
+/**
+ * Autumn Color Palette
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ * 
+ * Warm oranges, golden yellows, and earthy browns - inspired by fall foliage
+ */
+
+/* ===== AUTUMN PALETTE - LIGHT THEME ===== */
+html[data-palette="autumn"]:not([data-theme="dark"]), 
+html[data-palette="autumn"][data-theme="light"] {
+  /* Primary palette - Burnt orange */
+  --palette-primary-main: #ea580c;
+  --palette-primary-light: #fb923c;
+  --palette-primary-dark: #c2410c;
+  --palette-on-primary: #ffffff;
+
+  /* Secondary palette - Rich amber */
+  --palette-secondary-main: #b45309;
+  --palette-secondary-light: #d97706;
+  --palette-secondary-dark: #92400e;
+  --palette-on-secondary: #ffffff;
+
+  /* Surface palette - Cream */
+  --palette-surface-main: #fffbeb;
+  --palette-surface-variant: #fef3c7;
+  --palette-surface-elevated: #ffffff;
+  --palette-on-surface: #451a03;
+
+  /* Background palette - Warm ivory */
+  --palette-background-main: #fefce8;
+  --palette-background-dark: #fef3c7;
+  --palette-background-overlay: rgba(254, 252, 232, 0.95);
+  --palette-on-background: #78350f;
+
+  /* Header background with transparency */
+  --palette-header-bg-start: rgba(254, 252, 232, 0.98);
+  --palette-header-bg-end: rgba(254, 252, 232, 0.95);
+  --palette-header-collapsed-bg-start: rgba(254, 252, 232, 0.99);
+  --palette-header-collapsed-bg-end: rgba(254, 252, 232, 0.96);
+  
+  /* Text palette - Rich brown */
+  --palette-text-primary: #451a03;
+  --palette-text-secondary: #78350f;
+  --palette-text-disabled: rgba(69, 26, 3, 0.38);
+  --palette-text-inverted: #ffffff;
+  
+  /* Border palette - Tan */
+  --palette-border-main: #d4d4aa;
+  --palette-border-light: rgba(69, 26, 3, 0.12);
+  --palette-border-lighter: rgba(69, 26, 3, 0.05);
+  --palette-border-medium: #a8a29e;
+  
+  /* Success palette - Forest green */
+  --palette-success-main: #16a34a;
+  --palette-success-light: #dcfce7;
+  --palette-success-dark: #14532d;
+  --palette-success-border: #bbf7d0;
+  
+  /* Error palette - Crimson */
+  --palette-error-main: #dc2626;
+  --palette-error-light: #fee2e2;
+  --palette-error-dark: #7f1d1d;
+  --palette-error-border: #fecaca;
+  
+  /* Warning palette - Amber */
+  --palette-warning-main: #f59e0b;
+  --palette-warning-light: #fef3c7;
+  --palette-warning-dark: #78350f;
+  --palette-warning-border: #fde68a;
+  
+  /* Info palette - Teal */
+  --palette-info-main: #0891b2;
+  --palette-info-light: #e6fffa;
+  --palette-info-dark: #164e63;
+  --palette-on-info: #ffffff;
+  --palette-info-border: #67e8f9;
+  
+  /* Accent palette - Deep crimson */
+  --palette-accent-main: #dc2626;
+  --palette-accent-light: #f87171;
+  --palette-accent-dark: #991b1b;
+  --palette-on-accent: #ffffff;
+
+  /* Control palette - Walnut */
+  --palette-control-main: #451a03;
+  --palette-control-light: #78350f;
+  --palette-control-text: #fef3c7;
+  --palette-control-border: #92400e;
+}
+
+/* ===== AUTUMN PALETTE - DARK THEME ===== */
+html[data-palette="autumn"][data-theme="dark"] {
+  /* Primary palette - Glowing ember */
+  --palette-primary-main: #fb923c;
+  --palette-primary-light: #fdba74;
+  --palette-primary-dark: #ea580c;
+  --palette-on-primary: #1c1917;
+
+  /* Secondary palette - Golden glow */
+  --palette-secondary-main: #fbbf24;
+  --palette-secondary-light: #fcd34d;
+  --palette-secondary-dark: #f59e0b;
+  --palette-on-secondary: #1c1917;
+
+  /* Surface palette - Dark wood */
+  --palette-surface-main: #1c1917;
+  --palette-surface-variant: #292524;
+  --palette-surface-elevated: #44403c;
+  --palette-on-surface: #fef3c7;
+
+  /* Background palette - Deep earth */
+  --palette-background-main: #0c0a09;
+  --palette-background-dark: #1c1917;
+  --palette-background-overlay: rgba(28, 25, 23, 0.95);
+  --palette-on-background: #d6d3d1;
+
+  /* Header background with transparency */
+  --palette-header-bg-start: rgba(12, 10, 9, 0.98);
+  --palette-header-bg-end: rgba(12, 10, 9, 0.95);
+  --palette-header-collapsed-bg-start: rgba(12, 10, 9, 0.99);
+  --palette-header-collapsed-bg-end: rgba(12, 10, 9, 0.96);
+  
+  /* Text palette - Warm light */
+  --palette-text-primary: #fef3c7;
+  --palette-text-secondary: #d6d3d1;
+  --palette-text-disabled: rgba(254, 243, 199, 0.38);
+  --palette-text-inverted: #0c0a09;
+  
+  /* Border palette - Copper */
+  --palette-border-main: #78716c;
+  --palette-border-light: rgba(254, 243, 199, 0.12);
+  --palette-border-lighter: rgba(254, 243, 199, 0.05);
+  --palette-border-medium: #57534e;
+  
+  /* Success palette - Pine */
+  --palette-success-main: #4ade80;
+  --palette-success-light: #14532d;
+  --palette-success-dark: #22c55e;
+  --palette-success-border: #166534;
+  
+  /* Error palette - Fire */
+  --palette-error-main: #f87171;
+  --palette-error-light: #7f1d1d;
+  --palette-error-dark: #ef4444;
+  --palette-error-border: #991b1b;
+  
+  /* Warning palette - Harvest gold */
+  --palette-warning-main: #eab308;
+  --palette-warning-light: #78350f;
+  --palette-warning-dark: #ca8a04;
+  --palette-warning-border: #a16207;
+  
+  /* Info palette - River teal */
+  --palette-info-main: #22d3ee;
+  --palette-info-light: #164e63;
+  --palette-info-dark: #06b6d4;
+  --palette-on-info: #0c0a09;
+  --palette-info-border: #0891b2;
+  
+  /* Accent palette - Harvest crimson */
+  --palette-accent-main: #b91c1c;
+  --palette-accent-light: #dc2626;
+  --palette-accent-dark: #7f1d1d;
+  --palette-on-accent: #fef3c7;
+
+  /* Control palette - Charcoal */
+  --palette-control-main: #292524;
+  --palette-control-light: #44403c;
+  --palette-control-text: #f5f5f4;
+  --palette-control-border: #57534e;
+}

package/src/palettes/PaletteAutumn.ts

@@ -0,0 +1,16 @@
+/**
+ * Autumn Palette Configuration
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import "./PaletteAutumn.css";
+import type { PaletteConfig } from '../contexts/PaletteContext';
+
+export const PaletteAutumn: PaletteConfig = {
+  id: 'autumn',
+  name: 'Autumn',
+  description: 'Warm oranges and golden yellows',
+  primaryColor: '#ea580c',
+};
+
+export default PaletteAutumn;