recipe-mockup/VIEWS_AND_SCENARIOS.md

Widoki i scenariusze — Aplikacja Kuchenna

Cel dokumentu: Opis wszystkich widoków aplikacji z obecnym stanem, scenariusze użytkownika i znane problemy. Odniesienie dla dalszego rozwoju.

Kontekst projektu: To jest prototyp / mockup — celem jest wypracowanie UX, logiki widoków i przepływów użytkownika. Finalna aplikacja będzie pisana w innym języku z backendem. Wartość tego prototypu to przede wszystkim: struktura widoków, scenariusze, model danych i decyzje UX — nie kod sam w sobie.

---

1. Profil użytkownika

Cecha	Opis
Liczba osób	1 (gotuje dla siebie)
Planowanie	Elastyczne, 1–7 dni do przodu
Posiłki	3 główne (śniadanie, obiad, kolacja) + dodatkowe przy treningu
Powtarzalność	Duża (zwłaszcza śniadania) — kopiowanie dnia kluczowe
Styl gotowania	Hybrydowy: trochę meal-prep, trochę na bieżąco
Zakupy	Mieszane: duże zakupy + uzupełnienia w tygodniu
Cel dietetyczny	Utrzymanie wagi, śledzenie per posiłek
Pomijanie posiłków	Jawne "pomijam" (jedzenie na mieście)
Przepisy	Na razie katalog wbudowany (9 przepisów), bez edytora

Kluczowe pain-pointy (zgłoszone)

1. Brak możliwości pominięcia slotu w planerze
2. Brak "Dodaj do planera" z widoku przepisu
3. Ilości na liście zakupów nie do edycji
4. Brak kalorii per slot w widoku dnia
5. Za dużo kliknięć w kluczowych flow

---

2. Przegląd widoków

2.1 Przepisy (RecipeList)

Lokalizacja: js/views/RecipeList.js

Siatka 2-kolumnowa kart przepisów generowana dynamicznie z RECIPES. Każda karta zawiera miniaturę (placeholder), tytuł, czas przygotowania, kalorie. Kliknięcie otwiera detal.

Elementy:

• Wyszukiwarka (real-time, po tytule i tagach)
• Przycisk filtrów (overlay)
• Siatka kart

Stan: Kompletny.

---

2.2 Filtry (Filter)

Lokalizacja: js/views/Filter.js

Overlay z chipami pór posiłku, tagami dietetycznymi i suwakiem czasu. Dynamicznie generowane z MEAL_SLOTS i tagów z RECIPES.

Elementy:

• Chipy: pory posiłku (z MEAL_SLOTS)
• Chipy: tagi dietetyczne (zbierane z RECIPES)
• Suwak: maksymalny czas przygotowania
• Przycisk "Wyczyść" + "Pokaż X wyników"

Stan: Kompletny.

---

2.3 Szczegóły przepisu (RecipeDetail)

Lokalizacja: js/views/RecipeDetail.js

Full-screen overlay z detalami przepisu. Trzy zakładki: Składniki, Kroki, Wartości.

Elementy:

• Hero (placeholder) + strzałka powrotu + "Do planera" (nowe)
• Tytuł, tagi, czas, kcal
• Selektor porcji (±) z przeliczaniem
• Zakładka Składniki: lista z checkboxami + badge stanu spiżarni + "Dodaj do listy zakupów"
• Zakładka Kroki: numerowane kroki
• Zakładka Wartości: kcal/białko/tłuszcze/węglowodany × porcje
• Bottom sheet "Dodaj do planera": wybór dnia (7 dni) + slotu → zapis do planStore

Stan: Kompletny.

---

2.4 Planer posiłków (MealPlanner)

Lokalizacja: js/views/MealPlanner.js

Kalendarz (tydzień/miesiąc) + plan dnia z slotami posiłków.

Elementy kalendarza:

• Widok tygodnia ↔ miesiąca (swipe góra/dół)
• Nawigacja: ←/→ + "Dziś"
• Kropki pod dniem = zaplanowane posiłki

Elementy planu dnia:

• Nagłówek dnia + "Kopiuj dzień" (nowe)
• Karta podsumowania kalorycznego (kcal + makro, rozwijalne szczegóły)
• "Składniki na ten dzień" (badge z liczbą braków)
• Sloty posiłków (5 slotów z MEAL_SLOTS):
  • Kcal per slot w nagłówku (nowe)
  • Karty przepisów z porcjami, kcal, czasem, przyciskiem usuwania
  • Kliknięcie nazwy przepisu → RecipeDetail
  • "Dodaj przepis" / "Dodaj kolejny"
  • "Pomijam" przy pustym slocie (nowe) → slot przygaszony z "Cofnij"

Bottom sheety:

1. Picker przepisów: wyszukiwarka + "Ostatnio używane" + lista filtrowana do allowedSlots
2. Składniki i spiżarnia: porównanie potrzeb vs zapasy + prognoza tygodnia + "Dodaj braki"
3. Kopiuj plan dnia: lista 13 dni (3 wstecz, 10 do przodu) → kopiuje cały dzień

