# Zuschlagsrechner - Comprehensive Documentation

**Last Updated:** 2026-03-29

## Tool Overview

### Basic Information

- **Tool Name:** Zuschlagsrechner
- **Slug:** `zuschlagsrechner`
- **URL:** `https://www.ordio.com/tools/zuschlagsrechner`
- **Status:** Available
- **Last Updated:** 2026-01-21

### Purpose

Bereitstellung eines **Modellrechners** für Brutto-Zuschläge (Nacht, Sonntag, Feiertag, optional Samstag) aus Stundenlohn × Prozentsatz × Stunden. **Rechtliche Einordnung:** Steuerfreiheitsgrenzen nach **§3b EStG** (amtlicher Text: [gesetze-im-internet.de/estg/__3b.html](https://www.gesetze-im-internet.de/estg/__3b.html)); Zulagen nach **ArbZG** gesondert. **§3b Abs. 2:** Ansetzung des Stundenlohns für die Prozentgrenzen höchstens **50 €** je Stunde. Keine Steuerberatung.

## Technical Implementation

### Files

- **PHP:** `v2/pages/tools_zuschlagsrechner.php`
- **FAQ (sichtbar + JSON-LD):** `v2/data/tools_zuschlagsrechner_faq.php` (ein gemeinsamer Datensatz)
- **Research:** `docs/content/tools/zuschlagsrechner/` (SERP_ANALYSIS, CONTENT_OUTLINE), `docs/guides/tools-pages/data/zuschlagsrechner-serp-gap-matrix.md` (Intent-, E-E-A-T- und Mess-Notizen; fortlaufend pflegen), `docs/guides/tools-pages/data/zuschlagsrechner-gsc-ga-template.md`
- **JavaScript:** `/v2/js/tools-zuschlags-calculator.js?v=<?php echo filemtime(__DIR__ . `
- **JavaScript:** `/v2/js/lead-capture-triggers.min.js?v=<?php echo filemtime(__DIR__ . `
Calculate surcharges (Zuschläge) for night work, Sunday work, holiday work, and Saturday work based on base wage and customizable surcharge rates. Provides detailed breakdowns of surcharge amounts, total earnings, and supports PDF/CSV export. Industry-compliant surcharge rates with detailed breakdowns.

### Use Cases

- **Employees:** Calculate surcharge earnings for shift work
- **Employers:** Calculate surcharge costs for payroll planning
- **HR Professionals:** Calculate payroll surcharges accurately
- **Shift Workers:** Understand surcharge rates and total earnings
- **Payroll Administrators:** Process surcharge calculations efficiently

### Real-World Scenarios

**Scenario 1: Night Shift Worker Calculating Earnings**
- **User:** Employee working night shifts
- **Situation:** Works 8 hours night shift (22:00-06:00), base wage €15/hour, wants to calculate total earnings
- **Goal:** Understand total earnings including night surcharge
- **Steps:**
  1. Enter base wage: €15/hour
  2. Enter working hours: 8 hours
  3. Select night shift surcharge: 25% (standard)
  4. Review calculated surcharge amount
  5. See total earnings (base + surcharge)
- **Result:** Sees €30 surcharge (8h × €15 × 25%), €150 total earnings
- **Related Tools:** [Arbeitszeitrechner](arbeitszeitrechner-documentation.md) (for working hours), [Stundenlohnrechner](stundenlohnrechner-documentation.md) (for hourly rate)

**Scenario 2: HR Manager Planning Holiday Payroll**
- **User:** HR professional planning payroll for holiday shifts
- **Situation:** 5 employees working Christmas Day (8 hours each), base wage €18/hour, need to calculate costs
- **Goal:** Calculate total surcharge costs for holiday payroll
- **Steps:**
  1. Enter base wage: €18/hour
  2. Enter working hours: 8 hours × 5 employees = 40 hours
  3. Select holiday surcharge: 100% (standard)
  4. Review calculated surcharge amount
  5. Multiply by number of employees
  6. Budget for payroll
- **Result:** Sees €720 surcharge (40h × €18 × 100%), €1,440 total cost
- **Related Tools:** [Kostenrechner](kostenrechner-documentation.md) (for overall costs), [Brutto-Netto-Rechner](brutto-netto-rechner-documentation.md) (for net calculation)

**Scenario 3: Sunday Worker Verifying Pay**
- **User:** Employee working Sunday shifts
- **Situation:** Works 6 hours on Sunday, base wage €16/hour, received €96, wants to verify
- **Goal:** Verify if Sunday surcharge was correctly applied
- **Steps:**
  1. Enter base wage: €16/hour
  2. Enter working hours: 6 hours
  3. Select Sunday surcharge: 50% (standard)
  4. Review calculated total
  5. Compare with received payment
- **Result:** Sees €48 surcharge (6h × €16 × 50%), €144 total (should receive), identifies discrepancy
- **Related Tools:** [Brutto-Netto-Rechner](brutto-netto-rechner-documentation.md) (for net calculation), [Arbeitszeitrechner](arbeitszeitrechner-documentation.md) (for hours verification)

**Scenario 4: Employer Optimizing Shift Costs**
- **User:** Business owner planning shift schedule
- **Situation:** Need to schedule shifts, want to minimize surcharge costs while maintaining coverage
- **Goal:** Compare surcharge costs for different shift scenarios
- **Steps:**
  1. Calculate surcharges for night shift scenario
  2. Calculate surcharges for day shift scenario
  3. Compare total costs
  4. Optimize schedule to minimize surcharges
  5. Balance coverage with cost efficiency
- **Result:** Sees cost difference between scenarios, can optimize schedule
- **Related Tools:** [ROI-Rechner Schichtplanung](roi-rechner-schichtplanung-documentation.md) (for ROI analysis), [Kostenrechner](kostenrechner-documentation.md) (for total costs)

### Target Audience

- Shift workers
- Employers
- HR professionals
- Night/weekend workers
- Payroll administrators

### Visual Description

**Hero Section:**

- Layout: Centered hero section with headline and description
- Headline: Large bold headline "Zuschlagsrechner 2026: Nacht- & Feiertagszuschläge berechnen"
- Description: Paragraph explaining surcharge calculation
- Badge: "Zuschläge" badge (if applicable)

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

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

**Calculator Form Screenshot:**
- Location: `docs/guides/tools-pages/screenshots/zuschlagsrechner-form.png`
- Description: Calculator form showing base wage, hours, surcharge type selection
- Dimensions: 1920x1080 (desktop)
- Shows: Input fields, surcharge type buttons (night/Sunday/holiday), calculate button

**Result Display Screenshot:**
- Location: `docs/guides/tools-pages/screenshots/zuschlagsrechner-results.png`
- Description: Results section showing surcharge breakdown, total earnings
- Dimensions: 1920x1080 (desktop)
- Shows: Base wage, surcharge amount, surcharge percentage, total earnings breakdown

**Surcharge Types Diagram:**
- Location: `docs/guides/tools-pages/diagrams/zuschlagsrechner-types.svg`
- Description: Visual diagram showing different surcharge types and rates
- Format: SVG (vector) for scalability
- Shows: Night/Sunday/Holiday/Saturday surcharges with standard rates

**Calculator Form:**

- Layout: White card with rounded corners, shadow, centered max-width container
- Base Wage Input: Number input for hourly wage (€/hour)
- Surcharge Sections: Four sections for each surcharge type:
  - Nachtarbeit (Night Work) - Blue accent
  - Sonntagsarbeit (Sunday Work) - Orange accent
  - Feiertagsarbeit (Holiday Work) - Red accent
  - Samstagsarbeit (Saturday Work) - Green accent
- Each Section: Hours input and surcharge rate input (%)
- Advanced Toggle: Button to show/hide advanced options
- Styling: Color-coded sections, rounded corners, hover effects

**Result Display:**

- Layout: Summary section below form
- Total Surcharge: Large display of total surcharge amount
- Total Hours: Display of total hours worked
- Total Earnings: Large display of total earnings (base + surcharges)
- Breakdown Table: Table showing each surcharge type with amounts
- Export Buttons: PDF and CSV export buttons

### UI/UX Flow

**Initial Load:**

- Page loads with hero section visible
- Calculator form shows default values:
  - Base Wage: 15.00 €/hour
  - All hours: 0
  - Default surcharge rates: Nacht 25%, Sonntag 50%, Feiertag 100%, Samstag 25%
- No results displayed initially
- Advanced options hidden by default

**User Interaction Flow:**

1. User enters base wage
2. User enters hours for each surcharge type (if applicable)
3. User can adjust surcharge rates (defaults shown)
4. Calculation happens automatically as user types (real-time)
5. Results appear immediately below form
6. User can view breakdown table
7. User can export results (PDF/CSV) - email gating on first export
8. User can toggle advanced options for custom rates

**Error Handling Flow:**

- Invalid input shows validation messages
- Results update automatically when inputs change
- Export requires valid email (if not previously collected)

**Export Flow:**

1. User clicks export button (PDF or CSV)
2. If email not previously collected, email modal appears
3. User enters email address
4. Email validated in real-time
5. Email sent to HubSpot API
6. Email stored in localStorage
7. Export file generated and downloaded
8. Success message displayed

## Technical Documentation

### File Structure

- **PHP File:** `v2/pages/tools_zuschlagsrechner.php` (~2,254 lines)
- **JavaScript File:** `v2/js/tools-zuschlags-calculator.js` (664 lines, extracted)
- **CSS:** Uses shared `v2/css/tools-pages.css` + inline styles

### Code Organization

**Alpine.js Component Structure:**

- Main component: `zuschlagsrechnerCalculator()` - handles all calculator logic
- Component registered with `Alpine.data('zuschlagsrechnerCalculator')`
- Component accessible globally via `window.zuschlagsrechnerCalculator`

**State Management:**

- Alpine.js reactive state for all UI state
- localStorage for email persistence
- No URL parameter sharing

**Code Patterns:**

- Alpine.js reactive data properties
- Computed properties for derived values
- Real-time calculation on input change
- Export functions with email gating
- HubSpot API integration

### Calculation Modes

**Single Mode: Comprehensive Surcharge Calculator**

- **Visual Description:** Single calculation mode with four surcharge types
- **Purpose:** Calculate surcharges for all work types in one calculation
- **Input Fields:**
  - `baseWage` (number): Base hourly wage in €/hour
    - Type: Number input
    - Placeholder: "z. B. 15,00"
    - Default: 15.00
    - Validation: min=0, step=0.01
    - Format: Currency (€)
  - `nachtStunden` (number): Night work hours
    - Type: Number input
    - Placeholder: "0"
    - Default: 0
    - Validation: min=0, step=0.25
  - `nachtZuschlag` (number): Night work surcharge rate (%)
    - Type: Number input
    - Placeholder: "25"
    - Default: 25
    - Validation: min=0, max=100, step=1
  - `sonntagStunden` (number): Sunday work hours
    - Type: Number input
    - Placeholder: "0"
    - Default: 0
    - Validation: min=0, step=0.25
  - `sonntagZuschlag` (number): Sunday work surcharge rate (%)
    - Type: Number input
    - Placeholder: "50"
    - Default: 50
    - Validation: min=0, max=100, step=1
  - `feiertagStunden` (number): Holiday work hours
    - Type: Number input
    - Placeholder: "0"
    - Default: 0
    - Validation: min=0, step=0.25
  - `feiertagZuschlag` (number): Holiday work surcharge rate (%)
    - Type: Number input
    - Placeholder: "100"
    - Default: 100
    - Validation: min=0, max=100, step=1
  - `samstagStunden` (number): Saturday work hours
    - Type: Number input
    - Placeholder: "0"
    - Default: 0
    - Validation: min=0, step=0.25
  - `samstagZuschlag` (number): Saturday work surcharge rate (%)
    - Type: Number input
    - Placeholder: "25"
    - Default: 25
    - Validation: min=0, max=100, step=1
- **Output Fields:**
  - `totalZuschlag` (number): Total surcharge amount in €
  - `totalHours` (number): Total hours worked
  - `totalEarnings` (number): Total earnings (base wage + surcharges) in €
  - Breakdown by type: Each surcharge type with individual amounts
- **Formula:**
  ```
  Surcharge per Type = Base Wage × Hours × (Surcharge Rate / 100)
  Total Surcharge = Sum of all Surcharge Types
  Base Earnings = Base Wage × Total Hours
  Total Earnings = Base Earnings + Total Surcharge
  ```
- **Calculation Steps:**
  1. Parse all input values (base wage, hours, rates)
  2. Calculate total hours (sum of all hours)
  3. Calculate surcharge for each type: Base Wage × Hours × Rate%
  4. Sum all surcharges to get total surcharge
  5. Calculate base earnings: Base Wage × Total Hours
  6. Calculate total earnings: Base Earnings + Total Surcharge
  7. Format results for display
- **Example:**
  - Input:
    - Base Wage: 15.00 €/hour
    - Nachtstunden: 8 hours
    - Nachtzuschlag: 25%
  - Calculation:
    - Base Earnings: 15 × 8 = 120 €
    - Night Surcharge: 15 × 8 × 0.25 = 30 €
    - Total Earnings: 120 + 30 = 150 €
  - Output:
    - Total Surcharge: 30.00 €
    - Total Hours: 8 h
    - Total Earnings: 150.00 €
- **Edge Cases:**
  - Zero hours for some types → No surcharge for that type
  - Custom surcharge rates → Uses custom rates in calculation
  - Multiple surcharge types → All calculated and summed
  - Zero base wage → All surcharges zero
  - High surcharge rates → Calculated correctly up to 100%

### Constants and Thresholds

**2026 Values:**

- **Default Surcharge Rates:**
  - Nacht (Night): 25% (industry standard, steuerfrei bis 25% für 20:00-06:00 Uhr, bis 40% für 0:00-4:00 Uhr wenn Arbeit vor Mitternacht begonnen wurde)
  - Sonntag (Sunday): 50% (industry standard, steuerfrei bis 50%)
  - Feiertag (Holiday): 100% (industry standard, steuerfrei bis 125% für reguläre Feiertage, bis 150% für besondere Feiertage: 24.12 ab 14 Uhr, 25./26.12, 1. Mai)
  - Samstag (Saturday): 25% (industry standard, nicht automatisch steuerfrei - hängt vom Tarifvertrag ab)
- **Customizable:** All rates can be adjusted (0-100%)
- **Legal Minimums:** Varies by industry/tariff (not enforced in calculator)

**Previous Values (for reference):**

- Same as 2026 (rates typically stable)

### Validation Rules

- Base Wage: min=0, step=0.01, format=currency
- Hours: min=0, step=0.25 (quarter-hour increments)
- Surcharge Rates: min=0, max=100, step=1 (percentage)

### Edge Cases Handled

- Multiple surcharge types: All calculated and summed correctly
- Custom surcharge rates: Uses user-defined rates
- Zero hours for some types: No surcharge for that type, still calculates others
- High surcharge rates: Handles up to 100% correctly
- Zero base wage: All calculations result in zero
- Decimal hours: Supports quarter-hour increments (0.25)

### Dependencies

- **External Libraries:**
  - jsPDF (v2.5.1) - PDF generation
  - html2canvas (v1.4.1) - Canvas rendering for PDF
- **APIs:**
  - `/v2/api/collect-lead.php` - Email collection for exports (HubSpot integration)
- **Alpine.js:** Used for reactive UI (version from base includes)

## Functions & Methods

### Main Component Function

**Function:** `zuschlagsrechnerCalculator()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:18`
- **Purpose:** Main Alpine.js component for calculator functionality
- **Returns:** Alpine.js component object with data properties and methods
- **Dependencies:** Alpine.js framework
- **Side Effects:** Manages DOM state, localStorage, API calls

### Calculation Functions

**Function:** `calculateZuschlag()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:143`
- **Purpose:** Calculate all surcharges and total earnings
- **Parameters:** None (uses component state)
- **Returns:** void (sets component state)
- **Dependencies:** None (pure calculation)
- **Side Effects:** Updates `totalZuschlag`, `totalHours`, `totalEarnings`

**Function:** `calculateSurchargeAmount(baseWage, surchargeRate, hours)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:194`
- **Purpose:** Calculate surcharge amount for a single type
- **Parameters:**
  - `baseWage` (number): Base hourly wage
  - `surchargeRate` (number): Surcharge rate percentage
  - `hours` (number): Hours worked
- **Returns:** Number (surcharge amount)
- **Dependencies:** None (pure function)
- **Side Effects:** None

**Function:** `getCalculationData()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:198`
- **Purpose:** Get all calculation data for export
- **Parameters:** None (uses component state)
- **Returns:** Object with all calculation data
- **Dependencies:** `calculateSurchargeAmount()`
- **Side Effects:** None (pure function)

### Export Functions

**Function:** `exportPDF()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:129`
- **Purpose:** Trigger PDF export (with email gating)
- **Parameters:** None
- **Returns:** Promise (async function)
- **Dependencies:** Email collection, `exportPDFInternal()`
- **Side Effects:** Shows email modal if needed, triggers PDF generation

**Function:** `exportCSV()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:136`
- **Purpose:** Trigger CSV export (with email gating)
- **Parameters:** None
- **Returns:** Promise (async function)
- **Dependencies:** Email collection, `exportCSVInternal()`
- **Side Effects:** Shows email modal if needed, triggers CSV generation

**Function:** `exportPDFInternal()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:541`
- **Purpose:** Generate PDF file
- **Parameters:** None (uses component state)
- **Returns:** Promise (async function)
- **Dependencies:** jsPDF, html2canvas, `generatePDFHTML()`, `submitToHubSpot()`
- **Side Effects:** Creates PDF file, triggers download

**Function:** `exportCSVInternal()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:396`
- **Purpose:** Generate CSV file
- **Parameters:** None (uses component state)
- **Returns:** Promise (async function)
- **Dependencies:** `generateCSVContent()`, `submitToHubSpot()`
- **Side Effects:** Creates CSV file, triggers download

**Function:** `generatePDFHTML()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:439`
- **Purpose:** Generate HTML content for PDF
- **Parameters:** None (uses component state)
- **Returns:** String (HTML content)
- **Dependencies:** `getCalculationData()`, formatting functions
- **Side Effects:** None

**Function:** `generateCSVContent()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:319`
- **Purpose:** Generate CSV content
- **Parameters:** None (uses component state)
- **Returns:** String (CSV content)
- **Dependencies:** `getCalculationData()`, formatting functions
- **Side Effects:** None

**Function:** `submitEmailForExport()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:98`
- **Purpose:** Submit email for export and trigger export
- **Parameters:** None (uses component state)
- **Returns:** Promise (async function)
- **Dependencies:** HubSpot API, export functions
- **Side Effects:** Sends email to HubSpot, stores email in localStorage, triggers export

**Function:** `submitToHubSpot(email)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:235`
- **Purpose:** Submit calculation data to HubSpot API
- **Parameters:**
  - `email` (string): Email address
- **Returns:** Promise<boolean> (success status)
- **Dependencies:** HubSpot API (`/v2/api/collect-lead.php`)
- **Side Effects:** Sends data to HubSpot

### Email Management Functions

**Function:** `checkEmailCollection()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:48`
- **Purpose:** Check if email was previously collected
- **Parameters:** None
- **Returns:** void
- **Dependencies:** localStorage
- **Side Effects:** Updates `emailCollected` state

**Function:** `storeEmail(email)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:57`
- **Purpose:** Store email in localStorage
- **Parameters:**
  - `email` (string): Email address
- **Returns:** void
- **Dependencies:** localStorage
- **Side Effects:** Stores email, updates state

**Function:** `validateEmailInput(email)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:63`
- **Purpose:** Validate email format
- **Parameters:**
  - `email` (string): Email address
- **Returns:** void
- **Dependencies:** None
- **Side Effects:** Updates `exportEmailError` state

**Function:** `showExportEmailModal(format)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:76`
- **Purpose:** Show email collection modal
- **Parameters:**
  - `format` (string): Export format ('pdf' or 'csv')
- **Returns:** void
- **Dependencies:** None
- **Side Effects:** Shows modal, sets export format

**Function:** `hideExportEmailModal()`

- **Location:** `v2/js/tools-zuschlags-calculator.js:95`
- **Purpose:** Hide email collection modal
- **Parameters:** None
- **Returns:** void
- **Dependencies:** None
- **Side Effects:** Hides modal

### Utility Functions

**Function:** `formatCurrency(value)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:171`
- **Purpose:** Format number as currency (€)
- **Parameters:**
  - `value` (number): Value to format
- **Returns:** String (formatted currency)
- **Dependencies:** Intl.NumberFormat
- **Side Effects:** None

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

- **Location:** `v2/js/tools-zuschlags-calculator.js:179`
- **Purpose:** Format number with specified decimals
- **Parameters:**
  - `value` (number): Value to format
  - `decimals` (number): Number of decimals (default: 2)
- **Returns:** String (formatted number)
- **Dependencies:** Intl.NumberFormat
- **Side Effects:** None

**Function:** `formatDate(date)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:185`
- **Purpose:** Format date for display
- **Parameters:**
  - `date` (Date): Date object (default: current date)
- **Returns:** String (formatted date)
- **Dependencies:** Intl.DateTimeFormat
- **Side Effects:** None

**Function:** `showExportFeedback(message, type)`

- **Location:** `v2/js/tools-zuschlags-calculator.js:622`
- **Purpose:** Show export feedback notification
- **Parameters:**
  - `message` (string): Feedback message
  - `type` (string): Feedback type ('success', 'error', 'loading')
- **Returns:** void
- **Dependencies:** None
- **Side Effects:** Creates and displays notification element

## Formulas & Calculations

### Primary Formulas

**Surcharge per Type:**

```
Surcharge Amount = Base Wage × Hours × (Surcharge Rate / 100)
```

**Total Surcharge:**

```
Total Surcharge = Sum of all Surcharge Amounts
```

**Base Earnings:**

```
Base Earnings = Base Wage × Total Hours
```

**Total Earnings:**

```
Total Earnings = Base Earnings + Total Surcharge
```

### Legal Basis

- **Arbeitszeitgesetz (ArbZG):** German Working Time Act
  - Defines working time regulations
  - Does not mandate specific surcharge rates
- **Industry Tariffs:** Industry-specific surcharge rates
  - Common rates: Nacht 25%, Sonntag 50%, Feiertag 100%, Samstag 25%
  - Rates vary by industry and collective agreement
- **Collective Agreements:** Tariff-specific rates
  - Rates determined by collective bargaining agreements
  - Calculator allows custom rates to match specific agreements

### Step-by-Step Calculation Example

**Input:**

- Base Wage: 15.00 €/hour
- Nachtstunden: 8 hours
- Nachtzuschlag: 25%
- Sonntagstunden: 4 hours
- Sonntagszuschlag: 50%

**Calculation:**

1. Calculate total hours:

   - Total Hours = 8 + 4 = 12 hours

2. Calculate night surcharge:

   - Night Surcharge = 15 × 8 × (25 / 100) = 15 × 8 × 0.25 = 30.00 €

3. Calculate Sunday surcharge:

   - Sunday Surcharge = 15 × 4 × (50 / 100) = 15 × 4 × 0.50 = 30.00 €

4. Calculate total surcharge:

   - Total Surcharge = 30.00 + 30.00 = 60.00 €

5. Calculate base earnings:

   - Base Earnings = 15 × 12 = 180.00 €

6. Calculate total earnings:
   - Total Earnings = 180.00 + 60.00 = 240.00 €

**Output:**

- Total Surcharge: 60.00 €
- Total Hours: 12 h
- Total Earnings: 240.00 €

## Export Functionality

### PDF Export

**Trigger:** Click "PDF Export" button

**Email Gating:**

- First export requires email collection
- Email modal appears with validation
- Email sent to HubSpot API (`/v2/api/collect-lead.php`)
- Email stored in localStorage for future exports
- Subsequent exports skip email collection

**Data Included:**

- Header: Tool name, creation date
- Calculation Parameters: Base wage
- Surcharge Overview Table:
  - Columns: Zuschlagsart, Stunden, Zuschlagssatz, Zuschlag Betrag
  - Rows: Only surcharge types with hours > 0
  - Total row: Gesamt-Zuschlag
- Summary:
  - Grundlohn (nur Stunden)
  - Gesamte Auszahlung
- Footer: Ordio branding, tool URL

**Format:**

- Layout: A4 portrait
- Structure: Header, parameters, table, summary, footer
- Styling: Professional layout with colors and formatting
- Multi-page: Automatically paginated for long content
- File Name: `zuschlaege-berechnung-[date].pdf`

**Function:** `exportPDFInternal()`, `generatePDFHTML()`

### CSV Export

**Trigger:** Click "CSV Export" button

**Email Gating:** Same as PDF export

**Data Included:**

- Header: Tool name, creation date, URL
- Calculation Parameters: Base wage
- Surcharge Sections: Only surcharge types with hours > 0
  - Each section: Stunden, Zuschlagssatz, Zuschlag Betrag
- Summary:
  - Gesamt-Zuschlag
  - Gesamte Stunden
  - Grundlohn (nur Stunden)
  - Gesamte Auszahlung
- Footer: Tool name, URL

**Format:**

- Encoding: UTF-8 with BOM
- Delimiter: Semicolon (;)
- Line Endings: CRLF
- File Name: `zuschlaege-berechnung-[date].csv`

**Function:** `exportCSVInternal()`, `generateCSVContent()`

### Email Gating Process

**When Required:** First export attempt (PDF or CSV)

**Modal Display:**

- Appears as overlay modal
- Email input field with validation
- Submit button
- Error message display area
- Close button

**Email Validation:**

- Real-time validation as user types
- Format: Standard email format (user@domain.com)
- Error messages: Specific and helpful

**Storage:**

- Email stored in localStorage with key `zuschlagsrechner_export_email`
- Email address stored with key `zuschlagsrechner_export_email_address`
- Persists across sessions

**Pre-filling:**

- If email previously collected, modal skipped
- Email address pre-filled if available

**Error Handling:**

- Network errors: Specific error message
- Validation errors: Real-time feedback
- API errors: Graceful fallback (export still proceeds)

## Sharing Functionality

**Share URL Generation:** Not implemented

**Shareable Parameters:** Not implemented

**Share Restoration:** Not implemented

**Social Sharing:** Not implemented

## Results & Insights

### Result Display

**Primary Results:**

- Total Surcharge: Large display of total surcharge amount (€)
- Total Hours: Display of total hours worked
- Total Earnings: Large display of total earnings (€)

**Result Breakdowns:**

- Breakdown Table: Table showing each surcharge type
  - Columns: Zuschlagsart, Stunden, Zuschlagssatz, Zuschlag Betrag
  - Rows: Only surcharge types with hours > 0
  - Total row: Highlighted with total surcharge

**Result Formatting:**

- Currency: Formatted as € with 2 decimals (e.g., "30,00 €")
- Hours: Formatted with "h" suffix (e.g., "8 h")
- Percentages: Formatted with "%" suffix (e.g., "25%")

**Result Styling:**

- Large, bold numbers for totals
- Color-coded sections (blue, orange, red, green)
- Table with hover effects
- Total row highlighted

### Visualizations

**Charts/Graphs:** Not implemented

**Insights Provided:**

- Breakdown of surcharges by type
- Total earnings calculation
- Base wage vs. surcharge comparison

## Browser Testing Results

### Desktop Browsers

**Chrome (Latest):**

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

**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: Responsive design works well

**Android Chrome:**

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

**Mobile UI Differences:**

- Input fields adjust size for mobile
- Result cards stack vertically on small screens
- Export buttons remain accessible
- Table scrollable horizontally if needed

**Mobile Interactions:**

- Touch-friendly button sizes
- Keyboard input works correctly
- Export downloads work on mobile

### Responsive Design

**Desktop (>1024px):**

- Layout: Full-width form with side-by-side sections
- Table: Full width with all columns visible

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

- Layout: Responsive form layout
- Table: Scrollable horizontally if needed

**Mobile (<768px):**

- Layout: Single-column form
- Table: Horizontal scroll with touch gestures

**Breakpoints:**

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

### Accessibility

**Keyboard Navigation:**

- Tab navigation works through all interactive elements
- Enter key submits forms
- Escape key closes modals
- Focus indicators visible

**Screen Reader:**

- ARIA labels on interactive elements
- Result announcements after calculations
- Error announcements for validation
- Status messages announced

**ARIA Labels:**

- Input fields have labels
- Buttons have descriptive text
- Results have role="status"
- Errors have role="alert"

**Focus Management:**

- Focus moves to results after calculation
- Focus trapped in email modal
- Focus returns after modal close

**Color Contrast:**

- Meets WCAG AA standards
- Text readable on all backgrounds
- Error messages have sufficient contrast

**Text Readability:**

- Font sizes appropriate for all screen sizes
- Line height comfortable for reading
- Text not too small on mobile

### Performance

**Page Load Time:**

- Initial load: < 2 seconds
- Calculator ready: Immediate
- External libraries: Loaded asynchronously

**Calculation Speed:**

- Real-time calculations: < 10ms
- No noticeable lag

**Export Speed:**

- PDF generation: 1-3 seconds
- CSV generation: < 1 second
- Email submission: 1-2 seconds

**Large Data Handling:**

- Handles all input combinations efficiently
- No performance issues with multiple surcharge types

## Code Analysis

### Key Functions Location

- Main component: `v2/js/tools-zuschlags-calculator.js:18`
- Calculation function: `v2/js/tools-zuschlags-calculator.js:143`
- Export functions: `v2/js/tools-zuschlags-calculator.js:129-620`
- Email functions: `v2/js/tools-zuschlags-calculator.js:48-128`
- Utility functions: `v2/js/tools-zuschlags-calculator.js:171-193`

### Constants Location

- Default surcharge rates: `v2/js/tools-zuschlags-calculator.js:29-32`
- Default base wage: `v2/js/tools-zuschlags-calculator.js:24`

### Calculation Logic Flow

1. **Input Received:**

   - User enters base wage, hours, rates
   - Input handler triggered (`@input="calculateZuschlag()"`)

2. **Calculation:**

   - `calculateZuschlag()` function called
   - All surcharges calculated
   - Totals calculated

3. **Result Display:**
   - Results displayed in summary section
   - Breakdown table updated
   - Export buttons enabled

### State Management Flow

**Initialization:**

- Component initialized with Alpine.js
- Default values set
- localStorage checked for saved email

**Updates:**

- Input changes trigger reactive updates
- Calculations update result state
- Results update display automatically

**Dependencies:**

- Input state → Calculation → Result state
- Result state → Display → Export availability

### Event Handler Flow

**Input Events:**

- `@input`: Real-time calculation on input change
- Auto-calculation on every input change

**Export Triggers:**

- Button click → Email check → Modal or export
- Email submission → API call → Export generation

## Content Documentation

### Hero Section

- **H1:** "Zuschlagsrechner 2026: Nacht- & Feiertagszuschläge berechnen"
- **Description:** "Berechne Zuschläge für Nacht-, Sonn- und Feiertagsarbeit..."

### Educational Content Sections

1. **Surcharge Basics**

   - Night work surcharges explained
   - Sunday work surcharges explained
   - Holiday work surcharges explained
   - Saturday work surcharges explained

2. **Industry Rates**

   - Common surcharge rates by industry
   - Legal minimums (if applicable)
   - Industry-specific rates

3. **Calculation Examples**
   - Step-by-step examples
   - Common scenarios
   - Best practices

### FAQ Section

- **Total FAQs:** ~10 FAQs
- **FAQ Topics:**
  - Surcharge Calculation: 5 FAQs
  - Legal Requirements: 3 FAQs
  - Industry Rates: 2 FAQs

**Sample FAQs:**

1. "Wie berechne ich Nachtzuschläge?"
2. "Welche Zuschlagssätze gelten gesetzlich?"
3. "Sind Zuschläge steuerfrei?"
4. "Wie funktioniert die Berechnung bei mehreren Zuschlagsarten?"
5. "Kann ich eigene Zuschlagssätze eingeben?"

### Meta Tags

- **Title:** "Zuschlagsrechner 2026: Nacht- & Feiertagszuschläge berechnen - Ordio"
- **Description:** "Zuschlagsrechner 2026: Nacht-, Sonn- und Feiertagszuschläge berechnen. Steuerfreie Zuschläge, Excel-Formeln für Pflege & Gastronomie. Kostenlos & gesetzeskonform."
- **Keywords:** Zuschlagsrechner, zuschläge berechnen, Nachtzuschlag berechnen, Sonntagszuschlag berechnen, Feiertagszuschlag berechnen, nachtzuschlag ab wann, nachtzuschlag steuerfrei, zuschläge steuerfrei, brutto netto rechner mit zuschlägen, lohnberechnung zuschläge, arbeitszeit zuschläge berechnen

### Schema Markup

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

### Internal Linking

- Links to related tools (Arbeitszeitrechner, Stundenlohnrechner)
- Link count: ~3-5 internal links

## 2026 Update Requirements

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

**Constants/Values:**

- ✅ Surcharge rates unchanged (typically stable)
- ✅ Legal minimums unchanged (typically stable)
- ✅ Update JavaScript comments from "2025" to "2026" (if any)

**Content:**

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

**Priority:** 🟢 LOW (Year references only, rates typically stable)

### Throughout 2026 Updates

**Scheduled Updates:**

- None scheduled (rates typically stable)

### Monitoring Requirements

- **Arbeitszeitgesetz:** Check for regulation changes
- **Industry Tariffs:** Check for tariff updates
- **Frequency:** Annually (January) or when tariffs change
- **Source:** Official labor law sources, industry associations

## Testing

### Test Cases

**Normal Cases:**

- Test 1: 8h night work, 25% surcharge → Expected: 30.00 € surcharge, 150.00 € total
- Test 2: 4h Sunday work, 50% surcharge → Expected: 30.00 € surcharge, 90.00 € total
- Test 3: Multiple types (8h night + 4h Sunday) → Expected: 60.00 € surcharge, 240.00 € total
- Test 4: Custom rates (30% night) → Expected: Uses custom rate

**Edge Cases:**

- Edge case 1: Zero hours for some types → Expected: No surcharge for that type
- Edge case 2: Custom rates (150%) → Expected: Calculated correctly (if max allows)
- Edge case 3: Zero base wage → Expected: All surcharges zero
- Edge case 4: Decimal hours (8.5h) → Expected: Calculated correctly
- Edge case 5: All types with hours → Expected: All calculated and summed

**Export:**

- Test: PDF export → Expected: PDF file downloaded
- Test: CSV export → Expected: CSV file downloaded
- Test: Email gating → Expected: Email collected on first export

### Browser Testing

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

### Export Testing

- Excel: ❌ Not implemented
- PDF: ✅ Tested, working
- CSV: ✅ Tested, working

## Content Structure

### Hero Section

- **H1 Title:** To be documented
- **Meta Description:** Zuschlagsrechner 2026: Nacht-, Sonn- und Feiertagszuschläge berechnen. Steuerfreie Zuschläge, Excel-

### FAQs

- **Total FAQs:** 7
- Q: Welche Zuschläge sind steuerfrei?...
- Q: Ab wann gilt der Nachtzuschlag?...
- Q: Wie hoch ist der Sonntagszuschlag?...

## Maintenance Notes

### Known Issues

- None currently

### Future Improvements

- Add industry templates for common rates
- Add comparison mode (before/after)
- Add historical rate tracking
- Add Excel export functionality
- Add URL parameter sharing for results

### Related Tools

**Complementary Tools:**

- **[Arbeitszeitrechner](arbeitszeitrechner-documentation.md)** - Calculate working hours and compliance
  - Use together when: Need both working hours and surcharge calculations
  - Example workflow: Calculate working hours → Calculate surcharges → Total compensation

- **[Stundenlohnrechner](stundenlohnrechner-documentation.md)** - Calculate hourly wage
  - Use together when: Need to convert monthly salary to hourly rate for surcharge calculation
  - Example workflow: Calculate hourly rate → Calculate surcharges → Total earnings

- **[Brutto-Netto-Rechner](brutto-netto-rechner-documentation.md)** - Calculate net salary
  - Use together when: Need net salary after surcharges
  - Example workflow: Calculate surcharges → Calculate gross total → Calculate net salary

**Sequential Tools:**

- **[Kostenrechner](kostenrechner-documentation.md)** - Calculate labor costs
  - Use after: Calculating surcharges
  - Use before: Overall cost planning

- **[ROI-Rechner Schichtplanung](roi-rechner-schichtplanung-documentation.md)** - Calculate shift planning ROI
  - Use after: Calculating surcharge costs
  - Use before: Optimizing shift schedules

- **[Lohnabrechnung Feature](../../content/product-features/lohnabrechnung-documentation.md)** - Payroll processing
  - Use after: Calculating surcharges
  - Use before: Processing payroll

## References

### Official Sources

- **Arbeitszeitgesetz (ArbZG):** German Working Time Act
- **Industry Tariffs:** Tariff-specific rates
- **Collective Agreements:** Agreement-specific rates

### Documentation Files

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