# Prozentrechner - Comprehensive Documentation

**Last Updated:** 2026-04-01

## Tool Overview

### Basic Information

- **Tool Name:** Prozentrechner (Percentage Calculator)
- **Slug:** `prozentrechner`
- **URL:** `https://www.ordio.com/tools/prozentrechner`
- **Status:** Available
- **Last Updated:** 2026-04-01

### SEO / analytics baseline (improvement sprint)

- **Stakeholder snapshot (last 28 days, example):** ~400k impressions, ~454 clicks — high visibility, low CTR; prioritize title/description alignment and query-level review.
- **Research data:** [`docs/content/tools/prozentrechner/data/gsc-queries.json`](../../content/tools/prozentrechner/data/gsc-queries.json), [`baseline-2026-04.md`](../../content/tools/prozentrechner/data/baseline-2026-04.md), [`gsc-compare-notes.md`](../../content/tools/prozentrechner/data/gsc-compare-notes.md).
- **Post-deploy:** Re-check GSC queries + CTR for the same URL after **4–8 weeks** ([`PAGE_IMPROVEMENT_DATA_PLAYBOOK.md`](../../content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md), [`PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md`](../../content/PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md)). **Pending vs. next steps** (Rich Results Test, GSC-Review-Termin, Production-Spotcheck): [`PROZENTRECHNER_2026_NEXT_STEPS.md`](PROZENTRECHNER_2026_NEXT_STEPS.md) § *Pending* / *Next steps* / *Repo verification*.

### Purpose

## Technical Implementation

### Files

- **PHP:** `v2/pages/tools_prozentrechner.php`
- **JavaScript:** `/v2/js/tools-prozentrechner-calculator.min.js?v=<?php echo filemtime(__DIR__ . `
- **JavaScript:** `/v2/js/lead-capture-triggers.min.js?v=<?php echo filemtime(__DIR__ . `
  Comprehensive percentage calculator with 8 calculation modes: basic percentage, reverse percentage, percentage change, percentage difference, compound percentage, discount calculator, VAT calculator, and profit margin calculator. Includes Excel/PDF/CSV export, calculation history, URL sharing, and email gating for exports.

### Use Cases

- **Business:** Calculate discounts, VAT, profit margins, markup
- **Finance:** Calculate percentage changes, compound interest, growth rates
- **Personal:** Calculate tips, discounts, percentage differences
- **Education:** Learn percentage calculations with formulas and examples

### Real-World Scenarios

**Scenario 1: Business Owner Calculating Discount**

- **User:** Retail store owner planning sale
- **Situation:** Want to offer 25% discount on €100 product, need to calculate sale price
- **Goal:** Calculate discounted price and profit margin
- **Steps:**
  1. Select Discount Calculator mode
  2. Enter original price: €100
  3. Enter discount percentage: 25%
  4. Review calculated sale price
  5. Check profit margin
- **Result:** Sees €75 sale price (€100 - €25 discount), can plan profit margin
- **Related Tools:** [Mehrwertsteuer-Rechner](mehrwertsteuer-rechner-documentation.md) (for VAT), [Kostenrechner](kostenrechner-documentation.md) (for costs)

**Scenario 2: Employee Calculating Salary Increase**

- **User:** Employee negotiating salary increase
- **Situation:** Current salary €3,000/month, offered €3,300/month, want to calculate percentage increase
- **Goal:** Understand percentage increase for negotiation
- **Steps:**
  1. Select Percentage Change mode
  2. Enter old value: €3,000
  3. Enter new value: €3,300
  4. Review calculated percentage change
- **Result:** Sees 10% increase (€300 increase), can evaluate offer
- **Related Tools:** [Brutto-Netto-Rechner](brutto-netto-rechner-documentation.md) (for net calculation), [Einkommensteuer-Rechner](einkommensteuer-rechner-documentation.md) (for tax)

**Scenario 3: Investor Calculating Growth Rate**

- **User:** Investor analyzing investment returns
- **Situation:** Investment grew from €10,000 to €12,500 over 2 years, want to calculate annual growth rate
- **Goal:** Calculate compound annual growth rate
- **Steps:**
  1. Select Compound Percentage mode
  2. Enter initial value: €10,000
  3. Enter final value: €12,500
  4. Enter periods: 2 years
  5. Review calculated growth rate
- **Result:** Sees 11.8% annual growth rate, can compare with other investments
- **Related Tools:** [Zinseszinsrechner](zinseszinsrechner-documentation.md) (for detailed compound interest), [Einkommensteuer-Rechner](einkommensteuer-rechner-documentation.md) (for tax)

**Scenario 4: Restaurant Owner Calculating Tip**

- **User:** Restaurant owner calculating tip percentage
- **Situation:** Bill is €80, customer wants to tip 15%, need to calculate tip amount
- **Goal:** Calculate tip amount and total bill
- **Steps:**
  1. Select Basic Percentage mode
  2. Enter amount: €80
  3. Enter percentage: 15%
  4. Review calculated tip amount
  5. Add to bill for total
- **Result:** Sees €12 tip (15% of €80), €92 total bill
- **Related Tools:** [Mehrwertsteuer-Rechner](mehrwertsteuer-rechner-documentation.md) (for VAT), [PayPal Gebührenrechner](paypal-gebuehrenrechner-documentation.md) (for payment fees)

### Target Audience

- Business owners
- Accountants
- Students
- General users
- E-commerce sellers

### Visual Description

**Hero Section:**

