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	5 slotów (śniadanie, drugie śniadanie, obiad, przekąska, kolacja)
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 itp.)
Przepisy	Katalog wbudowany (9 przepisów, 24 składniki), bez edytora

---

2. Architektura i stos technologiczny

Warstwa	Technologia
Frontend	Plain HTML + ES modules, imperatywna manipulacja DOM
Style	Tailwind CSS (CDN) + inline <style> w index.html, Font Awesome 6 (CDN)
Dane	Statyczny katalog js/data/catalog.js (INGREDIENTS + RECIPES z opcjonalnymi alternatives per składnik), localStorage
Stan	Moduły-closure (filterState, state w planerze) + localStorage przez serwisy
Komunikacja widoków	Globalne callbacki na window (refreshPlanner, refreshPantry, refreshShopping, openRecipeDetail itp.)
PWA	manifest.webmanifest + sw.js (network-only fetch, spełnia warunek instalowalności)
Deploy	Docker + nginx:alpine, Gitea CI/CD
Język UI	Polski

Struktura plików

index.html                    ← jedyny plik HTML, shell aplikacji
js/
  app.js                      ← entry point, montuje widoki, setupTabs()
  storageKeys.js              ← klucze localStorage
  views/
    RecipeList.js             ← lista przepisów
    Filter.js                 ← overlay filtrów
    RecipeDetail.js           ← detal przepisu (slide-in overlay)
    MealPlanner.js            ← planer posiłków + kalendarz
    Pantry.js                 ← spiżarnia
    Shopping.js               ← listy zakupów
  services/
    planStore.js              ← load/save planów posiłków
    pantryShopping.js         ← logika spiżarni i list zakupów
    planIngredients.js        ← analityka: sumy kalorii, braki, prognoza
    dateUtils.js              ← narzędzia dat (poniedziałek jako start tygodnia)
  planner/
    mealSlots.js              ← definicja 5 slotów (id, label, icon)
  data/
    catalog.js                ← INGREDIENTS, RECIPES, helpery
  ui/
    toast.js                  ← showAppToast()

---

3. Przegląd widoków

3.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ł, opis, czas przygotowania, kalorie, chipy slotów. Kliknięcie otwiera detal.

Elementy:

• Wyszukiwarka (real-time, po tytule i tagach)
• Przycisk filtrów (otwiera overlay)
• Siatka kart
• Empty state gdy brak wyników

Stan: Kompletny.

---

3.2 Filtry (Filter)

Lokalizacja: js/views/Filter.js

Full-screen overlay (z-50) z chipami pór posiłku, tagami dietetycznymi i suwakiem czasu. Filtr zamknięty przyciskiem ← odrzuca niezapisane zmiany; "Pokaż X wyników" aplikuje i zamyka.

Elementy:

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

Stan: Kompletny.

---

3.3 Szczegóły przepisu (RecipeDetail)

Lokalizacja: js/views/RecipeDetail.js

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

Elementy:

