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