@aatulwork/customform-renderer 1.0.0 → 1.2.0

package/README.md

@@ -224,29 +224,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 '@custom-form/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 '@custom-form/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 (`apiReference`)
 
-// API Reference
+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 '@custom-form/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 '@custom-form/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.

package/dist/index.d.mts

@@ -73,6 +73,7 @@ interface FormRendererProps {
     allowResetOnValuesChange?: boolean;
     mode?: 'edit' | 'view';
     services?: FormServices;
+    colors?: FormColors;
 }
 interface FormServices {
     fileUpload?: FileUploadService;
@@ -115,6 +116,19 @@ interface DateFormatterService {
         datePickerMode?: 'date' | 'datetime' | 'time';
     }) => string;
 }
+interface FormColors {
+    primary?: string;
+    secondary?: string;
+    error?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    textPrimary?: string;
+    textSecondary?: string;
+    divider?: string;
+    background?: string;
+    backgroundPaper?: string;
+}
 interface FieldRendererProps {
     field: FormField;
     control: any;
@@ -131,9 +145,10 @@ interface FieldRendererProps {
     }) => void;
     clearErrors?: (name?: string) => void;
     services?: FormServices;
+    colors?: FormColors;
 }
 
-declare const FormRenderer: ({ formSchema, onSubmit, onCancel, isLoading, onSuccess, initialValues, hideTitle, allowResetOnValuesChange, mode, services, }: FormRendererProps) => react_jsx_runtime.JSX.Element;
+declare const FormRenderer: ({ formSchema, onSubmit, onCancel, isLoading, onSuccess, initialValues, hideTitle, allowResetOnValuesChange, mode, services, colors, }: FormRendererProps) => react_jsx_runtime.JSX.Element;
 
 interface FieldRendererComponentProps extends Omit<FieldRendererProps, 'defaultValue' | 'rules'> {
     formSchema: any;
@@ -152,8 +167,9 @@ interface FormViewModeProps {
     initialValues?: Record<string, any>;
     hideTitle?: boolean;
     services?: FormServices;
+    colors?: FormColors;
 }
-declare const FormViewMode: ({ formSchema, initialValues, hideTitle, services }: FormViewModeProps) => react_jsx_runtime.JSX.Element;
+declare const FormViewMode: ({ formSchema, initialValues, hideTitle, services, colors }: FormViewModeProps) => react_jsx_runtime.JSX.Element;
 
 interface FieldViewProps {
     field: FormField;
@@ -181,7 +197,7 @@ declare global {
         ClassicEditor: any;
     }
 }
-declare const CKEditorField: ({ field, control, defaultValue, rules, errors, setValue, formSchema, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
+declare const CKEditorField: ({ field, control, defaultValue, rules, errors, setValue, formSchema, services, colors }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
 
 interface FileFieldProps extends FieldRendererProps {
     uploadingFiles?: Record<string, boolean>;
@@ -192,7 +208,7 @@ interface FileFieldProps extends FieldRendererProps {
     }) => void;
     clearErrors?: (name?: string) => void;
 }
-declare const FileField: ({ field, control, defaultValue, rules, errors, formSchema, uploadingFiles, setUploadingFiles, setError, clearErrors, services, }: FileFieldProps) => react_jsx_runtime.JSX.Element;
+declare const FileField: ({ field, control, defaultValue, rules, errors, formSchema, uploadingFiles, setUploadingFiles, setError, clearErrors, services, colors, }: FileFieldProps) => react_jsx_runtime.JSX.Element;
 
 declare const FormReferenceField: ({ field, control, defaultValue, rules, errors, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
 declare const ApiReferenceField: ({ field, control, defaultValue, rules, errors, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
@@ -349,4 +365,4 @@ declare const defaultApiReferenceService: ApiReferenceService;
  */
 declare const defaultDateFormatterService: DateFormatterService;
 
-export { ApiReferenceField, type ApiReferenceService, CKEditorField, CheckboxField, ColorField, type DateFormatterService, DateTimePickerField, FieldRenderer, type FieldRendererProps, type FieldType, type FieldValidation, FieldView, FileField, type FileUploadService, type FormField, FormReferenceField, type FormReferenceService, FormRenderer, type FormRendererProps, type FormSchema, type FormSection, type FormServices, FormViewMode, type OptionItem, RadioField, SelectField, SimpleSelect, type SimpleSelectOption, type SimpleSelectProps, TextField, ToggleField, type UploadedFile, buildFieldRules, defaultApiReferenceService, defaultDateFormatterService, defaultFileUploadService, defaultFormReferenceService, formatFileSize, getAllFields, getDefaultValue, isCKEditorAvailable, loadCKEditor, normalizeInitialValues, normalizeOptions, transformFormValues, useCKEditor, validateFile, waitForCKEditor };
+export { ApiReferenceField, type ApiReferenceService, CKEditorField, CheckboxField, ColorField, type DateFormatterService, DateTimePickerField, FieldRenderer, type FieldRendererProps, type FieldType, type FieldValidation, FieldView, FileField, type FileUploadService, type FormColors, type FormField, FormReferenceField, type FormReferenceService, FormRenderer, type FormRendererProps, type FormSchema, type FormSection, type FormServices, FormViewMode, type OptionItem, RadioField, SelectField, SimpleSelect, type SimpleSelectOption, type SimpleSelectProps, TextField, ToggleField, type UploadedFile, buildFieldRules, defaultApiReferenceService, defaultDateFormatterService, defaultFileUploadService, defaultFormReferenceService, formatFileSize, getAllFields, getDefaultValue, isCKEditorAvailable, loadCKEditor, normalizeInitialValues, normalizeOptions, transformFormValues, useCKEditor, validateFile, waitForCKEditor };

package/dist/index.d.ts

@@ -73,6 +73,7 @@ interface FormRendererProps {
     allowResetOnValuesChange?: boolean;
     mode?: 'edit' | 'view';
     services?: FormServices;
+    colors?: FormColors;
 }
 interface FormServices {
     fileUpload?: FileUploadService;
@@ -115,6 +116,19 @@ interface DateFormatterService {
         datePickerMode?: 'date' | 'datetime' | 'time';
     }) => string;
 }
+interface FormColors {
+    primary?: string;
+    secondary?: string;
+    error?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    textPrimary?: string;
+    textSecondary?: string;
+    divider?: string;
+    background?: string;
+    backgroundPaper?: string;
+}
 interface FieldRendererProps {
     field: FormField;
     control: any;
@@ -131,9 +145,10 @@ interface FieldRendererProps {
     }) => void;
     clearErrors?: (name?: string) => void;
     services?: FormServices;
+    colors?: FormColors;
 }
 
-declare const FormRenderer: ({ formSchema, onSubmit, onCancel, isLoading, onSuccess, initialValues, hideTitle, allowResetOnValuesChange, mode, services, }: FormRendererProps) => react_jsx_runtime.JSX.Element;
+declare const FormRenderer: ({ formSchema, onSubmit, onCancel, isLoading, onSuccess, initialValues, hideTitle, allowResetOnValuesChange, mode, services, colors, }: FormRendererProps) => react_jsx_runtime.JSX.Element;
 
 interface FieldRendererComponentProps extends Omit<FieldRendererProps, 'defaultValue' | 'rules'> {
     formSchema: any;
@@ -152,8 +167,9 @@ interface FormViewModeProps {
     initialValues?: Record<string, any>;
     hideTitle?: boolean;
     services?: FormServices;
+    colors?: FormColors;
 }
-declare const FormViewMode: ({ formSchema, initialValues, hideTitle, services }: FormViewModeProps) => react_jsx_runtime.JSX.Element;
+declare const FormViewMode: ({ formSchema, initialValues, hideTitle, services, colors }: FormViewModeProps) => react_jsx_runtime.JSX.Element;
 
 interface FieldViewProps {
     field: FormField;
@@ -181,7 +197,7 @@ declare global {
         ClassicEditor: any;
     }
 }
-declare const CKEditorField: ({ field, control, defaultValue, rules, errors, setValue, formSchema, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
+declare const CKEditorField: ({ field, control, defaultValue, rules, errors, setValue, formSchema, services, colors }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
 
 interface FileFieldProps extends FieldRendererProps {
     uploadingFiles?: Record<string, boolean>;
@@ -192,7 +208,7 @@ interface FileFieldProps extends FieldRendererProps {
     }) => void;
     clearErrors?: (name?: string) => void;
 }
-declare const FileField: ({ field, control, defaultValue, rules, errors, formSchema, uploadingFiles, setUploadingFiles, setError, clearErrors, services, }: FileFieldProps) => react_jsx_runtime.JSX.Element;
+declare const FileField: ({ field, control, defaultValue, rules, errors, formSchema, uploadingFiles, setUploadingFiles, setError, clearErrors, services, colors, }: FileFieldProps) => react_jsx_runtime.JSX.Element;
 
 declare const FormReferenceField: ({ field, control, defaultValue, rules, errors, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
 declare const ApiReferenceField: ({ field, control, defaultValue, rules, errors, services }: FieldRendererProps) => react_jsx_runtime.JSX.Element;
@@ -349,4 +365,4 @@ declare const defaultApiReferenceService: ApiReferenceService;
  */
 declare const defaultDateFormatterService: DateFormatterService;
 
-export { ApiReferenceField, type ApiReferenceService, CKEditorField, CheckboxField, ColorField, type DateFormatterService, DateTimePickerField, FieldRenderer, type FieldRendererProps, type FieldType, type FieldValidation, FieldView, FileField, type FileUploadService, type FormField, FormReferenceField, type FormReferenceService, FormRenderer, type FormRendererProps, type FormSchema, type FormSection, type FormServices, FormViewMode, type OptionItem, RadioField, SelectField, SimpleSelect, type SimpleSelectOption, type SimpleSelectProps, TextField, ToggleField, type UploadedFile, buildFieldRules, defaultApiReferenceService, defaultDateFormatterService, defaultFileUploadService, defaultFormReferenceService, formatFileSize, getAllFields, getDefaultValue, isCKEditorAvailable, loadCKEditor, normalizeInitialValues, normalizeOptions, transformFormValues, useCKEditor, validateFile, waitForCKEditor };
+export { ApiReferenceField, type ApiReferenceService, CKEditorField, CheckboxField, ColorField, type DateFormatterService, DateTimePickerField, FieldRenderer, type FieldRendererProps, type FieldType, type FieldValidation, FieldView, FileField, type FileUploadService, type FormColors, type FormField, FormReferenceField, type FormReferenceService, FormRenderer, type FormRendererProps, type FormSchema, type FormSection, type FormServices, FormViewMode, type OptionItem, RadioField, SelectField, SimpleSelect, type SimpleSelectOption, type SimpleSelectProps, TextField, ToggleField, type UploadedFile, buildFieldRules, defaultApiReferenceService, defaultDateFormatterService, defaultFileUploadService, defaultFormReferenceService, formatFileSize, getAllFields, getDefaultValue, isCKEditorAvailable, loadCKEditor, normalizeInitialValues, normalizeOptions, transformFormValues, useCKEditor, validateFile, waitForCKEditor };