@qwickapps/react-framework 1.3.0

package/src/components/pages/Page.tsx

@@ -0,0 +1,345 @@
+/**
+ * Page Component - Main content wrapper for application pages
+ * 
+ * The Page component is what developers primarily focus on when building applications.
+ * It provides:
+ * - Automatic page title management
+ * - Route-based configuration
+ * - Contextual menu items that appear in navigation
+ * - Proper content spacing and layout
+ * - SEO and accessibility features
+ * 
+ * Page components automatically integrate with the AppScaffold to provide
+ * contextual actions and menu items specific to the current page.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useContext, createContext, useCallback } from 'react';
+import './Page.css';
+import { useSafeLocation } from '../../utils/reactUtils';
+
+export interface PageContextValue {
+  /** Current page route/path */
+  route?: string;
+}
+
+// Create context for page-level state
+const PageContext = createContext<PageContextValue>({});
+
+export const usePageContext = (): PageContextValue => {
+  const context = useContext(PageContext);
+  if (!context) {
+    throw new Error('usePageContext must be used within a PageProvider or Page component');
+  }
+  return context;
+};
+
+export type MessageType = 'loading' | 'error' | 'warning' | 'success' | 'info';
+
+export type LoadingType = 'spinner' | 'bar-top' | 'bar-bottom' | 'dots' | 'custom';
+
+export interface MessageState {
+  /** Type of message to display */
+  type: MessageType;
+  /** Message content (string or custom JSX) */
+  content?: string | React.ReactNode;
+  /** Custom component to render instead of default */
+  customComponent?: React.ReactNode;
+}
+
+export interface LoadingState {
+  /** Type of loading indicator */
+  type?: LoadingType;
+  /** Loading message */
+  message?: string;
+  /** Custom loading component */
+  customComponent?: React.ReactNode;
+}
+
+export interface PageProps {
+  /** Page content */
+  children: React.ReactNode;
+  /** Current route/path for this page */
+  route?: string;
+  /** Optional header component */
+  header?: React.ReactNode;
+  /** Optional footer component */
+  footer?: React.ReactNode;
+  /** Additional CSS class */
+  className?: string;
+  /** Page layout variant */
+  variant?: 'default' | 'centered' | 'narrow' | 'wide' | 'fullwidth';
+  /** Padding around page content */
+  padding?: 'none' | 'small' | 'medium' | 'large';
+  /** Background variant */
+  background?: 'default' | 'surface' | 'alternate';
+  /** Maximum width for content */
+  maxWidth?: 'small' | 'medium' | 'large' | 'extra-large' | 'none';
+  /** Loading state configuration */
+  loading?: boolean | LoadingState;
+  /** Message state for displaying info/warning/error/success messages */
+  message?: MessageState;
+}
+
+const Page: React.FC<PageProps> = ({
+  children,
+  route,
+  header,
+  footer,
+  className = '',
+  variant = 'default',
+  padding = 'medium',
+  background = 'default',
+  maxWidth = 'large',
+  loading = false,
+  message,
+}) => {
+  // Auto-detect current route if available
+  const location = useSafeLocation();
+  const actualRoute = route || location?.pathname || '';
+
+  // SCROLL HANDLING COMMENTED OUT FOR STABILITY
+  // Handle scroll for title shrinking
+  // useEffect(() => {
+  //   if (!shrinkTitleOnScroll || !pageContentRef.current) return;
+  //   
+  //   const handleScroll = () => {
+  //     if (pageContentRef.current) {
+  //       const scrollTop = pageContentRef.current.scrollTop;
+  //       const shouldCollapse = scrollTop > scrollThreshold;
+  //       setIsTitleCollapsed(shouldCollapse);
+  //     }
+  //   };
+  //
+  //   const pageElement = pageContentRef.current;
+  //   if (pageElement) {
+  //     pageElement.addEventListener('scroll', handleScroll);
+  //     return () => pageElement.removeEventListener('scroll', handleScroll);
+  //   }
+  // }, [shrinkTitleOnScroll, scrollThreshold]);
+
+  // Memoized context value
+  const contextValue = React.useMemo<PageContextValue>(() => ({
+    route: actualRoute,
+  }), [actualRoute]);
+
+  // Generate class names
+  const pageClasses = [
+    'page',
+    `page-variant-${variant}`,
+    `page-padding-${padding}`,
+    `page-background-${background}`,
+    `page-max-width-${maxWidth}`,
+    className,
+  ].filter(Boolean).join(' ');
+
+  // Render loading indicator
+  const renderLoading = (loadingState: boolean | LoadingState) => {
+    if (loadingState === false) return null;
+    
+    // Handle simple boolean loading
+    if (loadingState === true) {
+      return (
+        <div className="page-loading">
+          <div className="loading-spinner" aria-label="Loading content">
+            <div className="spinner"></div>
+          </div>
+        </div>
+      );
+    }
+    
+    // Handle custom loading state
+    const { type = 'spinner', message, customComponent } = loadingState;
+    
+    if (customComponent) {
+      return <div className="page-loading">{customComponent}</div>;
+    }
+    
+    switch (type) {
+      case 'bar-top':
+        return (
+          <div className="page-loading-bar page-loading-bar-top">
+            <div className="loading-bar-progress"></div>
+            {message && <div className="loading-message">{message}</div>}
+          </div>
+        );
+      case 'bar-bottom':
+        return (
+          <div className="page-loading-bar page-loading-bar-bottom">
+            <div className="loading-bar-progress"></div>
+            {message && <div className="loading-message">{message}</div>}
+          </div>
+        );
+      case 'dots':
+        return (
+          <div className="page-loading page-loading-dots">
+            <div className="loading-dots" aria-label="Loading content">
+              <span></span><span></span><span></span>
+            </div>
+            {message && <div className="loading-message">{message}</div>}
+          </div>
+        );
+      case 'spinner':
+      default:
+        return (
+          <div className="page-loading">
+            <div className="loading-spinner" aria-label="Loading content">
+              <div className="spinner"></div>
+            </div>
+            {message && <div className="loading-message">{message}</div>}
+          </div>
+        );
+    }
+  };
+
+  // Render message (error/warning/success/info)
+  const renderMessage = (messageState: MessageState) => {
+    const { type, content, customComponent } = messageState;
+    
+    if (customComponent) {
+      return <div className={`page-message page-message-${type}`}>{customComponent}</div>;
+    }
+    
+    const icons = {
+      error: '⚠️',
+      warning: '⚠️',
+      success: '✅',
+      info: 'ℹ️',
+      loading: '⏳'
+    };
+    
+    return (
+      <div className={`page-message page-message-${type}`}>
+        <div className="message-icon" aria-hidden="true">{icons[type]}</div>
+        <div className="message-content">
+          {typeof content === 'string' ? <p>{content}</p> : content}
+        </div>
+      </div>
+    );
+  };
+
+  // Handle loading state
+  if (loading) {
+    return (
+      <PageContext.Provider value={contextValue}>
+        <div className={pageClasses}>
+          {renderLoading(loading)}
+        </div>
+      </PageContext.Provider>
+    );
+  }
+
+  return (
+    <PageContext.Provider value={contextValue}>
+      <div className={pageClasses}>
+        {/* Optional Header */}
+        {header && (
+          <div className="page-header">
+            {header}
+          </div>
+        )}
+
+        {/* Message state (error/warning/success/info) */}
+        {message && renderMessage(message)}
+
+        {/* Page Content */}
+        <div className="page-content">
+          {children}
+        </div>
+
+        {/* Optional Footer */}
+        {footer && (
+          <div className="page-footer">
+            {footer}
+          </div>
+        )}
+      </div>
+    </PageContext.Provider>
+  );
+};
+
+// Utility hook for updating page configuration from within page components
+export const usePage = () => {
+  const context = usePageContext();
+  
+  return {
+    ...context,
+    // Helper method for setting page title
+    setTitle: useCallback((newTitle: string) => {
+      document.title = newTitle;
+    }, []),
+  };
+};
+
+/**
+ * Base Page Class Component - Extendable page component for inheritance pattern
+ * 
+ * Usage:
+ * class MyPage extends BasePage {
+ *   getPageProps() {
+ *     return {
+ *       route: '/my-page',
+ *       variant: 'narrow',
+ *       padding: 'large',
+ *       // ... other page props
+ *     };
+ *   }
+ * 
+ *   renderContent() {
+ *     return (
+ *       <div>My page content</div>
+ *     );
+ *   }
+ * }
+ */
+export abstract class BasePage<P = {}, S = {}> extends React.Component<P, S> {
+  /**
+   * Override this method to provide page configuration
+   * This will be passed to the Page component wrapper
+   */
+  abstract getPageProps(): Partial<PageProps>;
+
+  /**
+   * Override this method to provide the page content
+   * This replaces the render() method in your page components
+   */
+  abstract renderContent(): React.ReactNode;
+
+  /**
+   * Override this method to handle page mounting logic
+   * Called after the page is mounted and context is available
+   */
+  onPageMount?(): void;
+
+  /**
+   * Override this method to handle page unmounting logic
+   */
+  onPageUnmount?(): void;
+
+  /**
+   * Internal render method - wraps content in Page component
+   */
+  render() {
+    const pageProps = this.getPageProps();
+    
+    return (
+      <Page {...pageProps}>
+        {this.renderContent()}
+      </Page>
+    );
+  }
+
+  /**
+   * Component lifecycle methods
+   */
+  componentDidMount() {
+    this.onPageMount?.();
+  }
+
+  componentWillUnmount() {
+    this.onPageUnmount?.();
+  }
+}
+
+export default Page;

