@qwickapps/react-framework 1.3.4 → 1.4.0

package/src/components/pages/Page.tsx

@@ -1,73 +1,52 @@
 /**
- * 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.
+ * Page Architecture - Clean separation with functional controller
  * 
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
-import React, { useContext, createContext, useCallback } from 'react';
-import './Page.css';
+import React, { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useState } from 'react';
+import { t } from '../../contexts';
+import { useBaseProps, WithBaseProps } from '../../hooks/useBaseProps';
+import { usePrintMode } from '../../hooks/usePrintMode';
+import { PageTemplateSchema } from '../../schemas/PageTemplateSchema';
+import { PrintConfigSchema } from '../../schemas/PrintConfigSchema';
 import { useSafeLocation } from '../../utils/reactUtils';
+import { SafeSpan } from '../SafeSpan';
+import './Page.css';
 
 export interface PageContextValue {
   /** Current page route/path */
   route?: string;
+  /** Whether the page is currently in print mode */
+  isPrintMode: boolean;
+  /** Current print configuration */
+  printConfig: PrintConfigSchema;
+  /** Trigger print mode and dialog */
+  triggerPrint: (config?: Partial<PrintConfigSchema>) => void;
+  /** Set page loading state */
+  setLoading: (loading: boolean) => void;
+  /** Set page error state */
+  setError: (error: string | null) => void;
+  /** Current page loading state */
+  isLoading: boolean;
+  /** Current page error state */
+  error: string | null;
 }
 
 // Create context for page-level state
