# Canonical Gated Export Modal Spec

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

Single reference for the export email modal used on tools pages. All tools that gate Excel/PDF/CSV export behind email must follow this spec for consistency.

## Structure

- **Container:** `fixed inset-0 z-50 overflow-y-auto bg-black bg-opacity-50 flex items-center justify-center p-4`
- **Backdrop:** Close on click (e.g. `@click.away="showEmailModal = false"`). Do not close when clicking the card.
- **Card:** `bg-white rounded-xl shadow-2xl max-w-md w-full p-6 relative` with `@click.stop` so clicks inside do not close.
- **Close button:** Top-right, X icon, `aria-label="Schließen"`.
- **Icon circle:** Above title, `w-12 h-12 bg-ordio-blue bg-opacity-10 rounded-full` (or `bg-blue-100`) with document/download SVG.
- **Escape key:** `@keydown.escape.window="showEmailModal = false"` (or equivalent) to close.

## Accessibility

- `role="dialog"`
- `aria-modal="true"` (optional but recommended)
- `aria-labelledby` pointing to the title element id
- `aria-describedby` pointing to the description element id
- Close button `aria-label="Schließen"`

## Fields (required)

1. **Name** – Single text field.
   - Placeholder: "Dein Name"
   - Required
   - `autocomplete="name"`
   - State: e.g. `exportNameAddress` or `nameAddress`

2. **Email** – Email field.
   - Placeholder: "deine-email@beispiel.de"
   - Required
   - State: e.g. `exportEmailAddress`
   - Validate format before submit; show inline error from API when present.

## Copy template

- **Title:** `[Format] herunterladen` (e.g. "PDF herunterladen", "Excel herunterladen", "CSV herunterladen"). Must be dynamic per export type.
- **Description:** `E-Mail-Adresse eingeben für [Format]-Download` (dynamic same as title).
- **CTA button:** `[Format] herunterladen` (same as title). Loading state: "Wird vorbereitet..." or "Wird verarbeitet...".
- **Footer:** `Kostenlos • Keine Spam • Jederzeit abbestellbar` (or a short tool-specific line if needed).

## API contract

- **Endpoint:** `POST /v2/api/collect-lead.php`
- **Body (JSON):** `name`, `email`, `tool_name` (required). Optional: `tool_data`, `utm_*`, `hubspotutk`, `page_url`, `referrer` (see existing tools).
- **Success:** `response.ok && responseJson && responseJson.success === true`. Only then set `emailCollected`, close modal, and run the pending export (Excel/PDF/CSV).
- **Failure:** Set `emailError` (or equivalent) from `responseJson.message` or `responseJson.validation_errors[0].message` or `responseJson.errors[0].message`; fallback: "Es gab einen Fehler beim Senden. Bitte versuchen Sie es erneut."

## Behavior

- **Pending format:** When user clicks Excel/PDF/CSV, set `pendingExportFormat` (or equivalent) to the chosen format and show the modal. Title, description, and CTA must reflect that format.
- **After submit:** Call collect-lead; on success store name/email in localStorage (see key convention below), set emailCollected, close modal, run the export function for `pendingExportFormat`, then clear pending.
- **Repeat visit:** If email (and optionally name) already in localStorage for this tool, either skip modal and export directly or prefill and allow submit again (product decision per tool).

## localStorage key convention

- Prefer one or two keys per tool, e.g. `{tool_slug}_export_email` and `{tool_slug}_export_name` or a single JSON key.
- Document in this spec or in EMAIL_MODAL_UTILS.md. Examples: `urlaubsanspruch_email_collected`, `einkommensteuer_export_email`, `arbeitstage_export_email`, `stundenlohn_email_collected`, `stundenlohn_email_address`, `stundenlohn_name_address`.
- **Pendlerpauschale-Rechner:** `pendlerpauschale_export_email`, `pendlerpauschale_export_name`, `pendlerpauschale_export_submitted`.
- **Kurzarbeitergeld-Rechner:** `kurzarbeitergeld_export_email`, `kurzarbeitergeld_export_name`, `kurzarbeitergeld_export_submitted`. One-time read fallback to legacy `ordio_tool_email` so bestehende Nutzer:innen nicht erneut durchs Gate müssen.

## References

- [.cursor/rules/tools-pages-patterns-gated.mdc](../../.cursor/rules/tools-pages-patterns-gated.mdc) – Gated content and Alpine pattern
- [.cursor/rules/tools-pages-patterns-export.mdc](../../.cursor/rules/tools-pages-patterns-export.mdc) – Export and email gating
- [GATED_FORMS_TROUBLESHOOTING.md](./GATED_FORMS_TROUBLESHOOTING.md) – Debugging collect-lead and validation
- [docs/systems/shared-components/EMAIL_MODAL_UTILS.md](../../systems/shared-components/EMAIL_MODAL_UTILS.md) – Shared utilities and key format