@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

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

Peer Dependencies

This library requires the following peer dependencies:

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

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

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

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

Conditional Fields

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

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

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

Incentive Programs

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

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.

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.

# 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

# 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 - UI component library
• @rxbenefits/types - TypeScript type definitions
• @rxbenefits/constants - Shared constants
• @rxbenefits/utils - Utility functions

Support

For questions or issues, please file an issue on our GitHub repository.

Changelog

See CHANGELOG.md for version history and release notes.