-const PageContext = createContext<PageContextValue>({});
+const PageContext = createContext<PageContextValue | null>(null);
 
 export const usePageContext = (): PageContextValue => {
   const context = useContext(PageContext);
   if (!context) {
-    throw new Error('usePageContext must be used within a PageProvider or Page component');
+    throw new Error('usePageContext must be used within a 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;
+export interface PageProps extends WithBaseProps {
   /** 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 */
@@ -76,182 +55,274 @@ export interface PageProps {
   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;
+  /** Print configuration for this page */
+  printConfig?: Partial<PrintConfigSchema>;
+  /** PageTemplate model instance */
+  template?: PageTemplateSchema;
+  /** Page title */
+  title?: string;
+  /** Page description for SEO */
+  description?: string;
+  /** Page name/heading */
+  name?: string;
+  /** Page slug for URL */
+  slug?: string;
+}
+
+/**
+ * PageWrapper - Internal component handling print mode detection and page infrastructure
+ */
+interface PageWrapperProps extends PageProps {
+  children: React.ReactNode;
 }
 
-const Page: React.FC<PageProps> = ({
-  children,
-  route,
-  header,
-  footer,
-  className = '',
-  variant = 'default',
-  padding = 'medium',
-  background = 'default',
-  maxWidth = 'large',
-  loading = false,
-  message,
-}) => {
+const PageWrapper: React.FC<PageWrapperProps> = (props) => {
+  const {
+    children,
+    route: routeProp,
+    variant = 'default',
+    padding = 'medium',
+    background = 'default',
+    maxWidth = 'large',
+    printConfig: printConfigProp,
+    template,
+    title: titleProp,
+    description: descriptionProp,
+    name: nameProp,
+    slug: slugProp,
+    ...restProps
+  } = props;
+
+  // Use base props hook to handle common properties
+  const { styleProps, htmlProps } = useBaseProps(restProps);
+
+  // Note: QwickApp context is available if needed for future enhancements
+
+  // Resolve values from template or props (props take precedence)
+  const resolvedValues = {
+    route: routeProp ?? (template?.slug ? `/${template.slug}` : undefined),
+    title: titleProp ?? template?.title ?? template?.name,
+    description: descriptionProp ?? template?.description,
+    name: nameProp ?? template?.name,
+    slug: slugProp ?? template?.slug,
+    printConfig: { ...template?.printConfig, ...printConfigProp },
+  };
+
+  // Page state management
+  const [isLoading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Initialize print mode with page configuration  
+  const { isPrintMode, printConfig, onViewLoading, onViewReady, triggerPrint: triggerPrintBase } = usePrintMode();
+  // Create page-specific trigger that applies page config
+  const triggerPrint = useCallback((config?: Partial<PrintConfigSchema>) => {
+    const mergedConfig = { ...resolvedValues.printConfig, ...config };
+    triggerPrintBase(mergedConfig);
+  }, [triggerPrintBase, resolvedValues.printConfig]);
+
   // 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]);
+  const actualRoute = resolvedValues.route || location?.pathname || '';
+
+  // Handle SEO and document head updates
+  useEffect(() => {
+    if (resolvedValues.title) {
+      document.title = resolvedValues.title;
+    }
+    // Update meta description
+    if (resolvedValues.description) {
+      let metaDescription = document.querySelector('meta[name="description"]');
+      if (!metaDescription) {
+        metaDescription = document.createElement('meta');
+        metaDescription.setAttribute('name', 'description');
+        document.head.appendChild(metaDescription);
+      }
+      metaDescription.setAttribute('content', resolvedValues.description);
+    }
+  }, [resolvedValues.title, resolvedValues.description]);
+
+  // Signal view state changes - let reducer handle valid transitions
+  useLayoutEffect(() => {
+    if (isPrintMode && isLoading) {
+      onViewLoading();
+    } else if (isPrintMode && !isLoading) {
+      onViewReady();
+    }
+  }, [isPrintMode, isLoading, onViewLoading, onViewReady]);
 
   // Memoized context value
-  const contextValue = React.useMemo<PageContextValue>(() => ({
+  const contextValue = useMemo<PageContextValue>(() => ({
     route: actualRoute,
-  }), [actualRoute]);
+    isPrintMode,
+    printConfig,
+    triggerPrint,
+    setLoading,
+    setError,
+    isLoading,
+    error,
+  }), [actualRoute, isPrintMode, printConfig, triggerPrint, isLoading, error]);
+
+  // Inject dynamic @page margins during print to reserve header/footer space on every page
+  useEffect(() => {
+    const styleId = 'qwickapps-print-page-setup';
+
+    const applyPrintPageSetup = () => {
+      const configuredHeader = printConfig.printHeaderHeight || '0';
+      const configuredFooter = printConfig.printFooterHeight || '0';
+      const size = (printConfig as any).pageSize || 'auto';
+      const bg = printConfig.printBackground || 'transparent';
+      const bgFirst = printConfig.printBackgroundFirstPage || bg;
+
+      // Measure actual rendered heights (fallback to configured)
+      const getPx = (v: string | number) => typeof v === 'number' ? `${v}px` : (String(v).match(/(px|mm|cm|in|pt|pc)$/) ? String(v) : `${v}px`);
+      const headerEl = document.querySelector('.page-print-header:not(.page-print-header-first-page)') as HTMLElement | null;
+      const footerEl = document.querySelector('.page-print-footer:not(.page-print-footer-first-page)') as HTMLElement | null;
+      const measuredHeaderPx = headerEl && headerEl.getBoundingClientRect ? Math.ceil(headerEl.getBoundingClientRect().height) : 0;
+      const measuredFooterPx = footerEl && footerEl.getBoundingClientRect ? Math.ceil(footerEl.getBoundingClientRect().height) : 0;
+      const headerH = measuredHeaderPx > 0 ? `${measuredHeaderPx}px` : getPx(configuredHeader);
+      const footerH = measuredFooterPx > 0 ? `${measuredFooterPx}px` : getPx(configuredFooter);
+
+      const css = `@media print{\n  @page{\n    size: ${String(size)};\n    margin: 0;\n  }\n  .page-print-mode{\n    --print-header-height: ${String(headerH)};\n    --print-footer-height: ${String(footerH)};\n    --print-background: ${String(bg)};\n    --print-background-first-page: ${String(bgFirst)};\n}\n}`;
+
+      let el = document.getElementById(styleId) as HTMLStyleElement | null;
+      if (!el) {
+        el = document.createElement('style');
+        el.id = styleId;
+        document.head.appendChild(el);
+      }
+      el.textContent = css;
+
+      // Re-measure after layout settles once and update
+      setTimeout(() => {
+        const reHeaderEl = document.querySelector('.page-print-header:not(.page-print-header-first-page)') as HTMLElement | null;
+        const reFooterEl = document.querySelector('.page-print-footer:not(.page-print-footer-first-page)') as HTMLElement | null;
+        const reHeaderPx = reHeaderEl?.getBoundingClientRect ? Math.ceil(reHeaderEl.getBoundingClientRect().height) : 0;
+        const reFooterPx = reFooterEl?.getBoundingClientRect ? Math.ceil(reFooterEl.getBoundingClientRect().height) : 0;
+        if (reHeaderPx || reFooterPx) {
+          const finalHeader = reHeaderPx ? `${reHeaderPx}px` : headerH;
+          const finalFooter = reFooterPx ? `${reFooterPx}px` : footerH;
+          const finalCss = `@media print{\n  @page{\n    size: ${String(size)};\n    margin: 0;\n  }\n  .page-print-mode{\n    --print-header-height: ${String(finalHeader)};\n    --print-footer-height: ${String(finalFooter)};\n    --print-background: ${String(bg)};\n    --print-background-first-page: ${String(bgFirst)};\n  }\n}`;
+          let styleEl = document.getElementById(styleId) as HTMLStyleElement | null;
+          if (!styleEl) {
+            styleEl = document.createElement('style');
+            styleEl.id = styleId;
+            document.head.appendChild(styleEl);
+          }
+          styleEl.textContent = finalCss;
+        }
+      }, 60);
+    };
+
+    const removePrintPageSetup = () => {
+      const el = document.getElementById(styleId);
+      if (el && el.parentNode) el.parentNode.removeChild(el);
+    };
+
+    if (isPrintMode) {
+      applyPrintPageSetup();
+      // Cleanup after the print dialog closes
+      const onAfterPrint = () => removePrintPageSetup();
+      window.addEventListener('afterprint', onAfterPrint);
+      return () => {
+        window.removeEventListener('afterprint', onAfterPrint);
+        removePrintPageSetup();
+      };
+    }
 
-  // Generate class names
+    // If leaving print mode, ensure cleanup
+    removePrintPageSetup();
+  }, [isPrintMode, printConfig.printHeaderHeight, printConfig.printFooterHeight, (printConfig as any).pageSize, printConfig.printBackground, printConfig.printBackgroundFirstPage]);
+
+  // Calculate CSS variables for print configuration
+
+  // Generate class names based on configuration
   const pageClasses = [
     'page',
     `page-variant-${variant}`,
     `page-padding-${padding}`,
     `page-background-${background}`,
     `page-max-width-${maxWidth}`,
-    className,
+    // Print mode classes
+    isPrintMode ? 'page-print-mode' : '',
+    // Print margin variants
+    isPrintMode && printConfig.pageMargins === '0mm' ? 'page-print-borderless' : '',
+    isPrintMode && printConfig.pageMargins === '6mm' ? 'page-print-compact' : '',
+    isPrintMode && printConfig.pageMargins === '20mm' ? 'page-print-large' : '',
+    isPrintMode && printConfig.pageMargins === '25mm' ? 'page-print-formal' : '',
+    // Background class when custom background is specified
+    isPrintMode && (printConfig.printBackground || printConfig.printBackgroundFirstPage) ? 'has-background' : '',
+    // User classes
+    styleProps.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>}
+  return (
+    <PageContext.Provider value={contextValue}>
+      <div className={pageClasses} {...htmlProps}>
+        {/* Custom print header - regular pages */}
+        {isPrintMode && printConfig.printHeader && (
+          <div className="page-print-header">
+            {typeof printConfig.printHeader === 'string' ? (
+              <SafeSpan html={t`${printConfig.printHeader}` as string} />
+            ) : (
+              printConfig.printHeader
+            )}
           </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>
-    );
-  }
+        {/* Custom print header - first page only (rendered as a separate element for app control) */}
+        {isPrintMode && printConfig.printHeaderFirstPage && (
+          <div className="page-print-header page-print-header-first-page">
+            {typeof printConfig.printHeaderFirstPage === 'string' ? (
+              <SafeSpan html={t`${printConfig.printHeaderFirstPage}` as string} />
+            ) : (
+              printConfig.printHeaderFirstPage
+            )}
+          </div>
+        )}
 
-  return (
-    <PageContext.Provider value={contextValue}>
-      <div className={pageClasses}>
-        {/* Optional Header */}
-        {header && (
-          <div className="page-header">
-            {header}
+        {/* Default print header - only if no custom header provided */}
+        {isPrintMode && !printConfig.printHeader && printConfig.printTitle && (
+          <div className="page-print-header">
+            <h1>{printConfig.printTitle}</h1>
+            {printConfig.showPrintDate && (
+              <div className="page-print-date">
+                Printed on: {new Date().toLocaleString()}
+              </div>
+            )}
           </div>
         )}
 
-        {/* Message state (error/warning/success/info) */}
-        {message && renderMessage(message)}
+        {/* Page name as heading (if provided and different from title) */}
+        {resolvedValues.name && resolvedValues.name !== resolvedValues.title && (
+          <div className="page-heading">
+            <h1>{resolvedValues.name}</h1>
+          </div>
+        )}
 
         {/* Page Content */}
         <div className="page-content">
           {children}
         </div>
 
-        {/* Optional Footer */}
-        {footer && (
-          <div className="page-footer">
-            {footer}
+        {/* Custom print footer - regular pages */}
+        {isPrintMode && printConfig.printFooter && (
+          <div className="page-print-footer">
+            {typeof printConfig.printFooter === 'string' ? (
+              <SafeSpan html={t`${printConfig.printFooter}` as string} />
+            ) : (
+              printConfig.printFooter
+            )}
+          </div>
+        )}
+
+        {/* Custom print footer - first page only (rendered as a separate element for app control) */}
+        {isPrintMode && printConfig.printFooterFirstPage && (
+          <div className="page-print-footer page-print-footer-first-page">
+            {typeof printConfig.printFooterFirstPage === 'string' ? (
+              <SafeSpan html={t`${printConfig.printFooterFirstPage}` as string} />
+            ) : (
+              printConfig.printFooterFirstPage
+            )}
           </div>
         )}
       </div>
@@ -259,87 +330,68 @@ const Page: React.FC<PageProps> = ({
   );
 };
 
-// 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;
-    }, []),
-  };
+/**
+ * Page - Functional component that controls print/normal view routing
+ */
+interface PageWithViewsProps extends PageProps {
+  /** Function to render normal view */
+  renderView: () => React.ReactNode;
+  /** Function to render print view */
+  renderPrintView: () => React.ReactNode;
+}
+
+const Page: React.FC<PageWithViewsProps> = (props) => {
+  const { renderView, renderPrintView, ...pageProps } = props;
+
+  return (
+    <PageWrapper {...pageProps}>
+      <PageController renderView={renderView} renderPrintView={renderPrintView} />
+    </PageWrapper>
+  );
+};
+
+// Controller component that uses context to get print mode state
+const PageController: React.FC<{
+  renderView: () => React.ReactNode;
+  renderPrintView: () => React.ReactNode;
+}> = ({ renderView, renderPrintView }) => {
+  const { isPrintMode } = usePageContext();
+  return <>{isPrintMode ? renderPrintView() : renderView()}</>;
 };
 
 /**
- * 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>
- *     );
- *   }
- * }
+ * PageComponent - Base class for pages that provide view functions
  */
-export abstract class BasePage<P = {}, S = {}> extends React.Component<P, S> {
+export abstract class PageComponent<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;
+  abstract getPageProps(): PageProps;
 
   /**
-   * Override this method to handle page mounting logic
-   * Called after the page is mounted and context is available
+   * Override this method to provide the normal view content
    */
-  onPageMount?(): void;
+  abstract renderView(): React.ReactNode;
 
   /**
-   * Override this method to handle page unmounting logic
+   * Override this method to provide the print view content
    */
-  onPageUnmount?(): void;
+  abstract renderPrintView(): React.ReactNode;
 
   /**
-   * Internal render method - wraps content in Page component
+   * Render method - uses functional Page as controller
    */
   render() {
     const pageProps = this.getPageProps();
-    
+
     return (
-      <Page {...pageProps}>
-        {this.renderContent()}
-      </Page>
+      <Page
+        {...pageProps}
+        renderView={() => this.renderView()}
+        renderPrintView={() => this.renderPrintView()}
+      />
     );
   }
-
-  /**
-   * Component lifecycle methods
-   */
-  componentDidMount() {
-    this.onPageMount?.();
-  }
-
-  componentWillUnmount() {
-    this.onPageUnmount?.();
-  }
 }
 
 export default Page;

package/src/components/pages/index.ts

@@ -3,9 +3,9 @@
  * 
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
-export { BasePage } from './Page';
+export { PageComponent, usePageContext } from './Page';
 export { default as FormPage } from './FormPage';
 export { default as Page } from './Page';
 
 export type { FormPageProps } from './FormPage';
-export type { PageProps } from './Page';
+export type { PageProps, PageContextValue } from './Page';