DF AE Forms Package

A comprehensive React form preview component library with form controls, validation, conditional logic, and responsive design. This package provides a complete set of form components that can be used to build dynamic forms with real-time validation, conditional logic, threshold alerts, and component actions. Designed for integration with Angular/Ionic applications.

Features

- 🎨 Responsive Design: Desktop, tablet, and mobile views
- ✅ Form Validation: Real-time validation with custom error messages
- 🔧 Form Controls: Complete set of form input components (text, number, email, textarea, select, checkbox, radio, segment, date/time, signature, file upload, location, heading, instructions, section, table, datagrid)
- 🎯 Conditional Logic: Show/hide fields based on other field values
- 📊 Threshold Alerts: Visual alerts when threshold conditions are met
- 📝 Component Actions: Add notes, attachments, send emails, and raise issues for form components
- 📱 Device Preview: Preview forms in different device sizes
- 🎨 Customizable Styling: CSS variables for easy theming
- 📦 TypeScript: Full TypeScript support with comprehensive type definitions
- 🔄 Drag and Drop: Optional drag-and-drop support for form sections and grids (edit mode only)

Installation

``bash
npm install df-ae-forms-package
`

Peer Dependencies

This package requires the following peer dependencies to be installed in your project:

`bash
npm install react react-dom lucide-react @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
`

Note: Translation dependencies have been removed. The package no longer requires react-i18next or i18next.

Quick Start

$3

First, import the package styles in your application:

`tsx
import 'df-ae-forms-package/dist/index.css';
`

$3

`tsx
import React from 'react';
import { DfFormPreview, FormComponentType } from 'df-ae-forms-package';
import 'df-ae-forms-package/dist/index.css';

const formComponents: FormComponentType[] = [
{
id: 'name',
name: 'text-input',
basic: {
label: 'Full Name',
placeholder: 'Enter your full name',
defaultValue: ''
},
validation: {
required: true,
minLength: 2,
maxLength: 50
}
},
{
id: 'email',
name: 'email-input',
basic: {
label: 'Email Address',
placeholder: 'Enter your email',
defaultValue: ''
},
validation: {
required: true
}
}
];

function MyForm() {
const handleSubmit = (formData: Record) => {
console.log('Form submitted:', formData);
};

const handleFormDataChange = (formData: Record) => {
console.log('Form data changed:', formData);
};

return (
formComponents={formComponents}
currentDevice="desktop"
mode="test"
onSubmit={handleSubmit}
onFormDataChange={handleFormDataChange}
/>
);
}
`

Components

$3

The main form preview component that renders all form controls.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| formComponents | FormComponentType[] | [] | Array of form components to render |
| currentDevice | 'desktop' \| 'tablet' \| 'mobile' | 'desktop' | Device type for responsive preview |
| mode | 'edit' \| 'preview' \| 'test' | 'test' | Form mode: edit (with drag-drop), preview (readonly), test (interactive) |
| initialFormData | Record | {} | Initial form data with default values |
| onSubmit | (formData: Record) => void | - | Callback when form is submitted |
| onFormDataChange | (formData: Record) => void | - | Callback when form data changes |
| onComponentUpdate | (change: IFormControlChange) => void | - | Callback when a component value changes |
| selectedComponent | string \| null | null | Currently selected component ID (for edit mode) |
| formTemplateId | string | - | Form template ID (for component actions) |
| onThresholdActionCompletion | (conditionId: string, action: string, completed: boolean) => void | - | Callback when threshold action is completed |
| onThresholdIssueRaised | (conditionId: string) => void | - | Callback when threshold issue is raised |
| onNotesChange | (componentId: string, notes: string) => void | - | Callback when component notes change |
| onAttachmentChange | (componentId: string, attachments: File[]) => void | - | Callback when component attachments change |

$3

The package includes the following form control components:

- DfFormInput: Text, number, and email input fields
- DfFormTextarea: Multi-line text input
- DfFormSelect: Dropdown selection
- DfFormCheckbox: Checkbox inputs
- DfFormRadio: Radio button selection
- DfFormSegment: Segment/button group selection
- DfFormDateTime: Date and time inputs
- DfFormSignature: Signature pad component
- DfFormFileUpload: File upload component
- DfFormLocation: Location picker component
- DfFormHeading: Heading component for form sections
- DfFormInstruction: Instruction text component
- DfFormSection: Section container with collapsible children
- DfFormDataGrid: Data grid component for tabular data
- DfFormTable: Table component with nested form controls
- DfFormComments: Comments component
- DfFormErrorMsg: Error message display component

Conditional Logic

You can show/hide fields based on other field values:

`tsx
{
id: 'has-phone',
name: 'checkbox',
basic: {
label: 'Do you have a phone number?',
defaultValue: false
},
options: [
{ label: 'Yes', value: 'yes' }
]
},
{
id: 'phone',
name: 'text-input',
basic: {
label: 'Phone Number',
placeholder: 'Enter phone number',
defaultValue: ''
},
conditional: {
action: 'show',
when: 'all',
conditions: [{
fieldId: 'has-phone',
operator: 'equals',
value: 'yes'
}]
}
}
`

Threshold Alerts

Components can have threshold conditions that trigger alerts:

`tsx
{
id: 'temperature',
name: 'number-input',
basic: {
label: 'Temperature',
defaultValue: 0
},
threshold: {
conditions: [{
id: 'high-temp',
operator: 'greaterThan',
value: 100,
alertMessage: 'Temperature is too high!',
actions: ['notes', 'attachments', 'email']
}]
}
}
`

Component Actions

In test mode, components can have action features:
- Notes: Add notes to components
- Attachments: Attach files to components
- Email: Send email notifications
- Raise Issue: Raise an issue for the component

Styling

The package uses CSS variables for theming. You can override these variables in your application:

`css
:root {
--df-color-primary: #3b82f6;
--df-color-primary-hover: #2563eb;
--df-color-primary-disabled: #9ca3af;
--df-color-error-primary: #ef4444;
--df-color-success-primary: #10b981;
--df-color-text-dark: #1f2937;
--df-color-text-light: #6b7280;
--df-color-fb-container: #ffffff;
--df-color-fb-border: #e5e7eb;
--df-color-fb-bg: #f9fafb;
}
`

Import the design system CSS to get all the base styles:

`tsx
import 'df-ae-forms-package/dist/index.css';
`

TypeScript Support

The package is fully typed with TypeScript. All types are exported:

`tsx
import type {
FormComponentType,
IFormControlChange,
IFormValidationErrors,
DfFormPreviewProps,
// ... and many more
} from 'df-ae-forms-package';
`

Development

$3

- Node.js >= 14.0.0
- npm >= 6.0.0

$3

1. Clone the repository
2. Install dependencies:
`bash
cd df-ae-forms-package
npm install
`

$3

- npm run build - Build the package for production
- npm run build:watch - Build and watch for changes
- npm run dev - Development mode with watch
- npm run clean - Clean the dist directory
- npm run lint - Run ESLint
- npm run type-check - Run TypeScript type checking

$3

`bash
npm run build
`

This will create the following files in the dist directory:
- index.js - CommonJS build
- index.esm.js - ES modules build
- index.d.ts - TypeScript declarations
- index.css - Compiled CSS

Publishing

$3

1. NPM Account: Create an account at npmjs.com
2. Login to NPM: Run npm login in your terminal
3. Package Name: Ensure the package name df-ae-forms-package is available

$3

#### 1. Prepare the Package

`bash

