# Approval Decision Panel

## Short Description

Approval Decision Panel is a reusable Yeeflow approval-form custom code template that lets approvers choose a decision, enter comments, validate required reasons, and save the result into configured form fields or variables.

## Purpose / What This Is For

Use this template when an approval form needs a clear, consistent decision block instead of scattered fields or generic radio buttons.

It helps customers standardize approval experiences for:

- approve / reject / request changes
- risk review approvals
- contract approval
- vendor approval
- purchase approval
- master data change approval
- exception approval
- policy and compliance review

The template captures the approver's selected decision and optional or required comments, then writes those values back to configured Yeeflow fields or variables.

## Supported Placement

This template is optimized for:

- Approval form

It can write to approval form fields and compatible variables when the Yeeflow runtime exposes writable setter methods.

## When To Use This Template

Use Approval Decision Panel when:

- Approvers need a clean, guided decision area.
- Rejection or revision decisions should require a reason.
- The same decision pattern should be reused across multiple approval workflows.
- Delivery teams want configurable labels, comments, and optional custom decision options.
- Readonly viewers should see the captured decision clearly.

## Recommended Defaults

| Parameter | Recommended Value |
| --- | --- |
| `titleText` | `Approval Decision` |
| `subtitleText` | `Select your decision and add a comment when needed.` |
| `approveLabel` | `Approve` |
| `rejectLabel` | `Reject` |
| `reviseLabel` | `Request Changes` |
| `requireCommentOnReject` | `true` |
| `requireCommentOnRevise` | `true` |
| `showCommentBox` | `true` |
| `panelStyle` | `standard` |
| `showStatusSummary` | `true` |

## Input Parameters Overview

| Parameter | Type | Required | Purpose | Example Value |
| --- | --- | --- | --- | --- |
| `decisionField` | Writable target / expression editor | Yes | Field or variable used to save selected decision code. | `ApprovalDecision` |
| `commentField` | Writable target / expression editor | Recommended | Field or variable used to save approver comment/reason. | `ApprovalComment` |
| `titleText` | Plain text | No | Title shown above the panel. | `Approval Decision` |
| `subtitleText` | Plain text | No | Supporting text below the title. | `Review the request and choose an action.` |
| `approveLabel` | Plain text | No | Label for the approve button. | `Approve` |
| `rejectLabel` | Plain text | No | Label for the reject button. | `Reject` |
| `reviseLabel` | Plain text | No | Label for the request-changes button. | `Request Changes` |
| `defaultDecision` | Expression editor | No | Optional decision selected when no saved value exists. | `approve` |
| `requireCommentOnReject` | Expression editor boolean | No | Requires comment before Reject is saved. | `true` |
| `requireCommentOnRevise` | Expression editor boolean | No | Requires comment before Request Changes is saved. | `true` |
| `showCommentBox` | Expression editor boolean | No | Shows or hides the comment box. | `true` |
| `commentPlaceholder` | Plain text | No | Placeholder text in comment box. | `Add your reason or comment...` |
| `panelStyle` | Plain text | No | Visual style: `standard`, `compact`, or `bordered`. | `standard` |
| `showStatusSummary` | Expression editor boolean | No | Shows selected decision summary. | `true` |
| `readonlyText` | Plain text | No | Text shown in readonly mode when no decision exists. | `No decision captured yet.` |
| `decisionOptionsJson` | Expression editor | No | Optional JSON array for custom decisions. | See example config |
| `validationMessageReject` | Plain text | No | Custom Reject validation message. | `Please explain why this is rejected.` |
| `validationMessageRevise` | Plain text | No | Custom Request Changes validation message. | `Please describe the required changes.` |

## Detailed Parameter Explanation

### `decisionField`

The writable form field or variable that stores the selected decision code.

Standard saved values are:

- `approve`
- `reject`
- `revise`

This parameter uses the expression editor because delivery teams may select a form field, variable, or dynamic binding from the selector. The code resolves the actual writable target defensively before saving.

### `commentField`

The writable field or variable that stores the approver comment or reason text.

This is strongly recommended when rejection or revision decisions require comments.

### `titleText`

Title displayed above the decision controls.

### `subtitleText`

Optional helper text under the title. Use it to guide approvers without adding too much instruction.

### `approveLabel`, `rejectLabel`, `reviseLabel`

Button labels for the three standard decisions.

Changing labels does not change the saved decision codes unless you use `decisionOptionsJson`.

### `defaultDecision`

Optional default selected decision when the target field has no existing value.

Common values:

