pi-blackhole 0.4.1 → 0.4.3

package/src/pi-base/settings/frame.ts

@@ -0,0 +1,197 @@
+/**
+ * Rounded-light frame helpers for the settings modal — and for any
+ * future overlay in this package that wants the same look.
+ *
+ * Visual:
+ *
+ *     ╭── Title ──────────────────────╮
+ *     │                                │
+ *     │   Muted              off       │
+ *     │   Voice              Umbriel   │
+ *     │                                │
+ *     ╰────────────────────────────────╯
+ *
+ * The frame draws:
+ *   - A single-line top border with an inline title pill (`╭── Title ──╮`).
+ *     Title text is coloured via the host theme's `accent` foreground.
+ *   - A bottom border closing with `╰─╯`.
+ *   - Vertical sides as `│` separators.
+ *   - `paddingY` blank rows above and below the body, plus `paddingX`
+ *     spaces left and right of every body row.
+ *   - Optional row-count cap (`fixedInnerRows`) so a too-tall body is
+ *     truncated with a `↓ N more line(s)` indicator instead of overflowing
+ *     the popup.
+ *
+ * All helpers are width-aware: every output line is right-truncated to
+ * `width` columns using pi-tui's `truncateToWidth` so they never escape
+ * the overlay rectangle.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+/** Default horizontal padding inside the frame, in columns. */
+export const DEFAULT_PADDING_X = 2;
+/** Default vertical padding inside the frame, in rows. */
+export const DEFAULT_PADDING_Y = 1;
+/** Total vertical rows consumed by the frame chrome (top + bottom + 2× padY). */
+export const FRAME_VERTICAL_CHROME = 2 + DEFAULT_PADDING_Y * 2;
+
+export interface FrameOptions {
+  /** Inline title in the top border. Truncated with `…` when too wide. */
+  title?: string;
+  /** Inner padding columns (left and right). Defaults to {@link DEFAULT_PADDING_X}. */
+  paddingX?: number;
+  /** Inner padding rows (top and bottom). Defaults to {@link DEFAULT_PADDING_Y}. */
+  paddingY?: number;
+  /**
+   * If set, the body is forced to exactly this many inner rows. Excess
+   * lines are replaced with a `↓ N more` indicator at the bottom; missing
+   * lines are padded with blank rows so the overlay never visually shrinks
+   * mid-session.
+   */
+  fixedInnerRows?: number;
+}
+
+/** Width available to body content, given a frame's outer `width`. */
+export function frameContentWidth(
+  width: number,
+  paddingX: number = DEFAULT_PADDING_X,
+): number {
+  return Math.max(1, width - 2 - paddingX * 2);
+}
+
+/** Right-pad a (possibly ANSI-coloured) string to exactly `width` columns. */
+export function pad(text: string, width: number): string {
+  const truncated = truncateToWidth(text, width, "");
+  return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+/**
+ * Wrap `line` to fit `width` columns. Hard newlines split the line first;
+ * each segment is then word-wrapped (ANSI-aware via pi-tui's helper) and
+ * finally truncated as a defence-in-depth against pathological cases.
+ */
+export function wrapLine(line: string, width: number): string[] {
+  const safeWidth = Math.max(1, width);
+  const normalized = String(line ?? "").replace(/\t/g, "  ");
+  const wrapped = normalized.split(/\r?\n/).flatMap((part) => {
+    const rows = wrapTextWithAnsi(part, safeWidth);
+    return rows.length > 0 ? rows : [""];
+  });
+  return wrapped.map((part) => truncateToWidth(part, safeWidth, ""));
+}
+
+/** Render a single horizontal divider line, themed in `dim`. */
+export function divider(width: number, theme: Theme): string {
+  return theme.fg("dim", "─".repeat(Math.max(1, width)));
+}
+
+/** One key-hint pair as rendered in the modal's footer. */
+export interface KeyHint {
+  key: string;
+  label: string;
+}
+
+/**
+ * Format a list of key hints as a single line: each `key` rendered in
+ * the host theme's `accent` colour and each `label` in `dim`, joined
+ * by a dim middle-dot (`·`). Used by both the main settings modal
+ * footer and any submenu that wants matching highlighting.
+ *
+ * Returns the raw composed string — caller is responsible for
+ * truncating / wrapping if needed.
+ */
+export function formatHintLine(hints: KeyHint[], theme: Theme): string {
+  return hints
+    .map((h) => `${theme.fg("accent", h.key)} ${theme.fg("dim", h.label)}`)
+    .join(theme.fg("dim", " · "));
+}
+
+/**
+ * Wrap `lines` in a rounded-light frame. The top border embeds an
+ * optional title pill rendered in the host theme's `accent` colour; the
+ * border itself is themed in `borderAccent` so it stands out from chat
+ * but blends with the user's chosen palette.
+ *
+ * The output is exactly the right shape to hand to `ctx.ui.custom`'s
+ * overlay component — every line is exactly `width` columns wide.
+ */
+export function frame(
+  lines: string[],
+  width: number,
+  theme: Theme,
+  options: FrameOptions = {},
+): string[] {
+  const paddingX = options.paddingX ?? DEFAULT_PADDING_X;
+  const paddingY = options.paddingY ?? DEFAULT_PADDING_Y;
+  const inner = Math.max(1, width - 2);
+  const contentWidth = frameContentWidth(width, paddingX);
+  const border = (s: string) => theme.fg("borderAccent", s);
+
+  let body = lines;
+  if (
+    options.fixedInnerRows !== undefined &&
+    body.length > options.fixedInnerRows
+  ) {
+    const hidden = body.length - options.fixedInnerRows + 1;
+    body = [
+      ...body.slice(0, Math.max(0, options.fixedInnerRows - 1)),
+      theme.fg("dim", `↓ ${hidden} more line(s)`),
+    ].slice(0, options.fixedInnerRows);
+  }
+
+  const blank = `${border("│")}${" ".repeat(inner)}${border("│")}`;
+  const top = (): string => {
+    if (!options.title)
+      return `${border("╭")}${border("─".repeat(inner))}${border("╮")}`;
+    // Title pill: `── <title> ──`, truncated to fit; surrounded by border
+    // dashes on both sides so the pill always reaches the corners.
+    const titlePlain = ` ${truncateToWidth(options.title, Math.max(1, inner - 4), "…")} `;
+    const titleVisible = visibleWidth(titlePlain);
+    const leftDash = 2;
+    const rightDash = Math.max(1, inner - leftDash - titleVisible);
+    return (
+      `${border("╭")}${border("─".repeat(leftDash))}` +
+      `${theme.fg("accent", theme.bold(titlePlain))}` +
+      `${border("─".repeat(rightDash))}${border("╮")}`
+    );
+  };
+
+  const out: string[] = [top()];
+  for (let i = 0; i < paddingY; i += 1) out.push(blank);
+  for (const line of body) {
+    out.push(
+      `${border("│")}${" ".repeat(paddingX)}${pad(line, contentWidth)}${" ".repeat(paddingX)}${border("│")}`,
+    );
+  }
+  for (let i = 0; i < paddingY; i += 1) out.push(blank);
+  out.push(`${border("╰")}${border("─".repeat(inner))}${border("╯")}`);
+  return out.map((line) => truncateToWidth(line, width, ""));
+}
+
+/**
+ * Compute a sensible inner-row count given the terminal height and a
+ * preferred maximum. Mirrors the `responsiveInnerRows` math from
+ * `extension-manager.ts` so popups shrink gracefully on short terminals
+ * instead of clipping past the bottom edge.
+ */
+export function responsiveInnerRows(
+  terminalRows: number,
+  preferred: number,
+  minimum = 12,
+  ratio = 0.85,
+): number {
+  const available = Math.max(
+    minimum + FRAME_VERTICAL_CHROME,
+    Math.floor(Math.max(1, terminalRows) * ratio),
+  );
+  return Math.max(
+    minimum,
+    Math.min(preferred, available - FRAME_VERTICAL_CHROME),
+  );
+}

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

@@ -0,0 +1,77 @@
+/**
+ * @k0valik/pi-base/settings — public entry point for the settings
+ * modal feature (originally vendored from wierdbytes/pi-common/settings;
+ * since heavily reworked — buffered save mode, scope-aware values,
+ * validation, fuzzy filtering).
+ *
+ * High-level: `openSettingsModal(ctx, opts)` opens a centered popup,
+ * persists changes via `opts.onChange`, and resolves on close.
+ *
+ * Mid-level: `createSettingsModal(ctx, opts)` returns a `ctx.ui.custom`
+ * factory for callers that manage their own overlay lifecycle.
+ *
+ * Low-level: `createSettingsModalBody`, `frame`, `inline-edit` helpers,
+ * built-in `RENDERERS` map, and the full `Field` discriminated union
+ * are all exported for callers building bespoke layouts on top of the
+ * same primitives.
+ */
+
+export { createSettingsModal, openSettingsModal } from "./modal";
+
+export { createSettingsModalBody } from "./body";
+
+export {
+  divider,
+  formatHintLine,
+  frame,
+  frameContentWidth,
+  pad,
+  responsiveInnerRows,
+  wrapLine,
+  type FrameOptions,
+  type KeyHint,
+} from "./frame";
+
+export {
+  clampInlineCursor,
+  deleteWordBackward,
+  handleInlineEditInput,
+  insertInlineText,
+  renderInlineEditValue,
+  type InlineEditState,
+} from "./inline-edit";
+
+export { RENDERERS } from "./fields/index";
+
+export { validateFieldValue } from "./validate-field";
+
+export type {
+  ActionField,
+  BooleanField,
+  CustomField,
+  CustomFieldRenderArgs,
+  CustomFieldSubmenuArgs,
+  EnumField,
+  Field,
+  FieldBase,
+  FieldKeyHint,
+  FieldKeyResult,
+  FieldRenderContext,
+  FieldRenderer,
+  FieldRow,
+  ModelField,
+  ModelOption,
+  ModelValue,
+  NumberField,
+  PathField,
+  SecretField,
+  SettingsModalFactory,
+  SettingsModalOptions,
+  SettingsTheme,
+  StringField,
+  SubmenuFactory,
+  Tab,
+  TextField,
+  ValueOfField,
+  VisibilityContext,
+} from "./types";

package/src/pi-base/settings/inline-edit.ts

@@ -0,0 +1,313 @@
+/**
+ * Inline string-editor state machine for single-line value editing inside
+ * settings rows.
+ *
+ * Ported from the helpers in vstack's `extension-manager.ts`. This file is
+ * **pure logic** — no terminal access, no theme, no rendering — so it can
+ * be exercised in `bun test` / `vitest` without a TUI.
+ *
+ * Key shape: a tiny `{ buffer, cursor }` struct mutated in place by the
+ * helper functions. `cursor` is a **code-unit** index into `buffer` (so
+ * `buffer.slice(0, cursor)` is always safe), but every cursor-moving
+ * helper internally walks **code points** so multi-unit characters
+ * (CJK, emoji, regional indicators) move atomically — pressing `←` once
+ * over a 🌍 jumps two code units, not one.
+ *
+ * Word-jump uses the same three-class scheme as most readline-derived
+ * editors:
+ *   - `space`: `\s` (whitespace);
+ *   - `word`:  `[A-Za-z0-9_]` (identifier-ish);
+ *   - `punct`: everything else.
+ *
+ * Tabs / hard-newlines are intentionally not special-cased — settings
+ * values are single-line strings, and any `\n` arriving from terminal
+ * input would be the wrong kind of input to this editor anyway.
+ */
+
+import { matchesKey, decodeKittyPrintable } from "@earendil-works/pi-tui";
+
+/** Shared yank buffer for storing killed text. */
+let yankBuffer = "";
+
+/** Retrieve the current content of the yank buffer. */
+export function getInlineYankBuffer(): string {
+  return yankBuffer;
+}
+
+/** Set the content of the yank buffer. */
+export function setInlineYankBuffer(val: string): void {
+  yankBuffer = val;
+}
+
+/** Mutable cursor state. `cursor` is a code-unit offset into `buffer`. */
+export interface InlineEditState {
+  buffer: string;
+  cursor: number;
+}
+
+interface InlineEditChar {
+  ch: string;
+  /** Inclusive code-unit start of this char in the source buffer. */
+  start: number;
+  /** Exclusive code-unit end (==start of the next char). */
+  end: number;
+}
+
+/** Decompose `text` into its sequence of code-point chars with their
+ *  code-unit ranges. Used to keep the cursor on a code-point boundary. */
+export function inlineEditChars(text: string): InlineEditChar[] {
+  const out: InlineEditChar[] = [];
+  let offset = 0;
+  for (const ch of text) {
+    const start = offset;
+    offset += ch.length;
+    out.push({ ch, start, end: offset });
+  }
+  return out;
+}
+
+/** Force `cursor` back into `[0, buffer.length]` after a buffer mutation. */
+export function clampInlineCursor(editing: InlineEditState): void {
+  editing.cursor = Math.max(0, Math.min(editing.cursor, editing.buffer.length));
+}
+
+/**
+ * Convert a code-unit offset into the index of the char immediately to
+ * the right of the cursor. A cursor sitting on a char boundary returns
+ * the index of the char it is just before. A cursor past the end returns
+ * `chars.length`.
+ */
+export function codeUnitToCharIndex(
+  chars: InlineEditChar[],
+  cursor: number,
+): number {
+  let index = 0;
+  while (index < chars.length && chars[index]!.end <= cursor) index += 1;
+  return index;
+}
+
+/** Inverse of `codeUnitToCharIndex`. */
+export function charIndexToCodeUnit(
+  chars: InlineEditChar[],
+  index: number,
+  textLength: number,
+): number {
+  if (index <= 0) return 0;
+  if (index >= chars.length) return textLength;
+  return chars[index]!.start;
+}
+
+/** Three-class word/word-boundary classifier used by word-jump helpers. */
+export function inlineCharKind(ch: string): "space" | "word" | "punct" {
+  if (/\s/u.test(ch)) return "space";
+  if (/[A-Za-z0-9_]/.test(ch)) return "word";
+  return "punct";
+}
+
+/** Move the cursor by `delta` code-points (negative = left). */
+export function moveInlineCursorByChars(
+  editing: InlineEditState,
+  delta: number,
+): void {
+  const chars = inlineEditChars(editing.buffer);
+  const index = codeUnitToCharIndex(chars, editing.cursor);
+  editing.cursor = charIndexToCodeUnit(
+    chars,
+    index + delta,
+    editing.buffer.length,
+  );
+}
+
+/** Skip whitespace then a contiguous run of the same char-kind to the left. */
+export function moveInlineCursorWordLeft(editing: InlineEditState): void {
+  const chars = inlineEditChars(editing.buffer);
+  let index = codeUnitToCharIndex(chars, editing.cursor);
+  while (index > 0 && inlineCharKind(chars[index - 1]!.ch) === "space")
+    index -= 1;
+  if (index <= 0) {
+    editing.cursor = 0;
+    return;
+  }
+  const kind = inlineCharKind(chars[index - 1]!.ch);
+  while (index > 0 && inlineCharKind(chars[index - 1]!.ch) === kind) index -= 1;
+  editing.cursor = charIndexToCodeUnit(chars, index, editing.buffer.length);
+}
+
+/** Skip whitespace then a contiguous run of the same char-kind to the right. */
+export function moveInlineCursorWordRight(editing: InlineEditState): void {
+  const chars = inlineEditChars(editing.buffer);
+  let index = codeUnitToCharIndex(chars, editing.cursor);
+  while (index < chars.length && inlineCharKind(chars[index]!.ch) === "space")
+    index += 1;
+  if (index >= chars.length) {
+    editing.cursor = editing.buffer.length;
+    return;
+  }
+  const kind = inlineCharKind(chars[index]!.ch);
+  while (index < chars.length && inlineCharKind(chars[index]!.ch) === kind)
+    index += 1;
+  editing.cursor = charIndexToCodeUnit(chars, index, editing.buffer.length);
+}
+
+/** Insert `text` at the cursor and advance past it. */
+export function insertInlineText(editing: InlineEditState, text: string): void {
+  clampInlineCursor(editing);
+  editing.buffer = `${editing.buffer.slice(0, editing.cursor)}${text}${editing.buffer.slice(editing.cursor)}`;
+  editing.cursor += text.length;
+}
+
+/** Delete the half-open `[start, end)` code-unit range; cursor lands at `start`. */
+export function deleteInlineRange(
+  editing: InlineEditState,
+  start: number,
+  end: number,
+): void {
+  const safeStart = Math.max(0, Math.min(start, editing.buffer.length));
+  const safeEnd = Math.max(safeStart, Math.min(end, editing.buffer.length));
+  editing.buffer = `${editing.buffer.slice(0, safeStart)}${editing.buffer.slice(safeEnd)}`;
+  editing.cursor = safeStart;
+}
+
+/** Heuristic: is `data` a single, plain printable input character? */
+export function isPlainSearchInput(data: string): boolean {
+  // Kitty terminals report printable characters as CSI-u sequences
+  // (e.g. "5" arrives as \x1b[53u). Decode them so typing works there.
+  const decoded = decodeKittyPrintable(data) ?? data;
+  return decoded.length === 1 && decoded >= " " && decoded !== "\x7f";
+}
+
+/**
+ * Dispatch a raw terminal input string to the editor. Returns true when
+ * the input was consumed (caller should re-render); false when it didn't
+ * match any inline-edit shortcut (caller may handle it as a hot-key).
+ */
+export function handleInlineEditInput(
+  editing: InlineEditState,
+  data: string,
+): boolean {
+  clampInlineCursor(editing);
+  if (matchesKey(data, "left") || matchesKey(data, "ctrl+b")) {
+    moveInlineCursorByChars(editing, -1);
+    return true;
+  }
+  if (matchesKey(data, "right") || matchesKey(data, "ctrl+f")) {
+    moveInlineCursorByChars(editing, 1);
+    return true;
+  }
+  if (
+    matchesKey(data, "alt+left") ||
+    matchesKey(data, "ctrl+left") ||
+    matchesKey(data, "alt+b")
+  ) {
+    moveInlineCursorWordLeft(editing);
+    return true;
+  }
+  if (
+    matchesKey(data, "alt+right") ||
+    matchesKey(data, "ctrl+right") ||
+    matchesKey(data, "alt+f")
+  ) {
+    moveInlineCursorWordRight(editing);
+    return true;
+  }
+  if (matchesKey(data, "home") || matchesKey(data, "ctrl+a")) {
+    editing.cursor = 0;
+    return true;
+  }
+  if (matchesKey(data, "end") || matchesKey(data, "ctrl+e")) {
+    editing.cursor = editing.buffer.length;
+    return true;
+  }
+  if (matchesKey(data, "backspace") || matchesKey(data, "ctrl+h")) {
+    const before = editing.cursor;
+    moveInlineCursorByChars(editing, -1);
+    deleteInlineRange(editing, editing.cursor, before);
+    return true;
+  }
+  if (matchesKey(data, "delete") || matchesKey(data, "ctrl+d")) {
+    const start = editing.cursor;
+    moveInlineCursorByChars(editing, 1);
+    deleteInlineRange(editing, start, editing.cursor);
+    return true;
+  }
+  if (matchesKey(data, "ctrl+u")) {
+    editing.buffer = "";
+    editing.cursor = 0;
+    return true;
+  }
+  if (matchesKey(data, "ctrl+w")) {
+    const current = editing.cursor;
+    moveInlineCursorWordLeft(editing);
+    const target = editing.cursor;
+    const killedText = editing.buffer.slice(target, current);
+    if (killedText) {
+      yankBuffer = killedText;
+    }
+    deleteInlineRange(editing, target, current);
+    return true;
+  }
+  if (matchesKey(data, "alt+d")) {
+    const current = editing.cursor;
+    moveInlineCursorWordRight(editing);
+    const target = editing.cursor;
+    const killedText = editing.buffer.slice(current, target);
+    if (killedText) {
+      yankBuffer = killedText;
+    }
+    deleteInlineRange(editing, current, target);
+    return true;
+  }
+  if (matchesKey(data, "ctrl+k")) {
+    const killedText = editing.buffer.slice(editing.cursor);
+    if (killedText) {
+      yankBuffer = killedText;
+    }
+    deleteInlineRange(editing, editing.cursor, editing.buffer.length);
+    return true;
+  }
+  if (matchesKey(data, "ctrl+y")) {
+    if (yankBuffer) {
+      insertInlineText(editing, yankBuffer);
+    }
+    return true;
+  }
+  if (isPlainSearchInput(data)) {
+    // Kitty terminals deliver printable chars as CSI-u sequences —
+    // decode them so the decoded char (not the raw escape bytes) is
+    // inserted into the buffer.
+    const decoded = decodeKittyPrintable(data) ?? data;
+    insertInlineText(editing, decoded);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Render the buffer with a `█` block at the cursor position. Suitable
+ * for embedding in a one-line settings row.
+ */
+export function renderInlineEditValue(editing: InlineEditState): string {
+  clampInlineCursor(editing);
+  return `${editing.buffer.slice(0, editing.cursor)}█${editing.buffer.slice(editing.cursor)}`;
+}
+
+/**
+ * Word-deletion helper to delete a word backward from the end of a string.
+ */
+export function deleteWordBackward(text: string): string {
+  let i = text.length;
+  while (i > 0 && /\s/.test(text[i - 1]!)) {
+    i--;
+  }
+  if (i === 0) return "";
+  const charKind = (ch: string) => {
+    if (/\s/.test(ch)) return "space";
+    if (/[A-Za-z0-9_]/.test(ch)) return "word";
+    return "punct";
+  };
+  const kind = charKind(text[i - 1]!);
+  while (i > 0 && charKind(text[i - 1]!) === kind) {
+    i--;
+  }
+  return text.slice(0, i);
+}