Clean previous builds

npm run clean

Build the package

npm run build

Run type checking

npm run type-check

Run linting

npm run lint
`

#### 2. Test the Package Locally

`bash

Pack the package to test it

npm pack

This creates a .tgz file that you can test locally

Install it in a test project:

npm install /path/to/df-ae-forms-package-1.0.0.tgz

`

#### 3. Publish to NPM

For Patch Version (1.0.0 → 1.0.1):
`bash
npm run publish:patch
`

For Minor Version (1.0.0 → 1.1.0):
`bash
npm run publish:minor
`

For Major Version (1.0.0 → 2.0.0):
`bash
npm run publish:major
`

Manual Publishing:
`bash

Update version manually

npm version patch # or minor, major

Publish

npm publish
`

#### 4. Verify Publication

1. Check your package on npmjs.com
2. Test installation in a new project:
`bash
npm install df-ae-forms-package
`

$3

- [ ] All tests pass
- [ ] TypeScript compilation succeeds
- [ ] ESLint passes
- [ ] Package builds successfully
- [ ] README.md is up to date
- [ ] Version number is correct
- [ ] All dependencies are properly listed
- [ ] Package is tested locally with npm pack

Integration with Angular/Ionic

This package is designed to work with Angular/Ionic applications.

$3

- Quick Start Guide - Get up and running in 5 minutes
- Complete Integration Guide - Detailed step-by-step instructions with examples

$3

1. Install dependencies:
`bash
npm install df-ae-forms-package react react-dom lucide-react @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
`

2. Import styles in src/global.scss:
`scss
@import '~df-ae-forms-package/dist/index.css';
`

3. Set up React bridge (see Integration Guide)

4. Load form data from API and pass to the component

For complete instructions, code examples, API integration, styling, and troubleshooting, see:
- Quick Start Guide - For a condensed setup guide
- Integration Guide - For comprehensive documentation

Troubleshooting

$3

- Make sure you're importing the CSS file: import 'df-ae-forms-package/dist/index.css';
- Check that CSS variables are properly defined in your application
- Verify that the build includes the CSS file in the dist directory

$3

- Check that formComponents` array is not empty
- Verify that conditional logic is not hiding components
- Ensure that component IDs are unique

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the build and tests
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:
- Create an issue on GitHub
- Check the documentation
- Review the examples in the README

Changelog

$3

- Initial release
- Complete form preview component
- All form controls (input, textarea, select, checkbox, radio, segment, date, signature, file upload, location, heading, instructions, section, table, datagrid)
- Validation system
- Conditional logic
- Threshold alerts
- Component actions (notes, attachments, email, raise issue)
- Responsive design
- TypeScript support
- Drag and drop support (edit mode)