pi-blackhole 0.4.2 → 0.4.3

package/src/pi-base/settings/fields/action.ts

@@ -0,0 +1,43 @@
+/**
+ * Renderer for `type: "action"` rows. Non-storing — Enter triggers the
+ * caller-supplied `onActivate(ctx)` and never changes a value.
+ */
+
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { ActionField, FieldRenderer } from "../types";
+
+export const actionRenderer: FieldRenderer<ActionField, void> = {
+  type: "action",
+  renderValue(row, { selected, ctx }) {
+    const text = row.field.display ?? "(run)";
+    if (row.field.disabled) {
+      return ctx.theme.fg("muted", text);
+    }
+    return ctx.theme.fg(selected ? "accent" : "muted", text);
+  },
+  hints(row) {
+    if (row.field.disabled) return [];
+    return [{ key: "enter", label: "run" }];
+  },
+  handleKey(row, data, { ctx }) {
+    if (row.field.disabled) return {};
+    if (
+      matchesKey(data, "enter") ||
+      matchesKey(data, "return") ||
+      data === " "
+    ) {
+      // Fire and forget — actions are deliberately fire-and-go so the
+      // modal stays responsive even when `onActivate` is async.
+      try {
+        const ret = row.field.onActivate(ctx.ctx);
+        if (ret && typeof (ret as Promise<void>).then === "function") {
+          (ret as Promise<void>).catch(() => {});
+        }
+      } catch {
+        // Swallow — actions must never break the modal loop.
+      }
+      return { consumed: true };
+    }
+    return {};
+  },
+};

package/src/pi-base/settings/fields/boolean.ts

@@ -0,0 +1,47 @@
+/**
+ * Renderer for `type: "boolean"` rows. Enter / Space toggles between
+ * `on` and `off`; the value is committed immediately.
+ */
+
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { BooleanField, FieldRenderer } from "../types";
+
+export const booleanRenderer: FieldRenderer<BooleanField, boolean> = {
+  type: "boolean",
+  renderValue(row, { selected, ctx }) {
+    const text = row.value ? "on" : "off";
+    if (row.field.disabled) {
+      return ctx.theme.fg("muted", text);
+    }
+    return ctx.theme.fg(
+      selected ? "accent" : row.value ? "success" : "muted",
+      text,
+    );
+  },
+  hints(row) {
+    if (row.field.disabled) return [];
+    return [
+      { key: "enter/space", label: row.value ? "turn off" : "turn on" },
+      { key: "←/→", label: "toggle" },
+    ];
+  },
+  handleKey(row, data) {
+    if (row.field.disabled) return {};
+    if (
+      matchesKey(data, "enter") ||
+      matchesKey(data, "return") ||
+      data === " "
+    ) {
+      return { consumed: true, commit: !row.value };
+    }
+    if (matchesKey(data, "left")) {
+      if (row.value === false) return { consumed: true };
+      return { consumed: true, commit: false };
+    }
+    if (matchesKey(data, "right")) {
+      if (row.value === true) return { consumed: true };
+      return { consumed: true, commit: true };
+    }
+    return {};
+  },
+};

package/src/pi-base/settings/fields/custom.ts

