MeshCore-Solo/docs/design/nearby_redesign.md

Nearby Nodes — analiza i propozycja uporządkowania

Branch: refactor/nearby-nodes (zmergowany do main) Plik źródłowy: NearbyScreen.h Status: zaimplementowane — dokument zachowany jako zapis analizy/decyzji.

Odchylenia od propozycji (stan faktyczny):

• Akcji Filter… w menu nie ma — duplikowała cykl LEFT/RIGHT po typie, więc filtr został wyłącznie na liście (sekcja 3.1 zakładała Filter… też w menu).
• Sort nie jest togglem przez Enter, lecz zmienia się in-place przez LEFT/RIGHT na podświetlonym wierszu w popupie (wzorzec ustawień Trail), a wiersz pojawia się tylko dla źródła Zapisane (skan nie ma dystansu).
• Filtr i sort utrzymują się między wejściami na ekran (nie są resetowane).

---

1. Jak narzędzie jest zbudowane dzisiaj

Ekran łączy w sobie trzy osobne tryby o własnych listach, widokach szczegółów i popupach:

NearbyScreen
├── LIST (kontakty zapisane w mesh)        ← tryb domyślny
│   ├── filtr cyklowany LEFT/RIGHT (7 stanów)
│   ├── DETAIL  (Enter)  → Lat/Lon/Dist/Type/Seen
│   │   └── _opts popup (Hold Enter): Navigate / Ping / Save waypoint
│   │       └── _ping_menu popup
│   ├── NAV view (pełnoekranowa nawigacja)
│   └── _ctx_menu popup (Hold Enter): Discover / Navigate / Save waypoint
│
└── DISCOVER (skan na żywo NODE_DISCOVER_REQ) ← osobny pod-ekran
    ├── lista wyników (karty 2-liniowe)
    │   Hold Enter = ponowny skan (brak menu!)
    └── DETAIL (Enter) → pubkey / RSSI / SNR / status
        └── _ping_menu popup (Hold Enter = od razu ping, bez Options)

Stan ekranu trzyma 15+ pól (_detail, _nav, _discover_mode, _ddetail, _pinging, _filter, dwa komplety _sel/_scroll, trzy bufory wyników ping…) i trzy instancje PopupMenu (_ctx_menu, _opts, _ping_menu).

---

2. Co konkretnie jest nieuporządkowane

2.1 Jeden cykl filtra miesza trzy różne osie

LEFT/RIGHT przewija 7 stanów:

Fav · ALL · Comp · Rpt · Room · Snsr · TIME

Ale to nie jest jedna oś — to trzy wciśnięte w jeden liniowy cykl:

Stan	Czym naprawdę jest
Fav	filtr ulubionych (flaga ci.flags & 1)
ALL/Comp/Rpt/Room/Snsr	filtr po typie węzła
TIME	sortowanie (po lastmod zamiast po dystansie)

Konsekwencje:

• użytkownik „scrolluje po kategoriach” na ślepo — nie widzi wszystkich naraz, musi cyklować, by trafić w to, czego szuka;
• kombinacje są niemożliwe: nie da się zobaczyć „ulubionych repeaterów posortowanych po dystansie" ani „repeaterów posortowanych po czasie” — model wymusza dokładnie jeden stan z siedmiu;
• TIME jako „filtr" jest mylące — zmienia kolejność, nie zawartość;
• etykieta w nagłówku (NEARBY[TIME]) nie mówi, że to sort.

2.2 Te same akcje, różne menu w zależności od miejsca

Akcja	Lista (_ctx_menu)	Detail kontaktu (_opts)	Detail discover
Navigate	✓	✓	—
Save waypoint	✓	✓	—
Ping	—	✓	✓
Discover	✓	—	—

Ten sam węzeł oferuje inny zestaw akcji w zależności od tego, gdzie na niego patrzysz. Ping jest osiągalny tylko ze szczegółów, Discover tylko z listy.

2.3 „Hold Enter” znaczy co innego na każdym ekranie

Ekran	Hold Enter (KEY_CONTEXT_MENU)
Lista nearby	otwiera menu kontekstowe
Detail kontaktu	otwiera menu Options
Lista discover	ponowny skan (żadnego menu)
Detail discover	od razu Ping (pomija Options)

Brak spójnego modelu „przytrzymaj = menu akcji”.

2.4 _ping_menu to bespoke widget

W przeciwieństwie do reszty popupów, ping-menu:

• ma wiersze tylko-do-odczytu (RTT / SNR), więc połyka UP/DOWN;
• przebudowuje się w trakcie (rebuildPingMenu) gdy przychodzą wyniki;
• zostaje otwarte po SELECTED (reszta popupów się zamyka);
• ma własny handlePingMenuInput z trybem allow_enter_to_open.

To działa, ale jest to czwarty, niestandardowy wzorzec interakcji w jednym narzędziu.

2.5 Duplikacja list/detail/ping

