# Multi-Field Arithmetic Calculator — Plugin Guide
---

## 🇺🇸 English

### What This Plugin Does
This is a **non-visual controller element**. It sits invisibly on your Bubble page and evaluates arithmetic formulas using named variables you define. The results are exposed as **Bubble states** that you bind to Text elements, conditionals, or workflows.

---

### Element Fields (Properties Panel)

#### ── Input Fields ──
Up to **5 Field Name / Field Value pairs** (A1–B5):

| Field | Description |
|---|---|
| **A1 — Field Name** | Variable name used in your formula (e.g. `Price`, `Qty`, `A`) |
| **B1 — Field Value** | The numeric value, or a text option key if using Option Mapping |
| A2/B2 … A5/B5 | Same structure for fields 2 through 5 |

> ⚠️ Field names are **case-sensitive**. `Price` ≠ `price`. English letters only.

---

#### ── Option Mapping ──
Up to **5 Option Key / Option Value list pairs** (C1–D5):

| Field | Description |
|---|---|
| **C1 — Option Keys** | A Bubble list of text values (e.g. dropdown display values: `Small`, `Medium`, `Large`) |
| **D1 — Option Values** | A matching Bubble list of numbers (e.g. `1`, `2`, `3`) — order must match C |
| C2/D2 … C5/D5 | Additional slots for more option sets |

> This lets you map dropdown/option set text choices → numbers without hardcoding. The plugin merges all 5 slots into one lookup table automatically.

---

#### ── Formula ──

| Field | Description |
|---|---|
| **E — Formula** | Arithmetic expression using your variable names. Supported: `+ - * /` and `( )` |

**Examples:**
```text
(Price * Qty) - Discount
(A + B) * C / 100
A * B + C - D
```

---

#### ── Output Formatting ──

| Field | Description |
|---|---|
| **F — Decimal Places** | Number of decimal digits in `result_text` (0–10, default: 2) |
| **G — Thousands Separator** | Toggle `,` grouping (e.g. `1,234.56`) |
| **H — Prefix** | Text prepended to result (e.g. `$`, `₩`, `Total: `) |
| **I — Suffix** | Text appended to result (e.g. ` pts`, ` kg`, `%`) |
| **J — Auto-Recalculate** | If ON, recalculates on every property change. If OFF, use the **Recalculate** action. |

---

### Exposed States

| State | Type | Description |
|---|---|---|
| **result** | number | Raw numeric result of the formula |
| **result_text** | text | Formatted string: prefix + number + suffix |
| **has_error** | boolean | `true` if the last calculation failed |
| **error_message** | text | Human-readable error description |

---

### Events

| Event | When it fires |
|---|---|
| **Calculation Complete** | After every successful formula evaluation |
| **Calculation Error** | When evaluation fails (bad formula, division by zero, etc.) |

---

### Actions

| Action | What it does |
|---|---|
| **Recalculate** | Manually triggers formula evaluation (useful when Auto-Recalculate is OFF) |
| **Reset** | Sets `result` → 0, `result_text` → empty, clears error states |

---

