@aatulwork/customform-renderer 1.0.0

package/README.md

@@ -0,0 +1,653 @@
+# @custom-form/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.
+
+## Features
+
+- 🎨 **Material-UI Integration** - Built with Material-UI components
+- 📝 **13 Field Types** - Text, Email, Number, Select, Checkbox, Radio, DatePicker, File, CKEditor, Toggle, Color, FormReference, ApiReference
+- ✅ **Form Validation** - Built-in validation with react-hook-form
+- 📱 **Responsive Design** - Mobile-friendly layouts
+- 🎯 **Multiple Layouts** - Accordion panels, stepper, and grid layouts
+- 👁️ **View Mode** - Read-only view mode for displaying form data
+- 🔌 **Service Injection** - Extensible architecture with injectable services
+- 📦 **TypeScript** - Fully typed with TypeScript
+
+## Installation
+
+```bash
+npm install @custom-form/renderer
+```
+
+### Peer Dependencies
+
+Make sure you have these peer dependencies installed:
+
+```bash
+npm install react react-dom @mui/material @mui/icons-material @mui/x-date-pickers react-hook-form @tanstack/react-query dayjs @ckeditor/ckeditor5-react
+```
+
+### CKEditor Setup
+
+The package includes CKEditor in the `lib/ckeditor/` directory. You need to load it before using CKEditor fields.
+
+**Option 1: Include in HTML (Recommended)**
+```html
+<script src="/lib/ckeditor/ckeditor.js"></script>
+```
+
+**Option 2: Copy to your public directory**
+```bash
+cp node_modules/@custom-form/renderer/lib/ckeditor/ckeditor.js public/lib/ckeditor/
+```
+
+**Option 3: Use dynamic loading**
+```tsx
+import { useCKEditor } from '@custom-form/renderer';
+
+const { isReady } = useCKEditor({ autoLoad: true });
+```
+
+See [CKEditor Setup Guide](#ckeditor-setup) for more details.
+
+## Quick Start
+
+```tsx
+import { FormRenderer } from '@custom-form/renderer';
+import { FormSchema } from '@custom-form/renderer';
+
+const formSchema: FormSchema = {
+  title: 'User Registration',
+  name: 'user-registration',
+  sections: [
+    {
+      id: 'personal-info',
+      title: 'Personal Information',
+      fields: [
+        {
+          type: 'text',
+          name: 'firstName',
+          label: 'First Name',
+          required: true,
+        },
+        {
+          type: 'email',
+          name: 'email',
+          label: 'Email',
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+function App() {
+  const handleSubmit = async (data: Record<string, any>) => {
+    console.log('Form data:', data);
+    // Handle form submission
+  };
+
+  return (
+    <FormRenderer
+      formSchema={formSchema}
+      onSubmit={handleSubmit}
+      onSuccess={() => console.log('Form submitted successfully!')}
+    />
+  );
+}
+```
+
+## Form Schema Structure
+
+### Basic Schema
+
+```typescript
+interface FormSchema {
+  title: string;
+  name: string; // Unique identifier
+  sections?: FormSection[];
+  fields?: FormField[]; // Legacy support
+  settings?: {
+    sectionDisplayMode?: 'panel' | 'stepper';
+    fieldsPerRow?: 1 | 2 | 3;
+  };
+}
+```
+
+### Form Section
+
+```typescript
+interface FormSection {
+  id: string;
+  title: string;
+  description?: string;
+  fields: FormField[];
+}
+```
+
+### Form Field
+
+```typescript
+interface FormField {
+  type: 'text' | 'email' | 'number' | 'select' | 'checkbox' | 'radio' | 
+        'datepicker' | 'file' | 'ckeditor' | 'toggle' | 'color' | 
+        'formReference' | 'apiReference';
+  name: string;
+  label: string;
+  required?: boolean;
+  placeholder?: string;
+  options?: OptionItem[] | string[]; // For select/radio
+  validation?: {
+    min?: number;
+    max?: number;
+    pattern?: string;
+    maxFileSize?: number; // For file fields
+    allowedFileTypes?: string[]; // For file fields
+  };
+  allowMultiple?: boolean; // For select/file fields
+  datePickerMode?: 'date' | 'datetime' | 'time'; // For datepicker
+  // ... other field-specific properties
+}
+```
+
+## Field Types
+
+### Text Fields
+
+```typescript
+{
+  type: 'text' | 'email' | 'number',
+  name: 'fieldName',
+  label: 'Field Label',
+  required: true,
+  placeholder: 'Enter value',
+  validation: {
+    min: 0,
+    max: 100,
+    pattern: '^[A-Za-z]+$'
+  }
+}
+```
+
+### Select Field
+
+```typescript
+{
+  type: 'select',
+  name: 'country',
+  label: 'Country',
+  required: true,
+  allowMultiple: false,
+  options: [
+    { label: 'United States', value: 'us' },
+    { label: 'Canada', value: 'ca' },
+  ]
+}
+```
+
+### Date Picker
+
+```typescript
+{
+  type: 'datepicker',
+  name: 'birthDate',
+  label: 'Birth Date',
+  datePickerMode: 'date', // 'date' | 'datetime' | 'time'
+}
+```
+
+### File Upload
+
+```typescript
+{
+  type: 'file',
+  name: 'documents',
+  label: 'Upload Documents',
+  allowMultiple: true,
+  validation: {
+    maxFileSize: 5242880, // 5MB in bytes
+    allowedFileTypes: ['pdf', 'doc', 'docx']
+  }
+}
+```
+
+### CKEditor (Rich Text)
+
+```typescript
+{
+  type: 'ckeditor',
+  name: 'description',
+  label: 'Description',
+  required: true
+}
+```
+
+### Reference Fields
+
+```typescript
+// Form Reference
+{
+  type: 'formReference',
+  name: 'relatedForm',
+  label: 'Related Form Entry',
+  referenceFormName: 'users',
+  referenceFieldName: 'name',
+  allowMultiple: false
+}
+
+// API Reference
+{
+  type: 'apiReference',
+  name: 'role',
+  label: 'Role',
+  apiEndpoint: '/api/roles',
+  apiLabelField: 'name',
+  apiValueField: '_id',
+  allowMultiple: false
+}
+```
+
+## 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.
+
+### Providing Services
+
+```tsx
+import { FormRenderer, FormServices } from '@custom-form/renderer';
+
+const services: FormServices = {
+  // File upload service
+  fileUpload: {
+    uploadFiles: async (formName, fieldName, files) => {
+      // Your upload implementation
+      const formData = new FormData();
+      files.forEach(file => formData.append('files', file));
+      
+      const response = await fetch('/api/upload', {
+        method: 'POST',
+        body: formData,
+      });
+      
+      return response.json();
+    },
+  },
+  
+  // Form reference service
+  formReference: {
+    fetchOptions: async (formName, fieldName) => {
+      const response = await fetch(`/api/forms/${formName}/entries`);
+      const data = await response.json();
+      return data.map(entry => ({
+        label: entry.payload[fieldName],
+        value: entry._id,
+      }));
+    },
+  },
+  
+  // API reference service
+  apiReference: {
+    fetchOptions: async (endpoint, labelField, valueField = '_id') => {
+      const response = await fetch(endpoint);
+      const data = await response.json();
+      return data.map(item => ({
+        label: item[labelField],
+        value: item[valueField],
+      }));
+    },
+  },
+  
+  // Date formatter
+  dateFormatter: {
+    format: (value, options) => {
+      // Your date formatting logic
+      return new Date(value).toLocaleDateString();
+    },
+  },
+  
+  // File base URL for displaying uploaded files
+  fileBaseUrl: 'https://your-cdn.com/uploads/',
+  
+  // CKEditor license key
+  ckEditorLicenseKey: 'your-license-key',
+};
+
+function App() {
+  return (
+    <FormRenderer
+      formSchema={formSchema}
+      onSubmit={handleSubmit}
+      services={services}
+    />
+  );
+}
+```
+
+## Props
+
+### FormRenderer Props
+
+```typescript
+interface FormRendererProps {
+  formSchema: FormSchema;
+  onSubmit?: (data: Record<string, any>) => void | Promise<void>;
+  onCancel?: () => void;
+  isLoading?: boolean;
+  onSuccess?: () => void;
+  initialValues?: Record<string, any>;
+  hideTitle?: boolean;
+  allowResetOnValuesChange?: boolean;
+  mode?: 'edit' | 'view';
+  services?: FormServices;
+}
+```
+
+## View Mode
+
+You can render forms in read-only view mode:
+
+```tsx
+<FormRenderer
+  formSchema={formSchema}
+  initialValues={{
+    firstName: 'John',
+    email: 'john@example.com',
+  }}
+  mode="view"
+  services={services}
+/>
+```
+
+## Custom Components
+
+You can provide custom components for specific use cases:
+
+```typescript
+const services: FormServices = {
+  // Custom select component (e.g., searchable select)
+  SelectComponent: MyCustomSelectComponent,
+  
+  // Custom file display component
+  FileDisplayComponent: MyFileDisplayComponent,
+  
+  // Custom CKEditor display component
+  CKEditorDisplayComponent: MyCKEditorDisplayComponent,
+};
+```
+
+## Examples
+
+### Basic Form
+
+```tsx
+const schema: FormSchema = {
+  title: 'Contact Form',
+  name: 'contact',
+  sections: [
+    {
+      id: 'contact-info',
+      title: 'Contact Information',
+      fields: [
+        { type: 'text', name: 'name', label: 'Name', required: true },
+        { type: 'email', name: 'email', label: 'Email', required: true },
+        { type: 'text', name: 'phone', label: 'Phone' },
+      ],
+    },
+  ],
+};
+```
+
+### Form with Stepper
+
+```tsx
+const schema: FormSchema = {
+  title: 'Multi-Step Form',
+  name: 'multistep',
+  settings: {
+    sectionDisplayMode: 'stepper',
+  },
+  sections: [
+    {
+      id: 'step1',
+      title: 'Step 1',
+      fields: [/* fields */],
+    },
+    {
+      id: 'step2',
+      title: 'Step 2',
+      fields: [/* fields */],
+    },
+  ],
+};
+```
+
+### Form with Grid Layout
+
+```tsx
+const schema: FormSchema = {
+  title: 'Grid Form',
+  name: 'grid-form',
+  settings: {
+    fieldsPerRow: 2, // 1, 2, or 3 columns
+  },
+  sections: [
+    {
+      id: 'grid-section',
+      title: 'Grid Section',
+      fields: [/* fields will be displayed in 2 columns */],
+    },
+  ],
+};
+```
+
+## Building
+
+To build the package:
+
+```bash
+npm run build
+```
+
+This will generate:
+- `dist/index.js` - CommonJS build
+- `dist/index.esm.js` - ES Module build
+- `dist/index.d.ts` - TypeScript definitions
+
+### Build Commands
+
+```bash
+# Standard build
+npm run build
+
+# Clean build (removes dist first)
+npm run build:clean
+
+# Watch mode (development)
+npm run dev
+# or
+npm run build:watch
+
+# Type check only
+npm run lint:check
+```
+
+## Publishing
+
+### Quick Publish
+
+```bash
+# Patch version (1.0.0 -> 1.0.1) + build + publish
+npm run publish:patch
+
+# Minor version (1.0.0 -> 1.1.0) + build + publish
+npm run publish:minor
+
+# Major version (1.0.0 -> 2.0.0) + build + publish
+npm run publish:major
+```
+
+### Publish with Tags
+
+```bash
+# Publish as beta
+npm run publish:beta
+
+# Publish as next
+npm run publish:next
+
+# Publish as public (for scoped packages)
+npm run publish:public
+```
+
+### Dry Run (Test)
+
+```bash
+npm run publish:dry-run
+```
+
+### Interactive Publish Scripts
+
+**Linux/Mac:**
+```bash
+chmod +x scripts/publish.sh
+./scripts/publish.sh
+```
+
+**Windows:**
+```powershell
+.\scripts\publish.ps1
+```
+
+### Manual Publish Steps
+
+1. **Bump version** (if needed):
+   ```bash
+   npm run version:patch  # or :minor or :major
+   ```
+
+2. **Build**:
+   ```bash
+   npm run build
+   ```
+
+3. **Publish**:
+   ```bash
+   npm publish --access public
+   ```
+
+For detailed publishing instructions, see [PUBLISH_GUIDE.md](./PUBLISH_GUIDE.md).
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build in watch mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Type check
+npm run lint:check
+```
+
+## CKEditor Setup
+
+CKEditor is required for the `ckeditor` field type. The package includes the CKEditor build file.
+
+### Setup Methods
+
+#### Method 1: HTML Script Tag (Recommended)
+
+Add to your `index.html` or main HTML file:
+
+```html
+<script src="/lib/ckeditor/ckeditor.js"></script>
+```
+
+Make sure the file is accessible at `/lib/ckeditor/ckeditor.js` (or copy it to your public directory).
+
+#### Method 2: Copy to Public Directory
+
+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
+```
+
+Then include in HTML:
+```html
+<script src="/lib/ckeditor/ckeditor.js"></script>
+```
+
+#### Method 3: Dynamic Loading
+
+Use the provided hook to load CKEditor dynamically:
+
+```tsx
+import { useCKEditor } from '@custom-form/renderer';
+
+function App() {
+  const { isReady, isLoading, error } = useCKEditor({
+    scriptPath: '/lib/ckeditor/ckeditor.js',
+    autoLoad: true,
+  });
+
+  if (isLoading) {
+    return <div>Loading editor...</div>;
+  }
+
+  if (error) {
+    return <div>Error loading editor: {error.message}</div>;
+  }
+
+  return <FormRenderer formSchema={schema} />;
+}
+```
+
+#### Method 4: Custom Script Path
+
+If CKEditor is hosted elsewhere:
+
+```tsx
+const services: FormServices = {
+  ckEditorScriptPath: 'https://cdn.example.com/ckeditor.js',
+  // ... other services
+};
+```
+
+### CKEditor Utilities
+
+```tsx
+import { 
+  loadCKEditor, 
+  isCKEditorAvailable, 
+  waitForCKEditor,
+  useCKEditor 
+} from '@custom-form/renderer';
+
+// Check if available
+if (isCKEditorAvailable()) {
+  // CKEditor is ready
+}
+
+// Load manually
+await loadCKEditor('/lib/ckeditor/ckeditor.js');
+
+// Wait for it to become available
+await waitForCKEditor(10000); // 10 second timeout
+
+// React hook
+const { isReady, isLoading, error, load } = useCKEditor();
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.