@aatulwork/customform-renderer 1.1.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aatulwork/customform-renderer",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A powerful, reusable form renderer component for React with Material-UI support",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",