- Layout: Centered hero section with badge, headline, and description
- Badge: "Prozentrechner" badge
- Headline: Large bold headline "Prozentrechner 2026: Prozente berechnen" with blue accent
- Description: Paragraph explaining percentage calculation capabilities
- Background: Subtle dot pattern background

**Visual Examples (To Be Added):**

**Hero Section Screenshot:**

- Location: `docs/guides/tools-pages/screenshots/prozentrechner-hero.png`
- Description: Full hero section showing badge, headline, description
- Dimensions: 1920x1080 (desktop), 375x667 (mobile)
- Shows: Complete above-fold content with visual styling

**Calculator Form Screenshot:**

- Location: `docs/guides/tools-pages/screenshots/prozentrechner-form.png`
- Description: Calculator form showing 8 calculation mode tabs
- Dimensions: 1920x1080 (desktop)
- Shows: Tab navigation, input fields, mode-specific forms

**Results Display Screenshot:**

- Location: `docs/guides/tools-pages/screenshots/prozentrechner-results.png`
- Description: Results section showing calculation results, formulas, examples
- Dimensions: 1920x1080 (desktop)
- Shows: Calculation result, formula display, step-by-step explanation

**Percentage Calculation Types Diagram:**

- Location: `docs/guides/tools-pages/diagrams/prozentrechner-types.svg`
- Description: Visual diagram showing different percentage calculation types
- Format: SVG (vector) for scalability
- Shows: 8 calculation modes with examples (Basic, Reverse, Change, Difference, Compound, Discount, VAT, Profit Margin)

**Calculator Form:**

- Layout: Single-column centered layout with tab navigation
- Tab Navigation: 8 tabs for different calculation modes:
  - Tab 1: Prozent von Zahl (Basic Percentage)
  - Tab 2: Prozentwert (Reverse Percentage)
  - Tab 3: Prozentuale Änderung (Percentage Change)
  - Tab 4: Prozentuale Differenz (Percentage Difference)
  - Tab 5: Zusammengesetzte Prozente (Compound Percentage)
  - Tab 6: Rabatt-Rechner (Discount Calculator)
  - Tab 7: Mehrwertsteuer-Rechner (VAT Calculator)
  - Tab 8: Gewinnspanne-Rechner (Profit Margin Calculator)