### Typical Setup Flow
1. Place the **Arithmetic Calculator** element on your page (it's invisible — size doesn't matter).
2. Set **A1 Field Name** = `Price`, **B1 Field Value** = (bind to your input's value).
3. Set **A2 Field Name** = `Qty`, **B2 Field Value** = (bind to your input's value).
4. (Optional) Bind **C1 Option Keys** and **D1 Option Values** if any field value comes from a dropdown.
5. Set **E Formula** = `Price * Qty`.
6. Configure **F–I** for formatting.
7. On a Text element, bind its value to `Arithmetic Calculator's result_text`.
8. Optionally use **Calculation Complete** event to trigger downstream workflows.

---
---

## 🇰🇷 한국어

### 플러그인 개요
이 플러그인은 **비시각적 컨트롤러 엘리먼트**입니다. Bubble 페이지에 보이지 않는 채로 위치하며, 사용자가 정의한 변수명과 계산식을 기반으로 산술 연산을 수행합니다. 결과는 **Bubble 상태(State)** 로 노출되어 텍스트 엘리먼트나 워크플로우에 바인딩할 수 있습니다.

---

### 필드 구성 (Properties 패널)

#### ── 입력 필드 ──
최대 **5개의 필드명 / 필드값 쌍** (A1–B5):

| 필드 | 설명 |
|---|---|
| **A1 — 필드 이름** | 계산식에서 사용할 변수명 (예: `Price`, `Qty`, `A`) |
| **B1 — 필드 값** | 숫자값, 또는 옵션 매핑 사용 시 텍스트 옵션키 |
| A2/B2 … A5/B5 | 동일한 구조의 2~5번째 필드 |

> ⚠️ 필드명은 **대소문자를 구분**합니다. `Price` ≠ `price`. 영문만 사용 가능합니다.

---

#### ── 옵션 매핑 ──
최대 **5개의 옵션키 / 옵션값 리스트 쌍** (C1–D5):

| 필드 | 설명 |
|---|---|
| **C1 — 옵션키 (text list)** | Bubble 텍스트 리스트 (예: 드롭다운 표시값: `Small`, `Medium`, `Large`) |
| **D1 — 옵션값 (number list)** | C1과 순서가 일치하는 숫자 리스트 (예: `1`, `2`, `3`) |
| C2/D2 … C5/D5 | 추가 옵션 세트를 위한 슬롯 |

> 드롭다운/옵션셋의 텍스트 선택값을 숫자로 매핑할 때 사용합니다. 5개 슬롯은 하나의 조회 테이블로 자동 병합됩니다.

---

#### ── 계산식 ──

| 필드 | 설명 |
|---|---|
| **E — 계산식** | 변수명을 사용한 산술식. 지원 기호: `+ - * /` 및 `( )` |

**예시:**
```text
(Price * Qty) - Discount
(A + B) * C / 100
A * B + C - D
```

---

#### ── 출력 포맷 ──

| 필드 | 설명 |
|---|---|
| **F — 소수점 자리수** | `result_text`에 표시할 소수점 자릿수 (0~10, 기본값: 2) |
| **G — 천단위 구분자** | `,` 구분 여부 (예: `1,234.56`) |
| **H — 접두어** | 결과 앞에 붙일 문자 (예: `$`, `₩`, `합계: `) |
| **I — 접미사** | 결과 뒤에 붙일 문자 (예: ` 원`, ` kg`, `%`) |
| **J — 변경 시 자동갱신** | ON이면 속성 변경마다 자동 계산. OFF이면 **Recalculate** 액션 수동 실행 필요 |

---

### 노출 상태 (States)

| 상태 | 타입 | 설명 |
|---|---|---|
| **result** | number | 계산식의 원시 숫자 결과 |
| **result_text** | text | 포맷된 문자열: 접두어 + 숫자 + 접미사 |
| **has_error** | boolean | 마지막 계산이 실패했으면 `true` |
| **error_message** | text | 오류 내용 설명 |

---

### 이벤트 (Events)

| 이벤트 | 발생 시점 |
|---|---|
| **Calculation Complete** | 계산 성공 시마다 |
| **Calculation Error** | 계산 실패 시 (잘못된 계산식, 0으로 나누기 등) |

---

### 액션 (Actions)

| 액션 | 설명 |
|---|---|
| **Recalculate** | 계산식을 수동으로 재실행 (자동갱신 OFF 시 유용) |
| **Reset** | `result` → 0, `result_text` → 빈값, 오류 상태 초기화 |

---

### 기본 사용 흐름
1. **Arithmetic Calculator** 엘리먼트를 페이지에 배치합니다 (보이지 않으므로 크기 무관).
2. **A1 필드 이름** = `Price`, **B1 필드 값** = 인풋 값에 바인딩.
3. **A2 필드 이름** = `Qty`, **B2 필드 값** = 인풋 값에 바인딩.
4. (선택) 드롭다운 연동 시 **C1 옵션키**, **D1 옵션값** 에 리스트 바인딩.
5. **E 계산식** = `Price * Qty` 입력.
6. **F–I** 로 출력 포맷 설정.
7. 텍스트 엘리먼트 값을 `Arithmetic Calculator's result_text` 에 바인딩.
8. 필요 시 **Calculation Complete** 이벤트로 후속 워크플로우 연결.