@qwickapps/react-framework 1.4.9 → 1.5.1

package/src/components/forms/Captcha.tsx

@@ -0,0 +1,291 @@
+/**
+ * Captcha - Universal CAPTCHA component supporting multiple providers
+ *
+ * Supported providers:
+ * - Google reCAPTCHA v2 (checkbox)
+ * - Google reCAPTCHA v3 (invisible)
+ * - hCaptcha
+ * - Cloudflare Turnstile
+ *
+ * Features:
+ * - Provider-agnostic API
+ * - Automatic script loading
+ * - TypeScript support
+ * - Themed styling with base props support
+ * - Grid behavior support
+ * - Error handling
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useEffect, useRef, useState } from 'react';
+import { Box, Alert } from '@mui/material';
+import { useBaseProps, WithBaseProps, QWICKAPP_COMPONENT } from '../../hooks/useBaseProps';
+
+export type CaptchaProvider = 'recaptcha-v2' | 'recaptcha-v3' | 'hcaptcha' | 'turnstile';
+
+interface CaptchaBaseProps {
+  /** CAPTCHA provider */
+  provider: CaptchaProvider;
+  /** Site key (public key) */
+  siteKey: string;
+  /** Callback when CAPTCHA is successfully completed */
+  onVerify: (token: string) => void;
+  /** Callback when CAPTCHA expires or fails */
+  onExpire?: () => void;
+  /** Callback when CAPTCHA encounters an error */
+  onError?: (error: Error) => void;
+  /** Theme for the widget (light or dark) */
+  theme?: 'light' | 'dark';
+  /** Size of the widget */
+  size?: 'normal' | 'compact' | 'invisible';
+  /** reCAPTCHA v3 action name */
+  action?: string;
+}
+
+export interface CaptchaProps extends WithBaseProps<CaptchaBaseProps> {}
+
+// Declare global interfaces for CAPTCHA providers
+declare global {
+  interface Window {
+    grecaptcha?: unknown;
+    hcaptcha?: unknown;
+    turnstile?: unknown;
+    onRecaptchaLoad?: () => void;
+    onHcaptchaLoad?: () => void;
+    onTurnstileLoad?: () => void;
+  }
+}
+
+export const Captcha = React.forwardRef<HTMLDivElement, CaptchaProps>((props, ref) => {
+  const { gridProps, styleProps, htmlProps, restProps } = useBaseProps(props);
+
+  const {
+    provider,
+    siteKey,
+    onVerify,
+    onExpire,
+    onError,
+    theme = 'light',
+    size = 'normal',
+    action = 'submit',
+  } = restProps as CaptchaBaseProps;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const widgetIdRef = useRef<string | number | null>(null);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Load the appropriate CAPTCHA script
+  useEffect(() => {
+    const loadScript = () => {
+      // Check if script is already loaded
+      const isAlreadyLoaded = (() => {
+        switch (provider) {
+          case 'recaptcha-v2':
+          case 'recaptcha-v3':
+            return !!window.grecaptcha;
+          case 'hcaptcha':
+            return !!window.hcaptcha;
+          case 'turnstile':
+            return !!window.turnstile;
+          default:
+            return false;
+        }
+      })();
+
+      if (isAlreadyLoaded) {
+        setIsLoaded(true);
+        return;
+      }
+
+      // Get the script URL for the provider
+      const getScriptUrl = (): string => {
+        switch (provider) {
+          case 'recaptcha-v2':
+            return 'https://www.google.com/recaptcha/api.js?render=explicit';
+          case 'recaptcha-v3':
+            return `https://www.google.com/recaptcha/api.js?render=${siteKey}`;
+          case 'hcaptcha':
+            return 'https://js.hcaptcha.com/1/api.js?render=explicit';
+          case 'turnstile':
+            return 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
+          default:
+            return '';
+        }
+      };
+
+      const scriptUrl = getScriptUrl();
+      if (!scriptUrl) {
+        setError('Unsupported CAPTCHA provider');
+        return;
+      }
+
+      // Create and load script
+      const script = document.createElement('script');
+      script.src = scriptUrl;
+      script.async = true;
+      script.defer = true;
+
+      script.onload = () => {
+        setIsLoaded(true);
+      };
+
+      script.onerror = () => {
+        setError('Failed to load CAPTCHA script');
+        onError?.(new Error('Failed to load CAPTCHA script'));
+      };
+
+      document.head.appendChild(script);
+
+      return () => {
+        // Cleanup: remove script when component unmounts
+        document.head.removeChild(script);
+      };
+    };
+
+    loadScript();
+  }, [provider, siteKey, onError]);
+
+  // Render the CAPTCHA widget
+  useEffect(() => {
+    if (!isLoaded || !containerRef.current) return;
+
+    const renderWidget = () => {
+      try {
+        switch (provider) {
+          case 'recaptcha-v2':
+            if (window.grecaptcha && window.grecaptcha.render) {
+              widgetIdRef.current = window.grecaptcha.render(containerRef.current, {
+                sitekey: siteKey,
+                callback: onVerify,
+                'expired-callback': onExpire,
+                'error-callback': () => {
+                  const err = new Error('reCAPTCHA error');
+                  setError(err.message);
+                  onError?.(err);
+                },
+                theme,
+                size,
+              });
+            }
+            break;
+
+          case 'recaptcha-v3':
+            // reCAPTCHA v3 is invisible and executes programmatically
+            if (window.grecaptcha && window.grecaptcha.execute) {
+              window.grecaptcha.execute(siteKey, { action }).then((token: string) => {
+                onVerify(token);
+              }).catch((err: Error) => {
+                setError(err.message);
+                onError?.(err);
+              });
+            }
+            break;
+
+          case 'hcaptcha':
+            if (window.hcaptcha && window.hcaptcha.render) {
+              widgetIdRef.current = window.hcaptcha.render(containerRef.current, {
+                sitekey: siteKey,
+                callback: onVerify,
+                'expired-callback': onExpire,
+                'error-callback': () => {
+                  const err = new Error('hCaptcha error');
+                  setError(err.message);
+                  onError?.(err);
+                },
+                theme,
+                size: size === 'normal' ? 'normal' : 'compact',
+              });
+            }
+            break;
+
+          case 'turnstile':
+            if (window.turnstile && window.turnstile.render) {
+              widgetIdRef.current = window.turnstile.render(containerRef.current, {
+                sitekey: siteKey,
+                callback: onVerify,
+                'expired-callback': onExpire,
+                'error-callback': () => {
+                  const err = new Error('Turnstile error');
+                  setError(err.message);
+                  onError?.(err);
+                },
+                theme,
+                size: size === 'compact' ? 'compact' : 'normal',
+              });
+            }
+            break;
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to render CAPTCHA');
+        setError(error.message);
+        onError?.(error);
+      }
+    };
+
+    // Small delay to ensure the CAPTCHA library is fully initialized
+    const timer = setTimeout(renderWidget, 100);
+
+    return () => {
+      clearTimeout(timer);
+      // Cleanup widget on unmount
+      if (widgetIdRef.current !== null) {
+        try {
+          switch (provider) {
+            case 'recaptcha-v2':
+              window.grecaptcha?.reset(widgetIdRef.current);
+              break;
+            case 'hcaptcha':
+              window.hcaptcha?.remove(widgetIdRef.current);
+              break;
+            case 'turnstile':
+              window.turnstile?.remove(widgetIdRef.current);
+              break;
+          }
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      }
+    };
+  }, [isLoaded, provider, siteKey, onVerify, onExpire, onError, theme, size, action]);
+
+  // Don't render anything for reCAPTCHA v3 (invisible)
+  if (provider === 'recaptcha-v3') {
+    return null;
+  }
+
+  return (
+    <Box
+      ref={ref}
+      {...htmlProps}
+      sx={{
+        my: 2,
+        ...styleProps.sx,
+      }}
+      // Store grid props as data attributes for ColumnLayout to pick up
+      {...(gridProps && {
+        'data-grid-span': gridProps.span,
+        'data-grid-xs': gridProps.xs,
+        'data-grid-sm': gridProps.sm,
+        'data-grid-md': gridProps.md,
+        'data-grid-lg': gridProps.lg,
+        'data-grid-xl': gridProps.xl,
+      })}
+    >
+      {error && (
+        <Alert severity="error" sx={{ mb: 2 }}>
+          {error}
+        </Alert>
+      )}
+      <div ref={containerRef} />
+    </Box>
+  );
+});
+
+Captcha.displayName = 'Captcha';
+
+// Mark as QwickApp component
+(Captcha as Record<string, unknown>)[QWICKAPP_COMPONENT] = true;
+
+export default Captcha;

package/src/components/forms/FormBlock.tsx

@@ -27,9 +27,9 @@ import type { SchemaProps, WithDataBinding } from '@qwickapps/schema';
 import { useQwickApp } from '../../contexts/QwickAppContext';
 import { QWICKAPP_COMPONENT, useBaseProps, useDataBinding } from '../../hooks';
 import FormBlockModel from '../../schemas/FormBlockSchema';
+import { ModelView } from '../base/ModelView';
 import CoverImageHeader from '../blocks/CoverImageHeader';
 import Logo from '../Logo';
-import { ModelView } from '../base/ModelView';
 
 type FormBlockViewProps = SchemaProps<FormBlockModel> & {
   /**
@@ -55,7 +55,7 @@ type FormBlockViewProps = SchemaProps<FormBlockModel> & {
   footer?: React.ReactNode;
 };
 
-export interface FormBlockProps extends FormBlockViewProps, WithDataBinding { }
+export interface FormBlockProps extends FormBlockViewProps, WithDataBinding {} 
 
 /**
  * Default header component that uses CoverImageHeader and Logo
@@ -231,34 +231,41 @@ export class FormBlock extends ModelView<FormBlockProps, FormBlockModel> {
   static readonly version = '1.0.0';
   
   // Deserialization: JSON data → React element
-  static fromJson(jsonData: any): ReactElement {
-    return <FormBlock {...jsonData} />;
+  static fromJson(jsonData: unknown): ReactElement {
+    return <FormBlock {...(jsonData as Record<string, unknown>)} />;
   }
   
   // FormBlock components have nested ReactNode children (form content)
-  protected hasNestedComponents(children: React.ReactNode): boolean {
+  protected hasNestedComponents(_children: React.ReactNode): boolean {
     // FormBlock may contain other serializable components as children
     return true;
   }
-  
+
   // Custom children serialization for FormBlock
-  protected serializeChildren(children: React.ReactNode): any {
+  protected serializeChildren(children: React.ReactNode): unknown {
     // For FormBlock, children represent the form content which could be other components
     // We need to handle this properly by checking if children contain serializable components
-    if (React.isValidElement(children) && (children.type as any).prototype?.toJson) {
+    interface SerializableType {
+      prototype?: { toJson?: unknown };
+      fromJson?: unknown;
+      tagName?: string;
+    }
+
+    if (React.isValidElement(children) && (children.type as SerializableType).prototype?.toJson) {
       // If it's a serializable component, serialize it
-      return (children.type as any).fromJson ? {
-        component: (children.type as any).tagName,
+      const childType = children.type as SerializableType;
+      return childType.fromJson ? {
+        component: childType.tagName,
         props: children.props
       } : children;
     }
-    
+
     // For non-serializable children (regular JSX), extract text or return as-is
     return super.serializeChildren(children);
   }
   
   // Component-specific serialization properties
-  protected getComponentSpecificProps(): any {
+  protected getComponentSpecificProps(): unknown {
     return {
       title: this.props.title,
       description: this.props.description,
@@ -274,7 +281,7 @@ export class FormBlock extends ModelView<FormBlockProps, FormBlockModel> {
 
   // FormBlock component renders traditional props view
   protected renderView(): React.ReactElement {
-    const { dataSource, bindingOptions, ...restProps } = this.props;
+    const { dataSource: _dataSource, bindingOptions: _bindingOptions, ...restProps } = this.props;
     return <FormBlockView {...restProps} />;
   }
 
@@ -289,7 +296,7 @@ function FormBlockWithDataBinding(props: FormBlockProps) {
   const { dataSource, bindingOptions, ...restProps } = props;
 
   // Use data binding
-  const { dataSource: _source, loading, error, cached, ...formBlockProps } = useDataBinding<FormBlockModel>(
+  const { loading, error, ...formBlockProps } = useDataBinding<FormBlockModel>(
     dataSource!,
     restProps as Partial<FormBlockModel>,
     FormBlockModel.getSchema(),
@@ -339,6 +346,6 @@ function FormBlockWithDataBinding(props: FormBlockProps) {
 }
 
 // Mark as QwickApp component
-(FormBlock as any)[QWICKAPP_COMPONENT] = true;
+(FormBlock as Record<string, unknown>)[QWICKAPP_COMPONENT] = true;
 
 export default FormBlock;

package/src/components/forms/FormCheckbox.tsx

@@ -0,0 +1,116 @@
+/**
+ * FormCheckbox - Themed checkbox component wrapping MUI Checkbox and FormControlLabel
+ *
+ * Features:
+ * - Uses QwickApps CSS theme variables for consistent styling
+ * - Supports FormControlLabel for proper label positioning
+ * - Handles required and disabled states
+ * - Helper text support
+ * - Base props support for grid behavior and styling
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import {
+  FormControl,
+  FormControlLabel,
+  Checkbox,
+  FormHelperText,
+} from '@mui/material';
+import { useBaseProps, WithBaseProps, QWICKAPP_COMPONENT } from '../../hooks/useBaseProps';
+
+interface FormCheckboxBaseProps {
+  label: string;
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  helperText?: string;
+  required?: boolean;
+  disabled?: boolean;
+}
+
+export interface FormCheckboxProps extends WithBaseProps<FormCheckboxBaseProps> {}
+
+export const FormCheckbox = React.forwardRef<HTMLDivElement, FormCheckboxProps>((props, ref) => {
+  const { gridProps, styleProps, htmlProps, restProps } = useBaseProps(props);
+
+  const {
+    label,
+    checked,
+    onChange,
+    helperText,
+    required = false,
+    disabled = false,
+  } = restProps as FormCheckboxBaseProps;
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    onChange(e.target.checked);
+  };
+
+  const checkboxStyles = {
+    color: 'var(--theme-primary)',
+    '&.Mui-checked': {
+      color: 'var(--theme-primary)',
+    },
+    '&.Mui-disabled': {
+      color: 'var(--theme-text-disabled)',
+    },
+  };
+
+  const labelStyles = {
+    color: 'var(--theme-text-primary)',
+    '& .MuiFormControlLabel-label': {
+      color: 'var(--theme-text-primary)',
+    },
+    '& .MuiFormControlLabel-label.Mui-disabled': {
+      color: 'var(--theme-text-disabled)',
+    },
+    ...styleProps.sx,
+  };
+
+  const helperTextStyles = {
+    color: 'var(--theme-secondary)',
+    marginLeft: '32px', // Align with checkbox + label
+  };
+
+  return (
+    <FormControl
+      ref={ref}
+      {...htmlProps}
+      {...styleProps}
+      // Store grid props as data attributes for ColumnLayout to pick up
+      {...(gridProps && {
+        'data-grid-span': gridProps.span,
+        'data-grid-xs': gridProps.xs,
+        'data-grid-sm': gridProps.sm,
+        'data-grid-md': gridProps.md,
+        'data-grid-lg': gridProps.lg,
+        'data-grid-xl': gridProps.xl,
+      })}
+    >
+      <FormControlLabel
+        control={
+          <Checkbox
+            checked={checked}
+            onChange={handleChange}
+            required={required}
+            disabled={disabled}
+            sx={checkboxStyles}
+          />
+        }
+        label={label}
+        sx={labelStyles}
+      />
+      {helperText && (
+        <FormHelperText sx={helperTextStyles}>{helperText}</FormHelperText>
+      )}
+    </FormControl>
+  );
+});
+
+FormCheckbox.displayName = 'FormCheckbox';
+
+// Mark as QwickApp component
+(FormCheckbox as Record<string, unknown>)[QWICKAPP_COMPONENT] = true;
+
+export default FormCheckbox;

package/src/components/forms/FormField.tsx

@@ -0,0 +1,180 @@
+/**
+ * FormField - Themed form field component wrapping MUI FormControl
+ *
+ * Features:
+ * - Uses QwickApps CSS theme variables for consistent styling
+ * - Supports text, number, password, and email input types
+ * - Integrated with MUI FormControl, Input, and Select
+ * - Handles readonly, disabled, and required states
+ * - Support for adornments and helper text
+ * - Base props support for grid behavior and styling
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import {
+  FormControl,
+  InputLabel,
+  Input,
+  FormHelperText,
+  InputAdornment,
+} from '@mui/material';
+import { useBaseProps, WithBaseProps, QWICKAPP_COMPONENT } from '../../hooks/useBaseProps';
+
+export interface FormFieldOption {
+  value: string | number;
+  label: string;
+}
+
+interface FormFieldBaseProps {
+  label: string;
+  value: string | number;
+  onChange?: (value: string | number) => void;
+  onChangeRaw?: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  type?: 'text' | 'number' | 'password' | 'email' | 'tel';
+  helperText?: string;
+  required?: boolean;
+  readOnly?: boolean;
+  disabled?: boolean;
+  disabledColor?: string;
+  fullWidth?: boolean;
+  multiline?: boolean;
+  rows?: number;
+  placeholder?: string;
+  startAdornment?: React.ReactNode;
+  endAdornment?: React.ReactNode;
+  inputProps?: unknown;
+}
+
+export interface FormFieldProps extends WithBaseProps<FormFieldBaseProps> {}
+
+export const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>((props, ref) => {
+  const { gridProps, styleProps, htmlProps, restProps } = useBaseProps(props);
+
+  const {
+    label,
+    value,
+    onChange,
+    onChangeRaw,
+    type = 'text',
+    helperText,
+    required = false,
+    readOnly = false,
+    disabled = false,
+    disabledColor,
+    fullWidth = true,
+    multiline = false,
+    rows,
+    placeholder,
+    startAdornment,
+    endAdornment,
+    inputProps,
+  } = restProps as FormFieldBaseProps;
+
+  // Generate a unique ID for the input field
+  const fieldId = React.useId();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+    // If onChangeRaw is provided, use it instead
+    if (onChangeRaw) {
+      onChangeRaw(e);
+      return;
+    }
+
+    if (onChange) {
+      const newValue = type === 'number' ? parseInt(e.target.value) || 0 : e.target.value;
+      onChange(newValue);
+    }
+  };
+
+  const inputStyles = {
+    p: 1,
+    pl: 1.6,
+    mt: 3,
+    color: disabled && disabledColor
+      ? disabledColor
+      : readOnly
+        ? 'var(--theme-text-secondary)'
+        : 'var(--theme-text-primary)',
+    backgroundColor: readOnly ? 'var(--theme-surface-variant)' : 'transparent',
+    borderRadius: 1,
+    '&.Mui-disabled': disabledColor ? {
+      color: disabledColor,
+      WebkitTextFillColor: disabledColor,
+    } : undefined,
+    '& input.Mui-disabled': disabledColor ? {
+      color: disabledColor,
+      WebkitTextFillColor: disabledColor,
+    } : undefined,
+    ...styleProps.sx,
+  };
+
+  const labelStyles = {
+    left: -12,
+    fontWeight: 600,
+    color: 'var(--theme-text-primary)',
+  };
+
+  const helperTextStyles = {
+    color: 'var(--theme-secondary)',
+  };
+
+  return (
+    <FormControl
+      ref={ref}
+      fullWidth={fullWidth}
+      {...htmlProps}
+      {...styleProps}
+      // Store grid props as data attributes for ColumnLayout to pick up
+      {...(gridProps && {
+        'data-grid-span': gridProps.span,
+        'data-grid-xs': gridProps.xs,
+        'data-grid-sm': gridProps.sm,
+        'data-grid-md': gridProps.md,
+        'data-grid-lg': gridProps.lg,
+        'data-grid-xl': gridProps.xl,
+      })}
+    >
+      <InputLabel htmlFor={fieldId} sx={labelStyles} shrink>
+        {label}
+      </InputLabel>
+
+      <Input
+        id={fieldId}
+        type={type}
+        value={value}
+        onChange={handleChange}
+        readOnly={readOnly}
+        disabled={disabled}
+        required={required}
+        multiline={multiline}
+        rows={rows}
+        placeholder={placeholder}
+        inputProps={inputProps}
+        sx={inputStyles}
+        startAdornment={
+          startAdornment ? (
+            <InputAdornment position="start">{startAdornment}</InputAdornment>
+          ) : undefined
+        }
+        endAdornment={
+          endAdornment ? (
+            <InputAdornment position="end">{endAdornment}</InputAdornment>
+          ) : undefined
+        }
+      />
+
+      {helperText && (
+        <FormHelperText sx={helperTextStyles}>{helperText}</FormHelperText>
+      )}
+    </FormControl>
+  );
+});
+
+FormField.displayName = 'FormField';
+
+// Mark as QwickApp component
+(FormField as Record<string, unknown>)[QWICKAPP_COMPONENT] = true;
+
+export default FormField;