• Hero (placeholder) + strzałka powrotu + przycisk "Zaplanuj"
• Tytuł, tagi (sloty + tagi przepisu), czas, kcal
• Selektor porcji (± , zakres 1–12) z przeliczaniem składników i wartości
• Zakładka Składniki: lista read-only (bez checkboxów, bez badge'ów spiżarni). Składniki z wymiennymi wariantami mają ikonę shuffle — kliknięcie rozwija karty z alternatywami i ich wartościami odżywczymi (informacyjnie, bez możliwości wyboru)
• Zakładka Kroki: numerowane kroki
• Zakładka Wartości: kcal/białko/tłuszcze/węglowodany × porcje
• Bottom sheet "Zaplanuj":
  1. Kalendarz (tydzień/miesiąc, nawigacja ←/→/Dziś, toggle rozwinięcia) — styl ujednolicony z MealPlanner
  2. Pora posiłku — chipy filtrowane do allowedSlots przepisu
  3. Wymienne składniki (opcjonalne, widoczne tylko gdy przepis ma alternatives) — kompaktowe karty per składnik wyświetlające aktualny wybór z wartościami odżywczymi; kliknięcie rozwija listę opcji z radio-przyciskami; po wyborze karta się zwija; zmieniony składnik ma amber tło
  4. Przycisk "Dodaj" → zapis do planStore (z opcjonalnym obiektem substitutions)

Model danych — wymienne składniki:

• W RECIPES, składnik może mieć pole alternatives: ['id1', 'id2', ...] — tablica ID alternatywnych składników
• Przy dodawaniu do planera, wybrane zamienniki zapisywane są jako substitutions: { originalId: chosenAltId } w planStore
• Przykład: serek wiejski ma 3 wymienne składniki — orzechy (5 opcji), truskawki (banany), borówki (jagody)

Stan: Kompletny.

---

3.4 Planer posiłków (MealPlanner)

Lokalizacja: js/views/MealPlanner.js

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

Elementy kalendarza:

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

Elementy planu dnia:

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

Bottom sheety:

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

Demo: seedDemoIfEmpty wypełnia dzisiejszy dzień danymi demo gdy localStorage jest pusty.

Stan: Kompletny.

---

3.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 (multi-select)
• Toggle "Tylko na stanie"
• Siatka chipów składników pogrupowana po kategorii (kolor wg stanu)
• Bottom sheet edycji (#pv2-edit-sheet): ± z krokiem (pantryQtyStep), input numeryczny, opcjonalne wartości odżywcze (per 100g), "Dodaj na listę zakupów" (z purchasePack)

Stan: Kompletny.

---

3.6 Zakupy (Shopping)

Lokalizacja: js/views/Shopping.js

Zarządzanie listami zakupów — jedna stała lista kuchenna + dowolna liczba list freeform.

Elementy:

• Selektor aktywnej listy (dropdown)
• Przycisk "Nowa lista" (freeform) + usuwanie list (nie dotyczy kuchennej)
• Lista kuchenna (KITCHEN_LIST_ID): pogrupowana po kategorii, checkbox, edycja ilości (klik → prompt), usuwanie pozycji
• Pasek akcji (widoczny gdy są zaznaczone pozycje): "Kupione → spiżarnia" (z potwierdzeniem i podglądem) + "Wyczyść kupione"
• Lista freeform: pozycje tekstowe z opcjonalną notatką, checkbox

Stan: Kompletny.

---

4. Przepływy między widokami

Przepisy ──[klik kartę]──→ Szczegóły przepisu
                              └──[Zaplanuj]──→ Bottom sheet (kalendarz + pora + opcjonalnie wymiana składników) → Planer

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

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

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

---

5. 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ę "Serek wiejski z orzechami i owocami"
4. Widzi detal: składniki, kroki, wartości odżywcze
5. Przy orzechach, truskawkach i borówkach widzi ikonę shuffle — klika ją przy orzechach
6. Rozwija się lista alternatyw (laskowe, nerkowca, migdały, pekan) z wartościami odżywczymi — informacyjnie
7. Zmienia liczbę porcji z 1 na 2 → składniki i kcal się przeliczają
8. Przełącza zakładkę na "Kroki" → widzi numerowane kroki
9. Przełącza na "Wartości" → widzi makroskładniki ×2
10. Wraca strzałką ← do listy

Uwagi:

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

---

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 → otwiera się overlay
4. Zaznacza "Kolacja" → aktualizuje się licznik wyników
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

---

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ń (demo-dane lub wcześniej zaplanowane)
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 + prognoza
11. Klika "Dodaj braki na dziś do listy" → toast potwierdzenia
12. Następnego dnia: "Kopiuj dzień" → wybiera dzień docelowy → gotowe

---

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 (przyciskami ± lub inputem)
6. Zamyka → chip zmienił się na zielony z "500 g"
7. Chce dodać mleko na listę → klika "Dodaj na listę" w sheecie

---

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 z informacją skąd pozycja pochodzi
5. Ilość się nie zgadza — klika na ilość → prompt → poprawia
6. Kupuje dalsze pozycje

---

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

---

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"

---

Scenariusz 8: Dodanie przepisu do planera z widoku detalu

Cel: Użytkownik znalazł przepis i chce go zaplanować.

1. Przegląda Przepisy → otwiera detal "Serek wiejski z orzechami i owocami"
2. Klika "Zaplanuj" (górny przycisk)
3. Otwiera się bottom sheet z kalendarzem (domyślnie widok tygodnia, można rozwinąć do miesiąca)
4. Wybiera dzień w kalendarzu
5. Wybiera porę posiłku (np. "Śniadanie")
6. Widzi sekcję "Wymienne składniki" — 3 kompaktowe karty (orzechy, truskawki, borówki) z aktualnym wyborem
7. Klika kartę "Orzechy włoskie" → rozwija się lista opcji (włoskie, laskowe, nerkowca, migdały, pekan) z wartościami odżywczymi i radio-przyciskami
8. Wybiera "Migdały" → karta się zwija, wybrany składnik zmienia się na "Migdały" z amber tłem
9. Klika "Dodaj" → toast potwierdzenia, sheet się zamyka, przepis dodany do planera z informacją o zamianie (substitutions)

---

Scenariusz 9: "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.

---

6. Znane problemy i propozycje ulepszeń

Do poprawy (TODO)

#	Problem	Dotyczy scenariusza
1	Brak wskaźnika aktywnych filtrów na ikonce (badge/kropka)	2
2	Po dodaniu braków do listy zakupów brak ochrony przed duplikacją (brak info "już dodano")	3
3	Kupione pozycje mieszają się z niekupionymi w tej samej grupie (brak separacji)	5
4	Brak podsumowania na liście zakupów ("Do kupienia: X, kupione: Y")	5
5	Brak undo przy "Kupione → spiżarnia"	6
6	Scroll spiżarni resetuje się po edycji (re-render)	4
7	"Kopiuj dzień" kopiuje też status "Pominięto" — może nie zawsze pożądane	3

Propozycje nowych funkcji

#	Funkcja	Opis
P1	Tryb "krok po kroku" przy gotowaniu	Full-screen, jeden krok, swipe next + checkbox
P2	Wake lock	Zapobiega wygaszeniu ekranu podczas gotowania
P3	Filtr "Mam składniki"	W widoku Przepisy — pokaż co da się ugotować z aktualnej spiżarni
P4	Większe elementy na liście zakupów	Ułatwienie obsługi w sklepie na telefonie
P5	Edytor przepisów	Dodawanie własnych przepisów (poza wbudowanym katalogiem)