# 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 [#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.

```ts
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 [#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 [#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]

Validation is performed using [Ajv ](https://ajv.js.org) 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 [#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'`                 |