ui(menu): add paged ncurses navigation and chooser scrolling

Author: arancormonk

docs/ui-terminal.md

@@ -20,10 +20,10 @@ processed).
 
 Common controls:
 
-- Navigate: arrow keys (`Up`/`Down`)
-- Select: `Enter`
-- Back/close: `Esc`, `q`
-- Scroll long lists: `PageUp`/`PageDown`, `Home`/`End` (where supported by that prompt)
+- Move selection: arrow keys (`Up`/`Down`), `PageUp`/`PageDown`, `Home`/`End`
+- Select / open submenu: `Enter`, `Right`
+- Back / close: `Esc`, `q`, `Left`
+- Item help: `h`
 
 ## Hotkeys (Main Screen)
 

src/ui/terminal/menu_core.c

@@ -43,6 +43,85 @@ static UiMenuFrame g_stack[8];
 static int g_depth = 0;
 static UiCtx g_ctx_overlay = {0};
 
+static int
+ui_frame_items_rows(const UiMenuFrame* f) {
+    int rows = 1;
+    if (f && f->h > 7) {
+        rows = f->h - 7;
+    }
+    if (rows < 1) {
+        rows = 1;
+    }
+    return rows;
+}
+
+static int
+ui_first_enabled_idx(const NcMenuItem* items, size_t n) {
+    if (!items || n == 0) {
+        return 0;
+    }
+    for (size_t i = 0; i < n; i++) {
+        if (ui_is_enabled(&items[i], &g_ctx_overlay)) {
+            return (int)i;
+        }
+    }
+    return 0;
+}
+
+static int
+ui_last_enabled_idx(const NcMenuItem* items, size_t n) {
+    if (!items || n == 0) {
+        return 0;
+    }
+    for (size_t i = n; i > 0; i--) {
+        if (ui_is_enabled(&items[i - 1], &g_ctx_overlay)) {
+            return (int)(i - 1);
+        }
+    }
+    return 0;
+}
+
+static int
+ui_step_enabled(const NcMenuItem* items, size_t n, int from, int dir, int steps) {
+    if (!items || n == 0) {
+        return 0;
+    }
+    if (steps < 1) {
+        steps = 1;
+    }
+    const int delta = (dir < 0) ? -1 : 1;
+    int idx = from;
+    for (int i = 0; i < steps; i++) {
+        int next = idx;
+        while (1) {
+            next += delta;
+            if (next < 0 || next >= (int)n) {
+                next = idx;
+                break;
+            }
+            if (ui_is_enabled(&items[next], &g_ctx_overlay)) {
+                break;
+            }
+        }
+        if (next == idx) {
+            break;
+        }
+        idx = next;
+    }
+    return idx;
+}
+
+static void
+ui_frame_keep_highlight_visible(UiMenuFrame* f) {
+    if (!f || !f->items || f->n == 0) {
+        return;
+    }
+    int page_rows = ui_frame_items_rows(f);
+    int vis_total = ui_visible_count_and_maxlab(f->items, f->n, &g_ctx_overlay, NULL);
+    int hi_pos = ui_visible_index_for_item(f->items, f->n, &g_ctx_overlay, f->hi);
+    f->top = ui_scroll_follow_selection(vis_total, page_rows, f->top, hi_pos);
+}
+
 static void
 ui_overlay_breadcrumb(char* buf, size_t n) {
     if (!buf || n == 0) {
@@ -80,6 +159,65 @@ ui_overlay_close_all(void) {
     g_overlay_open = 0;
 }
 
+static void
+ui_overlay_pop_one(void) {
+    if (g_depth <= 0) {
+        return;
+    }
+    UiMenuFrame* cur = &g_stack[g_depth - 1];
+    if (cur->win) {
+        delwin(cur->win);
+        cur->win = NULL;
+    }
+    g_depth--;
+    if (g_depth <= 0) {
+        g_depth = 0;
+        g_overlay_open = 0;
+    }
+}
+
+static int
+ui_menu_activate_current(void) {
+    if (!g_overlay_open || g_depth <= 0) {
+        return 0;
+    }
+    UiMenuFrame* f = &g_stack[g_depth - 1];
+    const NcMenuItem* it = &f->items[f->hi];
+    if (!ui_is_enabled(it, &g_ctx_overlay)) {
+        return 1;
+    }
+    if (it->submenu && it->submenu_len > 0) {
+        if (g_depth < (int)(sizeof g_stack / sizeof g_stack[0])) {
+            UiMenuFrame* nf = &g_stack[g_depth++];
+            memset(nf, 0, sizeof(*nf));
+            nf->items = it->submenu;
+            nf->n = it->submenu_len;
+            nf->hi = ui_first_enabled_idx(nf->items, nf->n);
+            nf->top = 0;
+            nf->title = it->label ? it->label : it->id;
+            ui_overlay_layout(nf, &g_ctx_overlay);
+        }
+    }
+    if (it->on_select) {
+        it->on_select(&g_ctx_overlay);
+        if (exitflag) {
+            ui_overlay_close_all();
+            return 1;
+        }
+        UiMenuFrame* cf = &g_stack[g_depth - 1];
+        if (!ui_is_enabled(&cf->items[cf->hi], &g_ctx_overlay)) {
+            cf->hi = ui_next_enabled(cf->items, cf->n, &g_ctx_overlay, cf->hi, +1);
+        }
+        ui_overlay_layout(cf, &g_ctx_overlay);
+        ui_frame_keep_highlight_visible(cf);
+        ui_overlay_recreate_if_needed(cf);
+    }
+    if (!it->on_select && (!it->submenu || it->submenu_len == 0) && it->help && *it->help) {
+        ui_help_open(it->help);
+    }
+    return 1;
+}
+
 void
 ui_menu_open_async(dsd_opts* opts, dsd_state* state) {
     // Initialize overlay context and push root menu
@@ -105,7 +243,8 @@ ui_menu_open_async(dsd_opts* opts, dsd_state* state) {
     memset(g_stack, 0, sizeof(g_stack));
     g_stack[0].items = items;
     g_stack[0].n = n;
-    g_stack[0].hi = 0;
+    g_stack[0].hi = ui_first_enabled_idx(items, n);
+    g_stack[0].top = 0;
     g_stack[0].title = "Main Menu";
     ui_overlay_layout(&g_stack[0], &g_ctx_overlay);
 }
@@ -151,17 +290,45 @@ ui_menu_handle_key(int ch, dsd_opts* opts, dsd_state* state) {
             f->win = NULL;
         }
         ui_overlay_layout(f, &g_ctx_overlay);
+        ui_frame_keep_highlight_visible(f);
         return 1;
     }
     if (ch == ERR) {
         return 0;
     }
     if (ch == KEY_UP) {
         f->hi = ui_next_enabled(f->items, f->n, &g_ctx_overlay, f->hi, -1);
+        ui_frame_keep_highlight_visible(f);
         return 1;
     }
     if (ch == KEY_DOWN) {
         f->hi = ui_next_enabled(f->items, f->n, &g_ctx_overlay, f->hi, +1);
+        ui_frame_keep_highlight_visible(f);
+        return 1;
+    }
+    if (ch == KEY_HOME) {
+        f->hi = ui_first_enabled_idx(f->items, f->n);
+        f->top = 0;
+        return 1;
+    }
+    if (ch == KEY_END) {
+        f->hi = ui_last_enabled_idx(f->items, f->n);
+        f->top = ui_scroll_last_page_top(ui_visible_count_and_maxlab(f->items, f->n, &g_ctx_overlay, NULL),
+                                         ui_frame_items_rows(f));
+        return 1;
+    }
+    if (ch == KEY_PPAGE) {
+        int page = ui_scroll_page_step_from_rows(ui_frame_items_rows(f));
+        f->hi = ui_step_enabled(f->items, f->n, f->hi, -1, page);
+        f->top -= page;
+        ui_frame_keep_highlight_visible(f);
+        return 1;
+    }
+    if (ch == KEY_NPAGE) {
+        int page = ui_scroll_page_step_from_rows(ui_frame_items_rows(f));
+        f->hi = ui_step_enabled(f->items, f->n, f->hi, +1, page);
+        f->top += page;
+        ui_frame_keep_highlight_visible(f);
         return 1;
     }
     if (ch == 'h' || ch == 'H') {
@@ -171,59 +338,16 @@ ui_menu_handle_key(int ch, dsd_opts* opts, dsd_state* state) {
         }
         return 1;
     }
-    if (ch == DSD_KEY_ESC || ch == 'q' || ch == 'Q') {
-        // Pop submenu or close root
+    if (ch == KEY_LEFT || ch == DSD_KEY_ESC || ch == 'q' || ch == 'Q') {
         if (g_depth > 1) {
-            UiMenuFrame* cur = &g_stack[g_depth - 1];
-            if (cur->win) {
-                delwin(cur->win);
-                cur->win = NULL;
-            }
-            g_depth--;
+            ui_overlay_pop_one();
         } else {
             ui_overlay_close_all();
         }
         return 1;
     }
-    if (ch == 10 || ch == KEY_ENTER || ch == '\r') {
-        const NcMenuItem* it = &f->items[f->hi];
-        if (!ui_is_enabled(it, &g_ctx_overlay)) {
-            return 1;
-        }
-        if (it->submenu && it->submenu_len > 0) {
-            if (g_depth < (int)(sizeof g_stack / sizeof g_stack[0])) {
-                UiMenuFrame* nf = &g_stack[g_depth++];
-                memset(nf, 0, sizeof(*nf));
-                nf->items = it->submenu;
-                nf->n = it->submenu_len;
-                nf->hi = 0;
-                nf->title = it->label ? it->label : it->id;
-                if (!ui_is_enabled(&nf->items[nf->hi], &g_ctx_overlay)) {
-                    nf->hi = ui_next_enabled(nf->items, nf->n, &g_ctx_overlay, nf->hi, +1);
-                }
-                ui_overlay_layout(nf, &g_ctx_overlay);
-            }
-        }
-        if (it->on_select) {
-            it->on_select(&g_ctx_overlay);
-            if (exitflag) {
-                // Let caller exit soon
-                ui_overlay_close_all();
-                return 1;
-            }
-            // After a toggle or action, visible items may have changed.
-            // Ensure the highlight points at a visible item and recompute size.
-            UiMenuFrame* cf = &g_stack[g_depth - 1];
-            if (!ui_is_enabled(&cf->items[cf->hi], &g_ctx_overlay)) {
-                cf->hi = ui_next_enabled(cf->items, cf->n, &g_ctx_overlay, cf->hi, +1);
-            }
-            ui_overlay_layout(cf, &g_ctx_overlay);
-            ui_overlay_recreate_if_needed(cf);
-        }
-        if (!it->on_select && (!it->submenu || it->submenu_len == 0) && it->help && *it->help) {
-            ui_help_open(it->help);
-        }
-        return 1;
+    if (ch == KEY_RIGHT || ch == 10 || ch == KEY_ENTER || ch == '\r') {
+        return ui_menu_activate_current();
     }
     return 0;
 }
@@ -256,12 +380,13 @@ ui_menu_tick(dsd_opts* opts, dsd_state* state) {
     }
     // Ensure window exists with up-to-date geometry
     ui_overlay_layout(f, &g_ctx_overlay);
+    ui_frame_keep_highlight_visible(f);
     ui_overlay_recreate_if_needed(f);
     ui_overlay_ensure_window(f);
     if (!f->win) {
         return;
     }
     char breadcrumb[256];
     ui_overlay_breadcrumb(breadcrumb, sizeof breadcrumb);
-    ui_draw_menu(f->win, f->items, f->n, f->hi, breadcrumb, &g_ctx_overlay);
+    ui_draw_menu(f->win, f->items, f->n, f->hi, &f->top, breadcrumb, &g_ctx_overlay);
 }

src/ui/terminal/menu_internal.h

@@ -11,8 +11,13 @@
  */
 #pragma once
 
+#include <stddef.h>
+
+#include <dsd-neo/core/opts_fwd.h>
+#include <dsd-neo/core/state_fwd.h>
 #include <dsd-neo/platform/curses_compat.h>
-#include <dsd-neo/ui/menu_core.h>
+
+typedef struct NcMenuItem NcMenuItem;
 
 // Shared UI context passed to callbacks (full definition; forward-declared in menu_defs.h)
 typedef struct UiCtx {
@@ -25,6 +30,7 @@ typedef struct {
     const NcMenuItem* items;
     size_t n;
     int hi;
+    int top;
     const char* title;
     WINDOW* win;
     int w, h;
@@ -103,13 +109,61 @@ typedef struct {
     int n;
 } PulseSelCtx;
 
+static inline int
+ui_scroll_page_step_from_rows(int page_rows) {
+    if (page_rows <= 1) {
+        return 1;
+    }
+    return page_rows - 1;
+}
+
+static inline int
+ui_scroll_clamp_top(int total, int page_rows, int top) {
+    if (total <= 0 || page_rows <= 0 || total <= page_rows) {
+        return 0;
+    }
+    if (top < 0) {
+        top = 0;
+    }
+    if (top > total - page_rows) {
+        top = total - page_rows;
+    }
+    return top;
+}
+
+static inline int
+ui_scroll_last_page_top(int total, int page_rows) {
+    return ui_scroll_clamp_top(total, page_rows, total - page_rows);
+}
+
+static inline int
+ui_scroll_follow_selection(int total, int page_rows, int top, int sel_pos) {
+    if (total <= 0 || page_rows <= 0) {
+        return 0;
+    }
+    if (sel_pos < 0) {
+        sel_pos = 0;
+    }
+    if (sel_pos >= total) {
+        sel_pos = total - 1;
+    }
+    top = ui_scroll_clamp_top(total, page_rows, top);
+    if (sel_pos < top) {
+        top = sel_pos;
+    } else if (sel_pos >= top + page_rows) {
+        top = sel_pos - page_rows + 1;
+    }
+    return ui_scroll_clamp_top(total, page_rows, top);
+}
+
 // ---- Visibility helpers (from menu_render.c) ----
 int ui_is_enabled(const NcMenuItem* it, void* ctx);
 int ui_submenu_has_visible(const NcMenuItem* items, size_t n, void* ctx);
 int ui_next_enabled(const NcMenuItem* items, size_t n, void* ctx, int from, int dir);
+int ui_visible_index_for_item(const NcMenuItem* items, size_t n, void* ctx, int idx);
 
 // ---- Render helpers (from menu_render.c) ----
-void ui_draw_menu(WINDOW* win, const NcMenuItem* items, size_t n, int hi, const char* title, void* ctx);
+void ui_draw_menu(WINDOW* win, const NcMenuItem* items, size_t n, int hi, int* top_io, const char* title, void* ctx);
 void ui_overlay_layout(UiMenuFrame* f, void* ctx);
 void ui_overlay_ensure_window(UiMenuFrame* f);
 void ui_overlay_recreate_if_needed(UiMenuFrame* f);