df-forms-preview-react/README.md

A comprehensive React form preview component library with form controls, validation, and responsive design

# DF Form Preview React

A comprehensive React form preview component library with form controls, validation, and responsive design. This package provides a complete set of form components that can be used to build dynamic forms with real-time validation and conditional logic.

## Features

- 🎨 **Responsive Design**: Desktop, tablet, and mobile views
- ✅ **Form Validation**: Real-time validation with custom error messages
- 🔧 **Form Controls**: Input, textarea, select, checkbox, radio, date, signature, and heading components
- 🎯 **Conditional Logic**: Show/hide fields based on other field values
- 🌐 **Internationalization**: Built-in i18n support
- 📱 **Device Preview**: Preview forms in different device sizes
- 🎨 **Customizable Styling**: CSS variables for easy theming
- 📦 **TypeScript**: Full TypeScript support with comprehensive type definitions

## Installation

```bash
npm install df-form-preview-react
```

## Quick Start

```tsx
import React from 'react';
import { DfFormPreview, FormComponentType } from 'df-form-preview-react';

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: FormComponentType[]) => {
  };

  const handleFormDataChange = (formData: FormComponentType[]) => {

  return (
    <DfFormPreview
      formComponents={formComponents}
      currentDevice="desktop"
      isPreviewMode={false}
      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 |
| `isPreviewMode` | `boolean` | `false` | Whether the form is in preview mode (readonly) |
| `initialFormData` | `FormComponentType[]` | `[]` | Initial form data with default values |
| `onSubmit` | `(formData: FormComponentType[]) => void` | - | Callback when form is submitted |
| `onFormDataChange` | `(formData: FormComponentType[]) => void` | - | Callback when form data changes |

### Form Controls

#### DfFormInput
Text, number, and email input fields.

```tsx
{
  id: 'username',
  name: 'text-input', // or 'number-input', 'email-input'
  basic: {
    label: 'Username',
    placeholder: 'Enter username',
    defaultValue: ''
  },
  validation: {
    required: true,
    minLength: 3,
    maxLength: 20
  }
}
```

#### DfFormTextarea
Multi-line text input.

```tsx
{
  id: 'description',
  name: 'textarea',
  basic: {
    label: 'Description',
    placeholder: 'Enter description',
    defaultValue: ''
  },
  validation: {
    required: true,
    maxLength: 500
  }
}
```

#### DfFormSelect
Dropdown selection.

```tsx
{
  id: 'country',
  name: 'select',
  basic: {
    label: 'Country',
    defaultValue: ''
  },
  options: [
    { label: 'United States', value: 'us' },
    { label: 'Canada', value: 'ca' },
    { label: 'United Kingdom', value: 'uk' }
  ],
  validation: {
    required: true
  }
}
```

#### DfFormCheckbox
Checkbox inputs.

```tsx
{
  id: 'interests',
  name: 'checkbox',
  basic: {
    label: 'Interests',
    defaultValue: []
  },
  options: [
    { label: 'Technology', value: 'tech' },
    { label: 'Sports', value: 'sports' },
    { label: 'Music', value: 'music' }
  ],
  validation: {
    required: true
  }
}
```

#### DfFormRadio
Radio button selection.

```tsx
{
  id: 'gender',
  name: 'radio',
  basic: {
    label: 'Gender',
    defaultValue: ''
  },
  options: [
    { label: 'Male', value: 'male' },
    { label: 'Female', value: 'female' },
    { label: 'Other', value: 'other' }
  ],
  validation: {
    required: true
  }
}
```

#### DfFormDateTime
Date and time inputs.

```tsx
{
  id: 'birthdate',
  name: 'date',
  basic: {
    label: 'Birth Date',
    defaultValue: ''
  },
  validation: {
    required: true
  }
}
```

#### DfFormSignature
Signature pad component.

```tsx
{
  id: 'signature',
  name: 'signature',
  basic: {
    label: 'Digital Signature',
    defaultValue: ''
  },
  validation: {
    required: true
  }
}
```

#### DfFormHeading
Heading component for form sections.

```tsx
{
  id: 'section-title',
  name: 'heading',
  basic: {
    label: 'Personal Information',
    level: 2
  }
}
```

## 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: {
    showIf: {
      fieldId: 'has-phone',
      operator: 'equals',
      value: 'yes'
    }
  }
}
```

## 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;
}
```

## Internationalization

The package supports i18n through react-i18next. Make sure to set up your i18n configuration:

```tsx
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: {
        translation: {
          'formBuilder.submit': 'Submit'
        }
      }
    },
    lng: 'en',
    fallbackLng: 'en'
  });
```

## Development

### Prerequisites

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

### Setup

1. Clone the repository
2. Install dependencies:
   ```bash
   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-form-preview-react` 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-form-preview-react-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-form-preview-react)
2. Test installation in a new project:
   ```bash
   npm install df-form-preview-react
   ```

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

### Troubleshooting

**Authentication Issues:**
```bash
npm whoami  # Check if you're logged in
npm login   # Login if needed
```

**Package Name Conflicts:**
- Check if the package name is available on npmjs.com
- Update the name in package.json if needed

**Build Issues:**
```bash
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build
```

## 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.3
- Added new form components: DfFormFileUpload, DfFormLocation, DfFormComments, DfFormInstruction
- Added DfFormSection, DfFormDataGrid, and DfFormTable components
- Enhanced checkbox, radio, select, and segment components with comments support
- Added `showCommentsInPreview` prop for conditional comment display
- Updated all form components to latest versions
- Added support for date-picker and datetime-picker variants
- Added file-upload component with drag-and-drop support
- Added location component with map integration
- Added instruction component with rich text editor
- Updated interfaces with new component types (IFileUploadComponent, ILocationComponent, IInstructionComponent)
- Added conditional logic interfaces (ICondition, IConditionalLogic)
- Updated validation logic to use real-time form values
- Added @dnd-kit dependencies for section, grid, and table components
- Improved type safety and component prop handling

### 1.0.2
- Bug fixes and improvements

### 1.0.0
- Initial release
- Complete form preview component
- All form controls (input, textarea, select, checkbox, radio, date, signature, heading)
- Validation system
- Conditional logic
- Responsive design
- TypeScript support
- i18n support