@aliou/pi-utils-settings 0.2.0 → 0.3.0

package/README.md

@@ -134,6 +134,7 @@ interface ConfigStore<TConfig, TResolved> {
 
 - **SectionedSettings**: Grouped settings list with search filtering and cursor preservation on update.
 - **ArrayEditor**: String array editor with add/remove/reorder.
+- **PathArrayEditor**: Path-focused array editor with Tab completion in add/edit mode.
 
 ### Helpers
 
@@ -148,5 +149,6 @@ export { ConfigLoader, type ConfigStore, type Migration } from "./config-loader"
 export { registerSettingsCommand, type SettingsCommandOptions } from "./settings-command";
 export { SectionedSettings, type SectionedSettingsOptions, type SettingsSection } from "./components/sectioned-settings";
 export { ArrayEditor, type ArrayEditorOptions } from "./components/array-editor";
+export { PathArrayEditor, type PathArrayEditorOptions } from "./components/path-array-editor";
 export { setNestedValue, getNestedValue, displayToStorageValue } from "./helpers";
 ```

package/components/fuzzy-selector.ts

@@ -0,0 +1,176 @@
+import type { Component, SettingsListTheme } from "@mariozechner/pi-tui";
+import {
+  fuzzyFilter,
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+
+/**
+ * A submenu component for selecting one item from a large list using fuzzy search.
+ *
+ * Features:
+ * - Type to filter items via fuzzy search
+ * - Navigate with up/down arrows
+ * - Enter to select
+ * - Esc to cancel
+ * - Shows highlighted item clearly
+ * - Scrolls when items exceed maxVisible
+ */
+
+export interface FuzzySelectorOptions {
+  label: string;
+  items: string[];
+  currentValue?: string; // pre-select this item if present
+  theme: SettingsListTheme;
+  onSelect: (value: string) => void;
+  onDone: () => void;
+  maxVisible?: number; // default 10
+}
+
+export class FuzzySelector implements Component {
+  private allItems: string[];
+  private filteredItems: string[];
+  private label: string;
+  private theme: SettingsListTheme;
+  private onSelect: (value: string) => void;
+  private onDone: () => void;
+  private selectedIndex = 0;
+  private maxVisible: number;
+  private input: Input;
+  private query = "";
+
+  constructor(options: FuzzySelectorOptions) {
+    this.allItems = [...options.items];
+    this.filteredItems = [...this.allItems];
+    this.label = options.label;
+    this.theme = options.theme;
+    this.onSelect = options.onSelect;
+    this.onDone = options.onDone;
+    this.maxVisible = options.maxVisible ?? 10;
+    this.input = new Input();
+
+    // Pre-select currentValue if provided and exists in the list
+    if (options.currentValue) {
+      const index = this.allItems.indexOf(options.currentValue);
+      if (index !== -1) {
+        this.selectedIndex = index;
+      }
+    }
+
+    this.input.onSubmit = () => {
+      this.selectCurrent();
+    };
+    this.input.onEscape = () => {
+      this.onDone();
+    };
+  }
+
+  private selectCurrent() {
+    if (this.filteredItems.length === 0) return;
+    const selected = this.filteredItems[this.selectedIndex];
+    if (selected) {
+      this.onSelect(selected);
+    }
+  }
+
+  private updateFilter() {
+    this.query = this.input.getValue();
+    if (this.query.trim() === "") {
+      this.filteredItems = [...this.allItems];
+    } else {
+      this.filteredItems = fuzzyFilter(
+        this.allItems,
+        this.query,
+        (item) => item,
+      );
+    }
+    // Reset cursor to 0 when filtering
+    this.selectedIndex = 0;
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    // Header
+    lines.push(this.theme.label(` ${this.label}`, true));
+    lines.push("");
+
+    // Input field
+    lines.push(this.theme.hint("  Search:"));
+    lines.push(`  ${this.input.render(width - 4).join("")}`);
+    lines.push("");
+
+    // List of filtered items
+    if (this.filteredItems.length === 0) {
+      lines.push(this.theme.hint("  (no matches)"));
+    } else {
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(this.maxVisible / 2),
+          this.filteredItems.length - this.maxVisible,
+        ),
+      );
+      const endIndex = Math.min(
+        startIndex + this.maxVisible,
+        this.filteredItems.length,
+      );
+
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.filteredItems[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.theme.cursor : "  ";
+        const prefixWidth = visibleWidth(prefix);
+        const maxItemWidth = width - prefixWidth - 2;
+        const text = this.theme.value(
+          truncateToWidth(item, maxItemWidth, ""),
+          isSelected,
+        );
+        lines.push(prefix + text);
+      }
+
+      // Show count indicator when scrolling
+      if (startIndex > 0 || endIndex < this.filteredItems.length) {
+        lines.push(
+          this.theme.hint(
+            `  (${this.selectedIndex + 1}/${this.filteredItems.length})`,
+          ),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(this.theme.hint("  Type to search · Enter: select · Esc: back"));
+
+    return lines;
+  }
+
+  handleInput(data: string) {
+    // Navigation and selection
+    if (matchesKey(data, Key.up)) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.filteredItems.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down)) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.filteredItems.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (matchesKey(data, Key.escape)) {
+      this.onDone();
+    } else {
+      // Delegate to input handler
+      this.input.handleInput(data);
+      this.updateFilter();
+    }
+  }
+}

package/components/path-array-editor.ts

@@ -0,0 +1,447 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Component, SettingsListTheme } from "@mariozechner/pi-tui";
+import {
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+
+export interface PathArrayEditorOptions {
+  label: string;
+  items: string[];
+  theme: SettingsListTheme;
+  onSave: (items: string[]) => void;
+  onDone: () => void;
+  /** Max visible items before scrolling */
+  maxVisible?: number;
+  /** Base directory for resolving relative paths. Default: process.cwd() */
+  baseDir?: string;
+  /** Optional validation hook. Return error message to reject submit. */
+  validatePath?: (value: string) => string | null;
+}
+
+/**
+ * Array editor specialized for filesystem paths.
+ *
+ * Same UX as ArrayEditor, plus Tab completion in add/edit mode.
+ */
+export class PathArrayEditor implements Component {
+  private items: string[];
+  private label: string;
+  private theme: SettingsListTheme;
+  private onSave: (items: string[]) => void;
+  private onDone: () => void;
+  private selectedIndex = 0;
+  private maxVisible: number;
+  private mode: "list" | "add" | "edit" = "list";
+  private input: Input;
+  private editIndex = -1;
+  private baseDir: string;
+  private completions: string[] = [];
+  private completionIndex = 0;
+  private readonly validatePath?: (value: string) => string | null;
+  private inputError: string | null = null;
+
+  constructor(options: PathArrayEditorOptions) {
+    this.items = [...options.items];
+    this.label = options.label;
+    this.theme = options.theme;
+    this.onSave = options.onSave;
+    this.onDone = options.onDone;
+    this.maxVisible = options.maxVisible ?? 10;
+    this.baseDir = options.baseDir ?? process.cwd();
+    this.validatePath = options.validatePath;
+    this.input = new Input();
+    this.input.onSubmit = (value: string) => {
+      if (this.mode === "edit") {
+        this.submitEdit(value);
+      } else {
+        this.submitAdd(value);
+      }
+    };
+    this.input.onEscape = () => {
+      this.mode = "list";
+      this.editIndex = -1;
+      this.completions = [];
+      this.completionIndex = 0;
+      this.inputError = null;
+    };
+  }
+
+  private submitAdd(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      this.mode = "list";
+      return;
+    }
+
+    const validationError = this.validatePath?.(trimmed) ?? null;
+    if (validationError) {
+      this.inputError = validationError;
+      return;
+    }
+
+    this.items.push(trimmed);
+    this.selectedIndex = this.items.length - 1;
+    this.save();
+    this.mode = "list";
+    this.input.setValue("");
+    this.completions = [];
+    this.completionIndex = 0;
+    this.inputError = null;
+  }
+
+  private submitEdit(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      this.mode = "list";
+      this.editIndex = -1;
+      return;
+    }
+
+    const validationError = this.validatePath?.(trimmed) ?? null;
+    if (validationError) {
+      this.inputError = validationError;
+      return;
+    }
+
+    this.items[this.editIndex] = trimmed;
+    this.save();
+    this.mode = "list";
+    this.editIndex = -1;
+    this.input.setValue("");
+    this.completions = [];
+    this.completionIndex = 0;
+    this.inputError = null;
+  }
+
+  private deleteSelected() {
+    if (this.items.length === 0) return;
+    this.items.splice(this.selectedIndex, 1);
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+    this.save();
+  }
+
+  private startEdit() {
+    if (this.items.length === 0) return;
+    this.editIndex = this.selectedIndex;
+    this.mode = "edit";
+    this.setInputValueAtEnd(this.items[this.selectedIndex] as string);
+    this.completions = [];
+    this.completionIndex = 0;
+  }
+
+  private save() {
+    this.onSave([...this.items]);
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    lines.push(this.theme.label(` ${this.label}`, true));
+    lines.push("");
+
+    if (this.mode === "add" || this.mode === "edit") {
+      return [...lines, ...this.renderInputMode(width)];
+    }
+
+    return [...lines, ...this.renderListMode(width)];
+  }
+
+  private renderListMode(width: number): string[] {
+    const lines: string[] = [];
+
+    if (this.items.length === 0) {
+      lines.push(this.theme.hint("  (empty)"));
+    } else {
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(this.maxVisible / 2),
+          this.items.length - this.maxVisible,
+        ),
+      );
+      const endIndex = Math.min(
+        startIndex + this.maxVisible,
+        this.items.length,
+      );
+
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.items[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.theme.cursor : "  ";
+        const prefixWidth = visibleWidth(prefix);
+        const maxItemWidth = width - prefixWidth - 2;
+        const text = this.theme.value(
+          truncateToWidth(item, maxItemWidth, ""),
+          isSelected,
+        );
+        lines.push(prefix + text);
+      }
+
+      if (startIndex > 0 || endIndex < this.items.length) {
+        lines.push(
+          this.theme.hint(`  (${this.selectedIndex + 1}/${this.items.length})`),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(
+      this.theme.hint("  a: add · e/Enter: edit · d: delete · Esc: back"),
+    );
+
+    return lines;
+  }
+
+  private renderInputMode(width: number): string[] {
+    const lines: string[] = [];
+    const label = this.mode === "edit" ? "  Edit path:" : "  New path:";
+    lines.push(this.theme.hint(label));
+    lines.push(`  ${this.input.render(width - 4).join("")}`);
+
+    if (this.completions.length > 0) {
+      lines.push("");
+      lines.push(this.theme.hint("  Suggestions:"));
+      const start = Math.max(
+        0,
+        Math.min(this.completionIndex - 2, this.completions.length - 5),
+      );
+      const end = Math.min(this.completions.length, start + 5);
+      for (let i = start; i < end; i++) {
+        const completion = this.completions[i];
+        if (!completion) continue;
+        const isSelected = i === this.completionIndex;
+        const prefix = isSelected ? this.theme.cursor : "    ";
+        const text = isSelected
+          ? this.theme.value(completion, true)
+          : this.theme.hint(completion);
+        lines.push(`${prefix}${text}`);
+      }
+      if (this.completions.length > 5) {
+        lines.push(
+          this.theme.hint(
+            `    (${this.completionIndex + 1}/${this.completions.length})`,
+          ),
+        );
+      }
+    }
+
+    if (this.inputError) {
+      lines.push("");
+      lines.push(this.theme.value(`  ${this.inputError}`, true));
+    }
+
+    lines.push("");
+    lines.push(
+      this.theme.hint(
+        "  Tab: complete/apply · ↑/↓: select suggestion · Enter: confirm · Esc: cancel",
+      ),
+    );
+    return lines;
+  }
+
+  handleInput(data: string) {
+    if (this.mode === "add" || this.mode === "edit") {
+      if (matchesKey(data, Key.up) && this.completions.length > 0) {
+        this.completionIndex =
+          this.completionIndex === 0
+            ? this.completions.length - 1
+            : this.completionIndex - 1;
+        return;
+      }
+      if (matchesKey(data, Key.down) && this.completions.length > 0) {
+        this.completionIndex =
+          this.completionIndex === this.completions.length - 1
+            ? 0
+            : this.completionIndex + 1;
+        return;
+      }
+      if (matchesKey(data, Key.tab)) {
+        if (this.completions.length > 0) {
+          this.applySelectedCompletion();
+        } else {
+          this.completeInputPath();
+        }
+        return;
+      }
+      if (matchesKey(data, Key.enter)) {
+        // Keep Enter for submit/confirm. Use Tab to apply suggestions.
+        this.input.handleInput(data);
+        return;
+      }
+      this.input.handleInput(data);
+      this.completions = [];
+      this.completionIndex = 0;
+      this.inputError = null;
+      return;
+    }
+
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.items.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (data === "a" || data === "A") {
+      this.mode = "add";
+      this.input.setValue("");
+      this.completions = [];
+      this.completionIndex = 0;
+    } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
+      this.startEdit();
+    } else if (data === "d" || data === "D") {
+      this.deleteSelected();
+    } else if (matchesKey(data, Key.escape)) {
+      this.onDone();
+    }
+  }
+
+  private completeInputPath(): void {
+    const raw = this.input.getValue();
+    const completed = this.getCompletion(raw);
+    if (!completed) return;
+    this.setInputValueAtEnd(completed.nextValue);
+    this.completions = completed.suggestions;
+    this.completionIndex = 0;
+  }
+
+  private applySelectedCompletion(): void {
+    const selected = this.completions[this.completionIndex];
+    if (!selected) return;
+
+    const raw = this.input.getValue().trim();
+    const rawEndsWithSep = raw.endsWith("/") || raw.endsWith(path.sep);
+    const rawDirPart = rawEndsWithSep ? raw : path.dirname(raw);
+    const separator = rawDirPart === "." ? "" : rawDirPart;
+    const joiner = separator && !separator.endsWith("/") ? "/" : "";
+
+    const nextValue = `${separator}${joiner}${selected}`;
+
+    // Prevent duplicate appends when user tabs repeatedly on same completion.
+    if (nextValue === raw || raw.endsWith(selected)) {
+      this.completions = [];
+      this.completionIndex = 0;
+      return;
+    }
+
+    this.setInputValueAtEnd(nextValue);
+    this.completions = [];
+    this.completionIndex = 0;
+  }
+
+  private setInputValueAtEnd(value: string): void {
+    this.input.setValue(value);
+    // Input has no public setCursor API. Emulate End (Ctrl+E) so follow-up
+    // typing/tab completion continues from end of line.
+    this.input.handleInput("\u0005");
+  }
+
+  private getCompletion(inputValue: string): {
+    nextValue: string;
+    suggestions: string[];
+  } | null {
+    const raw = inputValue.trim();
+    if (!raw) return null;
+
+    const rawEndsWithSep = raw.endsWith("/") || raw.endsWith(path.sep);
+    const rawDirPart = rawEndsWithSep ? raw : path.dirname(raw);
+    const rawPrefix = rawEndsWithSep ? "" : path.basename(raw);
+
+    const absDir = this.resolveAbsolutePath(
+      rawDirPart === "." ? "" : rawDirPart,
+      this.baseDir,
+    );
+
+    let names: string[];
+    try {
+      names = fs.readdirSync(absDir);
+    } catch {
+      return null;
+    }
+
+    const matched = names
+      .filter((name) => name.startsWith(rawPrefix))
+      .sort((a, b) => a.localeCompare(b));
+
+    if (matched.length === 0) return null;
+
+    const suggestions = matched.map((name) => {
+      const candidateAbs = path.join(absDir, name);
+      const isDir = this.isDirectory(candidateAbs);
+      return `${name}${isDir ? "/" : ""}`;
+    });
+
+    const nextName =
+      matched.length === 1
+        ? matched[0]
+        : this.commonPrefix(matched) || rawPrefix;
+
+    if (!nextName || nextName === rawPrefix) {
+      return { nextValue: raw, suggestions };
+    }
+
+    const nextAbs = path.join(absDir, nextName);
+    const nextIsDir = this.isDirectory(nextAbs);
+    const separator = rawDirPart === "." ? "" : rawDirPart;
+    const joiner = separator && !separator.endsWith("/") ? "/" : "";
+    const nextValue = `${separator}${joiner}${nextName}${nextIsDir ? "/" : ""}`;
+
+    return { nextValue, suggestions };
+  }
+
+  private resolveAbsolutePath(rawPath: string, baseDir: string): string {
+    if (rawPath.startsWith("~/")) {
+      return path.resolve(os.homedir(), rawPath.slice(2));
+    }
+    if (rawPath === "~") {
+      return os.homedir();
+    }
+    if (path.isAbsolute(rawPath)) {
+      return path.normalize(rawPath);
+    }
+    return path.resolve(baseDir, rawPath || ".");
+  }
+
+  private isDirectory(filePath: string): boolean {
+    try {
+      return fs.statSync(filePath).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  private commonPrefix(values: string[]): string {
+    if (values.length === 0) return "";
+    let prefix = values[0] as string;
+    for (let i = 1; i < values.length; i++) {
+      const current = values[i] as string;
+      let j = 0;
+      while (
+        j < prefix.length &&
+        j < current.length &&
+        prefix[j] === current[j]
+      ) {
+        j++;
+      }
+      prefix = prefix.slice(0, j);
+      if (!prefix) break;
+    }
+    return prefix;
+  }
+}

package/components/sectioned-settings.ts

@@ -328,6 +328,9 @@ export class SectionedSettings implements Component {
   /**
    * Apply search filter to entries without resetting the cursor.
    * Used by updateSections() to preserve selection.
+   *
+   * Matches on both item labels and section labels. When a section label
+   * matches, all items in that section are included.
    */
   private filterEntries(query: string): void {
     if (!query) {
@@ -335,29 +338,49 @@ export class SectionedSettings implements Component {
       return;
     }
 
+    const q = query.toLowerCase();
     const filtered: FlatEntry[] = [];
     let currentSection: FlatEntry | null = null;
+    let sectionLabelMatches = false;
     let sectionHasMatch = false;
+    let sectionItems: FlatEntry[] = [];
+
+    const flushSection = () => {
+      if (sectionLabelMatches && currentSection) {
+        // Section label matched: include header + all items
+        filtered.push(currentSection);
+        filtered.push(...sectionItems);
+      } else if (sectionHasMatch && currentSection) {
+        // Only some items matched: include header + matched items
+        filtered.push(currentSection);
+        for (const item of sectionItems) {
+          if (item.item?.label.toLowerCase().includes(q)) {
+            filtered.push(item);
+          }
+        }
+      }
+    };
 
     for (const entry of this.flatEntries) {
       if (entry.type === "section") {
+        flushSection();
         currentSection = entry;
-        sectionHasMatch = false;
+        sectionLabelMatches = (entry.sectionLabel ?? "")
+          .toLowerCase()
+          .includes(q);
+        sectionHasMatch = sectionLabelMatches;
+        sectionItems = [];
         continue;
       }
 
       if (entry.item) {
-        const label = entry.item.label.toLowerCase();
-        const q = query.toLowerCase();
-        if (label.includes(q)) {
-          if (currentSection && !sectionHasMatch) {
-            filtered.push(currentSection);
-            sectionHasMatch = true;
-          }
-          filtered.push(entry);
+        sectionItems.push(entry);
+        if (entry.item.label.toLowerCase().includes(q)) {
+          sectionHasMatch = true;
         }
       }
     }
+    flushSection();
 
     this.filteredEntries = filtered;
   }

package/index.ts

@@ -13,6 +13,14 @@ export {
   ArrayEditor,
   type ArrayEditorOptions,
 } from "./components/array-editor";
+export {
+  FuzzySelector,
+  type FuzzySelectorOptions,
+} from "./components/fuzzy-selector";
+export {
+  PathArrayEditor,
+  type PathArrayEditorOptions,
+} from "./components/path-array-editor";
 export {
   SectionedSettings,
   type SectionedSettingsOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-utils-settings",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -24,4 +24,4 @@
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.51.0"
   }
-}
+}

package/settings-command.ts

@@ -230,7 +230,7 @@ export function registerSettingsCommand<
 
           // Store in draft, don't write to disk yet.
           drafts[scope] = updated;
-          tui.requestRender();
+          refresh();
         }
 
         // --- Save handler (Ctrl+S) ---