---

# (DD02) Business Logic — UI.panel() [24 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.github.blaxk3.ui.UI` |
| Layer | Utility (Package: `com.github.blaxk3.ui`) |
| Module | `ui` (Package: `com.github.blaxk3.ui`) |

## 1. Role

### UI.panel()

The `panel()` method is the primary UI composition method for a **currency conversion application**. It builds and assembles the complete visual layout — a two-row panel structure containing input fields, dropdown selectors, a result label, and action buttons — into a single `JPanel` component ready to be added to a Swing `JFrame`.

The method implements the **Builder pattern** for UI layout: it creates two sub-panels (`panelFramePanel1` and `panelFramePanel2`), populates each with child components via dedicated factory methods (`textField()`, `comboBox1()`, `label()`, `comboBox2()`, `button()`), and then nests them under a top-level panel with a vertical `BoxLayout`.

It is an **entry-point layout builder** called exactly once from the `UI` constructor (`add(panel())` at line 60). It has no conditional branches, no CRUD operations, and no service calls — its sole responsibility is assembling and returning a fully structured UI component tree. The functional behavior (currency conversion, swap, clear) is deferred to the `ActionListener` callbacks attached within the `button()` method.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["panel()"])
    STEP1["Create main JPanel framePanel<br/>Set Y_AXIS BoxLayout"]
    STEP2["Create panelFramePanel1<br/>Set DARK_GRAY background<br/>Set CENTER FlowLayout"]
    STEP3["Add textField() to panelFramePanel1"]
    STEP4["Add comboBox1() to panelFramePanel1<br/>CurrencyCode popup loads"]
    STEP5["Create panelFramePanel2<br/>Set CENTER FlowLayout<br/>Set DARK_GRAY background"]
    STEP6["Add label() to panelFramePanel2"]
    STEP7["Add comboBox2() to panelFramePanel2<br/>CurrencyCode popup loads"]
    STEP8["Add button() array elements to panelFramePanel2<br/>Convert / Swap / Clear buttons"]
    STEP9["Add panelFramePanel1 to framePanel"]
    STEP10["Add panelFramePanel2 to framePanel"]
    RETURN["Return framePanel"]

    START --> STEP1 --> STEP2 --> STEP3 --> STEP4 --> STEP5 --> STEP6 --> STEP7 --> STEP8 --> STEP9 --> STEP10 --> RETURN
```

The method follows a strictly linear, sequential flow:

1. **Create the main panel** (`framePanel`) — a `JPanel` with a vertical `BoxLayout` (`Y_AXIS`) to stack child panels top-to-bottom.
2. **Create the input row** (`panelFramePanel1`) — a `JPanel` with a dark gray background and centered `FlowLayout`. It receives the text input field and the source currency dropdown.
3. **Create the output row** (`panelFramePanel2`) — a `JPanel` with centered `FlowLayout` and dark gray background. It receives the result label, destination currency dropdown, and three action buttons (Convert, Swap, Clear).
4. **Nest both sub-panels** under the main panel and return the assembled component.

There are no conditional branches, loops, or error handling in this method.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | This method takes no parameters. It is a parameterless factory that assembles a complete currency conversion UI layout. |

**Instance fields accessed by this method:** None directly. All child components are instantiated fresh by calling their respective factory methods (`textField()`, `comboBox1()`, etc.).

**External state dependencies:**
| No | Dependency | Type | Business Description |
|----|-----------|------|---------------------|
| 1 | `CurrencyCode` (SwingWorker) | External class | Loaded when `comboBox1()` and `comboBox2()` are called; populates the currency dropdowns with currency codes fetched asynchronously from `CurrencyRateAPI` |
| 2 | `CurrencyRateAPI` | External class | Called by the "Convert" button's `ActionListener` (via `button()`); performs the actual currency conversion against a live exchange rate API |

## 4. CRUD Operations / Called Services

The `panel()` method itself does not perform any database or service operations. All calls are to UI component factory methods within the same class.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `UI.textField` | UI | - | Creates and returns the amount input text field component |
| - | `UI.comboBox1` | UI | - | Creates and returns the source currency selection dropdown (populates via CurrencyCode SwingWorker) |
| - | `UI.comboBox2` | UI | - | Creates and returns the destination currency selection dropdown (populates via CurrencyCode SwingWorker) |
| - | `UI.label` | UI | - | Creates and returns the result display label component |
| - | `UI.button` | UI | - | Creates and returns an array of three action buttons (Convert, Swap, Clear) with attached ActionListeners |

## 5. Dependency Trace

This method is called from exactly one location — the `UI` class constructor — which adds the returned panel to the frame.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Class: `UI` (Constructor) | `UI.<init>()` -> `add(panel())` [L60] | `button()[0].addActionListener` -> `CurrencyRateAPI.convert()` (no DB, HTTP API call) |

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] `(L71)`

> Creates the main container panel for the UI layout.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JPanel framePanel = new JPanel();` |
| 2 | SET | `framePanel.setLayout(new javax.swing.BoxLayout(framePanel, javax.swing.BoxLayout.Y_AXIS));` |