@@ -0,0 +1,72 @@
+/**
+ * Renderer for `type: "custom"` rows. The caller supplies:
+ *
+ *   - `render(args)` — returns the right-hand value cell as a string.
+ *   - `handleInput?(data, args)` — optional inline-edit handler; return
+ *     true to consume the key.
+ *   - `openSubmenu?(args)` — optional submenu mounted on Enter; the
+ *     factory receives a `done(value?)` callback the modal supplies.
+ *
+ * Anything more exotic than the built-in `model` widget belongs here.
+ */
+
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { CustomField, FieldRenderer, SubmenuFactory } from "../types";
+
+export const customRenderer: FieldRenderer<CustomField, unknown> = {
+  type: "custom",
+  renderValue(row, args) {
+    const text = row.field.render({
+      value: row.value,
+      width: args.width,
+      selected: args.selected && !row.field.disabled,
+      theme: args.ctx.theme,
+    });
+    if (row.field.disabled) {
+      return args.ctx.theme.fg("muted", text);
+    }
+    return text;
+  },
+  hints(row) {
+    if (row.field.disabled) return [];
+    // Caller-supplied override wins outright — useful when
+    // `handleInput` consumes a specific key (e.g. space) but Enter
+    // is a no-op, in which case the default "enter edit" heuristic
+    // would be misleading.
+    if (row.field.hints) return row.field.hints;
+    if (row.field.openSubmenu) return [{ key: "enter", label: "open" }];
+    if (row.field.handleInput) return [{ key: "enter", label: "edit" }];
+    return [];
+  },
+  handleKey(row, data, args) {
+    if (row.field.disabled) return {};
+    // Caller-supplied inline-edit handler runs first so it can intercept
+    // arrow keys etc. before we treat Enter as "open submenu".
+    if (row.field.handleInput) {
+      const consumed = row.field.handleInput(data, {
+        value: row.value,
+        width: 0,
+        selected: true,
+        theme: args.ctx.theme,
+      });
+      if (consumed) return { consumed: true };
+    }
+    if (
+      matchesKey(data, "enter") ||
+      matchesKey(data, "return") ||
+      data === " "
+    ) {
+      if (row.field.openSubmenu) {
+        const factory: SubmenuFactory<unknown> = (done) =>
+          row.field.openSubmenu!({
+            value: row.value,
+            theme: args.ctx.theme,
+            tui: args.ctx.tui,
+            done,
+          });
+        return { consumed: true, submenu: factory };
+      }
+    }
+    return {};
+  },
+};

package/src/pi-base/settings/fields/enum.ts

