df-ae-forms-package
Version:
A comprehensive React form preview component library with form controls, validation, and responsive design for Angular/Ionic integration
399 lines (316 loc) • 8.97 kB
Markdown
# Troubleshooting Guide
## Common Issues and Solutions
### Issue: "Cannot access 'qi' before initialization" Error
**Error Message:**
```
ReferenceError: Cannot access 'qi' before initialization
at Module.DfFormPreview
```
**Cause:**
This error occurs due to circular dependencies or timing issues when importing the React component in Angular.
**Solution:**
1. **Use Dynamic Imports** - Import the component asynchronously:
```typescript
// In your component
async ngOnInit(): Promise<void> {
await this.reactI18n.initialize();
// Dynamically import to avoid initialization issues
const module = await import('df-ae-forms-package');
this.DfFormPreview = module.DfFormPreview;
this.loading = false;
this.cdr.detectChanges();
}
```
2. **Use setTimeout in renderForm**:
```typescript
ngAfterViewInit(): void {
setTimeout(() => {
this.renderForm();
}, 0);
}
```
3. **Update ReactWrapperService** to use setTimeout:
```typescript
renderReactComponent(containerId: string, component: any, props: any): void {
setTimeout(() => {
// ... rendering code
}, 0);
}
```
4. **Ensure proper initialization order**:
- Initialize i18n first
- Then dynamically import the component
- Then render after view is initialized
### Issue: Styles Not Applying
**Symptoms:**
- Form components render but without styles
- CSS variables not working
- Components look unstyled
**Solutions:**
1. **Check CSS Import:**
```scss
// In src/global.scss or src/styles.scss
@import '~df-ae-forms-package/dist/index.css';
```
2. **Verify Build Configuration:**
- Ensure Angular is configured to include node_modules CSS
- Check `angular.json`:
```json
"styles": [
"node_modules/df-ae-forms-package/dist/index.css",
"src/styles.scss"
]
```
3. **Check CSS Variables:**
```scss
:root {
--df-color-primary: #3880ff;
// ... other variables
}
```
4. **Clear Build Cache:**
```bash
rm -rf .angular
npm run build
```
### Issue: React Components Not Rendering
**Symptoms:**
- Container div is empty
- No errors in console
- Component doesn't appear
**Solutions:**
1. **Check Container Element:**
```typescript
ngAfterViewInit(): void {
// Ensure container exists
if (!this.container?.nativeElement) {
console.error('Container not found');
return;
}
this.renderForm();
}
```
2. **Verify React Root Creation:**
```typescript
// Check if React root is created
console.log('Container:', document.getElementById(containerId));
```
3. **Check for JavaScript Errors:**
- Open browser console
- Look for any React or module errors
- Check network tab for failed module loads
4. **Ensure i18n is Initialized:**
```typescript
async ngOnInit(): Promise<void> {
await this.reactI18n.initialize(); // Must complete first
// Then load component
}
```
### Issue: Form Data Not Loading from API
**Symptoms:**
- Form renders but is empty
- API call succeeds but form doesn't update
**Solutions:**
1. **Check API Response Format:**
```typescript
// Ensure API returns correct format
{
components: FormComponentType[] // Array of form components
}
```
2. **Verify Component Update:**
```typescript
this.formService.getFormTemplate(id).subscribe({
next: (components) => {
this.formComponents = components;
this.cdr.detectChanges(); // Trigger change detection
// Re-render form if needed
setTimeout(() => this.renderForm(), 100);
}
});
```
3. **Check Input Binding:**
```html
<app-form-preview
[formComponents]="formComponents"
[formData]="formData"
></app-form-preview>
```
### Issue: Type Errors
**Symptoms:**
- TypeScript compilation errors
- Type mismatches
**Solutions:**
1. **Install Type Definitions:**
```bash
npm install --save-dev @types/react @types/react-dom
```
2. **Use Type Imports:**
```typescript
import type { FormComponentType, DfFormPreviewProps } from 'df-ae-forms-package';
```
3. **Check TypeScript Configuration:**
```json
{
"compilerOptions": {
"skipLibCheck": true,
"esModuleInterop": true
}
}
```
### Issue: i18n Not Working
**Symptoms:**
- Translation keys show as-is
- "formBuilder.submit" instead of "Submit"
**Solutions:**
1. **Verify i18n Initialization:**
```typescript
async ngOnInit(): Promise<void> {
await this.reactI18n.initialize(); // Must be awaited
}
```
2. **Check Translation Resources:**
```typescript
resources: {
en: {
translation: {
'formBuilder.submit': 'Submit'
}
}
}
```
3. **Ensure react-i18next is Installed:**
```bash
npm install react-i18next i18next
```
### Issue: Memory Leaks
**Symptoms:**
- Performance degrades over time
- Multiple form instances in memory
**Solutions:**
1. **Always Unmount in ngOnDestroy:**
```typescript
ngOnDestroy(): void {
this.reactWrapper.unmountReactComponent(this.containerId);
}
```
2. **Clean Up Subscriptions:**
```typescript
private destroy$ = new Subject<void>();
ngOnInit(): void {
this.formService.getFormTemplate(id)
.pipe(takeUntil(this.destroy$))
.subscribe(/* ... */);
}
ngOnDestroy(): void {
this.destroy$.next();
this.destroy$.complete();
this.reactWrapper.unmountReactComponent(this.containerId);
}
```
### Issue: Form Submission Not Working
**Symptoms:**
- Submit button doesn't trigger
- onSubmit callback not called
**Solutions:**
1. **Check onSubmit Prop:**
```typescript
const props: DfFormPreviewProps = {
// ... other props
onSubmit: (formData: Record<string, any>) => {
console.log('Form submitted:', formData);
// Handle submission
}
};
```
2. **Verify Form Validation:**
- Check if validation errors are preventing submission
- Ensure all required fields are filled
3. **Check Mode:**
```typescript
mode: 'test' // Must be 'test' for interactive forms
```
### Issue: Conditional Logic Not Working
**Symptoms:**
- Fields don't show/hide based on conditions
- Conditional logic seems ignored
**Solutions:**
1. **Verify Conditional Structure:**
```typescript
conditional: {
action: 'show', // or 'hide'
when: 'all', // or 'any'
conditions: [{
fieldId: 'other-field-id',
operator: 'equals', // or other operators
value: 'expected-value'
}]
}
```
2. **Check Field IDs:**
- Ensure fieldId in conditions matches actual component IDs
- IDs must be unique
3. **Verify Form Values:**
- Conditional logic uses current form values
- Ensure values are being tracked correctly
### Issue: Performance Issues
**Symptoms:**
- Slow rendering
- Laggy interactions
**Solutions:**
1. **Use OnPush Change Detection:**
```typescript
@Component({
changeDetection: ChangeDetectionStrategy.OnPush
})
```
2. **Debounce Form Updates:**
```typescript
import { debounceTime } from 'rxjs/operators';
onFormDataChange(formData: Record<string, any>): void {
// Debounce updates
this.updateSubject.next(formData);
}
private updateSubject = new Subject<Record<string, any>>();
ngOnInit(): void {
this.updateSubject.pipe(
debounceTime(300)
).subscribe(data => {
// Handle updates
});
}
```
3. **Lazy Load Forms:**
- Only load form when needed
- Unmount when not visible
## Getting Help
If you're still experiencing issues:
1. Check the browser console for detailed error messages
2. Verify all dependencies are installed correctly
3. Ensure you're using the latest version of the package
4. Review the [Integration Guide](./INTEGRATION-GUIDE.md) for complete setup
5. Check the [README](./README.md) for package-specific documentation
## Debugging Tips
1. **Enable React DevTools:**
```bash
npm install --save-dev @types/react-dom
```
2. **Add Console Logs:**
```typescript
private renderForm(): void {
console.log('Rendering form with:', {
components: this.formComponents.length,
data: this.formData,
container: this.container?.nativeElement
});
// ... rendering code
}
```
3. **Check Network Tab:**
- Verify module loads
- Check for failed requests
- Ensure CSS files load
4. **Inspect DOM:**
- Check if React root is created
- Verify container element exists
- Look for React error boundaries