@pellux/goodvibes-tui 0.27.0 → 0.29.0

package/src/panels/scrollable-list-panel.ts

@@ -5,6 +5,7 @@ import type { PanelCategory } from './types.ts';
 import type { ComponentHealthMonitor } from '../runtime/perf/panel-health-monitor.ts';
 import {
   buildEmptyState,
+  buildKeyboardHints,
   buildPanelWorkspace,
   buildSearchInputLine,
   DEFAULT_PANEL_PALETTE,
@@ -12,11 +13,6 @@ import {
   type PanelPalette,
 } from './polish.ts';
 import { GLYPHS } from '../renderer/ui-primitives.ts';
-import {
-  isPanelSearchBackspace,
-  isPanelSearchCancel,
-  isPanelSearchPrintable,
-} from './search-focus.ts';
 
 // ---------------------------------------------------------------------------
 // ScrollableListPanel<T>
@@ -56,6 +52,115 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
    */
   protected showSelectionGutter = false;
 
+  // -------------------------------------------------------------------------
+  // Opt-in inline filter ( / to filter, Esc to clear )
+  // -------------------------------------------------------------------------
+  // Set `filterEnabled = true` and override `filterMatches()` to give a list
+  // panel a `/`-to-filter affordance that coexists with single-letter action
+  // keys (filtering is modal: action keys work until you press `/`). A filter
+  // input line is auto-rendered at the top of the list.
+  protected filterEnabled = false;
+  protected filterQuery = '';
+  protected filterActive = false;
+  /** Short noun shown in the filter hint, e.g. "Filter sessions". */
+  protected filterLabel = 'Filter';
+
+  /** Override to define what the lower-cased filter query matches for an item. */
+  protected filterMatches(_item: T, _query: string): boolean {
+    return false;
+  }
+
+  /**
+   * The list after applying the active filter — used for both display and
+   * navigation. Identical to `getItems()` unless a filter is enabled and a
+   * non-empty query is set, so existing panels are unaffected.
+   */
+  protected getVisibleItems(): readonly T[] {
+    const all = this.getItems();
+    const q = this.filterQuery.trim().toLowerCase();
+    if (!this.filterEnabled || !q) return all;
+    return all.filter((item) => this.filterMatches(item, q));
+  }
+
+  /**
+   * The item currently under the cursor, resolved against the FILTERED list
+   * that navigation actually moves over (`getVisibleItems()`) — never the raw
+   * `getItems()` source.
+   *
+   * Subclasses MUST read the selected row through this method (or, when a
+   * function also needs the list for counts/windows, through a function-scope
+   * `const visible = this.getVisibleItems()` local — indexing that local, never
+   * the raw source). Indexing a raw item array (`this.rows`, `this.entries`,
+   * `getItems()`, …) with `this.selectedIndex` silently returns the wrong row
+   * whenever a filter is active, because `selectedIndex` is an offset into the
+   * visible list, not the raw one. The `no-raw-selectedindex-read` architecture
+   * rule enforces this by banning the `[this.selectedIndex]` token outside the
+   * base classes.
+   */
+  protected getSelectedItem(): T | undefined {
+    return this.getVisibleItems()[this.selectedIndex];
+  }
+
+  /**
+   * Filter-mode key handling. Returns `true`/`false` when consumed/ignored in
+   * filter context, or `null` to fall through to normal navigation.
+   */
+  private _handleFilterKey(key: string): boolean | null {
+    if (!this.filterEnabled) return null;
+    if (this.filterActive) {
+      if (key === 'escape') {
+        this.filterActive = false;
+        this.filterQuery = '';
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      if (key === 'return' || key === 'enter') {
+        this.filterActive = false; // commit; keep the query applied
+        this.needsRender = true;
+        return true;
+      }
+      if (key === 'backspace' || key === 'delete') {
+        this.filterQuery = this.filterQuery.slice(0, -1);
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      // Arrow/paging keys navigate the filtered list — fall through.
+      if (key === 'up' || key === 'down' || key === 'pageup' || key === 'pagedown' || key === 'home' || key === 'end') {
+        return null;
+      }
+      // Any printable character (including j/k/g/G) extends the query.
+      if (key.length === 1 && key >= ' ') {
+        this.filterQuery += key;
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      return false;
+    }
+    if (key === '/') {
+      this.filterActive = true;
+      this.needsRender = true;
+      return true;
+    }
+    return null;
+  }
+
+  /** The filter input line shown at the top of the list when filtering is enabled. */
+  protected buildFilterLine(width: number): Line {
+    const palette = this.getPalette();
+    const label = this.filterActive ? `[${this.filterLabel}] ` : `${this.filterLabel}: `;
+    const value = this.filterActive
+      ? `${this.filterQuery}_`
+      : this.filterQuery || '(/ to filter)';
+    return buildSearchInputLine(width, label, value, palette, {
+      active: false,
+      bg: this.filterActive ? palette.inputBg : palette.sectionBg,
+      valueColor: this.filterActive ? palette.info : (this.filterQuery ? palette.value : palette.dim),
+    });
+  }
+
   constructor(
     id: string,
     name: string,
@@ -143,7 +248,11 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     // call this.clearError() at the start of their handler.
     if (this.lastError !== null) this.clearError();
 
-    const items = this.getItems();
+    // Opt-in inline filter consumes input before navigation when active.
+    const filterResult = this._handleFilterKey(key);
+    if (filterResult !== null) return filterResult;
+
+    const items = this.getVisibleItems();
     const total = items.length;
 
     switch (key) {
@@ -202,7 +311,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
 
   handleScroll(deltaRows: number): boolean {
     if (this.lastError !== null) this.clearError();
-    const total = this.getItems().length;
+    const total = this.getVisibleItems().length;
     const rows = Math.trunc(deltaRows);
     if (total === 0 || rows === 0) return false;
     const next = Math.max(0, Math.min(total - 1, this.selectedIndex + rows));
@@ -221,7 +330,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
    * Must be called after any data refresh that may shrink the list.
    */
   protected clampSelection(): void {
-    const total = this.getItems().length;
+    const total = this.getVisibleItems().length;
     if (total === 0) {
       this.selectedIndex = 0;
     } else {
@@ -253,6 +362,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     options: {
       readonly header?: readonly Line[];
       readonly footer?: readonly Line[];
+      readonly hints?: ReadonlyArray<{ keys: string; label: string }>;
       readonly emptyMessage?: string;
       readonly title?: string;
       readonly spinnerFrame?: number;
@@ -260,19 +370,32 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
   ): Line[] {
     this.needsRender = false;
     const palette = this.getPalette();
-    const items = this.getItems();
+    const items = this.getVisibleItems();
     const title = options.title ?? this.name;
 
+    // Auto-inject the filter input line at the top of the header when filtering
+    // is enabled, so every filterable panel gets the same affordance for free.
+    const baseHeader = options.header ? [...options.header as Line[]] : [];
+    const header: Line[] | undefined = this.filterEnabled
+      ? [this.buildFilterLine(width), ...baseHeader]
+      : (options.header ? baseHeader : undefined);
+
+    // Standardized keyboard-hints footer row (rendered below any explicit footer).
+    const hintsLine = options.hints && options.hints.length > 0
+      ? buildKeyboardHints(width, options.hints, palette)
+      : null;
+
     // I2: inject error line into footer when present
     const errorLine = this.renderErrorLine(width);
     const baseFooter = options.footer ? [...options.footer as Line[]] : [];
+    if (hintsLine) baseFooter.push(hintsLine);
     const effectiveFooter: Line[] = errorLine ? [errorLine, ...baseFooter] : baseFooter;
 
     // I3: if loading, show spinner in place of normal content
     const spinnerLine = this.renderLoadingLine(width, options.spinnerFrame ?? 0);
     if (spinnerLine) {
       const loadingSection = { lines: [spinnerLine] };
-      const headerSection = options.header ? [{ lines: options.header as Line[] }] : [];
+      const headerSection = header ? [{ lines: header }] : [];
       const lines = buildPanelWorkspace(width, height, {
         title,
         sections: [...headerSection, loadingSection],
@@ -306,17 +429,22 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
 
     // Empty state
     if (scrollableLines.length === 0) {
+      // Distinguish "filter hides everything" from "genuinely empty".
+      const filteredToEmpty = this.filterEnabled && this.filterQuery.trim() !== '' && this.getItems().length > 0;
+      const emptyMessage = filteredToEmpty
+        ? ` No matches for "${this.filterQuery.trim()}"`
+        : (options.emptyMessage ?? this.getEmptyStateMessage());
       const emptyLines = buildEmptyState(
         width,
-        options.emptyMessage ?? this.getEmptyStateMessage(),
-        '',
-        this.getEmptyStateActions(),
+        emptyMessage,
+        filteredToEmpty ? 'Press Esc to clear the filter.' : '',
+        filteredToEmpty ? [] : this.getEmptyStateActions(),
         palette,
       );
       const lines = buildPanelWorkspace(width, height, {
         title,
         sections: [
-          ...(options.header ? [{ lines: options.header as Line[] }] : []),
+          ...(header ? [{ lines: header }] : []),
           { lines: emptyLines },
           ...(effectiveFooter.length > 0 ? [{ lines: effectiveFooter }] : []),
         ],
@@ -327,7 +455,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     }
 
     // Resolve scrollable section (updates scrollStart)
-    const beforeSections = options.header ? [{ lines: options.header as Line[] }] : [];
+    const beforeSections = header ? [{ lines: header }] : [];
     const afterSections = effectiveFooter.length > 0 ? [{ lines: effectiveFooter }] : [];
 
     const resolved = resolveScrollablePanelSection(width, height, {
@@ -359,133 +487,3 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     return lines.slice(0, height);
   }
 }
-
-// ---------------------------------------------------------------------------
-// SearchableListPanel<T>
-// ---------------------------------------------------------------------------
-
-/**
- * Extends `ScrollableListPanel<T>` with inline search/filter support.
- *
- * Subclasses implement:
- *   - `getAllItems()` — the full (unfiltered) item list
- *   - `matchesSearch(item, query)` — case-insensitive filter predicate
- *
- * `getItems()` is implemented here and returns filtered results. Do NOT
- * override `getItems()` in subclasses — override `getAllItems()` instead.
- *
- * Search state:
- *   - Printable characters append to `searchQuery`.
- *   - Backspace/Delete removes the last character.
- *   - Escape clears the query.
- *   - Navigation keys (up/down/etc.) are forwarded to the parent.
- *
- * Render the search input line by calling `buildSearchInput(width)` from
- * your panel's header builder.
- */
-export abstract class SearchableListPanel<T> extends ScrollableListPanel<T> {
-  protected searchQuery = '';
-
-  private _filteredItems: readonly T[] = [];
-  private _filterDirty = true;
-
-  // -------------------------------------------------------------------------
-  // Abstract — subclasses must implement
-  // -------------------------------------------------------------------------
-
-  /** Return the full unfiltered item list. */
-  protected abstract getAllItems(): readonly T[];
-
-  /** Return true if `item` matches the search `query`. */
-  protected abstract matchesSearch(item: T, query: string): boolean;
-
-  // -------------------------------------------------------------------------
-  // getItems — returns filtered list (do NOT override in subclasses)
-  // -------------------------------------------------------------------------
-
-  protected getItems(): readonly T[] {
-    if (this._filterDirty) {
-      const all = this.getAllItems();
-      this._filteredItems = this.searchQuery
-        ? all.filter((item) => this.matchesSearch(item, this.searchQuery))
-        : all;
-      this._filterDirty = false;
-      // Clamp after filter to keep selection in bounds
-      this.clampSelection();
-    }
-    return this._filteredItems;
-  }
-
-  /**
-   * Mark the filter cache as stale.
-   * Call this whenever `getAllItems()` returns new data.
-   */
-  protected invalidateFilter(): void {
-    this._filterDirty = true;
-    this.needsRender = true;
-  }
-
-  // -------------------------------------------------------------------------
-  // Input — search first, navigation second
-  // -------------------------------------------------------------------------
-
-  handleInput(key: string): boolean {
-    // Backspace: trim query
-    if (isPanelSearchBackspace(key)) {
-      if (this.searchQuery.length > 0) {
-        this.searchQuery = this.searchQuery.slice(0, -1);
-        this._filterDirty = true;
-        this.needsRender = true;
-        return true;
-      }
-      return false;
-    }
-
-    // Escape: clear query
-    if (isPanelSearchCancel(key)) {
-      if (this.searchQuery.length > 0) {
-        this.searchQuery = '';
-        this._filterDirty = true;
-        this.needsRender = true;
-        return true;
-      }
-      return false;
-    }
-
-    // Printable characters: append to query
-    if (isPanelSearchPrintable(key)) {
-      this.searchQuery += key;
-      this._filterDirty = true;
-      this.needsRender = true;
-      return true;
-    }
-
-    // Navigation and Enter: delegate to parent
-    return super.handleInput(key);
-  }
-
-  /**
-   * Build the filter input `Line` for use in a panel header section.
-   *
-   * Renders the filter label and current query with context-sensitive formatting:
-   *
-   * - **Focused** (`focused = true`): `[Filter] query_`  — active, bold, cursor visible
-   * - **Unfocused** (`focused = false`): `Filter: query`  — dim, no cursor
-   *
-   * @param width   Panel width in columns.
-   * @param label   Label text (default: `'Filter'`).
-   * @param focused Whether the filter input is currently active.
-   */
-  protected buildFilterInputLine(width: number, label = 'Filter', focused: boolean): Line {
-    const palette = this.getPalette();
-    const formattedLabel = focused ? `[${label}] ` : `${label}: `;
-    const value = focused ? `${this.searchQuery}_` : this.searchQuery;
-    // Pass active:false when focused to prevent buildSearchInputLine from converting the
-    // trailing '_' cursor to the block-glyph (GLYPHS.surface.cursor). The focused visual
-    // affordance is provided by the '[Label] ' bracket format and explicit inputBg/info colors.
-    const opts = focused
-      ? { active: false, bg: palette.inputBg, valueColor: palette.info }
-      : { active: false };
-    return buildSearchInputLine(width, formattedLabel, value, palette, opts);
-  }
-}