**Block 2** — [SET] `(L74)`

> Creates the first sub-panel (input row) with a dark gray background and centered flow layout.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JPanel panelFramePanel1 = new JPanel();` |
| 2 | SET | `panelFramePanel1.setBackground(Color.DARK_GRAY);` |
| 3 | SET | `panelFramePanel1.setLayout(new FlowLayout(FlowLayout.CENTER));` |

**Block 3** — [EXEC] `(L77)`

> Adds the text input field to the input row panel.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `panelFramePanel1.add(textField());` |

**Block 4** — [EXEC] `(L78)`

> Adds the source currency dropdown to the input row panel. This triggers a `CurrencyCode` SwingWorker that asynchronously populates the combo box with currency codes.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `panelFramePanel1.add(comboBox1());` |

**Block 5** — [SET] `(L80)`

> Creates the second sub-panel (output row) with a dark gray background and centered flow layout.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JPanel panelFramePanel2 = new JPanel();` |
| 2 | SET | `panelFramePanel2.setLayout(new FlowLayout(FlowLayout.CENTER));` |
| 3 | SET | `panelFramePanel2.add(label());` |
| 4 | SET | `panelFramePanel2.add(comboBox2());` |
| 5 | SET | `panelFramePanel2.setBackground(Color.DARK_GRAY);` |

**Block 6** — [EXEC] `(L84)`

> Adds the three action buttons (Convert, Swap, Clear) to the output row panel. Each button has an `ActionListener` registered via the `button()` factory method:
> - **Convert**: Calls `CurrencyRateAPI.convert()` to fetch the exchange rate and format the converted amount.
> - **Swap**: Swaps the selected currencies between the two combo boxes.
> - **Clear**: Clears the text field and result label.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `panelFramePanel2.add(button()[0]);` |
| 2 | EXEC | `panelFramePanel2.add(button()[1]);` |
| 3 | EXEC | `panelFramePanel2.add(button()[2]);` |

**Block 7** — [EXEC] `(L87)`

> Adds both sub-panels to the main frame panel (stacked vertically via BoxLayout Y_AXIS).

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `framePanel.add(panelFramePanel1);` |
| 2 | EXEC | `framePanel.add(panelFramePanel2);` |

**Block 8** — [RETURN] `(L89)`

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return framePanel;` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `framePanel` | Field | Main container panel — holds the two sub-panels stacked vertically |
| `panelFramePanel1` | Field | Input row panel — contains the amount input field and source currency selector |
| `panelFramePanel2` | Field | Output row panel — contains the result label, destination currency selector, and action buttons |
| `textField` | Component | Numeric text input field where the user enters the conversion amount |
| `comboBox1` | Component | Source currency dropdown — populated with ISO currency codes (e.g., USD, EUR, JPY) |
| `comboBox2` | Component | Destination currency dropdown — populated with ISO currency codes for the target currency |
| `label` | Component | Result display label — shows the formatted converted amount |
| `button` | Component | Array of action buttons: Convert (executes conversion), Swap (exchanges selected currencies), Clear (resets all fields) |
| `CurrencyCode` | Class | SwingWorker that asynchronously loads currency code options into combo boxes |
| `CurrencyRateAPI` | Class | External HTTP API client that performs real-time currency conversion calculations |
| BoxLayout Y_AXIS | Layout | Vertical layout manager — stacks child panels top-to-bottom |
| FlowLayout.CENTER | Layout | Horizontal layout manager — centers child components within the panel |
| Color.DARK_GRAY | Constant | Visual styling constant — gives sub-panels a dark gray background for visual separation |
| NumericFilter | Class | Document filter attached to the text field — restricts input to numeric characters and at most one decimal point |
| DecimalFormat | Class | Java formatter used to format the converted amount with thousand separators (e.g., `1,234.567`) |

---