@aatulwork/customform-renderer 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @custom-form/renderer
+# @aatulwork/customform-renderer
 
 A powerful, reusable form renderer component for React with Material-UI support. This package provides a dynamic form rendering system that can generate forms from JSON schemas with support for multiple field types, validation, file uploads, and more.
 
@@ -16,7 +16,7 @@ A powerful, reusable form renderer component for React with Material-UI support.
 ## Installation
 
 ```bash
-npm install @custom-form/renderer
+npm install @aatulwork/customform-renderer
 ```
 
 ### Peer Dependencies
@@ -27,9 +27,11 @@ Make sure you have these peer dependencies installed:
 npm install react react-dom @mui/material @mui/icons-material @mui/x-date-pickers react-hook-form @tanstack/react-query dayjs @ckeditor/ckeditor5-react
 ```
 
+Peer versions: React ^18, MUI ^6, @mui/x-date-pickers ^7, react-hook-form ^7, @tanstack/react-query ^5, dayjs ^1.11, @ckeditor/ckeditor5-react ^11.
+
 ### CKEditor Setup
 
-The package includes CKEditor in the `lib/ckeditor/` directory. You need to load it before using CKEditor fields.
+The package includes CKEditor in the `lib/ckeditor/` directory. You need to load it before using CKEditor fields. **If the CKEditor field shows "CKEditor failed to load" or stays on "Loading editor...",** the script URL is not reachable—copy `lib/ckeditor/ckeditor.js` to your app’s `public/lib/ckeditor/` or set `services.ckEditorScriptPath`. See [CKEDITOR_SETUP.md](./CKEDITOR_SETUP.md) for details and troubleshooting.
 
 **Option 1: Include in HTML (Recommended)**
 ```html