- Input Fields: Number inputs with German locale (comma as decimal separator)
- Calculate Button: Auto-calculation on input change (debounced 300ms)
- Styling: Blue accent color (#4D8EF3), gray borders, rounded corners, tab indicators

**Result Display:**

- Layout: Below form, centered
- Main Results: Large number display with formatted result
- Additional Results: Mode-specific additional calculations (e.g., discount amount, VAT amount, profit margin)
- Formula Display: Shows calculation formula
- Breakdown Table: For compound percentage mode (period-by-period breakdown)
- Styling: Green accent for results, blue for formulas

**Export & Sharing:**

- Export Buttons: Excel, PDF, CSV export buttons
- Email Gating: Email collection modal before export (stored in localStorage)
- Share Button: Web Share API or clipboard copy
- History: Calculation history sidebar with restore functionality

### UI/UX Flow

**Initial Load:**

- Page loads with hero section visible
- Calculator form shows default mode (Mode 1: Basic Percentage)
- Default values: Empty inputs
- No results displayed initially
- History sidebar hidden (can be toggled)

**User Interaction Flow:**

1. User selects calculation mode (tab click)
2. User enters values in input fields
3. Calculation runs automatically (debounced 300ms)
4. Results display below form
5. Formula displays below results
6. User can export results (Excel/PDF/CSV)
7. If first export: Email modal appears
8. Email collected and stored in localStorage
9. Export proceeds
10. Calculation added to history automatically

**Mode Switching:**

- Click tab to switch mode
- Input values preserved (not cleared)
- Results cleared when switching modes
- Tab indicator shows active mode

**Error Handling Flow:**

- Input validation: Real-time validation on input
- Error messages: Display below input fields (red text)
- Error states: Red border on invalid inputs
- Calculation errors: Display error message in results area

## Technical Documentation

### File Structure

- **PHP File:** `v2/pages/tools_prozentrechner.php` (3,404 lines)
- **JavaScript:** `v2/js/tools-prozentrechner-calculator.js` (extracted, 2,585 lines)
- **CSS:** Uses shared `v2/css/tools-pages.css` + extensive inline styles

### Code Organization

**Alpine.js Component Structure:**

- Main component: `prozentrechnerCalculator()` function (line 8 in JS file)
- Registered with: `Alpine.data('prozentrechnerCalculator', prozentrechnerCalculator)`
- All logic in external JS file
- No external API dependencies

**State Management:**

- Alpine.js reactive state for all UI state
- localStorage for calculation history and email collection
- URL parameters for sharing calculations
- No server-side state

**Code Patterns:**

- Alpine.js reactive data properties
- Debounced calculation function (300ms)
- Real-time calculation updates
- localStorage for persistence

### Calculation Modes

**Mode 1: Basic Percentage (X% of Y)**

- **Visual Description:** First tab, labeled "Prozent von Zahl"
- **Purpose:** Calculate percentage value from base value
- **Input Fields:**
  - `basicPercentage` (number input): Percentage value (0-100, step 0.01)
  - `basicBaseValue` (number input): Base value (≥0, step 0.01)
- **Output Fields:**
  - `basicResult` (display): Calculated percentage value
- **Formula:**

  ```
  Result = (Percentage / 100) × Base Value
  ```

- **Example Calculation:**

  ```
  Input: 20%, 100€
  Calculation: (20 / 100) × 100 = 20€
  Result: 20€
  ```

- **Validation:**
  - Percentage: 0-100, required
  - Base Value: ≥0, required
  - Error messages: Display below inputs

**Mode 2: Reverse Percentage (X is what % of Y)**

- **Visual Description:** Second tab, labeled "Prozentwert"
- **Purpose:** Calculate percentage from part and whole
- **Input Fields:**
  - `reversePart` (number input): Part value (≥0, step 0.01)
  - `reverseWhole` (number input): Whole value (>0, step 0.01)
- **Output Fields:**
  - `reverseResult` (display): Calculated percentage
- **Formula:**

  ```
  Result = (Part / Whole) × 100
  ```

- **Example Calculation:**

  ```
  Input: 25, 100
  Calculation: (25 / 100) × 100 = 25%
  Result: 25%
  ```

- **Validation:**
  - Part: ≥0, required
  - Whole: >0, required (division by zero check)
  - Error messages: Display below inputs

**Mode 3: Percentage Change (from X to Y)**

- **Visual Description:** Third tab, labeled "Prozentuale Änderung"
- **Purpose:** Calculate percentage change between two values
- **Input Fields:**
  - `changeOldValue` (number input): Old value (>0, step 0.01)
  - `changeNewValue` (number input): New value (≥0, step 0.01)
- **Output Fields:**
  - `changeResult` (display): Percentage change
  - `changeType` (display): "increase", "decrease", or "no-change"
- **Formula:**

  ```
  Result = ((New Value - Old Value) / Old Value) × 100
  Change Type = New > Old ? 'increase' : New < Old ? 'decrease' : 'no-change'
  ```

- **Example Calculation:**

  ```
  Input: 3000€, 3300€
  Calculation: ((3300 - 3000) / 3000) × 100 = 10%
  Result: 10% increase
  ```

- **Validation:**
  - Old Value: >0, required (division by zero check)
  - New Value: ≥0, required
  - Error messages: Display below inputs

**Mode 4: Percentage Difference (between X and Y)**

- **Visual Description:** Fourth tab, labeled "Prozentuale Differenz"
- **Purpose:** Calculate percentage difference between two values (symmetric)
- **Input Fields:**
  - `diffValue1` (number input): First value (≥0, step 0.01)
  - `diffValue2` (number input): Second value (≥0, step 0.01)
- **Output Fields:**
  - `diffResult` (display): Percentage difference
- **Formula:**

  ```
  Average = (Value1 + Value2) / 2
  Result = |(Value1 - Value2) / Average| × 100
  ```

- **Example Calculation:**

  ```
  Input: 80€, 100€
  Calculation: Average = (80 + 100) / 2 = 90
               Result = |(80 - 100) / 90| × 100 = 22.22%
  Result: 22.22%
  ```

- **Validation:**
  - Value 1: ≥0, required
  - Value 2: ≥0, required
  - Edge case: Both values = 0 → Result = 0%
  - Error messages: Display below inputs

**Mode 5: Compound Percentage**

- **Visual Description:** Fifth tab, labeled "Zusammengesetzte Prozente"
- **Purpose:** Calculate compound percentage growth over multiple periods
- **Input Fields:**
  - `compoundInitialValue` (number input): Initial value (≥0, step 0.01)
  - `compoundPercentage` (number input): Growth rate per period (can be negative, step 0.01)
  - `compoundPeriods` (number input): Number of periods (≥1, integer, step 1)
- **Output Fields:**
  - `compoundResult` (display): Final value after all periods
  - `compoundBreakdown` (table): Period-by-period breakdown showing:
    - Period number
    - Value at end of period
    - Increase for period
    - Total increase from initial
- **Formula:**

  ```
  Final Value = Initial Value × (1 + Percentage/100)^Periods

  For each period i:
    Period Value = Initial Value × (1 + Percentage/100)^i
    Period Increase = Period Value - Previous Value
    Total Increase = Period Value - Initial Value
  ```

- **Example Calculation:**

  ```
  Input: 1000€, 5%, 3 periods
  Calculation:
    Period 1: 1000 × 1.05 = 1050€ (increase: 50€)
    Period 2: 1000 × 1.05² = 1102.50€ (increase: 52.50€)
    Period 3: 1000 × 1.05³ = 1157.63€ (increase: 55.13€)
  Result: 1157.63€
  ```

- **Validation:**
  - Initial Value: ≥0, required
  - Percentage: Any number (can be negative), required
  - Periods: ≥1, integer, required
  - Error messages: Display below inputs

**Mode 6: Discount Calculator**

- **Visual Description:** Sixth tab, labeled "Rabatt-Rechner"
- **Purpose:** Calculate discount amount and final price
- **Input Fields:**
  - `discountOriginalPrice` (number input): Original price (≥0, step 0.01)
  - `discountPercentage` (number input): Discount percentage (0-100, step 0.01)
- **Output Fields:**
  - `discountAmount` (display): Discount amount in currency
  - `discountFinalPrice` (display): Final price after discount
- **Formula:**

  ```
  Discount Amount = Original Price × (Discount Percentage / 100)
  Final Price = Original Price - Discount Amount
  ```

- **Example Calculation:**

  ```
  Input: 100€, 20%
  Calculation:
    Discount Amount = 100 × 0.20 = 20€
    Final Price = 100 - 20 = 80€
  Result: Discount 20€, Final Price 80€
  ```

- **Validation:**
  - Original Price: ≥0, required
  - Discount Percentage: 0-100, required
  - Error messages: Display below inputs

**Mode 7: VAT Calculator**

- **Visual Description:** Seventh tab, labeled "Mehrwertsteuer-Rechner"
- **Purpose:** Calculate VAT (Mehrwertsteuer) from net or gross price
- **Input Fields:**
  - `vatMode` (radio/segmented control): "net" or "gross"
  - `vatNetPrice` (number input): Net price (if net mode, ≥0, step 0.01)
  - `vatGrossPrice` (number input): Gross price (if gross mode, ≥0, step 0.01)
  - `vatRate` (select): VAT rate - "19" (19%) or "7" (7%), default "19"
- **Output Fields:**
  - `vatAmount` (display): VAT amount in currency
  - `vatGrossPrice` (display): Gross price (if net mode)
  - `vatNetPrice` (display): Net price (if gross mode)
- **Formula:**

  ```
  If Net Mode:
    VAT Amount = Net Price × (VAT Rate / 100)
    Gross Price = Net Price + VAT Amount

  If Gross Mode:
    Net Price = Gross Price / (1 + VAT Rate / 100)
    VAT Amount = Gross Price - Net Price
  ```

- **Example Calculation (Net Mode):**

  ```
  Input: Net 100€, Rate 19%
  Calculation:
    VAT Amount = 100 × 0.19 = 19€
    Gross Price = 100 + 19 = 119€
  Result: VAT 19€, Gross 119€
  ```

- **Example Calculation (Gross Mode):**

  ```
  Input: Gross 119€, Rate 19%
  Calculation:
    Net Price = 119 / 1.19 = 100€
    VAT Amount = 119 - 100 = 19€
  Result: Net 100€, VAT 19€
  ```

- **Validation:**
  - VAT Rate: Must be 19 or 7
  - Net Price (if net mode): ≥0, required
  - Gross Price (if gross mode): ≥0, required
  - Error messages: Display below inputs

**Mode 8: Profit Margin Calculator**

- **Visual Description:** Eighth tab, labeled "Gewinnspanne-Rechner"
- **Purpose:** Calculate profit margin, markup, and profit amount
- **Input Fields:**
  - `marginCostPrice` (number input): Cost price (≥0, step 0.01)
  - `marginSellingPrice` (number input): Selling price (> cost price, step 0.01)
- **Output Fields:**
  - `marginProfitMargin` (display): Profit margin percentage
  - `marginMarkup` (display): Markup percentage
  - `marginProfitAmount` (display): Profit amount in currency
- **Formula:**

  ```
  Profit Amount = Selling Price - Cost Price
  Profit Margin = (Profit Amount / Selling Price) × 100
  Markup = (Profit Amount / Cost Price) × 100
  ```

- **Example Calculation:**

  ```
  Input: Cost 50€, Selling 75€
  Calculation:
    Profit Amount = 75 - 50 = 25€
    Profit Margin = (25 / 75) × 100 = 33.33%
    Markup = (25 / 50) × 100 = 50%
  Result: Margin 33.33%, Markup 50%, Profit 25€
  ```

- **Validation:**
  - Cost Price: ≥0, required
  - Selling Price: > Cost Price, required
  - Error messages: Display below inputs

### Constants and Thresholds

**2026 Values:**

- **Default VAT Rate:** 19% (German standard rate)
- **Reduced VAT Rate:** 7% (German reduced rate)
- **Debounce Delay:** 300ms (calculation trigger)
- **History Max Items:** 50 (calculation history limit)
- **Export Email Gating:** Enabled (first export requires email)

**Previous Values (for reference):**

- Same structure, but VAT rates need annual verification

### Validation Rules

- **All numeric inputs:** min=0 (or negative for decreases), step=0.01
- **Percentage inputs:** min=0, max=100 (or 1000 for some modes), step=0.01
- **Periods:** min=1, max=1000, step=1 (must be integer)
- **VAT Rate:** Must be 19 or 7
- **Selling Price:** Must be > Cost Price (profit margin mode)

### Edge Cases Handled

- Zero values (handled gracefully)
- Negative values (for decreases in compound mode)
- Very large numbers (precision maintained)
- Division by zero protection (reverse percentage, percentage change)
- Both values zero (percentage difference → 0%)
- Non-integer periods (compound mode → error)
- Selling price ≤ cost price (profit margin → error)

### Dependencies

- **External Libraries:**
  - XLSX.js (Excel export)
  - jsPDF + html2canvas (PDF export)
- **APIs:** None
- **Alpine.js:** Used for reactive UI (version from base includes)
- **localStorage:** Calculation history and email collection
- **External JavaScript:** `v2/js/tools-prozentrechner-calculator.js`

## Functions & Methods

### Main Component Function

**Function:** `prozentrechnerCalculator()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:8`
- **Purpose:** Main Alpine.js component for percentage calculator
- **Returns:** Alpine.js component object
- **Dependencies:** Alpine.js framework
- **Side Effects:** Manages DOM state, triggers calculations, manages localStorage

### Calculation Functions

**Function:** `calculate()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:860`
- **Purpose:** Main calculation dispatcher
- **Parameters:** None (uses component state)
- **Returns:** void (calls mode-specific calculation functions)
- **Dependencies:** Mode-specific calculation functions
- **Side Effects:** Updates result properties, adds to history

**Function:** `calculateBasic()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:902`
- **Purpose:** Calculate basic percentage (Mode 1)
- **Formula:** `Result = (Percentage / 100) × Base Value`

**Function:** `calculateReverse()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:936`
- **Purpose:** Calculate reverse percentage (Mode 2)
- **Formula:** `Result = (Part / Whole) × 100`

**Function:** `calculateChange()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:975`
- **Purpose:** Calculate percentage change (Mode 3)
- **Formula:** `Result = ((New - Old) / Old) × 100`

**Function:** `calculateDifference()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1018`
- **Purpose:** Calculate percentage difference (Mode 4)
- **Formula:** `Result = |(Value1 - Value2) / Average| × 100`

**Function:** `calculateCompound()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1063`
- **Purpose:** Calculate compound percentage (Mode 5)
- **Formula:** `Final = Initial × (1 + Percentage/100)^Periods`

**Function:** `calculateDiscount()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1138`
- **Purpose:** Calculate discount (Mode 6)
- **Formula:** `Discount = Original × (Percentage / 100), Final = Original - Discount`

**Function:** `calculateVAT()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1177`
- **Purpose:** Calculate VAT (Mode 7)
- **Formula:** Net mode: `Gross = Net × (1 + Rate/100)`, Gross mode: `Net = Gross / (1 + Rate/100)`

**Function:** `calculateProfitMargin()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1237`
- **Purpose:** Calculate profit margin (Mode 8)
- **Formula:** `Margin = ((Selling - Cost) / Selling) × 100, Markup = ((Selling - Cost) / Cost) × 100`

### Utility Functions

**Function:** `formatNumber(num, decimals)`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:811`
- **Purpose:** Format number with German locale
- **Parameters:** `num` (number), `decimals` (number, default 2)
- **Returns:** String (formatted number)

**Function:** `formatPercentage(num, decimals)`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:819`
- **Purpose:** Format number as percentage
- **Parameters:** `num` (number), `decimals` (number, default 2)
- **Returns:** String (formatted percentage with %)

**Function:** `parseNumber(value)`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:826`
- **Purpose:** Parse German number format (comma as decimal separator)
- **Parameters:** `value` (string)
- **Returns:** Number or null

**Function:** `validateNumber(value, min, max)`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:835`
- **Purpose:** Validate number input
- **Parameters:** `value` (string), `min` (number or null), `max` (number or null)
- **Returns:** String (error message) or null

**Function:** `debouncedCalculate()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:850`
- **Purpose:** Debounced calculation trigger (300ms)
- **Parameters:** None
- **Returns:** void (calls `calculate()`)

### Export Functions

**Function:** `exportExcel()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1340`
- **Purpose:** Trigger Excel export (with email gating)
- **Dependencies:** XLSX.js library

**Function:** `performExcelExport()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1358`
- **Purpose:** Generate Excel file with Ordio branding
- **Dependencies:** XLSX.js library

**Function:** `exportPDF()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1510`
- **Purpose:** Trigger PDF export (with email gating)
- **Dependencies:** jsPDF, html2canvas libraries

**Function:** `performPDFExport()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1528`
- **Purpose:** Generate PDF file with Ordio branding
- **Dependencies:** jsPDF, html2canvas libraries

**Function:** `exportCSV()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:1700+` (approximate)
- **Purpose:** Generate CSV file
- **Dependencies:** None (native JavaScript)

### History Functions

**Function:** `addToHistory()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:343`
- **Purpose:** Add current calculation to history
- **Dependencies:** localStorage

**Function:** `loadHistory()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:276`
- **Purpose:** Load calculation history from localStorage
- **Dependencies:** localStorage

**Function:** `saveHistory()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:294`
- **Purpose:** Save calculation history to localStorage
- **Dependencies:** localStorage

**Function:** `restoreFromHistory(historyItem)`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:429`
- **Purpose:** Restore calculation from history
- **Parameters:** `historyItem` (object)

### Sharing Functions

**Function:** `shareCalculation()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:533`
- **Purpose:** Share calculation via Web Share API or clipboard
- **Dependencies:** Web Share API (if available), clipboard API

**Function:** `generateShareURL()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:614`
- **Purpose:** Generate shareable URL with calculation parameters
- **Returns:** String (URL with parameters)

**Function:** `loadFromURL()`

- **Location:** `v2/js/tools-prozentrechner-calculator.js:648`
- **Purpose:** Load calculation from URL parameters
- **Dependencies:** URLSearchParams API

## Formulas & Calculations

### Primary Formulas

**Mode 1: Basic Percentage**

```
Result = (Percentage / 100) × Base Value
```

**Mode 2: Reverse Percentage**

```
Result = (Part / Whole) × 100
```

**Mode 3: Percentage Change**

```
Result = ((New Value - Old Value) / Old Value) × 100
Change Type = New > Old ? 'increase' : New < Old ? 'decrease' : 'no-change'
```

**Mode 4: Percentage Difference**

```
Average = (Value1 + Value2) / 2
Result = |(Value1 - Value2) / Average| × 100
```

**Mode 5: Compound Percentage**

```
Final Value = Initial Value × (1 + Percentage/100)^Periods

For each period i:
  Period Value = Initial Value × (1 + Percentage/100)^i
  Period Increase = Period Value - Previous Value
  Total Increase = Period Value - Initial Value
```

**Mode 6: Discount**

```
Discount Amount = Original Price × (Discount Percentage / 100)
Final Price = Original Price - Discount Amount
```

**Mode 7: VAT**

```
If Net Mode:
  VAT Amount = Net Price × (VAT Rate / 100)
  Gross Price = Net Price + VAT Amount

If Gross Mode:
  Net Price = Gross Price / (1 + VAT Rate / 100)
  VAT Amount = Gross Price - Net Price
```

**Mode 8: Profit Margin**

```
Profit Amount = Selling Price - Cost Price
Profit Margin = (Profit Amount / Selling Price) × 100
Markup = (Profit Amount / Cost Price) × 100
```

### Legal Basis

- **UStG (Umsatzsteuergesetz):** German VAT law (for VAT mode)
  - Standard rate: 19%
  - Reduced rate: 7%
- **No specific laws:** General percentage calculations (mathematical formulas)

### Step-by-Step Calculation Examples

**Example 1: Basic Percentage**

- Input: 20%, 100€
- Step 1: Convert percentage: 20 / 100 = 0.20
- Step 2: Multiply: 0.20 × 100 = 20€
- Result: 20€

**Example 2: Reverse Percentage**

- Input: 25, 100
- Step 1: Divide: 25 / 100 = 0.25
- Step 2: Multiply: 0.25 × 100 = 25%
- Result: 25%

**Example 3: Percentage Change**

- Input: 3000€, 3300€
- Step 1: Calculate difference: 3300 - 3000 = 300€
- Step 2: Divide by old value: 300 / 3000 = 0.10
- Step 3: Multiply: 0.10 × 100 = 10%
- Result: 10% increase

**Example 4: Compound Percentage**

- Input: 1000€, 5%, 3 periods
- Step 1: Calculate rate: 1 + 0.05 = 1.05
- Step 2: Period 1: 1000 × 1.05 = 1050€
- Step 3: Period 2: 1000 × 1.05² = 1102.50€
- Step 4: Period 3: 1000 × 1.05³ = 1157.63€
- Result: 1157.63€

**Example 5: VAT (Net Mode)**

- Input: Net 100€, Rate 19%
- Step 1: Calculate VAT: 100 × 0.19 = 19€
- Step 2: Calculate Gross: 100 + 19 = 119€
- Result: VAT 19€, Gross 119€

**Example 6: Profit Margin**

- Input: Cost 50€, Selling 75€
- Step 1: Calculate profit: 75 - 50 = 25€
- Step 2: Calculate margin: (25 / 75) × 100 = 33.33%
- Step 3: Calculate markup: (25 / 50) × 100 = 50%
- Result: Margin 33.33%, Markup 50%, Profit 25€

## Export Functionality

### Export Types

**Excel Export (.xlsx):**

- Format: XLSX format (Excel 2007+)
- Content:
  - Ordio branding header
  - Calculation mode
  - Input values
  - Results
  - Formula
  - Breakdown table (for compound mode)
- Filename: `Ordio_Prozentrechner_[Mode]_[Date].xlsx`
- Library: XLSX.js

**PDF Export (.pdf):**

- Format: PDF format (A4)
- Content:
  - Ordio branding header
  - Calculation mode
  - Input values
  - Results
  - Formula
  - Breakdown table (for compound mode)
- Filename: `Ordio_Prozentrechner_[Mode]_[Date].pdf`
- Libraries: jsPDF, html2canvas

**CSV Export (.csv):**

- Format: CSV format (semicolon-separated)
- Content:
  - Calculation history (all calculations)
  - Columns: Timestamp, Mode, Inputs, Result, Formula
- Filename: `prozentrechner-verlauf-[Date].csv`
- Library: Native JavaScript

### Email Gating

- **First Export:** Email modal appears
- **Email Collection:** Email stored in localStorage
- **Subsequent Exports:** No email prompt (email remembered)
- **Email Validation:** Basic email format validation
- **HubSpot Integration:** Email sent to HubSpot (if configured)

### Sharing

- **Web Share API:** Native share dialog (mobile)
- **Clipboard Fallback:** Copy calculation text and URL
- **URL Parameters:** Calculation encoded in URL
- **Share Text:** Formatted calculation result with Ordio branding

## Results & Insights

### Result Display

**Primary Results:**

- Large number display (formatted with German locale)
- Mode-specific additional results:
  - Mode 3: Change type indicator (increase/decrease)
  - Mode 5: Breakdown table
  - Mode 6: Discount amount + final price
  - Mode 7: VAT amount + net/gross price
  - Mode 8: Profit margin + markup + profit amount

**Formula Display:**

- Shows calculation formula below results
- Mode-specific formulas displayed
- Formula uses actual input values

**Breakdown Table (Compound Mode):**

- Period-by-period breakdown
- Columns: Period, Value, Increase, Total Increase
- Scrollable table for many periods

**History Sidebar:**

- List of previous calculations
- Restore functionality
- Delete individual items
- Export history as CSV
- Clear all history

### Smart Features

- **Auto-calculation:** Debounced (300ms) on input change
- **History:** Automatic history addition (debounced 1s)
- **URL Sharing:** Calculation encoded in URL
- **Email Gating:** Email collection for exports
- **Examples:** Quick example buttons for each mode

## Browser Testing Results

### Desktop Browsers

**Chrome (Latest):**

- Status: ✅ Fully functional
- Issues: None
- Notes: All 8 modes working correctly, exports functional

**Firefox (Latest):**

- Status: ✅ Fully functional
- Issues: None
- Notes: All features working correctly

**Safari (Latest):**

- Status: ✅ Fully functional
- Issues: None
- Notes: All features working correctly

**Edge (Latest):**

- Status: ✅ Fully functional
- Issues: None
- Notes: All features working correctly

### Mobile Testing

**iOS Safari:**

- Status: ✅ Functional
- Device: iPhone (tested)
- Issues: Minor UI adjustments on small screens
- Notes: Tab navigation works well, responsive design adapts

**Android Chrome:**

- Status: ✅ Functional
- Device: Android (tested)
- Issues: None
- Notes: Touch interactions work correctly

**Mobile UI Differences:**

- Tabs scroll horizontally on mobile
- Results stack vertically on small screens
- History sidebar becomes modal on mobile
- Export buttons adapt to mobile layout

### Responsive Design

**Desktop (>1024px):**

- Layout: Centered single-column
- Tabs: Horizontal tab navigation
- Results: Below form
- History: Sidebar (toggleable)

**Tablet (768px-1024px):**

- Layout: Centered single-column
- Tabs: Horizontal tab navigation (scrollable)
- Results: Below form
- History: Sidebar (toggleable)

**Mobile (<768px):**

- Layout: Full-width single-column
- Tabs: Horizontal scrollable tabs
- Results: Below form
- History: Modal overlay

**Breakpoints:**

- Mobile: < 768px
- Tablet: 768px - 1024px
- Desktop: > 1024px

### Accessibility

**Keyboard Navigation:**

- Tab navigation works through all form fields
- Tab switching with arrow keys
- Enter/Space to activate tabs
- Focus indicators visible

**Screen Reader:**

- Form labels properly associated
- Results announced after calculation
- Tab roles properly set
- ARIA labels on interactive elements

**ARIA Labels:**

- Input fields have labels
- Tabs have proper roles
- Results have proper roles
- History items have proper roles

## Code Analysis

### Key Functions Location

- Main component: `v2/js/tools-prozentrechner-calculator.js:8`
- Calculation dispatcher: `v2/js/tools-prozentrechner-calculator.js:860`
- Mode 1: `v2/js/tools-prozentrechner-calculator.js:902`
- Mode 2: `v2/js/tools-prozentrechner-calculator.js:936`
- Mode 3: `v2/js/tools-prozentrechner-calculator.js:975`
- Mode 4: `v2/js/tools-prozentrechner-calculator.js:1018`
- Mode 5: `v2/js/tools-prozentrechner-calculator.js:1063`
- Mode 6: `v2/js/tools-prozentrechner-calculator.js:1138`
- Mode 7: `v2/js/tools-prozentrechner-calculator.js:1177`
- Mode 8: `v2/js/tools-prozentrechner-calculator.js:1237`

### Constants Location

- Default values: Embedded in component data (line 11+)
- VAT rates: Hardcoded in `calculateVAT()` function (19% and 7%)
- History limit: `maxHistoryItems: 50` (line 270+)
- Debounce delay: 300ms (line 856)

### Calculation Logic Flow

1. **User Input:**

   - User changes input field
   - Debounced calculation triggered (300ms)

2. **Validation:**

   - Input parsed and validated
   - Error messages displayed if invalid

3. **Calculation:**

   - Mode-specific calculation function called
   - Result calculated using formula
   - Additional results calculated (if applicable)

4. **Display:**

   - Results updated in component state
   - UI updates automatically (Alpine.js reactivity)
   - Formula displayed below results

5. **History:**
   - Calculation added to history (debounced 1s)
   - History saved to localStorage

## Content Documentation

### Hero Section

- **H1:** "Prozentrechner 2026: Prozente berechnen" (✅ Already "2026")
- **Description:** "Prozentrechner Online 2026: Berechne Prozente, Prozentsatz & Prozentwert mit Formeln. Kostenloser Rechner mit Excel-Export & PDF-Report. Rabatte, Steigerungen, Differenzen."

### Educational Content Sections

1. **Percentage Basics**

   - Basic percentage calculation explained
   - Reverse percentage calculation explained
   - Percentage change calculation explained

2. **Business Applications**

   - Discount calculations explained
   - VAT calculations explained
   - Profit margin calculations explained

3. **Advanced Calculations**

   - Compound percentage explained
   - Percentage difference explained
   - Formula explanations for all modes

### FAQ Section

- **Total FAQs:** ~20 FAQs
- **FAQ Topics:**
  - Basic Calculation: 5 FAQs
  - Business Applications: 5 FAQs
  - Advanced Calculations: 5 FAQs
  - Export Features: 5 FAQs

**Sample FAQs:**

1. "Wie berechne ich Prozente?"
2. "Wie berechne ich die Mehrwertsteuer?"
3. "Wie funktioniert der Excel-Export?"
4. "Was ist der Unterschied zwischen Gewinnspanne und Aufschlag?"
5. "Wie berechne ich zusammengesetzte Prozente?"

### Meta Tags

- **Title:** "Prozentrechner 2026: Prozente berechnen - Ordio" (✅ Already "2026")
- **Description:** "Prozentrechner Online 2026: Berechne Prozente, Prozentsatz & Prozentwert mit Formeln. Kostenloser Rechner mit Excel-Export & PDF-Report. Rabatte, Steigerungen, Differenzen."
- **Keywords:** prozentrechner, prozentrechner online, prozentrechnung formel, prozentsatz berechnen, prozentwert berechnen

### Schema Markup

- **WebApplication schema:** Yes
- **FAQPage schema:** Yes
- **HowTo schema:** Yes
- **BreadcrumbList schema:** Yes

### Internal Linking

- Links to: Mehrwertsteuer-Rechner, Zinseszinsrechner
- Link count: 2-3 internal links

## 2026 Update Requirements

### Immediate Updates (Required for Jan 1, 2026)

**Constants/Values:**

- ✅ VAT Rates: Already correct (19% standard, 7% reduced)
- ✅ JavaScript Comments: Update any "2025" references to "2026" (if present)

**Content:**

- ✅ Title: Already "2026"
- ✅ Description: Already "2026"
- ✅ Educational sections: Review for "2025" → "2026" updates
- ✅ FAQs: Review and update year references (~20 FAQs)

**Priority:** 🟢 LOW (Year references only, VAT rates already correct)

### Throughout 2026 Updates

**Scheduled Updates:**

- None scheduled (formulas stable, VAT rates typically stable)

### Monitoring Requirements

- **Bundesfinanzministerium:** Check for VAT rate changes
- **Frequency:** Annually (January) or when VAT laws change
- **Source:** Official VAT law updates (UStG)

## Testing

### Automated Test Suite

**Test Script Location:** `v2/scripts/dev-helpers/test-prozentrechner-calculations.js`

**Test Coverage:**
- **Total Test Cases:** 50 test cases covering all 8 calculation modes
- **Basic Percentage:** 6 test cases (standard, decimal, zero, 100%, zero base, large numbers)
- **Reverse Percentage:** 5 test cases (standard, part equals whole, part > whole, zero part, division by zero)
- **Percentage Change:** 4 test cases (increase, decrease, no change, division by zero)
- **Percentage Difference:** 4 test cases (standard, identical values, both zero, very different values)
- **Compound Percentage:** 4 test cases (standard, one period, zero periods, negative percentage)
- **Discount Calculator:** 4 test cases (standard, zero discount, 100% discount, decimal discount)
- **VAT Calculator:** 7 test cases (net→gross 19%, net→gross 7%, gross→net 19%, gross→net 7%, zero price, invalid rate, large price)
- **Profit Margin:** 5 test cases (standard, equal prices, selling < cost, very small margin, large margin)
- **Edge Cases:** 11 additional test cases (invalid inputs, rounding, decimal precision)

**How to Run Tests:**
```bash
node v2/scripts/dev-helpers/test-prozentrechner-calculations.js
```

**Test Results:** All 50 tests passing (100% pass rate) ✅

### Test Cases

**Normal Cases:**

- Test 1: Mode 1 - 20% of 100€ → Expected: 20€
- Test 2: Mode 2 - 25 of 100 → Expected: 25%
- Test 3: Mode 3 - 3000€ to 3300€ → Expected: 10% increase
- Test 4: Mode 4 - 80€ and 100€ → Expected: 22.22%
- Test 5: Mode 5 - 1000€, 5%, 3 periods → Expected: 1157.63€
- Test 6: Mode 6 - 100€, 20% → Expected: 20€ discount, 80€ final
- Test 7: Mode 7 - 100€ net, 19% → Expected: 19€ VAT, 119€ gross
- Test 8: Mode 8 - 50€ cost, 75€ selling → Expected: 33.33% margin, 50% markup

**Edge Cases:**

- Edge case 1: Zero values → Expected: Handled gracefully
- Edge case 2: Negative values (compound mode) → Expected: Correct calculation
- Edge case 3: Very large numbers → Expected: Correct precision
- Edge case 4: Division by zero → Expected: Error handling
- Edge case 5: Selling price ≤ cost price → Expected: Error message

### Browser Testing

- Chrome: ✅ Tested, working
- Firefox: ✅ Tested, working
- Safari: ✅ Tested, working
- Mobile: ✅ Tested, working

### Export Testing

- Excel: ✅ Functional (XLSX.js)
- PDF: ✅ Functional (jsPDF + html2canvas)
- CSV: ✅ Functional (native JavaScript)

## Content Structure

### Hero Section

- **H1 Title:** To be documented
- **Meta Description:** Prozentrechner Online 2026: Berechne Prozente, Prozentsatz & Prozentwert mit Formeln. Kostenloser Re

### FAQs

- **Total FAQs:** 12
- Q: Wie ist die Formel für Prozentrechnung?...
- Q: Wie berechnet man den Prozentsatz?...
- Q: Wie berechnet man den Prozentwert?...

## Maintenance Notes

### Known Issues

- None currently

### Future Improvements

- Add more calculation modes (if needed)
- Add visual formula display (interactive)
- Add calculation history export improvements
- Add comparison mode (compare different calculations)

### Related Tools

**Complementary Tools:**

- **[Mehrwertsteuer-Rechner](mehrwertsteuer-rechner-documentation.md)** - Calculate VAT

  - Use together when: Need comprehensive VAT calculations beyond basic percentage
  - Example workflow: Calculate percentage → Calculate VAT → Total pricing

- **[Zinseszinsrechner](zinseszinsrechner-documentation.md)** - Calculate compound interest

  - Use together when: Need detailed compound interest calculations
  - Example workflow: Calculate percentage growth → Calculate compound interest → Investment planning

- **[Brutto-Netto-Rechner](brutto-netto-rechner-documentation.md)** - Calculate gross-to-net salary
  - Use together when: Need percentage calculations for salary changes
  - Example workflow: Calculate percentage increase → Calculate net salary → Salary planning

**Sequential Tools:**

- **[Einkommensteuer-Rechner](einkommensteuer-rechner-documentation.md)** - Calculate income tax

  - Use after: Calculating percentage changes in income
  - Use before: Tax planning

- **[Kostenrechner](kostenrechner-documentation.md)** - Calculate business costs
  - Use after: Calculating percentage changes
  - Use before: Overall cost analysis

## References

### Official Sources

- **Bundesfinanzministerium:** VAT rates (for VAT mode)
- **UStG (Umsatzsteuergesetz):** German VAT law

### Documentation Files

- `BROWSER_TESTING_FRAMEWORK.md`: Browser testing guidelines
- `CODE_ANALYSIS_FRAMEWORK.md`: Code analysis guidelines
- `TOOL_DOCUMENTATION_TEMPLATE.md`: Documentation template