@aliou/pi-utils-settings 0.3.0 → 0.5.0

package/components/fuzzy-selector.ts

@@ -165,6 +165,8 @@ export class FuzzySelector implements Component {
         this.selectedIndex === this.filteredItems.length - 1
           ? 0
           : this.selectedIndex + 1;
+    } else if (matchesKey(data, Key.enter)) {
+      this.selectCurrent();
     } else if (matchesKey(data, Key.escape)) {
       this.onDone();
     } else {

package/components/sectioned-settings.ts

@@ -27,6 +27,8 @@ export interface SectionedSettingsOptions {
   enableSearch?: boolean;
   /** Extra text appended to the hint line (e.g. "Ctrl+S to save"). */
   hintSuffix?: string;
+  /** Hide the built-in hint line (when the parent renders its own controls). */
+  hideHint?: boolean;
 }
 
 interface FlatEntry {
@@ -47,6 +49,7 @@ export class SectionedSettings implements Component {
   private searchInput?: Input;
   private searchEnabled: boolean;
   private hintSuffix: string;
+  private hideHint: boolean;
   private submenuComponent: Component | null = null;
   private submenuItemIndex: number | null = null;
 
@@ -65,6 +68,7 @@ export class SectionedSettings implements Component {
     this.onCancel = onCancel;
     this.searchEnabled = options.enableSearch ?? false;
     this.hintSuffix = options.hintSuffix ?? "";
+    this.hideHint = options.hideHint ?? false;
     this.selectedIndex = 0;
 
     if (this.searchEnabled) {
@@ -259,7 +263,9 @@ export class SectionedSettings implements Component {
       }
     }
 
-    this.addHintLine(lines);
+    if (!this.hideHint) {
+      this.addHintLine(lines);
+    }
     return lines;
   }
 

package/components/wizard.ts

@@ -0,0 +1,254 @@
+/**
+ * A multi-step wizard component with tabbed navigation and bordered frame.
+ *
+ * Features:
+ * - Box-drawing border around the entire wizard (╭╮╰╯ style)
+ * - Step tabs at the top with progress indicators (●/○)
+ * - Tab/Shift+Tab navigation between steps
+ * - Each step renders its own inner Component
+ * - Ctrl+S or Enter on the last step submits
+ * - Esc cancels the entire wizard
+ *
+ * Use for first-time setup flows, multi-step configuration, or any
+ * sequential data collection that benefits from back-and-forth navigation.
+ */
+
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+
+export interface WizardStep {
+  /** Tab label shown at the top. Keep it short (1-2 words). */
+  label: string;
+  /**
+   * Build the inner component for this step.
+   *
+   * The component controls its own rendering and input handling.
+   * Call `markComplete()` to mark the step as done (shows ● in tabs).
+   * Call `markIncomplete()` to revert it (shows ○).
+   *
+   * The wizard handles borders, tabs, and step navigation externally.
+   * The inner component should NOT handle Tab/Shift+Tab/Esc/Ctrl+S.
+   */
+  build: (ctx: WizardStepContext) => Component;
+}
+
+export interface WizardStepContext {
+  /** Mark this step as complete (filled ● in progress). */
+  markComplete: () => void;
+  /** Mark this step as incomplete (empty ○ in progress). */
+  markIncomplete: () => void;
+  /** Advance to the next step (wraps around). */
+  goNext: () => void;
+  /** Go back to the previous step (wraps around). */
+  goPrev: () => void;
+}
+
+export interface WizardOptions {
+  /** Title shown at the top of the wizard. */
+  title: string;
+  /** Ordered list of steps. */
+  steps: WizardStep[];
+  /** Theme for rendering borders and chrome. */
+  theme: Theme;
+  /** Called when user submits (Ctrl+S). */
+  onComplete: () => void;
+  /** Called when user cancels (Esc). */
+  onCancel: () => void;
+  /** Hint text appended to the controls line. */
+  hintSuffix?: string;
+}
+
+export class Wizard implements Component {
+  private steps: WizardStep[];
+  private theme: Theme;
+  private onComplete: () => void;
+  private onCancel: () => void;
+  private title: string;
+  private hintSuffix: string;
+
+  private activeIndex = 0;
+  private completed: boolean[];
+  private components: Component[];
+
+  constructor(options: WizardOptions) {
+    this.steps = options.steps;
+    this.theme = options.theme;
+    this.onComplete = options.onComplete;
+    this.onCancel = options.onCancel;
+    this.title = options.title;
+    this.hintSuffix = options.hintSuffix ?? "";
+
+    this.completed = new Array(options.steps.length).fill(false) as boolean[];
+    this.components = options.steps.map((step, i) =>
+      step.build({
+        markComplete: () => {
+          this.completed[i] = true;
+        },
+        markIncomplete: () => {
+          this.completed[i] = false;
+        },
+        goNext: () => {
+          this.activeIndex = (this.activeIndex + 1) % this.steps.length;
+        },
+        goPrev: () => {
+          this.activeIndex =
+            (this.activeIndex - 1 + this.steps.length) % this.steps.length;
+        },
+      }),
+    );
+  }
+
+  /** Returns the index of the currently active step. */
+  getActiveIndex(): number {
+    return this.activeIndex;
+  }
+
+  /** Returns whether all steps are marked complete. */
+  isAllComplete(): boolean {
+    return this.completed.every(Boolean);
+  }
+
+  invalidate(): void {
+    for (const component of this.components) {
+      component.invalidate?.();
+    }
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    const t = this.theme;
+    const contentWidth = Math.max(1, width - 2);
+
+    // --- Top border with title ---
+    const titleText = ` ${this.title} `;
+    const titleLen = visibleWidth(titleText);
+    const topRuleLen = Math.max(1, width - titleLen - 3);
+    lines.push(
+      t.fg("border", "╭─") +
+        t.fg("accent", t.bold(titleText)) +
+        t.fg("border", "─".repeat(topRuleLen)) +
+        t.fg("border", "╮"),
+    );
+
+    // --- Step tabs with progress ---
+    const tabLine = this.renderStepTabs(contentWidth);
+    lines.push(this.padLine(tabLine, contentWidth));
+    lines.push(this.padLine("", contentWidth));
+
+    // --- Inner component ---
+    const innerComponent = this.components[this.activeIndex];
+    if (innerComponent) {
+      const innerLines = innerComponent.render(contentWidth);
+      for (const line of innerLines) {
+        lines.push(this.padLine(line, contentWidth));
+      }
+    }
+
+    // --- Separator ---
+    lines.push(
+      t.fg("border", "├") +
+        t.fg("border", "─".repeat(contentWidth)) +
+        t.fg("border", "┤"),
+    );
+
+    // --- Controls ---
+    const controlsText = this.buildControlsText();
+    lines.push(this.padLine(controlsText, contentWidth));
+
+    // --- Bottom border ---
+    lines.push(
+      t.fg("border", "╰") +
+        t.fg("border", "─".repeat(contentWidth)) +
+        t.fg("border", "╯"),
+    );
+
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    // Ctrl+S: submit if all steps complete
+    if (matchesKey(data, Key.ctrl("s"))) {
+      this.onComplete();
+      return;
+    }
+
+    // Esc: cancel
+    if (matchesKey(data, Key.escape)) {
+      this.onCancel();
+      return;
+    }
+
+    // Tab / Shift+Tab: navigate steps
+    if (matchesKey(data, Key.tab)) {
+      this.activeIndex = (this.activeIndex + 1) % this.steps.length;
+      return;
+    }
+    if (matchesKey(data, Key.shift("tab"))) {
+      this.activeIndex =
+        (this.activeIndex - 1 + this.steps.length) % this.steps.length;
+      return;
+    }
+
+    // Delegate to inner component
+    const innerComponent = this.components[this.activeIndex];
+    innerComponent?.handleInput?.(data);
+  }
+
+  // --- Private rendering helpers ---
+
+  private renderStepTabs(_contentWidth: number): string {
+    const t = this.theme;
+    const parts: string[] = [];
+
+    for (let i = 0; i < this.steps.length; i++) {
+      const step = this.steps[i];
+      if (!step) continue;
+
+      const dot = this.completed[i]
+        ? t.fg("success", "●")
+        : i === this.activeIndex
+          ? t.fg("accent", "●")
+          : t.fg("dim", "○");
+
+      const label =
+        i === this.activeIndex
+          ? t.bg("selectedBg", t.fg("accent", ` ${step.label} `))
+          : t.fg("dim", ` ${step.label} `);
+
+      parts.push(`${dot} ${label}`);
+    }
+
+    return parts.join("  ");
+  }
+
+  private padLine(content: string, contentWidth: number): string {
+    const t = this.theme;
+    const len = visibleWidth(content);
+    const padding = Math.max(0, contentWidth - len);
+    return (
+      t.fg("border", "│") +
+      truncateToWidth(content, contentWidth) +
+      " ".repeat(padding) +
+      t.fg("border", "│")
+    );
+  }
+
+  private buildControlsText(): string {
+    const t = this.theme;
+    const parts: string[] = [
+      "Tab/Shift+Tab navigate",
+      "Ctrl+S submit",
+      "Esc cancel",
+    ];
+    if (this.hintSuffix) {
+      parts.push(this.hintSuffix);
+    }
+    return t.fg("dim", ` ${parts.join(" · ")}`);
+  }
+}

package/index.ts

@@ -4,6 +4,7 @@
  * Shared settings infrastructure for pi extensions:
  * - ConfigLoader: load/save/merge JSON configs from global + project paths
  * - registerSettingsCommand: create a settings command with Local/Global tabs
+ * - Wizard: multi-step wizard component with tabbed navigation and borders
  * - SectionedSettings: sectioned settings list component
  * - ArrayEditor: string array editor submenu component
  * - Helpers: nested value access, display-to-storage value mapping
@@ -26,6 +27,12 @@ export {
   type SectionedSettingsOptions,
   type SettingsSection,
 } from "./components/sectioned-settings";
+export {
+  Wizard,
+  type WizardOptions,
+  type WizardStep,
+  type WizardStepContext,
+} from "./components/wizard";
 export {
   ConfigLoader,
   type ConfigStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-utils-settings",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -19,8 +19,14 @@
   "files": [
     "*.ts",
     "components",
+    "skills",
     "README.md"
   ],
+  "pi": {
+    "skills": [
+      "skills"
+    ]
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.51.0"
   }

package/settings-command.ts

@@ -5,9 +5,17 @@
  * Changes are tracked in memory. Ctrl+S saves, Esc exits without saving.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
 import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
-import { Key, matchesKey } from "@mariozechner/pi-tui";
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
 import {
   SectionedSettings,
   type SettingsSection,
@@ -76,7 +84,7 @@ export interface SettingsCommandOptions<
    * Called after save succeeds. Use this to reload runtime state
    * that was captured at extension init time.
    */
-  onSave?: () => void | Promise<void>;
+  onSave?: (ctx: ExtensionCommandContext) => void | Promise<void>;
 }
 
 function defaultChangeHandler<TConfig extends object>(
@@ -197,7 +205,7 @@ export function registerSettingsCommand<
               handleChange(scope, id, newValue);
             },
             () => done(undefined),
-            { enableSearch: true, hintSuffix: "Ctrl+S to save" },
+            { enableSearch: true, hideHint: true },
           );
         }
 
@@ -256,7 +264,7 @@ export function registerSettingsCommand<
 
           if (saved) {
             ctx.ui.notify(`${extensionLabel}: saved`, "info");
-            if (onSave) await onSave();
+            if (onSave) await onSave(ctx);
             // Rebuild with fresh data.
             settings = buildSettingsComponent(activeScope);
           }
@@ -266,10 +274,10 @@ export function registerSettingsCommand<
 
         // --- Tab rendering ---
 
-        function renderTabs(): string[] {
+        function renderTabs(_contentWidth: number): string {
           // Single scope = no tabs needed
           if (enabledScopes.length === 1) {
-            return [""];
+            return "";
           }
 
           const tabLabels = enabledScopes.map((scope) => {
@@ -283,7 +291,18 @@ export function registerSettingsCommand<
             return theme.fg("dim", fullLabel);
           });
 
-          return ["", `  ${tabLabels.join("  ")}`, ""];
+          return tabLabels.join("  ");
+        }
+
+        function padLine(content: string, contentWidth: number): string {
+          const len = visibleWidth(content);
+          const padding = Math.max(0, contentWidth - len);
+          return (
+            theme.fg("border", "│") +
+            truncateToWidth(content, contentWidth) +
+            " ".repeat(padding) +
+            theme.fg("border", "│")
+          );
         }
 
         function handleTabSwitch(data: string): boolean {
@@ -311,9 +330,55 @@ export function registerSettingsCommand<
         return {
           render(width: number) {
             const lines: string[] = [];
-            lines.push(theme.fg("accent", theme.bold(title)));
-            lines.push(...renderTabs());
-            lines.push(...(settings?.render(width) ?? []));
+            const contentWidth = Math.max(1, width - 2);
+
+            // Top border with title
+            const titleText = ` ${title} `;
+            const titleLen = visibleWidth(titleText);
+            const topRuleLen = Math.max(1, width - titleLen - 3);
+            lines.push(
+              theme.fg("border", "╭─") +
+                theme.fg("accent", theme.bold(titleText)) +
+                theme.fg("border", "─".repeat(topRuleLen)) +
+                theme.fg("border", "╮"),
+            );
+
+            // Scope tabs
+            const tabs = renderTabs(contentWidth);
+            if (tabs) {
+              lines.push(padLine(tabs, contentWidth));
+            }
+            lines.push(padLine("", contentWidth));
+
+            // Settings content
+            const innerLines = settings?.render(contentWidth) ?? [];
+            for (const line of innerLines) {
+              lines.push(padLine(line, contentWidth));
+            }
+
+            // Separator
+            lines.push(
+              theme.fg("border", "├") +
+                theme.fg("border", "─".repeat(contentWidth)) +
+                theme.fg("border", "┤"),
+            );
+
+            // Controls
+            const parts = ["Enter/Space change"];
+            if (enabledScopes.length > 1) {
+              parts.push("Tab/Shift+Tab scope");
+            }
+            parts.push("Ctrl+S save", "Esc close");
+            const controlsText = theme.fg("dim", ` ${parts.join(" · ")}`);
+            lines.push(padLine(controlsText, contentWidth));
+
+            // Bottom border
+            lines.push(
+              theme.fg("border", "╰") +
+                theme.fg("border", "─".repeat(contentWidth)) +
+                theme.fg("border", "╯"),
+            );
+
             return lines;
           },
           invalidate() {