# Documentation

Learn how to create and share custom calculators with Calcula.club.

## Getting started

Calcula.club lets you create custom calculators without writing code. Go to the **Builder** to start building your calculator by dragging fields and defining formulas.

1. Click "Start creating" on the home page
2. Drag fields to the canvas or click on field types
3. Configure each field's properties (label, min, max, etc.)
4. Write your formula using the field IDs
5. Share your calculator with the generated URL

## Field types

Calcula.club offers several field types:

- **Number** — Numeric input with optional min, max, and step
- **Slider** — Visual slider with configurable range
- **Select** — Dropdown list with custom options (each option has a numeric value)
- **Checkbox** — Yes/no toggle that produces 0 or 1
- **Radio** — Button group with custom options
- **Date** — Date picker (converted to epoch days in formulas)
- **Range** — Dual slider that generates two variables: `id_min` and `id_max`
- **Section** — Text block with markdown support and dynamic values `{{formula}}`
- **Divider** — Visual separator, optionally with image or text

## Formula syntax

Formulas use field IDs as variables. You can use standard arithmetic operators and built-in functions.

**Operators:** `+`, `-`, `*`, `/`, `%` (modulo), `^` (power)

**Comparisons:** `>`, `<`, `>=`, `<=`, `==`, `!=` (return 1 or 0)

**Intermediate variables:** Use semicolons to define local variables:
```
monthly_rate = interest / 100 / 12;
n = term * 12;
principal * monthly_rate / (1 - pow(1 + monthly_rate, -n))
```

**Available functions:**
- Math: `pow(x,y)`, `sqrt(x)`, `abs(x)`, `round(x)`, `floor(x)`, `ceil(x)`
- Trigonometry: `sin(x)`, `cos(x)`, `tan(x)`, `asin(x)`, `acos(x)`, `atan(x)`
- Statistics: `min(a,b)`, `max(a,b)`, `avg(a,b,c)`, `sum(a,b,c)`, `factorial(n)`
- Logarithms: `ln(x)`, `log(x)`, `log10(x)`, `exp(x)`
- Conditionals: `if(cond, then, else)`
- Lookup: `lookup(value, threshold1, result1, ..., default)`
- Constants: `pi`, `e`

## Advanced features

The **Advanced** section in the Builder adds extra functionality:

- **Extra results** — Display additional calculated values with their own formulas (e.g. monthly payment, total interest)
- **Result thresholds** — Change the result color based on ranges (e.g. green for normal BMI, red for overweight)
- **Breakdown** — Show a line-by-line breakdown of the result
- **Pie chart** — Visualize value distribution with custom segments
- **Conditional visibility** — Each field has a "Show if" option that accepts a formula; the field shows when the result is non-zero

## Sharing and embedding

Every calculator has a unique URL that contains its entire configuration encoded. No backend or database needed.

**Share by URL:** Copy the direct URL from the Builder's "Share" section.

**Embed on your site:** Use the iframe code generated in the "Embed widget" section. You can customize initial values by adding query parameters to the URL.

**Download HTML:** Generate a self-contained HTML file that works offline.

**Custom values:** Add query parameters to the embed URL with field IDs to pre-fill values (e.g. `?field1=50&field2=100`).

---

# API Documentation

Technical reference for developers and integrations with Calcula.club.

## Configuration schema

Each calculator is defined by a `CalculatorConfig` JSON object:

```typescript
interface CalculatorConfig {
  name: string;             // Calculator name
  description: string;      // Short description
  icon: string;             // Emoji icon
  fields: Field[];          // Input fields
  formula: string;          // Main formula
  resultLabel: string;      // Result label text
  resultFormat: FormatType; // "number" | "currency" | "percent" | "integer"
  category?: string;
  theme?: { primary: string };
  extraResults?: ExtraResult[];
  resultThresholds?: ResultThreshold[];
  breakdown?: BreakdownItem[];
  pieConfig?: { segments: PieSegment[] };
}
```

**Field:**
```typescript
interface Field {
  id: string;        // Unique identifier (used in formulas)
  label: string;     // Display text
  type: "number" | "slider" | "select" | "checkbox" | "section" | "radio" | "date" | "range" | "divider";
  default: number;
  min?: number;
  max?: number;
  step?: number;
  options?: { label: string; value: number }[];
  suffix?: string;
  helpText?: string;
  content?: string;  // For section/divider
  imageUrl?: string; // For divider
  showIf?: string;   // Conditional visibility formula
}
```

## Formula engine

The formula engine supports:

**Operators** (by precedence):
1. `^` — Power
2. `*`, `/`, `%` — Multiplication, division, modulo
3. `+`, `-` — Addition, subtraction
4. `>`, `<`, `>=`, `<=`, `==`, `!=` — Comparisons (return 1 or 0)

**Unary operator:** `-` (negation)

**Functions:**
| Function | Signature | Description |
|----------|-----------|-------------|
| `pow` | `pow(base, exp)` | Power |
| `sqrt` | `sqrt(x)` | Square root |
| `abs` | `abs(x)` | Absolute value |
| `round` | `round(x)` | Round to nearest integer |
| `floor` | `floor(x)` | Round down |
| `ceil` | `ceil(x)` | Round up |
| `min` | `min(a, b, ...)` | Minimum |
| `max` | `max(a, b, ...)` | Maximum |
| `avg` | `avg(a, b, ...)` | Arithmetic mean |
| `sum` | `sum(a, b, ...)` | Sum |
| `factorial` | `factorial(n)` | Factorial (n!) |
| `sin` | `sin(x)` | Sine (radians) |
| `cos` | `cos(x)` | Cosine |
| `tan` | `tan(x)` | Tangent |
| `asin` | `asin(x)` | Arcsine |
| `acos` | `acos(x)` | Arccosine |
| `atan` | `atan(x)` | Arctangent |
| `ln` | `ln(x)` | Natural logarithm |
| `log` | `log(x)` | Natural logarithm |
| `log10` | `log10(x)` | Base-10 logarithm |
| `exp` | `exp(x)` | e^x |
| `if` | `if(cond, then, else)` | Conditional (lazy evaluation) |
| `lookup` | `lookup(val, t1, r1, ..., default)` | Threshold-based lookup |

**Constants:** `pi` (3.14159...), `e` (2.71828...)

**Intermediate variables:** Use `name = expression;` to define local variables. The last expression is the return value.

## URL format

Calculators are encoded in the URL:

```
https://calcula.club/c/{encoded_config}
https://calcula.club/es/c/{encoded_config}
```

The configuration is serialized as JSON, compressed with deflate, and encoded as base64url. For embedding, use the `/embed/{config}` path.

**Query parameters for initial values:**
```
/embed/{config}?field1=50&field2=100
```

Each parameter corresponds to a field's `id`. Only numeric values are accepted.

## Embedding

To embed a calculator, use an iframe:

```html
<iframe
  src="https://calcula.club/embed/{config}"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>
```

Or download the self-contained HTML from the Builder to host your own copy.

**Message API:** The iframe communicates height changes to the parent via `postMessage` for automatic size adjustment.