@mrclrchtr/supi-ask-user 0.1.0

package/ui-rich-render.ts

@@ -0,0 +1,370 @@
+// Pure rendering helpers for the rich overlay. Kept separate from
+// ui-rich.ts to stay within Biome's per-file line limit and so the input
+// dispatch logic can be read without scrolling past a wall of theme strings.
+
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { type Editor, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import type { QuestionnaireFlow } from "./flow.ts";
+import { decorateOption, formatReviewLines, NOTE_MARKER } from "./format.ts";
+import type { NormalizedStructuredQuestion } from "./types.ts";
+import { inlineStructuredRowLines, structuredRowLabel } from "./ui-rich-inline.ts";
+import {
+  editorCaption,
+  padRight,
+  renderEditorBlock,
+  renderEditorPane,
+  usesSeparateEditorPane,
+} from "./ui-rich-render-editor.ts";
+import {
+  currentNote,
+  currentRowSupportsNotes,
+  renderNoteStatus,
+  visibleNoteMarker,
+} from "./ui-rich-render-notes.ts";
+import { hasPreview, type InteractiveRow, interactiveRows } from "./ui-rich-state.ts";
+
+export type SubMode = "select" | "other-input" | "text-input" | "discuss-input" | "note-input";
+
+export interface OverlayRenderState {
+  selectedIndex: number;
+  subMode: SubMode;
+  stagedSelections: Map<string, number[]>;
+  stagedSingleNotes: Map<string, string>;
+  stagedMultiNotes: Map<string, Map<number, string>>;
+}
+
+export function isEditorMode(mode: SubMode): boolean {
+  return (
+    mode === "text-input" ||
+    mode === "other-input" ||
+    mode === "discuss-input" ||
+    mode === "note-input"
+  );
+}
+
+export function selectedIndexesForQuestion(
+  flow: Pick<QuestionnaireFlow, "getAnswer">,
+  state: Pick<OverlayRenderState, "stagedSelections">,
+  question: NormalizedStructuredQuestion,
+): number[] {
+  const staged = state.stagedSelections.get(question.id);
+  if (staged) return [...staged];
+  const answer = flow.getAnswer(question.id);
+  if (!answer) return [];
+  if (answer.source === "option" || answer.source === "yesno") return [answer.optionIndex];
+  if (answer.source === "options") return [...answer.optionIndexes];
+  return [];
+}
+
+// biome-ignore lint/complexity/useMaxParams: render entry needs full overlay context
+export function renderOverlay(
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+): string[] {
+  const lines: string[] = [];
+  const add = (text: string) => lines.push(truncateToWidth(text, width));
+  add(theme.fg("accent", "─".repeat(width)));
+  if (flow.isMultiQuestion) renderTabBar(add, theme, flow);
+  if (flow.currentMode === "reviewing") {
+    renderReview(add, theme, flow);
+  } else {
+    renderQuestion(add, lines, width, theme, flow, state, editor);
+  }
+  add(theme.fg("dim", ` ${footerHelp(flow, state)}`));
+  add(theme.fg("accent", "─".repeat(width)));
+  return lines;
+}
+
+function renderTabBar(add: (text: string) => void, theme: Theme, flow: QuestionnaireFlow): void {
+  // Active segment uses the selected-bg highlight (matches pi's reference
+  // questionnaire and Claude's UI). Inactive segments stay foreground-only:
+  // success when answered, muted when pending.
+  const segments: string[] = [theme.fg("dim", "← ")];
+  for (const [index, question] of flow.questions.entries()) {
+    const answered = flow.hasAnswer(question.id);
+    const active = flow.currentMode === "answering" && flow.currentIndex === index;
+    const marker = answered ? "■" : "□";
+    const text = ` ${marker} ${question.header} `;
+    segments.push(
+      active
+        ? theme.bg("selectedBg", theme.fg("text", text))
+        : theme.fg(answered ? "success" : "muted", text),
+    );
+    segments.push(" ");
+  }
+  const reviewText = " ✓ Review ";
+  segments.push(
+    flow.currentMode === "reviewing"
+      ? theme.bg("selectedBg", theme.fg("text", reviewText))
+      : theme.fg("dim", reviewText),
+  );
+  segments.push(theme.fg("dim", " →"));
+  add(` ${segments.join("")}`);
+  add("");
+}
+
+// biome-ignore lint/complexity/useMaxParams: question render needs full context
+function renderQuestion(
+  add: (text: string) => void,
+  lines: string[],
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+): void {
+  const question = flow.currentQuestion;
+  if (!question) return;
+  for (const line of wrapTextWithAnsi(` ${question.prompt}`, width)) {
+    add(theme.fg("text", line));
+  }
+  lines.push("");
+  if (question.type === "text") {
+    renderTextQuestion(add, lines, theme, editor, width);
+    return;
+  }
+  renderStructuredQuestion(add, lines, width, theme, flow, state, editor, question);
+}
+
+// biome-ignore lint/complexity/useMaxParams: split view layout needs full context
+function renderSplitView(
+  lines: string[],
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): void {
+  const leftWidth = Math.max(34, Math.floor(width * 0.42));
+  const rightWidth = Math.max(24, width - leftWidth - 3);
+  const leftLines = renderPaneRows(leftWidth, theme, flow, state, editor, question, rows);
+  const rightLines = usesSeparateEditorPane(state)
+    ? renderEditorPane(rightWidth, theme, editor, editorCaption(state))
+    : renderPreviewPane(
+        rightWidth,
+        theme,
+        previewForSelection(question, rows[state.selectedIndex]),
+      );
+  const total = Math.max(leftLines.length, rightLines.length);
+  for (let index = 0; index < total; index += 1) {
+    const left = padRight(leftLines[index] ?? "", leftWidth);
+    const right = padRight(rightLines[index] ?? "", rightWidth);
+    lines.push(`${left} ${theme.fg("accent", "│")} ${right}`);
+  }
+}
+
+// biome-ignore lint/complexity/useMaxParams: thin adapter for text question rendering
+function renderTextQuestion(
+  add: (text: string) => void,
+  lines: string[],
+  theme: Theme,
+  editor: Editor,
+  width: number,
+): void {
+  renderEditorBlock(add, lines, theme, editor, width, "Answer");
+}
+
+// biome-ignore lint/complexity/useMaxParams: structured render needs full context
+function renderStructuredQuestion(
+  add: (text: string) => void,
+  lines: string[],
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+  question: NormalizedStructuredQuestion,
+): void {
+  const rows = interactiveRows(question);
+  if (hasPreview(question) && width >= 100) {
+    renderSplitView(lines, width, theme, flow, state, editor, question, rows);
+  } else {
+    renderStandardStructuredQuestion(add, lines, width, theme, flow, state, editor, question, rows);
+  }
+  const note = currentNote(flow, state, question);
+  if (note) renderNoteStatus(add, theme, note);
+}
+
+// biome-ignore lint/complexity/useMaxParams: standard layout needs full context
+function renderStandardStructuredQuestion(
+  add: (text: string) => void,
+  lines: string[],
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): void {
+  renderRows(add, width, theme, flow, state, editor, question, rows);
+  if (usesSeparateEditorPane(state)) {
+    renderEditorBlock(add, lines, theme, editor, width, editorCaption(state));
+    return;
+  }
+  const preview = previewForSelection(question, rows[state.selectedIndex]);
+  if (preview) renderPreviewBlock(add, lines, theme, width, preview);
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper mirrors render context
+function renderPaneRows(
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): string[] {
+  const out: string[] = [];
+  const push = (text = "") => out.push(truncateToWidth(text, width));
+  renderRows(push, width, theme, flow, state, editor, question, rows);
+  return out;
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper mirrors render context
+function renderRows(
+  add: (text: string) => void,
+  width: number,
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  editor: Editor,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): void {
+  const selected = selectedIndexesForQuestion(flow, state, question);
+  for (const [index, row] of rows.entries()) {
+    const active = state.selectedIndex === index;
+    const prefix = active ? theme.fg("accent", "> ") : "  ";
+    const inlineEditorLines = inlineStructuredRowLines({
+      width,
+      theme,
+      state,
+      editor,
+      row,
+      prefix,
+    });
+    if (inlineEditorLines) {
+      for (const [lineIndex, line] of inlineEditorLines.entries()) {
+        add(`${lineIndex === 0 ? prefix : "   "}${line}`);
+      }
+      continue;
+    }
+    add(prefix + rowLabel(theme, flow, state, question, row, active, selected));
+    const description = rowDescription(question, row);
+    if (description) add(`     ${theme.fg("muted", description)}`);
+  }
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper mirrors render context
+function rowLabel(
+  theme: Theme,
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow,
+  active: boolean,
+  selected: number[],
+): string {
+  if (row.kind === "option") {
+    const option = question.options[row.optionIndex];
+    const recommended = question.recommendedIndexes.includes(row.optionIndex);
+    const noteMarker = visibleNoteMarker({ flow, state, question, row, active });
+    const baseLabel = `${decorateOption(option.label, recommended)}${noteMarker ? ` ${NOTE_MARKER}` : ""}`;
+    if (question.type === "multichoice") {
+      const checked = selected.includes(row.optionIndex) ? "[x]" : "[ ]";
+      return theme.fg("text", `${checked} ${baseLabel}`);
+    }
+    return theme.fg("text", `${row.optionIndex + 1}. ${baseLabel}`);
+  }
+  if (row.kind === "other") return theme.fg("text", structuredRowLabel(flow, question, row));
+  return theme.fg("text", structuredRowLabel(flow, question, row));
+}
+
+function rowDescription(
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow,
+): string | undefined {
+  if (row.kind === "option") return question.options[row.optionIndex].description;
+  return undefined;
+}
+
+function renderPreviewPane(width: number, theme: Theme, preview: string | undefined): string[] {
+  const out: string[] = [];
+  const push = (text = "") => out.push(truncateToWidth(text, width));
+  push(theme.fg("accent", " Preview"));
+  push("");
+  if (!preview) {
+    push(theme.fg("muted", " No preview for the current selection."));
+    return out;
+  }
+  for (const line of preview.split("\n")) push(theme.fg("text", ` ${line}`));
+  return out;
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper mirrors render context
+function renderPreviewBlock(
+  add: (text: string) => void,
+  lines: string[],
+  theme: Theme,
+  width: number,
+  preview: string,
+): void {
+  add("");
+  add(theme.fg("accent", " Preview:"));
+  for (const line of preview.split("\n")) {
+    lines.push(truncateToWidth(` ${line}`, width));
+  }
+}
+
+function previewForSelection(
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow | undefined,
+): string | undefined {
+  return row?.kind === "option" ? question.options[row.optionIndex].preview : undefined;
+}
+
+function renderReview(add: (text: string) => void, theme: Theme, flow: QuestionnaireFlow): void {
+  add(theme.fg("accent", " Review answers:"));
+  add("");
+  for (const question of flow.questions) {
+    const answer = flow.getAnswer(question.id);
+    const lines = answer ? formatReviewLines(question, answer) : ["(no answer)"];
+    add(theme.fg("muted", ` ${question.header}:`));
+    for (const line of lines) add(`   ${theme.fg("text", line)}`);
+  }
+  add("");
+  add(theme.fg(flow.allAnswered() ? "success" : "warning", " Press Enter to submit"));
+}
+
+function footerHelp(flow: QuestionnaireFlow, state: OverlayRenderState): string {
+  if (state.subMode === "text-input") return "Enter to submit • Esc to cancel";
+  if (isEditorMode(state.subMode)) return "Enter to submit • Esc to go back";
+  if (flow.currentMode === "reviewing") {
+    return "Enter to submit • ←/Shift-Tab to revise • Esc to cancel";
+  }
+  const question = flow.currentQuestion;
+  if (!question || question.type === "text") return "Esc cancel";
+  const canGoBack = flow.currentIndex > 0;
+  const canReview = flow.allAnswered();
+  const parts = ["↑↓ navigate"];
+  if (question.type === "multichoice") {
+    parts.push("Space toggle");
+    if (selectedIndexesForQuestion(flow, state, question).length > 0) parts.push("Enter submit");
+  } else {
+    parts.push("Enter confirm/select");
+  }
+  if (currentRowSupportsNotes(question, state)) {
+    parts.push(currentNote(flow, state, question) ? "n edit note" : "n add note");
+  }
+  if (canGoBack) parts.push("←/Shift-Tab back");
+  if (canReview) parts.push("→/Tab review");
+  parts.push("Esc cancel");
+  return parts.join(" • ");
+}

package/ui-rich-state.ts

@@ -0,0 +1,142 @@
+// Shared state types and pure helpers for the rich overlay.
+
+import type { Editor } from "@mariozechner/pi-tui";
+import type { QuestionnaireFlow } from "./flow.ts";
+import type {
+  NormalizedQuestion,
+  NormalizedStructuredQuestion,
+  QuestionnaireOutcome,
+} from "./types.ts";
+import { isStructuredQuestion, primaryRecommendationIndex } from "./types.ts";
+import type { OverlayRenderState, SubMode } from "./ui-rich-render.ts";
+
+export interface NoteTargetSingle {
+  mode: "single";
+  questionId: string;
+}
+
+export interface NoteTargetMulti {
+  mode: "multi";
+  questionId: string;
+  optionIndex: number;
+}
+
+export type NoteTarget = NoteTargetSingle | NoteTargetMulti;
+
+export interface OverlayState extends OverlayRenderState {
+  noteTarget?: NoteTarget;
+  cachedLines: string[] | undefined;
+  cachedWidth: number | undefined;
+}
+
+export interface OverlayDeps {
+  flow: QuestionnaireFlow;
+  state: OverlayState;
+  editor: Editor;
+  refresh: () => void;
+  finish: (o: QuestionnaireOutcome) => void;
+}
+
+export type InteractiveRow =
+  | { kind: "option"; optionIndex: number }
+  | { kind: "other" }
+  | { kind: "discuss" };
+
+export function interactiveRows(question: NormalizedStructuredQuestion): InteractiveRow[] {
+  const rows: InteractiveRow[] = question.options.map((_, optionIndex) => ({
+    kind: "option",
+    optionIndex,
+  }));
+  if (question.allowOther) rows.push({ kind: "other" });
+  if (question.allowDiscuss) rows.push({ kind: "discuss" });
+  return rows;
+}
+
+export function rowCount(question: NormalizedQuestion): number {
+  return isStructuredQuestion(question) ? interactiveRows(question).length : 0;
+}
+
+export function hasPreview(question: NormalizedQuestion): boolean {
+  return isStructuredQuestion(question) && question.options.some((option) => !!option.preview);
+}
+
+export function initialSubMode(question: NormalizedQuestion | undefined): SubMode {
+  if (!question) return "select";
+  return question.type === "text" ? "text-input" : "select";
+}
+
+export function resetStateForCurrent(deps: OverlayDeps): void {
+  const question = deps.flow.currentQuestion;
+  deps.state.subMode = deps.flow.currentMode === "reviewing" ? "select" : initialSubMode(question);
+  deps.state.selectedIndex = selectedRowIndex(deps.flow, question);
+  deps.state.noteTarget = undefined;
+  deps.editor.setText("");
+}
+
+export function existingStructuredInputValue(
+  flow: QuestionnaireFlow,
+  questionId: string,
+  kind: "other" | "discuss",
+): string {
+  const answer = flow.getAnswer(questionId);
+  if (kind === "other") return answer?.source === "other" ? answer.value : "";
+  return answer?.source === "discuss" ? (answer.value ?? "") : "";
+}
+
+export function singleNoteFromAnswer(
+  flow: Pick<QuestionnaireFlow, "getAnswer">,
+  questionId: string,
+): string | undefined {
+  const answer = flow.getAnswer(questionId);
+  if (!answer) return undefined;
+  if (answer.source === "option" || answer.source === "yesno") return answer.note;
+  return undefined;
+}
+
+export function multiNoteMapFromAnswer(
+  flow: Pick<QuestionnaireFlow, "getAnswer">,
+  questionId: string,
+): Map<number, string> {
+  const answer = flow.getAnswer(questionId);
+  const map = new Map<number, string>();
+  if (!answer || answer.source !== "options") return map;
+  for (const selection of answer.selections) {
+    if (selection.note) map.set(selection.optionIndex, selection.note);
+  }
+  return map;
+}
+
+export function mergedMultiNoteMap(deps: OverlayDeps, questionId: string): Map<number, string> {
+  const answerMap = multiNoteMapFromAnswer(deps.flow, questionId);
+  const staged = deps.state.stagedMultiNotes.get(questionId);
+  if (!staged) return answerMap;
+  const merged = new Map(answerMap);
+  for (const [optionIndex, note] of staged.entries()) merged.set(optionIndex, note);
+  return merged;
+}
+
+export function selectedRowIndex(
+  flow: Pick<QuestionnaireFlow, "getAnswer">,
+  question: NormalizedQuestion | undefined,
+): number {
+  if (!question || question.type === "text") return 0;
+  const rows = interactiveRows(question);
+  const answer = flow.getAnswer(question.id);
+  if (!answer) {
+    const recommended = primaryRecommendationIndex(question);
+    return recommended ?? 0;
+  }
+  switch (answer.source) {
+    case "option":
+    case "yesno":
+      return answer.optionIndex;
+    case "options":
+      return answer.optionIndexes[0] ?? 0;
+    case "other":
+      return rows.findIndex((row) => row.kind === "other");
+    case "discuss":
+      return rows.findIndex((row) => row.kind === "discuss");
+    case "text":
+      return 0;
+  }
+}

package/ui-rich.ts

@@ -0,0 +1,119 @@
+// Rich questionnaire UI built on `ctx.ui.custom()`. Supports explicit choice,
+// multichoice, notes, other, discuss, preview, and review flows. Returns a
+// QuestionnaireOutcome whose terminal state is owned by the shared flow.
+
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { type Component, Editor, type EditorTheme, type TUI } from "@mariozechner/pi-tui";
+import { QuestionnaireFlow } from "./flow.ts";
+import type { NormalizedQuestion, QuestionnaireOutcome } from "./types.ts";
+import { handleOverlayInput, onEditorSubmit } from "./ui-rich-handlers.ts";
+import { renderOverlay } from "./ui-rich-render.ts";
+import { initialSubMode, type OverlayState, selectedRowIndex } from "./ui-rich-state.ts";
+
+export interface RichCustomOptions {
+  overlay?: boolean;
+}
+
+export interface RichUiHost {
+  custom<T>(
+    factory: (
+      tui: TUI,
+      theme: Theme,
+      // biome-ignore lint/suspicious/noExplicitAny: keybindings parameter type isn't needed here
+      keybindings: any,
+      done: (result: T) => void,
+    ) => Component & { dispose?(): void },
+    options?: RichCustomOptions,
+  ): Promise<T> | undefined;
+}
+
+export interface RunRichOptions {
+  ui: RichUiHost;
+  signal?: AbortSignal;
+}
+
+export async function runRichQuestionnaire(
+  questions: NormalizedQuestion[],
+  opts: RunRichOptions,
+): Promise<QuestionnaireOutcome | "unsupported"> {
+  const flow = new QuestionnaireFlow(questions);
+  // Short-circuit before opening the overlay if we were already aborted.
+  // Otherwise signal.addEventListener("abort", …) would never fire and the
+  // overlay would stay open until the user dismissed it manually.
+  if (opts.signal?.aborted) {
+    flow.abort();
+    return flow.outcome();
+  }
+  const promise = opts.ui.custom<QuestionnaireOutcome>((tui, theme, _kb, done) =>
+    buildOverlay({ tui, theme, flow, signal: opts.signal, done }),
+  );
+  if (!promise) return "unsupported";
+  return promise;
+}
+
+interface BuildOverlayArgs {
+  tui: TUI;
+  theme: Theme;
+  flow: QuestionnaireFlow;
+  signal: AbortSignal | undefined;
+  done: (result: QuestionnaireOutcome) => void;
+}
+
+function buildOverlay(args: BuildOverlayArgs): Component {
+  const { tui, theme, flow, signal, done } = args;
+  const state: OverlayState = {
+    selectedIndex: selectedRowIndex(flow, flow.currentQuestion),
+    subMode: initialSubMode(flow.currentQuestion),
+    stagedSelections: new Map(),
+    stagedSingleNotes: new Map(),
+    stagedMultiNotes: new Map(),
+    noteTarget: undefined,
+    cachedLines: undefined,
+    cachedWidth: undefined,
+  };
+  const editor = new Editor(tui, makeEditorTheme(theme));
+  const refresh = () => {
+    state.cachedLines = undefined;
+    tui.requestRender();
+  };
+  const finish = (outcome: QuestionnaireOutcome) => done(outcome);
+
+  signal?.addEventListener("abort", () => {
+    flow.abort();
+    done(flow.outcome());
+  });
+
+  const deps = { flow, state, editor, refresh, finish };
+  editor.onSubmit = (value) => onEditorSubmit(value, deps);
+
+  return {
+    render: (width) => {
+      // pi's TUI does not call invalidate() on terminal resize, so a width
+      // change has to invalidate the cache here or we'd return stale lines
+      // truncated for the previous width.
+      if (state.cachedWidth !== width) {
+        state.cachedLines = undefined;
+        state.cachedWidth = width;
+      }
+      if (!state.cachedLines) state.cachedLines = renderOverlay(width, theme, flow, state, editor);
+      return state.cachedLines;
+    },
+    invalidate: () => {
+      state.cachedLines = undefined;
+    },
+    handleInput: (data: string) => handleOverlayInput(data, deps),
+  };
+}
+
+function makeEditorTheme(theme: Theme): EditorTheme {
+  return {
+    borderColor: (text) => theme.fg("accent", text),
+    selectList: {
+      selectedPrefix: (text) => theme.fg("accent", text),
+      selectedText: (text) => theme.fg("accent", text),
+      description: (text) => theme.fg("muted", text),
+      scrollInfo: (text) => theme.fg("dim", text),
+      noMatch: (text) => theme.fg("warning", text),
+    },
+  };
+}