From 43eb609b4ad517cb791cf5aa69e92d05c358d887 Mon Sep 17 00:00:00 2001 From: elpatron Date: Mon, 4 Aug 2025 11:39:51 +0200 Subject: [PATCH] Add multilingual README documentation - Rename README.md to README_de.md - Create README_en.md with English translation - Create new README.md with overview and language links --- README.md | 506 +------------------------------------------------- README_de.md | 511 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_en.md | 511 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1032 insertions(+), 496 deletions(-) create mode 100644 README_de.md create mode 100644 README_en.md diff --git a/README.md b/README.md index a83f0df..2dddbce 100644 --- a/README.md +++ b/README.md @@ -1,511 +1,25 @@ -# Elpatrons Datumsrechner + # Elpatron's Date Calculator -[![Test Coverage](https://img.shields.io/badge/test%20coverage-90%25-brightgreen)](https://github.com/elpatron/datecalc) -[![Lighthouse Performance](https://img.shields.io/badge/lighthouse%20performance-100%25-brightgreen)](https://date.elpatron.me) -[![Lighthouse Accessibility](https://img.shields.io/badge/lighthouse%20accessibility-100%25-brightgreen)](https://date.elpatron.me) -[![Lighthouse Best Practices](https://img.shields.io/badge/lighthouse%20best%20practices-100%25-brightgreen)](https://date.elpatron.me) -[![Lighthouse SEO](https://img.shields.io/badge/lighthouse%20seo-100%25-brightgreen)](https://date.elpatron.me) +A modern Python web application (Flask) that enables various date calculations through a clear, accessible web interface. Features include calculating days between dates, working days with state-specific holidays, calendar weeks, date arithmetic, and more. The application supports German and English languages, includes a REST API, and is designed with accessibility in mind. -Diese moderne Python-Webanwendung (Flask) ermöglicht verschiedene Datumsberechnungen über eine übersichtliche, barrierefreie Weboberfläche. +## Documentation -## Inhaltsverzeichnis +- **[English Documentation](README_en.md)** - Complete documentation in English +- **[Deutsche Dokumentation](README_de.md)** - Vollständige Dokumentation auf Deutsch -- [Demo](#demo) -- [Funktionen](#funktionen) -- [Installation (lokal)](#installation-lokal) -- [Starten der App](#starten-der-app) -- [Statistik-Dashboard & Passwortschutz](#statistik-dashboard-stats--passwortschutz) -- [Docker (empfohlen für Produktion)](#docker-empfohlen-für-produktion) - - [Log-Verzeichnis mounten](#log-verzeichnis-mounten-logs-auf-dem-host-speichern) - - [docker-compose Beispiel](#docker-compose-beispiel) -- [REST API](#rest-api) - - [Tage/Werktage zwischen zwei Daten](#1-tagewerktage-zwischen-zwei-daten) - - [Wochentag zu einem Datum](#2-wochentag-zu-einem-datum) - - [Kalenderwoche zu Datum](#3-kalenderwoche-zu-datum) - - [Start-/Enddatum einer Kalenderwoche](#4-start-enddatum-einer-kalenderwoche) - - [Datum plus/minus Tage, Wochen, Monate](#5-datum-plusminus-tage-wochen-monate) - - [Statistik](#6-statistik) - - [Monitoring & Healthcheck](#7-monitoring--healthcheck) -- [Progressive Web App (PWA)](#progressive-web-app-pwa) -- [Monitoring & Healthcheck](#monitoring--healthcheck) -- [Entwicklung & Hinweise](#entwicklung--hinweise) -- [Automatisierte Tests](#automatisierte-tests) -- [Hinweise](#hinweise) - - [Motivation](#motivation) - - [Vibe Coding](#vibe-coding) - - [Statistik-Erfassung, Logging](#statistik-erfassung-logging) - - [Barrierefreiheit (Accessibility)](#barrierefreiheit-accessibility) - - [Code Statistik](#code-statistik) -- [Lizenz](#lizenz) - -## Demo - -Datumsrechner Live: [https://date.elpatron.me](https://date.elpatron.me) - -[![App Screenshot](./assets/image-20250725095959116.png)](https://date.elpatron.me) - -**[Lighthouse](https://en.wikipedia.org/wiki/Lighthouse_(software))-Performance-Score:** - -Die Webanwendung erreicht hervorragende Performance-Werte in allen Kategorien (Performance, Accessibility, Best Practices, SEO). - -[Lighthouse-Ergebnis (PDF)](./lighthouse/lighthouse-score.pdf) - -## Funktionen - -- Anzahl der Tage zwischen zwei Daten -- Anzahl der Werktage zwischen zwei Daten (mit optionaler Berücksichtigung bundeslandspezifischer Feiertage) -- Anzeige des Wochentags eines Datums -- Datum plus/minus X Tage -- Datum plus/minus X Werktage -- Datum plus/minus X Wochen/Monate -- Kalenderwoche zu Datum -- Start-/Enddatum einer Kalenderwoche eines Jahres -- Integrierter Taschenrechner mit History und Sprachausgabe -- Mehrsprachige Unterstützung (Deutsch/Englisch) mit automatischer Browser-Spracherkennung -- Sprachausgabe für alle Ergebnisse (barrierefrei) -- Statistik-Dashboard mit Passwortschutz unter `/stats` - -## Bundesland-Feiertage - -Die Werktagsberechnung kann optional bundeslandspezifische Feiertage berücksichtigen. Dazu wird die kostenlose API von [feiertage-api.de](https://feiertage-api.de) verwendet. - -**Verfügbare Bundesländer:** - -- Baden-Württemberg (BW) -- Bayern (BY) -- Berlin (BE) -- Brandenburg (BB) -- Bremen (HB) -- Hamburg (HH) -- Hessen (HE) -- Mecklenburg-Vorpommern (MV) -- Niedersachsen (NI) -- Nordrhein-Westfalen (NW) -- Rheinland-Pfalz (RP) -- Saarland (SL) -- Sachsen (SN) -- Sachsen-Anhalt (ST) -- Schleswig-Holstein (SH) -- Thüringen (TH) - -Die Feiertage werden automatisch für den gewählten Zeitraum abgerufen und bei der Werktagsberechnung als arbeitsfreie Tage behandelt. Im Ergebnis werden zusätzlich die Anzahl der Wochenendtage und Feiertage angezeigt. - -## Mehrsprachige Unterstützung (i18n) - -Die Anwendung unterstützt Deutsch und Englisch mit folgenden Features: - -### Automatische Spracherkennung: - -- *Browser-Sprache*: Automatische Erkennung der Browser-Einstellung -- *URL-Parameter*: Sprachauswahl über `?lang=de` oder `?lang=en` -- *localStorage*: Persistente Sprachauswahl im Browser -- *Fallback*: Deutsch als Standardsprache - -### *Datenschutzfreundliche Implementierung:* - -- *Keine Cookies*: Sprachauswahl ohne Cookies -- *URL-Parameter*: Transparente Sprachauswahl in der URL -- *localStorage*: Lokale Speicherung im Browser -- *Teilbare URLs*: URLs mit Sprachauswahl können geteilt werden - -### *Barrierefreiheit:* - -- *Screenreader*: Vollständige Unterstützung -- *Tastatur-Navigation*: Vollständig bedienbar -- *ARIA-Attribute*: Korrekte Beschriftungen -- *Semantische HTML*: Korrekte Struktur -- *Taschenrechner*: Vollständig barrierefrei mit Tastatur-Bedienung und Sprachausgabe - -### *Technische Details:* - -- *Flask-Babel*: Professionelle i18n-Implementierung -- *Gettext*: Standard für Übersetzungen -- *Responsive Design*: Angepasst für alle Geräte -- *SEO-freundlich*: URLs sind indexierbar - -## Installation (lokal) - -1. Python 3.8+ installieren -2. Abhängigkeiten installieren: +## Quick Start ```bash pip install -r requirements.txt -``` - -## Starten der App - -```bash python app.py ``` -Die App ist dann unter http://localhost:5000 erreichbar. +Visit [https://date.elpatron.me](https://date.elpatron.me) for the live demo. -## Statistik-Dashboard (/stats) & Passwortschutz +## License -Das Dashboard ist mit einem statischen Passwort geschützt, das über die Umgebungsvariable `STATS_PASSWORD` gesetzt wird. - -![Statistics page](./assets/image-20250725100127004.png) - -Beispiel (PowerShell): - -```powershell -$env:STATS_PASSWORD = "meinSicheresPasswort" -python app.py -``` - -Für Docker: - -```powershell -$env:STATS_PASSWORD = "meinSicheresPasswort" -docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner -``` - -## Docker (empfohlen für Produktion) - -Die App läuft im Container mit dem WSGI-Server **Gunicorn**: - -```bash -docker build -t datumsrechner . -docker run -p 5000:5000 datumsrechner -``` - -- Gunicorn startet automatisch (siehe Dockerfile) -- Empfohlen für produktiven Einsatz - -### Log-Verzeichnis mounten (Logs auf dem Host speichern) - -Um die Logdateien außerhalb des Containers zu speichern, kannst du das log-Verzeichnis mounten: - -**PowerShell-Beispiel:** - -```powershell -docker run -e STATS_PASSWORD=deinPasswort -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner -``` - -### docker-compose Beispiel - -Erstelle eine Datei `docker-compose.yml`: - -```yaml -services: - datumsrechner: - build: . - ports: - - "5000:5000" - environment: - - STATS_PASSWORD=deinPasswort - volumes: - - ./log:/app/log -``` - -Starte mit: - -```bash -docker-compose up --build -``` - -## REST API - -Alle Datumsfunktionen stehen auch als REST-API zur Verfügung. Die API akzeptiert und liefert JSON. - -**Basis-URL:** `http://localhost:5000/api/` - -**Swagger Dokumentation:** [https://date.elpatron.me/api-docs](https://date.elpatron.me/api-docs) - -**Hinweis:** Die Nutzung der REST API wird im Statistik-Dashboard ausgewertet und als Diagramm angezeigt. - -### Endpunkte und Beispiele - -#### 1. Tage/Werktage zwischen zwei Daten - -**POST** `/api/tage_werktage` - -```json -{ - "start": "2024-06-01", - "end": "2024-06-10", - "werktage": true, - "bundesland": "BY" -} -``` - -**Mit curl:** - -```bash -curl -X POST http://localhost:5000/api/tage_werktage \ - -H "Content-Type: application/json" \ - -d '{"start": "2024-06-01", "end": "2024-06-10", "werktage": true, "bundesland": "BY"}' -``` - -**Antwort:** - -```json -{ "result": 7 } -``` - -**Hinweis:** Der Parameter `bundesland` ist optional und wird nur bei `"werktage": true` berücksichtigt. Verfügbare Bundesland-Kürzel siehe oben. - -#### 2. Wochentag zu einem Datum - -**POST** `/api/wochentag` - -```json -{ "datum": "2024-06-10" } -``` - -**Mit curl:** - -```bash -curl -X POST http://localhost:5000/api/wochentag \ - -H "Content-Type: application/json" \ - -d '{"datum": "2024-06-10"}' -``` - -**Antwort:** - -```json -{ "result": "Montag" } -``` - -#### 3. Kalenderwoche zu Datum - -**POST** `/api/kw_berechnen` - -```json -{ "datum": "2024-06-10" } -``` - -**Mit curl:** - -```bash -curl -X POST http://localhost:5000/api/kw_berechnen \ - -H "Content-Type: application/json" \ - -d '{"datum": "2024-06-10"}' -``` - -**Antwort:** - -```json -{ "result": "KW 24 (2024)", "kw": 24, "jahr": 2024 } -``` - -#### 4. Start-/Enddatum einer Kalenderwoche - -**POST** `/api/kw_datum` - -```json -{ "jahr": 2024, "kw": 24 } -``` - -**Mit curl:** - -```bash -curl -X POST http://localhost:5000/api/kw_datum \ - -H "Content-Type: application/json" \ - -d '{"jahr": 2024, "kw": 24}' -``` - -**Antwort:** - -```json -{ - "result": "10.06.2024 bis 16.06.2024", - "start": "2024-06-10", - "end": "2024-06-16" -} -``` - -#### 5. Datum plus/minus Tage, Wochen, Monate - -**POST** `/api/plusminus` - -```json -{ - "datum": "2024-06-10", - "anzahl": 5, - "einheit": "tage", - "richtung": "add", - "werktage": false -} -``` - -**Mit curl:** - -```bash -curl -X POST http://localhost:5000/api/plusminus \ - -H "Content-Type: application/json" \ - -d '{"datum": "2024-06-10", "anzahl": 5, "einheit": "tage", "richtung": "add", "werktage": false}' -``` - -**Antwort:** - -```json -{ "result": "2024-06-15" } -``` - -**Hinweis:** - -- `"einheit"`: `"tage"`, `"wochen"` oder `"monate"` -- `"richtung"`: `"add"` (plus) oder `"sub"` (minus) -- `"werktage"`: `true` für Werktage, sonst `false` (nur bei `"tage"` unterstützt) - -#### 6. Statistik - -**GET** `/api/stats` - -**Mit curl:** - -```bash -curl http://localhost:5000/api/stats -``` - -**Antwort:** - -```json -{ - "pageviews": 42, - "func_counts": { "plusminus": 10, "tage_werktage": 5 }, - "impressions_per_day": { "2024-06-10": 7 } -} -``` - -#### 7. Monitoring & Healthcheck - -**GET** `/api/monitor` - -**Mit curl:** - -```bash -curl http://localhost:5000/api/monitor -``` - -**Antwort:** - -```json -{ - "status": "ok", - "message": "App running", - "time": "2025-07-24T13:37:00.123456", - "uptime_seconds": 12345, - "pageviews_last_7_days": 42 -} -``` +This project is licensed under the [MIT License](LICENSE). --- -**Fehlerfälle** liefern immer einen HTTP-Statuscode 400 und ein JSON mit `"error"`-Feld, z.B.: - -```json -{ "error": "Ungültige Eingabe", "details": "..." } -``` - -## Progressive Web App (PWA) - -Elpatrons Datumsrechner ist als PWA installierbar (z.B. auf Android/iOS-Homescreen oder Desktop). Die App funktioniert offline für die Startseite und statische Ressourcen, die Datumsberechnung bleibt serverseitig. - -- Manifest und Service Worker sind integriert -- App-Icon und Theme-Color für Homescreen -- Installation über Browser-Menü ("Zum Startbildschirm hinzufügen") -- Taschenrechner funktioniert vollständig clientseitig (offline verfügbar) - -## Monitoring & Healthcheck - -Die App bietet einen Monitoring-Endpunkt unter `/monitor`, der Statusinformationen als JSON zurückgibt (z.B. für Uptime-Robot, Docker Healthcheck oder eigene Tools): - -- Status (ok) -- Aktuelle Serverzeit -- Uptime (Sekunden seit Start) -- Pageviews der letzten 7 Tage - -Beispiel-Aufruf: - -`GET https://date.elpatron.me/monitor` - -Antwort: - -```json -{ - "status": "ok", - "message": "App running", - "time": "2025-07-24T13:37:00.123456", - "uptime_seconds": 12345, - "pageviews_last_7_days": 42 -} -``` - -## Entwicklung & Hinweise - -- Die HTML-Templates liegen im Ordner `templates/` (Trennung von Logik und Darstellung) -- Das Projekt ist auf Codeberg gehostet: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc) -- Modernes, responsives Design mit Akkordeon und Icons - -## Automatisierte Tests - -Automatisierte Tests sind mit pytest möglich: - -```powershell -pip install -r requirements.txt -pytest test_app.py -``` - -Die Tests prüfen u.a. die Erreichbarkeit der App, die wichtigsten Funktionen und den Schutz vor XSS-Angriffen. - -## Hinweise - -### Motivation - -Finde mal eine Datumsrechner- Webapp, die nicht völlig Werbe- und Tracking verseucht ist! Da ich sowas häufiger mal brauche, hab ich mir eine eigene gemacht. - -### Vibe Coding - -Dieses Projekt wurde zu nahezu 100% mit Unterstützung künsticher Intelligenz (*[Vibe Coding](https://de.wikipedia.org/wiki/Vibe_Coding)*) erstellt. Das Grundgerüst war nach ca. 45 Minuten fertig gestellt, insgesamt hat die Entwicklung des Projekts ca. 12 Stunden Zeit beansprucht. - -### Statistik-Erfassung, Logging - -Es werden keine IP-Adressen oder sonstigen persönlichen Daten gespeichert, lediglich die Zahl der Aufrufe der Funktionen in einer kumulierten Darstellung. Die Logdatei enthält nur Einträge der letzten sieben Tage. - -### Barrierefreiheit (Accessibility) - -*Elpatrons Datumsrechner* ist barrierefrei gestaltet und erfüllt zentrale Anforderungen an Accessibility (a11y): - -- *Semantische HTML-Struktur:* Überschriften, Labels und Formularelemente sind korrekt ausgezeichnet und verknüpft. -- *ARIA-Attribute:* Accordion und Statusmeldungen sind mit ARIA-Attributen versehen, damit Screenreader die Struktur und Zustände erkennen. -- *Tastaturbedienbarkeit:* Alle interaktiven Elemente (Accordion, Buttons, Formulare) sind vollständig per Tastatur bedienbar (inkl. Fokus-Indikator und Pfeiltasten-Navigation im Accordion). -- *Fokus-Indikatoren:* Deutliche visuelle Hervorhebung des Fokus für alle Bedienelemente. -- *Farbkontraste:* Hohe Kontraste für Texte, Buttons und Ergebnisboxen, geprüft nach WCAG-Richtlinien. -- *Status- und Fehlermeldungen:* Ergebnisse und Fehler werden mit `aria-live` für Screenreader zugänglich gemacht. -- *Sprachausgabe:* Alle Ergebnisse können über 🔊-Buttons vorgelesen werden (Web Speech API, deutsche Sprache). -- *Taschenrechner:* Vollständig barrierefrei mit Tastatur-Bedienung, Sprachausgabe und History-Funktion. -- *Mobile Optimierung:* Zusätzliche Meta-Tags für bessere Bedienbarkeit auf mobilen Geräten und Unterstützung von Screenreadern. -- *SEO:* Das Thema Barrierefreiheit ist in den Meta-Tags für Suchmaschinen sichtbar. - -Damit ist die App für Menschen mit unterschiedlichen Einschränkungen (z.B. Sehbehinderung, motorische Einschränkungen) gut nutzbar und entspricht modernen Webstandards. - -### Code Statistik - -cloc|github.com/AlDanial/cloc v 2.06 T=0.23 s (109.5 files/s, 30735.0 lines/s) ---- | --- - -Language|files|blank|comment|code -:-------|-------:|-------:|-------:|-------: -HTML|8|159|8|2805 -Python|2|66|74|739 -JavaScript|2|95|88|580 -PO File|2|260|266|544 -Markdown|3|184|0|498 -JSON|3|0|0|243 -CSS|1|186|3|188 -SVG|2|0|0|14 -Dockerfile|1|5|6|8 -DOS Batch|1|0|0|1 ---------|--------|--------|--------|-------- -SUM:|25|955|445|5620 - -## Lizenz - -Dieses Projekt steht unter der [MIT-Lizenz](LICENSE). - ---- -(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron) - -**Version 1.4.12** - Integrierter Taschenrechner mit History und Sprachausgabe hinzugefügt +(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron) \ No newline at end of file diff --git a/README_de.md b/README_de.md new file mode 100644 index 0000000..a83f0df --- /dev/null +++ b/README_de.md @@ -0,0 +1,511 @@ +# Elpatrons Datumsrechner + +[![Test Coverage](https://img.shields.io/badge/test%20coverage-90%25-brightgreen)](https://github.com/elpatron/datecalc) +[![Lighthouse Performance](https://img.shields.io/badge/lighthouse%20performance-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse Accessibility](https://img.shields.io/badge/lighthouse%20accessibility-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse Best Practices](https://img.shields.io/badge/lighthouse%20best%20practices-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse SEO](https://img.shields.io/badge/lighthouse%20seo-100%25-brightgreen)](https://date.elpatron.me) + +Diese moderne Python-Webanwendung (Flask) ermöglicht verschiedene Datumsberechnungen über eine übersichtliche, barrierefreie Weboberfläche. + +## Inhaltsverzeichnis + +- [Demo](#demo) +- [Funktionen](#funktionen) +- [Installation (lokal)](#installation-lokal) +- [Starten der App](#starten-der-app) +- [Statistik-Dashboard & Passwortschutz](#statistik-dashboard-stats--passwortschutz) +- [Docker (empfohlen für Produktion)](#docker-empfohlen-für-produktion) + - [Log-Verzeichnis mounten](#log-verzeichnis-mounten-logs-auf-dem-host-speichern) + - [docker-compose Beispiel](#docker-compose-beispiel) +- [REST API](#rest-api) + - [Tage/Werktage zwischen zwei Daten](#1-tagewerktage-zwischen-zwei-daten) + - [Wochentag zu einem Datum](#2-wochentag-zu-einem-datum) + - [Kalenderwoche zu Datum](#3-kalenderwoche-zu-datum) + - [Start-/Enddatum einer Kalenderwoche](#4-start-enddatum-einer-kalenderwoche) + - [Datum plus/minus Tage, Wochen, Monate](#5-datum-plusminus-tage-wochen-monate) + - [Statistik](#6-statistik) + - [Monitoring & Healthcheck](#7-monitoring--healthcheck) +- [Progressive Web App (PWA)](#progressive-web-app-pwa) +- [Monitoring & Healthcheck](#monitoring--healthcheck) +- [Entwicklung & Hinweise](#entwicklung--hinweise) +- [Automatisierte Tests](#automatisierte-tests) +- [Hinweise](#hinweise) + - [Motivation](#motivation) + - [Vibe Coding](#vibe-coding) + - [Statistik-Erfassung, Logging](#statistik-erfassung-logging) + - [Barrierefreiheit (Accessibility)](#barrierefreiheit-accessibility) + - [Code Statistik](#code-statistik) +- [Lizenz](#lizenz) + +## Demo + +Datumsrechner Live: [https://date.elpatron.me](https://date.elpatron.me) + +[![App Screenshot](./assets/image-20250725095959116.png)](https://date.elpatron.me) + +**[Lighthouse](https://en.wikipedia.org/wiki/Lighthouse_(software))-Performance-Score:** + +Die Webanwendung erreicht hervorragende Performance-Werte in allen Kategorien (Performance, Accessibility, Best Practices, SEO). + +[Lighthouse-Ergebnis (PDF)](./lighthouse/lighthouse-score.pdf) + +## Funktionen + +- Anzahl der Tage zwischen zwei Daten +- Anzahl der Werktage zwischen zwei Daten (mit optionaler Berücksichtigung bundeslandspezifischer Feiertage) +- Anzeige des Wochentags eines Datums +- Datum plus/minus X Tage +- Datum plus/minus X Werktage +- Datum plus/minus X Wochen/Monate +- Kalenderwoche zu Datum +- Start-/Enddatum einer Kalenderwoche eines Jahres +- Integrierter Taschenrechner mit History und Sprachausgabe +- Mehrsprachige Unterstützung (Deutsch/Englisch) mit automatischer Browser-Spracherkennung +- Sprachausgabe für alle Ergebnisse (barrierefrei) +- Statistik-Dashboard mit Passwortschutz unter `/stats` + +## Bundesland-Feiertage + +Die Werktagsberechnung kann optional bundeslandspezifische Feiertage berücksichtigen. Dazu wird die kostenlose API von [feiertage-api.de](https://feiertage-api.de) verwendet. + +**Verfügbare Bundesländer:** + +- Baden-Württemberg (BW) +- Bayern (BY) +- Berlin (BE) +- Brandenburg (BB) +- Bremen (HB) +- Hamburg (HH) +- Hessen (HE) +- Mecklenburg-Vorpommern (MV) +- Niedersachsen (NI) +- Nordrhein-Westfalen (NW) +- Rheinland-Pfalz (RP) +- Saarland (SL) +- Sachsen (SN) +- Sachsen-Anhalt (ST) +- Schleswig-Holstein (SH) +- Thüringen (TH) + +Die Feiertage werden automatisch für den gewählten Zeitraum abgerufen und bei der Werktagsberechnung als arbeitsfreie Tage behandelt. Im Ergebnis werden zusätzlich die Anzahl der Wochenendtage und Feiertage angezeigt. + +## Mehrsprachige Unterstützung (i18n) + +Die Anwendung unterstützt Deutsch und Englisch mit folgenden Features: + +### Automatische Spracherkennung: + +- *Browser-Sprache*: Automatische Erkennung der Browser-Einstellung +- *URL-Parameter*: Sprachauswahl über `?lang=de` oder `?lang=en` +- *localStorage*: Persistente Sprachauswahl im Browser +- *Fallback*: Deutsch als Standardsprache + +### *Datenschutzfreundliche Implementierung:* + +- *Keine Cookies*: Sprachauswahl ohne Cookies +- *URL-Parameter*: Transparente Sprachauswahl in der URL +- *localStorage*: Lokale Speicherung im Browser +- *Teilbare URLs*: URLs mit Sprachauswahl können geteilt werden + +### *Barrierefreiheit:* + +- *Screenreader*: Vollständige Unterstützung +- *Tastatur-Navigation*: Vollständig bedienbar +- *ARIA-Attribute*: Korrekte Beschriftungen +- *Semantische HTML*: Korrekte Struktur +- *Taschenrechner*: Vollständig barrierefrei mit Tastatur-Bedienung und Sprachausgabe + +### *Technische Details:* + +- *Flask-Babel*: Professionelle i18n-Implementierung +- *Gettext*: Standard für Übersetzungen +- *Responsive Design*: Angepasst für alle Geräte +- *SEO-freundlich*: URLs sind indexierbar + +## Installation (lokal) + +1. Python 3.8+ installieren +2. Abhängigkeiten installieren: + +```bash +pip install -r requirements.txt +``` + +## Starten der App + +```bash +python app.py +``` + +Die App ist dann unter http://localhost:5000 erreichbar. + +## Statistik-Dashboard (/stats) & Passwortschutz + +Das Dashboard ist mit einem statischen Passwort geschützt, das über die Umgebungsvariable `STATS_PASSWORD` gesetzt wird. + +![Statistics page](./assets/image-20250725100127004.png) + +Beispiel (PowerShell): + +```powershell +$env:STATS_PASSWORD = "meinSicheresPasswort" +python app.py +``` + +Für Docker: + +```powershell +$env:STATS_PASSWORD = "meinSicheresPasswort" +docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner +``` + +## Docker (empfohlen für Produktion) + +Die App läuft im Container mit dem WSGI-Server **Gunicorn**: + +```bash +docker build -t datumsrechner . +docker run -p 5000:5000 datumsrechner +``` + +- Gunicorn startet automatisch (siehe Dockerfile) +- Empfohlen für produktiven Einsatz + +### Log-Verzeichnis mounten (Logs auf dem Host speichern) + +Um die Logdateien außerhalb des Containers zu speichern, kannst du das log-Verzeichnis mounten: + +**PowerShell-Beispiel:** + +```powershell +docker run -e STATS_PASSWORD=deinPasswort -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner +``` + +### docker-compose Beispiel + +Erstelle eine Datei `docker-compose.yml`: + +```yaml +services: + datumsrechner: + build: . + ports: + - "5000:5000" + environment: + - STATS_PASSWORD=deinPasswort + volumes: + - ./log:/app/log +``` + +Starte mit: + +```bash +docker-compose up --build +``` + +## REST API + +Alle Datumsfunktionen stehen auch als REST-API zur Verfügung. Die API akzeptiert und liefert JSON. + +**Basis-URL:** `http://localhost:5000/api/` + +**Swagger Dokumentation:** [https://date.elpatron.me/api-docs](https://date.elpatron.me/api-docs) + +**Hinweis:** Die Nutzung der REST API wird im Statistik-Dashboard ausgewertet und als Diagramm angezeigt. + +### Endpunkte und Beispiele + +#### 1. Tage/Werktage zwischen zwei Daten + +**POST** `/api/tage_werktage` + +```json +{ + "start": "2024-06-01", + "end": "2024-06-10", + "werktage": true, + "bundesland": "BY" +} +``` + +**Mit curl:** + +```bash +curl -X POST http://localhost:5000/api/tage_werktage \ + -H "Content-Type: application/json" \ + -d '{"start": "2024-06-01", "end": "2024-06-10", "werktage": true, "bundesland": "BY"}' +``` + +**Antwort:** + +```json +{ "result": 7 } +``` + +**Hinweis:** Der Parameter `bundesland` ist optional und wird nur bei `"werktage": true` berücksichtigt. Verfügbare Bundesland-Kürzel siehe oben. + +#### 2. Wochentag zu einem Datum + +**POST** `/api/wochentag` + +```json +{ "datum": "2024-06-10" } +``` + +**Mit curl:** + +```bash +curl -X POST http://localhost:5000/api/wochentag \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10"}' +``` + +**Antwort:** + +```json +{ "result": "Montag" } +``` + +#### 3. Kalenderwoche zu Datum + +**POST** `/api/kw_berechnen` + +```json +{ "datum": "2024-06-10" } +``` + +**Mit curl:** + +```bash +curl -X POST http://localhost:5000/api/kw_berechnen \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10"}' +``` + +**Antwort:** + +```json +{ "result": "KW 24 (2024)", "kw": 24, "jahr": 2024 } +``` + +#### 4. Start-/Enddatum einer Kalenderwoche + +**POST** `/api/kw_datum` + +```json +{ "jahr": 2024, "kw": 24 } +``` + +**Mit curl:** + +```bash +curl -X POST http://localhost:5000/api/kw_datum \ + -H "Content-Type: application/json" \ + -d '{"jahr": 2024, "kw": 24}' +``` + +**Antwort:** + +```json +{ + "result": "10.06.2024 bis 16.06.2024", + "start": "2024-06-10", + "end": "2024-06-16" +} +``` + +#### 5. Datum plus/minus Tage, Wochen, Monate + +**POST** `/api/plusminus` + +```json +{ + "datum": "2024-06-10", + "anzahl": 5, + "einheit": "tage", + "richtung": "add", + "werktage": false +} +``` + +**Mit curl:** + +```bash +curl -X POST http://localhost:5000/api/plusminus \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10", "anzahl": 5, "einheit": "tage", "richtung": "add", "werktage": false}' +``` + +**Antwort:** + +```json +{ "result": "2024-06-15" } +``` + +**Hinweis:** + +- `"einheit"`: `"tage"`, `"wochen"` oder `"monate"` +- `"richtung"`: `"add"` (plus) oder `"sub"` (minus) +- `"werktage"`: `true` für Werktage, sonst `false` (nur bei `"tage"` unterstützt) + +#### 6. Statistik + +**GET** `/api/stats` + +**Mit curl:** + +```bash +curl http://localhost:5000/api/stats +``` + +**Antwort:** + +```json +{ + "pageviews": 42, + "func_counts": { "plusminus": 10, "tage_werktage": 5 }, + "impressions_per_day": { "2024-06-10": 7 } +} +``` + +#### 7. Monitoring & Healthcheck + +**GET** `/api/monitor` + +**Mit curl:** + +```bash +curl http://localhost:5000/api/monitor +``` + +**Antwort:** + +```json +{ + "status": "ok", + "message": "App running", + "time": "2025-07-24T13:37:00.123456", + "uptime_seconds": 12345, + "pageviews_last_7_days": 42 +} +``` + +--- + +**Fehlerfälle** liefern immer einen HTTP-Statuscode 400 und ein JSON mit `"error"`-Feld, z.B.: + +```json +{ "error": "Ungültige Eingabe", "details": "..." } +``` + +## Progressive Web App (PWA) + +Elpatrons Datumsrechner ist als PWA installierbar (z.B. auf Android/iOS-Homescreen oder Desktop). Die App funktioniert offline für die Startseite und statische Ressourcen, die Datumsberechnung bleibt serverseitig. + +- Manifest und Service Worker sind integriert +- App-Icon und Theme-Color für Homescreen +- Installation über Browser-Menü ("Zum Startbildschirm hinzufügen") +- Taschenrechner funktioniert vollständig clientseitig (offline verfügbar) + +## Monitoring & Healthcheck + +Die App bietet einen Monitoring-Endpunkt unter `/monitor`, der Statusinformationen als JSON zurückgibt (z.B. für Uptime-Robot, Docker Healthcheck oder eigene Tools): + +- Status (ok) +- Aktuelle Serverzeit +- Uptime (Sekunden seit Start) +- Pageviews der letzten 7 Tage + +Beispiel-Aufruf: + +`GET https://date.elpatron.me/monitor` + +Antwort: + +```json +{ + "status": "ok", + "message": "App running", + "time": "2025-07-24T13:37:00.123456", + "uptime_seconds": 12345, + "pageviews_last_7_days": 42 +} +``` + +## Entwicklung & Hinweise + +- Die HTML-Templates liegen im Ordner `templates/` (Trennung von Logik und Darstellung) +- Das Projekt ist auf Codeberg gehostet: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc) +- Modernes, responsives Design mit Akkordeon und Icons + +## Automatisierte Tests + +Automatisierte Tests sind mit pytest möglich: + +```powershell +pip install -r requirements.txt +pytest test_app.py +``` + +Die Tests prüfen u.a. die Erreichbarkeit der App, die wichtigsten Funktionen und den Schutz vor XSS-Angriffen. + +## Hinweise + +### Motivation + +Finde mal eine Datumsrechner- Webapp, die nicht völlig Werbe- und Tracking verseucht ist! Da ich sowas häufiger mal brauche, hab ich mir eine eigene gemacht. + +### Vibe Coding + +Dieses Projekt wurde zu nahezu 100% mit Unterstützung künsticher Intelligenz (*[Vibe Coding](https://de.wikipedia.org/wiki/Vibe_Coding)*) erstellt. Das Grundgerüst war nach ca. 45 Minuten fertig gestellt, insgesamt hat die Entwicklung des Projekts ca. 12 Stunden Zeit beansprucht. + +### Statistik-Erfassung, Logging + +Es werden keine IP-Adressen oder sonstigen persönlichen Daten gespeichert, lediglich die Zahl der Aufrufe der Funktionen in einer kumulierten Darstellung. Die Logdatei enthält nur Einträge der letzten sieben Tage. + +### Barrierefreiheit (Accessibility) + +*Elpatrons Datumsrechner* ist barrierefrei gestaltet und erfüllt zentrale Anforderungen an Accessibility (a11y): + +- *Semantische HTML-Struktur:* Überschriften, Labels und Formularelemente sind korrekt ausgezeichnet und verknüpft. +- *ARIA-Attribute:* Accordion und Statusmeldungen sind mit ARIA-Attributen versehen, damit Screenreader die Struktur und Zustände erkennen. +- *Tastaturbedienbarkeit:* Alle interaktiven Elemente (Accordion, Buttons, Formulare) sind vollständig per Tastatur bedienbar (inkl. Fokus-Indikator und Pfeiltasten-Navigation im Accordion). +- *Fokus-Indikatoren:* Deutliche visuelle Hervorhebung des Fokus für alle Bedienelemente. +- *Farbkontraste:* Hohe Kontraste für Texte, Buttons und Ergebnisboxen, geprüft nach WCAG-Richtlinien. +- *Status- und Fehlermeldungen:* Ergebnisse und Fehler werden mit `aria-live` für Screenreader zugänglich gemacht. +- *Sprachausgabe:* Alle Ergebnisse können über 🔊-Buttons vorgelesen werden (Web Speech API, deutsche Sprache). +- *Taschenrechner:* Vollständig barrierefrei mit Tastatur-Bedienung, Sprachausgabe und History-Funktion. +- *Mobile Optimierung:* Zusätzliche Meta-Tags für bessere Bedienbarkeit auf mobilen Geräten und Unterstützung von Screenreadern. +- *SEO:* Das Thema Barrierefreiheit ist in den Meta-Tags für Suchmaschinen sichtbar. + +Damit ist die App für Menschen mit unterschiedlichen Einschränkungen (z.B. Sehbehinderung, motorische Einschränkungen) gut nutzbar und entspricht modernen Webstandards. + +### Code Statistik + +cloc|github.com/AlDanial/cloc v 2.06 T=0.23 s (109.5 files/s, 30735.0 lines/s) +--- | --- + +Language|files|blank|comment|code +:-------|-------:|-------:|-------:|-------: +HTML|8|159|8|2805 +Python|2|66|74|739 +JavaScript|2|95|88|580 +PO File|2|260|266|544 +Markdown|3|184|0|498 +JSON|3|0|0|243 +CSS|1|186|3|188 +SVG|2|0|0|14 +Dockerfile|1|5|6|8 +DOS Batch|1|0|0|1 +--------|--------|--------|--------|-------- +SUM:|25|955|445|5620 + +## Lizenz + +Dieses Projekt steht unter der [MIT-Lizenz](LICENSE). + +--- +(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron) + +**Version 1.4.12** - Integrierter Taschenrechner mit History und Sprachausgabe hinzugefügt diff --git a/README_en.md b/README_en.md new file mode 100644 index 0000000..4a6bab1 --- /dev/null +++ b/README_en.md @@ -0,0 +1,511 @@ +# Elpatron's Date Calculator + +[![Test Coverage](https://img.shields.io/badge/test%20coverage-90%25-brightgreen)](https://github.com/elpatron/datecalc) +[![Lighthouse Performance](https://img.shields.io/badge/lighthouse%20performance-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse Accessibility](https://img.shields.io/badge/lighthouse%20accessibility-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse Best Practices](https://img.shields.io/badge/lighthouse%20best%20practices-100%25-brightgreen)](https://date.elpatron.me) +[![Lighthouse SEO](https://img.shields.io/badge/lighthouse%20seo-100%25-brightgreen)](https://date.elpatron.me) + +This modern Python web application (Flask) enables various date calculations through a clear, accessible web interface. + +## Table of Contents + +- [Demo](#demo) +- [Features](#features) +- [Installation (local)](#installation-local) +- [Starting the App](#starting-the-app) +- [Statistics Dashboard & Password Protection](#statistics-dashboard--password-protection) +- [Docker (recommended for production)](#docker-recommended-for-production) + - [Mounting log directory](#mounting-log-directory-logs-stored-on-host) + - [docker-compose example](#docker-compose-example) +- [REST API](#rest-api) + - [Days/Working days between two dates](#1-daysworking-days-between-two-dates) + - [Weekday for a date](#2-weekday-for-a-date) + - [Calendar week for date](#3-calendar-week-for-date) + - [Start/End date of a calendar week](#4-startend-date-of-a-calendar-week) + - [Date plus/minus days, weeks, months](#5-date-plusminus-days-weeks-months) + - [Statistics](#6-statistics) + - [Monitoring & Healthcheck](#7-monitoring--healthcheck) +- [Progressive Web App (PWA)](#progressive-web-app-pwa) +- [Monitoring & Healthcheck](#monitoring--healthcheck) +- [Development & Notes](#development--notes) +- [Automated Tests](#automated-tests) +- [Notes](#notes) + - [Motivation](#motivation) + - [Vibe Coding](#vibe-coding) + - [Statistics collection, Logging](#statistics-collection-logging) + - [Accessibility](#accessibility) + - [Code Statistics](#code-statistics) +- [License](#license) + +## Demo + +Date Calculator Live: [https://date.elpatron.me](https://date.elpatron.me) + +[![App Screenshot](./assets/image-20250725095959116.png)](https://date.elpatron.me) + +**[Lighthouse](https://en.wikipedia.org/wiki/Lighthouse_(software)) Performance Score:** + +The web application achieves excellent performance values in all categories (Performance, Accessibility, Best Practices, SEO). + +[Lighthouse Result (PDF)](./lighthouse/lighthouse-score.pdf) + +## Features + +- Number of days between two dates +- Number of working days between two dates (with optional consideration of state-specific holidays) +- Display of the weekday of a date +- Date plus/minus X days +- Date plus/minus X working days +- Date plus/minus X weeks/months +- Calendar week for date +- Start/End date of a calendar week of a year +- Integrated calculator with history and speech output +- Multilingual support (German/English) with automatic browser language detection +- Speech output for all results (accessible) +- Statistics dashboard with password protection under `/stats` + +## State Holidays + +The working day calculation can optionally consider state-specific holidays. The free API from [feiertage-api.de](https://feiertage-api.de) is used for this purpose. + +**Available States:** + +- Baden-Württemberg (BW) +- Bavaria (BY) +- Berlin (BE) +- Brandenburg (BB) +- Bremen (HB) +- Hamburg (HH) +- Hesse (HE) +- Mecklenburg-Vorpommern (MV) +- Lower Saxony (NI) +- North Rhine-Westphalia (NW) +- Rhineland-Palatinate (RP) +- Saarland (SL) +- Saxony (SN) +- Saxony-Anhalt (ST) +- Schleswig-Holstein (SH) +- Thuringia (TH) + +Holidays are automatically retrieved for the selected time period and treated as non-working days in the working day calculation. The result also shows the number of weekend days and holidays. + +## Multilingual Support (i18n) + +The application supports German and English with the following features: + +### Automatic Language Detection: + +- *Browser Language*: Automatic detection of browser settings +- *URL Parameter*: Language selection via `?lang=de` or `?lang=en` +- *localStorage*: Persistent language selection in browser +- *Fallback*: German as default language + +### *Privacy-friendly Implementation:* + +- *No Cookies*: Language selection without cookies +- *URL Parameters*: Transparent language selection in URL +- *localStorage*: Local storage in browser +- *Shareable URLs*: URLs with language selection can be shared + +### *Accessibility:* + +- *Screen Reader*: Full support +- *Keyboard Navigation*: Fully operable +- *ARIA Attributes*: Correct labels +- *Semantic HTML*: Correct structure +- *Calculator*: Fully accessible with keyboard operation and speech output + +### *Technical Details:* + +- *Flask-Babel*: Professional i18n implementation +- *Gettext*: Standard for translations +- *Responsive Design*: Adapted for all devices +- *SEO-friendly*: URLs are indexable + +## Installation (local) + +1. Install Python 3.8+ +2. Install dependencies: + +```bash +pip install -r requirements.txt +``` + +## Starting the App + +```bash +python app.py +``` + +The app is then accessible at http://localhost:5000. + +## Statistics Dashboard (/stats) & Password Protection + +The dashboard is protected with a static password that is set via the environment variable `STATS_PASSWORD`. + +![Statistics page](./assets/image-20250725100127004.png) + +Example (PowerShell): + +```powershell +$env:STATS_PASSWORD = "mySecurePassword" +python app.py +``` + +For Docker: + +```powershell +$env:STATS_PASSWORD = "mySecurePassword" +docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner +``` + +## Docker (recommended for production) + +The app runs in a container with the **Gunicorn** WSGI server: + +```bash +docker build -t datumsrechner . +docker run -p 5000:5000 datumsrechner +``` + +- Gunicorn starts automatically (see Dockerfile) +- Recommended for production use + +### Mounting log directory (Logs stored on host) + +To store log files outside the container, you can mount the log directory: + +**PowerShell Example:** + +```powershell +docker run -e STATS_PASSWORD=yourPassword -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner +``` + +### docker-compose example + +Create a `docker-compose.yml` file: + +```yaml +services: + datumsrechner: + build: . + ports: + - "5000:5000" + environment: + - STATS_PASSWORD=yourPassword + volumes: + - ./log:/app/log +``` + +Start with: + +```bash +docker-compose up --build +``` + +## REST API + +All date functions are also available as a REST API. The API accepts and returns JSON. + +**Base URL:** `http://localhost:5000/api/` + +**Swagger Documentation:** [https://date.elpatron.me/api-docs](https://date.elpatron.me/api-docs) + +**Note:** The use of the REST API is evaluated in the statistics dashboard and displayed as a chart. + +### Endpoints and Examples + +#### 1. Days/Working days between two dates + +**POST** `/api/tage_werktage` + +```json +{ + "start": "2024-06-01", + "end": "2024-06-10", + "werktage": true, + "bundesland": "BY" +} +``` + +**With curl:** + +```bash +curl -X POST http://localhost:5000/api/tage_werktage \ + -H "Content-Type: application/json" \ + -d '{"start": "2024-06-01", "end": "2024-06-10", "werktage": true, "bundesland": "BY"}' +``` + +**Response:** + +```json +{ "result": 7 } +``` + +**Note:** The `bundesland` parameter is optional and is only considered when `"werktage": true`. Available state abbreviations see above. + +#### 2. Weekday for a date + +**POST** `/api/wochentag` + +```json +{ "datum": "2024-06-10" } +``` + +**With curl:** + +```bash +curl -X POST http://localhost:5000/api/wochentag \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10"}' +``` + +**Response:** + +```json +{ "result": "Monday" } +``` + +#### 3. Calendar week for date + +**POST** `/api/kw_berechnen` + +```json +{ "datum": "2024-06-10" } +``` + +**With curl:** + +```bash +curl -X POST http://localhost:5000/api/kw_berechnen \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10"}' +``` + +**Response:** + +```json +{ "result": "CW 24 (2024)", "kw": 24, "jahr": 2024 } +``` + +#### 4. Start/End date of a calendar week + +**POST** `/api/kw_datum` + +```json +{ "jahr": 2024, "kw": 24 } +``` + +**With curl:** + +```bash +curl -X POST http://localhost:5000/api/kw_datum \ + -H "Content-Type: application/json" \ + -d '{"jahr": 2024, "kw": 24}' +``` + +**Response:** + +```json +{ + "result": "10.06.2024 to 16.06.2024", + "start": "2024-06-10", + "end": "2024-06-16" +} +``` + +#### 5. Date plus/minus days, weeks, months + +**POST** `/api/plusminus` + +```json +{ + "datum": "2024-06-10", + "anzahl": 5, + "einheit": "tage", + "richtung": "add", + "werktage": false +} +``` + +**With curl:** + +```bash +curl -X POST http://localhost:5000/api/plusminus \ + -H "Content-Type: application/json" \ + -d '{"datum": "2024-06-10", "anzahl": 5, "einheit": "tage", "richtung": "add", "werktage": false}' +``` + +**Response:** + +```json +{ "result": "2024-06-15" } +``` + +**Note:** + +- `"einheit"`: `"tage"`, `"wochen"` or `"monate"` +- `"richtung"`: `"add"` (plus) or `"sub"` (minus) +- `"werktage"`: `true` for working days, otherwise `false` (only supported for `"tage"`) + +#### 6. Statistics + +**GET** `/api/stats` + +**With curl:** + +```bash +curl http://localhost:5000/api/stats +``` + +**Response:** + +```json +{ + "pageviews": 42, + "func_counts": { "plusminus": 10, "tage_werktage": 5 }, + "impressions_per_day": { "2024-06-10": 7 } +} +``` + +#### 7. Monitoring & Healthcheck + +**GET** `/api/monitor` + +**With curl:** + +```bash +curl http://localhost:5000/api/monitor +``` + +**Response:** + +```json +{ + "status": "ok", + "message": "App running", + "time": "2025-07-24T13:37:00.123456", + "uptime_seconds": 12345, + "pageviews_last_7_days": 42 +} +``` + +--- + +**Error cases** always return an HTTP status code 400 and JSON with an `"error"` field, e.g.: + +```json +{ "error": "Invalid input", "details": "..." } +``` + +## Progressive Web App (PWA) + +Elpatron's Date Calculator is installable as a PWA (e.g., on Android/iOS home screen or desktop). The app works offline for the homepage and static resources, date calculation remains server-side. + +- Manifest and Service Worker are integrated +- App icon and theme color for home screen +- Installation via browser menu ("Add to home screen") +- Calculator works completely client-side (available offline) + +## Monitoring & Healthcheck + +The app provides a monitoring endpoint at `/monitor` that returns status information as JSON (e.g., for Uptime Robot, Docker Healthcheck or own tools): + +- Status (ok) +- Current server time +- Uptime (seconds since start) +- Pageviews of the last 7 days + +Example call: + +`GET https://date.elpatron.me/monitor` + +Response: + +```json +{ + "status": "ok", + "message": "App running", + "time": "2025-07-24T13:37:00.123456", + "uptime_seconds": 12345, + "pageviews_last_7_days": 42 +} +``` + +## Development & Notes + +- HTML templates are in the `templates/` folder (separation of logic and presentation) +- The project is hosted on Codeberg: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc) +- Modern, responsive design with accordion and icons + +## Automated Tests + +Automated tests are possible with pytest: + +```powershell +pip install -r requirements.txt +pytest test_app.py +``` + +The tests check, among other things, the accessibility of the app, the most important functions, and protection against XSS attacks. + +## Notes + +### Motivation + +Try to find a date calculator web app that isn't completely riddled with ads and tracking! Since I need something like this more often, I made my own. + +### Vibe Coding + +This project was created almost 100% with the support of artificial intelligence (*[Vibe Coding](https://en.wikipedia.org/wiki/Vibe_Coding)*). The basic framework was completed after about 45 minutes, and the total development of the project took about 12 hours. + +### Statistics collection, Logging + +No IP addresses or other personal data are stored, only the number of function calls in a cumulative representation. The log file only contains entries from the last seven days. + +### Accessibility + +*Elpatron's Date Calculator* is designed to be accessible and meets central accessibility (a11y) requirements: + +- *Semantic HTML Structure:* Headings, labels, and form elements are correctly marked and linked. +- *ARIA Attributes:* Accordion and status messages are equipped with ARIA attributes so that screen readers can recognize the structure and states. +- *Keyboard Operability:* All interactive elements (accordion, buttons, forms) are fully operable by keyboard (including focus indicator and arrow key navigation in accordion). +- *Focus Indicators:* Clear visual highlighting of focus for all control elements. +- *Color Contrasts:* High contrasts for texts, buttons, and result boxes, tested according to WCAG guidelines. +- *Status and Error Messages:* Results and errors are made accessible to screen readers with `aria-live`. +- *Speech Output:* All results can be read aloud via 🔊 buttons (Web Speech API, German language). +- *Calculator:* Fully accessible with keyboard operation, speech output, and history function. +- *Mobile Optimization:* Additional meta tags for better usability on mobile devices and support for screen readers. +- *SEO:* The accessibility topic is visible in meta tags for search engines. + +This makes the app well usable for people with different disabilities (e.g., visual impairment, motor limitations) and meets modern web standards. + +### Code Statistics + +cloc|github.com/AlDanial/cloc v 2.06 T=0.23 s (109.5 files/s, 30735.0 lines/s) +--- | --- + +Language|files|blank|comment|code +:-------|-------:|-------:|-------:|-------: +HTML|8|159|8|2805 +Python|2|66|74|739 +JavaScript|2|95|88|580 +PO File|2|260|266|544 +Markdown|3|184|0|498 +JSON|3|0|0|243 +CSS|1|186|3|188 +SVG|2|0|0|14 +Dockerfile|1|5|6|8 +DOS Batch|1|0|0|1 +--------|--------|--------|--------|-------- +SUM:|25|955|445|5620 + +## License + +This project is licensed under the [MIT License](LICENSE). + +--- +(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron) + +**Version 1.4.12** - Integrated calculator with history and speech output added \ No newline at end of file