package/src/components/pages/index.ts

@@ -0,0 +1,11 @@
+/**
+ * All page components available in QwickApps React Framework.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export { BasePage } from './Page';
+export { default as FormPage } from './FormPage';
+export { default as Page } from './Page';
+
+export type { FormPageProps } from './FormPage';
+export type { PageProps } from './Page';

package/src/contexts/DataContext.tsx

@@ -0,0 +1,355 @@
+/**
+ * DataContext - React Context for Data Provider
+ * 
+ * Provides data templating capabilities throughout the React component tree
+ * via React Context API. Supports mustache template resolution and caching.
+ * Enables JSX components to use mustache syntax to reference named data elements.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { createContext, useContext, useEffect, useState, ReactNode } from 'react';
+import { ITemplateResolver, TemplateResolverConfig } from '../types';
+import { TemplateResolver } from '../templates';
+import { Model } from '@qwickapps/schema';
+
+/**
+ * Data Context interface
+ */
+interface DataContextValue {
+  provider: ITemplateResolver | null;
+  get<T extends Model>(slug: string): Promise<T | undefined>;
+  select<T extends Model>(schema: string, options?: any): Promise<T[]>;
+  resolveTemplate(template: string): Promise<string>;
+}
+
+/**
+ * React Context for data provider
+ */
+const DataContext = createContext<DataContextValue | null>(null);
+
+/**
+ * Props for DataProvider component
+ */
+export interface DataProviderProps {
+  /** The data source configuration (follows new SRP architecture) */
+  dataSource: TemplateResolverConfig;
+  /** Child components that will have access to data templating */
+  children: ReactNode;
+}
+
+/**
+ * DataProvider component that wraps children with data templating capabilities
+ * 
+ * Enables JSX components to use mustache syntax for data interpolation:
+ * - {t`Welcome {{company.name}}!`} 
+ * - {useData('users')} for data fetching
+ * - Template resolution with caching support
+ * 
+ * Usage (new SRP architecture):
+ * ```tsx
+ * <DataProvider dataSource={{
+ *   dataProvider: new JsonDataProvider({ data: { ... } }),
+ *   cache: true,
+ *   templateResolver: new MustacheTemplateResolver()
+ * }}>
+ *   <MyComponent /> // Can use useData() hooks and t`` templates
+ * </DataProvider>
+ * ```
+ */
+export function DataProvider({ dataSource, children }: DataProviderProps) {
+  // Create TemplateResolver internally
+  const dataProvider = new TemplateResolver(dataSource);
+  
+  const contextValue: DataContextValue = {
+    provider: dataProvider,
+    get: async <T extends Model>(slug: string): Promise<T | undefined> => {
+      const result = await dataProvider.get(slug);
+      return result && result.data ? (result.data as T) : undefined;
+    },
+    select: async <T extends Model>(schema: string, options?: any): Promise<T[]> => {
+      const result = await dataProvider.select(schema, options);
+      return result && Array.isArray(result.data) ? (result.data as T[]) : [];
+    },
+    resolveTemplate: (template: string) => dataProvider.resolveTemplate(template)
+  };
+
+  return (
+    <DataContext.Provider value={contextValue}>
+      {children}
+    </DataContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the data context
+ * 
+ * @throws Error if used outside of DataProvider
+ */
+export function useDataContext(): DataContextValue {
+  const context = useContext(DataContext);
+  if (!context) {
+    throw new Error('useDataContext must be used within a DataProvider. Did you wrap your component with <DataProvider>?');
+  }
+  return context;
+}
+
+/**
+ * Hook to get data by unique slug (safe version that doesn't throw)
+ * 
+ * @param slug - The unique slug to fetch data for
+ * @returns Data with loading state information
+ */
+export function useDataSafe<T extends Model>(slug: string): {
+  data: T | undefined;
+  loading: boolean;
+  error: Error | null;
+} {
+  const context = useContext(DataContext);
+  if (!context) {
+    return { data: undefined, loading: false, error: null };
+  }
+
+  const [data, setData] = useState<T | undefined>(undefined);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchData = async () => {
+    if (!slug) {
+      setLoading(false);
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError(null);
+      const result = await context.get<T>(slug);
+      setData(result);
+      setLoading(false);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+  }, [slug]);
+
+  return { data, loading, error };
+}
+
+/**
+ * Hook to get data by field group ID
+ * 
+ * @param fieldGroupId - The field group to fetch
+ * @returns Data and loading state
+ */
+export function useData<T extends Model>(fieldGroupId: string): {
+  data: T | undefined;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const { get } = useDataContext();
+  const [data, setData] = useState<T | undefined>(undefined);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchData = async () => {
+    if (!fieldGroupId) {
+      setLoading(false);
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError(null);
+      const result = await get<T>(fieldGroupId);
+      setData(result ? result : undefined);
+      setLoading(false);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+  }, [fieldGroupId, get]);
+
+  return { 
+    data, 
+    loading, 
+    error, 
+    refetch: fetchData
+  };
+}
+
+/**
+ * Hook to resolve a template string with mustache syntax
+ * 
+ * @param template - Template string with {{fieldGroup.property}} syntax
+ * @returns Resolved template string and loading state
+ */
+export function useResolveTemplate(template: string) {
+  const { resolveTemplate } = useDataContext();
+  const [resolved, setResolved] = useState(template);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    async function resolve() {
+      if (!template || !template.includes('{{')) {
+        setResolved(template);
+        return;
+      }
+
+      try {
+        setLoading(true);
+        setError(null);
+        const result = await resolveTemplate(template);
+        
+        if (isMounted) {
+          setResolved(result);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (isMounted) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setResolved(template); // Fallback to original template
+          setLoading(false);
+        }
+      }
+    }
+
+    resolve();
+
+    return () => {
+      isMounted = false;
+    };
+  }, [template, resolveTemplate]);
+
+  return { resolved, loading, error };
+}
+
+/**
+ * Hook to access data provider directly for advanced use cases
+ */
+export function useDataProvider(): ITemplateResolver {
+  const { provider } = useDataContext();
+  if (!provider) {
+    throw new Error('Data provider not available');
+  }
+  return provider;
+}
+
+/**
+ * Template component for inline template resolution
+ * 
+ * This is a React-friendly component for template resolution
+ * that works well with conditional rendering and fallbacks.
+ * 
+ * Usage:
+ * ```tsx
+ * <T template="Welcome to {{company.name}}!" fallback="Loading..." />
+ * <T template="Hello {{user.name}}" fallback="Guest" />
+ * ```
+ */
+export const T: React.FC<{ template: string; fallback?: ReactNode; wrapper?: React.ComponentType<{ children: ReactNode }> }> = ({ 
+  template, 
+  fallback,
+  wrapper: Wrapper 
+}) => {
+  try {
+    const context = useContext(DataContext);
+    if (!context) {
+      throw new Error('T component must be used within a DataProvider. Did you wrap your component with <DataProvider>?');
+    }
+
+    const { resolved, loading, error } = useResolveTemplate(template);
+    
+    if (loading) {
+      return fallback ? <>{fallback}</> : null;
+    } else if (error) {
+      if (process.env.NODE_ENV === 'development') {
+        return <>[Template Error: {error.message}]</>;
+      } else {
+        return fallback ? <>{fallback}</> : null;
+      }
+    } else {
+      const content = <>{resolved}</>;
+      return Wrapper ? <Wrapper>{content}</Wrapper> : content;
+    }
+  } catch (error) {
+    throw error;
+  }
+};
+
+/**
+ * Hook to resolve template with tagged template literal syntax
+ * 
+ * This returns the resolved value directly so it can be used with || operator
+ */
+export function useTemplate(template: string): string | null {
+  const { resolved, loading, error } = useResolveTemplate(template);
+  
+  if (loading) {
+    return null;
+  } else if (error) {
+    if (process.env.NODE_ENV === 'development') {
+      return `[Template Error: ${error.message}]`;
+    } else {
+      return null;
+    }
+  } else {
+    return resolved;
+  }
+}
+
+/**
+ * Tagged template function for inline data templating
+ * 
+ * Enables JSX components to use mustache syntax for data interpolation:
+ * 
+ * Usage:
+ * ```tsx
+ * {t`Welcome to {{company.name}}!`}
+ * {t`Hello {{user.name}}` || 'Loading...'}
+ * {t.wrap(CustomComponent)`{{company.slogan}}`}
+ * ```
+ */
+export function t(strings: TemplateStringsArray, ...values: any[]): ReactNode {
+  // First do regular template literal interpolation
+  const template = String.raw(strings, ...values);
+  
+  // Return a component that uses the hook
+  const TemplateResolver = () => {
+    const resolved = useTemplate(template);
+    return resolved;
+  };
+  
+  return <TemplateResolver />;
+}
+
+/**
+ * Tagged template function with custom wrapper component
+ * 
+ * Usage:
+ * ```tsx
+ * {t.wrap(QuoteComponent)`{{company.slogan}}`}
+ * ```
+ */
+t.wrap = (WrapperComponent: React.ComponentType<{ children: ReactNode }>) => 
+  (strings: TemplateStringsArray, ...values: any[]): ReactNode => {
+    const template = String.raw(strings, ...values);
+    
+    const WrappedTemplate = () => {
+      const resolved = useTemplate(template);
+      return resolved ? <WrapperComponent>{resolved}</WrapperComponent> : null;
+    };
+    
+    return <WrappedTemplate />;
+  };