@@ -0,0 +1,310 @@
+/**
+ * Renderer for `type: "enum"` rows.
+ *
+ * Short option lists (≤ `cycleThreshold`, default 4) cycle in place via
+ * Enter / Space; longer lists open a `SelectList` submenu so users
+ * don't have to mash Enter to scroll through 20+ entries.
+ */
+
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  matchesKey,
+  SelectList,
+  truncateToWidth,
+  type Component,
+  type SelectItem,
+} from "@earendil-works/pi-tui";
+import { formatHintLine } from "../frame";
+import type {
+  EnumField,
+  FieldRenderContext,
+  FieldRenderer,
+  SubmenuFactory,
+} from "../types";
+
+const DEFAULT_CYCLE_THRESHOLD = 4;
+const MAX_VISIBLE_ROWS = 12;
+
+function labelFor(field: EnumField, value: string): string {
+  return field.optionLabels?.[value] ?? value;
+}
+
+function nextCycleValue(field: EnumField, current: string): string {
+  if (field.options.length === 0) return current;
+  const idx = field.options.indexOf(current as never);
+  const nextIdx = (idx + 1 + field.options.length) % field.options.length;
+  return field.options[nextIdx]!;
+}
+
+function prevCycleValue(field: EnumField, current: string): string {
+  if (field.options.length === 0) return current;
+  const idx = field.options.indexOf(current as never);
+  const prevIdx = (idx - 1 + field.options.length) % field.options.length;
+  return field.options[prevIdx]!;
+}
+
+/** Build a submenu factory the modal can mount with its own `done`. */
+function makeEnumSubmenu(
+  field: EnumField,
+  current: string,
+  ctx: FieldRenderContext,
+): SubmenuFactory<string> {
+  if (field.search) {
+    return makeSearchableEnumSubmenu(field, current, ctx);
+  }
+
+  return (done) => {
+    const items: SelectItem[] = field.options.map((value, idx) => ({
+      value,
+      label: `${idx + 1}. ${labelFor(field, value)}`,
+    }));
+    const list = new SelectList(
+      items,
+      Math.min(items.length, MAX_VISIBLE_ROWS),
+      getSelectListTheme(),
+    );
+    const idx = field.options.indexOf(current);
+    list.setSelectedIndex(idx >= 0 ? idx : 0);
+    list.onSelect = (item) => done(item.value);
+    list.onCancel = () => done();
+
+    const component: Component = {
+      render(width: number): string[] {
+        const lines = [...list.render(width)];
+        lines.push("");
+        const hints = [
+          { key: "↑↓", label: "select" },
+          ...(items.length > 1
+            ? [{ key: `1-${Math.min(9, items.length)}`, label: "choose" }]
+            : []),
+          { key: "enter", label: "save" },
+          { key: "esc", label: "cancel" },
+        ];
+        const hintText = `  ${formatHintLine(hints, ctx.theme)}`;
+        lines.push(truncateToWidth(hintText, width, "…", true));
+        return lines;
+      },
+      invalidate(): void {
+        list.invalidate();
+      },
+      handleInput(data: string): void {
+        const num = parseInt(data, 10);
+        if (
+          data.length === 1 &&
+          !isNaN(num) &&
+          num >= 1 &&
+          num <= Math.min(9, items.length)
+        ) {
+          const item = items[num - 1];
+          if (item) {
+            done(item.value);
+            return;
+          }
+        }
+        list.handleInput(data);
+        ctx.tui.requestRender();
+      },
+    };
+    return component;
+  };
+}
+
+/**
+ * Build a searchable enum submenu with a filter bar at the top.
+ * Used when `field.search === true`.
+ */
+function makeSearchableEnumSubmenu(
+  field: EnumField,
+  _current: string,
+  ctx: FieldRenderContext,
+): SubmenuFactory<string> {
+  return (done) => {
+    const allItems: SelectItem[] = field.options.map((value) => ({
+      value,
+      label: labelFor(field, value),
+    }));
+
+    let search = "";
+    let selected = 0;
+
+    function filteredItems(): SelectItem[] {
+      if (!search.trim()) return allItems;
+      const q = search.toLowerCase();
+      return allItems.filter(
+        (item) =>
+          item.label.toLowerCase().includes(q) ||
+          item.value.toLowerCase().includes(q),
+      );
+    }
+
+    const component: Component = {
+      render(width: number): string[] {
+        const lines: string[] = [];
+        const items = filteredItems();
+        const searchPrompt = `Search: ${search}${ctx.theme.inverse(" ")}`;
+        lines.push(
+          ctx.theme.bg(
+            "toolPendingBg",
+            truncateToWidth(searchPrompt, width, "…", true),
+          ),
+        );
+        lines.push("");
+
+        if (items.length === 0) {
+          lines.push(ctx.theme.fg("muted", "  No matching options."));
+        } else {
+          const maxVisible = MAX_VISIBLE_ROWS;
+          const scroll = Math.max(
+            0,
+            Math.min(
+              selected - Math.floor(maxVisible / 2),
+              Math.max(0, items.length - maxVisible),
+            ),
+          );
+          const slice = items.slice(scroll, scroll + maxVisible);
+          for (let i = 0; i < slice.length; i++) {
+            const isSelected = scroll + i === selected;
+            const prefix = isSelected ? ctx.theme.fg("accent", "▌ ") : "  ";
+            const display = isSelected
+              ? ctx.theme.fg("accent", slice[i]!.label)
+              : ctx.theme.fg("muted", slice[i]!.label);
+            const line = `${prefix}${display}`;
+            lines.push(
+              isSelected
+                ? ctx.theme.bg(
+                    "selectedBg",
+                    truncateToWidth(line, width, "…", true),
+                  )
+                : truncateToWidth(line, width, "…", true),
+            );
+          }
+        }
+
+        lines.push("");
+        const hints = [
+          { key: "↑↓", label: "select" },
+          { key: "enter", label: "save" },
+          { key: "esc", label: "cancel" },
+        ];
+        if (search) hints.unshift({ key: "type", label: "to filter" });
+        lines.push(`  ${formatHintLine(hints, ctx.theme)}`);
+        return lines;
+      },
+      invalidate(): void {
+        // no external state to invalidate
+      },
+      handleInput(data: string): void {
+        if (matchesKey(data, "up")) {
+          selected = Math.max(0, selected - 1);
+          ctx.tui.requestRender();
+          return;
+        }
+        if (matchesKey(data, "down")) {
+          const items = filteredItems();
+          selected = Math.min(selected + 1, Math.max(0, items.length - 1));
+          ctx.tui.requestRender();
+          return;
+        }
+        if (matchesKey(data, "enter") || matchesKey(data, "return")) {
+          const items = filteredItems();
+          if (items.length > 0) {
+            done(items[Math.min(selected, items.length - 1)]!.value);
+          }
+          return;
+        }
+        if (matchesKey(data, "escape")) {
+          done();
+          return;
+        }
+        if (matchesKey(data, "backspace") || matchesKey(data, "ctrl+h")) {
+          search = search.slice(0, -1);
+          selected = 0;
+          ctx.tui.requestRender();
+          return;
+        }
+        if (data.length === 1 && data >= " " && data !== "\x7f") {
+          search += data;
+          selected = 0;
+          ctx.tui.requestRender();
+        }
+      },
+    };
+    return component;
+  };
+}
+
+export const enumRenderer: FieldRenderer<EnumField, string> = {
+  type: "enum",
+  renderValue(row, { selected, ctx }) {
+    const text = labelFor(row.field, row.value);
+    if (row.field.disabled) {
+      return ctx.theme.fg("muted", text);
+    }
+    return ctx.theme.fg(selected ? "accent" : "muted", text);
+  },
+  hints(row) {
+    if (row.field.disabled) return [];
+    // Searchable enums always open a list submenu
+    if (row.field.search) {
+      return [{ key: "enter", label: "open list" }];
+    }
+    const threshold = row.field.cycleThreshold ?? DEFAULT_CYCLE_THRESHOLD;
+    if (row.field.options.length > threshold) {
+      return [{ key: "enter", label: "open list" }];
+    }
+    return [
+      { key: "enter/space", label: "cycle" },
+      { key: "←/→", label: "prev/next" },
+    ];
+  },
+  handleKey(row, data, { ctx }) {
+    if (row.field.disabled) return {};
+    // Searchable enums always open a submenu on Enter/Space
+    if (row.field.search) {
+      if (
+        matchesKey(data, "enter") ||
+        matchesKey(data, "return") ||
+        data === " "
+      ) {
+        return {
+          consumed: true,
+          submenu: makeEnumSubmenu(row.field, row.value, ctx),
+        };
+      }
+      // No cycling for searchable enums — all navigation is in the submenu
+      return {};
+    }
+
+    const threshold = row.field.cycleThreshold ?? DEFAULT_CYCLE_THRESHOLD;
+    const isLongList = row.field.options.length > threshold;
+
+    if (
+      matchesKey(data, "enter") ||
+      matchesKey(data, "return") ||
+      data === " "
+    ) {
+      if (isLongList) {
+        return {
+          consumed: true,
+          submenu: makeEnumSubmenu(row.field, row.value, ctx),
+        };
+      }
+      return { consumed: true, commit: nextCycleValue(row.field, row.value) };
+    }
+
+    if (!isLongList) {
+      if (matchesKey(data, "left")) {
+        const prev = prevCycleValue(row.field, row.value);
+        if (prev === row.value) return { consumed: true };
+        return { consumed: true, commit: prev };
+      }
+      if (matchesKey(data, "right")) {
+        const next = nextCycleValue(row.field, row.value);
+        if (next === row.value) return { consumed: true };
+        return { consumed: true, commit: next };
+      }
+    }
+
+    return {};
+  },
+};

