update

.paul/phases/04-polish-testing/04-01-SUMMARY.md

@@ -0,0 +1,126 @@
+---
+phase: 04-polish-testing
+plan: 01
+subsystem: ui, api
+tags: [a11y, animations, error-handling, focus-trap, aria, css-transitions]
+
+requires:
+  - phase: 03-form-submit-booking
+    provides: Complete booking flow end-to-end (customer → pricing → booking → confirm → success)
+provides:
+  - Token retry on 401/403 with auto-recovery
+  - AbortController timeout 15s with Polish error messages
+  - Network error detection and user-friendly messaging
+  - Extended reject reason translations (6 codes)
+  - Animated step transitions (form ↔ summary ↔ success)
+  - Modal open/close animations (fade + scale)
+  - ARIA dialog with focus trap and focus management
+  - aria-live announcements for screen readers
+  - CSS bug fix (orphaned media query styles)
+affects: [05-admin-panel]
+
+tech-stack:
+  added: []
+  patterns: [AbortController timeout, CSS class-based step transitions, focus trap pattern, aria-live announcements]
+
+key-files:
+  modified:
+    - wp-content/plugins/carei-reservation/assets/js/carei-reservation.js
+    - wp-content/plugins/carei-reservation/assets/css/carei-reservation.css
+    - wp-content/plugins/carei-reservation/includes/class-elementor-widget.php
+
+key-decisions:
+  - "Inline style.display for step visibility instead of CSS-only classes — HTML inline display:none overrides classes"
+  - "Focus trap via keydown listener on overlay, filtering visible focusable elements"
+  - "aria-live region appended to modal overlay for scoped announcements"
+
+patterns-established:
+  - "transitionStep(outEl, inEl, callback) pattern for animated view switching"
+  - "hideStep/showStep helpers using style.display for reliable visibility control"
+  - "announce() via aria-live polite region with 100ms delay for screen reader pickup"
+
+duration: ~45min
+started: 2026-03-25T14:00:00Z
+completed: 2026-03-25T14:45:00Z
+---
+
+# Phase 4 Plan 01: Polish & Integration Testing Summary
+
+**Edge cases (token retry, timeout, network errors), animated step transitions, ARIA dialog with focus trap — formularz gotowy produkcyjnie.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~45min |
+| Tasks | 3 auto + 1 checkpoint |
+| Files modified | 3 |
+| Deviations | 1 (auto-fixed) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Wygasły token JWT | Pass | 401/403 → auto-retry 1x, user nie widzi błędu |
+| AC-2: Brak dostępności pojazdu | Pass | CAR_NOT_FOUND → czytelny komunikat PL z sugestią |
+| AC-3: Timeouty i błędy sieciowe | Pass | AbortController 15s, TypeError → retry → komunikat PL |
+| AC-4: Animacje przejść | Pass | fade+translate form↔summary↔success, modal scale |
+| AC-5: Accessibility | Pass | role=dialog, aria-modal, focus trap, focus management, aria-live |
+| AC-6: Fix CSS orphaned styles | Pass | Styles przeniesione do @media (max-width: 768px) |
+
+## Accomplishments
+
+- Pełny error recovery: token retry, timeout 15s, network errors — formularz nigdy nie blokuje się na stałe
+- Animowane przejścia między krokami: smooth fade+translate (250ms) z callback focus management
+- Focus trap w modalu: Tab nie wychodzi poza modal, Escape zamyka, focus wraca na trigger
+- aria-live announcements: "Ładowanie podsumowania...", "Rezerwacja potwierdzona", błędy API
+
+## Files Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `assets/js/carei-reservation.js` | Modified | Token retry, timeout, network errors, animacje, focus trap, aria-live |
+| `assets/css/carei-reservation.css` | Modified | Modal animations, step transitions, sr-only class, CSS bug fix |
+| `includes/class-elementor-widget.php` | Modified | ARIA: role=dialog, aria-modal, aria-labelledby, aria-busy, tabindex=-1 |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| style.display zamiast CSS class dla visibility | HTML inline display:none nadpisuje klasy CSS | hideStep/showStep helpers operują na style.display |
+| Focus na segment select po open | Pierwszy interaktywny element, najlogiczniejszy start | 350ms delay po animacji otwarcia |
+| aria-live region w overlay | Scoped do modalu, nie zanieczyszcza strony | announce() z 100ms delay dla pickup przez screen readery |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 1 | Konieczna zmiana podejścia do visibility |
+
+**Total impact:** Essential fix, no scope creep
+
+### Auto-fixed Issues
+
+**1. Inline display:none vs CSS class conflict**
+- **Found during:** Checkpoint (user reported form title instead of summary)
+- **Issue:** HTML elements miały `style="display:none;"` inline, a transitionStep używał klas CSS (`carei-step--hidden`) — inline style nadpisywał klasę
+- **Fix:** Zmieniono na hideStep()/showStep() operujące na `el.style.display`
+- **Verification:** User potwierdził poprawne działanie po fix
+
+## Next Phase Readiness
+
+**Ready:**
+- Formularz produkcyjnie gotowy: error handling, animacje, a11y
+- Booking flow end-to-end przetestowany na carei.pagedev.pl
+
+**Concerns:**
+- Penalty items filtrowane po kodzie (BRAK/BRUD/KARA) — może nie pokryć przyszłych kodów
+- Brak email notification po rezerwacji (zależy od konfiguracji Softra)
+
+**Blockers:** None
+
+---
+*Phase: 04-polish-testing, Plan: 01*
+*Completed: 2026-03-25*