Stan: Kompletny.

---

2.5 Spiżarnia (Pantry)

Lokalizacja: js/views/Pantry.js

Przeglądanie i edycja stanów magazynowych składników.

Elementy:

• Wyszukiwarka
• Chipy filtrów kategorii
• Toggle "Tylko na stanie"
• Siatka chipów składników (kolorowana wg stanu)
• Bottom sheet edycji: ±, input, wartości odżywcze, "Dodaj na listę zakupów"

Stan: Kompletny.

---

2.6 Zakupy (Shopping)

Lokalizacja: js/views/Shopping.js

Zarządzanie listami zakupów.

Elementy:

• Selektor aktywnej listy
• Przycisk "Nowa lista"
• Pasek akcji listy kuchennej (widoczny gdy są zaznaczone pozycje):
  • "Kupione → spiżarnia" (z potwierdzeniem — nowe)
  • "Wyczyść kupione"
• Lista kuchenna: pogrupowana po kategorii, checkbox, edycja ilości (klik → prompt, nowe)
• Lista freeform: tekst + notatka, checkbox

Stan: Kompletny.

---

3. Przepływy między widokami

Przepisy ──[klik kartę]──→ Szczegóły przepisu
                              ├──[Dodaj do listy zakupów]──→ Zakupy (lista kuchenna)
                              └──[Do planera]──→ Planer (wybór dnia + slotu)

Planer ──[klik przepis w slocie]──→ Szczegóły przepisu
       ──[Składniki na ten dzień]──→ Sheet: porównanie z spiżarnią
       ──[Dodaj braki do listy]──→ Zakupy (lista kuchenna)
       ──[Kopiuj dzień]──→ Sheet: wybór dnia docelowego

Spiżarnia ──[Dodaj na listę zakupów]──→ Zakupy

Zakupy ──[Kupione → spiżarnia]──→ Spiżarnia (stany zaktualizowane)

---

4. Scenariusze użytkownika

Scenariusz 1: Przeglądanie przepisów

Cel: Użytkownik otwiera apkę, chce zobaczyć co jest dostępne.

1. Otwiera aplikację → widzi zakładkę Przepisy z siatką 9 kart
2. Przewija listę, czyta opisy i kalorie na kartach
3. Klika kartę "Makaron z pomidorami i bazylią"
4. Widzi detal: składniki, kroki, wartości odżywcze
5. Zmienia liczbę porcji z 1 na 3 → składniki i kcal się przeliczają
6. Przełącza zakładkę na "Kroki" → widzi kroki
7. Przełącza na "Wartości" → widzi makroskładniki ×3
8. Wraca strzałką ← do listy

Znane problemy:

• Brak zdjęć (szare placeholdery) — OK dla prototypu
• Po powrocie z detalu filtr/szukajka powinny się utrzymać (utrzymują się)

---

Scenariusz 2: Szukanie przepisu na kolację

Cel: Użytkownik szuka czegoś konkretnego.

1. Wpisuje "łosoś" → lista filtruje się do 1 karty
2. Kasuje tekst → wracają wszystkie
3. Klika ikonę filtrów
4. Zaznacza "Kolacja" → lista się zawęża
5. Dodatkowo zaznacza tag "Wysokobiałkowe"
6. Ustawia suwak na max 25 min
7. Klika "Pokaż X wyników" → wraca do przefiltrowanej listy
8. Wybiera przepis i otwiera detal

Znane problemy:

• Brak wizualnego wskaźnika aktywnych filtrów na ikonce (badge/kropka)
• Po zamknięciu filtrów ← (zamiast "Pokaż") — zachowanie może być nieintuicyjne

---

Scenariusz 3: Planowanie posiłków na tydzień

Cel: Użytkownik układa menu na kilka dni.

1. Przechodzi na zakładkę Planer
2. Widzi dzisiejszy dzień z demo-danymi
3. Klika na przepis w slocie → otwiera się detal
4. Wraca ← do planera
5. Klika następny dzień w kalendarzu
6. Widzi puste sloty, klika "Dodaj przepis" przy Śniadaniu
7. Picker: wpisuje fragment nazwy, widzi "Ostatnio używane"
8. Wybiera przepis → pojawia się w slocie z kcal w nagłówku
9. Przy obiedzie klika "Pomijam" (je na mieście) → slot przygaszony
10. Klika "Składniki na ten dzień" → widzi braki vs spiżarnia
11. Klika "Dodaj braki na dziś do listy" → toast
12. Następnego dnia: "Kopiuj dzień" → wybiera dzień docelowy → gotowe

Znane problemy:

• Po dodaniu braków brak informacji "już dodano" — ryzyko duplikacji
• "Kopiuj dzień" kopiuje też status "Pominięto"

---

Scenariusz 4: Zarządzanie spiżarnią

Cel: Użytkownik sprawdza co ma w domu.

