NewDisbursementForm

The NewDisbursementForm component provides a user interface for creating a new disbursement. It’s a specialized form that captures all necessary details for a disbursement, such as amount, type, and payment method. The form fields dynamically adjust based on the selected disbursement type defined in the data model.

Usage

To use the NewDisbursementForm, you must provide context about the account, such as its locator, balance, and currency, along with a dataModel and a submit handler. The component wraps the JsonForms library to render the form structure.

import { NewDisbursementForm } from '@socotra/ec-react-components';
import { DataModel, CurrencyType } from '@socotra/ec-react-schemas';

// Example Usage
const MyDisbursementComponent = ({ dataModel }: { dataModel: DataModel }) => {
  const handleSubmit = (disbursementData) => {
    console.log('Disbursement created:', disbursementData);
    // Handle API call to create the disbursement
  };

  return (
    <NewDisbursementForm
      accountLocator="123-abc"
      accountBalance={5000}
      currency={"USD" as CurrencyType}
      dataModel={dataModel}
      handleSubmit={handleSubmit}
      submitButtonText="Create Disbursement"
    />
  );
};

Props

The component accepts the following props:

Prop	Type	Description	Default
accountLocator	string	The unique locator for the account from which the disbursement will be made.	Required
accountBalance	number	The current balance of the account.	Required
currency	CurrencyType	The currency for the disbursement transaction.	Required
dataModel	DataModel	The resolved data model object containing disbursement configurations and data types.	Required
handleSubmit	(data: DisbursementCreateRequest) => void	Callback function triggered on form submission with the fully formed disbursement request payload.	Required
isSubmitting	boolean	When true, disables the form fields and submit button.	false
disabled	boolean	When true, disables the entire form.	false
hideSubmitButton	boolean	If true, the submit button is not rendered.	false
validateOnSubmit	boolean	If true, validation is run on submit and submission is blocked if the data is invalid.	false
submitButtonText	string	Custom text for the submit button.	'Update'
id	string	A unique ID for the form wrapper element.	undefined
titles	object	An object to override default labels for the form title and other fields.	{}

State Management

NewDisbursementForm uses React’s useState hook to manage the form’s data.

• The form’s entire data object is held in a single state variable.

• When the disbursement type is changed by the user, the component resets the data portion of the state to ensure no stale information is carried over, while preserving the selected default values.

• State is passed to and updated from the underlying JsonForms component.

Validation

Validation is performed using Ajv against a dynamically generated JSON Schema.

• The JSON Schema is created based on the selected disbursement type from the dataModel. The dataModelToJSONSchema utility is used for this conversion.

• The form’s ajv instance is extended with custom formats and error handling.

• If validateOnSubmit is set to true, the handleSubmit function is blocked from being called if the form data is invalid.

• The translateError utility is used to provide user-friendly validation messages.

Labels and Translations

The text for UI labels and validation messages can be customized.

UI Labels

Labels for sections and fields can be overridden by passing a titles object prop.

Key	Description	Default Value
formTitle	The main title for the form.	''
type	Label for the “Disbursement Type” field.	'Type'
amount	Label for the “Amount” field.	'Amount'
transactionMethod	Label for the “Transaction Method” field.	'Transaction Method'
transactionNumber	Label for the “Transaction Number” field.	'Transaction Number'
truthyLabel	Text for a “true” boolean value.	'Yes'
falsyLabel	Text for a “false” boolean value.	'No'