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

npm install df-ae-forms-package

Peer Dependencies

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

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

1. Import CSS

First, import the package styles in your application:

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

2. Use the Component

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<string, any>) => {
    console.log('Form submitted:', formData);
  };

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

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

Components

DfFormPreview

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<string, any> | {} | Initial form data with default values | | onSubmit | (formData: Record<string, any>) => void | - | Callback when form is submitted | | onFormDataChange | (formData: Record<string, any>) => 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 |

Form Controls

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:

{
  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:

{
  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:

: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:

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

TypeScript Support

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

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

Development

Prerequisites

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

Setup

1. Clone the repository
2. Install dependencies:

   cd df-ae-forms-package
   npm install

Available Scripts

• 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

Building

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

Prerequisites for Publishing

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

Publishing Steps

1. Prepare the Package

# 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

# 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):

npm run publish:patch

For Minor Version (1.0.0 → 1.1.0):

npm run publish:minor

For Major Version (1.0.0 → 2.0.0):

npm run publish:major

Manual Publishing:

# 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:

   npm install df-ae-forms-package

Publishing Checklist

• [ ] 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.

Documentation

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

Quick Overview

1. Install dependencies:

   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:

   @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

Styles Not Reflecting

• 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

Components Not Visible

• 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

1.0.0

• 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)