- `approve`
- `reject`
- `revise`

### `requireCommentOnReject`

When true, the Reject decision shows a validation message until a comment is entered. The decision value is only saved after the comment requirement is satisfied.

### `requireCommentOnRevise`

When true, the Request Changes decision shows a validation message until a comment is entered. The decision value is only saved after the comment requirement is satisfied.

### `showCommentBox`

Controls whether the comment text area is shown.

If comments are required for any decision, keep this enabled.

### `commentPlaceholder`

Placeholder text displayed inside the comment box.

### `panelStyle`

Visual style for the panel.

Supported values:

- `standard`
- `compact`
- `bordered`

### `showStatusSummary`

Shows a short summary below the controls, such as the selected decision and whether a comment is required.

### `readonlyText`

Text shown when the approval form is readonly and no saved decision is available.

### `decisionOptionsJson`

Optional JSON array for custom decision options.

Each option can include:

- `code`
- `label`
- `tone`
- `helper`
- `requireComment`

Supported tones include:

- `approve`
- `reject`
- `revise`
- `escalate`
- `hold`
- `neutral`

### `validationMessageReject`

Optional custom validation message when Reject requires a comment.

### `validationMessageRevise`

Optional custom validation message when Request Changes requires a comment.

## Step-By-Step Setup Guide

1. Add the Custom Code control to a Yeeflow approval form.
2. Open the code editor and paste `approval-decision-panel.tsx`.
3. Create or identify a field to store the decision value.
4. Create or identify a field to store the approval comment.
5. Configure `decisionField` by selecting the decision field from the expression/variable selector.
6. Configure `commentField` by selecting the comment field from the expression/variable selector.
7. Set labels and helper text as needed.
8. Keep `requireCommentOnReject` and `requireCommentOnRevise` enabled for governed approvals.
9. Preview the approval form.
10. Select Approve, Reject, and Request Changes and confirm the configured fields update correctly.
11. Test readonly mode by viewing a submitted or completed approval.

## Result / Expected Output

When the user selects a decision:

- The selected decision is visually highlighted.
- The decision code is saved into `decisionField` when valid.
- The comment text is saved into `commentField`.
- If Reject or Request Changes requires a comment, the decision is not saved until a comment is entered.
- Readonly mode displays the saved decision and comment without editable controls.

## Real Business Examples

### Purchase Approval

Approvers choose Approve, Reject, or Request Changes. Reject and Request Changes require a reason for audit visibility.

### Vendor Approval

Procurement teams use the panel to approve a new vendor, reject it, or request corrected business documents.

### Contract Approval

Legal reviewers approve a contract, reject it with a reason, or request changes before final approval.

### Policy Exception Approval

Risk teams use stricter validation so rejection and revision always include clear comments.

## Notes / Assumptions / Limitations

- The template is optimized for approval forms.
- `decisionField` and `commentField` are writable target parameters, not ordinary text settings.
- The control writes values through available Yeeflow setter methods such as `setFieldValue`, `setFormFieldValue`, or variable setter paths when exposed.
- Validation happens inside the custom control. For full workflow blocking, pair this with Yeeflow field-required or workflow validation rules where appropriate.
- Custom decisions can be configured through `decisionOptionsJson`, but the standard three decisions are recommended for first rollout.
- The panel does not execute workflow actions directly. It captures decision data for the form/workflow to use.

## Testing Checklist

- Select Approve and confirm `decisionField` saves `approve`.
- Select Reject with no comment and confirm validation appears.
- Add a Reject comment and confirm `decisionField` saves `reject`.
- Select Request Changes with no comment and confirm validation appears.
- Add a Request Changes comment and confirm `decisionField` saves `revise`.
- Confirm `commentField` updates when the comment changes.
- Test default decision behavior.
- Test readonly mode with existing saved values.
- Test missing `decisionField` configuration.
- Test custom `decisionOptionsJson` if used.
- Test narrow/mobile form layout.

## Troubleshooting

### The decision does not save

Confirm `decisionField` is configured as a writable form field or variable. Use the selector rather than display text when possible.

### Comments do not save

Confirm `commentField` points to a writable text/multiline text field.

### Reject or Request Changes never saves

If comment-required validation is enabled, enter a comment first. The control intentionally waits to save the decision until the required comment exists.

### Existing values do not show in readonly mode

Confirm `decisionField` and `commentField` are included in the form and available to the custom code runtime.

### Custom options do not appear

Check that `decisionOptionsJson` is valid JSON and is an array. If unsure, remove it and test the standard options first.