renderDiscover/handleInputDiscover/renderDiscoverDetail to niemal równoległa kopia logiki listy i szczegółów nearby (osobne _dsel, _dscroll, _d_visible, własne rysowanie kart). Discover i Nearby robią to samo — pokazują listę węzłów z możliwością wejścia w szczegóły i pingowania — ale dwoma osobnymi ścieżkami kodu.

---

3. Propozycja uporządkowania

Trzy zasady przewodnie: (a) jedno menu akcji wszędzie, (b) filtr i sortowanie jako osobne, jawne osie, (c) jeden wzorzec listy.

3.1 Rozdziel filtr od sortowania

Zamiast jednego cyklu 7-stanowego — dwie niezależne osie wybierane z menu (nie przez ślepe cyklowanie):

Filtr (oś „co pokazujemy") i sort (oś „w jakiej kolejności") są od siebie niezależne i łączą się dowolnie:

FILTR (jedna oś — typ węzła, z Ulubionymi)      SORT (przełącznik)
  • Wszystkie                                      • Dystans (domyślnie)
  • Ulubione                                       • Ostatnio słyszane
  • Companion
  • Repeater
  • Room
  • Sensor

Sterowanie (zatwierdzone):

• LEFT/RIGHT = szybki cykl tylko po filtrze-typie (jedna spójna oś, znany gest; bez „TIME" zanieczyszczającego cykl);
• Sort = przełącznik w menu akcji (Dystans ↔ Ostatnio słyszane), trzymany niezależnie od filtra;
• Filter… dostępny też w menu akcji (odkrywalność — cała lista widoczna naraz, nie tylko cyklowanie).

Dzięki temu „ulubione repeatery po dystansie" staje się możliwe, a w nagłówku widać oba wymiary, np. NEARBY · Rpt · ↓dist.

3.2 Jedno spójne menu akcji (Hold Enter wszędzie)

Jeden PopupMenu (zamiast _ctx_menu + _opts), pozycje zależne od kontekstu, ale kolejność i nazwy stałe:

Hold Enter →  Options
  • Navigate        (gdy węzeł ma GPS)
  • Ping            (gdy znamy pubkey)
  • Save waypoint   (gdy węzeł ma GPS)
  ──────────────
  • Filter…         (podmenu z 3.1)
  • Sort…           (toggle z 3.1)
  • Discover scan   (uruchamia skan na żywo = przełącza źródło)

To samo menu na liście i w szczegółach, w obu źródłach (Zapisane / Skan). Pozycje niedostępne są pomijane (jak już teraz robi has_node), ale nigdy nie zmieniają kolejności ani nazw. „Hold Enter = menu akcji" — bez wyjątków. Ping zawsze przez Options (znika „od razu Ping" z detalu Discover); rescan to pozycja menu, nie ukryty Hold Enter.

3.3 Jedna lista, dwa źródła (Zapisane / Skan na żywo)

Zatwierdzone: zamiast osobnego pod-ekranu Discover — jeden komponent listy/szczegółów/menu/ping napędzany przełącznikiem źródła:

• ta sama nawigacja, to samo menu akcji, ten sam wzorzec szczegółów i pingu (znika duplikacja renderDiscover*, niespójne Hold Enter i połowa pól stanu);
• różni się tylko prawa kolumna wiersza i pola w detalu:
  • źródło Zapisane → dystans / azymut / lastmod (jak dziś),
  • źródło Skan na żywo → RSSI / SNR (dane z DiscoverResult).

To nie jest dosłowne zlanie dwóch list w jedną tablicę (dane mają różny kształt — kontakt ma GPS, wynik skanu ma sygnał), tylko jedna ścieżka interakcji nad dwoma źródłami. Wybór źródła = „Discover scan" w menu (uruchamia NODE_DISCOVER_REQ i przełącza widok na wyniki) oraz powrót do Zapisanych przez Cancel.

---

4. Proponowany zakres (etapami)

Etap	Zmiana	Ryzyko
1	Rozdziel sort od filtra: TIME znika z cyklu; LEFT/RIGHT cyklują tylko typ+Fav; sort jako stan + toggle	niskie
2	Scal _ctx_menu i _opts w jedno menu akcji o stałej kolejności; dodaj Filter…/Sort…	niskie
3	Ujednolić Hold Enter w Discover (menu zamiast bezpośredniego rescan/ping; Ping zawsze przez Options)	średnie
4	Scal listę Discover z listą Nearby w jeden komponent z przełącznikiem źródła	wyższe

Kolejność implementacji: 1 → 2 → 3 → 4. Etapy 1–2 dają największą poprawę „uporządkowania" przy najmniejszym ryzyku; 3–4 domykają spójność (jedna lista, jedno menu wszędzie).

---

5. Decyzje (zatwierdzone 2026-06-14)

1. Filtr i sort — pełne rozdzielenie osi. LEFT/RIGHT = szybki cykl filtra-typu; Sort jako toggle w menu; Filter… też w menu dla odkrywalności. (Nie chowamy wszystkiego do menu — zachowujemy szybki gest.)
2. Discover — jedna lista, dwa źródła. Wspólny komponent interakcji; różni się tylko prawa kolumna/pola detalu (dystans vs sygnał).