@@ -38,23 +40,34 @@ The package includes CKEditor in the `lib/ckeditor/` directory. You need to load
 
 **Option 2: Copy to your public directory**
 ```bash
-cp node_modules/@custom-form/renderer/lib/ckeditor/ckeditor.js public/lib/ckeditor/
+cp node_modules/@aatulwork/customform-renderer/lib/ckeditor/ckeditor.js public/lib/ckeditor/
 ```
 
 **Option 3: Use dynamic loading**
 ```tsx
-import { useCKEditor } from '@custom-form/renderer';
+import { useCKEditor } from '@aatulwork/customform-renderer';
 
 const { isReady } = useCKEditor({ autoLoad: true });
 ```
 
 See [CKEditor Setup Guide](#ckeditor-setup) for more details.
 
+## Package Exports
+
+The package exports the following:
+
+- **Components:** `FormRenderer`, `FieldRenderer`, `FormViewMode`, `FieldView`
+- **Field components:** `TextField`, `SelectField`, `CheckboxField`, `RadioField`, `ToggleField`, `ColorField`, `DateTimePickerField`, `CKEditorField`, `FileField`, `FormReferenceField`, `ApiReferenceField`
+- **Common:** `SimpleSelect` (and types `SimpleSelectProps`, `SimpleSelectOption`)
+- **Types:** `FormSchema`, `FormField`, `FormSection`, `FormRendererProps`, `FieldRendererProps`, `FormServices`, `FileUploadService`, `FormReferenceService`, `ApiReferenceService`, `DateFormatterService`, `OptionItem`, `FieldType`, `FieldValidation`, `UploadedFile`, `FormColors`
+- **Utils:** `getAllFields`, `normalizeInitialValues`, `transformFormValues`, `getDefaultValue`, `formatFileSize`, `validateFile`, `buildFieldRules`, `normalizeOptions`
+- **CKEditor:** `loadCKEditor`, `isCKEditorAvailable`, `waitForCKEditor`, `useCKEditor`
+- **Default services:** `defaultFileUploadService`, `defaultFormReferenceService`, `defaultApiReferenceService`, `defaultDateFormatterService` (throw if used without override; provide your own via `services`)
+
 ## Quick Start
 
 ```tsx
-import { FormRenderer } from '@custom-form/renderer';
-import { FormSchema } from '@custom-form/renderer';
+import { FormRenderer, FormSchema } from '@aatulwork/customform-renderer';
 
 const formSchema: FormSchema = {
   title: 'User Registration',
@@ -103,14 +116,22 @@ function App() {
 
 ```typescript
 interface FormSchema {
+  _id?: string;
+  id?: string;        // Legacy support
   title: string;
-  name: string; // Unique identifier
+  name: string;       // Unique identifier (lowercase)
+  module?: string | null;
+  formType?: 'system' | 'custom';
+  collectionName?: string;
   sections?: FormSection[];
   fields?: FormField[]; // Legacy support
   settings?: {
     sectionDisplayMode?: 'panel' | 'stepper';
-    fieldsPerRow?: 1 | 2 | 3;
+    fieldsPerRow?: number; // 1, 2, or 3
+    [key: string]: any;
   };
+  createdAt?: string;
+  updatedAt?: string;
 }
 ```
 
@@ -129,24 +150,32 @@ interface FormSection {
 
 ```typescript
 interface FormField {
-  type: 'text' | 'email' | 'number' | 'select' | 'checkbox' | 'radio' | 
-        'datepicker' | 'file' | 'ckeditor' | 'toggle' | 'color' | 
+  type: 'text' | 'email' | 'number' | 'select' | 'checkbox' | 'radio' |
+        'datepicker' | 'file' | 'ckeditor' | 'toggle' | 'color' |
         'formReference' | 'apiReference';
   name: string;
   label: string;
   required?: boolean;
   placeholder?: string;
+  allowFilter?: boolean;
   options?: OptionItem[] | string[]; // For select/radio
   validation?: {
     min?: number;
     max?: number;
     pattern?: string;
-    maxFileSize?: number; // For file fields
+    maxFileSize?: number;   // For file fields (bytes)
     allowedFileTypes?: string[]; // For file fields
   };
-  allowMultiple?: boolean; // For select/file fields
+  // Reference fields
+  referenceFormName?: string;
+  referenceFieldName?: string;
+  apiEndpoint?: string;
+  referenceModel?: string;
+  apiLabelField?: string;
+  apiValueField?: string;
+  allowMultiple?: boolean;  // For select/file fields
   datePickerMode?: 'date' | 'datetime' | 'time'; // For datepicker
-  // ... other field-specific properties
+  displayTime?: boolean;   // @deprecated Use datePickerMode instead
 }
 ```
 
@@ -187,6 +216,8 @@ interface FormField {
 
 ### Date Picker
 
+Field type is `datepicker`; the exported component is `DateTimePickerField`.
+
 ```typescript
 {
   type: 'datepicker',
@@ -224,29 +255,375 @@ interface FormField {
 
 ### Reference Fields
 
+Reference fields allow you to create dropdown selects that fetch options from other forms or external APIs. There are two types: **Form Reference** and **API Reference**.
+
+#### Form Reference (`formReference`)
+
+Form Reference fields fetch options from entries of another form in your system. This is useful for creating relationships between forms (e.g., selecting a user, product, or category).
+
+**Field Configuration:**
 ```typescript
-// Form Reference
 {
   type: 'formReference',
-  name: 'relatedForm',
-  label: 'Related Form Entry',
-  referenceFormName: 'users',
-  referenceFieldName: 'name',
-  allowMultiple: false
+  name: 'userId',
+  label: 'Select User',
+  required: true,
+  referenceFormName: 'users',        // Name of the form to reference
+  referenceFieldName: 'fullName',   // Field name to display as label
+  allowMultiple: false,             // Allow selecting multiple items
+  placeholder: 'Select a user...'
+}
+```
+
+**Required Service Setup:**
+
+You must provide a `formReference` service that fetches options from your form entries:
+
+```tsx
+import { FormRenderer, FormServices } from '@aatulwork/customform-renderer';
+
+const services: FormServices = {
+  formReference: {
+    fetchOptions: async (formName: string, fieldName: string) => {
+      // Fetch entries from the referenced form
+      const response = await fetch(`/api/forms/${formName}/entries`);
+      const data = await response.json();
+      
+      // Transform entries into OptionItem format
+      return data.map((entry: any) => ({
+        label: entry.payload[fieldName] || entry[fieldName] || entry._id,
+        value: entry._id,
+      }));
+    },
+  },
+};
+
+<FormRenderer
+  formSchema={formSchema}
+  services={services}
+  onSubmit={handleSubmit}
+/>
+```
+
+**Example: Complete Form Reference Setup**
+
+```tsx
+import { FormRenderer, FormServices, FormSchema } from '@aatulwork/customform-renderer';
+
+// Define your form schema with formReference field
+const formSchema: FormSchema = {
+  title: 'Task Assignment',
+  name: 'task-assignment',
+  sections: [
+    {
+      id: 'assignment',
+      title: 'Assignment Details',
+      fields: [
+        {
+          type: 'formReference',
+          name: 'assignedTo',
+          label: 'Assign To',
+          required: true,
+          referenceFormName: 'users',        // References the 'users' form
+          referenceFieldName: 'fullName',   // Displays the 'fullName' field
+          placeholder: 'Select a user...',
+        },
+        {
+          type: 'formReference',
+          name: 'project',
+          label: 'Project',
+          required: true,
+          referenceFormName: 'projects',
+          referenceFieldName: 'title',
+          allowMultiple: false,
+        },
+      ],
+    },
+  ],
+};
+
+// Provide the formReference service
+const services: FormServices = {
+  formReference: {
+    fetchOptions: async (formName: string, fieldName: string) => {
+      try {
+        // Example: Fetch from your API
+        const response = await fetch(`/api/forms/${formName}/entries?status=active`);
+        
+        if (!response.ok) {
+          throw new Error(`Failed to fetch ${formName} entries`);
+        }
+        
+        const entries = await response.json();
+        
+        // Transform to OptionItem format
+        return entries.map((entry: any) => ({
+          label: entry.payload?.[fieldName] || entry[fieldName] || `Entry ${entry._id}`,
+          value: entry._id,
+        }));
+      } catch (error) {
+        console.error(`Error fetching ${formName} options:`, error);
+        return [];
+      }
+    },
+  },
+};
+
+function TaskForm() {
+  const handleSubmit = async (data: Record<string, any>) => {
+    console.log('Assigned to:', data.assignedTo); // Will be the _id of selected user
+    console.log('Project:', data.project);       // Will be the _id of selected project
+    // Submit to your API...
+  };
+
+  return (
+    <FormRenderer
+      formSchema={formSchema}
+      services={services}
+      onSubmit={handleSubmit}
+    />
+  );
 }
+```
 
-// API Reference
+#### API Reference (`apiReference`)
+
+API Reference fields fetch options from any external API endpoint. This is useful for integrating with third-party APIs or your own REST endpoints.
+
+**Field Configuration:**
+```typescript
 {
   type: 'apiReference',
   name: 'role',
-  label: 'Role',
-  apiEndpoint: '/api/roles',
-  apiLabelField: 'name',
-  apiValueField: '_id',
-  allowMultiple: false
+  label: 'Select Role',
+  required: true,
+  apiEndpoint: '/api/roles',         // API endpoint to fetch from
+  apiLabelField: 'name',             // Field name to display as label
+  apiValueField: '_id',              // Field name to use as value (default: '_id')
+  allowMultiple: false,              // Allow selecting multiple items
+  placeholder: 'Select a role...'
 }
 ```
 
+**Required Service Setup:**
+
+You must provide an `apiReference` service that fetches options from your API:
+
+```tsx
+import { FormRenderer, FormServices } from '@aatulwork/customform-renderer';
+
+const services: FormServices = {
+  apiReference: {
+    fetchOptions: async (endpoint: string, labelField: string, valueField = '_id') => {
+      const response = await fetch(endpoint);
+      const data = await response.json();
+      
+      // Handle both array responses and object responses
+      const items = Array.isArray(data) ? data : data.items || data.data || [];
+      
+      return items.map((item: any) => ({
+        label: item[labelField],
+        value: item[valueField],
+      }));
+    },
+  },
+};
+
+<FormRenderer
+  formSchema={formSchema}
+  services={services}
+  onSubmit={handleSubmit}
+/>
+```
+
+**Example: Complete API Reference Setup**
+
+```tsx
+import { FormRenderer, FormServices, FormSchema } from '@aatulwork/customform-renderer';
+
+// Define your form schema with apiReference field
+const formSchema: FormSchema = {
+  title: 'User Registration',
+  name: 'user-registration',
+  sections: [
+    {
+      id: 'user-info',
+      title: 'User Information',
+      fields: [
+        {
+          type: 'text',
+          name: 'firstName',
+          label: 'First Name',
+          required: true,
+        },
+        {
+          type: 'apiReference',
+          name: 'country',
+          label: 'Country',
+          required: true,
+          apiEndpoint: '/api/countries',
+          apiLabelField: 'name',
+          apiValueField: 'code',
+        },
+        {
+          type: 'apiReference',
+          name: 'role',
+          label: 'Role',
+          required: true,
+          apiEndpoint: '/api/roles',
+          apiLabelField: 'name',
+          apiValueField: '_id',  // Default, can be omitted
+        },
+      ],
+    },
+  ],
+};
+
+// Provide the apiReference service
+const services: FormServices = {
+  apiReference: {
+    fetchOptions: async (endpoint: string, labelField: string, valueField = '_id') => {
+      try {
+        const response = await fetch(endpoint, {
+          headers: {
+            'Authorization': `Bearer ${yourAuthToken}`, // Add auth if needed
+            'Content-Type': 'application/json',
+          },
+        });
+        
+        if (!response.ok) {
+          throw new Error(`Failed to fetch from ${endpoint}`);
+        }
+        
+        const data = await response.json();
+        
+        // Handle different response formats
+        const items = Array.isArray(data) 
+          ? data 
+          : data.items || data.data || data.results || [];
+        
+        // Transform to OptionItem format
+        return items.map((item: any) => ({
+          label: item[labelField] || String(item[valueField]),
+          value: item[valueField],
+        }));
+      } catch (error) {
+        console.error(`Error fetching options from ${endpoint}:`, error);
+        return [];
+      }
+    },
+  },
+};
+
+function RegistrationForm() {
+  const handleSubmit = async (data: Record<string, any>) => {
+    console.log('Country code:', data.country); // Will be the country code
+    console.log('Role ID:', data.role);         // Will be the role _id
+    // Submit to your API...
+  };
+
+  return (
+    <FormRenderer
+      formSchema={formSchema}
+      services={services}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+#### Multiple Selection Support
+
+Both reference field types support multiple selections:
+
+```typescript
+{
+  type: 'formReference',
+  name: 'tags',
+  label: 'Tags',
+  referenceFormName: 'tags',
+  referenceFieldName: 'name',
+  allowMultiple: true,  // Enable multiple selection
+}
+```
+
+When `allowMultiple: true`, the field will return an array of selected values.
+
+#### Advanced: Custom API with Query Parameters
+
+You can create dynamic endpoints by modifying the service:
+
+```tsx
+const services: FormServices = {
+  apiReference: {
+    fetchOptions: async (endpoint: string, labelField: string, valueField = '_id') => {
+      // Add query parameters
+      const url = new URL(endpoint, window.location.origin);
+      url.searchParams.append('status', 'active');
+      url.searchParams.append('limit', '100');
+      
+      const response = await fetch(url.toString());
+      const data = await response.json();
+      
+      return data.map((item: any) => ({
+        label: item[labelField],
+        value: item[valueField],
+      }));
+    },
+  },
+};
+```
+
+#### Error Handling
+
+Both services should handle errors gracefully:
+
+```tsx
+const services: FormServices = {
+  formReference: {
+    fetchOptions: async (formName: string, fieldName: string) => {
+      try {
+        const response = await fetch(`/api/forms/${formName}/entries`);
+        if (!response.ok) throw new Error('Failed to fetch');
+        const data = await response.json();
+        return data.map((entry: any) => ({
+          label: entry.payload?.[fieldName] || entry._id,
+          value: entry._id,
+        }));
+      } catch (error) {
+        console.error('Form reference error:', error);
+        return []; // Return empty array on error
+      }
+    },
+  },
+  apiReference: {
+    fetchOptions: async (endpoint: string, labelField: string, valueField = '_id') => {
+      try {
+        const response = await fetch(endpoint);
+        if (!response.ok) throw new Error('Failed to fetch');
+        const data = await response.json();
+        const items = Array.isArray(data) ? data : data.items || [];
+        return items.map((item: any) => ({
+          label: item[labelField],
+          value: item[valueField],
+        }));
+      } catch (error) {
+        console.error('API reference error:', error);
+        return []; // Return empty array on error
+      }
+    },
+  },
+};
+```
+
+#### Notes
+
+- **Loading State**: Reference fields automatically show a loading indicator while fetching options
+- **Disabled State**: Fields are disabled if required configuration is missing (e.g., `referenceFormName` or `apiEndpoint`)
+- **Error Handling**: If the service throws an error or returns empty array, the field will be disabled
+- **Caching**: Options are fetched once when the component mounts and when dependencies change
+- **Custom Select Component**: You can provide a custom `SelectComponent` in services to use your own select component
+
 ## Service Injection
 
 The package uses a service injection pattern to handle external dependencies. You can provide custom services for file uploads, form references, API references, and more.
@@ -254,7 +631,7 @@ The package uses a service injection pattern to handle external dependencies. Yo
 ### Providing Services
 
 ```tsx
-import { FormRenderer, FormServices } from '@custom-form/renderer';
+import { FormRenderer, FormServices } from '@aatulwork/customform-renderer';
 
 const services: FormServices = {
   // File upload service
@@ -339,7 +716,11 @@ interface FormRendererProps {
   allowResetOnValuesChange?: boolean;
   mode?: 'edit' | 'view';
   services?: FormServices;
+  colors?: FormColors;  // Override theme colors (primary, secondary, error, etc.)
 }
+
+// FormColors: primary?, secondary?, error?, success?, warning?, info?,
+// textPrimary?, textSecondary?, divider?, background?, backgroundPaper?
 ```
 
 ## View Mode
@@ -575,7 +956,7 @@ If using Vite, Create React App, or similar:
 
 ```bash
 # Copy CKEditor to your public directory
-cp node_modules/@custom-form/renderer/lib/ckeditor/ckeditor.js public/lib/ckeditor/ckeditor.js
+cp node_modules/@aatulwork/customform-renderer/lib/ckeditor/ckeditor.js public/lib/ckeditor/ckeditor.js
 ```
 
 Then include in HTML:
@@ -588,7 +969,7 @@ Then include in HTML:
 Use the provided hook to load CKEditor dynamically:
 
 ```tsx
-import { useCKEditor } from '@custom-form/renderer';
+import { useCKEditor } from '@aatulwork/customform-renderer';
 
 function App() {
   const { isReady, isLoading, error } = useCKEditor({
@@ -622,12 +1003,12 @@ const services: FormServices = {
 ### CKEditor Utilities
 
 ```tsx
-import { 
-  loadCKEditor, 
-  isCKEditorAvailable, 
+import {
+  loadCKEditor,
+  isCKEditorAvailable,
   waitForCKEditor,
-  useCKEditor 
-} from '@custom-form/renderer';
+  useCKEditor,
+} from '@aatulwork/customform-renderer';
 
 // Check if available
 if (isCKEditorAvailable()) {

package/dist/index.js

@@ -568,12 +568,20 @@ var loadCKEditor = (scriptPath = "/lib/ckeditor/ckeditor.js") => {
       setTimeout(() => {
         clearInterval(checkInterval);
         if (!window.ClassicEditor) {
-          reject(new Error("CKEditor script loaded but ClassicEditor not found on window after 10 seconds"));
+          reject(
+            new Error(
+              "CKEditor script loaded but ClassicEditor was not found on window. Ensure you are using the package-provided build from lib/ckeditor/ckeditor.js (see CKEDITOR_SETUP.md)."
+            )
+          );
         }
       }, 1e4);
     };
     script.onerror = () => {
-      reject(new Error(`Failed to load CKEditor from ${scriptPath}`));
+      reject(
+        new Error(
+          `Failed to load CKEditor from ${scriptPath}. Ensure the file exists at that URL (e.g. copy from node_modules/@aatulwork/customform-renderer/lib/ckeditor/ckeditor.js to public/lib/ckeditor/ckeditor.js) or set services.ckEditorScriptPath to a working URL.`
+        )
+      );
     };
     document.head.appendChild(script);
   });
@@ -705,9 +713,10 @@ var CKEditorField = ({ field, control, defaultValue, rules, errors, setValue, fo
     ] });
   }
   if (ckEditorError || !isCKEditorReady) {
+    const message = ckEditorError?.message || `CKEditor failed to load. Script path: ${ckEditorScriptPath}. Copy ckeditor.js to public/lib/ckeditor/ or set services.ckEditorScriptPath. See CKEDITOR_SETUP.md.`;
     return /* @__PURE__ */ jsxRuntime.jsxs(material.Box, { children: [
       /* @__PURE__ */ jsxRuntime.jsx(material.FormLabel, { required: field.required, error: !!errors[field.name], children: field.label }),
-      /* @__PURE__ */ jsxRuntime.jsx(material.Box, { sx: { p: 2, border: "1px solid", borderColor: formColors.error, borderRadius: 1 }, children: /* @__PURE__ */ jsxRuntime.jsx(material.FormHelperText, { error: true, children: ckEditorError?.message || "CKEditor failed to load. Please ensure the CKEditor script is loaded." }) })
+      /* @__PURE__ */ jsxRuntime.jsx(material.Box, { sx: { p: 2, border: "1px solid", borderColor: formColors.error, borderRadius: 1 }, children: /* @__PURE__ */ jsxRuntime.jsx(material.FormHelperText, { error: true, children: message }) })
     ] });
   }
   return /* @__PURE__ */ jsxRuntime.jsx(