package/src/pi-base/settings/fields/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Built-in field renderers. The modal's `RENDERERS` lookup is
+ * constructed from these so user-supplied `type: "custom"` fields can
+ * coexist with built-ins without any registration ceremony.
+ */
+
+import type { Field, FieldRenderer } from "../types";
+import { actionRenderer } from "./action";
+import { booleanRenderer } from "./boolean";
+import { customRenderer } from "./custom";
+import { enumRenderer } from "./enum";
+import { modelRenderer } from "./model";
+import {
+  numberRenderer,
+  pathRenderer,
+  secretRenderer,
+  stringRenderer,
+} from "./string";
+import { textRenderer } from "./text";
+
+export {
+  actionRenderer,
+  booleanRenderer,
+  customRenderer,
+  enumRenderer,
+  modelRenderer,
+  numberRenderer,
+  pathRenderer,
+  secretRenderer,
+  stringRenderer,
+  textRenderer,
+};
+
+/** Map of field discriminator → renderer. */
+export const RENDERERS: Record<Field["type"], FieldRenderer<any, any>> = {
+  boolean: booleanRenderer,
+  enum: enumRenderer,
+  string: stringRenderer,
+  number: numberRenderer,
+  secret: secretRenderer,
+  path: pathRenderer,
+  text: textRenderer,
+  action: actionRenderer,
+  model: modelRenderer,
+  custom: customRenderer,
+};