df-ae-forms-package/README.md

A comprehensive React form preview component library with form controls, validation, and responsive design for Angular/Ionic integration

# 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

### 1. Import CSS

First, import the package styles in your application:

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

### 2. Use the Component

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

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

### Prerequisites

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

### Setup

1. Clone the repository
2. Install dependencies:
   ```bash
   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

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

### Prerequisites for Publishing

1. **NPM Account**: Create an account at [npmjs.com](https://www.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

```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](https://www.npmjs.com/package/df-ae-forms-package)
2. Test installation in a new project:
   ```bash
   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](./QUICK-START.md)** - Get up and running in 5 minutes
- **[Complete Integration Guide](./INTEGRATION-GUIDE.md)** - Detailed step-by-step instructions with examples

### Quick Overview

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](./INTEGRATION-GUIDE.md))

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](./QUICK-START.md)** - For a condensed setup guide
- **[Integration Guide](./INTEGRATION-GUIDE.md)** - 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)