1. Przechodzi na zakładkę Spiżarnia
2. Widzi chipy składników pogrupowane po kategorii
3. Włącza "Tylko na stanie" → widzi co ma
4. Klika "Płatki owsiane" → bottom sheet
5. Ustawia 500g
6. Zamyka → chip zmienił się na zielony z "500 g"
7. Chce dodać mleko na listę → klika "Dodaj na listę" w sheecie

Znane problemy:

• Po zamknięciu bottom sheet scroll wraca na górę (re-render)
• Brak możliwości ręcznego wpisania ilości szybko (ale jest input type=number)

---

Scenariusz 5: Zakupy w sklepie

Cel: Użytkownik jest w sklepie, odznacza kupione.

1. Otwiera zakładkę Zakupy
2. Widzi listę kuchenną pogrupowaną po kategorii
3. Bierze mleko z półki → klika checkbox → przekreślenie
4. Widzi sourceNote: "Braki z planu dnia"
5. Ilość się nie zgadza — klika na ilość → prompt → poprawia
6. Kupuje dalsze pozycje

Znane problemy:

• Kupione mieszają się z niekupionymi w grupie (brak separacji)
• Brak podsumowania: "Do kupienia: 5, kupione: 3"
• Na telefonie w sklepie — elementy mogłyby być większe

---

Scenariusz 6: Po zakupach — przeniesienie do spiżarni

Cel: Użytkownik wrócił ze sklepu, aktualizuje spiżarnię.

1. Otwiera Zakupy → widzi zaznaczone pozycje
2. Pojawia się pasek: "Kupione → spiżarnia" i "Wyczyść kupione"
3. Klika "Kupione → spiżarnia" → potwierdzenie z podglądem pozycji
4. Potwierdza → toast "Przeniesiono X pozycji"
5. Kupione znikają z listy
6. Przechodzi do Spiżarni → stany zaktualizowane
7. Wraca do Planera → braki zmniejszone

Znane problemy:

• Brak undo (cofnięcia przeniesienia)

---

Scenariusz 7: Gotowanie z przepisu

Cel: Użytkownik gotuje, sprawdza przepis krok po kroku.

1. Otwiera Planer → dzisiejszy dzień
2. Klika przepis w slocie Kolacja
3. Otwiera się detal → przełącza na "Kroki"
4. Czyta krok po kroku
5. Sprawdza ilość składnika → przełącza na "Składniki"
6. Wraca na "Kroki"

Znane problemy:

• Brak trybu "krok po kroku" (full-screen, jeden krok, swipe next)
• Ekran wygasa po chwili (brak wake lock)
• Nie ma checkboxa przy krokach

---

Scenariusz 8: "Co mogę ugotować?"

Cel: Użytkownik ma coś w spiżarni, chce wiedzieć co da się z tego zrobić.

1. Otwiera Spiżarnię → widzi co ma
2. Chciałby kliknąć "Co mogę ugotować?" → takiej funkcji jeszcze nie ma
3. Musi ręcznie sprawdzać przepisy

Propozycja: Filtr "Mam składniki" w widoku Przepisy.

---

5. Tabela znanych problemów i luk

#	Problem	Scenariusz	Status
1	Brak wskaźnika aktywnych filtrów na ikonce	2	TODO
2	Podwójne dodanie braków do listy zakupów	3	TODO
3	Kupione mieszają się z niekupionymi (brak separacji)	5	TODO
4	Brak podsumowania na liście zakupów (ile kupione/do kupienia)	5	TODO
5	Brak undo przy "Kupione → spiżarnia"	6	TODO
6	Brak trybu "krok po kroku" przy gotowaniu	7	PROPOZYCJA
7	Brak wake lock (ekran wygasa)	7	PROPOZYCJA
8	Brak filtra "Mam składniki"	8	PROPOZYCJA
9	Scroll spiżarni resetuje się po edycji	4	TODO
10	Zamknięcie filtrów ← vs "Pokaż" — niespójne zachowanie?	2	DO WERYFIKACJI

---

6. Zrealizowane w ostatniej iteracji

#	Funkcja	Widok
P1	"Dodaj do planera" z widoku przepisu (wybór dnia + slotu)	RecipeDetail
P2	Kopiowanie planu dnia na inny dzień	MealPlanner
P3	"Pomijam" w slocie planera	MealPlanner + planStore
P4	Kalorie per slot w nagłówku slotu	MealPlanner
P5	Edycja ilości na liście zakupów (klik → prompt)	Shopping
P6	Potwierdzenie "Kupione → spiżarnia" z podglądem	Shopping
P7	Lepszy picker przepisów (wyszukiwarka + ostatnio używane)	MealPlanner

---

7. Stos technologiczny

Warstwa	Technologia
Frontend	Plain HTML + ES modules, imperatywna manipulacja DOM
Style	Tailwind CSS (CDN), Font Awesome 6 (CDN)
Dane	Statyczny katalog js/data/catalog.js, localStorage
PWA	manifest.webmanifest + sw.js
Deploy	Docker + nginx:alpine, Gitea CI/CD
Język UI	Polski