npm package: @rxbenefits/forms
Description: Form schemas and validation library for RxBenefits applications
Author: RxBenefits
Latest version: 1.0.0

# @rxbenefits/forms

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40rxbenefits%2Fforms.svg)](https://www.npmjs.com/package/@rxbenefits/forms)

Form schemas and validation library for RxBenefits applications. Provides type-safe field group configurations for Employee, Dependent, and Member management forms.

## Features

- 🎯 **Type-Safe**: Full TypeScript support with strict mode
- 📦 **Modular**: Organized field groups for different form types
- ✅ **Validated**: Built-in validation rules and patterns
- 🔄 **Reusable**: Shareable configurations across applications
- 📝 **Well-Tested**: 135 tests with 77% statement coverage

## Installation

```bash
npm install @rxbenefits/forms
# or
yarn add @rxbenefits/forms
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install react@^18.3.1 react-dom@^18.3.1
```

### Internal Dependencies

The following @rxbenefits packages are also required:

- `@rxbenefits/constants@^1.0.0`
- `@rxbenefits/types@^1.0.0`
- `@rxbenefits/ui@^1.0.0`
- `@rxbenefits/utils@^1.0.0`

## Usage

### Basic Example

```typescript
import { CreateEmployeeIdentity, UpdateDependentDetails } from '@rxbenefits/forms';

// Create employee identity fields
const employeeIdentityFields = CreateEmployeeIdentity(false, 5, 20);

// Update dependent details fields
const dependentDetailsFields = UpdateDependentDetails();

// Use with @rxbenefits/ui Form component
<Form fieldGroups={employeeIdentityFields} />
```

### Field Groups Available

#### Dependent Field Groups

**Create Operations:**
- `CreateDependentIdentity` - SSN and person code fields
- `CreateDependentDetails` - Name, birthdate, gender, relationship
- `CreateDependentEffectiveDate` - Effective date field
- `CreateDependentOrgAndMember` - Organization and member info

**Update Operations:**
- `UpdateDependentIdentity` - Identity fields with reveal/edit
- `UpdateDependentDetails` - Details with age field

**Shared Fields:**
- `DependentAddress` - Address fields (address, city, state, ZIP)
- `DependentCOB` - Coordination of benefits
- `DependentMedDSubsidy` - Medicare Part D subsidy
- `DependentAlternateGroup` - Alternate group assignment
- `DependentClientDefinedData` - Custom client data

#### Employee Field Groups

**Create Operations:**
- `CreateEmployeeIdentity` - SSN, person code, client ID
- `CreateEmployeeDetails` - Name, birthdate, gender
- `CreateEmployeeDivision` - Division assignment
- `CreateEmployeeBenefitPackage` - Benefit package selection
- `CreateEmployeeCOB` - Coordination of benefits
- `CreateEmployeeEffectiveDate` - Effective date
- `CreateEmployeeOrganization` - Organization selection

**Update Operations:**
- `UpdateEmployeeIdentity` - Identity with reveal/edit
- `UpdateEmployeeDetails` - Details with age
- `UpdateEmployeeDivision` - Division changes
- `UpdateEmployeeBenefitPackage` - Benefit package changes
- `UpdateEmployeeCOB` - COB updates
- `UpdateEmployeeGroupAssignment` - Group changes
- `UpdateEmployeeDivisionHistory` - Division history table
- `UpdateEmployeeGroupAssignmentHistory` - Group history table

**Shared Fields:**
- `EmployeeAddress` - Address fields
- `EmployeeClientDefinedData` - Custom client data
- `EmployeeMedDSubsidy` - Medicare Part D subsidy
- `AddDivision` - Add new division component

#### Member Field Groups

- `MemberIncentivePrograms` - Incentive program management (diabetic, cholesterol, asthma, etc.)
- `anyIncentiveProgramEnabled` - Helper to check if any program is enabled

### Advanced Usage

#### Dynamic Validation

```typescript
import { CreateEmployeeIdentity } from '@rxbenefits/forms';

// With client ID length validation
const fields = CreateEmployeeIdentity(
  false,              // generateEmployeeSSN
  5,                  // clientIdMinimumLength
  20                  // clientIdMaximumLength
);
```

#### Conditional Fields

```typescript
import { DependentAddress } from '@rxbenefits/forms';

// Address required
const requiredAddress = DependentAddress(true);

// Address optional
const optionalAddress = DependentAddress(false);
```

#### Incentive Programs

```typescript
import { MemberIncentivePrograms, anyIncentiveProgramEnabled } from '@rxbenefits/forms';

const incentivePrograms = {
  IsDiabeticIncentiveProgramSupported: true,
  IsCholesterolIncentiveProgramSupported: true,
  // ... other programs
};

// Check if any program is enabled
if (anyIncentiveProgramEnabled(incentivePrograms)) {
  const fields = MemberIncentivePrograms(member, incentivePrograms);
}
```

## API Reference

### Field Group Structure

All field groups return `FieldGroupProps[]`:

```typescript
interface FieldGroupProps {
  groupTitle?: string;
  groupKey?: string;
  groupToolTip?: string;
  groupColumnSpan?: number;
  fields: FieldProps[];
}

interface FieldProps {
  fieldName: string;
  type: string;
  label?: string;
  isRequired?: boolean;
  toolTip?: string;
  rules?: ValidationRule[];
  inputProps?: Record<string, any>;
  // ... other properties
}
```

### Validation Rules

Common validation rules from `@rxbenefits/constants`:

- `SSN_PATTERN` - Social Security Number (9 digits, no dashes)
- `NUMBERS_ONLY` - Numeric input only
- `ZIP_PATTERN` - ZIP code (5 digits or 5+4 format)
- `Int32Validator` - Integer range validation

## TypeScript Support

This library is written in TypeScript and includes type definitions.

```typescript
import { FieldGroupProps } from '@rxbenefits/ui';
import { CreateEmployeeIdentity } from '@rxbenefits/forms';

const fields: FieldGroupProps[] = CreateEmployeeIdentity();
```

## Testing

The library includes comprehensive tests using Jest and React Testing Library.

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

### Test Coverage

- **Statements**: 76.99%
- **Lines**: 74.15%
- **Functions**: 58.2%
- **Branches**: 46.07%

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

# Validate all
npm run validate
```

## License

MIT © RxBenefits

## Related Packages

- [@rxbenefits/ui](https://www.npmjs.com/package/@rxbenefits/ui) - UI component library
- [@rxbenefits/types](https://www.npmjs.com/package/@rxbenefits/types) - TypeScript type definitions
- [@rxbenefits/constants](https://www.npmjs.com/package/@rxbenefits/constants) - Shared constants
- [@rxbenefits/utils](https://www.npmjs.com/package/@rxbenefits/utils) - Utility functions

## Support

For questions or issues, please file an issue on our [GitHub repository](https://github.com/rxbenefits/rxbenefits-forms/issues).

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.